(LINUXDOC
AOPTS CDATA null
(ARTICLE
(TITLEPAG
(TITLE
-ULOGD 2.x - the Netfilter Userspace Logging Daemon
)TITLE
(AUTHOR
(NAME
-Harald Welte \|[lt    ]\|laforge@netfilter.org\|[gt    ]\|, Eric Leblond \|[lt    ]\|eric@inl.fr\|[gt    ]\|
)NAME
)AUTHOR
(DATE
-Revision 2009/04/18
)DATE
(ABSTRACT
-This is the documentation for 
(TT
-ulogd-2.x
)TT
-, the second generation\nNetfilter Userspace logging daemon.  ulogd makes use of the Linux \|[gt    ]\|= 2.6.14\nnfnetlink\|[lowbar]\|log and nfnetlink\|[lowbar]\|conntrack subsystems, but also provides backwards compatibility for Linux\n\|[gt    ]\|= 2.4.0 ipt\|[lowbar]\|ULOG.
)ABSTRACT
)TITLEPAG
(TOC
)TOC
(SECT
(HEADING
-DESIGN
)HEADING
(SECT1
(HEADING
-CONCEPT
)HEADING
(P
-ulogd-2.x wants to provide a flexible, almost universal logging daemon for \nnetfilter logging.  This encompasses both packet-based logging (logging of\npolicy violations) and flow-based logging, e.g. for accounting purpose.
)P
(P
-ulogd consists of a small core and a number of plugins.  All the real power\nlies in the plugins, and in the user who configures the interactions between those\nplugins.
)P
(P
(DESCRIP
(TAG
-Input Plugins
)TAG
(P
-Input plugins acts data source.  They get data from somewhere outside of ulogd,\nand convert it into a list of ulogd keys.
)P
(TAG
-Filter Plugins
)TAG
(P
-Filter plugins interpret and/or filter data that was received from the Input\nPlugin.  A good example is parsing a raw packet into IPv4 / TCP / ... header\ninformation.
)P
(TAG
-Output Plugins
)TAG
(P
-Output plugins describe how and where to put the information gained by the\nInput Plugin and processed by one or more Filter Plugins.\nThe easiest way is to build a line per packet and fprint it to a file. \nSome people might want to log into a SQL database or want an output \nconforming to the IETF IPFIX language.
)P
)DESCRIP
)P
(P
-By means of the configuration file, the administrator can build any number\nof Plugin Stacks.  A plugin stack is a series of plugins, starting with an Input\nplugin, none, one or multiple filter plugins, and one output plugin on top.
)P
)SECT1
(SECT1
(HEADING
-DETAILS
)HEADING
(P
-The major clue is providing a framework which is as flexible as possible. \nNobody knows what strange network protocols are out there :) But at the same\ntime, logging of a packet filter is often very performance critical.\nLike all ulogd releases since 0.3.x, the ulogd-2.x core doesn't do any\ndynamic allocations at runtime.  Yes, obviously, at startup time the config\nfile is parsed, and allocations are made.  But after that, everything is\npre-allocated.  As an additional improvement over ulogd-1.x, there are also no\nhashtable lookups for key resolval.  All input/output keys of plugins within\nevery stack are resolved at config file parsing time, and directly\ninterconnected  by pointers.
)P
(P
)P
)SECT1
)SECT
(SECT
(HEADING
-INSTALLATION
)HEADING
(P
)P
(SECT1
(HEADING
-Linux kernel
)HEADING
(P
-To use the NFCT or NFLOG input plugin, you will need a 2.6.14 or later kernel.\nFor old-style ULOG logging, you need a kernel \|[gt    ]\|= 2.4.18.
)P
(P
)P
)SECT1
(SECT1
(HEADING
-Userspace libraries
)HEADING
(P
-If you plan to use NFCT and NFLOG input plugin, you will need to compile\nlibnfnetlink, libnetfilter\|[lowbar]\|conntrack and libnetfilter\|[lowbar]\|log libraries which\ncan be downloaded from 
AURL CDATA http://ftp.netfilter.org/pub/
ANAME CDATA \|urlnam\|
(URL
)URL
-.\nA simple './configure; make; make install' will be enough to have library\ninstalled on your system.
)P
(P
)P
(P
)P
)SECT1
(SECT1
(HEADING
-ulogd
)HEADING
(SECT2
(HEADING
-Recompiling the source
)HEADING
(P
-Download the ulogd package from 
AURL CDATA http://ftp.netfilter.org/pub/ulogd/
ANAME CDATA \|urlnam\|
(URL
)URL
- and\nuntar it. 
)P
(P
-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'.
)P
(P
-To compile and install the program, call 'make install'.
)P
(P
)P
)SECT2
)SECT1
)SECT
(SECT
(HEADING
-Configuration
)HEADING
(SECT1
(HEADING
-iptables NFLOG target
)HEADING
(SECT2
(HEADING
-Quick Setup
)HEADING
(P
-Just add rules using the NFLOG target to your firewalling chain. A very basic\nexample:\n
(TSCREEN
(VERB
-iptables -A FORWARD -j NFLOG --nflog-group 32 --nflog-prefix foo 
)VERB
)TSCREEN
)P
(P
-To increase logging performance, try to use the\n
(TSCREEN
(VERB
---nflog-qthreshold N
)VERB
)TSCREEN
-\noption (where 1 \|[lt    ]\| N \|[lt    ]\|= 50). The number you specify is the amount of packets\nbatched together in one multipart netlink message. If you set this to 20, the\nkernel schedules ulogd only once every 20 packets. All 20 packets are then \nprocessed by ulogd. This reduces the number of context switches between kernel\nand userspace.
)P
(P
-Of course you can combine the NFLOG target with the different netfilter match\nmodules.  For a more detailed description, have a look at the netfilter\nHOWTO's, available on the netfilter homepage.
)P
)SECT2
(SECT2
(HEADING
-NFLOG target reference
)HEADING
(P
(DESCRIP
(TAG
---nflog-group N
)TAG
(P
-The number of the netlink multicast group to which NFLOG'ed packets are sent.\nYou will have to use the same group number in the NFLOG target and ulogd in\norder to make logging work.
)P
(TAG
---nflog-range N
)TAG
(P
-Copyrange.  This works like the 'snaplen' parameter of tcpdump.  You can specify\na number of bytes up to which the packet is copied.  If you say '40', you will\nreceive the first fourty bytes of every packet. Leave it to 
(TT
-0
)TT
- to dump\nthe whole packet.
)P
(TAG
---nflog-threshold N
)TAG
(P
-Queue threshold.  If a packet is matched by the iptables rule, and already N\npackets are in the queue, the queue is flushed to userspace.  You can use this\nto implement a policy like: Use a big queue in order to gain high performance,\nbut still have certain packets logged immediately to userspace.
)P
(TAG
---nflog-prefix STRING
)TAG
(P
-A string that is associated with every packet logged by this rule.  You can use\nthis option to later tell from which rule the packet was logged.
)P
)DESCRIP
)P
(P
)P
)SECT2
)SECT1
(SECT1
(HEADING
-iptables ULOG target
)HEADING
(SECT2
(HEADING
-Quick Setup
)HEADING
(P
-Just add rules using the ULOG target to your firewalling chain. A very basic\nexample:\n
(TSCREEN
(VERB
-iptables -A FORWARD -j ULOG --ulog-nlgroup 32 --ulog-prefix foo 
)VERB
)TSCREEN
)P
(P
-To increase logging performance, try to use the\n
(TSCREEN
(VERB
---ulog-qthreshold N
)VERB
)TSCREEN
-\noption (where 1 \|[lt    ]\| N \|[lt    ]\|= 50). The number you specify is the amount of packets\nbatched together in one multipart netlink message. If you set this to 20, the\nkernel schedules ulogd only once every 20 packets. All 20 packets are then \nprocessed by ulogd. This reduces the number of context switches between kernel\nand userspace.
)P
(P
-Of course you can combine the ULOG target with the different netfilter match\nmodules.  For a more detailed description, have a look at the netfilter\nHOWTO's, available on the netfilter homepage.
)P
)SECT2
(SECT2
(HEADING
-ULOG target reference
)HEADING
(P
(DESCRIP
(TAG
---ulog-nlgroup N
)TAG
(P
-The number of the netlink multicast group to which ULOG'ed packets are sent.\nYou will have to use the same group number in the ULOG target and ulogd in\norder to make logging work.
)P
(TAG
---ulog-cprange N
)TAG
(P
-Copyrange.  This works like the 'snaplen' parameter of tcpdump.  You can specify\na number of bytes up to which the packet is copied.  If you say '40', you will\nreceive the first fourty bytes of every packet. Leave it to 
(TT
-0
)TT
)P
(TAG
---ulog-qthreshold N
)TAG
(P
-Queue threshold.  If a packet is matched by the iptables rule, and already N\npackets are in the queue, the queue is flushed to userspace.  You can use this\nto implement a policy like: Use a big queue in order to gain high performance,\nbut still have certain packets logged immediately to userspace.
)P
(TAG
---ulog-prefix STRING
)TAG
(P
-A string that is associated with every packet logged by this rule.  You can use\nthis option to later tell from which rule the packet was logged.
)P
)DESCRIP
)P
(P
)P
)SECT2
(SECT2
(HEADING
-ipt\|[lowbar]\|ULOG module parameters
)HEADING
(P
-The ipt\|[lowbar]\|ULOG kernel module has a couple of module loadtime parameters which can\n(and should) be tuned to accomodate the needs of the application:\n
(DESCRIP
(TAG
-nlbufsiz N
)TAG
(P
-Netlink buffer size. A buffer of the specified size N is allocated for every\nnetlink group that is used.  Please note that due to restrictions of the kernel\nmemory allocator, we cannot have a buffer size \|[gt    ]\| 128kBytes.  Larger buffer\nsizes increase the performance, since less kernel/userspace context switches\nare needed for the same amount of packets.  The backside of this performance\ngain is a potentially larger delay. The default value is 4096 bytes, which is\nquite small.
)P
(TAG
-flushtimeout N
)TAG
(P
-The flushtimeout dete
)P
)DESCRIP
)P
)SECT2
)SECT1
)SECT
)ARTICLE
)LINUXDOC