
	IPAC Version 0.96
	(c) 1997, 1998 Moritz Both
	For copyright notice see at the bottom of this file

WHAT IS IT?

ipac is a package which is designed to summarize and nicely
output the IP accounting data.

ipac...
	- is for Linux
	- runs on top of the ipfwadm tool
	- needs certain kernel parts compiled in


HOW DOES IT WORK?

  ipac consists of three scripts (sh and perl):

  - ipacset reads a config file and sets up ip accounting
  for the kernel using ipfwadm

  - fetchipac, executed from cron once in a while, reads
  the current ip accounting data assembled by the kernel
  and writes it to a new file; the file also gets information
  about which filter should filter what

  - ipacsum summarizes the data from a set of files and, optionally,
  replaces these files by one.


PRECONDITIONS

This runs at least unter Linux kernel 2.0.29. It should run on any kernel
above. You need a kernel with IP accounting compiled in, that is, with
the option CONFIG_IP_ACCT set to y.

You also need ipfwadm - I used version 2.3.0 - and perl 5. 


INSTALLATION

To install:
  - Edit the file 'config'.
  - Type 'make'.
  - As root, type 'make install'.
  - Create the file 'ipac.conf' and execute ipacset (see below).
  - Put fetchipac into cron (see below).
  - Put ipacset into a startup file to set ip accounting after reboots
  	(see below)
  - Make sure that the accounting data files are cleaned up properly
  	(see below).


CONFIG FILE, RUNNING IPACSET

The ipac.conf file is '/etc/ipac.conf' if you don't change this path
in config. ipac.conf controls what data is collected. Each line
which begins with a '#' is ignored. All the other lines have the format

  Name of rule|direction|interface|protocol|source|destination

  where
  Name of rule          Any string to identify this rule
  direction             'in' or 'out'
  interface             ip number or interface name
  protocol              'tcp' or 'udp' or 'icmp' or 'all'
  source                \
  destination           both as described in ipfwadm(8), or empty
 
In the summaries, the 'Name of rule' string identifies the counter.
Both the source and destination must be in ipfwadm syntax -
consult the man page.

The interface can be named (for example, eth0) or its IP number can
be given. Linux IP accounting always counts at one interface. The
direction means in or out of this interface.

* You must run the ipacset script after changing the 
* ipac.conf file every time for the changes to take effect!

An example ipac.conf file comes with the distribution.


FETCHING ACCOUNTING DATA FROM KERNEL: FETCHIPAC IN CRON

In order to collect the accounting data, you must put a line into a
crontab to call fetchipac on a regular basis. The more often you call 
fetchipac, the less data is lost in case of a crash or reboot. It 
is unharmful to call fetchipac any time. I suggest to call it every 
15 minutes.  For example, put this into your /etc/crontab file:

# Save IP accounting info every five minutes.
*/15 * * * * root /usr/local/bin/fetchipac


AFTER REBOOTS

Naturally, the kernel forgets about the ip accounting on reboots.
To reset the ip accounting properly, you should put a line into a
startup file to call ipacset. For example, in my /etc/rc.d/rc.local
file, I put this:

# Switch on ip accounting
/usr/local/bin/ipacset


READING IP ACCOUNTING SUMMARIES

To get summaries, use ipacsum. ipacsum takes some arguments:

 -s time        Start time, default: The epoch
 -e time        End time, default: now
These times are either:
   * absolute, in format YYYYMMDD[hh[mm[ss]]] -> Note year is 4 digit!
     If you leave away the optional time of day, 00:00:00 is assumed;
     or
   * relative to now, format: any combination of (number size) pairs, 
     where size is one of {smhDWMY} (sec,min,hours,days,weeks,months,years)
Examples:
   -s19980101		Start time 1998/01/01, 0:00 am
   -s1Y                 Start time one year ago
   -e1D1m1s		End time one day, one minute and one second ago
   Note: One month is assumed to always have 30 days; one year is 365 days.

 -f regex       filter output by rule names on regular expression
