DESCRIPTION

ipacsum is part of the ipac linux ip accounting package.

ipacsum first reads files from the directory /var/lib/ipac. The files in this directory contain ip accounting counter information and are created by
fetchipac(8) on a regular basis or by ipacsum itself (see below). By default, all files are read.

Then, it displays a summary of the data from all these
files. For each ip accounting rule that appears in one of
the input files, it displays a number which represents the
total bytes which have been counted by the rule. For val
ues over 9999 bytes, the count is displayed in KBytes with
a "K" appended (1024 Bytes = 1 KByte). For values over
9999 KBytes, the count is displayed in MBytes with a "M"
appended (1024 KBytes = 1 MByte). For values over 9999
MBytes, the count is displayed in GBytes with a "G"
appended (1024 MBytes = 1 GByte).

Additionally, the host name, the current time and the cre
ation times of the oldest and the newest input files are
printed.

OPTIONS

--starttime, -s time

This selects a set of the input files from the
directory /var/lib/ipac. Only files which are newer than time are read. The time parameter can
have two different formats.

It can be an absolute time in the format YYYYMMD Dhhmmss where YYYY means the year, MM the month, DD
the day of month, hh the hour, mm the minute and ss
the second. Note that the year must have four dig
its!

The absolute time can be abbreviated at any posi
tion; then, the time is recognized as the start of
the respective period. For example, "-s 199805"
means start time is the first of may, 1998, mid
night.

The other form of the time is the relative format. Relative means, back from the current time. It can
be any combination of number-size pairs, where size
is one of the letters s, m, h, D, M and Y, repre
senting a count of seconds, minutes, hours, days,
months or years. For example, "-s 1D" means start
time 24 hours ago; "-s 1Y1s" means start time one
year and one second ago.

Note: In relative times, a month has always 30 and
a year has always 365 days.

--endtime, -e time

This is the pendant to --starttime; only those files from /var/lib/ipac are read which are older than time. The format of time is exactly the same
as with --starttime (see above).

--timeframe, -t timeframe

This sets both start time and end time (see
--starttime and --endtime above) at once. timeframe
is a more or less English time specification. If it
consists of more than one word, it must be places
in quotes. Possible values are "this hour", "last hour", "the hour N hours ago", today, yesterday, "the day before yesterday", "the day N days ago", "this week", "last week", "the week N weeks ago" "this month", "last month", "the month N months ago", "this year", "last year" and "the year N years ago". Replace N with a number.

--filter, -f regex

Filter the set of ip accounting rules that are dis
played by name. Only the rules that match regex are
displayed. regex is a perl style regular expres
sion. See perlre(1) for details.

--fixed-quantity Q

Display byte count values with quantity Q. Q may be
'' (for exact byte count, same as --exact), K, M,
G, or T for KByte, MByte, GByte and TByte. (TByte
is untested... can anybody confirm if it works?)

--graph, -g

After the normal output, print ascii graphs for
each rule. The graph consists of one line per hour
(unless this interval is changed with --interval).
The lines start with the date and time, specifying
the hour. Right of the time, ipacsum prints a num ber of asterisk (*) characters, representing the
relative amount of traffic counted by this rule in
this hour. A header line marks the positions "0"
and the maximum. The maximum is the amount of traf
fic in the hour with the most traffic.

ipacsum can also create much nicer png images. See below.

--interval, -i TIME

With --graph, change the interval for which one
line is printed. The time must be given with any
combination of number-size pairs, where size is one
of s, m, h, D, W, M or Y, representing seconds, minutes, hours, days, weeks, months and years. For
example, "--interval 1D" sets the interval to one
line per day, or "--interval 1W3D" sets it to one
line per 10 days. Beware, there must not appear
white spaces within the TIME string.

--help, -h

Display a help screen.

--replace, -r

After the normal operation, replace all input files
(as specified with --starttime, --endtime and/or
--timeframe) by one single file, containing the
displayed summary. The new file is in the same for
mat as the old input files and can be read with a
later call to ipacsum. The file name is derived from the endtime of the data displayed.

This option is provided to reduce the overhead of
detailed old data in the /var/lib/ipac directory. It sort of "compresses" many detailed data files
into one summary file. Thus, the resolution of fur
ther output of ipacsum will be worse because of the
loss of details, but disk space is saved and ipac
sum runs much faster if it has less input files to
read.

--exact, -x

Do not use KByte, MByte or GByte numbers. Display
the pure byte count. (Same as --fixed-quantity '')

--dir, -d DIR

Override the default accounting file directory
/var/lib/ipac, with DIR.

--show-run-progression

While running, display the total number of files to
be read and a percentage of files already read.
This may slow down ipacsum, because terminal output can be expensive.

--version

Display ipacsum version number and exit.

IMAGE CREATION

ipacsum can create png images for every rule which is dis played (so the --filter option can be used to create only
certain pngs). The png contains a much nicer version of
the ascii graph.

