1
2policy-spf.conf(5)            File Formats Manual           policy-spf.conf(5)
3
4
5

NAME

7       policyd-spf - policyd-spf python configuration parameters
8

VERSION

10       2.0.0
11
12

USAGE

14       Usage:
15         policyd-spf [/etc/policyd-spf/policyd-spf.conf]
16
17

OTHER DOCUMENTATION

19       This documentation assumes you have read Postfix's README_FILES/
20       SMTPD_POLICY_README and are generally familiar with Sender Policy
21       Framework (SPF).  See RFC 7208 for details.
22
23       man 1 policyd-spf provides general operation documentation for this
24       package.
25
26       man 5 policyd-spf.peruser provides documentation on setting up and
27       using different configuration options on a per user (mail reciepient)
28       basis.
29
30

SYNOPSIS

32       python-policyd-spf operates with a default installed configuration file
33       and set of default configuration options that are used if the configu‐
34       ration file cannot be found.  These options can be changed by changing
35       the installed configuration files or through giving a path to an alter‐
36       nate configuration file.
37
38

DESCRIPTION

40       Configuration options are described here and in the configuration file
41       provided with the package.  The provided setup.py installs this config‐
42       uration file in /etc/policyd-spf/.
43
44       Additionally, whitelisting certain IP addresses from SPF checks is sup‐
45       ported.  This man page and the sample configuration file show the for‐
46       mat to use.  These options can be adjusted on a per user (mail recipi‐
47       ent) basis.  Details on per user settings can be found in policyd-
48       spf.peruser(5).
49
50

OPTIONS

52
53

LOGGING

55       "debugLevel" controls the amount of information logged by the policy
56       server.
57
58       The default, 1, logs no debugging messages, just basic policy results
59       and errors generated through the policy server.  This value can be
60       increased up to 5 (values higher than 5 will not cause an error, but
61       will not log any additional information).
62
63       debug level 2 adds a log message if no client address (IP address from
64       which the connection was made), Mail From address, or HELO/EHLO name is
65       received by the policy server, and logs SPF results for each Mail From
66       and HELO check.
67
68       debug level 3 generates a log message each time the policy server
69       starts and each time it exits, as well as logging a copy of the exact
70       header returned to Postfix to be prepended into the message.  Each time
71       the policy server starts, debug level 3 also logs the configuration
72       information used by the policy server.
73
74       debug level 4 logs the complete data set received by Postfix via the
75       policy interface and when the end of the entry is read.
76
77       debug level 5 is used to debug config file processing and, for this
78       purpose, can only be set in code and not via the config file.  It also
79       provides additional internal status details generally of interest only
80       to developers.
81
82       If debug level is 0, then the policy server logs errors only.
83
84       When set to -1, nothing is logged once the configuration file has been
85       read in, not even error messages.  Use with caution.
86
87       Default:
88
89       debugLevel = 1
90
91

TEST OPERATION

93       The policy server can operate in a test only mode. This allows you to
94       see the potential impact of SPF checking in your mail logs without
95       rejecting mail.  Headers are prepended in messages, but message deliv‐
96       ery is not affected. This mode is not enabled by default.  To enable
97       it, set TestOnly = 0.
98
99       Note: This option was previously named defaultSeedOnly.  This is still
100       accepted, but logs an error.
101
102       Default:
103
104       TestOnly = 1
105
106

HELO/EHLO CHECKING

108       HELO check rejection policy options are:
109
110       Fail - (Default) Reject only on HELO Fail. HELO/EHLO is known first in
111       the SMTP dialogue and there is no practical reason to waste resources
112       on Mail From checks if the HELO check will already cause the message to
113       be rejected.  This should not cause interoperability problems when used
114       for HELO.
115
116       SPF_Not_Pass - Reject if result not Pass, None, or Temperror (alterna‐
117       tively put, reject if the SPF result is Fail, Softfail, Neutral, PermE‐
118       rror). Unlike Mail From checking, there are no standard e-mail use
119       cases where a HELO check should not Pass if there is an SPF record for
120       the HELO name (transparent forwarding, for example, is not an issue).
121       HELO/EHLO is known first in the SMTP dialogue and there is no practical
122       reason to waste resources on Mail From checks if the HELO check will
123       already cause the message to be rejected. This is not consistent with
124       the RFC 7208 requirement to treat none and neutral the same, but should
125       not cause interoperability problems when used for HELO.
126
127       Softfail - Reject on HELO Softfail or Fail.  HELO/EHLO is known first
128       in the SMTP dialogue and there is no practical reason to waste
129       resources on Mail From checks if the HELO check will already cause the
130       message to be rejected.  This should not cause interoperability prob‐
131       lems when used for HELO.
132
133       Null - Only reject HELO Fail for Null sender (SPF Classic).  This is
134       the approach used by the pre-RFC 4408 reference implementation and many
135       of the pre- RFC specifications.  Use of at least this option
136       (SPF_Not_Pass or Fail) are preferred) is highly recommended.
137
138       False - Never reject on HELO, append header only. This is useful for
139       post-SMTP spam filters such as SpamAssassin.
140
141       No_Check - Never check HELO.  This is only recommended if you are call‐
142       ing the policy server twice (once for HELO checks and once for Mail
143       From) with two different configuration files.  This approach is useful
144       to get both the HELO and Mail From headers prepended to a message.
145
146       Default:
147
148       HELO_reject = Fail
149
150

