DESCRIPTION

Captrap is a set of Perl scripts designed to work with the pmacctd network
traffic accounting daemon. Pmacctd logs traffic statistics to a MySQL database,
and Captrap fetches those data and generates tables and graphs.

Captrap is intended for users in situations like these:
1. A home user's ISP has imposed a monthly or daily cap.
2. A web site administrator gets charged extra for traffic above a limit.

The graphs produced by Captrap can be useful for determining whether a cap will
be overrun based on recent usage data.


FEATURES

* simple yearly/monthly/daily/hourly graphs
* moving-total graphs
* predicted moving-total graphs
* classification of MAC addresses into upload/download/broadcast, etc.
* ability to ignore specified MAC addresses
* scripts may be installed or run from source directory
* CGI scripts for live statistics (updated as frequently as pmacctd logs data)
* "cron mode" for generating a full set of web pages and graphs periodically
* lots of helper scripts to ease configuration
* after the setup, doesn't require root or any special privileges
* no dependency on complex web frameworks


HOME PAGE

Captrap source and a demo may be found at:
http://fatooh.org/captrap/


INSTALLING

Read the INSTALL document for details. A simple 'make install' may install the
scripts, but further configuration is needed in order to use them.


RUNNING WITHOUT INSTALLING

Sometimes it can be nice to avoid installing random programs to /usr/local.
Captrap is designed so that it can be run from the source directory. Just
follow these steps:

1. Create a /etc/captrap/ directory.
2. Whenever running a Captrap script, first cd to the root of the Captrap
   source, then run the script with its relative path. For example:
   $ sbin/captrap_mkconfig
   The command-line scripts live in sbin/ and bin/.

There are a couple other steps for running Captrap's CGI scripts or "cron
mode". See doc/CGI and doc/cron_mode for details.

Otherwise, configuration is the same, so read the INSTALL document and proceed.

Man pages are built from POD documentation in the source files; if you wish to
view them, run 'make man' (or just 'make') within the Captrap source directory.
The man pages are built in the build/man/ directory. You can view them like
this:

$ man -l build/man/captrap_mkconfig.8pm


SECURITY

Running Captrap as a CGI program raises a few security considerations, mostly
with respect to slow MySQL queries and denial of service attacks. It is easy
for a user to craft a set of graph parameters for which the MySQL server will
take a while to fetch data. There are ways to mitigate this (including, but
not limited to, writing faster SQL queries), and they may be included in future
versions of Captrap. For now, however, the safest way to use Captrap is to
avoid using the CGI programs on a publicly-accessible website. The doc/CGI file
has examples of setting up the CGI scripts with host-based security; you may
use any other access control mechanism if you like.

It is fairly easy to set up Captrap to periodically generate a full set of
files that can safely be made available to the public. The captrap_recurse
script provides a "cron mode" specifically suited for this purpose. Consult
doc/cron_mode for instructions. As a security note, be sure to set up cron mode
to create the symlink in a directory that is not writable by other users. This
is explained further in the cron_mode document, and if you follow the
instructions this will not happen.


BUGS

* Graphs have a 1-pixel wide colored "shadow" along the top and right edges.
  This is actually a gnuplot bug that I reported on 2009-06-10. The fix is in
  CVS and should end up in gnuplot 4.4.rc1. I've tested CVS from 2009-09-03,
  and it seems to work fine with Captrap. So does the latest CVS snapshot:
  http://www.gnuplot.info/development/binaries/gnuplot-4.3.0-2009-07-08.tar.gz
  If you don't want to install gnuplot CVS system-wide, you can specify an
  alternate gnuplot binary with the "gnuplot" configuration item.



EOF