Installation and Configuration
==============================

1. iptables
-----------

Copy iptables.server (accounting directly on a server) or iptables.firewall
(accounting on the firewall or router) to /etc/init.d/iptables, and edit it
to set the path for DUMPFILE and to assign packets to different chains.

Alternatively you can use your own iptables script and only add the 'dump'
option, which should do:
   DATE=`date '+%Y%m%d%H%M%S'
   echo "START $DATE" >> $DUMPFILE
   iptables -vnxZ -L --line-numbers -t filter >> $DUMPFILE
   echo "END $DATE" >> $DUMPFILE

Start the new rules with: /etc/init.d/iptables start

If everything works ok (try: /etc/init.d/iptables status), you should make
your system use this script on startup and shutdown. Consult the manual of
your Linux distribution to see how this works.
Some examples:
    Debian: update-rc.d iptables defaults 17 30
    RedHat: chkconfig --add iptables

2. iam
------

Put the file iam and all *.py files in a directory of your choice.
Edit chains.py to set categories, names, rates and their descriptions.
There will be a configuration file for this in a future release.

3. crontab
----------

iam_report can be called via cron to generate web reports.
Put iam_report in a directory of your choice (e.g. where iam is installed),
and edit it to set IAM (file name of iam), DUMP (file name of dump file)
and WWWDIR (name of directory for web reports).

See file crontab.iam for an example of lines to add to the system-wide
/etc/crontab file.


Usage
=====

I assume iam and the file dump to be in the current directory, otherwise
replace ./iam with /path/to/iam and dump with /path/to/dump.
Text after '$' at the start of a line is a shell command.

1. Show help:
-------------

$ ./iam --help

Usage: iam [OPTIONS] [DUMPFILE]...

Options:
  -r, --report             - Print plain text report
  -o, --outfile=FILE       - Save output to FILE
  -w, --www=FILE           - Create WWW report in FILE
  -f, --from-date=YYYYMMDD - Lower date limit for report
  -t, --to-date=YYYYMMDD   - Upper date limit for report

Miscellaneous:
  -h, --help               - Display this help and exit
      --version            - print version information and exit

Comments and bug reports: Thomas Koester <tkoester@intevation.de>

2. Simple reports:
------------------

$ ./iam -r dump
Generate a plain text report of all data in 'dump'.

$ ./iam -r -o report.txt dump
Save a plain text report of all data to file 'report.txt'.

$ ./iam -w /home/www/report/report.html
Save a web report to file '/home/www/report/report.html'.

$ ./iam -r -o report.txt -w report.html
Save a plain text report to 'report.txt' and a web report to 'report.html'.
The advantage is that the dump file only needs to be read once.

3. Reports with date ranges:
----------------------------

$ ./iam -r -f 20010801 dump
Generate a plain text report of all data since August 2001.

$ ./iam -r -t 20010899 dump
Generate a plain text report of all data until end of August 2001.
Note that you can use 99 as the last day of the month here.

$ ./iam -r -f 20010800 -t 20010899 dump
Generate a plain text report of all data for August 2001.

Date ranges can be used with any combination of -r, -o and -w.
At the moment only the last -f and -t options will be used.

See iam_report for a real world example of using date ranges.


Sample output
=============

Generate a plain text report for August 2001 using data from file 'dump',
which was collected via iptables.server:
$ ./iam -r -f 20010800 -t 20010899 dump

                IP traffic (2001-08-01..2001-08-31):                
                ====================================                
| traffic   | cost      | description                              |
+-----------+-----------+------------------------------------------+
| 2465.3 MB |           | local (local network)                    |
|  586.4 MB |           | intevation (Intevation office)           |
+-----------+-----------+------------------------------------------+
| 3051.7 MB |           | free of charge                           |
+-----------+-----------+------------------------------------------+
|           |           |                                          |
| 1770.8 MB |  88.54 DM | www (http/https/caudium)                 |
| 1531.7 MB |  76.58 DM | cvs (grass-cvs)                          |
| 1423.8 MB |  71.19 DM | ip_local_port_range (probably FTP)       |
| 1307.3 MB |  65.37 DM | ftp (FTP (without passive data))         |
|  203.8 MB |  10.19 DM | mail (smtp)                              |
|    0.7 MB |   0.03 DM | misc (ssh, dns, identd)                  |
|    0.6 MB |   0.03 DM | outgoing (without other listed services) |
|    0.0 MB |   0.00 DM | rsync (rsync server (not backup))        |
+-----------+-----------+------------------------------------------+
| 6238.6 MB | 311.93 DM | internet services                        |
+-----------+-----------+------------------------------------------+
|           |           |                                          |
|    0.2 MB |   0.01 DM | related (related connections)            |
|    0.2 MB |   0.01 DM | unknown (not in any chain)               |
|    0.0 MB |   0.00 DM | fragment (fragmented packets)            |
+-----------+-----------+------------------------------------------+
|    0.4 MB |   0.02 DM | other traffic (unspecified)              |
+-----------+-----------+------------------------------------------+