HELO/EHLO PASS RESTRICTION

152       HELO Pass Restriction allows integration with other Postfix access con‐
153       trols by provding a user supplied name of a postfix access restriction
154       to be applied to a message when the HELO checking result is Pass.  The
155       indicated restriction must be an action as defined for a Postfix SMTP
156       server access table access(5) and explained in the Postfix RESTRICTION
157       CLASS README. The README.per_user_whitelisting file provided with this
158       distribution provides examples. Note: A helo pass restriction will be
159       the returned result even if the mail from result would cause the mes‐
160       sage to be rejected.
161
162
163       Example:
164
165       HELO_pass_restriction = helo_passed_spf
166
167       Default:
168
169       None
170
171

Mail From CHECKING

173       Mail From rejection policy options are:
174
175       SPF_Not_Pass - Reject if result not Pass/None/Tempfail. This option is
176       not RFC 7208 compliant since the mail with an SPF Neutral result is
177       treated differently than mail with no SPF record and Softfail results
178       are not supposed to cause mail rejection.  Global use of this option is
179       not recommended. Use per-domain if needed (per-domain usage described
180       below).
181
182       Softfail - Reject on Mail From Softfail or Fail.  Global use of this
183       option is not recommended. Use per-domain if needed (per-domain usage
184       described below).
185
186       Fail (default) - Reject on Mail From Fail.
187
188       False - Never reject on Mail From, append header only.  This is useful
189       for post-SMTP spam filters such as SpamAssassin.
190
191       No_Check - Never check Mail From/Return Path.  This is only recommended
192       if you are calling the policy server twice (once for HELO checks and
193       once for Mail From) with two different configuration files.  This
194       approach is useful to get both the HELO and Mail From headers prepended
195       to a message.  It could also be used to do HELO checking only (because
196       HELO checking has a lower false positive risk than Mail From checking),
197       but this approach may not be fully RFC 7208 compliant since the Mail
198       From identity is mandatory if HELO checking does not reach a definitive
199       result.
200
201       Default:
202
203       Mail_From_reject = Fail
204
205

Mail From PASS RESTRICTION

207       Mail From Pass Restriction allows integration with other Postfix access
208       contlols by provding a user supplied name of a postfix access restric‐
209       tion to be applied to a message when the Mail From checking result is
210       Pass.  The indicated restriction must be an action as defined for a
211       Postfix SMTP server access table access(5) and explained in the Postfix
212       RESTRICTION CLASS README. The README.per_user_whitelisting file pro‐
213       vided with this distribution provides examples. Note: A mail from pass
214       restriction will be the returned result even if the helo result would
215       cause the message to be rejected.
216
217       Example:
218
219       Mail_From_pass_restriction = mfrom_passed_spf
220
221       Default:
222
223       None
224
225

Limit Rejections To Domains That Send No Mail

227       No_Mail - Only reject when SPF indicates the host/domain sends no mail.
228       This option will only cause mail to be rejected if the HELO/Mail From
229       record is "v=spf1 -all".  This option is useful for rejecting mail in
230       situations where the tolerance for rejecting wanted mail is very low.
231       It operates on both HELO and Mail From identities if set.
232
233       Default:
234
235       No_Mail = False
236
237

Domain Specific Receiver Policy

239       Using this option, a list of domains can be defined for special pro‐
240       cessing when messages do not Pass SPF.  This can be useful for commonly
241       spoofed domains that are not yet publishing SPF records with -all.
242       Specifically, if mail from a domain in this list has a Neutral/Softfail
243       result, it will be rejected (as if it had a Fail result).  If needed,
244       it is better to do it on a per-domain basis rather than globally.
245
246       Example:
247
248       Reject_Not_Pass_Domains = aol.com,hotmail.com
249
250       Default:
251
252       None
253
254

