NAME

VERSION

1.0

USAGE

Usage:
policyd-spf [/etc/postfix-policyd-spf-python/policyd-spf.conf]

OTHERDOCUMENTATION

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

TESTOPERATION

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/EHLOCHECKING

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/EHLOPASSRESTRICTION

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

MailFromCHECKING

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

MailFromPASSRESTRICTION

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

LimitRejectionsToDomainsThatSendNoMail

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

DomainSpecificReceiverPolicy

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

PermanentErrorProcessing

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

TemporaryErrorProcessing

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

ProspectiveSPFCheck

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

LOCALSPFBYPASSLIST

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//128

SPFIPWHITELIST

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

SPFDOMAINWHITELIST

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

PTRDOMAINWHITELIST

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

RESULTSHEADER

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

AuthenticationsResultsAuthenticationIdentifier

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