Logging: Fix logging of errors under PIPELINING

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 174873d07a0528abc5b3498164bb4c453f280a26..d08a7a040e77c28a6c2b53acb2b00b31deb14a08 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9213,8 +9213,8 @@ The environment is adjusted by the &%keep_environment%& and
 .cindex "&%extract%&" "substrings by key"
 The key and <&'string1'&> are first expanded separately. Leading and trailing
 white space is removed from the key (but not from any of the strings). The key
 .cindex "&%extract%&" "substrings by key"
 The key and <&'string1'&> are first expanded separately. Leading and trailing
 white space is removed from the key (but not from any of the strings). The key

-must not consist entirely of digits. The expanded <&'string1'&> must be of the
-form:
+must not be empty and must not consist entirely of digits.
+The expanded <&'string1'&> must be of the form:

 .display
 <&'key1'&> = <&'value1'&>  <&'key2'&> = <&'value2'&> ...
 .endd
 .display
 <&'key1'&> = <&'value1'&>  <&'key2'&> = <&'value2'&> ...
 .endd


@@ -10090,6 +10090,21 @@ Last:user@example.com
 user@example.com
 .endd
 
 user@example.com
 .endd
 

+.new
+.vitem &*${base32:*&<&'digits'&>&*}*&
+.cindex "&%base32%& expansion item"
+.cindex "expansion" "conversion to base 32"
+The string must consist entirely of decimal digits. The number is converted to
+base 32 and output as a (empty, for zero) string of characters.
+Only lowercase letters are used.
+
+.vitem &*${base32d:*&<&'base-32&~digits'&>&*}*&
+.cindex "&%base32d%& expansion item"
+.cindex "expansion" "conversion to base 32"
+The string must consist entirely of base-32 digits.
+The number is converted to decimal and output as a string.
+.wen
+

 .vitem &*${base62:*&<&'digits'&>&*}*&
 .cindex "&%base62%& expansion item"
 .cindex "expansion" "conversion to base 62"
 .vitem &*${base62:*&<&'digits'&>&*}*&
 .cindex "&%base62%& expansion item"
 .cindex "expansion" "conversion to base 62"


@@ -10514,7 +10529,7 @@ variables or headers inside regular expressions.
 .cindex "SHA-1 hash"
 .cindex "expansion" "SHA-1 hashing"
 .cindex certificate fingerprint
 .cindex "SHA-1 hash"
 .cindex "expansion" "SHA-1 hashing"
 .cindex certificate fingerprint

-.cindex "&%sha2%& expansion item"
+.cindex "&%sha1%& expansion item"

 The &%sha1%& operator computes the SHA-1 hash value of the string, and returns
 it as a 40-digit hexadecimal number, in which any letters are in upper case.
 
 The &%sha1%& operator computes the SHA-1 hash value of the string, and returns
 it as a 40-digit hexadecimal number, in which any letters are in upper case.
 


@@ -10522,16 +10537,38 @@ If the string is a single variable of type certificate,
 returns the SHA-1 hash fingerprint of the certificate.
 
 
 returns the SHA-1 hash fingerprint of the certificate.
 
 

-.vitem &*${sha256:*&<&'certificate'&>&*}*&
+.vitem &*${sha256:*&<&'string'&>&*}*&

 .cindex "SHA-256 hash"
 .cindex certificate fingerprint
 .cindex "expansion" "SHA-256 hashing"
 .cindex "&%sha256%& expansion item"
 .cindex "SHA-256 hash"
 .cindex certificate fingerprint
 .cindex "expansion" "SHA-256 hashing"
 .cindex "&%sha256%& expansion item"

-The &%sha256%& operator computes the SHA-256 hash fingerprint of the
-certificate,
+.new
+The &%sha256%& operator computes the SHA-256 hash value of the string
+and returns
+it as a 64-digit hexadecimal number, in which any letters are in upper case.
+.wen
+
+If the string is a single variable of type certificate,
+returns the SHA-256 hash fingerprint of the certificate.
+
+
+.new
+.vitem &*${sha3:*&<&'string'&>&*}*& &&&
+       &*${sha3_<n>:*&<&'string'&>&*}*&
+.cindex "SHA3 hash"
+.cindex "expansion" "SHA3 hashing"
+.cindex "&%sha3%& expansion item"
+The &%sha3%& operator computes the SHA3-256 hash value of the string

 and returns
 it as a 64-digit hexadecimal number, in which any letters are in upper case.
 and returns
 it as a 64-digit hexadecimal number, in which any letters are in upper case.

