IPAC Version 1.10 (c) 1997 - 2000 Moritz Both For copyright notice see at the bottom of this file WHAT IS IT? ipac is a package which is designed to gather, summarize and nicely output the IP accounting data. ipac make summaries and graphs as ascii text and/or gif images with graphs. ipac... - is for Linux - runs on top of the ipfwadm or ipchains tool - needs certain kernel parts compiled in HOW DOES IT WORK? ipac consists of two scripts (shell and perl) and one C program: - ipacset reads a configuration file and sets up ip accounting for the kernel using ipfwadm or ipchains - 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 - ipacsum summarizes the data from a set of files and, optionally, replaces these files by one. It displays the values as a simple table containing the sums, as png graph pictures or as ascii graph pictures. UPDATE If you are updating from an old version of ipac, read the file UPDATE. 2.1.* OR NEWER KERNEL If you update your kernel from a 2.0 to 2.1 or newer version, beware that you will suddenly need the ipchains (version 1.3.8 or newer), awk and mktemp tools. If these all existed when you installed ipac, there is no need for re-installing; however, that is the unlikely case. You should probably re-install it anyway to be on the safe side. Once ipac was installed with all the tools in place, you can switch kernels as you like without re-installing. Put differently, if the programs ipfwadm, ipchains, awk and mktemp are in the PATH when installing, you are fine for every kernel. (As long as it is Linux.) INSTALLATION / PRECONDITIONS ipac runs at least under Linux kernel 2.0.29, 2.0.33, 2.0.35, 2.2.3 and 2.2.5. It should run on any kernel above. You need perl 5. If you want to use ipacsum to create images, you need a perl library called "GD". If GD is not installed and you run ipacsum to make images, it will exit with an error. GD can be found at http://www.cpan.org/CPAN.html - follow the link to the perl module list and look for GD. After downloading, you must install GD as described within the package. The type of images ipacsum makes depends on the version of the perl GD library you have. If you use GD version 1.19 or older, you will be generating gif images. If you use GD version 1.20 or later, the image format will be png. png is preferred because there is no copyright / patent hassle. PRECONDITIONS FOR 2.0.* kernels You need a kernel which was compiled with the configuration option CONFIG_IP_ACCT set to y. You also need the front end to ip firewall and ip accounting, that is, the tool 'ipfwadm'. I used version 2.3.0. PRECONDITIONS FOR 2.1.* and 2.2.* kernels You need a kernel which was compiled with the configuration option CONFIG_IP_FIREWALL set to y. You also need the front end to ip firewall and ip accounting, that is, the tool 'ipchains'. I used version 1.3.8, and it was reported that older versions do not work. Finally, you will need awk and mktemp. * Beware: firewall packet filter scripts may interfere with ipacset when * using 2.1.* or 2.2.* kernels! If you have a script that sets up a packet * filter, read the ipacset man page, section BUGS! INSTALLATION / OVERVIEW 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). INSTALLATION / 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' or 'both' interface ip number or interface name or empty 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 or at any interface. The direction means in or out of this interface, or both directions. For a more complete explanation of this file, see the man page of ipacset(8). * 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. INSTALLATION / 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 INSTALLATION / 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. Without arguments, ipacsum will print a sum for every rule in ipac.conf. It will evaluate every file it finds in the ip accounting data directory, thus, all data ever gathered by fetchipac will be used. ipacsum outputs a nicely formatted overview 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. Other capabilities of ipacsum include generation of graph images, filter output by rule name and setting time frame of files to be evaluated. For a complete description of ipacsum, read the man page ipacsum(8). A small help screen will be displayed with ipacsum --help. CLEANING UP 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. 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 summarized into one, meaning there will be no more information when exactly the traffic occurred, 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 past 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 FURTHER DOCUMENTATION Read the man pages - ipacset(8), ipacsum(8) and fetchipac(8). CONTRIBUTIONS The directory contrib/ contains stuff that does not directly belong to ipac but is related. Further (well-documented and... "nice") contributions to the directory are welcome! Thanks to all who contributed with patches, comments or suggestions! UPDATES, BUG REPORTS, WHERE TO GET For new versions of ipac, look at http://www.comlink.apc.org/~moritz/ipac.html There is a mailing list about ipac, for discussion, patches, suggestions and announcements. To subscribe, send mail to with the word "subscribe" (without the quotes) in the mail body. 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 - 2000 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, Im Moore 26, 30167 Hannover, Germany. Phone: +49-511-1610129 $Id: README,v 1.33 2000/08/07 10:24:22 kruemelmo Exp $ EOF