Plugins

reaction has since v2.3.0 a plugin system.

Plugins are binaries named reaction-plugin-$NAME.

Purpose

The plugin system allows developers to extend reaction, without modifying the core code. This page documents how to use the plugins.

Developer documentation can be found on docs.rs.

Performance

Running a new UNIX process for each Action can become costly when we need to run thousands of them.

Each plugin is run by reaction as a separate, long-living process. Plugins can be much more efficient than commands (or worse, scripts), because it skips all the initialization (and cleanup). It reuses its ressources for each action, instead of restarting again and again.

Complexity made easier

Complex actions are better coded in a programming language such as Rust than a shell script. The power of a full programming language can ease the process of writing its own configuration, while permitting more complex setups.

A cluster plugin is in progress, and will permit secure message passing between reaction instances on different servers, which would be virtually impossible to do with shell scripts.

Configuration

Each plugin creates new type(s) of Streams and/or new type(s) of Actions.

Those Streams and Actions don't specify the usual cmd option, but instead a type and options.

See the documentation of each plugin for the real types and options.

{
  // Non-plugin stream
  streams: {
    foo: {
      cmd: ['foo', 'bar'],
    },
  },
  // Plugin stream
  streams: {
    foo: {
      type: 'foo',
      options: {
        bar: 'baz',
      }
    },
  },
}

But before using a plugin, it must be defined!

Plugins are loaded by reaction only if defined in its configuration.

/etc/reaction/plugins.jsonnet

{
  plugins: {
    foo: {
      path: '/usr/bin/reaction-plugin-foo',
    },
  },
}

Security

By default, reaction will ensure that the plugin binary is owned by root.

It will also limit its running privileges with systemd's run0 by default. Disable this option if you don't run systemd or if your run0 is buggy.

See all configuration options of Plugins in the reference.

Official plugins released

ipset

Since v2.3.0.

Permits to manipulate ipsets much faster than with UNIX commands.

reaction's startup on my server is 15 times faster with the ipset plugin than it was when running ipset UNIX commands.

It's also more convenient to use. It easily permits to manage one ipset by Filter and thus avoid IP conflicts between filters.

virtual

Since v2.3.0.

Enables the use of "virtual" Streams and "virtual" Actions.

A virtual action feeds a virtual stream.

It permits to have a second-level stream to perform another actions. This second-level permits for example to ban recidivist IPs for a longer time.

Community plugins

Make a PR to add your plugin here!