README
1postfix-policyd-spf-perl 2.010
2A Postfix SMTPd policy server for SPF checking
3(C) 2007-2008,2012 Scott Kitterman <scott@kitterman.com>
4(C) 2012 Allison Randal <allison@perl.org>
5(C) 2007 Julian Mehnle <julian@mehnle.net>
6(C) 2003-2004 Meng Weng Wong <mengwong@pobox.com>
7Thanks for contributions by various members of the SPF project
8<http://www.openspf.net/Software#postfix-policyd-spf-perl>
9==============================================================================
10
11postfix-policyd-spf-perl is a Postfix SMTPd policy server for SPF checking.
12It is implemented in pure Perl and uses the Mail::SPF CPAN module. Note that
13Mail::SPF is a complete re-implementation of SPF based on the final SPF RFC,
14RFC 4408. It shares no code with the older Mail::SPF::Query that was the
15original SPF development implementation. If you are upgrading from on older
16(<< 2.000) version of this policy server you will need to install Mail::SPF.
17At least version 2.006 of Mail::SPF is required.
18
19This version of the policy server always checks HELO before Mail From (older
20versions just checked HELO if Mail From was null). It will reject mail that
21fails either Mail From or HELO SPF checks. It will defer mail if there is a
22temporary SPF error and the message would othersise be permitted
23(DEFER_IF_PERMIT). If the HELO check produces a REJECT/DEFER result, Mail From
24will not be checked.
25
26If the message is not rejected or deferred, the policy server will PREPEND the
27appropriate SPF Received header. If Mail From is anything other than completely
28empty (i.e. <>) then the Mail From result will be used for SPF Received (e.g.
29Mail From None even if HELO is Pass).
30
31The policy server skips SPF checks for connections from the localhost (127.) and
32instead prepends and logs 'SPF skipped - localhost is always allowed.' If you
33have relays that you want to skip SPF checks for, you can add them to
34relay_addresses on line 78 using standard CIDR notation in a space separated
35list. For these addresses, 'X-Comment: SPF skipped for whitelisted relay' is
36prepended and logged. IPv6 localhost is also skipped.
37
38Error conditions within the policy server (that don't result in a crash) or from
39Mail::SPF will return DUNNO.
40
41See INSTALL for installation instructions.
42
43Usage:
44 policyd-spf-perl [-v]
45
46This documentation assumes you have read Postfix's README_FILES/
47SMTPD_POLICY_README.
48
49Logging is sent to syslogd.
50
51Each time a Postfix SMTP server process is started it connects to the policy
52service socket, and Postfix runs one instance of this Perl script. By
53default, a Postfix SMTP server process terminates after 100 seconds of idle
54time, or after serving 100 clients. Thus, the cost of starting this Perl
55script is smoothed out over time.
56
57The default policy_time_limit is 1000 seconds. This may be too short for some
58SMTP transactions to complete. As recommended in SMTPD_POLICY_README, this
59should be extended to 3600 seconds. To do so, set "policy_time_limit = 3600"
60in /etc/postfix/main.cf.
61
62Testing the policy daemon
63-------------------------
64
65To test the policy daemon by hand, execute:
66
67 % /usr/local/lib/policyd-spf-perl
68
69Each query is a bunch of attributes. Order does not matter, and the daemon
70uses only a few of all the attributes shown below:
71
72 request=smtpd_access_policy
73 protocol_state=RCPT
74 protocol_name=SMTP
75 helo_name=some.domain.tld
76 queue_id=
77 instance=71b0.45e2f5f1.d4da1.0
78 sender=foo@bar.tld
79 recipient=bar@foo.tld
80 client_address=1.2.3.4
81 client_name=another.domain.tld
82 [empty line]
83
84The policy daemon will answer in the same style, with an attribute list
85followed by a empty line:
86
87 action=550 Please see http://www.openspf.org/Why?id=foo@bar.tld&ip=1.2.3.4&
88 receiver=bar@foo.tld
89 [empty line]
90
91To test HELO checking sender should be empty:
92
93 sender=
94 ... More attributes...
95 [empty line]
96
97If you want more detail in the system logs change $VERBOSE to 1.
98
99License
100-------
101
102postfix-policyd-spf-perl is free software. You may use, modify, and distribute
103it under the GNU GPL (version 2 or later); see the LICENSE file.
104
105