SPF: Add main config option "spf_smtp_comment_template

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 6d858252870ea093605a6218c086d835f639b87e..b1387eb497122eae0a27b66dd892539e3a124aa3 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6663,6 +6663,13 @@ If the value of &$sender_host_address$& is 192.168.5.6, expansion of the
 first &%domains%& setting above generates the second setting, which therefore
 causes a second lookup to occur.
 
+.new
+The lookup type may optionally be followed by a comma
+and a comma-separated list of options.
+Each option is a &"name=value"& pair.
+Whether an option is meaningful depands on the lookup type.
+.wen
+
 The rest of this chapter describes the different lookup types that are
 available. Any of them can be used in any part of the configuration where a
 lookup is permitted.
@@ -6680,6 +6687,13 @@ lookup to succeed. The lookup type determines how the file is searched.
 .new
 .cindex "tainted data" "single-key lookups"
 The file string may not be tainted
+
+.cindex "tainted data" "de-tainting"
+All single-key lookups support the option &"ret=key"&.
+If this is given and the lookup
+(either underlying implementation or cached value)
+returns data, the result is replaced with a non-tainted
+version of the lookup key.
 .wen
 .next
 .cindex "query-style lookup" "definition of"
@@ -14564,6 +14578,7 @@ listed in more than one group.
 .row &%percent_hack_domains%&        "recognize %-hack for these domains"
 .row &%spamd_address%&               "set interface to SpamAssassin"
 .row &%strict_acl_vars%&             "object to unset ACL variables"
+.row &%spf_smtp_comment_template%&   "template for &$spf_smtp_comment$&"
 .endtable
 
 
@@ -17747,6 +17762,41 @@ See section &<<SECTscanspamass>>& for more details.
 This option is available when Exim is compiled with SPF support.
 See section &<<SECSPF>>& for more details.
 
+.new
+.option spf_smtp_comment_template main string&!! "Please%_see%_http://www.open-spf.org/Why"
+This option is available when Exim is compiled with SPF support.  It
+allows the customisation of the SMTP comment that the SPF library
+generates.  You are strongly encouraged to link to your own explanative
+site. The following placeholders (along with Exim variables) are allowed
+in the template (this list is compiled from the libspf2 sources):
+.ilist
+&*L*&: Envelope sender's local part.
+.next
+&*S*&: Envelope sender.
+.next
+&*O*&: Envelope sender's domain.
+.next
+&*D*&: Current(?) domain.
+.next
+&*I*&: SMTP client Ip.
+.next
+&*C*&: SMTP client pretty IP.
+.next
+&*T*&: Epoch time (UTC).
+.next
+&*P*&: SMTP client domain name.
+.next
+&*V*&: IP version.
+.next
+&*H*&: EHLO/HELO domain.
+.next
+&*R*&: Receiving domain.
+.endlist
+The capitalized placeholders do proper URL encoding, if you use them
+lowercased, no encoding takes place.  A note on using Exim variables: As
+currenty the SPF library is initialized already during the EHLO phase,
+the amount of variables available for expansion is quite limited.
+.wen
 
 
 .option split_spool_directory main boolean false
@@ -40986,13 +41036,16 @@ deny spf = fail
      message = $sender_host_address is not allowed to send mail from \
                ${if def:sender_address_domain \
                     {$sender_address_domain}{$sender_helo_name}}.  \
-               Please see http://www.open-spf.org/Why?scope=\
-               ${if def:sender_address_domain {mfrom}{helo}};\
+               Please see http://www.open-spf.org/Why;\
                identity=${if def:sender_address_domain \
                              {$sender_address}{$sender_helo_name}};\
                ip=$sender_host_address
 .endd
 
+Note: The above mentioned URL may not be as helpful as expected. You are
+encouraged to replace the link with a link to a site with more
+explanations.
+
 When the spf condition has run, it sets up several expansion
 variables:
 
@@ -41027,8 +41080,13 @@ variables:
 
 .vitem &$spf_smtp_comment$&
 .vindex &$spf_smtp_comment$&
+.vindex &%spf_smtp_comment_template%&
   This contains a string that can be used in a SMTP response
   to the calling party. Useful for "fail".
+.new
+  The string is generated by the SPF library from the template configured in the main config
+  option &%spf_smtp_comment_template%&.
+.wen
 .endlist