postfix-policyd-spf-perl 2.010
A Postfix SMTPd policy server for SPF checking
(C) 2007-2008,2012 Scott Kitterman <scott@kitterman.com>
(C) 2012           Allison Randal <allison@perl.org>
(C) 2007           Julian Mehnle <julian@mehnle.net>
(C) 2003-2004      Meng Weng Wong <mengwong@pobox.com>
Thanks for contributions by various members of the SPF project
<http://www.openspf.org/Software#postfix-policyd-spf-perl>
<https://launchpad.net/postfix-policyd-spf-perl>
==============================================================================

postfix-policyd-spf-perl is a Postfix SMTPd policy server for SPF checking.
It is implemented in pure Perl and uses the Mail::SPF CPAN module.  Note that
Mail::SPF is a complete re-implementation of SPF based on the final SPF RFC,
RFC 4408.  It shares no code with the older Mail::SPF::Query that was the
original SPF development implementation.  If you are upgrading from on older
(<< 2.000) version of this policy server you will need to install Mail::SPF.
At least version 2.006 of Mail::SPF is required.

This version of the policy server always checks HELO before Mail From (older
versions just checked HELO if Mail From was null).  It will reject mail that
fails either Mail From or HELO SPF checks.  It will defer mail if there is a
temporary SPF error and the message would othersise be permitted 
(DEFER_IF_PERMIT).  If the HELO check produces a REJECT/DEFER result, Mail From
will not be checked.

If the message is not rejected or deferred, the policy server will PREPEND the
appropriate SPF Received header.  If Mail From is anything other than completely
empty (i.e. <>) then the Mail From result will be used for SPF Received (e.g.
Mail From None even if HELO is Pass).

The policy server skips SPF checks for connections from the localhost (127.) and
instead prepends and logs 'SPF skipped - localhost is always allowed.'  If you
have relays that you want to skip SPF checks for, create a configuration file,
/etc/postfix/exempt_spf_addresses and add them on one using standard CIDR
notation in a space separated list.  For these addresses, 'X-Comment: SPF
skipped for whitelisted relay' is prepended and logged. IPv6 localhost is also
skipped.

A configuration file, /etc/postfix/exempt_spf_domains, can be used to
ignore domains that have broken SPF configurations that would normally
fail. For those domains, add the domain to the file (one per line), and
restart postfix so that the policy server can reload its configuration.
The policy server will ignore the domain going forward.

If defined, the configuration files described above need to have permissions
to allow the policy server to read the files.

The standard build for the policy server assumes that the postfix config file
directory is /etc/postfix.  If this is not correct for your operating systemn,
run the provided config.sh file from the package directory and it will update
the config file directory based on the output of postconf -h config_directory.
This needs to be done before package installation.

Error conditions within the policy server (that don't result in a crash) or from
Mail::SPF will return DUNNO.

See INSTALL for installation instructions.

Usage:
    policyd-spf-perl [-v]

This documentation assumes you have read Postfix's README_FILES/
SMTPD_POLICY_README.

Logging is sent to syslogd.

Each time a Postfix SMTP server process is started it connects to the policy
service socket, and Postfix runs one instance of this Perl script.  By
default, a Postfix SMTP server process terminates after 100 seconds of idle
time, or after serving 100 clients.  Thus, the cost of starting this Perl
script is smoothed out over time.

The default policy_time_limit is 1000 seconds.  This may be too short for some
SMTP transactions to complete.  As recommended in SMTPD_POLICY_README, this
should be extended to 3600 seconds.  To do so, set "policy_time_limit = 3600"
in /etc/postfix/main.cf.

Testing the policy daemon
-------------------------

To test the policy daemon by hand, execute:

    % /usr/local/lib/policyd-spf-perl

Each query is a bunch of attributes.  Order does not matter, and the daemon
uses only a few of all the attributes shown below:

    request=smtpd_access_policy
    protocol_state=RCPT
    protocol_name=SMTP
    helo_name=some.domain.tld
    queue_id=
    instance=71b0.45e2f5f1.d4da1.0
    sender=foo@bar.tld
    recipient=bar@foo.tld
    client_address=1.2.3.4
    client_name=another.domain.tld
    [empty line]

The policy daemon will answer in the same style, with an attribute list
followed by a empty line:

    action=550 Please see http://www.openspf.org/Why?id=foo@bar.tld&ip=1.2.3.4&
           receiver=bar@foo.tld
    [empty line]

To test HELO checking sender should be empty:

    sender=
    ... More attributes...
    [empty line]

If you want more detail in the system logs change $VERBOSE to 1.

License
-------

postfix-policyd-spf-perl is free software.  You may use, modify, and distribute
it under the GNU GPL (version 2 or later); see the LICENSE file.