NAME

VERSION

USAGE

OTHER DOCUMENTATION

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

DESCRIPTION

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

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

Note: This option was previously named defaultSeedOnly. This is still accepted, but logs an error.

Default:

TestOnly = 1

HELO/EHLO CHECKING

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

Example:

HELO_pass_restriction = helo_passed_spf

Default:

None

Mail From CHECKING

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

Example:

Mail_From_pass_restriction = mfrom_passed_spf

Default:

None

Limit Rejections To Domains That Send No Mail

Default:

No_Mail = False

Domain Specific Receiver Policy

Example:

Reject_Not_Pass_Domains = aol.com,hotmail.com

Default:

None

Permanent Error Processing

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

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

Default:

None

LOCAL SPF BYPASS LIST

Default:

skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1

SPF IP WHITELIST

Example:

Whitelist = 192.168.0.0/31,192.168.1.0/30

Default:

None

SPF HELO WHITELIST

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

Example:

Domain_Whitelist = pobox.com,trustedforwarder.org

Default:

None

PTR DOMAIN WHITELIST

Example:

Domain_Whitelist_PTR = yahoo.com,yahoogroups.com

Default:

None

SPF ENHANCED STATUS CODES

Example:

SPF_Enhanced_Status_Codes = No

Default:

Yes

RESULTS HEADER

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

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

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

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

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

Example:

Void_Limit = 2

Default

2

Mock SPF Check To Add Milter Compatibility Header Field

To use this feature requires additional postfix configuration to execute the second, mock, instance of the policy server:

Add a second service to /usr/local/etc/postfix/master.cf:

policyd-spf-mock unix - n n - 0 spawn user=nobody argv=/usr/local/bin/policyd-spf '/usr/local/etc/pypolicyd-spf/mock

Configure the Postfix additional policy service in /usr/local/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

Example:

Reason_Message = Message {rejectdefer} due to: {spf}.

Default:

Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}

SEE ALSO

AUTHORS

This man-page was created by Scott Kitterman <scott@kitterman.com> and is licensed under the same terms as the program.