POP-Before-SMTP-Auth v.1.3.2  October 27, 2012
(c) 2012 Ron Guerin <ron@vnetworx.net>
Licensed under GPL2 or later.
Requires PHP-CLI 5.3 or greater with pcntl, PCRE and POSIX.

This code is unsupported, though you can try mailing the list and if I can,
and I have time, I may try to help.  You have to join the list to post to it.

Mailing List: http://lists.gothamcode.com/gothamcode

This script needs to be run as root to read log files and run postmap

Installing
----------
1. Copy the script pop-before-smtp-auth to /usr/local/sbin
2. Copy the manpage pop-before-smtp-auth.8.gz to /usr/local/man/man8
3. Create the config file /etc/pop-before-smtp-auth.conf
   Put your settings in this file rather than altering the script.

Configuring Postfix
-------------------
Postfix's main.cf needs to be modified to include:
   check_client_access hash:${posthashfile}

where you'd substitute something like /var/lib/pop-before-smtp-auth/hosts
for ${posthashfile}.  This needs to go under smtp_recipient_restrictions,
perhaps immediately follwing permit_sasl_authenticated .


Settings
--------
Do not edit the script.  Create a /etc/pop-before-smtp-auth.conf file
to change settings, or set them via the command-line.

Setting        Default
------------   -------------------------------------------------------------
config       = ./${scriptname}.conf, /etc/${scriptname}.conf,
               or /etc/local/${scriptname}.conf  (in that order)
               If Optware is detected, these will be prefixed by /opt and
               checked first. (see Config Search below)
pidpath      = /var/run (where to put the pidfile)
hostname     = (default: output of hostname --short)
maillog      = /var/log/mail.log (log file to monitor)
authperiod   = 30 (minutes to allow an IP address to relay)
checkdelay   = 5 (seconds, length of time between checking for changes)
popserver    = dovecot
popservice   = pop3-login
postmap      = postmap
postinstance = /etc/postfix (the instance of Postfix to work with)
posthashfile = /var/lib/${scriptname}/hosts
debug        = FALSE
daemonize    = TRUE (run as a daemon)
logignores   = TRUE (log ignored POP mail collectors)
regex        = (.*) $HOSTNAME $POPSERVER: $POPSERVICE: Login: user=<(.*)>, method=.*, rip=(.*), lip
regexstamp   = 1
regexuser    = 2
regexip      = 3
silentmax    = 30 (seconds to wait for monitored file exist before warning)
stderr       = /dev/null (where to point stderr)

${scriptname} = whatever the name of the script is. Usually=pop-before-smtp-auth

Command-line Options
--------------------
All configuration settings are available as command-line options.  Settings
made via the command-line override config file settings.

For example, to use a config file with a non-standard name in a non-standard
location, use the option --config=/path/to/configfile.conf

To override a config file setting with the default setting, set the option
on the command-line without a value.  For example, if in your config file
you have set: authperiod=60

You can override it with its default like this:
   --authperiod=
To override it with a specific value:
   --authperiod=45

Options can be set to TRUE by either of the following:
   --option=TRUE
   --option
The form --option is an abbreviation for --option=TRUE

Config Search
-------------
The config file is searched for in the following order:
1. If a config file is specified on the command-line, use that,
   or terminate because it doesn't exist or it can't be read.
2. ./${scriptname}.conf
3. /opt/usr/local/etc/${scriptname}.conf
4. /opt/etc/${scriptname}.conf
5. /usr/local/etc/${scriptname}.conf
6. /etc/${scriptname}.conf

Changing the log-line matching regular expression
-------------------------------------------------
You should be able to substitute any PCRE regex for your own, by defining
the configuration setting "regex".  The following substitutions will be
made at runtime:

 * $HOSTNAME
 * $POPSERVER
 * $POPSERVICE

These substitutions are made based on their corresponding configuation
variable values. (ie: $HOSTNAME = the hostname config value)

The values 'regexstamp', 'regexuser', and 'regexip' indicate which sub-matches
in 'regex' contain the timestamp, user, and remote IP address, respectively.
These three values are required to be able to use a custom regex in 'regex'.

Unless you change it, the following default regex will be used:
$HOSTNAME $POPSERVER: $POPSERVICE: Login: user=<(.*)>, method=.*, rip=(.*), lip

With the default regex, the regexstamp is 1, regexuser is 2,
and regexip is 3.

Specifying regex changes on the command line is possible as with any other
configuration setting, but you may find it difficult to properly escape
everything.


Init Scripts
------------
  Debian/Ubuntu/et al:
  --------------------
  Copy: pop-before-smtp-auth.init-debian to /etc/init.d/pop-before-smtp-auth
  Run: update-rc.d pop-before-smtp-auth start 20 2 3 4 5 . stop 20 0 1 6 .

  RedHat/Fedora/CentOS/et al:
  ---------------------------
  Copy: pop-before-smtp-auth.init-fedora to /etc/init.d/pop-before-smtp-auth
  Run: ????

The RedHat/Fedora init script is untested, and I don't know how to properly
install it on a contemporary RedHat system.