fetchipac(8)
NAME
fetchipac - ip accounting kernel data and database handler
SYNOPSIS
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|--ver bose ]
DESCRIPTION
fetchipac is part of the ipac-ng linux ip accounting pack
age.
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 meth
ods provided are: gdbm plain-file . The default storage
method used is gdbm. 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.)
NORMAL OPERATION
When fetchipac is called without any arguments, it fetches
kernel ip accounting data.
To do this, it first runs through a lock mechanism to pre
vent 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 (ker
nel 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.
SPOOL MECHANISM
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 unreach
able. 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 con
tents of the spool file is copied into the database and
the spool file is removed.
COMMON OPTIONS
- -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
OPTIONS USED INTERNALLY AND FOR DEBUGGING
- -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 dis
carded. 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.
BATCH MODE
When fetchipac is in batch mode (option --batch), it rec
ognizes 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 repre
senting the timestamp of the record, followed by a
space character, followed by a decimal number rep
resenting the number of sub records that will fol
low, followed by a newline character, followed by
the individual sub records, followed by a newline
character. - A sub record consists of the character '(', fol
lowed by a space character, followed by a host name
representing the machine where the data was mea
sured, 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 per
formed is the same as with the option --timstamps, so see there. - QUIT Exit.
FILES
- /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.
DIAGNOSTICS
- 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.
BUGS
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!)
VERSION
This man page belongs to ipac-ng version 1.31. For
updates and other information, look at http://sf.net/pro
jects/ipac-ng
HISTORY
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 fun
tions were added and it became the database access program
ipacsum(8) uses.
AUTHORS
Moritz Both <moritz@daneben.de>
Al Zaharov <kaiser13@mail2000.ru>