'\" t
.\" 
.TH SPECTER.CONF 5 "April 12, 2005" "Linux Netfilter"


.SH NAME
specter.conf \- configuration file for specter


.SH DESCRIPTION
specter reads its configuration parameters from file, which is mostly
.IR /etc/specter.conf .
It is divided into blocks. Each block start with a opening curly bracket
.IR {
and end with closing curly bracket
.IR } .
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
.IR name .
You can use any name for a block, except two special names:
.IR global
(which is used to specify general daemon parameters) and
.IR plugins
(that list available add-ons).
Numbers in range \fB1\fP-\fBSPECTER_GROUPS_MAX\fP has also
special functional meaning (see
.IR 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.
.LP
Each block have to start in a new line, then goes its name and opening
bracket. All blocks (except for
.IR global
and
.IR plugins )
are divided into logical sections, which define a configuration space
for every plugin. You start a section with a colon
.IR :
followed by its name. Within section you can finally specify your
configuration.
.IR global
and
.IR 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:
.IP
.nf
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
   ...
}
.fi
.LP
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
.IR #
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\fB \\\fP
and continue your statement in the line below.
.LP
Since 1.2 version of specter you can use
.IR include
statement
to attach contents of other block to current block. Length of
.IR include
chain is unlimited, but no recursion is allowed.
Each
.IR include
command is performed exacly once, what
mostly does what you wanted.
.LP
specter does nearly nothing on its own, it uses
.IR plugins
for all the dirty work. They are divided into two groups.
.IR 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
.IR 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.
.LP


.SH "GENERAL OPTIONS"
Remember that these should be set inside
.IR global
options block.
.TP
.BI 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.
.TP
.BI logfile
Path to a file you want specter messages to get logged to. Can be set to
.IR stdout
or
.IR stderr .
.TP
.BI 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.
.TP
.BI 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
.IR /proc/sys/net/core/rmem_max
which you cannot exceed by increasing the
.IR 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).
.TP
.BI bufsize
Receive buffer for netlink packets. This should be at least the size
.IR rmem
option has. Like
.IR rmem
can be suffixed by 'M' or 'K'.
.TP
.BI grouping
That option sets grouping strategy. Every block which name is a number
within range
.IR 1
to
.IR SPECTER_GROUPS_MAX
(default 32, use
.IR --with-group-max
build option to change it), will be treaten as a separate execution
block. Setting
.IR grouping
to
.IR netlink
will cause interpreting these blocks as netlink groups (as defined with
.IR --ulog-nlgroup
iptables ULOG target option). When
.IR 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.
.TP
.BI nlgroup
Will set netlink group to listen to. Can't be used with
.IR grouping
set to
.IR netlink ,
as several nlgroups are used in that case.


.SH "PLUGINS BLOCK"
.IR plugins
block structure is very simple. In each line symbolic name and path to
plugin binary have to be provided, like in a example:
.IP
.nf
	BASE	/lib/specter/specter_BASE.so
.fi
.LP
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.
.LP
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.


.SH "specter_EXEC OPTIONS"
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.
.TP
.BI 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:
.IP
.nf
	%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
.fi
.IP
If you want to use literal '%' in command, write it double '%%'.
.TP
.BI 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
.IR %i
in your
.IR 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
.IR force
option. Instead of bogus data, string "invalid" will be placed. It's up
to executed application to work with that.
.TP
.BI 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.
.TP
.BI environment
If set, child will inherit specter's environment. In other case child be be
run in empty environment.


.SH "specter_LOGEMU OPTIONS"
LOGEMU emulates iptables LOG target.
.TP
.BI logfile
Path to a file, where plugin should log caught packets. The default is
.IR /var/log/specter.logemu .
.TP
.BI sync
Define this option if you want to have your logfile written
synchronously. This may reduce performance, but makes your log lines
appear immediately.
.TP
.BI tcp_options
Works the same way as ipt_LOG --log-tcp-options parameter. It enables
logging of tcp options.
.TP
.BI ip_options
Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG
target).
.TP
.BI tcp_seq
Enable logging of tcp sequence numbers.
.TP
.BI mac_header
Log MAC values of incoming packets.


.SH "specter_MYSQL OPTIONS"
This plugin insert info into a MySQL database. Amount and type of data
is forced by table layout (see specter docs for more info).
.TP
.BI db
Name of the mysql database.
.TP
.BI table
Name of the table to which specter should log.
.TP
.BI host
Name of the mysql database host. If it's
.IR localhost ,
specter first tries to connect to local host by unix socket if possible.
.TP
.BI port
Server port number for the tcp/ip connection.
.TP
.BI user
Name of the mysql user, if ommited, the current user is assumed.
.TP
.BI pass
Password for mysql.
.TP
.BI 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.
.TP
.BI ssl_enable
If this boolean option is set, MYSQL plugin will use SSL during connection
to database.
.TP
.BI ssl_key
Pathname to the key file.
.TP
.BI ssl_cert
Pathname to the certificate file.
.TP
.BI ssl_ca
Pathname to the certificate authority file.
.TP
.BI ssl_capath
Pathname to a directory that contains trusted SSL CA certificates in pem format.
.TP
.BI ssl_cipher
List of allowable ciphers to use for SSL encryption.


.SH "specter_OPRINT OPTIONS"
Plugin useful during debugging, simply drops all info gathered about
current packet.
.TP
.BI logfile
The filename where it should drop the data. The default is
.IR /var/log/specter.oprint .


