policy-spf.conf(5) File Formats Manual policy-spf.conf(5)
NAME
policyd-spf - policyd-spf python configuration parameters
VERSION
2.0.0
USAGE
Usage:
policyd-spf [/etc/postfix-policyd-spf-python/policyd-spf.conf]
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.
man 1 policyd-spf provides general operation documentation for this
package.
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 operates with a default installed configuration file
and set of default configuration options that are used if the configu-
ration file cannot be found. These options can be changed by changing
the installed configuration files or through giving a path to an alter-
nate configuration file.
DESCRIPTION
Configuration options are described here and in the configuration file
provided with the package. The provided setup.py installs this config-
uration file in /etc/postfix-policyd-spf-python/.
Additionally, whitelisting certain IP addresses from SPF checks is sup-
ported. This man page and the sample configuration file show the for-
mat to use. These options can be adjusted on a per user (mail recipi-
ent) basis. Details on per user settings can be found in policyd-
spf.peruser(5).
OPTIONS
LOGGING
"debugLevel" controls the amount of information logged by the policy
server.
The default, 1, logs no debugging messages, just basic policy results
and errors generated through the policy server. This value can be in-
creased up to 5 (values higher than 5 will not cause an error, but will
not log any additional information).
debug level 2 adds a log message if no client address (IP address from
which the connection was made), Mail From address, or HELO/EHLO name is
received by the policy server, and logs SPF results for each Mail From
and HELO check.
debug level 3 generates a log message each time the policy server
starts and each time it exits, as well as logging a copy of the exact
header returned to Postfix to be prepended into the message. Each time
the policy server starts, debug level 3 also logs the configuration in-
formation used by the policy server.
debug level 4 logs the complete data set received by Postfix via the
policy interface and when the end of the entry is read.
debug level 5 is used to debug config file processing and, for this
purpose, can only be set in code and not via the config file. It also
provides additional internal status details generally of interest only
to developers.
If debug level is 0, then the policy server logs errors only.
When set to -1, nothing is logged once the configuration file has been
read in, not even error messages. Use with caution.
Default:
debugLevel = 1
TEST OPERATION
The policy server can operate in a test only mode. This allows you to
see the potential impact of SPF checking in your mail logs without re-
jecting mail. Headers are prepended in messages, but message delivery
is not affected. This mode is not enabled by default. To enable it,
set TestOnly = 0. If you want test operation with no header added,
also set Header_Type = None.
Note: This option was previously named defaultSeedOnly. This is still
accepted, but logs an error.
Default:
TestOnly = 1
HELO/EHLO CHECKING
HELO check rejection policy options are:
Fail - (Default) Reject only on HELO Fail. HELO/EHLO is known first in
the SMTP dialogue and there is no practical reason to waste resources
on Mail From checks if the HELO check will already cause the message to
be rejected. This should not cause interoperability problems when used
for HELO.
SPF_Not_Pass - Reject if result not Pass, None, or Temperror (alterna-
tively put, reject if the SPF result is Fail, Softfail, Neutral, PermE-
rror). Unlike Mail From checking, there are no standard e-mail use
cases where a HELO check should not Pass if there is an SPF record for
the HELO name (transparent forwarding, for example, is not an issue).
HELO/EHLO is known first in the SMTP dialogue and there is no practical
reason to waste resources on Mail From checks if the HELO check will
already cause the message to be rejected. This is not consistent with
the RFC 7208 requirement to treat none and neutral the same, but should
not cause interoperability problems when used for HELO.
Softfail - Reject on HELO Softfail or Fail. HELO/EHLO is known first
in the SMTP dialogue and there is no practical reason to waste re-
sources on Mail From checks if the HELO check will already cause the
message to be rejected. This should not cause interoperability prob-
lems when used for HELO.
Null - Only reject HELO Fail for Null sender (SPF Classic). This is
the approach used by the pre-RFC 4408 reference implementation and many
of the pre- RFC specifications. Use of at least this option
(SPF_Not_Pass or Fail) are preferred) is highly recommended.
False - Never reject on HELO, append header only. This is useful for
post-SMTP spam filters such as SpamAssassin.
No_Check - Never check HELO. This is only recommended if you are call-
ing the policy server twice (once for HELO checks and once for Mail
From) with two different configuration files. This approach is useful
to get both the HELO and Mail From headers prepended to a message.
Default:
HELO_reject = Fail
HELO/EHLO PASS RESTRICTION
HELO Pass Restriction allows integration with other Postfix access con-
trols by provding a user supplied name of a postfix access restriction
to be applied to a message when the HELO checking result is Pass. The
indicated restriction must be an action as defined for a Postfix SMTP
server access table access(5) and explained in the Postfix RESTRICTION
CLASS README. The README.per_user_whitelisting file provided with this
distribution provides examples. Note: A helo pass restriction will be
the returned result even if the mail from result would cause the mes-
sage to be rejected.
Example:
HELO_pass_restriction = helo_passed_spf
Default:
None
Mail From CHECKING
Mail From rejection policy options are:
SPF_Not_Pass - Reject if result not Pass/None/Tempfail. This option is
not RFC 7208 compliant since the mail with an SPF Neutral result is
treated differently than mail with no SPF record and Softfail results
are not supposed to cause mail rejection. Global use of this option is
not recommended. Use per-domain if needed (per-domain usage described
below).
Softfail - Reject on Mail From Softfail or Fail. Global use of this
option is not recommended. Use per-domain if needed (per-domain usage
described below).
Fail (default) - Reject on Mail From Fail.
False - Never reject on Mail From, append header only. This is useful
for post-SMTP spam filters such as SpamAssassin.
No_Check - Never check Mail From/Return Path. This is only recommended
if you are calling the policy server twice (once for HELO checks and
once for Mail From) with two different configuration files. This ap-
proach is useful to get both the HELO and Mail From headers prepended
to a message. It could also be used to do HELO checking only (because
HELO checking has a lower false positive risk than Mail From checking),
but this approach may not be fully RFC 7208 compliant since the Mail
From identity is mandatory if HELO checking does not reach a definitive
result.
Default:
Mail_From_reject = Fail
Mail From PASS RESTRICTION
Mail From Pass Restriction allows integration with other Postfix access
contlols by provding a user supplied name of a postfix access restric-
tion to be applied to a message when the Mail From checking result is
Pass. The indicated restriction must be an action as defined for a
Postfix SMTP server access table access(5) and explained in the Postfix
RESTRICTION CLASS README. The README.per_user_whitelisting file pro-
vided with this distribution provides examples. Note: A mail from pass
restriction will be the returned result even if the helo result would
cause the message to be rejected.
Example:
Mail_From_pass_restriction = mfrom_passed_spf
Default:
None
Limit Rejections To Domains That Send No Mail
No_Mail - Only reject when SPF indicates the host/domain sends no mail.
This option will only cause mail to be rejected if the HELO/Mail From
record is "v=spf1 -all". This option is useful for rejecting mail in
situations where the tolerance for rejecting wanted mail is very low.
It operates on both HELO and Mail From identities if set.
Default:
No_Mail = False
Domain Specific Receiver Policy
Using this option, a list of domains can be defined for special pro-
cessing when messages do not Pass SPF. This can be useful for commonly
spoofed domains that are not yet publishing SPF records with -all.
Specifically, if mail from a domain in this list has a Neutral/Softfail
result, it will be rejected (as if it had a Fail result). If needed,
it is better to do it on a per-domain basis rather than globally.
Example:
Reject_Not_Pass_Domains = aol.com,hotmail.com
Default:
None
Permanent Error Processing
Policy for rejecting due to SPF PermError options are:
True - Reject the message if the SPF result (for HELO or Mail From) is
PermError. This has a higher short-term false positive risk, but does
result in senders getting feedback that they have a problem with their
SPF record.
False - Treat PermError the same as no SPF record at all. This is con-
sistet with the pre-RFC usage (the pre-RFC name for this error was "Un-
known").
This is a global option that affects both HELO and Mail From scopes
when checks for that scope are enabled. The only per scope setting that
can over-ride this is Mail_From/HELO_reject = False/
Default:
PermError_reject = False
Temporary Error Processing
Policy for deferring messages due to SPF TempError options are:
True - Defer the message if the SPF result (for HELO or Mail From) is
TempError. This is the traditional usage and has proven useful in re-
ducing acceptance of unwanted messages. Sometimes spam senders do not
retry. Sometimes by the time a message is retried the sending IP has
made it onto a DNS RBL and can then be rejected. This is not the de-
fault because it is possible for some DNS errors that are classified as
"Temporary" per RFC 7208 to be permanent in the sense that they require
operator intervention to correct.
This is a global option that affects both HELO and Mail From scopes
when checks for that scope are enabled. The only per scope setting that
can over-ride this is Mail_From/HELO_reject = False/
False - Treat TempError the same as no SPF record at all. This is the
default to minimize false positive risk.
Default:
TempError_Defer = False
Prospective SPF Check
Prospective SPF checking - Check to see if mail sent from the defined
IP address would pass. This is useful for outbound MTAs to avoid send-
ing mail that would Fail SPF checks when received. Disable HELO check-
ing when using this option. It's only potentially useful for Mail From
checking. SPF Received headers are not added when this option is used.
Prospective = 192.168.0.4
Default:
None
LOCAL SPF BYPASS LIST
Do not check SPF for localhost addresses - add to skip addresses to
skip SPF for internal networks if desired. Defaults are standard IPv4
and IPv6 localhost addresses. This can also be used, to allow mail from
local clients submitting mail to an MTA also acting as a Mail Submis-
sion Agent (MSA) to be skipped. An x-header is prepended indicating
SPF checks were skipped due to a local address. This is a trace header
only. Note the lack of spaces in the list.
Default:
skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
SPF IP WHITELIST
A comma separated CIDR Notation list of IP addresses to skip SPF checks
for. Use this list to whitelist trusted relays (such as a secondary MX
and trusted forwarders). An x-header is prepended indicating the IP
was whitelisted against SPF checks. This is a trace header only. Note
the lack of spaces in the list.
Example:
Whitelist = 192.168.0.0/31,192.168.1.0/30
Default:
None
SPF HELO WHITELIST
A comma separated HELO/EHLO host names to skip SPF checks for. Use
this list to whitelist trusted relays (such as a secondary MX and
trusted forwarders) or to work around a host with a buggy SPF record.
An x-header is prepended indicating the host was whitelisted against
SPF checks. This is a trace header only. Note the lack of spaces in
the list.
This option includes a check to ensure the connect IP address is refer-
enced in an A or AAAA record by the HELO/EHLO domain that is
whitelisted. This is to avoid inadvertent bypass of SPF checks if
HELO/EHLO names are forged. If a HELO/EHLO domain is unable to pass
such a forward IP address match check, then use an SPF IP Whitelist for
the host's IP address instead.
Example:
HELO_Whitelist = relay.example.com,sender.example.org
Default:
None
SPF DOMAIN WHITELIST
Domain_Whitelist: List of domains whose sending IPs should be
whitelisted from SPF checks. Use this to list trusted forwarders by
domain name. Client IP addresses are tested against SPF records pub-
lished by the listed domains. This is useful for large forwarders with
complex outbound infrastructures and SPF records. This option is less
scalable than the SPF IP Whitelist. An x-header is prepended indicat-
ing the IP was whitelisted against SPF checks. This is a trace header
only. This option does nothing if the domain does not have an SPF
record. In this case use the SPF IP Whitelist described above or Do-
main_Whitelist_PTR (below). Note the lack of spaces in the list.
Example:
Domain_Whitelist = pobox.com,trustedforwarder.org
Default:
None
PTR DOMAIN WHITELIST
Domain_Whitelist_PTR: List of domains (and subdomains) whose sending
IPs should be whitelisted from SPF checks based on PTR match of the do-
main. Use this to list trusted forwarders by domain name if they do not
publish SPF records. Client IP addresses PTR names are tested to see
if they match the listed domains. This is useful for large forwarders
with complex outbound infrastructures, but no SPF records and predict-
able host naming. Matching is done using the same rules as the SPF PTR
mechanism as described in RFC 7208. List the parent domain and all
subdomains will match. This option is less scalable than the SPF IP
Whitelist. An x-header is prepended indicating the IP was whitelisted
against SPF checks. This is a trace header only. This option does
nothing if the host does not have a PTR record record. In this case
use the SPF IP Whitelist described above. Note the lack of spaces in
the list.
Example:
Domain_Whitelist_PTR = yahoo.com,yahoogroups.com
Default:
None
SPF ENHANCED STATUS CODES
By default, Postfix will use the 4/5.7.1 enhanced status code for de-
fer/reject actions from the policy server (originally defined in RFC
1893, RFC 3463 is the current reference). New email authentication
(including SPF) specific codes were defined in RFC 7372. The policy
server now overrides the Postfix enhanced status codes to use the RFC
7372 values. This can be disabled by setting this option to "No" in
the event of interoperability issues.
Example:
SPF_Enhanced_Status_Codes = No
Default:
Yes
RESULTS HEADER
The standard method for documenting SPF results in a message (for con-
sumption by downstream processes) is the Received-SPF header defined in
RFC 7208. This is the default header to use. Results can also be docu-
mented in the Authentication-Results header, which is also covered in
RFC 7208. The default is Received-SPF (SPF), but inclusion of Authenti-
cation-Results (AR) headers as an alternative to Received-SPF can be
specified.
If there is a requirement to prepend both Received-SPF and Authentica-
tion- Results headers, then it must be done by processing the message
with more than one instance of the policy server using different con-
figuration files with different Header_Type settings.
For no header at all, use Header_Type = None.
Examples:
Header_Type = SPF or Header_Type = AR
Default:
SPF
HIDE RCPT TO IN RESULTS HEADER
Both Received-SPF and Authentication-Results (AR) header fields include
the receiving (RCPT TO) address. In this application, it will always
be the first recipient sent by the sending MTA, even if that recipient
is a BCC recipient. This is unavoidable as the Postfix policy inter-
face does not provide any indication that if the recipient is BCC or
not (this information is not available in until after SMTP DATA in the
body of the message). This presents a possible avenue for a privacy
breach.
In order to avoid this, Hide_Receiver is set to Yes by default in the
interest of maximizing privacy. This setting will replace the actual
recipient with <UNKNOWN> both in header fields and SMTP responses. The
latter may make it more difficult for senders to troubleshoot issues
with their SPF deployments. As an implementation detail, currently
specifying any value other than No will result in the recipient being
hidden, but that may change in the future.
Examples:
Hide_Receiver = Yes or Hide_Receiver = No
Default:
True
Authentications Results Authentication Identifier
Every Authentication-Results header field has an authentication identi-
fier field ('Authserv_Id'). This is similar in syntax to a fully-quali-
fied domain name. See policyd-spf.conf.5 and RFC 7001 paragraph 2.4 for
details. Default is HOSTNAME. The results of socket.gethostname will
be used unless an alternate value is specified. An Authserv-Id must be
provided if Header_Type 'AR' is used.
The authentication identifier field provides a unique identifier that
refers to the authenticating service within a given administrative do-
main. The identifier MUST be unique to that domain. This identifier is
intended to be machine-readable and not necessarily meaningful to
users.
Example:
Authserv_Id = mx.example.com
Default:
HOSTNAME
DNS Timeout Limit
RFC 7208 recommends an elapsed time limit for SPF checks of at least 20
seconds. Lookup_Time allows the maximum time (seconds) to be adjusted.
20 seconds is the default. This limit is applied separately to Mail
From and HELO/EHLO checks, so if both are performed, the lookups may
take up to twice Lookup_Time (plus any additional time required for
whitelisting related DNS lookups).
It is important that the combination of Lookup_Time(s) and applicable
Whitelist_Lookup_Time(s) be less than the smtpd_policy_service_timeout
defined for the service (default 100 seconds). Since HELO and Mail
From time limits are independent, smtpd_policy_service_timeout needs to
be at least double the time allowed for the SPF policy server per en-
tity type.
Example:
Lookup_Time = 20
Default
20 (seconds)
Whitelist DNS Timeout Limit
Some of the available whitelisting mechanisms, i.e. Domain_Whitelist,
Domain_Whitelist_PTR, and HELO_Whitelist, require specific non-SPF DNS
lookups to determine if a connection should be white listed from SPF
checks. The maximum amount of time (in seconds) allocated for each of
these checks, when used (none are enabled by default), is controlled by
the Whitelist_Lookup_Time parameter. It defaults to 10 seconds and is
applied independently to each whitelisting method in use (e.g. if both
a Domain_Whitelist_PTR and HELO_Whitelist are defined, together they
may take up to 20 seconds). This is in addition to the time allowed
for SPF Lookup_Time.
It is important that the combination of Lookup_Time(s) and applicable
Whitelist_Lookup_Time(s) be less than the smtpd_policy_service_timeout
defined for the service (default 100 seconds). Since HELO and Mail
From time limits are independent, smtpd_policy_service_timeout needs to
be at least double the time allowed for the SPF policy server per en-
tity type.
Example:
Whitelist_Lookup_Time = 10
Default
10 (seconds)
DNS Void Lookup Limit
RFC 7208 adds a new processing limit called "void lookup limit" (See
section 4.6.4). Void lookups are DNS queries within an SPF record for
which DNS queries return either a positive answer (RCODE 0) with an an-
swer count of 0, or a "Name Error" (RCODE 3) answer. This should not
need to be changed. Although new in an RFC in RFC 7208, this limit has
been widely deployed in the Mail::SPF perl library without issue. De-
fault is 2, but it can be adjusted.
Example:
Void_Limit = 2
Default
2
Mock SPF Check To Add Milter Compatibility Header Field
In some versions of postfix, for bizarre Sendmail compatibility rea-
sons, the first header field added by a policy server is not visible to
milters. To make this easy to work around, set the Mock value to true
and a fixed header field will be inserted so the actual SPF check will
be the second field and visible to milters such as DMARC milter.
To use this feature requires additional postfix configuration to exe-
cute the second, mock, instance of the policy server:
Add a second service to /etc/postfix/master.cf:
policyd-spf-mock unix - n n - 0
spawn
user=nobody argv=/usr/bin/policyd-spf '/etc/pypolicyd-
spf/mock
Configure the Postfix additional policy service in /etc/postfix/main.cf
to run before the regular service:
smtpd_recipient_restrictions =
...
reject_unauth_destination
check_policy_service unix:private/policyd-spf-mock
check_policy_service unix:private/policyd-spf
...
Create the specified configuration file in the location indicated with
Mock set to True.
Example:
Mock = True
Default
False
Reason Message
If a message is rejected or deferred because of the SPF policy, a rea-
son is given for logging and debugging purposes. The String configured
supports the following format specifiers:
rejectdefer - either the string 'rejected' or 'deferred'
spf - SPF result code
url - Parameterized URL to http://www.openspf.net/ ex-
plaining SPF
Example:
Reason_Message = Message {rejectdefer} due to: {spf}.
Default:
Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}
SEE ALSO
man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf,
<http://www.openspf.net>, RFC 7208, RFC 7001, RFC 7372
AUTHORS
This version of policyd-spf was written by Copyright © 2007-2016, Scott
Kitterman <scott@kitterman.com>. It is derived from Tumgreyspf, writ-
ten 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> and
is licensed under the same terms as the program.
policy-spf.conf(5)
Generated by dwww version 1.14 on Fri Jan 24 09:49:26 CET 2025.