  ULOGD 2.x - the Netfilter Userspace Logging Daemon
  Harald Welte <laforge@netfilter.org>, Eric Leblond
  <eric@inl.fr>
  Revision 2009/04/18

  This is the documentation for ulogd-2.x, the second generation Netfil-
  ter Userspace logging daemon. ulogd makes use of the Linux >= 2.6.14
  nfnetlink_log and nfnetlink_conntrack subsystems, but also provides
  backwards compatibility for Linux >= 2.4.0 ipt_ULOG.
  ______________________________________________________________________

  Table of Contents


  1. DESIGN
     1.1 CONCEPT
     1.2 DETAILS

  2. INSTALLATION
     2.1 Linux kernel
     2.2 Userspace libraries
     2.3 ulogd
        2.3.1 Recompiling the source

  3. Configuration
     3.1 iptables NFLOG target
        3.1.1 Quick Setup
        3.1.2 NFLOG target reference
     3.2 iptables ULOG target
        3.2.1 Quick Setup
        3.2.2 ULOG target reference
        3.2.3 ipt_ULOG module parameters

  4. QUESTIONS / COMMENTS


  ______________________________________________________________________

  11..  DDEESSIIGGNN

  11..11..  CCOONNCCEEPPTT

  ulogd-2.x wants to provide a flexible, almost universal logging daemon
  for netfilter logging. This encompasses both packet-based logging
  (logging of policy violations) and flow-based logging, e.g. for
  accounting purpose.

  ulogd consists of a small core and a number of plugins. All the real
  power lies in the plugins, and in the user who configures the
  interactions between those plugins.


     IInnppuutt PPlluuggiinnss
        Input plugins acts data source. They get data from somewhere
        outside of ulogd, and convert it into a list of ulogd keys.

     FFiilltteerr PPlluuggiinnss
        Filter plugins interpret and/or filter data that was received
        from the Input Plugin. A good example is parsing a raw packet
        into IPv4 / TCP / ... header information.

     OOuuttppuutt PPlluuggiinnss
        Output plugins describe how and where to put the information
        gained by the Input Plugin and processed by one or more Filter
        Plugins.  The easiest way is to build a line per packet and
        fprint it to a file.  Some people might want to log into a SQL
        database or want an output conforming to the IETF IPFIX
        language.

  By means of the configuration file, the administrator can build any
  number of Plugin Stacks. A plugin stack is a series of plugins,
  starting with an Input plugin, none, one or multiple filter plugins,
  and one output plugin on top.

  11..22..  DDEETTAAIILLSS

  The major clue is providing a framework which is as flexible as
  possible.  Nobody knows what strange network protocols are out there
  :) But at the same time, logging of a packet filter is often very
  performance critical.  Like all ulogd releases since 0.3.x, the
  ulogd-2.x core doesn't do any dynamic allocations at runtime. Yes,
  obviously, at startup time the config file is parsed, and allocations
  are made. But after that, everything is pre-allocated. As an
  additional improvement over ulogd-1.x, there are also no hashtable
  lookups for key resolval. All input/output keys of plugins within
  every stack are resolved at config file parsing time, and directly
  interconnected by pointers.

  22..  IINNSSTTAALLLLAATTIIOONN

  22..11..  LLiinnuuxx kkeerrnneell

  To use the NFCT or NFLOG input plugin, you will need a 2.6.14 or later
  kernel.  For old-style ULOG logging, you need a kernel >= 2.4.18.

  22..22..  UUsseerrssppaaccee lliibbrraarriieess

  If you plan to use NFCT and NFLOG input plugin, you will need to
  compile libnfnetlink, libnetfilter_conntrack and libnetfilter_log
  libraries which can be downloaded from
  <http://ftp.netfilter.org/pub/>.  A simple './configure; make; make
  install' will be enough to have library installed on your system.

  22..33..  uullooggdd

  22..33..11..  RReeccoommppiilliinngg tthhee ssoouurrccee

  Download the ulogd package from  <http://ftp.netfilter.org/pub/ulogd/>
  and untar it.

  If you want to build ulogd with MySQL support, type './configure
  --with-mysql'. You may also have to specify the path of the mysql
  libraries using '--with-mysql=path'. To build ulogd without MySQL
  support, just use './configure'.

  To compile and install the program, call 'make install'.

  33..  CCoonnffiigguurraattiioonn

  33..11..  iippttaabblleess NNFFLLOOGG ttaarrggeett

  33..11..11..  QQuuiicckk SSeettuupp

  Just add rules using the NFLOG target to your firewalling chain. A
  very basic example:


       iptables -A FORWARD -j NFLOG --nflog-group 32 --nflog-prefix foo



  To increase logging performance, try to use the


       --nflog-qthreshold N



  option (where 1 < N <= 50). The number you specify is the amount of
  packets batched together in one multipart netlink message. If you set
  this to 20, the kernel schedules ulogd only once every 20 packets. All
  20 packets are then processed by ulogd. This reduces the number of
  context switches between kernel and userspace.

  Of course you can combine the NFLOG target with the different
  netfilter match modules. For a more detailed description, have a look
  at the netfilter HOWTO's, available on the netfilter homepage.

  33..11..22..  NNFFLLOOGG ttaarrggeett rreeffeerreennccee


     ----nnfflloogg--ggrroouupp NN
        The number of the netlink multicast group to which NFLOG'ed
        packets are sent.  You will have to use the same group number in
        the NFLOG target and ulogd in order to make logging work.

     ----nnfflloogg--rraannggee NN
        Copyrange. This works like the 'snaplen' parameter of tcpdump.
        You can specify a number of bytes up to which the packet is
        copied. If you say '40', you will receive the first fourty bytes
        of every packet. Leave it to 0 to dump the whole packet.

     ----nnfflloogg--tthhrreesshhoolldd NN
        Queue threshold. If a packet is matched by the iptables rule,
        and already N packets are in the queue, the queue is flushed to
        userspace. You can use this to implement a policy like: Use a
        big queue in order to gain high performance, but still have
        certain packets logged immediately to userspace.

     ----nnfflloogg--pprreeffiixx SSTTRRIINNGG
        A string that is associated with every packet logged by this
        rule. You can use this option to later tell from which rule the
        packet was logged.

  33..22..  iippttaabblleess UULLOOGG ttaarrggeett

  33..22..11..  QQuuiicckk SSeettuupp

  Just add rules using the ULOG target to your firewalling chain. A very
  basic example:


       iptables -A FORWARD -j ULOG --ulog-nlgroup 32 --ulog-prefix foo



  To increase logging performance, try to use the


       --ulog-qthreshold N



  option (where 1 < N <= 50). The number you specify is the amount of
  packets batched together in one multipart netlink message. If you set
  this to 20, the kernel schedules ulogd only once every 20 packets. All
  20 packets are then processed by ulogd. This reduces the number of
  context switches between kernel and userspace.

  Of course you can combine the ULOG target with the different netfilter
  match modules. For a more detailed description, have a look at the
  netfilter HOWTO's, available on the netfilter homepage.

  33..22..22..  UULLOOGG ttaarrggeett rreeffeerreennccee


     ----uulloogg--nnllggrroouupp NN
        The number of the netlink multicast group to which ULOG'ed
        packets are sent.  You will have to use the same group number in
        the ULOG target and ulogd in order to make logging work.

     ----uulloogg--ccpprraannggee NN
        Copyrange. This works like the 'snaplen' parameter of tcpdump.
        You can specify a number of bytes up to which the packet is
        copied. If you say '40', you will receive the first fourty bytes
        of every packet. Leave it to 0

     ----uulloogg--qqtthhrreesshhoolldd NN
        Queue threshold. If a packet is matched by the iptables rule,
        and already N packets are in the queue, the queue is flushed to
        userspace. You can use this to implement a policy like: Use a
        big queue in order to gain high performance, but still have
        certain packets logged immediately to userspace.

     ----uulloogg--pprreeffiixx SSTTRRIINNGG
        A string that is associated with every packet logged by this
        rule. You can use this option to later tell from which rule the
        packet was logged.

  33..22..33..  iipptt__UULLOOGG mmoodduullee ppaarraammeetteerrss

  The ipt_ULOG kernel module has a couple of module loadtime parameters
  which can (and should) be tuned to accomodate the needs of the
  application:

     nnllbbuuffssiizz NN
        Netlink buffer size. A buffer of the specified size N is
        allocated for every netlink group that is used. Please note that
        due to restrictions of the kernel memory allocator, we cannot
        have a buffer size > 128kBytes. Larger buffer sizes increase the
        performance, since less kernel/userspace context switches are
        needed for the same amount of packets. The backside of this
        performance gain is a potentially larger delay. The default
        value is 4096 bytes, which is quite small.G_NOTICE, LOG_INFO,
        LOG_DEBUG)

  44..  QQUUEESSTTIIOONNSS // CCOOMMMMEENNTTSS

  All comments / questions / ... are appreciated.

  Just drop a note to netfilter-devel@vger.kernel.org.


  The preferred method for reporting bugs is the netfilter bugzilla
  system, available at  <http://bugzilla.netfilter.org/>.



