PPPUSAGE(1)

📦 version 0.2.5, in arch rolling

💅 PPPUSAGE(1) — like, the manual page, bestie

okay so real talk: this is PPUSAGE(1), section 1 of the manual, and it comes to you courtesy of User Contributed Perl Documentation. Yes, Perl. We stan a legacy icon. 🐪✨

✨ NAME ✨

pppusage — generates PPP connection summaries. That's the whole gig. 🎀

🌸 SYNOPSIS 🌸

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

pppusage [-hv]

Like, that's the shape of it. Flags, maybe a datafile, maybe a time range, maybe some logfiles. Very choose-your-own-adventure. 🦋

💖 DESCRIPTION 💖

So pppusage summarizes average and total transfer volumes, number of connections, and average and total online time for all the logged PPP connections. It's giving accountant but make it dial-up. 😌

Where does the data come from? It reads the logfiles that contain the ppp[d] messages. That's the source of truth, periodt.

And here's the cute part: you can feed it multiple logfiles — like the active one and the rotated ppp[d] logfiles — so that new ppp[d] entries don't get missed when the relevant logfile gets rotated before pppusage has seen them. Chef's kiss. 🫶

⚠️ but bestie, please go read "CAVEATS" below before you get too excited about that multiple-logfile thing. It's lowkey a trap.

pppusage saves the relevant data in datafile (a Berkeley DB database), and you can keep that updated automatically on a regular basis by using cron(5) or something similar. Set it and forget it, icon behavior. 👑

🎀 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. One little overachiever. 💅

But 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. No sparkle. Monochrome era. 🖤
  • -c — parse the PPP syslog files, update the Berkeley DB database file (or create it, if it doesn't exist), and exit. This one is especially useful if you want the database updated automatically in the background on a regular basis. Like this:
05 14 * * * nice /usr/bin/core_perl/pppusage -c > /dev/null

That crontab(5) entry would update the database once a day (at 2:05 pm). 2:05 pm specifically. We respect the schedule. ⏰

  • -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. Everything. The whole buffet. 🍓
  • -h — print out a quick overview of all available options and exit. Your little helper bestie. 🙈
  • -t yyyy[mm[dd]][-<yyyy>[mm[dd]]] — specify the time period for a query. You can do it 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 — no clock-watching here. 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. Yes, a perl file. It's giving old money. 💜

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. Command line stays winning. 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`! This is not a drill, bestie, I cannot stress this enough. 😭
  • $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). Like, protect your data, queen. 🛡️
  • $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. It's giving legacy baggage. 💀

🧚 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. The full package. ✨

pppusage -t 2003

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

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. Q1 slay. 🔥

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. Minimalist moment. 🖤

🗂️ FILES 🗂️

  • ~/.pppusagerc — user configuration file. Your personal vibe file. 💖
  • /etc/pppusagerc — system-wide configuration file. The communal vibe file. 👑

⚠️ CAVEATS ⚠️

okay bestie, sit down, this is the serious part. 🙈

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. Sorting by mtime is not the girlboss move it thinks it is. 💀

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. Double 💀.

In both cases the database file must be deleted and recreated. No shortcuts, no workarounds. Recreate it. 🚨

💀 BUGS 💀

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

🔗 SEE ALSO 🔗

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

👑 AUTHOR 👑

Holger Weiss <holger@jhweiss.de>

and that's the whole page, bestie 💜 — brought to you by perl v5.42.0, dated 2025-12-14, and lovingly stamped PPUSAGE(1) at the top and bottom like a little bow 🎀 go forth and summarize your PPP connections, no cap ✨

📦 where this page comes from