Provided by: postfix-policyd-spf-python_2.9.3-1_all bug

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 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 policy 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 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 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, 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 rejecting 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 (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). 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 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.

       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 = Fail

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 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 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 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 restriction 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 provided 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 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).  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 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 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 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 referenced 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 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
       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 defer/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 consumption by
       downstream processes) is the Received-SPF header defined in RFC 7208. This is the default
       header to use. Results can also be documented in the Authentication-Results header, which
       is also covered in  RFC 7208. 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.

       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 interface 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 identifier field
       ('Authserv_Id'). This is similar in syntax to a fully-qualified 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 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

       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 entity 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 entity 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 answer 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.  Default 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 reasons, 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 execute 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 reason 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/ explaining 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, 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> and is licensed under
       the same terms as the program.

                                                                               policy-spf.conf(5)