ulogipac
========

ulogipac is a powerful IP traffic accounting tool for linux routers and
possibly hosts. You can use the power of iptables rules to specify which
traffic you want to account and which *not*.
The size of IP packets sent to ulogipac through iptables is counted and 
buffered. After a configurable timeperiod you can submit the traffic 
information to your database servers (currently only MySQL is supported). 
You can specify 1 to N servers to send traffic information to.


INSTALLATION

	see INSTALL for installation instructions

USAGE

Once ulogipac is installed you can start using it in combination with any 
iptables rule you like. Normally you want to account traffic, which is
routed to a linux router from one network interface to another or others 
(for example ppp devices terminating PPTP/PPPOE/DIALIN sessions).

iptables setup
==============

First of all you have to create iptables rules to sent IP headers of packets 
to ulogipac. This is done using iptables ULOG target. Check whether your 
kernel supports this. (find /lib/modules/`uname -r` -name ipt_ULOG*)

Then create some rules that match some packets. In this example we create a
new iptables chain which will catch *all* packets routed through a linux 
router using eth0 as external interface and eth1 as internal interface:

iptables -N TRAFFIC   # create new Chain TRAFFIC
iptables -F TRAFFIC   # flush/clear this chain for sanity

And two other chains catching Incoming and outgoing packets:

iptables -N TRAFFIC_ULOG_IN   # you should now know what this means
iptables -F TRAFFIC_ULOG_IN
iptables -N TRAFFIC_ULOG_OUT
iptables -F TRAFFIC_ULOG_OUT

Then you have to direct all forwarded packets to this chain:

iptables -A FORWARD -j TRAFFIC   # at the end of forwarding jump to TRAFFIC

Now its time to fill the new TRAFFIC chain with some more specific stuff:

# Incoming packets eth0->eth1 to TRAFFIC_ULOG_IN
iptables -A TRAFFIC -i eth0 -o eth1 -j TRAFFIC_ULOG_IN

# Outgoing packets eth1->eth0 to TRAFFIC_ULOG_OUT
iptables -A TRAFFIC -i eth1 -o eth0 -j TRAFFIC_ULOG_OUT

And now how to get packets from TRAFFIC_ULOG_XXX to the userspace program
ulogipac:

# send incomming traffic to netlinkgroup 10. Only copy 20 bytes 
# and queue 20 packets
iptables -A TRAFFIC_ULOG_IN -j ULOG --ulog-nlgroup 10 --ulog-cprange 20 --ulog-qthreshold 20

iptables -A TRAFFIC_ULOG_OUT -j ULOG --ulog-nlgroup 20 --ulog-cprange 20 --ulog-qthreshold 20


Why so many chains you may ask...

Well, with this you are now able to filter out some adress spaces, that don't
get accounted:

iptables -I TRAFFIC_ULOG_IN -s 10.0.0.0/16 -j RETURN
iptables -I TRAFFIC_ULOG_OUT -d 10.0.0.0/24 -j RETURN

These two lines will filter out traffic, which is then not accounted anymore
The Packets will not be blocked!!!

ulogipac.conf
=============

iptables is now set up. Now you should turn to /etc/ulogipac.conf. You can 
find an example in examples/ directory. Change the file to your needs.

You can specify 1 to N mysql servers. Make sure the user has the rights to
create tables and insert.

create_table_in and create_table_out will specify how new tables will be 
created by ulogipac. The tables will get names starting with table_prefix_in
and table_prefix_out. ulogipac adds the current year and month to the 
prefix and creates the tables if they don't exist. When month or year changes
the new tables will be created. So you don't have to worry about pre-creating
these tables.

Insert queries will be done using insert_in and insert_out specs. The 
following strings *must* be present:

ULOGIPAC_PID     # will be replaced by pid of main ulogipac process
ULOGIPAC_IP      # will be replaced by accounting IP
ULOGIPAC_BYTES   # will be replaced by sum of bytes

storage_interval specifies number of seconds to accumulate traffic 
internally before sending it to the database server(s).

netling_group_in and netlink_group_out should match the two values set
in TRAFFIC_ULOG_IN and TRAFFIC_ULOG_OUT chains


Starting ulogipac
=================

Ok. Now its time to start ulogipac. You can start processes for incomming
and outgoing traffic seperately:

ulogipac -d in
ulogipac -d out

The two processes will fork into background. Output and errors are sent to
Syslog Facility LOCAL6.

By adding

local6.*                        /var/log/ulogipac.log

to your /etc/syslog.conf you can have these messages in a seperate file.


!!! IMPORTANT NOTE FOR 0.04 USERS!!!

If ulogipac is crashing with segmentation fault, please add:

do_userid_query=no
userid_query="id from onlinedb where IP=ULOGIPAC_IP order by login desc limit 0,1"

to /etc/ulogipac.conf

Example will be fixed in 0.05 and check will be added.



Torge Szczepanek - tsml@szczepanek.de