-Only arguments which are a single variable of certificate type are supported.
+
+If a number is appended, separated by an underbar, it specifies
+the output length.  Values of 224, 256, 384 and 512 are accepted;
+with 256 being the default.
+
+The &%sha3%& expansion item is only supported if Exim has been
+compiled with GnuTLS 3.5.0 or later.
+.wen

 
 
 .vitem &*${stat:*&<&'string'&>&*}*&
 
 
 .vitem &*${stat:*&<&'string'&>&*}*&


@@ -12816,7 +12853,7 @@ When a message is received from a remote host over an encrypted SMTP
 connection, this variable is set to the cipher suite that was negotiated, for
 example DES-CBC3-SHA. In other circumstances, in particular, for message
 received over unencrypted connections, the variable is empty. Testing
 connection, this variable is set to the cipher suite that was negotiated, for
 example DES-CBC3-SHA. In other circumstances, in particular, for message
 received over unencrypted connections, the variable is empty. Testing

-&$tls_cipher$& for emptiness is one way of distinguishing between encrypted and
+&$tls_in_cipher$& for emptiness is one way of distinguishing between encrypted and

 non-encrypted connections during ACL processing.
 
 The deprecated &$tls_cipher$& variable is the same as &$tls_in_cipher$& during message reception,
 non-encrypted connections during ACL processing.
 
 The deprecated &$tls_cipher$& variable is the same as &$tls_in_cipher$& during message reception,


@@ -15955,7 +15992,7 @@ the daemon's command line.
 
 .new
 .cindex queues named
 
 .new
 .cindex queues named

-.condex "named queues"
+.cindex "named queues"

 To set limits for different named queues use
 an expansion depending on the &$queue_name$& variable.
 .wen
 To set limits for different named queues use
 an expansion depending on the &$queue_name$& variable.
 .wen


@@ -16975,7 +17012,7 @@ in IKE is assigned number 23.
 
 Otherwise, the option must expand to the name used by Exim for any of a number
 of DH primes specified in RFC 2409, RFC 3526 and RFC 5114.  As names, Exim uses
 
 Otherwise, the option must expand to the name used by Exim for any of a number
 of DH primes specified in RFC 2409, RFC 3526 and RFC 5114.  As names, Exim uses

-"ike" followed by the number used by IKE, of "default" which corresponds to
+"ike" followed by the number used by IKE, or "default" which corresponds to

 "ike23".
 
 The available primes are:
 "ike23".
 
 The available primes are:


@@ -17550,7 +17587,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence.
 .cindex "DNSSEC" "MX lookup"
 .cindex "security" "MX lookup"
 .cindex "DNS" "DNSSEC"
 .cindex "DNSSEC" "MX lookup"
 .cindex "security" "MX lookup"
 .cindex "DNS" "DNSSEC"

-DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+DNS lookups for domains matching &%dnssec_require_domains%& will be done with

 the dnssec request bit set.  Any returns not having the Authenticated Data bit
 (AD bit) set will be ignored and logged as a host-lookup failure.
 This applies to all of the SRV, MX, AAAA, A lookup sequence.
 the dnssec request bit set.  Any returns not having the Authenticated Data bit
 (AD bit) set will be ignored and logged as a host-lookup failure.
 This applies to all of the SRV, MX, AAAA, A lookup sequence.


@@ -19851,12 +19888,17 @@ list1:   :include:/opt/lists/list1
 .endd
 .next
 .cindex "address redirection" "to black hole"
 .endd
 .next
 .cindex "address redirection" "to black hole"

-Sometimes you want to throw away mail to a particular local part. Making the
-&%data%& option expand to an empty string does not work, because that causes
-the router to decline. Instead, the alias item
+.cindex "delivery" "discard"
+.cindex "delivery" "blackhole"

 .cindex "black hole"
 .cindex "abandoning mail"
 .cindex "black hole"
 .cindex "abandoning mail"