PNG image creation depends on the existence of the perl GD
library. If you do not have the GD library installed,
ipacsum won't be able to create images.

If you only have version 1.19 or older of the GD library,
ipacsum will create GIF images instead of PNG images. Newer GD library versions dumped the GIF support in favor
of PNG due to legal / copyright reasons. All newer
browsers support PNG images, and their use is strongly
encouraged. All options described in this section start
with '--png'; they work the same way if you use the alter
native versions which start with '--gif' instead. There is
no functional difference.

--png [DIR]

Enable png image creation. Images are stored into
the directory DIR; if not given, in the current
directory. The images' file names are derived from
the rule name - unacceptable characters for file
names or for http transfers, such as spaces, are
replaced with underscores ("_"). The images dimen
sions are 500 * 150. The Y axis is scaled in bytes
per second. The input data is divided into inter
vals of exactly one pixel on the X axis.

--png-asis

Instead of creating regular .png files, create
.asis files. .asis files are like .png files, but
with an HTTP header prepended. If you use the
apache HTTP server, you can enable it to directly
send .asis files without generating many HTTP
header lines on its own (see the apache documenta
tion, "mod_asis"). The major advantage is that we
can send HTTP "Expires:" header lines with the png
data, forcing browsers to reload the pictures. The
time given in the Expires: header line is the same
as in the HTTP META tag in the index html file (see
--png-index).

--png-average-curve N

Draw an additional curve with average values for
the N dots around the current one. The resulting
curve shows tendencies rather than exact values.
Can be useful for long-term development evaluation.
A good value for N to start with is 15.

--png-caption-in-index

When generating a html index file (see --png-index
below), add statistical data to each png picture in
the index file as text.

--png-height N

Set the image height to N pixels.

--png-index [FILE]

Create a html index file in the image directory,
containing all images created and some more infor
mation about creation/start/end times, host name
etc. The name of the file is index.html or, if
given, FILE, and it is placed into the png image
directory unless starting with a "/". The index
file will have some META-Tags in the <HEAD> sec
tion. If the end of the time period for which the
data is displayed is the current time, one of them
will be an "Expires" line so www browsers will know
when they should drop the page from their cache.
The time in there is calculated as "now plus the
time one value on the X axis represents".

(To be accurate, the time that appears is now plus
the time given at --interval, given --interval
wasn't smaller than the time one pixel in X direc
tion represents in which case it is the time one
pixel in X direction represents.)

--png-no-average

ipacsum draws a dashed horizontal line indicating the average value in each png picture. Specify this
option to suppress that line.

--png-normalize SEC

This setting changes the scale on the Y axis. The
scale is set to "bytes per SEC seconds". The
default value is 1, resulting in a scale of "bytes
per second". If set to 8, the scale will be "bytes
per 8 seconds" which is in fact the same as "bits
per second" (and the scale label is "bits / sec" in
this special case indeed). Other values are
possible, for example, for a scale of "bytes per
hour", set this to 3600 (60*60).

If set to 0, the Y scale is what you could call
"absolute". The scale factor is now evaluated from
the --interval (see above) setting which defaults
to one hour (resulting in a display of bytes /
hour). The input data is no longer divided into
intervals of exactly one pixel per interval, but
the pixels are divided into n pixels per (constant)
interval. The resulting X,Y value dots in the
matrix are displayed stronger and are connected
with lines.

Does anybody understand this and has an idea how to
explain better?

--png-filename-prefix PREFIX

Prefix every image file name with PREFIX.

--png-total

Put total byte count value - as displayed in the
text output - into image caption (maximum and aver
age values are there anyway).

--png-use-smallfont

Use a smaller font in the image for labels and
scales.

--png-width N

Set the image width to N pixels.

EXAMPLES

To display a summary of accounting data for last month:

% ipacsum --timeframe "last month"

To display a summary of accounting data since midnight
with a graph with one line per hour:

% ipacsum --timeframe today --graph

To display a summary of accounting data for the last ten
days with a graph with one line for each day, and only for
rules containing "isili":

% ipacsum --starttime 10D --graph --interval 1D --filter
isili

To summarize all accounting data of 1997 into one file for
the whole year without displaying anything:

% ipacsum --starttime 1997 --endtime 19971231235959
--replace >/dev/null

or, if we are in 1998:

% ipacsum --timeframe "last year" --replace >/dev/null

To create png graph images of all rules for the last month
in the directory /tmp, including a html file called
"index.html" to display them all at once in a web browser:

% ipacsum --timeframe "last month" --png /tmp --png-index

FILES

/var/lib/ipac

The default accounting file directory, mostly fed
by fetchipac(8).

BUGS

The graph printing function (--graph) doesn't work very
well and the output is ugly. Use --png instead.

VERSION

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

AUTHOR

Moritz Both <moritz@daneben.de> Al Zaharov
<kaiser13@mail2000.ru>

SEE ALSO

fetchipac(8), perlre(1).

Linux SEPTEMBER 2001 IPACSUM(8)