Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 [/usr/local/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 /usr/local/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.

       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).

       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.

       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 A(C) 2007-2016,
       Scott Kitterman <scott@kitterman.com>.  It is derived from Tumgreyspf,
       written by Sean Reifschneider, tummy.com, ltd <jafo@tummy.com>. Por-
       tions of	the documentation were written by Meng Weng Wong <meng-
       wong@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)

NAME | VERSION | USAGE | OTHER DOCUMENTATION | SYNOPSIS | DESCRIPTION | OPTIONS | LOGGING | TEST OPERATION | HELO/EHLO CHECKING | HELO/EHLO PASS RESTRICTION | Mail From CHECKING | Mail From PASS RESTRICTION | Limit Rejections To Domains That Send No Mail | Domain Specific Receiver Policy | Permanent Error Processing | Temporary Error Processing | Prospective SPF Check | LOCAL SPF BYPASS LIST | SPF IP WHITELIST | SPF HELO WHITELIST | SPF DOMAIN WHITELIST | PTR DOMAIN WHITELIST | SPF ENHANCED STATUS CODES | RESULTS HEADER | HIDE RCPT TO IN RESULTS HEADER | Authentications Results Authentication Identifier | DNS Timeout Limit | Whitelist DNS Timeout Limit | DNS Void Lookup Limit | Mock SPF Check To Add Milter Compatibility Header Field | Reason Message | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=policyd-spf.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help