-&':blackhole:'& can be used. It does what its name implies. No delivery is
+Sometimes you want to throw away mail to a particular local part.  Making the
+&%data%& option expand to an empty string does not work, because that causes
+the router to decline. Instead, the alias item
+.code
+:blackhole:
+.endd
+can be used. It does what its name implies. No delivery is

 done, and no error message is generated. This has the same effect as specifying
 &_/dev/null_& as a destination, but it can be independently disabled.
 
 done, and no error message is generated. This has the same effect as specifying
 &_/dev/null_& as a destination, but it can be independently disabled.
 


@@ -20826,7 +20868,7 @@ is forced to fail, no action is taken. Other expansion failures are treated as
 errors and cause the delivery to be deferred.
 
 Unlike most options, &%headers_remove%& can be specified multiple times
 errors and cause the delivery to be deferred.
 
 Unlike most options, &%headers_remove%& can be specified multiple times

-for a router; all listed headers are removed.
+for a transport; all listed headers are removed.

 
 &*Warning*&: Because of the separate expansion of the list items,
 items that contain a list separator must have it doubled.
 
 &*Warning*&: Because of the separate expansion of the list items,
 items that contain a list separator must have it doubled.


@@ -23594,7 +23636,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence.
 .cindex "DNSSEC" "MX lookup"
 .cindex "security" "MX lookup"
 .cindex "DNS" "DNSSEC"
 .cindex "DNSSEC" "MX lookup"
 .cindex "security" "MX lookup"
 .cindex "DNS" "DNSSEC"

-DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+DNS lookups for domains matching &%dnssec_require_domains%& will be done with

 the dnssec request bit set.  Any returns not having the Authenticated Data bit
 (AD bit) set will be ignored and logged as a host-lookup failure.
 This applies to all of the SRV, MX, AAAA, A lookup sequence.
 the dnssec request bit set.  Any returns not having the Authenticated Data bit
 (AD bit) set will be ignored and logged as a host-lookup failure.
 This applies to all of the SRV, MX, AAAA, A lookup sequence.


@@ -28772,13 +28814,18 @@ with &`-d`&, with the output going to a new logfile, by default called
 &'debuglog'&.  The filename can be adjusted with the &'tag'& option, which
 may access any variables already defined.  The logging may be adjusted with
 the &'opts'& option, which takes the same values as the &`-d`& command-line
 &'debuglog'&.  The filename can be adjusted with the &'tag'& option, which
 may access any variables already defined.  The logging may be adjusted with
 the &'opts'& option, which takes the same values as the &`-d`& command-line

-option.  Some examples (which depend on variables that don't exist in all
+option.
+.new
+Logging may be stopped, and the file removed, with the &'kill'& option.
+.wen
+Some examples (which depend on variables that don't exist in all

 contexts):
 .code
       control = debug
       control = debug/tag=.$sender_host_address
       control = debug/opts=+expand+acl
       control = debug/tag=.$message_exim_id/opts=+expand
 contexts):
 .code
       control = debug
       control = debug/tag=.$sender_host_address
       control = debug/opts=+expand+acl
       control = debug/tag=.$message_exim_id/opts=+expand

+      control = debug/kill

 .endd
 
 
 .endd
 
 


@@ -29017,7 +29064,7 @@ any ACL verb, including &%deny%& (though this is potentially useful only in a
 RCPT ACL).
 
 Headers will not be added to the message if the modifier is used in
 RCPT ACL).
 
 Headers will not be added to the message if the modifier is used in

-DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing.
+DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.

 
 Leading and trailing newlines are removed from
 the data for the &%add_header%& modifier; if it then
 
 Leading and trailing newlines are removed from
 the data for the &%add_header%& modifier; if it then


@@ -29118,8 +29165,8 @@ receiving a message). The message must ultimately be accepted for
 with any ACL verb, including &%deny%&, though this is really not useful for
 any verb that doesn't result in a delivered message.
 
 with any ACL verb, including &%deny%&, though this is really not useful for
 any verb that doesn't result in a delivered message.
 

-Headers will not be removed to the message if the modifier is used in
-DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing.
+Headers will not be removed from the message if the modifier is used in
+DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.

 
 More than one header can be removed at the same time by using a colon separated
 list of header names. The header matching is case insensitive. Wildcards are
 
 More than one header can be removed at the same time by using a colon separated
 list of header names. The header matching is case insensitive. Wildcards are


