Modular Python Postfix Policy Server
                ====================================

Modular Python Postfix Policy Server is tool for extending Postfix
checking capabilities. It uses Postfix access policy delegation
(http://www.postfix.org/SMTPD_POLICY_README.html) to check incoming
SMTP request and accept or reject it according provided data. It can
reduce mailserver load with rejecting incorrect mail during SMTP
connection. It was made with stress to height reliability and performance
by providing caching of required data and results.

Because it has modular design it can be easily extended by custom
modules (only one method has to be implemented and everything else is
handled automatically). By default it provide modules for SPF
checking, domain mailhost checking, sender/recipient verification,
black/white listing, greylisting, spam traps, DNS blacklists, ...

You can configure how to use all modules by implementing one simple
method in config file. It provide to you ability to define check
dependencies and use different modules according to the result of
previous.



1. Installation

1.1 Requirements

postfix           >= 2.1           - http://www.postfix.org
python            >= 2.3           - http://www.python.org
python-twisted    >= 1.3           - http://twistedmatrix.com
MySQL         *   >= 3.23          - http://www.mysql.com
python-GeoIP  *   >= 1.2.1         - http://www.maxmind.com/app/python
python-ldap   *   >= 2.0.x         - http://python-ldap.sourceforge.net
dnspython     **  >= 1.3.3         - http://www.dnspython.org
pyperl        *** >= 1.0.1         - http://ftp.activestate.com/Zope-Perl

*   required by some check modules (but not by application core)
**  version 1.3.5 is much slower then 1.3.4 because of changes in resolver
    (may be that newer version is better but I did not check it)
*** required by modules that directly call perl (none module now)
    you can use local patched copy (works with python 2.4 and perl 5.8.8)
    http://kmlinux.fjfi.cvut.cz/~vokac/activities/ppolicy/download/pyperl


1.2 PPolicy download

Primary site for this PPolicy server is
http://kmlinux.fjfi.cvut.cz/~vokac/activities/ppolicy/download. You can
download there prebuild RPM package or sources in SRPM and tgz format.


1.3 PPolicy installation

1.3.1 Install from RPM

rpm -Uvh ppolicy-2.x.x.noarch.rpm

1.3.2 Install from sources

Rebuild SRPM package or install application directly from tgz package.

* building SRPM:
  rpmbuild --rebuild ppolicy-2.x.x.src.rpm
  rpm -Uvh /path/to/builded/package/ppolicy-2.x.x.noarch.rpm

* building tgz:
  tar xzf ppolicy-2.x.x.tar.gz
  cd ppolicy-2.x.x
  python setup.py install
  # if you want to use different than default python installation directory
  # than you should omit last step, but you have to set basePath
  # in ppolicy.conf configuration file

  # installing additional required files
  cp ppolicy.tap /usr/sbin/ppolicy.tap
  cp ppolicy.init /etc/init.d/ppolicy # this script was tested on RedHat
  cp ppolicy.conf /etc/postfix
  mkdir -p /var/log/ppolicy # this path is defined in /etc/init.d/ppolicy
  mysql < ppolicy.sql       # if you want to use database 

1.3.2 Starting ppolicy

* use startup script /etc/init.d/ppolicy
* or start ppolicy daemon manually using command
      /usr/bin/python /usr/bin/twistd \
          --pidfile=/var/log/ppolicy/ppolicy.pid \
          --rundir=/var/log/ppolicy \
          --file=/usr/sbin/ppolicy.tap \
          --python=/usr/sbin/ppolicy.tap \
          --logfile=/var/log/ppolicy/ppolicy.log \
          --no_save


2. Configuration

2.1 PPolicy

Configuration of ppolicy daemon is done through ppolicy.conf file. Default
location for this file is /etc/postfix/ppolicy.conf. If you place this file
somewhere else than you have to change this information in ppolicy.tap
twisted bootstrap file that is installed by default to /usr/sbin.

There are plenty of comments and examples in ppolicy.conf so you
should be able to adapt it to your needs. For details about particular
check modules you can read class description in source file or
documentation exported in file MODULES.


2.2 Postfix configuration

Update configuration according following examples and adapt to your needs.

/etc/postfix/main.cf:
    smtpd_recipient_restrictions =
        ...
        reject_unauth_destination
        check_policy_service inet:127.0.0.1:10030
        ...
    127.0.0.1:10030_time_limit = 3600


2.3 Database configuration

Database is used to permanently store result of some expensive
checks. In most cases it should be possible to run ppolicy without
database backend but it is not recommended because of degraded
performance and (may be) more bug (it was not fully tested without
database).

Only MySQL database was tested with ppolicy but it should not be
difficult to adapt to any SQL database. You have to create new ppolicy
database and change database connection information in configuration
file ppolicy.conf. User you use to connect to ppolicy database must
have rights to create new tables. All required tables are created
automatically during ppolicy server startup.

New (MySQL) database can be created using ppolicy.sql template, but
you should first change predefined password. To run this SQL script
you need database user with CREATE DATABASE privileges, e.g.:

mysql --hostname=localhost --user=root --password=secret < ppolicy.sql



3. Modules

3.1 Existing modules

* Country
* Dnsbl
* DnsblDynamic
* DnsblScore
* DOS
* Dummy
* DumpDataDB
* DumpDataFile
* Greylist
* List
* ListBW
* ListDyn
* ListMailDomain
* LookupLDAP
* P0f
* Resolve
* SPF
* Trap
* Verification
* Whois

Detailed descriptions of all modules can be found in file named MODULES.
There are also information about all parameters and basic examples
how to use the module in config file.


3.2. Writing new modules

Before you start to write custom modules look at IPPolicyServerCheck,
Base and mainly Dummy module. There are plenty of comments that can be
useful to know. The heart of each module is check() method that is
called when you use module in config file. Next important is hashArg()
which influence data caching (it is key for result cache dictionary),
start() that is called before first usage of check() method. Last method
that can be implemented is stop() and it is called e.g. when application
terminating.



4. Bug reports

If you find some bug or performance bottleneck than let me know or
better send me patch. You can contact me using following address

Petr Vokac <vokac[at]kmlinux.fjfi.cvut.cz>