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