Permanent Error Processing

256       Policy for rejecting due to SPF PermError options are:
257
258       True - Reject the message if the SPF result (for HELO or Mail From) is
259       PermError.  This has a higher short-term false positive risk, but does
260       result in senders getting feedback that they have a problem with their
261       SPF record.
262
263       False - Treat PermError the same as no SPF record at all.  This is con‐
264       sistet with the pre-RFC usage (the pre-RFC name for this error was
265       "Unknown").
266
267       This is a global option that affects both HELO and Mail From scopes
268       when checks for that scope are enabled. The only per scope setting that
269       can over-ride this is Mail_From/HELO_reject = False/
270
271       Default:
272
273       PermError_reject = False
274
275

Temporary Error Processing

277       Policy for deferring messages due to SPF TempError options are:
278
279       True - Defer the message if the SPF result (for HELO or Mail From) is
280       TempError.  This is the traditional usage and has proven useful in
281       reducing acceptance of unwanted messages.  Sometimes spam senders do
282       not retry.  Sometimes by the time a message is retried the sending IP
283       has made it onto a DNS RBL and can then be rejected.  This is not the
284       default because it is possible for some DNS errors that are classified
285       as "Temporary" per RFC 7208 to be permanent in the sense that they
286       require operator intervention to correct.
287
288       This is a global option that affects both HELO and Mail From scopes
289       when checks for that scope are enabled. The only per scope setting that
290       can over-ride this is Mail_From/HELO_reject = False/
291
292       False - Treat TempError the same as no SPF record at all.  This is the
293       default to minimize false positive risk.
294
295       Default:
296
297       TempError_Defer = False
298
299

Prospective SPF Check

301       Prospective SPF checking - Check to see if mail sent from the defined
302       IP address would pass.  This is useful for outbound MTAs to avoid send‐
303       ing mail that would Fail SPF checks when received.  Disable HELO check‐
304       ing when using this option.  It's only potentially useful for Mail From
305       checking. SPF Received headers are not added when this option is used.
306
307       Prospective = 192.168.0.4
308
309       Default:
310
311       None
312
313

LOCAL SPF BYPASS LIST

315       Do not check SPF for localhost addresses - add to skip addresses to
316       skip SPF for internal networks if desired. Defaults are standard IPv4
317       and IPv6 localhost addresses. This can also be used, to allow mail from
318       local clients submitting mail to an MTA also acting as a Mail Submis‐
319       sion Agent (MSA) to be skipped.  An x-header is prepended indicating
320       SPF checks were skipped due to a local address.  This is a trace header
321       only.  Note the lack of spaces in the list.
322
323       Default:
324
325       skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
326
327

SPF IP WHITELIST

329       A comma separated CIDR Notation list of IP addresses to skip SPF checks
330       for.  Use this list to whitelist trusted relays (such as a secondary MX
331       and trusted forwarders).  An x-header is prepended indicating the IP
332       was whitelisted against SPF checks.  This is a trace header only.  Note
333       the lack of spaces in the list.
334
335       Example:
336
337       Whitelist = 192.168.0.0/31,192.168.1.0/30
338
339       Default:
340
341       None
342
343

SPF HELO WHITELIST

345       A comma separated HELO/EHLO host names to skip SPF checks for.  Use
346       this list to whitelist trusted relays (such as a secondary MX and
347       trusted forwarders) or to work around a host with a buggy SPF record.
348       An x-header is prepended indicating the host was whitelisted against
349       SPF checks.  This is a trace header only.  Note the lack of spaces in
350       the list.
351
352       This option includes a check to ensure the connect IP address is refer‐
353       enced in an A or AAAA record by the HELO/EHLO domain that is
354       whitelisted.  This is to avoid inadvertent bypass of SPF checks if
355       HELO/EHLO names are forged.  If a HELO/EHLO domain is unable to pass
356       such a forward IP address match check, then use an SPF IP Whitelist for
357       the host's IP address instead.
358
359       Example:
360
361       HELO_Whitelist = relay.example.com,sender.example.org
362
363       Default:
364
365       None
366
367

SPF DOMAIN WHITELIST

369       Domain_Whitelist: List of domains whose sending IPs should be
370       whitelisted from SPF checks.  Use this to list trusted forwarders by
371       domain name.  Client IP addresses are tested against SPF records pub‐
372       lished by the listed domains.  This is useful for large forwarders with
373       complex outbound infrastructures and SPF records.  This option is less
374       scalable than the SPF IP Whitelist.  An x-header is prepended indicat‐
375       ing the IP was whitelisted against SPF checks.  This is a trace header
376       only.  This option does nothing if the domain does not have an SPF
377       record.  In this case use the SPF IP Whitelist described above or
378       Domain_Whitelist_PTR (below). Note the lack of spaces in the list.
379
380       Example:
381
382       Domain_Whitelist = pobox.com,trustedforwarder.org
383
384       Default:
385
386       None
387
388

