1policy-spf.conf(5) File Formats Manual policy-spf.conf(5)
3
7 policyd-spf - policyd-spf python configuration parameters
8
10 2.0.0
11
14 Usage:
15 policyd-spf [/etc/policyd-spf/policyd-spf.conf]
16
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 man 1 policyd-spf provides general operation documentation for this
24 package.
25 man 5 policyd-spf.peruser provides documentation on setting up and us‐
27 ing different configuration options on a per user (mail reciepient) ba‐
28 sis.
29
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
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 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
52
55 "debugLevel" controls the amount of information logged by the policy
56 server.
57 The default, 1, logs no debugging messages, just basic policy results
59 and errors generated through the policy server. This value can be in‐
60 creased up to 5 (values higher than 5 will not cause an error, but will
61 not log any additional information).
62 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 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 in‐
72 formation used by the policy server.
73 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 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 If debug level is 0, then the policy server logs errors only.
83 When set to -1, nothing is logged once the configuration file has been
85 read in, not even error messages. Use with caution.
86 Default:
88 debugLevel = 1
90
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 re‐
95 jecting mail. Headers are prepended in messages, but message delivery
96 is not affected. This mode is not enabled by default. To enable it,
97 set TestOnly = 0. If you want test operation with no header added,
98 also set Header_Type = None.
99 Note: This option was previously named defaultSeedOnly. This is still
101 accepted, but logs an error.
102 Default:
104 TestOnly = 1
106
109 HELO check rejection policy options are:
110 Fail - (Default) Reject only on HELO Fail. HELO/EHLO is known first in
112 the SMTP dialogue and there is no practical reason to waste resources
113 on Mail From checks if the HELO check will already cause the message to
114 be rejected. This should not cause interoperability problems when used
115 for HELO.
116 SPF_Not_Pass - Reject if result not Pass, None, or Temperror (alterna‐
118 tively put, reject if the SPF result is Fail, Softfail, Neutral, PermE‐
119 rror). Unlike Mail From checking, there are no standard e-mail use
120 cases where a HELO check should not Pass if there is an SPF record for
121 the HELO name (transparent forwarding, for example, is not an issue).
122 HELO/EHLO is known first in the SMTP dialogue and there is no practical
123 reason to waste resources on Mail From checks if the HELO check will
124 already cause the message to be rejected. This is not consistent with
125 the RFC 7208 requirement to treat none and neutral the same, but should
126 not cause interoperability problems when used for HELO.
127 Softfail - Reject on HELO Softfail or Fail. HELO/EHLO is known first
129 in the SMTP dialogue and there is no practical reason to waste re‐
130 sources on Mail From checks if the HELO check will already cause the
131 message to be rejected. This should not cause interoperability prob‐
132 lems when used for HELO.
133 Null - Only reject HELO Fail for Null sender (SPF Classic). This is
135 the approach used by the pre-RFC 4408 reference implementation and many
136 of the pre- RFC specifications. Use of at least this option
137 (SPF_Not_Pass or Fail) are preferred) is highly recommended.
138 False - Never reject on HELO, append header only. This is useful for
140 post-SMTP spam filters such as SpamAssassin.
141 No_Check - Never check HELO. This is only recommended if you are call‐
143 ing the policy server twice (once for HELO checks and once for Mail
144 From) with two different configuration files. This approach is useful
145 to get both the HELO and Mail From headers prepended to a message.
146 Default:
148 HELO_reject = Fail
150
153 HELO Pass Restriction allows integration with other Postfix access con‐
154 trols by provding a user supplied name of a postfix access restriction
155 to be applied to a message when the HELO checking result is Pass. The
156 indicated restriction must be an action as defined for a Postfix SMTP
157 server access table access(5) and explained in the Postfix RESTRICTION
158 CLASS README. The README.per_user_whitelisting file provided with this
159 distribution provides examples. Note: A helo pass restriction will be
160 the returned result even if the mail from result would cause the mes‐
161 sage to be rejected.
162 Example:
165 HELO_pass_restriction = helo_passed_spf
167 Default:
169 None
171
174 Mail From rejection policy options are:
175 SPF_Not_Pass - Reject if result not Pass/None/Tempfail. This option is
177 not RFC 7208 compliant since the mail with an SPF Neutral result is
178 treated differently than mail with no SPF record and Softfail results
179 are not supposed to cause mail rejection. Global use of this option is
180 not recommended. Use per-domain if needed (per-domain usage described
181 below).
182 Softfail - Reject on Mail From Softfail or Fail. Global use of this
184 option is not recommended. Use per-domain if needed (per-domain usage
185 described below).
186 Fail (default) - Reject on Mail From Fail.
188 False - Never reject on Mail From, append header only. This is useful
190 for post-SMTP spam filters such as SpamAssassin.
191 No_Check - Never check Mail From/Return Path. This is only recommended
193 if you are calling the policy server twice (once for HELO checks and
194 once for Mail From) with two different configuration files. This ap‐
195 proach is useful to get both the HELO and Mail From headers prepended
196 to a message. It could also be used to do HELO checking only (because
197 HELO checking has a lower false positive risk than Mail From checking),
198 but this approach may not be fully RFC 7208 compliant since the Mail
199 From identity is mandatory if HELO checking does not reach a definitive
200 result.
201 Default:
203 Mail_From_reject = Fail
205
208 Mail From Pass Restriction allows integration with other Postfix access
209 contlols by provding a user supplied name of a postfix access restric‐
210 tion to be applied to a message when the Mail From checking result is
211 Pass. The indicated restriction must be an action as defined for a
212 Postfix SMTP server access table access(5) and explained in the Postfix
213 RESTRICTION CLASS README. The README.per_user_whitelisting file pro‐
214 vided with this distribution provides examples. Note: A mail from pass
215 restriction will be the returned result even if the helo result would
216 cause the message to be rejected.
217 Example:
219 Mail_From_pass_restriction = mfrom_passed_spf
221 Default:
223 None
225
228 No_Mail - Only reject when SPF indicates the host/domain sends no mail.
229 This option will only cause mail to be rejected if the HELO/Mail From
230 record is "v=spf1 -all". This option is useful for rejecting mail in
231 situations where the tolerance for rejecting wanted mail is very low.
232 It operates on both HELO and Mail From identities if set.
233 Default:
235 No_Mail = False
237
240 Using this option, a list of domains can be defined for special pro‐
241 cessing when messages do not Pass SPF. This can be useful for commonly
242 spoofed domains that are not yet publishing SPF records with -all.
243 Specifically, if mail from a domain in this list has a Neutral/Softfail
244 result, it will be rejected (as if it had a Fail result). If needed,
245 it is better to do it on a per-domain basis rather than globally.
246 Example:
248 Reject_Not_Pass_Domains = aol.com,hotmail.com
250 Default:
252 None
254
257 Policy for rejecting due to SPF PermError options are:
258 True - Reject the message if the SPF result (for HELO or Mail From) is
260 PermError. This has a higher short-term false positive risk, but does
261 result in senders getting feedback that they have a problem with their
262 SPF record.
263 False - Treat PermError the same as no SPF record at all. This is con‐
265 sistet with the pre-RFC usage (the pre-RFC name for this error was "Un‐
266 known").
267 This is a global option that affects both HELO and Mail From scopes
269 when checks for that scope are enabled. The only per scope setting that
270 can over-ride this is Mail_From/HELO_reject = False/
271 Default:
273 PermError_reject = False
275
278 Policy for deferring messages due to SPF TempError options are:
279 True - Defer the message if the SPF result (for HELO or Mail From) is
281 TempError. This is the traditional usage and has proven useful in re‐
282 ducing acceptance of unwanted messages. Sometimes spam senders do not
283 retry. Sometimes by the time a message is retried the sending IP has
284 made it onto a DNS RBL and can then be rejected. This is not the de‐
285 fault because it is possible for some DNS errors that are classified as
286 "Temporary" per RFC 7208 to be permanent in the sense that they require
287 operator intervention to correct.
288 This is a global option that affects both HELO and Mail From scopes
290 when checks for that scope are enabled. The only per scope setting that
291 can over-ride this is Mail_From/HELO_reject = False/
292 False - Treat TempError the same as no SPF record at all. This is the
294 default to minimize false positive risk.
295 Default:
297 TempError_Defer = False
299
302 Prospective SPF checking - Check to see if mail sent from the defined
303 IP address would pass. This is useful for outbound MTAs to avoid send‐
304 ing mail that would Fail SPF checks when received. Disable HELO check‐
305 ing when using this option. It's only potentially useful for Mail From
306 checking. SPF Received headers are not added when this option is used.
307 Prospective = 192.168.0.4
309 Default:
311 None
313
316 Do not check SPF for localhost addresses - add to skip addresses to
317 skip SPF for internal networks if desired. Defaults are standard IPv4
318 and IPv6 localhost addresses. This can also be used, to allow mail from
319 local clients submitting mail to an MTA also acting as a Mail Submis‐
320 sion Agent (MSA) to be skipped. An x-header is prepended indicating
321 SPF checks were skipped due to a local address. This is a trace header
322 only. Note the lack of spaces in the list.
323 Default:
325 skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
327
330 A comma separated CIDR Notation list of IP addresses to skip SPF checks
331 for. Use this list to whitelist trusted relays (such as a secondary MX
332 and trusted forwarders). An x-header is prepended indicating the IP
333 was whitelisted against SPF checks. This is a trace header only. Note
334 the lack of spaces in the list.
335 Example:
337 Whitelist = 192.168.0.0/31,192.168.1.0/30
339 Default:
341 None
343
346 A comma separated HELO/EHLO host names to skip SPF checks for. Use
347 this list to whitelist trusted relays (such as a secondary MX and
348 trusted forwarders) or to work around a host with a buggy SPF record.
349 An x-header is prepended indicating the host was whitelisted against
350 SPF checks. This is a trace header only. Note the lack of spaces in
351 the list.
352 This option includes a check to ensure the connect IP address is refer‐
354 enced in an A or AAAA record by the HELO/EHLO domain that is
355 whitelisted. This is to avoid inadvertent bypass of SPF checks if
356 HELO/EHLO names are forged. If a HELO/EHLO domain is unable to pass
357 such a forward IP address match check, then use an SPF IP Whitelist for
358 the host's IP address instead.
359 Example:
361 HELO_Whitelist = relay.example.com,sender.example.org
363 Default:
365 None
367
370 Domain_Whitelist: List of domains whose sending IPs should be
371 whitelisted from SPF checks. Use this to list trusted forwarders by
372 domain name. Client IP addresses are tested against SPF records pub‐
373 lished by the listed domains. This is useful for large forwarders with
374 complex outbound infrastructures and SPF records. This option is less
375 scalable than the SPF IP Whitelist. An x-header is prepended indicat‐
376 ing the IP was whitelisted against SPF checks. This is a trace header
377 only. This option does nothing if the domain does not have an SPF
378 record. In this case use the SPF IP Whitelist described above or Do‐
379 main_Whitelist_PTR (below). Note the lack of spaces in the list.
380 Example:
382 Domain_Whitelist = pobox.com,trustedforwarder.org
384 Default:
386 None
388
391 Domain_Whitelist_PTR: List of domains (and subdomains) whose sending
392 IPs should be whitelisted from SPF checks based on PTR match of the do‐
393 main. Use this to list trusted forwarders by domain name if they do not
394 publish SPF records. Client IP addresses PTR names are tested to see
395 if they match the listed domains. This is useful for large forwarders
396 with complex outbound infrastructures, but no SPF records and predict‐
397 able host naming. Matching is done using the same rules as the SPF PTR
398 mechanism as described in RFC 7208. List the parent domain and all
399 subdomains will match. This option is less scalable than the SPF IP
400 Whitelist. An x-header is prepended indicating the IP was whitelisted
401 against SPF checks. This is a trace header only. This option does
402 nothing if the host does not have a PTR record record. In this case
403 use the SPF IP Whitelist described above. Note the lack of spaces in
404 the list.
405 Example:
407 Domain_Whitelist_PTR = yahoo.com,yahoogroups.com
409 Default:
411 None
413
416 By default, Postfix will use the 4/5.7.1 enhanced status code for de‐
417 fer/reject actions from the policy server (originally defined in RFC
418 1893, RFC 3463 is the current reference). New email authentication
419 (including SPF) specific codes were defined in RFC 7372. The policy
420 server now overrides the Postfix enhanced status codes to use the RFC
421 7372 values. This can be disabled by setting this option to "No" in
422 the event of interoperability issues.
423 Example:
425 SPF_Enhanced_Status_Codes = No
427 Default:
429 Yes
431
434 The standard method for documenting SPF results in a message (for con‐
435 sumption by downstream processes) is the Received-SPF header defined in
436 RFC 7208. This is the default header to use. Results can also be docu‐
437 mented in the Authentication-Results header, which is also covered in
438 RFC 7208. The default is Received-SPF (SPF), but inclusion of Authenti‐
439 cation-Results (AR) headers as an alternative to Received-SPF can be
440 specified.
441 If there is a requirement to prepend both Received-SPF and Authentica‐
443 tion- Results headers, then it must be done by processing the message
444 with more than one instance of the policy server using different con‐
445 figuration files with different Header_Type settings.
446 For no header at all, use Header_Type = None.
448 Examples:
450 Header_Type = SPF or Header_Type = AR
452 Default:
454 SPF
456
459 Both Received-SPF and Authentication-Results (AR) header fields include
460 the receiving (RCPT TO) address. In this application, it will always
461 be the first recipient sent by the sending MTA, even if that recipient
462 is a BCC recipient. This is unavoidable as the Postfix policy inter‐
463 face does not provide any indication that if the recipient is BCC or
464 not (this information is not available in until after SMTP DATA in the
465 body of the message). This presents a possible avenue for a privacy
466 breach.
467 In order to avoid this, Hide_Receiver is set to Yes by default in the
469 interest of maximizing privacy. This setting will replace the actual
470 recipient with <UNKNOWN> both in header fields and SMTP responses. The
471 latter may make it more difficult for senders to troubleshoot issues
472 with their SPF deployments. As an implementation detail, currently
473 specifying any value other than No will result in the recipient being
474 hidden, but that may change in the future.
475 Examples:
477 Hide_Receiver = Yes or Hide_Receiver = No
479 Default:
481 True
483
486 Every Authentication-Results header field has an authentication identi‐
487 fier field ('Authserv_Id'). This is similar in syntax to a fully-quali‐
488 fied domain name. See policyd-spf.conf.5 and RFC 7001 paragraph 2.4 for
489 details. Default is HOSTNAME. The results of socket.gethostname will
490 be used unless an alternate value is specified. An Authserv-Id must be
491 provided if Header_Type 'AR' is used.
492 The authentication identifier field provides a unique identifier that
494 refers to the authenticating service within a given administrative do‐
495 main. The identifier MUST be unique to that domain. This identifier is
496 intended to be machine-readable and not necessarily meaningful to
497 users.
498 Example:
500 Authserv_Id = mx.example.com
502 Default:
504 HOSTNAME
506
509 RFC 7208 recommends an elapsed time limit for SPF checks of at least 20
510 seconds. Lookup_Time allows the maximum time (seconds) to be adjusted.
511 20 seconds is the default. This limit is applied separately to Mail
512 From and HELO/EHLO checks, so if both are performed, the lookups may
513 take up to twice Lookup_Time (plus any additional time required for
514 whitelisting related DNS lookups).
515 It is important that the combination of Lookup_Time(s) and applicable
517 Whitelist_Lookup_Time(s) be less than the smtpd_policy_service_timeout
518 defined for the service (default 100 seconds). Since HELO and Mail
519 From time limits are independent, smtpd_policy_service_timeout needs to
520 be at least double the time allowed for the SPF policy server per en‐
521 tity type.
522 Example:
524 Lookup_Time = 20
526 Default
528 20 (seconds)
530
533 Some of the available whitelisting mechanisms, i.e. Domain_Whitelist,
534 Domain_Whitelist_PTR, and HELO_Whitelist, require specific non-SPF DNS
535 lookups to determine if a connection should be white listed from SPF
536 checks. The maximum amount of time (in seconds) allocated for each of
537 these checks, when used (none are enabled by default), is controlled by
538 the Whitelist_Lookup_Time parameter. It defaults to 10 seconds and is
539 applied independently to each whitelisting method in use (e.g. if both
540 a Domain_Whitelist_PTR and HELO_Whitelist are defined, together they
541 may take up to 20 seconds). This is in addition to the time allowed
542 for SPF Lookup_Time.
543 It is important that the combination of Lookup_Time(s) and applicable
545 Whitelist_Lookup_Time(s) be less than the smtpd_policy_service_timeout
546 defined for the service (default 100 seconds). Since HELO and Mail
547 From time limits are independent, smtpd_policy_service_timeout needs to
548 be at least double the time allowed for the SPF policy server per en‐
549 tity type.
550 Example:
552 Whitelist_Lookup_Time = 10
554 Default
556 10 (seconds)
558
561 RFC 7208 adds a new processing limit called "void lookup limit" (See
562 section 4.6.4). Void lookups are DNS queries within an SPF record for
563 which DNS queries return either a positive answer (RCODE 0) with an an‐
564 swer count of 0, or a "Name Error" (RCODE 3) answer. This should not
565 need to be changed. Although new in an RFC in RFC 7208, this limit has
566 been widely deployed in the Mail::SPF perl library without issue. De‐
567 fault is 2, but it can be adjusted.
568 Example:
570 Void_Limit = 2
572 Default
574 2
576
579 In some versions of postfix, for bizarre Sendmail compatibility rea‐
580 sons, the first header field added by a policy server is not visible to
581 milters. To make this easy to work around, set the Mock value to true
582 and a fixed header field will be inserted so the actual SPF check will
583 be the second field and visible to milters such as DMARC milter.
584 To use this feature requires additional postfix configuration to exe‐
586 cute the second, mock, instance of the policy server:
587 Add a second service to /etc/postfix/master.cf:
589 policyd-spf-mock unix - n n - 0
591 spawn
592 user=nobody argv=/usr/bin/policyd-spf '/etc/pypolicyd-
593 spf/mock
594 Configure the Postfix additional policy service in /etc/postfix/main.cf
596 to run before the regular service:
597 smtpd_recipient_restrictions =
599 ...
600 reject_unauth_destination
601 check_policy_service unix:private/policyd-spf-mock
602 check_policy_service unix:private/policyd-spf
603 ...
604 Create the specified configuration file in the location indicated with
606 Mock set to True.
607 Example:
609 Mock = True
611 Default
613 False
615
618 If a message is rejected or deferred because of the SPF policy, a rea‐
619 son is given for logging and debugging purposes. The String configured
620 supports the following format specifiers:
621 rejectdefer - either the string 'rejected' or 'deferred'
623 spf - SPF result code
625 url - Parameterized URL to http://www.openspf.net/ ex‐
627 plaining SPF
628 Example:
630 Reason_Message = Message {rejectdefer} due to: {spf}.
632 Default:
634 Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}
636
639 man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf,
640 <http://www.openspf.net>, RFC 7208, RFC 7001, RFC 7372
641
644 This version of policyd-spf was written by Copyright © 2007-2016, Scott
645 Kitterman <scott@kitterman.com>. It is derived from Tumgreyspf, writ‐
646 ten by Sean Reifschneider, tummy.com, ltd <jafo@tummy.com>. Portions of
647 the documentation were written by Meng Weng Wong <mengwong@pobox.com>.
648 This man-page was created by Scott Kitterman <scott@kitterman.com> and
650 is licensed under the same terms as the program.
651 policy-spf.conf(5)