doc/ulogd.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4  <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
   5  <TITLE>ULOGD - the Userspace Logging Daemon</TITLE>
   6 </HEAD>
   7 <BODY>
   8 <H1>ULOGD - the Userspace Logging Daemon</H1>
   9
  10 <H2>Harald Welte &lt;laforge@gnumonks.org&gt;</H2>Revision $Revision: 5846 $, $Date: 2005-07-12 17:33:23 +0200 (Tue, 12 Jul 2005) $
  11 <HR>
  12 <EM>This is the documentation for <CODE>ulogd</CODE>, the Userspace logging daemon.
  13 ulogd makes use of the Linux &gt;= 2.4.x packet filter subsystem (iptables) and
  14 the ULOG target for iptables.</EM>
  15 <HR>
  16 <H2><A NAME="s1">1. DESIGN</A></H2>
  17
  18 <H2><A NAME="ss1.1">1.1 CONCEPT</A>
  19 </H2>
  20
  21 <P>I want to provide a flexible, almost universal logging daemon for my netfilter
  22 ULOG target. It is not optimized in any way, the goal is to keep as simple as
  23 possible. These are my thoughts about how the architecture which is most
  24 capable of doing that:</P>
  25 <P>
  26 <DL>
  27 <DT><B>Interpreter plugins</B><DD><P>It should be possible to add plugins / runtime modules for new protocols, etc.
  28 For example the standard logging daemon provides source-ip, dest-ip,
  29 source-port, dest-port, etc. Logging for various other protocols (GRE,
  30 IPsec, ...) may be implemented as modules.</P>
  31
  32 <DT><B>Output plugins</B><DD><P>... describe how and where to put the information gained by logging plugins.
  33 The easiest way is to build a line per packet and fprint it to a file.
  34 Some people might want to log into a SQL database or want an output
  35 conforming to the intrusion detection systems communication draft from the
  36 IETF.</P>
  37
  38 </DL>
  39 </P>
  40
  41 <H2><A NAME="ss1.2">1.2 DETAILS</A>
  42 </H2>
  43
  44 <P>The major clue is providing a framework which is as flexible as possible.
  45 Nobody knows what strange network protocols are out there :) Flexibility
  46 depends on the communication between the output of the logging plugins
  47 and input of the output plugins.</P>
  48 <P>Rusty advised me to use some kind of type-key-value triples, which is in fact
  49 what I implemented.</P>
  50 <P>One issue is, of course, performance. Up to ulogd 0.3, ulogd did several
  51 linked list iterations and about 30 malloc() calls _per packet_. This
  52 changed with the new &gt;= 0.9 revisions:
  53 <UL>
  54 <LI>Not a single dynamic allocation in the core during runtime.
  55 Everything is pre-allocated at start of ulogd to provide the highest
  56 possible throughput.</LI>
  57 <LI>Hash tables in addition to the linked lists. Linked lists are only
  58 traversed if we really want to access each element of the list.</LI>
  59 </UL>
  60 </P>
  61
  62 <H2><A NAME="s2">2. INSTALLATION</A></H2>
  63
  64
  65 <H2><A NAME="ss2.1">2.1 Linux kernel</A>
  66 </H2>
  67
  68 <P>First you will need a recent 2.4.x kernel.  If you have a kernel &gt;=
  69 2.4.18-pre8, it already has the kernel support for ULOG (ipt_ULOG.o).</P>
  70 <P>If you have an older kernel version (between 2.4.0 and 2.4.18-pre6), you
  71 can use the patch-o-matic system of netfilter/iptables, as described in
  72 the following section.</P>
  73
  74 <H2><A NAME="ss2.2">2.2 ipt_ULOG from netfilter/iptables patch-o-matic</A>
  75 </H2>
  76
  77 <P>You only need to read this chapter if you have a 2.4.x kernel &lt;=
  78 2.4.18-pre6.</P>
  79 <P>In order to put the ipt_ULOG module into your kernel source,you need the latest
  80 iptables package, or even better: the latest CVS snapshot. A description how to
  81 obtain this is provided on the netfilter
  82 homepage
  83 <A HREF="http://www.netfilter.org/">http://www.netfilter.org/</A>.</P>
  84 <P>To run patch-o-matic, just type
  85 <BLOCKQUOTE><CODE>
  86 <PRE>
  87 make patch-o-matic
  88 </PRE>
  89 </CODE></BLOCKQUOTE>
  90
  91 in the userspace directory of netfilter CVS.</P>
  92
  93 <H2><A NAME="ss2.3">2.3 ulogd</A>
  94 </H2>
  95
  96 <H3>Recompiling the source</H3>
  97
  98 <P>Download the ulogd package from
  99 <A HREF="http://ftp.netfilter.org/pub/ulogd/">http://ftp.netfilter.org/pub/ulogd/</A> and
 100 untar it. </P>
 101 <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>
 102 <P>To compile and install the program, call 'make install'.</P>
 103
 104 <H3>Using a precompiled package</H3>
 105
 106 <P>I also provide a SRPM, which should compile on almost any rpm-based distribution. It is available at
 107 <A HREF="http://ftp.netfilter.org/pub/ulogd/">http://ftp.netfilter.org/pub/ulogd/</A></P>
 108 <P>Just download the package and do the usual 'rpm --rebuild &lt;file&gt;'.</P>
 109
 110 <H2><A NAME="s3">3. Configuration</A></H2>
 111
 112 <H2><A NAME="ss3.1">3.1 iptables ULOG target</A>
 113 </H2>
 114
 115 <H3>Quick Setup</H3>
 116
 117 <P>Just add rules using the ULOG target to your firewalling chain. A very basic
 118 example:
 119 <BLOCKQUOTE><CODE>
 120 <PRE>
 121 iptables -A FORWARD -j ULOG --ulog-nlgroup 32 --ulog-prefix foo
 122 </PRE>
 123 </CODE></BLOCKQUOTE>
 124 </P>
 125 <P>To increase logging performance, try to use the
 126 <BLOCKQUOTE><CODE>
 127 <PRE>
 128 --ulog-qthreshold N
 129 </PRE>
 130 </CODE></BLOCKQUOTE>
 131
 132 option (where 1 &lt; N &lt;= 50). The number you specify is the amount of packets
 133 batched together in one multipart netlink message. If you set this to 20, the
 134 kernel schedules ulogd only once every 20 packets. All 20 packets are then
 135 processed by ulogd. This reduces the number of context switches between kernel
 136 and userspace.</P>
 137 <P>Of course you can combine the ULOG target with the different netfilter match
 138 modules.  For a more detailed description, have a look at the netfilter
 139 HOWTO's, available on the netfilter homepage.</P>
 140 <H3>ULOG target reference</H3>
 141
 142 <P>
 143 <DL>
 144 <DT><B>--ulog-nlgroup N</B><DD><P>The number of the netlink multicast group to which ULOG'ed packets are sent.
 145 You will have to use the same group number in the ULOG target and ulogd in
 146 order to make logging work.</P>
 147 <DT><B>--ulog-cprange N</B><DD><P>Copyrange.  This works like the 'snaplen' parameter of tcpdump.  You can specify
 148 a number of bytes up to which the packet is copied.  If you say '40', you will
 149 receive the first fourty bytes of every packet. Leave it to <CODE>0</CODE></P>
 150 <DT><B>--ulog-qthreshold N</B><DD><P>Queue threshold.  If a packet is matched by the iptables rule, and already N
 151 packets are in the queue, the queue is flushed to userspace.  You can use this
 152 to implement a policy like: Use a big queue in order to gain high performance,
 153 but still have certain packets logged immediately to userspace.</P>
 154 <DT><B>--ulog-prefix STRING</B><DD><P>A string that is associated with every packet logged by this rule.  You can use
 155 this option to later tell from which rule the packet was logged.</P>
 156 </DL>
 157 </P>
 158
 159 <H3>ipt_ULOG module parameters</H3>
 160
 161 <P>The ipt_ULOG kernel module has a couple of module loadtime parameters which can
 162 (and should) be tuned to accomodate the needs of the application:
 163 <DL>
 164 <DT><B>nlbufsiz N</B><DD><P>Netlink buffer size. A buffer of the specified size N is allocated for every
 165 netlink group that is used.  Please note that due to restrictions of the kernel
 166 memory allocator, we cannot have a buffer size &gt; 128kBytes.  Larger buffer
 167 sizes increase the performance, since less kernel/userspace context switches
 168 are needed for the same amount of packets.  The backside of this performance
 169 gain is a potentially larger delay. The default value is 4096 bytes, which is
 170 quite small.</P>
 171 <DT><B>flushtimeout N</B><DD><P>The flushtimeout determines, after how many clock ticks (on alpha: 1ms, on
 172 x86 and most other platforms: 10ms time units) the buffer/queue is to be
 173 flushed, even if it is not full.  This can be used to have the advantage of a
 174 large buffer, but still a finite maximum delay introduced.  The default value
 175 is set to 10 seconds.</P>
 176 </DL>
 177
 178 Example:
 179 <BLOCKQUOTE><CODE>
 180 <PRE>
 181 modprobe ipt_ULOG nlbufsiz=65535 flushtimeout=100
 182 </PRE>
 183 </CODE></BLOCKQUOTE>
 184
 185 This would use a buffer size of 64k and a flushtimeout of 100 clockticks (1 second on x86).</P>
 186
 187 <H2><A NAME="ss3.2">3.2 ulogd</A>
 188 </H2>
 189
 190 <P>ulogd is what this is all about, so let's describe it's configuration...</P>
 191 <H3>ulogd configfile syntax reference</H3>
 192
 193 <P>All configurable parameters of ulogd are in the configfile, typically located
 194 at '/etc/ulogd.conf'.</P>
 195 <P>The following configuration parameters are available:
 196 <DL>
 197 <DT><B>nlgroup</B><DD><P>The netlink multicast group, which ulgogd should bind to. This is the same as
 198 given with the '--ulog-nlgroup' option to iptables.</P>
 199 <DT><B>logfile</B><DD><P>The main logfile, where ulogd reports any errors, warnings and other unexpected conditions. Apart from a regular filename, the following special values can be used; ``syslog'' to log via the unix syslog(3) mechanism.  ``stdout'' to log to stdout.</P>
 200 <DT><B>loglevel</B><DD><P>This specifies, how verbose the logging to logfile is. Currently defined
 201 loglevels are: 1=debug information, 3=informational messages, 5=noticable
 202 exceptional conditions, 7=error conditions, 8=fatal errors, program abort.</P>
 203 <DT><B>plugin</B><DD><P>This option is followed by a filename of a ulogd plugin, which ulogd shold load
 204 upon initialization. This option may appear more than once.</P>
 205 <DT><B>rmem</B><DD><P>Size of the netlink socket receive memory.  You should set this to at least the
 206 size of the kernel buffer (nlbufsiz parameter of the ipt_ULOG module).  Please
 207 note that there is a maximum limit in /proc/sys/net/core/rmem_max which you
 208 cannot exceed by increasing the ``rmem'' parameter.  You may need to raise the
 209 system-wide maximum limit before.</P>
 210 <DT><B>bufsize</B><DD><P>Size of the receive buffer. You should set this to at least the socket receive buffer (rmem).</P>
 211 </DL>
 212 </P>
 213 <H3>ulogd commandline option reference</H3>
 214
 215 <P>Apart from the configfile, there are a couple of commandline options to ulogd:
 216 <DL>
 217 <DT><B>-h --help</B><DD><P>Print a help message about the commandline options.</P>
 218 <DT><B>-V --version</B><DD><P>Print version information about ulogd.</P>
 219 <DT><B>-d --daemon</B><DD><P>For off into daemon mode.  Unless you are debugging, you will want to use this
 220 most of the time.</P>
 221 <DT><B>-c --configfile</B><DD><P>Using this commandline option, an alternate config file can be used.  This is
 222 important if multiple instances of ulogd are to be run on a single machine.</P>
 223 </DL>
 224 </P>
 225
 226 <H2><A NAME="s4">4. Available plugins</A></H2>
 227
 228 <P>It is important to understand that ulogd without plugins does nothing.  It will receive packets, and do nothing with them.</P>
 229 <P>There are two kinds of plugins, interpreter and output plugins.  Interpreter
 230 plugins parse the packet, output plugins write the interpreted information to
 231 some logfile/database/...</P>
 232
 233 <H2><A NAME="ss4.1">4.1 Interpreter plugins</A>
 234 </H2>
 235
 236 <P>ulogd comes with the following interpreter plugins:</P>
 237 <H3>ulogd_BASE.so</H3>
 238
 239 <P>Basic interpreter plugin for nfmark, timestamp, mac address, ip header, tcp
 240 header, udp header, icmp header, ah/esp header... Most people will want to load
 241 this very important plugin.</P>
 242 <H3>ulogd_PWSNIFF.so</H3>
 243
 244 <P>Example interpreter plugin to log plaintext passwords as used with FTP and
 245 POP3. Don't blame me for writing this plugin! The protocols are inherently
 246 insecure, and there are a lot of other tools for sniffing passwords... it's
 247 just an example.</P>
 248 <H3>ulogd_LOCAL.so</H3>
 249
 250 <P>This is a 'virtual interpreter'.  It doesn't really return any information on
 251 the packet itself, rather the local system time and hostname.  Please note that
 252 the time is the time at the time of logging, not the packets receive time.</P>
 253
 254 <H2><A NAME="ss4.2">4.2 Output plugins</A>
 255 </H2>
 256
 257 <P>ulogd comes with the following output plugins:</P>
 258
 259 <H3>ulogd_OPRINT.so</H3>
 260
 261 <P>A very simple output module, dumping all packets in the format
 262 <BLOCKQUOTE><CODE>
 263 <PRE>
 264 ===>PACKET BOUNDARY
 265 key=value
 266 key=value
 267 ...
 268 ===>PACKET BOUNDARY
 269 ...
 270 </PRE>
 271 </CODE></BLOCKQUOTE>
 272
 273 to a file.  The only useful application is debugging.</P>
 274 <P>The module defines the following configuration directives:
 275 <DL>
 276 <DT><B>dumpfile</B><DD><P>The filename where it should log to. The default is
 277 <CODE>/var/log/ulogd.pktlog</CODE></P>
 278 </DL>
 279 </P>
 280
 281 <H3>ulogd_LOGEMU.so</H3>
 282
 283 <P>An output module which tries to emulate the old syslog-based LOG targed as far
 284 as possible. Logging is done to a seperate textfile instead of syslog, though.</P>
 285 <P>The module defines the following configuration directives:
 286 <DL>
 287 <DT><B>file</B><DD><P>The filename where it should log to. The default is
 288 <CODE>/var/log/ulogd.syslogemu</CODE></P>
 289 <DT><B>sync</B><DD><P>Set this to 1 if you want to have your logfile written
 290 synchronously. This may reduce performance, but makes your log-lines appear
 291 immediately.  The default is <CODE>0</CODE></P>
 292 </DL>
 293 </P>
 294
 295 <H3>ulogd_MYSQL.so</H3>
 296
 297 <P>An output plugin for logging into a mysql database. This is only compiled if
 298 you have the mysql libraries installed, and the configure script was able to
 299 detect them. (that is: --with-mysql was specified for ./configure)</P>
 300
 301 <P>The plugin automagically inserts the data into the configured table; It
 302 connects to mysql during the startup phase of ulogd and obtains a list of the
 303 columns in the table. Then it tries to resolve the column names against keys of
 304 interpreter plugins. This way you can easily select which information you want
 305 to log - just by the layout of the table.</P>
 306
 307 <P>If, for example, your table contains a field called 'ip_saddr', ulogd will
 308 resolve this against the key 'ip.saddr' and put the ip address as 32bit
 309 unsigned integer into the table.</P>
 310
 311 <P>You may want to have a look at the file '<CODE>doc/mysql.table</CODE>' as an
 312 example table including fields to log all keys from ulogd_BASE.so. Just delete
 313 the fields you are not interested in, and create the table.</P>
 314
 315 <P>The module defines the following configuration directives:
 316 <DL>
 317 <DT><B>table</B><DD><P>Name of the table to which ulogd should log.</P>
 318 <DT><B>ldb</B><DD><P>Name of the mysql database.</P>
 319 <DT><B>host</B><DD><P>Name of the mysql database host.</P>
 320 <DT><B>port</B><DD><P>TCP port number of mysql database server.</P>
 321 <DT><B>user</B><DD><P>Name of the mysql user.</P>
 322 <DT><B>pass</B><DD><P>Password for mysql.</P>
 323 </DL>
 324 </P>
 325
 326 <H3>ulogd_PGSQL.so</H3>
 327
 328 <P>An output plugin for logging into a postgresql database. This is only compiled
 329 if you have the mysql libraries installed, and the configure script was able to
 330 detect them. (that is: --with-pgsql was specified for ./configure)</P>
 331
 332 <P>The plugin automagically inserts the data into the configured table; It
 333 connects to pgsql during the startup phase of ulogd and obtains a list of the
 334 columns in the table. Then it tries to resolve the column names against keys of
 335 interpreter plugins. This way you can easily select which information you want
 336 to log - just by the layout of the table.</P>
 337
 338 <P>If, for example, your table contains a field called 'ip_saddr', ulogd will
 339 resolve this against the key 'ip.saddr' and put the ip address as 32bit
 340 unsigned integer into the table.</P>
 341
 342 <P>You may want to have a look at the file '<CODE>doc/mysql.table</CODE>' as an
 343 example table including fields to log all keys from ulogd_BASE.so. Just delete
 344 the fields you are not interested in, and create the table.</P>
 345
 346 <P>The module defines the following configuration directives:
 347 <DL>
 348 <DT><B>table</B><DD><P>Name of the table to which ulogd should log.</P>
 349 <DT><B>db</B><DD><P>Name of the database.</P>
 350 <DT><B>host</B><DD><P>Name of the mysql database host.</P>
 351 <DT><B>port</B><DD><P>TCP port number of database server.</P>
 352 <DT><B>user</B><DD><P>Name of the sql user.</P>
 353 <DT><B>pass</B><DD><P>Password for sql user.</P>
 354 </DL>
 355 </P>
 356
 357 <H3>ulogd_PCAP.so</H3>
 358
 359 <P>An output plugin that can be used to generate libpcap-style packet logfiles.
 360 This can be useful for later analysing the packet log with tools like tcpdump
 361 or ethereal.</P>
 362 <P>The module defines the following configuration directives:
 363 <DL>
 364 <DT><B>file</B><DD><P>The filename where it should log to.  The default is:
 365 <CODE>/var/log/ulogd.pcap</CODE></P>
 366 <DT><B>sync</B><DD><P>Set this to <CODE>1</CODE> if you want to have your pcap logfile written
 367 synchronously.  This may reduce performance, but makes your packets appear
 368 immediately in the file on disk.  The default is <CODE>0</CODE></P>
 369 </DL>
 370 </P>
 371
 372 <H3>ulogd_SQLITE3.so</H3>
 373
 374 <P>An output plugin for logging into a SQLITE v3 database. This is only compiled
 375 if you have the sqlite libraries installed, and the configure script was able to
 376 detect them. (that is: --with-sqlite3 was specified for ./configure)</P>
 377
 378 <P>The plugin automagically inserts the data into the configured table; It
 379 opens the sqlite db during the startup phase of ulogd and obtains a list of the
 380 columns in the table. Then it tries to resolve the column names against keys of
 381 interpreter plugins. This way you can easily select which information you want
 382 to log - just by the layout of the table.</P>
 383
 384 <P>If, for example, your table contains a field called 'ip_saddr', ulogd will
 385 resolve this against the key 'ip.saddr' and put the ip address as 32bit
 386 unsigned integer into the table.</P>
 387
 388 <P>You may want to have a look at the file '<CODE>doc/sqlite3.table</CODE>' as an
 389 example table including fields to log all keys from ulogd_BASE.so. Just delete
 390 the fields you are not interested in, and create the table.</P>
 391
 392 <P>The module defines the following configuration directives:
 393 <DL>
 394 <DT><B>table</B><DD><P>Name of the table to which ulogd should log.</P>
 395 <DT><B>db</B><DD><P>Name of the database.</P>
 396 <DT><B>buffer</B><DD><P>Size of the sqlite buffer.</P>
 397 </DL>
 398 </P>
 399 <H3>ulogd_SYSLOG.so</H3>
 400
 401 <P>An output plugin that really logs via syslogd. Lines will look exactly like printed with traditional LOG target.</P>
 402
 403 <P>The module defines the following configuration directives:
 404 <DL>
 405 <DT><B>facility</B><DD><P>The syslog facility (LOG_DAEMON, LOG_KERN, LOG_LOCAL0 .. LOG_LOCAL7, LOG_USER)</P>
 406 <DT><B>level</B><DD><P>The syslog level (LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG)</P>
 407 </DL>
 408 </P>
 409 <H2><A NAME="s5">5. QUESTIONS / COMMENTS</A></H2>
 410
 411 <P>All comments / questions / ... are appreciated.</P>
 412 <P>Just drop me a note to laforge@gnumonks.org</P>
 413 <P>Please note also that there is now a mailinglist, ulogd@lists.gnumonks.org.
 414 You can subscribe at
 415 <A HREF="http://lists.gnumonks.org/mailman/listinfo/ulogd/">http://lists.gnumonks.org/mailman/listinfo/ulogd/</A>.</P>
 416 <P>
 417 The preferred method for reporting bugs is the netfilter bugzilla system,
 418 available at
 419 <A HREF="http://bugzilla.netfilter.org/">http://bugzilla.netfilter.org/</A>.</P>
 420
 421 </BODY>
 422 </HTML>