PPPUSAGE(1)

NAME
pppusage - generate PPP connection summaries

SYNOPSIS
pppusage [-bcq] [-f datafile] [-t yyyy[mm[dd]][-yyyy[mm[dd]]]] [logfile...]

pppusage [-hv]

DESCRIPTION
pppusage summarizes average and total transfer volumes, number of connections and average and total online time for all logged PPP connections. The data is collected by reading the logfiles which contain the ppp[d] messages. Multiple logfiles (that is, the active and the rotated ppp[d] logfiles) can be read in order to make sure that new ppp[d] entries aren't missed when the relevant logfile gets rotated before pppusage has seen the entries. However, please see "CAVEATS" below! pppusage saves the relevant data in datafile (a Berkeley DB database) which can be updated automatically on a regular basis by using cron(5) or something similar.

OPTIONS
By default, pppusage does all four steps: It parses the PPP syslog files, saves the data, reads the saved data and spits out the summaries for all available data. You can split up building the database on the one hand and querying it on the other by using some of the following options.

-b  Don't use ANSI colors and attributes for the pppusage output.

-c  Parse the PPP syslog files, update the Berkeley DB database file (or create it, if it doesn't exist), and exit. This option is especially useful if you want the database updated automatically in the background on a regular basis. For example:

       05 14 * * * nice /usr/bin/core_perl/pppusage -c > /dev/null

    This crontab(5) entry would update the database once a day (at 2:05 pm).

-f datafile
    Specify the database file that should be used by pppusage.

-q  Query the database: Read the database file and spit out summaries. If the time range is not specified with -t, all available data will be processed.

-h  Print out a quick overview of all available options and exit.

-t yyyy[mm[dd]][-<yyyy>[mm[dd]]]
    Specify the time period for a query. This can be done either by specifying a single year, month or day, or by specifying a time range. A time range is used by specifying two dates, seperated with a `-'. The order in which the two dates are given is irrelevant. Any combination of days, months or years may be specified. Implies -q.

-v  Print version information and exit.

CONFIGURATION
The configuration file used by pppusage simply is a perl file that is read on startup. Both the logfiles to parse and the database file to use may be adjusted by setting the following variables. However, specifying them on the command line will overwrite these settings. The default values are shown in brackets.

$logfiles = 'logfile...';  [`ls /var/log/messages*`]
    The ppp[d] logfiles to parse. A space delimited list must be used to specify multiple files. Note that if you specify the files to parse directly (as opposed to using the output of a command like ls), you must use normal "quotation marks", not `backticks`!

$datafile = 'datafile';    ['/tmp/pppusage.db']
    The file that is used by pppusage to store it's data. Normally it makes sense to set this to a different path, especially if the /tmp directory gets wiped out every now an then (by, for example, a cron(5) job or on boot).

$configured = 0|1;         [0]
    Forget about this one. We needed it to make sure that those of you who upgraded from older releases of pppusage have set $logfiles correctly by forcing them to open the configuration file and setting $configured to 1 ;-) Actually, you can simply delete this variable completely. It will be removed from future releases of pppusage.

EXAMPLES
    pppusage

Parses the syslog files that ppp[d] logs it's messages to, saves the relevant data to a Berkeley DB file and writes summaries regarding all available data to STDOUT.

    pppusage -t 2003

Searches the database file for all PPP connections logged in 2003 and writes the results to STDOUT.

    pppusage -t 200305

Searches the database file for all PPP connections logged in May 2003 and writes the results to STDOUT.

    pppusage -t 2003-200303

Searches the database file for all PPP connections logged in the first quarter of 2003 and writes the results to STDOUT.

    pppusage -t 20030915-20030931

Searches the database file for all PPP connections logged in the second half of September 2003 and writes the results to STDOUT.

    pppusage -b -f /tmp/pppusage.2002.db -t 20020501

Searches the database file /tmp/pppusage.2002.db for all PPP connections logged at May 1st, 2002 and spits out the results without using any ANSI colors or attributes.

FILES
~/.pppusagerc
    User configuration file.

/etc/pppusagerc
    System-wide configuration file.

CAVEATS
Since pppusage tries to get multiple logfiles in the right order simply by sorting them by their last modification time, feeding multiple logfiles to pppusage will most probably produce a broken database if they were modified after they have been rotated.

Even worse: Updating an existing database with logfiles that contain data which is older than the already parsed data won't work either. This would again result in a broken database.

In both cases the database file must be deleted and recreated.

BUGS
Most probably, there are some. Please let me know if you find them!

SEE ALSO
ppp(8), pppd(8), syslog(8), syslog.conf(5), cron(5), crontab(1), crontab(5)

AUTHOR
Holger Weiss <holger@jhweiss.de>