agentsmith.conf Manual Page

NAME
SYNTAX
DESCRIPTION
OPTIONS
REGULAR EXPRESSION
EXAMPLE
SEE ALSO
AUTHOR

NAME

agentsmith.conf − configuration file for agentsmith

SYNTAX

<option>=<value>

# Comments

DESCRIPTION

The syntax of the file is very strict. Options must be placed at the very beginning of the line. It is not allowed to have leading spaces in front of the option name. It is also not allowed to have the equal sign surrounded by trailing or leading spaces, e.g.:

foo = bar
foo= bar
foo =bar

are all invalid configuration directives.

Comments start with a # at the beginning of the line with no leading space.

Empty lines are ignored.

Invoking agentsmith with the -t option specified checks the configuration file. It is recommended to run this command every time the configuration file has been altered.

OPTIONS

The following options are recognized:
pidfile

The location of the PID file. That is where agentsmith writes the PID of the daemon when run in daemon mode.

Default: /usr/local/var/agentsmith/agentsmith.pid

syslogfile

The location of the file to be monitored, i.e. the file that will be continuously monitored for new lines which are matched against the regular expression (see regex further down).

Default: /var/log/authlog

action_threshold

The number of occurrences of a host until the action script will be called (see also time_interval). In this context, the term occurrence refers to the matching of the regular expression to a line in logfile.

Default: 3

time_interval

The action script will be called if a host has action_threshold occurrences within this time span (in seconds).

Default: 60

purge_after

If a host has no more occurrences in the log file for purge_after seconds, it will be purged from memory. For each host that is purged, the action script will be called (see also agentsmith(8)).

Default: 3600

action

The file path to the action script. It will be called if action_threshold is reached or exceeded in time_interval seconds, or the offending host is removed from memory due to purging.
The action script is called with the following options

<ip_address> <occurrences> new|remove <origin>

The literal new is passed when a host meets the action threshold and time interval criteria. The literal remove is passed when a host is purged from memory.
origin is either the literal localhost if the host appeared in the local syslog file, or the IP address of the agentsmith instance sending the offending host information.

Default: /bin/true

exclude

File that contains IP addresses to be ignored by agentsmith. The specified file will be re-read upon SIGHUP. See also agentsmith_exclude(5).

Default: none

regex

The regular expression used to identify the IP address of offending hosts. See REGULAR EXPRESSION.

Default: Failed keyboard-interactive for [\w ]+ from ([\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3})

Networking Options
Options in this section are used to configure communication between agentsmith instances. Please note, that SSL has to be set up when network communication is enabled, too (see SSL Configuration below).
server

Enable the server mode of agentsmith. In server mode, agentsmith allows other remote agentsmith instances to trigger the local action script. A value of 1 (‘one’) enables the server. A value of 0 (‘zero’) disables the server.
If the server is enabled, agentsmith requires ssl_ca_cert, ssl_server_cert, and ssl_server_key to be set properly.

Default: 0

maxinconnections

The maximum concurrent connections allowed from remote agentsmith instances. The maximum value is 256.

Default: 5

server_timeout

Time to wait for data from remote agentsmith instances in seconds.

Default: 5

listen

This tells agentsmith on which IP addresses to listen. IPv4/IPv6 Adresses and host names can be used. IPv6 addresses have to be enclosed in square brackets, e.g.

[fe80::e2cb:4eff:feb7:2af5]

At maximum 256 IP addresses can be specified, each separated by space. The listening port can be specified using a colon. If no port is specified, the default port 48621 is used (see also EXAMPLE).
Please note, that if a host name resolves to multiple IP addresses, agentsmith tries to listen on all addresses resolved.

Default: 0.0.0.0:48621

remote_authoritative

If set to 1 (‘one’) agentsmith will not consult the exclusion file specified with exclude when receiving offending host information from remote agentsmith instances. Setting this option to 0 (‘zero’) makes agentsmith check offending hosts received from remote instances whether they are to be ignored.

Default: 0

inform

If set to 1 (‘one’) let inform agentsmith other agentsmith instances about occurrences of offending hosts and thus trigger remote actions scripts. It will only inform instances specified with the inform_agent options.

Enabling this option requires also ssl_ca_file, ssl_client_cert, and ssl_client_key to be set.

Default: 0
inform_agent

A space separated list of IPv4/IPv6 addresses or host names to be informed about offending hosts. The syntax is identical to the listen option above.

Default: none

inform_retry

How many times agentsmith should retry to connect a remote instance if it is not responding.

Default: 30

inform_retry_wait

How many seconds to wait between subsequent attempts to connect remote agentsmith instances. If after inform_retry * inform_retry_wait seconds an instance cannot be connected, the data to be sent to this instance is discarded.

Default: 3

SSL Configuration
In order to communicate with remote instances, agentsmith uses SSL for encryption and authentication. Network communication is not possible without proper SSL certificates.
ssl_ca_file

Path to the file containing the Certificate Authority bundle in PEM format used in Server and Inform Mode.

Default: none

ssl_server_cert

Path to the file containing the server certificate in PEM format.

Default: none

ssl_server_key

Path to the file containing the server private key in PEM format. Please note, that if the key is encrypted agentsmith will prompt for the password.

Default: none

ssl_client_cert

Path to the file containing the client certificate in PEM format.

Default: none

ssl_client_key

Path to the file containing the client private key in PEM format. Please not, that if the key is encrypted agentsmith will prompt for the password.

Default: none

REGULAR EXPRESSION

agentsmith uses Perl compatible regular expressions. The expression used by agentsmith may only contain one catching pattern ´(...)´ which has to catch the IP address of the offending host. If alternations ´(...|...)´ have to be used, they can be written as follows

(?:a|b)

Invoking agentsmith with the -t option set will test the regular expression for correctness as required by agentsmith.

EXAMPLE

This is an example configuration with default values filled in

pidfile=/usr/local/var/agentsmith/agentsmith.pid
syslogfile=/var/log/authlog
action_threshold=3
time_interval=60
purge_after=3600
action=/bin/true
server=1
listen=127.0.0.1:48621 [::1]:48621 host.example.com:48650
regex=Failed keyboard-interactive for [\w ]+ from ([\d]{1,3}\.[\d]{1,3}\.[\d]{1,3}\.[\d]{1,3})

AUTHOR

Rafael Ostertag <rafi@guengel.ch>