broadband-usage-log - Home broadband usage meter for SNMP-enabled modem/routers


 usage: broadband-usage-log [options]
  -h           - Print this message then exit.
  -V           - Print the version then exit.
  -M           - Print the manpage then exit
  -W           - Print the manpage in html format then exit
  -R           - Print the manpage in nroff format then exit
  -l /logdir   - Override log directory (default: /var/log/broadband)
  -s snmpget   - Override snmpget path (default: snmpget)
  -v (1|2c|3)  - Override SNMP version (default: 1)
  -c community - Override SNMP community (default: public)
  -r router    - Override modem/router hostname (default: router)
  -i #[,#]*    - Override the interface number(s) (default: 1)
  -w           - Fetch 64-bit byte counters (rather than 32-bit ones)


This program collects modem/router statistics and logs them to file. Create the log directory /var/log/broadband (owned by you). Cron this to run every 5-15 minutes and at 23:59:59 every night. Then use broadband-usage(1) later to report the logged statistics. WARNING: Don't switch between 32- and 64-bit counters in the same file.


Some data is lost when the modem/router is rebooted. Extrapolation can be done by broadband-usage to estimate the missing data. If this is a problem, run broadband-usage-log every 5 minutes to reduce the inaccuracy. If you do this, the log files will be 3 times larger so cronning a job to delete/compress old ones becomes more important:

 0 0 1 * * find /var/log/broadband -mtime +32 -a -name '*[0-9]' -exec gzip '{}' ';'
 0 0 1 * * find /var/log/broadband -mtime +92 -a -name '*.gz' -exec rm '{}' ';'

The host running broadband-usage-log needs to be up. Preferably all the time. This isn't really a bug might it might be a problem for some people. If the monitoring host is shut down, and then other hosts start using the broadband connection, and then the modem/router is rebooted, and then the monitoring host is booted, then the results will exclude traffic that occurred between the time that the the monitoring host was shut down and the time when the the modem/router was rebooted. So don't do that.

Similarly, multiple rapid reboots of the modem/router will result in the exclusion of traffic that occurs between the reboots. So don't do that either.

Similarly, data is lost if byte counters overflow multiple times before the next time that broadband-usage-log runs. Fortunately, this is unlikely to be a problem for broadband usage provided that broadband-usage-log is run frequently enough.

Here are some figures on how often 32-bit byte counters can overflow on network links of different speeds:

 Link Speed     Minumum overflow interval  Sample frequency
 -------------- -------------------------  ----------------
 ADSL   256kbps  37.28 hours               15 minutes
 ADSL   512kbps  18.64 hours               15 minutes
 ADSL  1500kbps   6.36 hours               15 minutes
 Cable    5Mbps   1.91 hours               15 minutes
 ADSL2    8Mbps   1.19 hours               15 minutes
 LAN     10Mbps  57.26 minutes             15 minutes
 ADSL2+  24Mbps  23.86 minutes             5 minutes
 LAN    100Mbps   5.73 minutes             1-2 minutes
 LAN      1Gbps     34 seconds             Use 64-bit counters

By the way, modem/router uptime timestamps overflow every 1.36 years.

But don't worry. broadband-usage copes with occasional modem/router reboots and the uptime and/or byte counters overflowing once between samples (even if they both overflow in the same period between samples). It's only multiple overflows between samples that are a problem. So don't let that happen.


Here is the broadband-usage-related part of my crontab:

 # Log broadband usage every 15 minutes and at 23:59:59 every day
 0,15,30,45 * * * * /usr/local/bin/broadband-usage-log -r moriarty -i 2
 59 23 * * * sleep 59; /usr/local/bin/broadband-usage-log -r moriarty -i 2
 # Save broadband usage report into the broadband log directory
 5 0 1 * * /usr/local/bin/broadband-usage -o 0100-1000 > /var/log/broadband/`date +%Y%m%d`-usage
 # Compress broadband usage logs after a month, delete them after three months
 1 0 1 * * find /var/log/broadband -mtime +32 -a -name '*[0-9]' -exec gzip '{}' ';'
 1 0 1 * * find /var/log/broadband -mtime +92 -a -name '*.gz' -exec rm '{}' ';'




20060122 raf <>