This file explains how to install and configure Captrap, configure pmacct, and
create a database.

Commands are preceded by a '$' if they should be run by a normal user; a '#'
means the command should be run as root (or some other user with sufficient
administrative privileges).


--------------------------------------------------------------------------------
1. Install Captrap.

You can skip this step if you've installed the Debian package already.

Before installing Captrap you'll need to extract the tar.bz2 file. If you're
reading this file, there's a good chance you've already done so. Otherwise, do
something like this:

$ tar jxf captrap-0.8.tar.bz2
$ cd captrap-0.8

First see if you have the necessary Perl dependencies installed.

$ make test

This will attempt to load the necessary modules and list the ones you need to
install. Missing modules should be installed by using your distribution's
package manager, if possible; otherwise, they are available from CPAN. See:
http://www.cpan.org/
http://www.cpan.org/misc/cpan-faq.html#How_install_Perl_modules

Once you can run 'make test' without errors, you may install Captrap, or you
may choose to run Captrap without installing it. Installing Captrap is easy:

$ make
$ su
# make install

Running Captrap without installing it is a tiny bit trickier; see the README
for details. The rest of this document assumes you have installed Captrap, so
you may need to substitute some commands (e.g., "captrap_mkconfig" becomes
"sbin/captrap_mkconfig").


--------------------------------------------------------------------------------
2. Configure Captrap.

# captrap_mkconfig -print | less

Look over the information briefly. This is what will be written to the Captrap
configuration files. For a new installation, all parameters will be either set
to default values or randomly generated (for passwords). You can change any of
the information later, so go ahead and write the files out. Specify the
network interface you want to monitor instead of "eth0".

# captrap_mkconfig -write eth0

The new configuration files are:
/etc/captrap/captrap.conf
/etc/captrap/priv.conf

Some of the default values may not be suitable for your setup. If so, now is a
good time to change the parameters that will be used to generate the database
and the pmacct configuration file. In particular, check and possibly change the
following parameters:
* captrap_host
* interface
* any parameter beginning with "db_"

Once you have edited the Captrap configuration files to your satisfaction, you
can generate a pmacctd configuration file. Skip this step if you already have
pmacctd installed and configured, but, if so, make sure Captrap's "db_*"
configuration parameters match how you have pmacct configured.

# mkdir /etc/pmacct/
# captrap_mkconfig -write-pmacct /etc/pmacct/pmacctd.eth0.conf

The file listed above is an example. You can have pmacct's configuration file
anywhere, as long as you tell pmacctd where the file is (see the "Start
pmacctd" section below).


--------------------------------------------------------------------------------
3. Install pmacct.

Of course, if you have pmacct installed already, skip this section.

If possible, install your distribution's pmacct package (such as "apt-get
install pmacct" on Debian). Otherwise, pmacct may be downloaded from:
http://www.pmacct.net/

Install pmacct according to the pmacct documentation, but don't create a
database yet--Captrap can help you do that now.


--------------------------------------------------------------------------------
4. Create a pmacct database.

Captrap is designed to work with a minimal, stripped-down variation of pmacct's
"version 1" SQL table. If you already have pmacct set up to use a "version 1"
table, that should work, albeit likely with reduced performance--Captrap will
ignore the extra columns, but MySQL will have to do more work summing data
over extra rows if they are present.

Other SQL table versions are untested. Let me know if they work.

Captrap can help you create SQL tables and users. Run the following and see if
it looks OK:

# captrap_mkdb -print

If you already have pmacct set up with a database, you should copy/paste into
your MySQL client the statements for creating the MAC address table and
creating a read-only Captrap user. Otherwise, if the generated SQL statements
look OK, commit them all:

# captrap_mkdb -print | mysql

The command above will fail if you don't have proper privileges for accessing
the MySQL server. You may need to create a ".my.cnf" file for your root user or
use the following command, instead, to manually enter a MySQL password for
root:

# captrap_mkdb -print | mysql -u root -p

If you still have MySQL permissions problems, consult the MySQL documentation
or your favorite search engine. This page may be helpful if you've lost your
MySQL root password:
http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html


--------------------------------------------------------------------------------
5. Start pmacctd.

Pmacctd needs to be told the path to the configuration file you generated
earlier. Debian users should edit "/etc/default/pmacct". Otherwise, pmacctd
needs to be run with a command like this:

# pmacctd -f /etc/pmacct/pmacctd.eth0.conf

Consult your distribution's pmacct package documentation or init script, or run
pmacctd manually. Captrap doesn't care how pmacctd is run, as long as pmacctd
writes to the appropriate database table.


--------------------------------------------------------------------------------
6. Classify MAC addresses.

Pmaact logs data separated according to the destination MAC address. In order
for Captrap to identify traffic as upload/download/broadcast/etc., the MAC
addresses need to be classified as belonging to certain traffic "states". For
example, the MAC address of your ISP's gateway should be set to the "up" state
and the MAC address of the interface on your computer that connects to the ISP
should be set to the "down" state.

Captrap can attempt to automatically detect your local MAC address and the
gateway's MAC address.

# captrap_mac -auto-print

If that worked ok, add those addresses:

# captrap_mac -auto-add

If the automatic method fails, you may add the MAC addresses manually.
The easiest method is to use captrap_mac's interactive terminal.

# captrap_mac -inter

Detailed help is available within the interactive terminal.


--------------------------------------------------------------------------------
6. Test the installation.

At this point, pmacctd should be running and logging statistics to the
database. Captrap should be able to read from the database, so first try
a simple test:

$ captrap_view -write /tmp/test.html "views=basic"

If captrap_view exited without error, examine /tmp/test.html.

Next, test whether graphing works. Substitute start and end times within the
range of data in your database or else the graph will be blank.

$ captrap_graph -write /tmp/test.png \
    "graph=per&per=hour&start=2009-08-12T00:00:00&end=2009-08-13T00:00:00"

The final test is to run a recursive download of all of Captrap's default
pages and graphs. This may take a little while, so the "-v-write" option prints
some information to keep you entertained. Note that the third argument to
captrap_recurse is mandatory, so we specify it to be blank ("").

$ mkdir /tmp/test
$ captrap_recurse -v-write /tmp/test ""

If that worked ok, use a web browser to view /tmp/test/index.html and see if
the generated pages and graphs look correct.

If you've gotten this far, then your Captrap setup is functioning properly.


--------------------------------------------------------------------------------
7. What next?

If you wish to use Captrap's CGI scripts along with a web server, read doc/CGI
and the "SECURITY" section of the README file.

An alternative to using the CGI scripts is to set up a cron job. Read
doc/cron_mode and the "SECURITY" section of the README file.



EOF
