specter.conf - configuration file for specter

specter reads its configuration parameters from file, which is mostly /etc/specter.conf. It is divided into blocks. Each block start with a opening curly bracket { and end with closing curly bracket }. Nesting of blocks (opening new block inside another) is forbidden, and there's no need for that in specter configuration. In order to distinguish between blocks, each has a name. You can use any name for a block, except two special names: global (which is used to specify general daemon parameters) and plugins (that list available add-ons). Numbers in range 1-SPECTER_GROUPS_MAX has also special functional meaning (see grouping option description). You cannot define the same block twice, but don't have to define all of them. In most configurations you'll be fine with three or four blocks.

Each block have to start in a new line, then goes its name and opening bracket. All blocks (except for global and plugins) are divided into logical sections, which define a configuration space for every plugin. You start a section with a colon : followed by its name. Within section you can finally specify your configuration. global and plugins blocks are simpler in that manner that they don't have any sections. Block ends with a closing bracket. So, in general, block definition looks like this:

name {
include other_block
:section_one
some_option value
# comment
other_option "long value that needs spaces"
:section_two
# this section have no options, but it's important to specify it
:section_three
option
option value # another comment
   ...
}

As you can see, not every option needs a value, in that case its presence will override a default (see below for specific options description). A hash # is used as a comment, as it will cause a rest of line to be ignored. Of course you can use comments everywhere, not only inside blocks. If you need to set an option to a string containing spaces or tabs, you can enclose it inside double quotation marks, as shown above. And if you ever manage to write a very long config line, you can cut it by \ and continue your statement in the line below.

Since 1.2 version of specter you can use include statement to attach contents of other block to current block. Length of include chain is unlimited, but no recursion is allowed. Each include command is performed exacly once, what mostly does what you wanted.

specter does nearly nothing on its own, it uses plugins for all the dirty work. They are divided into two groups. Input plugins analyze a packet and create hash table concerning received data, in the form like key=value. They don't open files nor they take any input from user. Only output plugins take options. They actually use data from input plugins - save it into logs/databases or execute appropriate commands. So it's vital for you to learn about their configuration, because it's the essence of using specter.

Remember that these should be set inside global options block.

errignore

This options causes specter to continue running despite of errors generated by plugins. That doesn't affect initialization phase, when all errors cause an exit. This option can be useful on heavy-load systems, when you expect some malloc() to fail. It doesn't take any arguments.

logfile

Path to a file you want specter messages to get logged to. Can be set to stdout or stderr.

loglevel

The lower the value, the more information is logged. If you experience any problems, check lowest, debug loglevel=1, so that you can see all messages. The highest loglevel is 8, which cause only fatal errors to be shown. The default is 3.

rmem

Size of the netlink socket receive memory. You should set this to at least the size of the kernel buffer (nlbufsiz parameter of the ipt_ULOG netfilter module). Please note that there is a maximum limit in /proc/sys/net/core/rmem_max which you cannot exceed by increasing the rmem parameter. You may need to raise the system-wide maximum limit before. You can define this variable in kilobytes (suffix it by 'K') or in megabytes (use 'M' suffix).

bufsize

Receive buffer for netlink packets. This should be at least the size rmem option has. Like rmem can be suffixed by 'M' or 'K'.

grouping

That option sets grouping strategy. Every block which name is a number within range 1 to SPECTER_GROUPS_MAX (default 32, use --with-group-max build option to change it), will be treaten as a separate execution block. Setting grouping to netlink will cause interpreting these blocks as netlink groups (as defined with --ulog-nlgroup iptables ULOG target option). When nfmark value is used, groups will be compared to mark field in netfilter packet (see iptables(8) for more details on MARK module). If you find it a bit complicated, check examples section.

nlgroup

Will set netlink group to listen to. Can't be used with grouping set to netlink, as several nlgroups are used in that case.

plugins block structure is very simple. In each line symbolic name and path to plugin binary have to be provided, like in a example:

	BASE	/lib/specter/specter_BASE.so

Name can be anything you want, but it's probably the most informative to set it to plugin's name. You should then use this name as sections names.

Please note that setting paths doesn't mean corresponding plugins will be loaded. You have to use them in blocks in order to force their load. That mean you can list all plugins you have compiled and select which to use by configuring execute blocks adequately.

This plugin executes specified command when packet is received. By proper use of its functions you can dynamically change your firewall configuration, or even set up simple port-knocking utility.

command