This will only display the data for those rules matching regex. The
rule names are taken form the /etc/ipac.conf file, colomn 1.

 -g             print progression graph for every rule
 -i intervall   specify prograssion graph (-g) intervall; default 1 hour;
                 format: see -s relative from now time format.

With -g, output ascii graph for every rule. The graph displays the
progression of traffic for a rule. Use -i to determine the intervall,
for example, -i4h for four hours, -i8W for eight weeks or
-i1M3W2h for one month, three weeks and two hours.

 -t time_frame  Start and End time in one; time_frame is one of these:
	For -t, you can give the following time frames (quote if more than one
	word, n is any integer number):
		today, yesterday, "the day before yesterday",
		"the day n days ago",
		"this week", "last week", "the week before last week",
		"the week n weeks ago",
		"this month", "last month", "the month n months ago",
		"this year", "last year", "the year n years ago".

 -h             Print this help
 -r             replace all summarized accounting files by one
                 file name will be according to end time
                 (= highest file name)
 -x             eXact values (dont use K or MByte values)
 -d dir		specify data directory other than the default
		 (which is specified at install time in the config file)

ipacsum outputs a nicely formatted overwiev of all accounting rules
which were in effect during the given period. The rules are identified
by their names from the ipac.conf file. If a rule was added or
deleted during that time, it is nevertheless shown.

fetchipac generates a single file every time it runs. The more often
fetchipac runs, the more files you get and the more exact will be
your accounting info. For example, if you run fetchipac every five
minutes, ipacsum will be able to display accurate data for every
five minute period.


CLEANING UP

Every time ipacsum runs, you can let it make a summary file for
all the files read to replace them. This will decrease the needed
disk space and the time ipacsum needs to calculate sums for this
period. You lose accuracy, though, since all data files are
summerized into one, meaning there will be no more information
when exactly the traffic occured, but only the sum for the whole
period.

In general, it makes sense to periodically summarize the info
for a past period. For example, you could run these cron jobs
cleanups:

 - run fetchipac every 15 minutes
 - every hour, summarize the files of the hour 48 hours ago
 - every day, summarize the files of the day 7 days ago
 - every week, summarize the files of the week 11 weeks ago
 - every year, summarize the files of the year 2 years ago

With this scheme, you can have the data of the ip traffic with
15-minute-accuracy for the pase two days. For the last week, you
still can tell at which day the traffic passed your machine. Keeping
the daily files for 14 weeks, you have a daily overview of the last
three months. After that, you keep weekly files only. After two years,
you sum up the data of the year into one file.

The daily cron jobs could look like this:

# Summarize ip accounting info:
# every day, sum up the data of 7 days ago into one file.
1 0 * * * root /usr/local/bin/ipacsum -r -t "the day 7 days ago" >/dev/null
# every hour, sum up the data of 48 hours ago into one file
2 * * * * root /usr/local/bin/ipacsum -r -t "the hour 48 hours ago" >/dev/null
# every week, sum up the data of the week 11 weeks ago into one file
3 0 * * 0 root /usr/local/bin/ipacsum -r -t "the week 11 weeks ago" >/dev/null
# every year, sum up the data of the year 2 years ago into one file
4 0 1 2 * root /usr/local/bin/ipacsum -r -t "the year 2 years ago" >/dev/null


UPDATES, BUG REPORTS, WHERE TO GET

For new versions of ipfwadm, look at 
http://www.comlink.apc.org/~moritz/ipac.html

If you find a bug, please send me a report or a diff. See at the
bottom of this file for the email address.


COPYRIGHT

  Copyright (C) 1997,98 Moritz Both
 
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.
 
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
  The author can be reached via email: moritz@daneben.de, or by
  snail mail: Moritz Both, c/o Comlink, Im Moore 26, 30167 Hannover,
              Germany. Phone: +49-511-1617811
 

$Id: README,v 1.8 1998/02/23 13:52:36 moritz Exp $
EOF
