whitelister is a Postfix Policy Server (see [1]).


the aim is to accept every really clean mail immediately, and to reserve the
evil treatments (like greylisting) to suspicious mails.


BUILDING WHITELISTER
~~~~~~~~~~~~~~~~~~~~

    you need :
     * a recent ocaml distribution (like 3.08.3), supporting Unix module and
       native compilation.
     * ocamlfind
     * the package syslog

    then you only have to run `make' and it should produce a `whitelister'
    executable.

    Note for Debian : if you have a deb-src line in your /etc/apt/source.list,
    you can get the Build Dependecies of whitelister by simply running :
    `apt-get build-dep whitelister'


POSTFIX CONFIGURATION
~~~~~~~~~~~~~~~~~~~~~

    It is intended to be used like that :

    (1) Default inet socket :

        in your main.cf :

            smtpd_recipient_restrictions =
                ...
                reject_unauth_destination
                check_policy_service inet:127.0.0.1:10000
                ... here your nasty treatments , like postgrey ...

        in your whitelister.conf, don't specify sock as its default value is OK.


    (2) Unix socket

        if you use a unix socket (more efficient on most systems) :

            smtpd_recipient_restrictions =
                ...
                reject_unauth_destination
                check_policy_service unix:private/whitelister.ctl
                ... here your nasty treatments , like postgrey ...

        in your whitelister.conf, set :

            sock: /var/spool/postfix/private/whitelister.ctl


    Some Notes :
    ~~~~~~~~~~

    Postfix DOC states :

        In case of trouble the policy server must not send a reply.  Instead the
        server must log a warning and disconnect.  Postfix will retry the
        request at some later time.

    But whitelister does not work that way.  Either the mail seems to be clean
    (wrt whitelister checks) and whitelister returns 'OK' (and the mail is also
    accepted), or one check fails and it returns 'DUNNO' in order to let the
    mail go through the nexts checks (like greylister).

    That's why, you *have* to use whitelister as one of the *last* rules in your
    smtpd_recipient_restrictions. Else, it can transform your smtp server into
    an open-relay.

    Any failure (in DNS e.g.) is also interpreted as a suspicious mail, and it
    will also go through the next restrictions checks too.


WHITELISTER CONFIGURATION
~~~~~~~~~~~~~~~~~~~~~~~~~

    whitelister search for two config files, named whitelister.conf in :
     o /etc/whitelister.conf
     o the same directory as itself
    and it aggregates the configuration of both files.


    the syntax is : <20> key: value <20> where key is the setting key, and value its
    value without quotes or anything.  Comments begin with a # at the first char
    of the line see whitelister-example.conf for an example config file.


    current settings are :


    (1) Daemon Options
        --------------

      verb     verbosity of the logs.
               `0' means don't log `Clean' mails
               `1' means log everything

      pidf     path to the pidfile whitelister will write its pid into.
               default is /var/run/whitelister.pid ,
               use /dev/null if you don't want to use the feature

      sock     the socket whitelister will listen to.
               the value is the path for a unix socket,
               or ip:port for a TCP one.

               last setting is used (/etc/whitelister.conf overrides local configs)

      user     name of the user used to run whitelister if launched as root
               default is nobody

      group    name of the group used to run whitelister if launched as root
               default is nogroup


    (2) Rules Configuration
        -------------------

      rbl       hostname of a rbl service

      rhbl_rcpt / rhbl_helo / rhbl_client / rhbl_sender

                hostname of a rhbl service.

                rcpt/helo/client/sender refers to the classical postfix
                terminology related to the settings :
                smtpd_(recipient, helo, client, sender)_restriction

                it means that an rhbl check is performed on (resp.) :
                 - the domain of the recipient
                 - the domain from the HELO/EHLO command
                 - the domain of the client connection
                 - the domain part of the sender address

      spf       spf checkings :
                0 means no check.

                for the rest, see the table :
                -------+-------+----------+----------------+-------
                 level | pass  |  neutal  |  empty record  | other
                -------+-------+----------+----------------+-------
                   1   |  ok   |    ok    |       ok       | !!!!
                   2   |  ok   |    ok    |      !!!!      | !!!!
                   3   |  ok   |   !!!!   |      !!!!      | !!!!
                -------+-------+----------+----------------+-------

      spfrej    reject mail on invalid SPF (default is yes), possible values are
                on/off/yes/no/0/1


APPENDIX

 [1] http://www.postfix.org/SMTPD_POLICY_README.html