That option defines a command that should be executed. Don't rely on your $PATH environment variable, and provide full path to an executable. Few printf-like macros can be used, which are expanded during parsing of every packet:

	%I   interface packet got received from
	%O   interface packet is going to be sent to
	%S   IP address of source host
	%D   IP address of destination host
	%P   IP protocol number (see /etc/protocols)
	%s   TCP/UDP source port
	%d   TCP/UDP destination port
	%i   ICMP type value

If you want to use literal '%' in command, write it double '%%'.

force

When a macros expansion is being done, and any field is empty, executing of a given command is aborted. For example, if you have %i in your command and specter gets a tcp packet, command won't be executed, 'cos given macro cannot be expanded (there's no ICMP type field in a TCP packet). You can override this behavior by setting force option. Instead of bogus data, string "invalid" will be placed. It's up to executed application to work with that.

wait

If this options is set, daemon will wait until application terminates. It's probably not a good idea to actually use it. If you definitely need it, do it with caution, because it can freeze the whole daemon.

environment

If set, child will inherit specter's environment. In other case child be be run in empty environment.

LOGEMU emulates iptables LOG target.

logfile

Path to a file, where plugin should log caught packets. The default is /var/log/specter.logemu.

sync

Define this option if you want to have your logfile written synchronously. This may reduce performance, but makes your log lines appear immediately.

tcp_options

Works the same way as ipt_LOG --log-tcp-options parameter. It enables logging of tcp options.

ip_options

Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG target).

tcp_seq

Enable logging of tcp sequence numbers.

mac_header

Log MAC values of incoming packets.

This plugin insert info into a MySQL database. Amount and type of data is forced by table layout (see specter docs for more info).

db

Name of the mysql database.

table

Name of the table to which specter should log.

host

Name of the mysql database host. If it's localhost, specter first tries to connect to local host by unix socket if possible.

port

Server port number for the tcp/ip connection.

user

Name of the mysql user, if ommited, the current user is assumed.

pass

Password for mysql.

buffsize

Size of a query buffer. You should set it only in a situation when you see "SQL buffer too small. Insert aborted." messages in your logs. Never try to lower this value below default, unless you really know what you're doing.

ssl_enable

If this boolean option is set, MYSQL plugin will use SSL during connection to database.

ssl_key

Pathname to the key file.

ssl_cert

Pathname to the certificate file.

ssl_ca

Pathname to the certificate authority file.

ssl_capath

Pathname to a directory that contains trusted SSL CA certificates in pem format.

ssl_cipher

List of allowable ciphers to use for SSL encryption.

Plugin useful during debugging, simply drops all info gathered about current packet.

logfile

The filename where it should drop the data. The default is /var/log/specter.oprint.

Plugin used to generate libpcap-style packet logfiles. This can be useful for later analyzing the packet log with tools like tcpdump or ethereal.

logfile

The filename where it should log to. The default is /var/log/specter.pcap.

sync

Set this option if you want to have your pcap logfile written synchronously. This may reduce performance, but makes your packets appear immediately in the file on disk.

This plugin insert info into a PostgreSQL database. Amount and type of data is forced by table layout (see specter docs for more info).

db

Name of the postgresql database.

table

Name of the table to which specter should log.

host

Name of the postgresql database host. When undefined, specter try to connect to local database by unix socket.

port

Server port number for the tcp/ip connection, or socket file name extension for Unix-domain connections.

user

Name of the postgresql user, if ommited, the current user is assumed.

pass

Password for postgresql.

buffsize

Size of a query buffer. You should set it only in a situation when you see "SQL buffer too small. Insert aborted." messages in your logs. Never try to lower this value below default, unless you really know what you're doing.

ssl_enable

If this boolean option is set, PGSQL plugin will use SSL during connection to database.

This plugin behaves much like LOGEMU, but logs its input into syslog.

facility

Facility a message should be logged with. See syslog(3) manual page. specter accepts following facilities: daemon, kernel, user, and localx from 0 to 7.

level

Importance of a message. All standard syslog levels are allowed: emerg, alert, crit, err, warning, notice, info, debug.

tcp_options

Works the same way as ipt_LOG --log-tcp-options parameter. It enables logging of tcp options.

ip_options

Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG target).

tcp_seq

Enable logging of tcp sequence numbers.

mac_header

Log MAC values of incoming packets.

Example 1

Example 2

Example 3

Example 4

specter(8), iptables(8).

This manual page was written by Michal Kwiatkowski <ruby@joker.linuxstuff.pl>.