1
2POLICYD-SPF(1)              General Commands Manual             POLICYD-SPF(1)
3
4
5

NAME

7       policyd-spf - pure-Python Postfix policy daemon for SPF checking
8

VERSION

10       2.0.0
11
12

USAGE

14       NOTE: Depending on the packaging and distribution, the exact path to
15       the executable may vary.
16
17       $ policyd-spf (Start using installed config file)
18
19       $ policyd-spf -h (Display usage message)
20
21       $ policyd-spf /etc/policyd-spf/policyd-spf.conf (Config file name to
22       use)
23
24       Configuration options are described in the sample configuration file
25       provided with the package (policyd-spf.conf.commented) and in policyd-
26       spf.conf(5).  The provided setup.py installs an uncommented configura‐
27       tion file in /etc/policyd-spf/.
28
29       Additionally, whitelisting certain IP addresses or IP addresses used by
30       listed domains from SPF checks is supported.  Skipping SPF checks for
31       local submission or trusted relays is also provided.  The sample con‐
32       figuration file and policyd-spf.conf(5) shows the format to use.
33
34

OTHER DOCUMENTATION

36       This documentation assumes you have read Postfix's README_FILES/
37       SMTPD_POLICY_README and are generally familiar with Sender Policy
38       Framework (SPF).  See RFC 7208 for details.
39
40       See man 5 policyd-spf.conf for configuration file information.
41
42       man 5 policyd-spf.peruser provides documentation on setting up and
43       using different configuration options on a per user (mail reciepient)
44       basis.
45
46

SYNOPSIS

48       python-policyd-spf is a Postfix SMTPd policy daemon for SPF checking.
49       It is implemented in pure Python and uses the pyspf module.  The SPF
50       web site is http://www.openspf.org/.  The Postfix configuration must be
51       changed to check SPF.
52
53

DESCRIPTION

55       Logging is sent to syslogd.
56
57       Each time a Postfix SMTP server process is started it connects to the
58       policy service socket and Postfix runs one instance of this Python
59       script.  By default, a Postfix SMTP server process terminates after 100
60       seconds of idle time, or after serving 100 clients.  Thus, the cost of
61       starting this Python script is smoothed over time
62
63       The default policy_time_limit is 1000 seconds.  This may be too short
64       for some SMTP transactions to complete.  As recommended in SMTPD_POL‐
65       ICY_README, this should be extended to 3600 seconds.  To do so, set
66       "policy_time_limit = 3600" in /etc/postfix/main.cf.
67
68       Messages that get a Fail SPF result will be rejected.  Messages that
69       get a Permerror are, by default, treated as if they had no SPF record.
70       Messages that get a Temperror result are, by default, treated as if
71       they had no SPF record, but can (and probably should) be deferred if
72       otherwise permitted.  Messages that get other SPF results (Pass, None,
73       Neutral, Softfail) will have the SPF Received header prepended.  Note:
74       Spamasassisn 3.2 and follow will use this header for spam scoring so
75       there is no need to configure a separate SPF check in these Spamassas‐
76       sin versions.  See Spamassassin documentation for details.
77
78       Default Mail From rejection/deferal criteria are, by design, conserva‐
79       tive.  Default HELO check actions are to reject mail with other than
80       Pass/None. HELO records are much simpler than Mail From records and
81       rejecting based on HELO checking does not present a false positive
82       risk.  These settings are a matter of local policy and should be
83       adjusted to meet the requirements of site administrators.  See policyd-
84       spf.conf(5) for configuration file details.
85
86

LOGGING

88       Policyd-spf will log messages to syslog about it's activities.  The
89       "debugLevel" value in "policyd-spf.conf" can be increased to get addi‐
90       tional information to be logged.  When set to a value of "0", only test
91       results (SPF hits/misses) are logged.  Results will be returned to
92       Postfix and logged as a warning by Postfix also.  For logging by this
93       policy server, look for "policyd-spf" in your mail log files.
94
95

TESTING THE POLICY DAEMON

