Configuration reference

reaction can be configured using the following formats:

• JSON (.json)
• JSONnet (.jsonnet)
• YAML (.yaml, .yml)

See FAQ "What is JSONnet and why should I use it over YAML" for a rationale.

It can be configured with either:

• one configuration file,
• or a directory containing multiple configuration files:
  • files are loaded and merged in alphanumeric order,
  • files beginning with . or _ are ignored,
  • files not ending with a supported extension are ignored,
  • no recursion in subdirectories.

Here's a graph of reaction's model. Each concept is explained in the reference, along with all its configuration options.

Table of Contents

All possible keys of the configuration in their context:

{
  concurrency: ...,
  state_directory: ...,
  state_rotation_interval: ...,

  start: ...,
  stop: ...,

  patterns: {
    [name]: {
      type: ...,
      regex: ...,
      ignore: ...,
      ignoreregex: ...,
      ignorecidr: ...,
      ipv4mask: ...,
      ipv6mask: ...,
    },
  },

  plugins: {
    [name]: {
      path: ...,
      check_root: ...,
      systemd: ...,
      systemd_options: {
        ...
      }
    }
  }

  streams: {
    [name]: {
      cmd: ...,
      type: ...,
      options: ...,
      filters: {
        [name]: {
          regex: ...,
          type: ...,
          options: {
            lang: ...,
            fields: ...,
          }
          retry: ...,
          retryperiod: ...,
          duplicates: ...,
          actions: {
            [name]: {
              cmd: ...,
              type: ...,
              options: ...,
              after: ...,
              onexit: ...,
              oneshot: ...,
              ipv4only: ...,
              ipv6only: ...,
            },
          },
        },
      },
    },
  },
}

concurrency: ...
state_directory: ...
state_rotation_interval: ...

start: ...
stop: ...

plugins:
  [name]:
    path: ...
    check_root: ...
    systemd: ...
    systemd_options:
      ...

patterns:
  [name]:
    type: ...
    regex: ...
    ignore: ...
    ignoreregex: ...
    ignorecidr: ...
    ipv4mask: ...
    ipv6mask: ...

streams:
  [name]:
    cmd: ...
    type: ...
    options: ...
    filters:
      [name]:
        regex: ...
        type: ...,
        options:
          lang: ...
          fields: ...
        retry: ...
        retryperiod: ...
        duplicates: ...
        actions:
          [name]:
            cmd: ...
            type: ...
            options: ...
            after: ...
            onexit: ...
            oneshot: ...
            ipv4only: ...
            ipv6only: ...

Glossary

Match

A Match is one concrete instance of a Pattern found in the logs.

For example, if we have a Pattern user with regex [a-z]+, and a Filter with regex ^hello <user>$, the line hello charlie will result in the Match charlie.

A Match can be reused in Actions. So an Action with the command ['echo', '<user>'] would run echo charlie for the previous match.

Trigger

A Trigger is a Match that will make the related Filter execute its Actions.

How much Matches must happen before the Filter is triggered depends on its retry and retryperiod options.

How Persistance works

TL;DR: when an after Action is set in a Filter, such Filter acts as a jail, which is persisted after reboot.

When a filter is triggered, there are 2 possibilities:

• If none of its Actions have an after directive set:

  • no action will be replayed when reaction restarts.

• If at least one Action has an after directive set:

  If reaction stops while after Actions are pending,

  and reaction starts again when those actions would still be pending, reaction:

  • executes the past actions (actions without after or with then+after <= now),
  • plans the execution of future actions (actions with then+after > now).