Userspace logging facility for netfilter / linux 2.4
$Id: README,v 1.2 2000/09/22 06:57:16 laforge Exp $

===> IDEA

This packages is intended for passing packets from the kernel to userspace 
to do some logging there. It should work like that:

- Register a target called ULOG with netfilter
- if the target is hit: 
	- send the packet out using netlink multicast facility
	- return NF_CONTINUE immediately

New with ipt_ULOG 0.8 we can accumulate packets in userspace and send
them in small batches (1-50) to userspace. This reduces the amount of
expensive context switches.

More than one logging daemon may listen to the netlink multicast address.

===> CONTENTS

The package is consisting out of three parts:

NOTE:
ipt_ULOG and libipt_ULOG are NOW INCLUDED IN NETFILTER patch-o-matic. 
I strongly recommend using the latest package or even CVS from 
http://netfilter.samba.org

1. Netfilter target ipt_ULOG
This is the kernel module which does the kernel part of packet passing to 
the userspace. This module is inserted on demand through the netfilter 
subsystem as soon as You add a rule with the target ULOG to any chain.

2. iptables plugin (libipt_ULOG.so)
This is a plugin for the netfilter configuration tool iptables. Just put 
it to /usr/local/lib/iptables and it is loaded on demand from iptables.

3. Ulog library (libipulog.a)
Just a little library like libipq.a which provides a convenient way to 
write userspace logging daemons. The functions provided are described 
in the source code, a small demo program (ulog_test) is also included.

4. ulogd daemon (ulogd) 
A sophisticated logging daemon which uses libipulog. The daemon provides 
an easy to use plugin interface to write additional packet interpreters and
output targets. Example plugins (interpreter: ip, tcp, icmp output: simple
logging to a file) are included.

===> USAGE

Just apply the kernel patch and enable the kernel config option 
CONFIG_IP_NF_TARGET_ULOG in the netfilter subsection of the network options. 
Then recompile the kernel or just recompile the netfilter modules using 
'make modules SUBDIRS=net/ipv4/netfilter'. 
Next step is installing the module using 'make modules_install'

To use the iptables plugin, copy libipt_ULOG.so to /usr/local/lib/iptables

Now You are ready to go. You may now insert logging rules to every chain.
To see the full syntax, type 'iptables -j ULOG -h'

===> EXAMPLES

At first a simple example, which passes every outgoing packet to the 
userspace logging, using netlink multicast group 3.

iptables -A OUTPUT -j ULOG --ulog-nlgroup 3

A more advanced one, passing all incoming tcp packets with destination 
port 80 to the userspace logging daemon listening on netlink multicast 
group 32. All packets get tagged with the ulog prefix "inp"

iptables -A INPUT -j ULOG -p tcp --dport 80 --ulog-nlgroup 32 --ulog-prefix inp

In the latest Version (0.2) I added another parameter (--ulog-cprange). 
Using this parameter You are able to specify how much octets of the 
packet should be copied from the kernel to userspace. 
Setting --ulog-cprange to 0 does always copy the whole packet. Default is 0

===> COPYRIGHT + CREDITS

The code is (C) 2000 by Harald Welte <laforge@gnumonks.org>

Credits to Rusty Russel, James Morris, Marc Boucher and all the other 
netfilter hackers.