Provided by: postfix-policyd-spf-python_1.2-1_all 
NAME
python-policyd-spf - pure-Python Postfix policy daemon for SPF checking
VERSION
1.1.1
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 4408 for details.
man 1 policyd-spf provides general operation documentation for this package.
man 5 policyd-spf.peruser provides documentation on setting up and using different
configuration options on a per user (mail reciepient) basis.
SYNOPSIS
python-policyd-spf operates with a default installed configuration file and set of default
configuration options that are used if the configuration file cannot be found. These
options can be changed by changing the installed configuration files or through giving a
path to an alternate configuration file.
DESCRIPTION
Configuration options are described here and in the configuration file provided with the
package. The provided setup.py installs this configuration file in /etc/postfix-policyd-
spf-python/.
Additionally, whitelisting certain IP addresses from SPF checks is supported. This man
page and the sample configuration file show the format to use. These options can be
adjusted on a per user (mail recipient) 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 SPF results and errors generated
through the policy server. This value can be increased 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 addresss, 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 information 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 can only be set in code and not
via the config file.
If debug level is 0, then the policy server logs errors only.
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 rejecting mail. Headers are prepended in
messages, but message delivery is not affected. This mode is not enabled by default. To
enable it, set defaultSeedOnly = 0.
Default:
defaultSeedOnly = 1
HELO/EHLO CHECKING
HELO check rejection policy options are:
SPF_Not_Pass (default) - Reject if result not Pass, None, or Temperror (alternatively put,
reject if the SPF result is Fail, Softfail, Neutral, PermError). 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). Technically this option is not fully RFC 4408 compliant since the SPF check for
the Mail From identity is mandatory and Neutral and None results must be treated the same.
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. These deviations should not cause interoperability problems when used for HELO.
Softfail - Reject on HELO Softfail or Fail. Technically this option is not fully RFC 4408
compliant since the Mail From identity is mandatory, but 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.
Fail - Reject only on HELO Fail. Technically this option is not fully RFC 4408 compliant
since the Mail From identity is mandatory, but 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.
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 calling 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 = SPF_Not_Pass
HELO/EHLO PASS RESTRICTION
HELO Pass Restriction allows integration with other Postfix access controls 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 message 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 4408
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 HELO Softfail or Fail. Technically this option is not fully RFC 4408
compliant since 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).
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 approach 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 would
not be fully RFC 4408 compliant since the Mail From identity is mandatory.
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 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. 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 processing 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). This option is
not supported by RFC 4408, but 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 consistet with the pre-
RFC usage (the pre-RFC name for this error was "Unknown").
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 reducing 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 default
because it is possible for some DNS errors that are classified as "Temporary" per RFC 4408
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 sending mail that would Fail SPF checks
when received. Disable HELO checking 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 Submission 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 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 published 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 indicating 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
Domain_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 domain. 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 predictable host
naming. Matching is done using the same rules as the SPF PTR mechanism as described in RFC
4408. 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
RESULTS HEADER
The standard method for documenting SPF results in a message (for consumption by
downstream processes) is the Received-SPF header defined in RFC 4408. This is the default
header to use. Results can also be documented in the Authentication-Results header defined
by RFC 5451. The default is Received-SPF (SPF), but inclusion of Authentication-Results
(AR) headers as an alternative to Received-SPF can be specified.
If there is a requirement to prepend both Received-SPF and Authentication- Results
headers, then it must be done by processing the message with more than one instance of the
policy server using different configuration files with different Header_Type settings.
Examples:
Header_Type = SPF or Header_Type = AR
Default:
SPF
Authentications Results Authentication Identifier
Every Authentication-Results header field has an authentication identifier field
('Authserv_Id'). This is similar in syntax to a fully-qualified domain name. See policyd-
spf.conf.5 and RFC 5451 paragraph 2.3 for details. Default is None. 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 domain. 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
SEE ALSO
man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf, <http://www.openspf.net>, RFC
4408, RFC 5451
AUTHORS
This version of pypolicyd-spf was written by Copyright © 2007-2012, 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>.
2012-03-17 policy-spf.conf(5)