Action

Actions are commands that a Filter runs when it is Triggered.

Actions are the reaction!

cmd

An array of strings. The first string is the command, and the subsequent strings are the arguments.

See FAQ "Why start, stop, stream and action commands are arrays" for an explanation.

{
  action1: {
    cmd: [ '/root/myscript.sh' ],
  },
}

action1:
  cmd: [ '/root/myscript.sh' ]

Patterns specified in the Action's Filter can be referenced in the command by providing their name enclosed in < and >. It will be substitued by the actual Match value.

{
  action2: {
    cmd: [ 'iptables', '-I', ..., '<ip>' ],
  },
}

action2:
  cmd: [ 'iptables', '-I', ..., '<ip>' ]

type

Available since v2.3.0.

Defaults to "cmd", in which case a cmd must be provided.

{
  action3: {
    type: "cmd",
    cmd: [...],
  }
}

action3:
  type: cmd
  cmd: [...]

Otherwise, defines the Plugin that will be used for that Action.

options

Available since v2.3.0.

Used in conjunction with type.

The value of options depends on the Plugin selected, see their documentation.

{
  action3: {
    type: "plugin3",
    options: {
      option1: "value1",
      ...
    }
  }
}

action3:
  type: plugin3
  options:
    option1: value1
    ...

after

By default, actions are executed as soon as the Filter is Triggered.

An action can be delayed with after.

Format is defined as follows: <number> <unit>

• whitespace between the integer and unit is optional
• number must be a positive integer (>= 0, no floating point)
• unit can be one of:
  • ms / millis / millisecond / milliseconds
  • s / sec / secs / second / seconds
  • m / min / mins / minute / minutes
  • h / hour / hours
  • d / day / days

{
  action1: {
    cmd: [ ... ],
    // no after, action is run immediately
  },
  action2: {
    cmd: [ ... ],
    after: '10 secs',
  },
  action3: {
    cmd: [ ... ],
    after: '30m',
  },
  action4: {
    cmd: [ ... ],
    after: '1day',
  },
}

action1:
  cmd: [ ... ]
  # no after, action is run immediately
action2:
  cmd: [ ... ]
  after: '10 secs'
action3:
  cmd: [ ... ]
  after: '30m'
action4:
  cmd: [ ... ]
  after: '1day'

A delayed action that is scheduled and that will run later is called a pending action.

onexit

Whether to run this action when pending (scheduled by a Filter for later) on exit.

Defaults to false.

For firewalls, it's much more performant to just flush the chain or IP set than to removing each IP one by one.

Only makes sense when after is set.

{
  action1: {
    cmd: [ ... ],
  },
  action2: {
    cmd: [ ... ],
    after: '2h',
    onexit: true,
  },
}

action1:
  cmd: ...
action2:
  cmd: ...
  after: '2h'
  onexit: true

oneshot

Available since v2.1.0.

Whether this action will rerun when reaction restarts.

Useful for alerting actions, such as sending a mail.

When reaction restarts, you surely want an IP to be banned again, but not to send the associated alert again.

Defaults to false.

{
  ban: {
    cmd: [ ... ],
  },
  unban: {
    cmd: [ ... ],
    after: '12h',
  },
  mail: {
    cmd: [ ... ],
    oneshot: true,
  },
}

ban:
  cmd: ...
unban:
  cmd: ...
  after: '12h'
mail:
  cmd: ...
  oneshot: true

ipv4only and ipv6only

Available since v2.2.0.

Only makes sense when the underlying Filter's regex has a Pattern of type ip.

• ipv4only: only execute this action when the type: ip Pattern matches an IPv4.
• ipv6only: only execute this action when the type: ip Pattern matches an IPv6.

Both options are mutually exclusive.

{
  ban: {
    cmd: [ 'iptables', ... ],
    ipv4only: true,
  },
  ban6: {
    cmd: [ 'ip6tables', ... ],
    ipv6only: true,
  },
}

ban:
  cmd: [ 'iptables', ... ]
  ipv4only: true
ban6:
  cmd: [ 'ip6tables', ... ]
  ipv6only: true