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 us‐
43       ing different configuration options on a per user (mail reciepient) ba‐
44       sis.
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 re‐
81       jecting based on HELO checking does not present a false positive risk.
82       These settings are a matter of local policy and should be adjusted to
83       meet the requirements of site administrators.  See policyd-spf.conf(5)
84       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               policyd-spf_time_limit is an instance of transport_time_limit.
154       See
155               SMTPD_POLICY_README or postconf (5) transport_time_limit for
156       details.
157
158           NOTE:  Specify check_policy_service AFTER reject_unauth_destination
159       or
160                  else your system can become an open relay.
161
162
163        3. Reload Postfix.
164
165

PERFORMANCE CONSIDERATIONS

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

SEE ALSO

200       policyd-spf.conf(5), policyd-spf.peruser(5), python-spf,
201       <http://www.openspf.org>, RFC 7208
202
203

AUTHORS

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