fetchipac - ip accounting kernel data and database handler

fetchipac [ -b|--batch ] [ -d|--directory DIR ] [ -h|--help ] [ -m|--machine-output-format ] [ -r|--records ] [ -R|--list-raw ] [ -s|--storage-method METHOD ] [ -S|--start ] [ -t|--timestamps [START][,END] ] [ -v|--verbose ]

fetchipac is part of the ipac-ng linux ip accounting package.

fetchipac reads the kernel ip counters and stores this information in a database. It also provides access to the database for other programs, mainly for ipacsum(8).

If you are an average user of ipac, you don't want to know about most of the things described here. You will want to run fetchipac regulary from cron, probably without any options. You will possibly want to use the options --directory and --storage-method. The rest is mostly for internal use by ipac and for debugging the database.

fetchipac operates in different modes and does fairly unrelated things. The only common thing it does is that it accesses a database. The database can be of different types which are called storage methods. The storage methods provided are: gdbm plain-file . The default storage method used is plain-file. fetchipac uses a directory to store data. The default directory for that is /var/lib/ipac. If the storage method does not make use of this directory, for example, if it stores the data on a remote host, the directory is still used for the spool file (see below). (All these defaults are determined at build time and this man page is updated automatically.)

When fetchipac is called without any arguments, it fetches kernel ip accounting data.

