POLICYD-SPF(1) General Commands Manual POLICYD-SPF(1)
NAME
policyd-spf - pure-Python Postfix policy daemon for SPF checking
VERSION
2.0.0
USAGE
NOTE: Depending on the packaging and distribution, the exact path to
the executable may vary.
$ policyd-spf (Start using installed config file)
$ policyd-spf -h (Display usage message)
$ policyd-spf /etc/postfix-policyd-spf-python/policyd-spf.conf
(Config file name to use)
Configuration options are described in the sample configuration file
installed in /usr/share/doc/postfix-policyd-spf-python (policyd-
spf.conf.commented) and in policyd-spf.conf(5). The provided setup.py
installs an uncommented configuration file in /etc/postfix-policyd-spf-
python/.
Additionally, whitelisting certain IP addresses or IP addresses used by
listed domains from SPF checks is supported. Skipping SPF checks for
local submission or trusted relays is also provided. The sample con-
figuration file and policyd-spf.conf(5) shows the format to use.
OTHER DOCUMENTATION
This documentation assumes you have read Postfix's README_FILES/
SMTPD_POLICY_README and are generally familiar with Sender Policy
Framework (SPF). See RFC 7208 for details.
See man 5 policyd-spf.conf for configuration file information.
man 5 policyd-spf.peruser provides documentation on setting up and us-
ing different configuration options on a per user (mail reciepient) ba-
sis.
SYNOPSIS
python-policyd-spf is a Postfix SMTPd policy daemon for SPF checking.
It is implemented in pure Python and uses the pyspf module. The SPF
web site is http://www.openspf.org/. The Postfix configuration must be
changed to check SPF.
DESCRIPTION
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 Python
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 Python script is smoothed 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_POL-
ICY_README, this should be extended to 3600 seconds. To do so, set
"policy_time_limit = 3600" in /etc/postfix/main.cf.
Messages that get a Fail SPF result will be rejected. Messages that
get a Permerror are, by default, treated as if they had no SPF record.
Messages that get a Temperror result are, by default, treated as if
they had no SPF record, but can (and probably should) be deferred if
otherwise permitted. Messages that get other SPF results (Pass, None,
Neutral, Softfail) will have the SPF Received header prepended. Note:
Spamasassisn 3.2 and follow will use this header for spam scoring so
there is no need to configure a separate SPF check in these Spamassas-
sin versions. See Spamassassin documentation for details.
Default Mail From rejection/deferal criteria are, by design, conserva-
tive. Default HELO check actions are to reject mail with other than
Pass/None. HELO records are much simpler than Mail From records and re-
jecting based on HELO checking does not present a false positive risk.
These settings are a matter of local policy and should be adjusted to
meet the requirements of site administrators. See policyd-spf.conf(5)
for configuration file details.
LOGGING
Policyd-spf will log messages to syslog about it's activities. The
"debugLevel" value in "policyd-spf.conf" can be increased to get addi-
tional information to be logged. When set to a value of "0", only test
results (SPF hits/misses) are logged. Results will be returned to
Postfix and logged as a warning by Postfix also. For logging by this
policy server, look for "policyd-spf" in your mail log files.
TESTING THE POLICY DAEMON
Testing the policy daemon
To test the policy daemon by hand, execute:
policyd-spf
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=8045F2AB23
instance=12345.6789
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=dunno
[empty line]
POSTFIX INTEGRATION
1. Add the following to /etc/postfix/master.cf:
policyd-spf unix - n n - 0
spawn
user=policyd-spf argv=/usr/bin/policyd-spf
NOTE: Check the path to both the installed Python interpreter and
policyd-spf. These vary from system to system. To use non-
default
settings, you must also add the config file (see above and
policyd-spf.conf(5) for details). Python and Python 3 ver-
sions
prior to 3.3 are not supported.
2. Configure the Postfix policy service in /etc/postfix/main.cf:
smtpd_recipient_restrictions =
...
reject_unauth_destination
check_policy_service unix:private/policyd-spf
...
policyd-spf_time_limit = 3600
policyd-spf_time_limit is an instance of transport_time_limit.
See
SMTPD_POLICY_README or postconf (5) transport_time_limit for
details.
NOTE: Specify check_policy_service AFTER reject_unauth_destination
or
else your system can become an open relay.
3. Reload Postfix.
PERFORMANCE CONSIDERATIONS
The time to complete DNS lookups associated with SPF checks is the most
significant factor in policy server performance. Use of a capable lo-
cal caching resolver is highly recommended. Specifics of resolver
setup are outside the scope of this document.
Long waits for DNS answers can cause performance bottlenecks. There
are two primary controls, policyd-spf.conf(5) has details, provided to
affect DNS timing. Lookup_Time controls the overall time, in seconds,
allowed for an SPF check to complete. Whitelist_Lookup_Time controls
the amount of time allowed for individual DNS lookups associated with
name based whitelist options.
Lookup_Time defaults to the 20 second value recommended by RFC 7208.
This is a conservative recommendation and often a lower limit works
quite well. Delays associated with whitelisting related DNS lookups
can be avoided by using IP based options instead.
A shorter time increases the likelihood that the result for some mes-
sages will be a temporary error rather then the actual correct result.
To avoid some reported interoperability issues with some greylisting
implementations, TempError_Defer defaults to False. With TempError_De-
fer set to True, such TempError messages will be deferred and when re-
tried, the responses should be in the local DNS resolver's cache.
The combination of a low Lookup_Time setting, TempError_Defer = True,
and no DNS name based whitelisting will maximize SPF checking through-
put with only mimimal delays. Consider a value of Lookup_Time = 5 sec-
onds and monitor the system mail logs. If TempError results are rare
or non-existent, the value can be lowered. If such result are common
(more than 1% of mail), then the value should be raised.
SEE ALSO
policyd-spf.conf(5), policyd-spf.peruser(5), python-spf,
<http://www.openspf.org>, RFC 7208
AUTHORS
This version of policyd-spf (python) was written by Copyright ©
2007-2016 Scott Kitterman <scott@kitterman.com>. It is derived from
Tumgreyspf, written by Sean Reifschneider, tummy.com, ltd
<jafo@tummy.com>. Portions of the documentation were written by Meng
Weng Wong <mengwong@pobox.com>.
This man-page was created by Scott Kitterman <scott@kitterman.com>. It
is licensed under the same terms as the program.
POLICYD-SPF(1)
Generated by dwww version 1.14 on Fri Jan 24 06:25:49 CET 2025.