Penguin
Recent Changes
Annotated edit history of ipacsum(8) version 4, including all changes. View license author blame.
Rev Author # Line
1 CraigBox 1 !!NAME
2
3 ipacsum - summarize, display and compact ip accounting information
4
5 !!SYNOPSIS
6
7 __ipacsum [[ --debug dbopt ] [[ --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 ]__
8
9 !!DESCRIPTION
10 ipacsum is part of the ipac linux ip accounting package.
11
12 ipacsum first reads files from the directory /var/log/ip-acct. 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.
13
14 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).
15
16 Additionally, the host name, the current time and the creation times of the oldest and the newest input files are printed.
17
18 !!OPTIONS
19
20 ; --starttime, -s time : This selects a set of the input files from the directory /var/log/ip-acct. Only files which are newer than time are read. The time parameter can have two different formats.
21
22 ;: 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!
23
24 ;: 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.
25
26 ;: 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.
27
28 ;: Note: In relative times, a month has always 30 and a year has always 365 days.
29
30 ; __--endtime, -e time__ : This is the pendant to --starttime; only those files from /var/log/ip-acct are read which are older than time. The format of time is exactly the same as with --starttime (see above).
31 ; __--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.
32 ; __--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.
33 ; __--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?)
34 ; __--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.
35 ; __--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.
36 ; __--help, -h__ : Display a help screen.
37 ; __--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/log/ip-acct 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.
38 ; __--exact, -x__ : Do not use KByte, MByte or GByte numbers. Display the pure byte count. (Same as --fixed-quantity '')
39 ; __--debug dbopt__ : This option is available only if debugging codes wasn't stripped out of ipacsum during installation. See section DEBUGGING below.
40 ; __--dir, -d DIR__ : Override the default accounting file directory /var/log/ip-acct, with DIR.
41 ; __--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.
42 ; __--version__ : Display ipacsum version number and exit.
43
44
45 !IMAGE CREATION
46
47 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.
48
49 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.
50
51 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.
52
53 ; __--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.
54
55 ;: Also create an 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 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".
56
57 ;: (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.)
58 ; __--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).
59 ; __--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.
60 ; __--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.
61 ; __--png-height N__: Set the image height to N pixels.
62 ; __--png-index FILE__: Choose a different name for the html index file which is created. If the name is /dev/null, no index file is created.
63 ; __--png-no-average__: ipacsum draws a dashed horizontal line indicating the average value in each png picture. Specify this option to suppress that line.
64 ; __--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).
65
66 ;: 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.
67
68 ;: Does anybody understand this and has an idea how to explain better?
69 ; __--png-filename-prefix PREFIX__: Prefix every image file name with PREFIX.
70 ; __--png-total__: Put total byte count value - as displayed in the text output - into image caption (maximum and average values are there anyway).
71 ; __--png-use-smallfont__: Use a smaller font in the image for labels and scales.
72 ; __--png-width N__: Set the image width to N pixels.
73
74
75 !!EXAMPLES
76
77 To display a summary of accounting data for last month:
78
79 % ipacsum --timeframe "last month"
80
81 To display a summary of accounting data since midnight with a graph with one line per hour:
82
83 % ipacsum --timeframe today --graph
84
85 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":
86
87 % ipacsum --starttime 10D --graph --interval 1D --filter isili
88
89 To summarize all accounting data of 1997 into one file for the whole year without displaying anything:
90
91 % ipacsum --starttime 1997 --endtime 19971231235959 --replace >/dev/null
92
93 or, if we are in 1998:
94
95 % ipacsum --timeframe "last year" --replace >/dev/null
96
97 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:
98
99 % ipacsum --timeframe "last month" --png /tmp --png-index
100
101
102 !!FILES
103
104 ; __/var/log/ip-acct__ : The default accounting file directory, mostly fed by fetchipac(8).
105
106
107 !!BUGS
108
109 The graph printing function (--graph) doesn't work very well and the output is ugly. Use --png instead.
110
111 !!DEBUGGING
112
113 ipacsum understands an option "--debug dbopt" if the debugging code wasn't stripped out during installation. The dbopt argument can be one or more of the following items, separated by space, which each switch on one debugging option. If you want to switch on more than one, put the list into double quotes. All debugging options produce output on stdout.
114
115 ; __files_to_read__ : Prints a list of all data files ipacsum reads
116
117
118 !!VERSION
119
4 ChristianSchlack 120 This man page belongs to ipac version 1.10. For updates and other information, look at http://www.daneben.de/ipac.html
1 CraigBox 121
122 !!AUTHOR
2 CraigBox 123 [Moritz Both|mailto:moritz@daneben.de]
1 CraigBox 124
125 !!SEE ALSO
126 fetchipac(8), ipacset(8), perlre(1).
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.