"Cron mode" is a feature of the captrap_recurse script intended to be run
periodically by the cron daemon.

When run in "cron mode", captrap_recurse will generate a full set of files into
a directory and then create a symlink to that directory. The next time
captrap_recurse is run, a new set of files is generated and the symlink is
changed to point to the new directory; the directory previously pointed to by
the symlink is removed.


--------------------------------------------------------------------------------
1. Create/choose a local user.

captrap_recurse need not be run as root (so don't do it). The user needs only
read access to /etc/captrap/captrap.conf and write access to an area where you
want to store the files.

If you're using the Debian package, you should already have a "captrap" user.
Otherwise, create a new "captrap" user if you want to:

# util/adduser.sh

Now would be a good time to set up an alias for the new user's mail, if you
want to. Check /etc/aliases.

The rest of these instructions should be run as that user, so switch users now:

# su captrap -s /bin/bash


--------------------------------------------------------------------------------
2. Create directories.

If you just created a new captrap user and can store the files in the user's
home directory (/var/lib/captrap/static), then skip this step. If you're using
another user or location, then follow this step and alter the provided commands
accordingly.

The directory in which the files will be stored must be created first. For
example:

$ mkdir /var/www/captrap

Likewise, create the directory to hold the symlink (if it's different from the
other directory).

It is very important that the directory holding the symlink be writable only by
the "captrap" user--otherwise, a malicious local user may point the symlink to
an arbitrary location and cause captrap_recurse to remove files it shouldn't.
The script makes an effort to detect this and prevent any harm, but don't
depend on it protecting you. Protect the directory instead.

--------------------------------------------------------------------------------
3. Test.

Run captrap_recurse configured to round down to the most recent hour; it may
take a little while. If you aren't writing to the user's home directory,
replace the ~ and ~/current with the paths you want to use.

$ captrap_recurse -cron-write ~ ~/current hour
$ ls -l ~

You should see a directory named with the date/time and a symlink to that
directory.


--------------------------------------------------------------------------------
4. Edit user crontab.

This example shows how to run captrap_recurse 5 minutes after every hour (which
gives pmacct time to finish up writing data for the previous hour).

$ crontab -e

Now put the following two lines in the file:

PATH = /usr/local/bin:/usr/bin/:/bin
5 * * * *  captrap_recurse -cron-write "$HOME" "$HOME/current" hour

The first line is needed unless you already have Captrap installed in part of
the PATH cron is configured to use. Users of the Debian package may omit it.

If you wish to use cron mode without having Captrap installed, edit the wrapper
script util/captrap_cron.sh and use that in your crontab instead.

You'll have to wait up to an hour to see if it works. If it doesn't, check the
local user's mail to see any errors.

Meanwhile, you can work on the next step.


--------------------------------------------------------------------------------
5. Set up a web page.

This step is optional, but it's most useful to have the Captrap pages hosted on
a web server. If you want to, configure your web server to have a directory
alias to the symlink created by captrap_recurse.

Here is an example configuration for Apache 2.2:

        Alias /ct-static /var/lib/captrap/static/current
        <Directory "/var/lib/captrap/static/current">
                DirectoryIndex index.html
                Options SymLinksIfOwnerMatch
                Order Allow,Deny
                Allow from all
        </Directory>

Put those lines in an Apache configuration file, such as
/etc/apache2/sites-enabled/000-default. Then restart your web server and test
http://your-server/ct-static/. Watch your Apache error log.


EOF
