Provided by: specter_1.4-2build2_i386 bug

NAME

       specter.conf - configuration file for specter

DESCRIPTION

       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.

GENERAL OPTIONS

       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

       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.

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.

       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.

specter_LOGEMU OPTIONS

       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.

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).

       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.

specter_OPRINT OPTIONS

       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.

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.

       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.

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).

       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.

specter_SYSLOG OPTIONS

       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.

EXAMPLES

   Example 1
       Say,  you  just want to log non-related tcp and udp packets in separate
       files. You must first set up your netfilter:

                   # 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

       And now use this specter configuration:

                   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
                   }

   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:

                   # iptables -A INPUT -p tcp --dport 80 -j ULOG --ulog-nlgroup 5
                   # iptables -A OUTPUT -p tcp --sport 80 -j ULOG --ulog-nlgroup 5

       Then  use  this  configuration,  so all http traffic will be saved in a
       /var/log/specter.http.  But you expect some attacks and want packets to
       appear immediately in log, so you use sync option as well.

                   plugins {
                        BASE    /lib/specter/specter_BASE.so
                        PCAP    /lib/specter/specter_PCAP.so
                   }

                   5 {
                        :BASE
                        :PCAP
                        file /var/log/specter.http
                        sync
                   }

   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:

                   # 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

       This config will do the rest:

                   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
                   }

   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:

                   # iptables -A INPUT -p tcp -f -j ULOG --ulog-nlgroup 1

       Now  use this config to dynamically change your netfilter configuration
       with the use of EXEC plugin:

                   plugins {
                        EXEC /lib/specter/specter_EXEC.so
                   }

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

SEE ALSO

       specter(8), iptables(8).

AUTHOR

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