pppusage version 0.2.5
======================


OVERVIEW
--------

pppusage summarizes PPP transfer volumes, number of connections and
online time. The data is collected by reading the syslog files which
contain the ppp[d] messages. A database file is used to store the
relevant data, thus it doesn't get lost when your ppp[d] logfiles are
rotated or deleted. Certain time ranges (that is: a year, month, or day)
may be specified on the command line. pppusage should run on Linux
systems with pppd(8) aswell as on NetBSD, FreeBSD or OpenBSD with ppp(8)
(known as user-ppp). It's written in Perl (tested with Perl 5.6.1), but
no non-standard Perl modules are required.


INSTALLATION
------------

See the file INSTALL for installation instructions, see the file UPGRADE
if you are upgrading pppusage, especially if you are upgrading on Linux
from a release prior to 0.2.2.


CONFIGURATION
-------------

There are two things to configure: The PPP logfiles that should be read
and the database file pppusage should use to store it's data in. The
configuration is done in /usr/local/etc/pppusagerc (on BSD) or in
/etc/pppusagerc (on Linux).

1. PPP logfiles

On most Linux systems, the PPP data is written to /var/log/messages. If
that's the case on your system, the default settings should be okay. If
not, you must adjust the variable $logfiles in your pppusagerc. In this
case, please make sure to not only specify one file but also the file
names of the rotated archives in order to make sure that pppusage
doesn't miss any ppp[d] messages! This can be done by using a space
delimited list of files, for example:

   $logfiles = "/var/log/syslog /var/log/syslog.0.gz";

NOTE: pppusage tries to get them in the right order simply by sorting
them by their last modification time. Therefore, if the rotated logfiles
are modified after they are rotated, pppusage will produce a broken
database! Note also that _updating_ an existing database with _old_
logfiles that were _not_ parsed before won't work either. See the
section on `CAVEATS' in the man page.

However, on some BSD systems the PPP data by default doesn't get logged
at all. If you are an BSD, the following commands will give you a
/var/log/ppp.log:

   su root -c csh
   cp /etc/syslog.conf /etc/syslog.conf.bak
   printf '\n\!ppp\n*.*\t/var/log/ppp.log\n' >> /etc/syslog.conf
   touch /var/log/ppp.log
   kill -HUP `cat /var/run/syslog.pid`

2. database file

The second thing that you can adjust is which file pppusage should use
to store it's data. By default it will use /tmp/pppusage.db, which is
probably not what you want (especially not if your /tmp gets wiped out
automatically every now and then). Change the variable `$datafile' in
your pppusagerc to specify a different path.


USAGE
-----

As soon as there is some connection summary data in your PPP logfile(s),
you can build the pppusage database and get some statistics by simply
running pppusage. If you want to build the pppusage database twice a day
automatically, you could use a crontab(5) entry like the following:

   05 2,14 * * * nice /usr/local/bin/pppusage -c > /dev/null

You can then query the database with -q. If you want to specify a
timerange, use -t. See pppusage -h for a quick overview of the available
options, see the man page pppusage(1) for detailed information.


LICENSE
-------

The license is BSD style, see the file License.


AUTHOR
------

The most recent version of pppusage can be found on:

   http://code.jhweiss.de/pppusage/

Please send comments and bug-reports to:

   Holger Weiss <holger@jhweiss.de>