.SH "specter_PCAP OPTIONS"
Plugin used to generate libpcap-style packet logfiles. This can be
useful for later analyzing the packet log with tools like tcpdump or
ethereal.
.TP
.BI logfile
The filename where it should log to.  The default is
.IR /var/log/specter.pcap .
.TP
.BI 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.


.SH "specter_PGSQL OPTIONS"
This plugin insert info into a PostgreSQL database. Amount and type of
data is forced by table layout (see specter docs for more info).
.TP
.BI db
Name of the postgresql database.
.TP
.BI table
Name of the table to which specter should log.
.TP
.BI host
Name of the postgresql database host. When undefined, specter try to
connect to local database by unix socket.
.TP
.BI port
Server port number for the tcp/ip connection, or socket file name
extension for Unix-domain connections.
.TP
.BI user
Name of the postgresql user, if ommited, the current user is assumed.
.TP
.BI pass
Password for postgresql.
.TP
.BI 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.
.TP
.BI ssl_enable
If this boolean option is set, PGSQL plugin will use SSL during connection
to database.


.SH "specter_SYSLOG OPTIONS"
This plugin behaves much like LOGEMU, but logs its input into syslog.
.TP
.BI facility
Facility a message should be logged with. See syslog(3) manual page.
specter accepts following facilities:
.IR daemon ,
.IR kernel ,
.IR user,
and 
.IR local x
from 0 to 7.
.TP
.BI level
Importance of a message. All standard syslog levels are allowed:
.IR emerg ,
.IR alert ,
.IR crit ,
.IR err ,
.IR warning ,
.IR notice ,
.IR info ,
.IR debug .
.TP
.BI tcp_options
Works the same way as ipt_LOG --log-tcp-options parameter. It enables
logging of tcp options.
.TP
.BI ip_options
Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG
target).
.TP
.BI tcp_seq
Enable logging of tcp sequence numbers.
.TP
.BI mac_header
Log MAC values of incoming packets.


.SH EXAMPLES
.SS Example 1
Say, you just want to log non-related tcp and udp packets in separate
files. You must first set up your netfilter:
.IP
.nf
	# iptables -A INPUT -p tcp -m state --state INVALID -j ULOG --ulog-nlgroup 1
	# iptables -A INPUT -p udp -m state --state INVALID -j ULOG --ulog-nlgroup 2
.fi
.PP
And now use this specter configuration:
.IP
.nf
	plugins {
		BASE      /lib/specter/specter_BASE.so
		LOCAL     /lib/specter/specter_LOCAL.so
		LOGEMU    /lib/specter/specter_LOGEMU.so
	}

	1 {
		:BASE
		:LOCAL
		:LOGEMU
		logfile /var/log/specter.tcp
	}

	2 {
		:BASE
		:LOCAL
		:LOGEMU
		logfile /var/log/specter.udp
	}
.fi
.SS Example 2
Maybe you want to analyze every packet that passes your HTTP server
with a application that uses pcap-style files? Prepare you firewall:
.IP
.nf
	# iptables -A INPUT -p tcp --dport 80 -j ULOG --ulog-nlgroup 5
	# iptables -A OUTPUT -p tcp --sport 80 -j ULOG --ulog-nlgroup 5
.fi
.PP
Then use this configuration, so all http traffic will be saved in a
.IR /var/log/specter.http .
But you expect some attacks and want packets to appear immediately in
log, so you use
.IR sync
option as well.
.IP
.nf
	plugins {
		BASE    /lib/specter/specter_BASE.so
		PCAP    /lib/specter/specter_PCAP.so
	}

	5 {
		:BASE
		:PCAP
		file /var/log/specter.http
		sync
	}
.fi
.SS Example 3
You're very paranoid and want to save all IPs that tried to ping you
in a database, yes? Logging tcp requests are also in you concern, right?
Moreover, you don't want to occupy more than one netlink group, so you
decide to use mark module to divide packets into groups. Try these
iptables rules:
.IP
.nf
	# iptables -t mangle -A INPUT -p icmp --icmp-type echo-request -j MARK --set-mark 13
	# iptables -t mangle -A INPUT -p tcp -m state --state NEW -j MARK --set-mark 15
	# iptables -A INPUT -m mark --mark 13 -j ULOG --ulog-nlgroup 1
	# iptables -A INPUT -m mark --mark 15 -j ULOG --ulog-nlgroup 1
.fi
.PP
This config will do the rest:
.IP
.nf
	global {
		grouping nfmark
		nlgroup 1
	}

	plugins {
		BASE     /lib/specter/specter_BASE.so
		MYSQL    /lib/specter/specter_MYSQL.so
	}

	13 {
		:BASE
		:MYSQL
		db mydb
		host localhost
		user username
		pass password
		table pings
	}

	15 {
		:BASE
		:MYSQL
		db mydb
		host localhost
		user username
		pass password
		table tcp_requests
	}
.fi
.SS Example 4
You don't like fragmented packets? You can automaticaly block anyone
who ever send you fragmented tcp packet. Use this single iptables rule:
.IP
.nf
	# iptables -A INPUT -p tcp -f -j ULOG --ulog-nlgroup 1
.fi
.PP
Now use this config to dynamically change your netfilter configuration
with the use of EXEC plugin:
.IP
.nf
	plugins {
		EXEC	/lib/specter/specter_EXEC.so
	}

	1 {
		:EXEC
		command "/usr/sbin/iptables -A INPUT -p tcp -s %S --sport %s -j DROP"
	}
.fi


.SH "SEE ALSO"
specter(8), iptables(8).


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