97       Testing the policy daemon
98
99       To test the policy daemon by hand, execute:
100
101           policyd-spf
102
103       Each query is a bunch of attributes.  Order does not matter, and the
104       daemon uses only a few of all the attributes shown below:
105
106           request=smtpd_access_policy
107           protocol_state=RCPT
108           protocol_name=SMTP
109           helo_name=some.domain.tld
110           queue_id=8045F2AB23
111           instance=12345.6789
112           sender=foo@bar.tld
113           recipient=bar@foo.tld
114           client_address=1.2.3.4
115           client_name=another.domain.tld
116           [empty line]
117
118       The policy daemon will answer in the same style, with an attribute list
119       followed by a empty line:
120
121           action=dunno
122           [empty line]
123
124

POSTFIX INTEGRATION

126        1. Add the following to /etc/postfix/master.cf:
127
128               policyd-spf  unix  -       n       n       -       0
129       spawn
130                   user=nobody argv=/usr/bin/policyd-spf
131
132           NOTE: Check the path to both the installed Python 3 interpreter and
133                 policyd-spf.  These vary from system to system.  To use non-
134       default
135                 settings, you must also add the config file (see above and
136                 policyd-spf.conf(5) for details).  If you run other services
137       with
138                 user nobody, create a dedicated user for this policy server
139       and use
140                 that instead.  Python and Python 3 versions prior to 3.3 are
141       not
142                 supported.
143
144        2. Configure the Postfix policy service in /etc/postfix/main.cf:
145
146               smtpd_recipient_restrictions =
147                   ...
148                   reject_unauth_destination
149                   check_policy_service unix:private/policyd-spf
150                   ...
151               policyd-spf_time_limit = 3600
152
153           NOTE:  Specify check_policy_service AFTER reject_unauth_destination
154       or
155                  else your system can become an open relay.
156
157
158        3. Reload Postfix.
159
160

PERFORMANCE CONSIDERATIONS

162       The time to complete DNS lookups associated with SPF checks is the most
163       significant factor in policy server performance.  Use of a capable
164       local caching resolver is highly recommended.  Specifics of resolver
165       setup are outside the scope of this document.
166
167       Long waits for DNS answers can cause performance bottlenecks.  There
168       are two primary controls, policyd-spf.conf(5) has details, provided to
169       affect DNS timing.  Lookup_Time controls the overall time, in seconds,
170       allowed for an SPF check to complete.  Whitelist_Lookup_Time controls
171       the amount of time allowed for individual DNS lookups associated with
172       name based whitelist options.
173
174       Lookup_Time defaults to the 20 second value recommended by RFC 7208.
175       This is a conservative recommendation and often a lower limit works
176       quite well.  Delays associated with whitelisting related DNS lookups
177       can be avoided by using IP based options instead.
178
179       A shorter time increases the likelihood that the result for some mes‐
180       sages will be a temporary error rather then the actual correct result.
181       To avoid some reported interoperability issues with some greylisting
182       implementations, TempError_Defer defaults to False.  With TempEr‐
183       ror_Defer set to True, such TempError messages will be deferred and
184       when retried, the responses should be in the local DNS resolver's
185       cache.
186
187       The combination of a low Lookup_Time setting, TempError_Defer = True,
188       and no DNS name based whitelisting will maximize SPF checking through‐
189       put with only mimimal delays.  Consider a value of Lookup_Time = 5 sec‐
190       onds and monitor the system mail logs.  If TempError results are rare
191       or non-existent, the value can be lowered.  If such result are common
192       (more than 1% of mail), then the value should be raised.
193
194

SEE ALSO

196       policyd-spf.conf(5), policyd-spf.peruser(5), python-spf,
197       <http://www.openspf.org>, RFC 7208
198
199

AUTHORS

201       This version of policyd-spf (python) was written by Copyright ©
202       2007-2016 Scott Kitterman <scott@kitterman.com>.  It is derived from
203       Tumgreyspf, written by Sean Reifschneider, tummy.com, ltd
204       <jafo@tummy.com>. Portions of the documentation were written by Meng
205       Weng Wong <mengwong@pobox.com>.
206
207       This man-page was created by Scott Kitterman <scott@kitterman.com>.  It
208       is licensed under the same terms as the program.
209
210
211
212
213                                                                POLICYD-SPF(1)
Impressum