.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PPPUSAGE 1" .TH PPPUSAGE 1 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME pppusage \- generate PPP connection summaries .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBpppusage\fR [\fB\-bcq\fR] [\fB\-f\fR\ \fIdatafile\fR] [\fB\-t\fR\ \fIyyyy\fR[\fImm\fR[\fIdd\fR]][\-\fIyyyy\fR[\fImm\fR[\fIdd\fR]]]] [\fIlogfile\fR...] .PP \&\fBpppusage\fR [\fB\-hv\fR] .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBpppusage\fR 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 \fIlogfile\fRs which contain the ppp[d] messages. Multiple \fIlogfile\fRs (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 \fBpppusage\fR has seen the entries. However, please see "CAVEATS" below! \fBpppusage\fR saves the relevant data in \fIdatafile\fR (a Berkeley DB database) which can be updated automatically on a regular basis by using \fR\f(BIcron\fR\fI\|(5)\fR or something similar. .SH OPTIONS .IX Header "OPTIONS" By default, \fBpppusage\fR 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. .IP \fB\-b\fR 6 .IX Item "-b" Don't use ANSI colors and attributes for the \fBpppusage\fR output. .IP \fB\-c\fR 6 .IX Item "-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: .Sp .Vb 1 \& 05 14 * * * nice /usr/bin/core_perl/pppusage \-c > /dev/null .Ve .Sp This \fR\f(BIcrontab\fR\fI\|(5)\fR entry would update the database once a day (at 2:05 pm). .IP "\fB\-f\fR \fIdatafile\fR" 6 .IX Item "-f datafile" Specify the database file that should be used by \fBpppusage\fR. .IP \fB\-q\fR 6 .IX Item "-q" Query the database: Read the database file and spit out summaries. If the time range is not specified with \fB\-t\fR, all available data will be processed. .IP \fB\-h\fR 6 .IX Item "-h" Print out a quick overview of all available options and exit. .IP "\fB\-t\fR \fIyyyy\fR[\fImm\fR[\fIdd\fR]][\-[\fImm\fR[\fIdd\fR]]]" 6 .IX Item "-t yyyy[mm[dd]][-[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 \fB\-q\fR. .IP \fB\-v\fR 6 .IX Item "-v" Print version information and exit. .SH CONFIGURATION .IX Header "CONFIGURATION" The configuration file used by \fBpppusage\fR 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. .ie n .IP "\fR\fB$logfiles\fR\fB\fR = \fI'logfile...'\fR; [`ls /var/log/messages*`]" 6 .el .IP "\fR\f(CB$logfiles\fR\fB\fR = \fI'logfile...'\fR; [`ls /var/log/messages*`]" 6 .IX Item "$logfiles = 'logfile...'; [`ls /var/log/messages*`]" The ppp[d] \fBlogfile\fRs 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`! .ie n .IP "\fR\fB$datafile\fR\fB\fR = \fI'datafile'\fR; ['/tmp/pppusage.db']" 6 .el .IP "\fR\f(CB$datafile\fR\fB\fR = \fI'datafile'\fR; ['/tmp/pppusage.db']" 6 .IX Item "$datafile = 'datafile'; ['/tmp/pppusage.db']" The file that is used by \fBpppusage\fR 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 \fBcron\fR\|(5) job or on boot). .ie n .IP "\fR\fB$configured\fR\fB\fR = \fI0|1\fR; [0]" 6 .el .IP "\fR\f(CB$configured\fR\fB\fR = \fI0|1\fR; [0]" 6 .IX Item "$configured = 0|1; [0]" Forget about this one. We needed it to make sure that those of you who upgraded from older releases of \fBpppusage\fR have set \fR\f(CB$logfiles\fR\fB\fR correctly by forcing them to open the configuration file and setting \&\fB\fR\f(CB$configured\fR\fB\fR to 1 ;\-) Actually, you can simply delete this variable completely. It will be removed from future releases of \fBpppusage\fR. .SH EXAMPLES .IX Header "EXAMPLES" .Vb 1 \& pppusage .Ve .PP 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. .PP .Vb 1 \& pppusage \-t 2003 .Ve .PP Searches the database file for all PPP connections logged in 2003 and writes the results to STDOUT. .PP .Vb 1 \& pppusage \-t 200305 .Ve .PP Searches the database file for all PPP connections logged in May 2003 and writes the results to STDOUT. .PP .Vb 1 \& pppusage \-t 2003\-200303 .Ve .PP Searches the database file for all PPP connections logged in the first quarter of 2003 and writes the results to STDOUT. .PP .Vb 1 \& pppusage \-t 20030915\-20030931 .Ve .PP Searches the database file for all PPP connections logged in the second half of September 2003 and writes the results to STDOUT. .PP .Vb 1 \& pppusage \-b \-f /tmp/pppusage.2002.db \-t 20020501 .Ve .PP 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. .SH FILES .IX Header "FILES" \&\fI~/.pppusagerc\fR User configuration file. .PP \&\fI/etc/pppusagerc\fR System-wide configuration file. .SH CAVEATS .IX Header "CAVEATS" Since \fBpppusage\fR tries to get multiple logfiles in the right order simply by sorting them by their last modification time, feeding multiple logfiles to \fBpppusage\fR will most probably produce a broken database if they were modified after they have been rotated. .PP Even worse: Updating an \fIexisting\fR database with logfiles that contain data which is \fIolder\fR than the already parsed data won't work either. This would again result in a broken database. .PP In both cases the database file must be deleted and recreated. .SH BUGS .IX Header "BUGS" Most probably, there are some. Please let me know if you find them! .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBppp\fR\|(8), \fBpppd\fR\|(8), \fBsyslog\fR\|(8), \fBsyslog.conf\fR\|(5), \fBcron\fR\|(5), \fBcrontab\fR\|(1), \fBcrontab\fR\|(5) .SH AUTHOR .IX Header "AUTHOR" Holger Weiss