README

   1
   2 NOTE: This is the README for ulogd, not DRL.  All of the DRL-related
   3 code and documentation is located in the drl subdirectory.
   4
   5 ------------------------------------------------------------------------------
   6
   7 Userspace logging facility for iptables / linux 2.4
   8 $Id: README 4896 2003-03-05 23:03:49Z laforge $
   9
  10 Project Homepage: http://www.gnumonks.org/projects/ulogd
  11 Mailinglist: http://lists.gnumonks.org/mailman/listinfo/ulogd/
  12
  13 This is just a short README, pleaes see the more extensive documentation
  14 in the doc/ subdirectory.
  15
  16 ===> IDEA
  17
  18 This packages is intended for passing packets from the kernel to userspace
  19 to do some logging there. It should work like that:
  20
  21 - Register a target called ULOG with iptables
  22 - if the target is hit:
  23         - send the packet out using netlink multicast facility
  24         - return NF_CONTINUE immediately
  25
  26 New with ipt_ULOG 0.8 we can accumulate packets in userspace and send
  27 them in small batches (1-50) to userspace. This reduces the amount of
  28 expensive context switches.
  29
  30 More than one logging daemon may listen to the netlink multicast address.
  31
  32 ===> CONTENTS
  33
  34 = Ulog library (libipulog.a)
  35 Just a little library like libipq.a which provides a convenient way to
  36 write userspace logging daemons. The functions provided are described
  37 in the source code, a small demo program (ulog_test) is also included.
  38
  39 = ulogd daemon (ulogd)
  40 A sophisticated logging daemon which uses libipulog. The daemon provides
  41 an easy to use plugin interface to write additional packet interpreters and
  42 output targets. Example plugins (interpreter: ip, tcp, icmp output: simple
  43 logging to a file) are included.
  44
  45 = documentation (doc)
  46 A quite verbose documentation of this package and it's configuration exists,
  47 please actually make use of it and read it :)
  48
  49 ===> USAGE
  50
  51 The kernel part of the userspace logging facility (ipt_ULOG.o) is included
  52 in kernels >= 2.4.18-pre8.  If you are running older kernel versions, you MUST
  53 install the ulog-patch from netfilter patch-o-matic FIRST !!
  54
  55 Please go to the netfilter homepage (http://www.netfilter.org/)
  56 and download the latest iptables package.  There is a system called
  57 patch-o-matic, which manages recent netfilter development, which has
  58 not been included in the stock kernel yet.
  59
  60 Just apply the ulog-patch from patch-o-matic (there is some documentation
  61 included in the iptables package how to use patch-o-matic).
  62
  63 Next you have to enable the kernel config option CONFIG_IP_NF_TARGET_ULOG in
  64 the netfilter subsection of the network options.
  65
  66 Then recompile the kernel or just recompile the netfilter modules using 'make
  67 modules SUBDIRS=net/ipv4/netfilter'.  Next step is installing the module using
  68 'make modules_install'
  69
  70 It is also a good idea to recompile and re-install the iptables package,
  71 if you don't already have libipt_ULOG.so in /usr/local/lib/iptables or
  72 /usr/lib/iptables
  73
  74 Now You are ready to go. You may now insert logging rules to every chain.
  75 To see the full syntax, type 'iptables -j ULOG -h'
  76
  77 ===> EXAMPLES
  78
  79 At first a simple example, which passes every outgoing packet to the
  80 userspace logging, using netlink multicast group 3.
  81
  82 iptables -A OUTPUT -j ULOG --ulog-nlgroup 3
  83
  84 A more advanced one, passing all incoming tcp packets with destination
  85 port 80 to the userspace logging daemon listening on netlink multicast
  86 group 32. All packets get tagged with the ulog prefix "inp"
  87
  88 iptables -A INPUT -j ULOG -p tcp --dport 80 --ulog-nlgroup 32 --ulog-prefix inp
  89
  90 Since version 0.2,  I added another parameter (--ulog-cprange).
  91 Using this parameter You are able to specify how much octets of the
  92 packet should be copied from the kernel to userspace.
  93 Setting --ulog-cprange to 0 does always copy the whole packet. Default is 0
  94
  95 ===> COPYRIGHT + CREDITS
  96
  97 The code is (C) 2000-2003 by Harald Welte <laforge@gnumonks.org>
  98
  99 Thanks also to the valuable Contributions of Daniel Stone, Alexander
 100 Janssen and Michael Stolovitzsky.
 101
 102 Credits to Rusty Russel, James Morris, Marc Boucher and all the other
 103 netfilter hackers.