PTR DOMAIN WHITELIST

390       Domain_Whitelist_PTR: List of domains (and subdomains)  whose sending
391       IPs should be whitelisted from SPF checks based on PTR match of the
392       domain. Use this to list trusted forwarders by domain name if they do
393       not publish SPF records.  Client IP addresses PTR names are tested to
394       see if they match the listed domains.  This is useful for large for‐
395       warders with complex outbound infrastructures, but no SPF records and
396       predictable host naming. Matching is done using the same rules as the
397       SPF PTR mechanism as described in RFC 7208.  List the parent domain and
398       all subdomains will match. This option is less scalable than the SPF IP
399       Whitelist.  An x-header is prepended indicating the IP was whitelisted
400       against SPF checks.  This is a trace header only.  This option does
401       nothing if the host does not have a PTR record record.  In this case
402       use the SPF IP Whitelist described above. Note the lack of spaces in
403       the list.
404
405       Example:
406
407       Domain_Whitelist_PTR = yahoo.com,yahoogroups.com
408
409       Default:
410
411       None
412
413

SPF ENHANCED STATUS CODES

415       By default, Postfix will use the 4/5.7.1 enhanced status code for
416       defer/reject actions from the policy server (originally defined in RFC
417       1893, RFC 3463 is the current reference).  New email authentication
418       (including SPF) specific codes were defined in RFC 7372.  The policy
419       server now overrides the Postfix enhanced status codes to use the RFC
420       7372 values.  This can be disabled by setting this option to "No" in
421       the event of interoperability issues.
422
423       Example:
424
425       SPF_Enhanced_Status_Codes = No
426
427       Default:
428
429       Yes
430
431

RESULTS HEADER

433       The standard method for documenting SPF results in a message (for con‐
434       sumption by downstream processes) is the Received-SPF header defined in
435       RFC 7208. This is the default header to use. Results can also be docu‐
436       mented in the Authentication-Results header, which is also covered in
437       RFC 7208. The default is Received-SPF (SPF), but inclusion of Authenti‐
438       cation-Results (AR) headers as an alternative to Received-SPF can be
439       specified.
440
441       If there is a requirement to prepend both Received-SPF and Authentica‐
442       tion- Results headers, then it must be done by processing the message
443       with more than one instance of the policy server using different con‐
444       figuration files with different Header_Type settings.
445
446       For no header at all, use Header_Type = None.
447
448       Examples:
449
450       Header_Type = SPF or Header_Type = AR
451
452       Default:
453
454       SPF
455
456

HIDE RCPT TO IN RESULTS HEADER

458       Both Received-SPF and Authentication-Results (AR) header fields include
459       the receiving (RCPT TO) address.  In this application, it will always
460       be the first recipient sent by the sending MTA, even if that recipient
461       is a BCC recipient.  This is unavoidable as the Postfix policy inter‐
462       face does not provide any indication that if the recipient is BCC or
463       not (this information is not available in until after SMTP DATA in the
464       body of the message).  This presents a possible avenue for a privacy
465       breach.
466
467       In order to avoid this, Hide_Receiver is set to Yes by default in the
468       interest of maximizing privacy.  This setting will replace the actual
469       recipient with <UNKNOWN> both in header fields and SMTP responses.  The
470       latter may make it more difficult for senders to troubleshoot issues
471       with their SPF deployments.  As an implementation detail, currently
472       specifying any value other than No will result in the recipient being
473       hidden, but that may change in the future.
474
475       Examples:
476
477       Hide_Receiver = Yes or Hide_Receiver = No
478
479       Default:
480
481       True
482
483

Authentications Results Authentication Identifier

485       Every Authentication-Results header field has an authentication identi‐
486       fier field ('Authserv_Id'). This is similar in syntax to a fully-quali‐
487       fied domain name. See policyd-spf.conf.5 and RFC 7001 paragraph 2.4 for
488       details.  Default is HOSTNAME. The results of socket.gethostname will
489       be used unless an alternate value is specified.  An Authserv-Id must be
490       provided if Header_Type 'AR' is used.
491
492       The authentication identifier field provides a unique identifier that
493       refers to the authenticating service within a given administrative
494       domain. The identifier MUST be unique to that domain.  This identifier
495       is intended to be machine-readable and not necessarily meaningful to
496       users.
497
498       Example:
499
500       Authserv_Id = mx.example.com
501
502       Default:
503
504       HOSTNAME
505
506

