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
27 using different configuration options on a per user (mail reciepient)
28 basis.
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
60 increased up to 5 (values higher than 5 will not cause an error, but
61 will 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
72 information 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
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 Note: This option was previously named defaultSeedOnly. This is still
100 accepted, but logs an error.
101 Default:
103 TestOnly = 1
105
108 HELO check rejection policy options are:
109 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 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 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 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 False - Never reject on HELO, append header only. This is useful for
139 post-SMTP spam filters such as SpamAssassin.
140 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 Default:
147 HELO_reject = Fail
149
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 Example:
164 HELO_pass_restriction = helo_passed_spf
166 Default:
168 None
170
173 Mail From rejection policy options are:
174 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 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 Fail (default) - Reject on Mail From Fail.
187 False - Never reject on Mail From, append header only. This is useful
189 for post-SMTP spam filters such as SpamAssassin.
190 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 Default:
202 Mail_From_reject = Fail
204
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 Example:
218 Mail_From_pass_restriction = mfrom_passed_spf
220 Default:
222 None
224
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 Default:
234 No_Mail = False
236
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 Example:
247 Reject_Not_Pass_Domains = aol.com,hotmail.com
249 Default:
251 None
253
256 Policy for rejecting due to SPF PermError options are:
257 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 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 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 Default:
272 PermError_reject = False
274
277 Policy for deferring messages due to SPF TempError options are:
278 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 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 False - Treat TempError the same as no SPF record at all. This is the
293 default to minimize false positive risk.
294 Default:
296 TempError_Defer = False
298
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 Prospective = 192.168.0.4
308 Default:
310 None
312
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 Default:
324 skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
326
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 Example:
336 Whitelist = 192.168.0.0/31,192.168.1.0/30
338 Default:
340 None
342
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 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 Example:
360 HELO_Whitelist = relay.example.com,sender.example.org
362 Default:
364 None
366
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 Example:
381 Domain_Whitelist = pobox.com,trustedforwarder.org
383 Default:
385 None
387
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 Example:
406 Domain_Whitelist_PTR = yahoo.com,yahoogroups.com
408 Default:
410 None
412
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 Example:
424 SPF_Enhanced_Status_Codes = No
426 Default:
428 Yes
430
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 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 For no header at all, use Header_Type = None.
447 Examples:
449 Header_Type = SPF or Header_Type = AR
451 Default:
453 SPF
455
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 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 Examples:
476 Hide_Receiver = Yes or Hide_Receiver = No
478 Default:
480 True
482
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 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 Example:
499 Authserv_Id = mx.example.com
501 Default:
503 HOSTNAME
505
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 Example:
516 Lookup_Time = 20
518 Default
520 20 (seconds)
522
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 Example:
537 Whitelist_Lookup_Time = 10
539 Default
541 10 (seconds)
543
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 Example:
555 Void_Limit = 2
557 Default
559 2
561
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 To use this feature requires additional postfix configuration to exe‐
571 cute the second, mock, instance of the policy server:
572 Add a second service to /etc/postfix/master.cf:
574 policyd-spf-mock unix - n n - 0
576 spawn
577 user=nobody argv=/usr/bin/policyd-spf '/etc/pypolicyd-
578 spf/mock
579 Configure the Postfix additional policy service in /etc/postfix/main.cf
581 to run before the regular service:
582 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 Create the specified configuration file in the location indicated with
591 Mock set to True.
592 Example:
594 Mock = True
596 Default
598 False
600
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 rejectdefer - either the string 'rejected' or 'deferred'
608 spf - SPF result code
610 url - Parameterized URL to http://www.openspf.net/
612 explaining SPF
613 Example:
615 Reason_Message = Message {rejectdefer} due to: {spf}.
617 Default:
619 Reason_Message = Message {rejectdefer} due to: {spf}. Please see {url}
621
624 man 1 policyd-spf, man 5 policyd-spf.peruser, python-spf,
625 <http://www.openspf.net>, RFC 7208, RFC 7001, RFC 7372
626
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 This man-page was created by Scott Kitterman <scott@kitterman.com> and
635 is licensed under the same terms as the program.
636 policy-spf.conf(5)