Logging: ensure that an error for a mistyped IPv6 address in a search

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 2bdb2bbdf9b730af9f758428073de9688fa63700..dc8f5cc4d0347419fdfed60b57d6d235d24ee8a8 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -22792,8 +22792,11 @@ If unset, or expanding to an empty string, no filtering is done.
 When the message is about to be written out, the command specified by
 &%transport_filter%& is started up in a separate, parallel process, and
 the entire message, including the header lines, is passed to it on its standard
 When the message is about to be written out, the command specified by
 &%transport_filter%& is started up in a separate, parallel process, and
 the entire message, including the header lines, is passed to it on its standard

-input (this in fact is done from a third process, to avoid deadlock). The
-command must be specified as an absolute path.
+input (this in fact is done from a third process, to avoid deadlock).
+The command must be specified as an absolute path.
+
+The process run by the command must use its standard input as the message
+data to be transformed, and write the results on its standard output.

 
 The lines of the message that are written to the transport filter are
 terminated by newline (&"\n"&). The message is passed to the filter before any
 
 The lines of the message that are written to the transport filter are
 terminated by newline (&"\n"&). The message is passed to the filter before any


@@ -24828,7 +24831,7 @@ Exim, and each argument is separately expanded, as described in section
 No part of the resulting command may be tainted.
 
 
 No part of the resulting command may be tainted.
 
 

-.option environment pipe string&!! unset
+.option environment pipe "string list&!!" unset

 .cindex "&(pipe)& transport" "environment for command"
 .cindex "environment" "&(pipe)& transport"
 This option is used to add additional variables to the environment in which the
 .cindex "&(pipe)& transport" "environment for command"
 .cindex "environment" "&(pipe)& transport"
 This option is used to add additional variables to the environment in which the


@@ -25546,15 +25549,24 @@ load-balancer, matching the session stored in the client's cache.
 
 Exim can pull out a server name, if there is one, from the response to the
 client's SMTP EHLO command.
 
 Exim can pull out a server name, if there is one, from the response to the
 client's SMTP EHLO command.

-The default value of this option:
+For normal STARTTLS use, the default value of this option:

 .code
     ${if and { {match {$host} {.outlook.com\$}} \
                {match {$item} {\N^250-([\w.]+)\s\N}} \
             } {$1}}
 .endd
 suffices for one known case.
 .code
     ${if and { {match {$host} {.outlook.com\$}} \
                {match {$item} {\N^250-([\w.]+)\s\N}} \
             } {$1}}
 .endd
 suffices for one known case.

+

 During the expansion of this option the &$item$& variable will have the
 server's EHLO response.
 During the expansion of this option the &$item$& variable will have the
 server's EHLO response.

+
+.new
+For TLS-on-connect connections we do not have an EHLO
+response to use. Because of this the default value of this option is
+set to a static string for those cases, meaning that resumption will
+always be attempted if permitted by the &%tls_resumption_hosts%& option.
+.wen
+

 The result of the option expansion is included in the key used to store and
 retrieve the TLS session, for session resumption.
 
 The result of the option expansion is included in the key used to store and
 retrieve the TLS session, for session resumption.
 


@@ -35323,9 +35335,10 @@ The arguments are as follows:
 (the -D file). The file is open for reading and writing, but updating it is not
 recommended. &*Warning*&: You must &'not'& close this file descriptor.
 
 (the -D file). The file is open for reading and writing, but updating it is not
 recommended. &*Warning*&: You must &'not'& close this file descriptor.
 

-The descriptor is positioned at character 19 of the file, which is the first
-character of the body itself, because the first 19 characters are the message
-id followed by &`-D`& and a newline. If you rewind the file, you should use the
+The descriptor is positioned at character 26 of the file, which is the first
+character of the body itself, because the first 26 characters (19 characters
+before Exim  4.97) are the message id followed by &`-D`& and a newline.
+If you rewind the file, you should use the

 macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in
 case this changes in some future version.
 .next
 macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in
 case this changes in some future version.
 .next


@@ -39084,7 +39097,7 @@ selection marked by asterisks:
 .irow &`tls_peerdn`&                   &nbsp; "TLS peer DN on <= and => lines"
 .irow &`tls_resumption`&               &nbsp; "append * to cipher field"
 .irow &`tls_sni`&                      &nbsp; "TLS SNI on <= lines"
 .irow &`tls_peerdn`&                   &nbsp; "TLS peer DN on <= and => lines"
 .irow &`tls_resumption`&               &nbsp; "append * to cipher field"
 .irow &`tls_sni`&                      &nbsp; "TLS SNI on <= lines"

-.irow &`unknown_in_list`&              &nbsp; "DNS lookup failed in list match"
+.irow &`unknown_in_list`&              &nbsp; "lookup failed in list match"

 .irow &`all`&                          &nbsp; "&*all of the above*&"
 .endtable
 See also the &%slow_lookup_log%& main configuration option,
 .irow &`all`&                          &nbsp; "&*all of the above*&"
 .endtable
 See also the &%slow_lookup_log%& main configuration option,


@@ -39503,7 +39516,8 @@ added to the log line, preceded by SNI=.
 .next
 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the
 .next
 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the

-result of a list match is failure because a DNS lookup failed.
+result of a list match is failure because a DNS lookup failed, or because
+a bad IP address was in the list.

 .endlist
 
 
 .endlist
 
 


@@ -41698,7 +41712,7 @@ variables here.
 .option dkim_sign_headers smtp string&!! "see below"
 If set, this option must expand to a colon-separated
 list of header names.
 .option dkim_sign_headers smtp string&!! "see below"
 If set, this option must expand to a colon-separated
 list of header names.