DNS Timeout Limit

508       RFC 7208 recommends an elapsed time limit for SPF checks of at least 20
509       seconds.  Lookup_Time allows the maximum time (seconds) to be adjusted.
510       20 seconds is the default.  This limit is applied separately to Mail
511       From and HELO/EHLO checks, so if both are performed, the lookups may
512       take up to twice Lookup_Time (plus any additional time required for
513       whitelisting related DNS lookups).
514
515       Example:
516
517       Lookup_Time = 20
518
519       Default
520
521       20 (seconds)
522
523

Whitelist DNS Timeout Limit

525       Some of the available whitelisting mechanisms, i.e. Domain_Whitelist,
526       Domain_Whitelist_PTR, and HELO_Whitelist, require specific non-SPF DNS
527       lookups to determine if a connection should be white listed from SPF
528       checks.  The maximum amount of time (in seconds) allocated for each of
529       these checks, when used (none are enabled by default), is controlled by
530       the Whitelist_Lookup_Time parameter.  It defaults to 10 seconds and is
531       applied independently to each whitelisting method in use (e.g. if both
532       a Domain_Whitelist_PTR and HELO_Whitelist are defined, together they
533       may take up to 20 seconds).  This is in addition to the time allowed
534       for SPF Lookup_Time.
535
536       Example:
537
538       Whitelist_Lookup_Time = 10
539
540       Default
541
542       10 (seconds)
543
544

DNS Void Lookup Limit

546       RFC 7208 adds a new processing limit called "void lookup limit" (See
547       section 4.6.4).  Void lookups are DNS queries within an SPF record for
548       which DNS queries return either a positive answer (RCODE 0) with an
549       answer count of 0, or a "Name Error" (RCODE 3) answer.  This should not
550       need to be changed.  Although new in an RFC in RFC 7208, this limit has
551       been widely deployed in the Mail::SPF perl library without issue.
552       Default is 2, but it can be adjusted.
553
554       Example:
555
556       Void_Limit = 2
557
558       Default
559
560       2
561
562

Mock SPF Check To Add Milter Compatibility Header Field

564       In some versions of postfix, for bizarre Sendmail compatibility rea‐
565       sons, the first header field added by a policy server is not visible to
566       milters.  To make this easy to work around, set the Mock value to true
567       and a fixed header field will be inserted so the actual SPF check will
568       be the second field and visible to milters such as DMARC milter.
569
570       To use this feature requires additional postfix configuration to exe‐
571       cute the second, mock, instance of the policy server:
572
573        Add a second service to /etc/postfix/master.cf:
574
575               policyd-spf-mock  unix  -       n       n       -       0
576       spawn
577                   user=nobody argv=/usr/bin/policyd-spf '/etc/pypolicyd-
578       spf/mock
579
580       Configure the Postfix additional policy service in /etc/postfix/main.cf
581       to run before the regular service:
582
583               smtpd_recipient_restrictions =
584                   ...
585                   reject_unauth_destination
586                   check_policy_service unix:private/policyd-spf-mock
587                   check_policy_service unix:private/policyd-spf
588                   ...
589
590       Create the specified configuration file in the location indicated with
591       Mock set to True.
592
593       Example:
594
595       Mock = True
596
597       Default
598
599       False
600
601

Reason Message

603       If a message is rejected or deferred because of the SPF policy, a rea‐
604       son is given for logging and debugging purposes. The String configured
605       supports the following format specifiers:
606
607              rejectdefer - either the string 'rejected' or 'deferred'
608
609              spf         - SPF result code
610
611              url         - Parameterized URL to http://www.openspf.net/
612              explaining SPF
613
614       Example:
615
616       Reason_Message = Message {rejectdefer} due to: {spf}.
617
618       Default:
619
620       Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}
621
622

SEE ALSO

624       man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf,
625       <http://www.openspf.net>, RFC 7208, RFC 7001, RFC 7372
626
627

AUTHORS

629       This version of policyd-spf was written by Copyright © 2007-2016, Scott
630       Kitterman <scott@kitterman.com>.  It is derived from Tumgreyspf, writ‐
631       ten by Sean Reifschneider, tummy.com, ltd <jafo@tummy.com>. Portions of
632       the documentation were written by Meng Weng Wong <mengwong@pobox.com>.
633
634       This man-page was created by Scott Kitterman <scott@kitterman.com> and
635       is licensed under the same terms as the program.
636
637
638
639                                                            policy-spf.conf(5)
Impressum