summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorlaforge <laforge>2000-08-02 12:37:58 +0000
committerlaforge <laforge>2000-08-02 12:37:58 +0000
commita7d1240cba00fdea627bc020ffd236faf27a8fe6 (patch)
treeec4ff5be76543ae894e4018332077597d885d285 /README
parent0fe4f331f570e19ffdd4c80445f9c1d11aa2c203 (diff)
Initial revision
Diffstat (limited to 'README')
-rw-r--r--README79
1 files changed, 79 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..a2b8b99
--- /dev/null
+++ b/README
@@ -0,0 +1,79 @@
+Userspace logging facility for netfilter / linux 2.4
+$Id$
+
+===> 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_ACCEPT immediately
+
+We don't have to enqueue packets, just send them out as datagrams. If the
+user process isn't fast enough this isn't our problem.
+
+More than one logging daemon may listen to the netlink multicast address.
+
+===> CONTENTS
+
+The package is consisting out of three parts:
+
+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@sunbeam.franken.de>
+
+Credits to Rusty Russel, James Morris, Marc Boucher and all the other
+netfilter hackers.