@@ -31497,7 +31544,7 @@ condition defers.
 
 Unix and TCP socket specifications may be mixed in any order.
 Each element of the list is a list itself, space-separated by default
 
 Unix and TCP socket specifications may be mixed in any order.
 Each element of the list is a list itself, space-separated by default

-and changeable in the usual way.
+and changeable in the usual way; take care to not double the separator.

 
 For TCP socket specifications a host name or IP (v4 or v6, but
 subject to list-separator quoting rules) address can be used,
 
 For TCP socket specifications a host name or IP (v4 or v6, but
 subject to list-separator quoting rules) address can be used,


@@ -35588,6 +35635,7 @@ the following table:
 &`CV  `&        certificate verification status
 &`D   `&        duration of &"no mail in SMTP session"&
 &`DN  `&        distinguished name from peer certificate
 &`CV  `&        certificate verification status
 &`D   `&        duration of &"no mail in SMTP session"&
 &`DN  `&        distinguished name from peer certificate

+&`DS  `&        DNSSEC secured lookups

 &`DT  `&        on &`=>`& lines: time taken for a delivery
 &`F   `&        sender address (on delivery lines)
 &`H   `&        host name and IP address
 &`DT  `&        on &`=>`& lines: time taken for a delivery
 &`F   `&        sender address (on delivery lines)
 &`H   `&        host name and IP address


@@ -35679,6 +35727,7 @@ selection marked by asterisks:
 &` deliver_time               `&  time taken to perform delivery
 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
 &`*dnslist_defer              `&  defers of DNS list (aka RBL) lookups
 &` deliver_time               `&  time taken to perform delivery
 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
 &`*dnslist_defer              `&  defers of DNS list (aka RBL) lookups

+&` dnssec                     `&  DNSSEC secured lookups

 &`*etrn                       `&  ETRN commands
 &`*host_lookup_failed         `&  as it says
 &` ident_timeout              `&  timeout for ident connection
 &`*etrn                       `&  ETRN commands
 &`*host_lookup_failed         `&  as it says
 &` ident_timeout              `&  timeout for ident connection


@@ -35786,6 +35835,14 @@ the &"=>"& line, tagged with S=.
 &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a
 DNS black list suffers a temporary error.
 .next
 &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a
 DNS black list suffers a temporary error.
 .next

+.cindex log dnssec
+.cindex dnssec logging
+&%dnssec%&: For message acceptance and (attempted) delivery log lines, when
+dns lookups gave secure results a tag of DS is added.
+For acceptance this covers the reverse and forward lookups for host name verification.
+It does not cover helo-name verification.
+For delivery this covers the SRV, MX, A and/or AAAA lookups.
+.next

 .cindex "log" "ETRN commands"
 .cindex "ETRN" "logging"
 &%etrn%&: Every valid ETRN command that is received is logged, before the ACL
 .cindex "log" "ETRN commands"
 .cindex "ETRN" "logging"
 &%etrn%&: Every valid ETRN command that is received is logged, before the ACL


@@ -38021,7 +38078,7 @@ senders).
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 

-Signing is implemented by setting private options on the SMTP transport.
+Signing is enabled by setting private options on the SMTP transport.

 These options take (expandable) strings as arguments.
 
 .option dkim_domain smtp string&!! unset
 These options take (expandable) strings as arguments.
 
 .option dkim_domain smtp string&!! unset


@@ -38078,7 +38135,7 @@ used.
 .section "Verifying DKIM signatures in incoming mail" "SECID514"
 .cindex "DKIM" "verification"
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"
 .cindex "DKIM" "verification"
 

-Verification of DKIM signatures in incoming email is implemented via the
+Verification of DKIM signatures in SMTP incoming email is implemented via the

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


@@ -38440,7 +38497,7 @@ form of the name.
 Log lines and Received-by: header lines will acquire a "utf8"
 prefix on the protocol element, eg. utf8esmtp.
 
 Log lines and Received-by: header lines will acquire a "utf8"
 prefix on the protocol element, eg. utf8esmtp.
 

-The following expansion operator can be used:
+The following expansion operators can be used:

 .code
 ${utf8_domain_to_alabel:str}
 ${utf8_domain_from_alabel:str}
 .code
 ${utf8_domain_to_alabel:str}
 ${utf8_domain_from_alabel:str}