To do this, it first runs through a lock mechanism to prevent multiple instances of fetchipac to run at the same time. Then, it reads the ipac rule file, /var/run/ipac.rules, which maps kernel ip accounting data to names. Next, it reads the kernel ip accounting data from the appropriate file in /proc/net, which is /proc/net/ip_fwchains if you have an ipchains system (kernel 2.1.* or newer) fetchipac opens this file in read/write mode; this makes the kernel set all counters to zero in the moment the file is opened and we can be sure to count every byte only once (see BUGS section. In case of kernel 2.4.* it uses kernel's internal structures to read byte and packet counters.

After reading and closing those files, fetchipac creates a new record in its database using the default storage method.

There is a spool mechanism which allows fetchiapc to spool ip accounting data in a file when the database cannot be opened. For example, if the storage method stores data on a remote host, the remote host might be down or unreachable. Another example is the gdbm storage method; if some other process accesses a gdbm file, it is locked and can't be written to. If fetchipac could not spool the data, it would be lost in either case.

If the database can't be opened, the data collected from the kernel is put into a spool file. The spool file resides in the data directory and its name is spool. If there is already data in this spool file, the new records are appended. The data is stored in this file in the same format as described unter the batch mode command ADD (see below).

Whenever fetchipac runs, it checks if the spool file exists. If so, and if the database can be opened, the contents of the spool file is copied into the database and the spool file is removed.

-d|--directory DIR

Use a different data directory DIR instead of the default, /var/lib/ipac, for the database (if the storage method uses a directory to store data) and the spool file.

-h|--help

Print a help message and exit.

-s|--storage-method METHOD

Use METHOD as the storage method. METHOD can be one of the compiled in storage methods. Run fetchipac --help to see which storage methods exactly have been compiled in.

-S|--start

initial accounting setup: insert accounting rules and chains according to your /etc/ipac-ng/ipac.conf

-b|--batch

Switch to batch mode. In this mode, fetchipac does not fetch ip accounting data from the kernel. Instead, it displays a prompt, "> ", on standard output and then expects commands. fetchipac exists when the command QUIT was entered or at end of file on stdin. See below, section BATCH MODE, for a description of the commands.

-m|--machine-output-format

When using the --record or --timestamps options, fetchipac normally prints the data in a nice human readable format. When using this option, the data will be formatted in a way that it is easily parsable by a program. This is used by ipacsum(8).

When used with --record, the output generated will be in the format fetchipac expects in batch mode with the ADD command.

When used with --timestamps, the output generated will be in the format expected on standard input with the --record option.

-r|--records

Switch to record retrieve mode. In this mode, fetchipac does not read the kernel ip accounting data from the kernel. Instead, it reads lines from standard input and exits on end of file on stdin. The lines are interpreted as decimal numbers which represent timestamps. (The lines may begin with a single character '+', '-' or '*', which is discarded. The number may also be preceded by white spaces.)

For every timestamp read, fetchipac tries to retrieve the record from the database. If such a record is not found, it prints "ERROR". If it is found, the record is displayed in a human readable format. (See also option --machine-output-format.)

-R|--list-raw

List rules and chains to be inserted into firewall. Don't actually insert them, just list.

-t|--timestamps [START][,END]

Print all timestamps for which there are records in the database. If given, start with timestamp START and end with END. START is interpreted exclusively (if a timestamp START exists, it will NOT be printed) and END is interpreted inclusively (if a timestamp END exists, it WILL be printed).

Also, print the final timestamp before START and the first timestamp after END.

The output will be in a human readable format, unless the --machine-output-format option is given.

-v|--verbose

Be verbose. Add more 'v' for more verbosity.

When fetchipac is in batch mode (option --batch), it recognizes the following commands on standard input:

ADD

The ADD command is used to add a record to the database. The ADD command takes no arguments, but after giving the ADD command, fetchipac expects one data record on standard input.

The data record consists of a decimal number representing the timestamp of the record, followed by a space character, followed by a decimal number representing the number of sub records that will follow, followed by a newline character, followed by the individual sub records, followed by a newline character.

A sub record consists of the character '(', followed by a space character, followed by a host name representing the machine where the data was measured, followed by a newline character, followed by individual rules, followed by the character ')', followed by a newline character.

A rule consists of a decimal number representing a byte count, followed by a space character, followed by a decimal number representing a packet count, followed by a space character, followed by the character '|', followed by a rule name, followed by the character '|', followed by a newline character.

The ADD command format data can be created using the --records and --machine-output-format options of fetchipac (together).

Note: The whole record is terminated by an empty line. If there is only one sub record, the whole thing end with a line with only a ')' followed by an empty line.

DELETE timestamp

The DELETE command takes exactly one arguement: A timestamp (a decimal number). fetchpipac tries to delete the record with this timestamp from the database. If there is no such record, it prints "ERROR"; otherwise, the deletion is performed and the prompt is displayed again.

LIST START END

START and END are two parameters: Dicimal numbers, representing two timestamps. The operation performed is the same as with the option --timstamps, so see there.

QUIT

Exit.

/etc/ipac-ng/ipac.conf The ipac configuration file. /var/run/ipac.rules ip accounting rule name file. /var/lib/ipac/spool The spool file.

Warning: ipac chains and/or jumps are corrupted. Trying to fix them Some program or human deleted one of ipac's chains or jump rules. This probably means that no traffic was counted by ipac since the deletion. It may be caused by firewall set up scripts. For example, performing ipchains --flush or -F has this effect. fetchipac automatically runs ipacset --fix-chains to fix this condition. See ipacset(8), section BUGS, for details. Sorry, this section is obsolete and needs to be rewritten, just do fetchipac -S no ip firewall / accounting code in the kernel The kernel had been compiled without the ip accounting feature. many more messages Which are meant to speak for themselves.

Resetting accounting data counters on ipchains systems resets all counters; there is no way to reset only ipac's counters. Thus, you probably can't use other ip accounting software together which ipac on the same system. This is not right under iptables system. Also, there are some things (bugs) in ipchains from 2.4.* kernels and using it is no good. (shortly: dont even try to use ipchains with 2.4.* kernels!)

This man page belongs to ipac-ng version 1.31. For updates and other information, look at http://sf.net/projects/ipac-ng

fetchipac is part of ipac since the beginning. It started as a kernel data fetch program only. Until February 2000, it has been a shell script and was then rewritten in C. For ipac 2, it grew a lot, because database access funtions were added and it became the database access program ipacsum(8) uses.

Moritz Both <moritz@daneben.de>

Al Zaharov <kaiser13@mail2000.ru>

ipacsum(8), ipfw(4).