DESCRIPTION

pop-before-smtp watches your mail log file (e.g. /var/log/mail.log) for lines
written by your POP/IMAP software (e.g. UW popd/imapd) that indicate a
successful login. When found, pop-before-smtp installs an entry for the IP in
an on-disk hash (DB) that is watched by your SMTP software (e.g. Postfix,
sendmail, qmail, etc.). It then expires these entries when 30 minutes have
elapsed after the last POP/IMAP access from that IP.

OPTIONS

--config=FILE

Specify the config file to read instead of /etc/pop-before-smtp/pop-before-smtp.conf.
Useful for testing a new configuration before you install it. This option
must occur first on the command-line since it will be processed before
reading the config file, and all other options will be processed after
reading the config file.

--[no]write

Specify --nowrite if you don't want the DB file to be even opened, let alone
updated. Useful for trying out pattern-matching rules, especially when used
with --debug and --reprocess. (If your mail-log is world-readable, you can
even run the test as a non-privileged user.)

--[no]debug

If you specify --debug, logging to stdout will be enabled, plus extra
debug messages will be generated to help you diagnose local/remote IP
distinctions. Specify --logto after this option if you want the messages
to go somewhere other than stdout. Often combined with --reprocess.

--[no]flock

Using --noflock will turn off the default file-locking used on the DB file.

--reprocess

Parse the whole mail-log file, pretending that each line is happening again.
Useful for testing, especially when combined with --debug and possibly
--nowrite.

--watchlog=FILE

You can specify what mail-log to watch for POP/IMAP events. To see what the
default value is for your system, run ``pop-before-smtp --dumpconfig''.

--dbfile=FILE

You can specify what DB file to update. To see what the default value is for
your system, run ``pop-before-smtp --dumpconfig''. Typically, the filename that
is created/updated is this name with a ``.db'' suffix added (because the default
tie function appends the ``.db'' onto the specified db name --- if you supply a
custom tie function, it is free to choose to do something else).

--logto=FILE

Turns on logging to the specified file (use ``-'' for stdout).

--grace=SECONDS

Set the number of seconds that an IP address is authorized after it
successfully signs in via POP or IMAP.

--version

Output the current version of the script and exit. May be combined with
--dumpconfig and --list in the same run.

--dumpconfig

Output some config info and exit. This makes it easy to see what things like
the dbfile, logto, and watchlog values are being set to in the config file.
May be combined with --version and --list in the same run.

--list

List the current IPs contained in the DB file (if any) and exit. May be
combined with --version and --dumpconfig in the same run.

--daemon=PIDFILE

Become a daemon by forking, redirecting STDIN/STDOUT/STDERR to /dev/null,
calling setsid, calling chdir('/'), and writing out the process ID of the
forked process into the specified PIDFILE.

INSTALLATION

This daemon directly requires four modules from CPAN, which are not included
in the base Perl release as of this writing. See the quickstart guide for
more information (either look at the README.QUICKSTART file in the source or
visit http://popbsmtp.sourceforge.net/quickstart.shtml).

You should edit the supplied pop-before-smtp-conf.pl file to customize things
for your local system, such as scanning for the right POP/IMAP authorization,
setting various options, etc. Again, the quickstart guide cover this.

When starting up, pop-before-smtp builds an internal table of all netblocks
natively permitted by your SMTP software (for Postfix it looks at the output
of ``postconf mynetworks''). This allows us to filter out local IP addresses
that are already authorized and thus need no special help from us.

This daemon likes a couple of helpers. Several init scripts are included with
the source and a version customized for your current OS may have been
installed in the same package as the pop-before-smtp script.

Once pop-before-smtp has been started (and thus the database file has been
created), you'll need to modify your MTA's configuration to read the IPs from
the database file. This is also covered in the quickstart guide.

DOWNLOAD, SUPPORT, etc.

INTERNALS

pop-before-smtp keeps two data structures for all currently-allowed hosts: a
queue, and a hash. The queue contains [ipaddr, time] records, while the hash
contains ipaddr => time. Every time the daemon wakes up to deal with something
else from the logfile handle, it peeks a the front of the queue, and when
the timestamp of the record there has expired (is > 30 minutes old) it tosses
it, and if the timestamp in the hash equals the timestamp in the queue, it
deletes the hash entry and the on-disk db file entry.

pop-before-smtp protects the writes to the db file by flock. As far as I
know, the consequences of a collision (corrupt read in an smtpd) are
relatively mild, and the likelihood of one is remote, but the performance
impact of the locking seems to be negligible, so it's enabled by default.
To disable the flocking, invoke with --noflock or set ``$flock = 0'' in the
config file.