ipacsum - summarize, display and compact ip accounting information

ipacsum [ --dir, -d DIR ] [ --endtime, -e time ] [ --exact, -x ] [ --filter, -f regex ] [ --fixed-quantity Q ] [ --png DIR ] [ --png-asis ] [ --png-average-curve N ] [ --png-caption-in-index ] [ --png-height N ] [ --png-index FILE ] [ --png-no-average ] [ --png-normalize SEC ] [ --png-filename-prefix PREFIX ] [ --png-total ] [ --png-use-smallfont ] [ --png-width N ] [ --graph, -g ] [ --help, -h ] [ --interval, -i n ] [ --replace, -r ] [ --show-run-progression ] [ --starttime, -s time ] [ --timeframe, -t timeframe ] [ --version ]

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 values 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 creation times of the oldest and the newest input files are printed.

--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 YYYYMMDDhhmmss 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 digits!

The absolute time can be abbreviated at any position; 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, midnight.

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, representing 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 "thishour""", "lasthour""", "thehourNhoursago""", today, yesterday, "thedaybeforeyesterday""", "thedayNdaysago""", "thisweek""", "lastweek""", "theweekNweeksago""" "thismonth""", "lastmonth""", "themonthNmonthsago""", "thisyear""", "lastyear""" and "theyearNyearsago""". Replace N with a number.

--filter, -f regex

Filter the set of ip accounting rules that are displayed by name. Only the rules that match regex are displayed. regex is a perl style regular expression. 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 number 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 traffic 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 format 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 further output of ipacsum will be worse because of the loss of details, but disk space is saved and ipacsum 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.

ipacsum can create png images for every rule which is displayed (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 alternative 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 dimensions are 500 * 150. The Y axis is scaled in bytes per second. The input data is divided into intervals 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 documentation, "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 information 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> section. 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 direction 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 average 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.

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

/var/lib/ipac The default accounting file directory, mostly fed by fetchipac(8).

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

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

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

fetchipac(8), perlre(1).