-Headers with these names, or the absence or such a header, will be included
+Headers with these names, or the absence of such a header, will be included

 in the message signature.
 When unspecified, the header names listed in RFC4871 will be used,
 whether or not each header is present in the message.
 in the message signature.
 When unspecified, the header names listed in RFC4871 will be used,
 whether or not each header is present in the message.


@@ -41733,8 +41747,9 @@ RFC 6376 lists these tags as RECOMMENDED.
 
 Verification of DKIM signatures in SMTP incoming email is done for all
 messages for which an ACL control &%dkim_disable_verify%& has not been set.
 
 Verification of DKIM signatures in SMTP incoming email is done for all
 messages for which an ACL control &%dkim_disable_verify%& has not been set.

+

 .cindex DKIM "selecting signature algorithms"
 .cindex DKIM "selecting signature algorithms"

-Individual classes of signature algorithm can be ignored by changing
+Individual classes of DKIM signature algorithm can be ignored by changing

 the main options &%dkim_verify_hashes%& or &%dkim_verify_keytypes%&.
 The &%dkim_verify_minimal%& option can be set to cease verification
 processing for a message once the first passing signature is found.
 the main options &%dkim_verify_hashes%& or &%dkim_verify_keytypes%&.
 The &%dkim_verify_minimal%& option can be set to cease verification
 processing for a message once the first passing signature is found.


@@ -41747,7 +41762,7 @@ For most purposes the default option settings suffice and the remainder
 of this section can be ignored.
 
 The results of verification are made available to the
 of this section can be ignored.
 
 The results of verification are made available to the

-&%acl_smtp_dkim%& ACL, which can examine and modify them.
+&%acl_smtp_dkim%& ACL, which (for complex needs) can examine and modify them.

 A missing ACL definition defaults to accept.
 By default, the ACL is called once for each
 syntactically(!) correct signature in the incoming message.
 A missing ACL definition defaults to accept.
 By default, the ACL is called once for each
 syntactically(!) correct signature in the incoming message.


@@ -41812,6 +41827,12 @@ an identity. This is one of the list items from the expanded main option
 &%dkim_verify_signers%& (see above).
 
 .vitem &%$dkim_verify_status%&
 &%dkim_verify_signers%& (see above).
 
 .vitem &%$dkim_verify_status%&

+So long as a DKIM ACL is defined
+(it need do no more than accept, which is the default),
+after all the DKIM ACL runs have completed, the value becomes a
+colon-separated list of the values after each run.
+The value is maintained for the MIME, PRDR and DATA ACLs.
+

 Within the DKIM ACL,
 a string describing the general status of the signature. One of
 .ilist
 Within the DKIM ACL,
 a string describing the general status of the signature. One of
 .ilist


@@ -41840,11 +41861,6 @@ hash-method or key-size:
        set dkim_verify_reason = hash too weak or key too short
 .endd
 
        set dkim_verify_reason = hash too weak or key too short
 .endd
 

-So long as a DKIM ACL is defined (it need do no more than accept),
-after all the DKIM ACL runs have completed, the value becomes a
-colon-separated list of the values after each run.
-This is maintained for the mime, prdr and data ACLs.
-

 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either
 "fail" or "invalid". One of
 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either
 "fail" or "invalid". One of


@@ -41969,13 +41985,15 @@ option.
 
 .endlist
 
 
 .endlist
 

-In addition, two ACL conditions are provided, usable only in a DKIM ACL:
+In addition, two ACL conditions are provided:

 
 .vlist
 .vitem &%dkim_signers%&
 ACL condition that checks a colon-separated list of domains or identities
 for a match against the domain or identity that the ACL is currently verifying
 
 .vlist
 .vitem &%dkim_signers%&
 ACL condition that checks a colon-separated list of domains or identities
 for a match against the domain or identity that the ACL is currently verifying

-(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
+(reflected by &%$dkim_cur_signer%&).
+This condition is only usable in a DKIM ACL.
+This is typically used to restrict an ACL

 verb to a group of domains or identities. For example:
 
 .code
 verb to a group of domains or identities. For example:
 
 .code


@@ -41991,7 +42009,18 @@ for that check for empty &$h_DKIM-Signature:$& in the data ACL.
 
 .vitem &%dkim_status%&
 ACL condition that checks a colon-separated list of possible DKIM verification
 
 .vitem &%dkim_status%&
 ACL condition that checks a colon-separated list of possible DKIM verification

-results against the actual result of verification. This is typically used
+results against the actual result of verification,
+given by &$dkim_verify_status$& if that is non-empty or "none" if empty.
+.new
+This condition may be used in DKIM, MIME, PRDR and DATA ACLs.
+.wen
+
+A basic verification might be:
+.code
+deny !dkim_status = pass:none:invalid
+.endd
+
+A more complex use could be

 to restrict an ACL verb to a list of verification outcomes, for example:
 
 .code
 to restrict an ACL verb to a list of verification outcomes, for example:
 
 .code


@@ -42004,6 +42033,12 @@ deny sender_domains = paypal.com:paypal.de
 The possible status keywords are: 'none','invalid','fail' and 'pass'. Please
 see the documentation of the &%$dkim_verify_status%& expansion variable above
 for more information of what they mean.
 The possible status keywords are: 'none','invalid','fail' and 'pass'. Please
 see the documentation of the &%$dkim_verify_status%& expansion variable above
 for more information of what they mean.

+
+The condition is true if the status
+.new
+(or any of the list of status values)
+.wen
+is any one of the supplied list.

 .endlist
 
 
 .endlist