tidying

[exim.git] / doc / doc-docbook / spec.xfpt
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt

index 6ede1dc95c07a81093cf2268c8e619fad7081fb2..7b92a2f21cd8294e79ef19767b749efd94c187c2 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -54,7 +54,7 @@
  .set drivernamemax "64"
  
  .macro copyyear
  .set drivernamemax "64"
  
  .macro copyyear
-2021
+2022
  .endmacro
  
  . /////////////////////////////////////////////////////////////////////////////
  .endmacro
  
  . /////////////////////////////////////////////////////////////////////////////
@@ -97,6 +97,21 @@
  .itable none 0 0 2 $1 left $2 left
  .endmacro
  
  .itable none 0 0 2 $1 left $2 left
  .endmacro
  
+
+. --- A macro for a "tainted" marker, done as a one-element table
+.macro tmark
+.itable none 0 0 1 10pt left
+.row &'Tainted'&
+.endtable
+.endmacro
+. --- A macro for a tainted variable, adding a taint-marker
+. --- and including the .vitem and .vindex
+.macro tvar
+.vitem $1
+.vindex $1
+.tmark
+.endmacro
+
  . --- A macro that generates .row, but puts &I; at the start of the first
  . --- argument, thus indenting it. Assume a minimum of two arguments, and
  . --- allow up to four arguments, which is as many as we'll ever need.
  . --- A macro that generates .row, but puts &I; at the start of the first
  . --- argument, thus indenting it. Assume a minimum of two arguments, and
  . --- allow up to four arguments, which is as many as we'll ever need.
@@ -239,14 +254,6 @@
    <secondary>failure report</secondary>
    <see><emphasis>bounce message</emphasis></see>
  </indexterm>
    <secondary>failure report</secondary>
    <see><emphasis>bounce message</emphasis></see>
  </indexterm>
-<indexterm role="concept">
-  <primary>de-tainting</primary>
-  <see><emphasis>tainting, de-tainting</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>detainting</primary>
-  <see><emphasis>tainting, de-tainting</emphasis></see>
-</indexterm>
  <indexterm role="concept">
    <primary>dialup</primary>
    <see><emphasis>intermittently connected hosts</emphasis></see>
  <indexterm role="concept">
    <primary>dialup</primary>
    <see><emphasis>intermittently connected hosts</emphasis></see>
@@ -1422,6 +1429,7 @@ check an address given in the SMTP EXPN command (see the &%expn%& option).
  If the &%domains%& option is set, the domain of the address must be in the set
  of domains that it defines.
  .cindex "tainted data" "de-tainting"
  If the &%domains%& option is set, the domain of the address must be in the set
  of domains that it defines.
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
  A match verifies the variable &$domain$& (which carries tainted data)
  and assigns an untainted value to the &$domain_data$& variable.
  Such an untainted value is often needed in the transport.
  A match verifies the variable &$domain$& (which carries tainted data)
  and assigns an untainted value to the &$domain_data$& variable.
  Such an untainted value is often needed in the transport.
@@ -3700,41 +3708,41 @@ of debugging data, respectively. For example, &%-d+filter%& adds filter
  debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that
  no spaces are allowed in the debug setting. The available debugging categories
  are:
  debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that
  no spaces are allowed in the debug setting. The available debugging categories
  are:
-.display
-&`acl            `& ACL interpretation
-&`auth           `& authenticators
-&`deliver        `& general delivery logic
-&`dns            `& DNS lookups (see also resolver)
-&`dnsbl          `& DNS black list (aka RBL) code
-&`exec           `& arguments for &[execv()]& calls
-&`expand         `& detailed debugging for string expansions
-&`filter         `& filter handling
-&`hints_lookup   `& hints data lookups
-&`host_lookup    `& all types of name-to-IP address handling
-&`ident          `& ident lookup
-&`interface      `& lists of local interfaces
-&`lists          `& matching things in lists
-&`load           `& system load checks
-&`local_scan     `& can be used by &[local_scan()]& (see chapter &&&
-                    &<<CHAPlocalscan>>&)
-&`lookup         `& general lookup code and all lookups
-&`memory         `& memory handling
-&`noutf8         `& modifier: avoid UTF-8 line-drawing
-&`pid            `& modifier: add pid to debug output lines
-&`process_info   `& setting info for the process log
-&`queue_run      `& queue runs
-&`receive        `& general message reception logic
-&`resolver       `& turn on the DNS resolver's debugging output
-&`retry          `& retry handling
-&`rewrite        `& address rewriting
-&`route          `& address routing
-&`timestamp      `& modifier: add timestamp to debug output lines
-&`tls            `& TLS logic
-&`transport      `& transports
-&`uid            `& changes of uid/gid and looking up uid/gid
-&`verify         `& address verification logic
-&`all            `& almost all of the above (see below), and also &%-v%&
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow acl            "ACL interpretation"
+.irow auth           "authenticators"
+.irow deliver        "general delivery logic"
+.irow dns            "DNS lookups (see also resolver)"
+.irow dnsbl          "DNS black list (aka RBL) code"
+.irow exec           "arguments for &[execv()]& calls"
+.irow expand         "detailed debugging for string expansions"
+.irow filter         "filter handling"
+.irow hints_lookup   "hints data lookups"
+.irow host_lookup    "all types of name-to-IP address handling"
+.irow ident          "ident lookup"
+.irow interface      "lists of local interfaces"
+.irow lists          "matching things in lists"
+.irow load           "system load checks"
+.irow local_scan     "can be used by &[local_scan()]& (see chapter &&&
+                    &<<CHAPlocalscan>>&)"
+.irow lookup         "general lookup code and all lookups"
+.irow memory         "memory handling"
+.irow noutf8         "modifier: avoid UTF-8 line-drawing"
+.irow pid            "modifier: add pid to debug output lines"
+.irow process_info   "setting info for the process log"
+.irow queue_run      "queue runs"
+.irow receive        "general message reception logic"
+.irow resolver       "turn on the DNS resolver's debugging output"
+.irow retry          "retry handling"
+.irow rewrite        "address rewriting""
+.irow route          "address routing"
+.irow timestamp      "modifier: add timestamp to debug output lines"
+.irow tls            "TLS logic"
+.irow transport      "transports"
+.irow uid            "changes of uid/gid and looking up uid/gid"
+.irow verify         "address verification logic"
+.irow all            "almost all of the above (see below), and also &%-v%&"
+.endtable
  The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it
  for &`-all`&. The reason for this is that &`+all`& is something that people
  tend to use when generating debug output for Exim maintainers. If &`+memory`&
  The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it
  for &`-all`&. The reason for this is that &`+all`& is something that people
  tend to use when generating debug output for Exim maintainers. If &`+memory`&
@@ -6780,6 +6788,7 @@ file that is searched could contain lines like this:
  When the lookup succeeds, the result of the expansion is a list of domains (and
  possibly other types of item that are allowed in domain lists).
  .cindex "tainted data" "de-tainting"
  When the lookup succeeds, the result of the expansion is a list of domains (and
  possibly other types of item that are allowed in domain lists).
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a lookup expansion""
  The result of the expansion is not tainted.
  
  In the second example, the lookup is a single item in a domain list. It causes
  The result of the expansion is not tainted.
  
  In the second example, the lookup is a single item in a domain list. It causes
@@ -6836,17 +6845,23 @@ lookup to succeed. The lookup type determines how the file is searched.
  The file string may not be tainted.
  
  .cindex "tainted data" "de-tainting"
  The file string may not be tainted.
  
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a single-key lookup"
  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.
  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.
-.cindex "tainted data" "de-tainting"
  .next
  .cindex "query-style lookup" "definition of"
  The &'query-style'& type accepts a generalized database query. No particular
  key value is assumed by Exim for query-style lookups. You can use whichever
  Exim variables you need to construct the database query.
  .next
  .cindex "query-style lookup" "definition of"
  The &'query-style'& type accepts a generalized database query. No particular
  key value is assumed by Exim for query-style lookups. You can use whichever
  Exim variables you need to construct the database query.
+.cindex "tainted data" "quoting for lookups"
+.new
+If tainted data is used in the query then it should be quuted by
+using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
+appropriate for the lookup.
+.wen
  .endlist
  
  The code for each lookup type is in a separate source file that is included in
  .endlist
  
  The code for each lookup type is in a separate source file that is included in
@@ -7000,7 +7015,7 @@ IPv4, in dotted-quad form. (Exim converts IPv4-mapped IPv6 addresses to this
  notation before executing the lookup.)
  
  One option is supported, "ret=full", to request the return of the entire line
  notation before executing the lookup.)
  
  One option is supported, "ret=full", to request the return of the entire line
-rather than omitting the key porttion.
+rather than omitting the key portion.
  Note however that the key portion will have been de-quoted.
  
  .next
  Note however that the key portion will have been de-quoted.
  
  .next
@@ -7911,16 +7926,16 @@ be preceded by any number of <&'name'&>=<&'value'&> settings, separated by
  spaces. If a value contains spaces it must be enclosed in double quotes, and
  when double quotes are used, backslash is interpreted in the usual way inside
  them. The following names are recognized:
  spaces. If a value contains spaces it must be enclosed in double quotes, and
  when double quotes are used, backslash is interpreted in the usual way inside
  them. The following names are recognized:
-.display
-&`DEREFERENCE`&  set the dereferencing parameter
-&`NETTIME    `&  set a timeout for a network operation
-&`USER       `&  set the DN, for authenticating the LDAP bind
-&`PASS       `&  set the password, likewise
-&`REFERRALS  `&  set the referrals parameter
-&`SERVERS    `&  set alternate server list for this query only
-&`SIZE       `&  set the limit for the number of entries returned
-&`TIME       `&  set the maximum waiting time for a query
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow DEREFERENCE "set the dereferencing parameter"
+.irow NETTIME     "set a timeout for a network operation"
+.irow USER        "set the DN, for authenticating the LDAP bind"
+.irow PASS        "set the password, likewise"
+.irow REFERRALS   "set the referrals parameter"
+.irow SERVERS     "set alternate server list for this query only"
+.irow SIZE        "set the limit for the number of entries returned"
+.irow TIME        "set the maximum waiting time for a query"
+.endtable
  The value of the DEREFERENCE parameter must be one of the words &"never"&,
  &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter
  must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP
  The value of the DEREFERENCE parameter must be one of the words &"never"&,
  &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter
  must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP
@@ -8835,6 +8850,7 @@ or a &%domains%& condition in an ACL statement, the value is preserved in the
  &$domain_data$& variable and can be referred to in other router options or
  other statements in the same ACL.
  .cindex "tainted data" "de-tainting"
  &$domain_data$& variable and can be referred to in other router options or
  other statements in the same ACL.
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using ACL domains condition"
  The value will be untainted.
  
  &*Note*&: If the data result of the lookup (as opposed to the key)
  The value will be untainted.
  
  &*Note*&: If the data result of the lookup (as opposed to the key)
@@ -8876,6 +8892,7 @@ whether or not the query succeeds. However, when a lookup is used for the
  &%domains%& option on a router, the value is preserved in the &$domain_data$&
  variable and can be referred to in other options.
  .cindex "tainted data" "de-tainting"
  &%domains%& option on a router, the value is preserved in the &$domain_data$&
  variable and can be referred to in other options.
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
  The value will be untainted.
  
  .next
  The value will be untainted.
  
  .next
@@ -9628,8 +9645,6 @@ reasons,
  .cindex expansion "tainted data"
  and expansion of data deriving from the sender (&"tainted data"&)
  is not permitted (including acessing a file using a tainted name).
  .cindex expansion "tainted data"
  and expansion of data deriving from the sender (&"tainted data"&)
  is not permitted (including acessing a file using a tainted name).
-The main config option &%allow_insecure_tainted_data%& can be used as
-mitigation during uprades to more secure configurations.
  
  Common ways of obtaining untainted equivalents of variables with
  tainted values
  
  Common ways of obtaining untainted equivalents of variables with
  tainted values
@@ -10667,16 +10682,32 @@ expansion items.
  This item inserts &"raw"& header lines. It is described with the &%header%&
  expansion item in section &<<SECTexpansionitems>>& above.
  
  This item inserts &"raw"& header lines. It is described with the &%header%&
  expansion item in section &<<SECTexpansionitems>>& above.
  
-.vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&&
+.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
          {*&<&'string2'&>&*}}*&"
  .cindex "expansion" "running a command"
  .cindex "&%run%& expansion item"
          {*&<&'string2'&>&*}}*&"
  .cindex "expansion" "running a command"
  .cindex "&%run%& expansion item"
-The command and its arguments are first expanded as one string. The string is
-split apart into individual arguments by spaces, and then the command is run
+This item runs an external command, as a subprocess.
+.new
+One option is supported after the word &'run'&, comma-separated.
+
+If the option &'preexpand'& is not used,
+the command string is split into individual arguments by spaces
+and then each argument is expanded.
+Then the command is run
  in a separate process, but under the same uid and gid.  As in other command
  executions from Exim, a shell is not used by default. If the command requires
  a shell, you must explicitly code it.
  in a separate process, but under the same uid and gid.  As in other command
  executions from Exim, a shell is not used by default. If the command requires
  a shell, you must explicitly code it.
+The command name may not be tainted, but the remaining arguments can be.
+
+&*Note*&: if tainted arguments are used, they are supplied by a
+potential attacker;
+a careful assessment for security vulnerabilities should be done.
  
  
+If the option &'preexpand'& is used,
+.wen
+the command and its arguments are first expanded as one string. The result is
+split apart into individual arguments by spaces, and then the command is run
+as above.
  Since the arguments are split by spaces, when there is a variable expansion
  which has an empty result, it will cause the situation that the argument will
  simply be omitted when the program is actually executed by Exim. If the
  Since the arguments are split by spaces, when there is a variable expansion
  which has an empty result, it will cause the situation that the argument will
  simply be omitted when the program is actually executed by Exim. If the
@@ -10687,6 +10718,9 @@ in a string containing quotes, because it would interfere with the quotes
  around the command arguments. A possible guard against this is to wrap the
  variable in the &%sg%& operator to change any quote marks to some other
  character.
  around the command arguments. A possible guard against this is to wrap the
  variable in the &%sg%& operator to change any quote marks to some other
  character.
+.new
+Neither the command nor any argument may be tainted.
+.wen
  
  The standard input for the command exists, but is empty. The standard output
  and standard error are set to the same file descriptor.
  
  The standard input for the command exists, but is empty. The standard output
  and standard error are set to the same file descriptor.
@@ -10804,16 +10838,16 @@ SRS encoding.  See SECT &<<SECTSRS>>& for details.
  
  
  
  
  
  
-.vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
+.vitem &*${substr{*&<&'start'&>&*}{*&<&'len'&>&*}{*&<&'subject'&>&*}}*&
  .cindex "&%substr%& expansion item"
  .cindex "substring extraction"
  .cindex "expansion" "substring extraction"
  The three strings are expanded; the first two must yield numbers. Call them
  <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
  .cindex "&%substr%& expansion item"
  .cindex "substring extraction"
  .cindex "expansion" "substring extraction"
  The three strings are expanded; the first two must yield numbers. Call them
  <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
-if <&'string1'&> and <&'string2'&> do not change when they are expanded, you
+if <&'start'&> and <&'len'&> do not change when they are expanded, you
  can use the simpler operator notation that avoids some of the braces:
  .code
  can use the simpler operator notation that avoids some of the braces:
  .code
-${substr_<n>_<m>:<string>}
+${substr_<n>_<m>:<subject>}
  .endd
  The second number is optional (in both notations).
  If it is absent in the simpler format, the preceding underscore must also be
  .endd
  The second number is optional (in both notations).
  If it is absent in the simpler format, the preceding underscore must also be
@@ -11600,14 +11634,14 @@ condition.
  .cindex "expansion" "numeric comparison"
  There are a number of symbolic operators for doing numeric comparisons. They
  are:
  .cindex "expansion" "numeric comparison"
  There are a number of symbolic operators for doing numeric comparisons. They
  are:
-.display
-&`=   `&   equal
-&`==  `&   equal
-&`>   `&   greater
-&`>=  `&   greater or equal
-&`<   `&   less
-&`<=  `&   less or equal
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow "=   " "equal"
+.irow "==  " "equal"
+.irow ">   " "greater"
+.irow ">=  " "greater or equal"
+.irow "<   " "less"
+.irow "<=  " "less or equal"
+.endtable
  For example:
  .code
  ${if >{$message_size}{10M} ...
  For example:
  .code
  ${if >{$message_size}{10M} ...
@@ -11906,6 +11940,20 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
    ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
  .endd
  
    ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
  .endd
  
+.new
+The variable &$value$& will be set for a successful match and can be
+used in the success clause of an &%if%& expansion item using the condition.
+.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using an inlist expansion condition"
+It will have the same taint status as the list; expansions such as
+.code
+${if inlist {$h_mycode:} {0 : 1 : 42} {$value}}
+.endd
+can be used for de-tainting.
+Any previous &$value$& is restored after the if.
+.wen
+
+
  .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
         &*isip4&~{*&<&'string'&>&*}*& &&&
         &*isip6&~{*&<&'string'&>&*}*&
  .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
         &*isip4&~{*&<&'string'&>&*}*& &&&
         &*isip6&~{*&<&'string'&>&*}*&
@@ -12102,6 +12150,19 @@ item can be used, as in all address lists, to cause subsequent items to
  have their local parts matched casefully. Domains are always matched
  caselessly.
  
  have their local parts matched casefully. Domains are always matched
  caselessly.
  
+.new
+The variable &$value$& will be set for a successful match and can be
+used in the success clause of an &%if%& expansion item using the condition.
+.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a match_local_part expansion condition"
+It will have the same taint status as the list; expansions such as
+.code
+${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}}
+.endd
+can be used for de-tainting.
+Any previous &$value$& is restored after the if.
+.wen
+
  Note that <&'string2'&> is not itself subject to string expansion, unless
  Exim was built with the EXPAND_LISTMATCH_RHS option.
  
  Note that <&'string2'&> is not itself subject to string expansion, unless
  Exim was built with the EXPAND_LISTMATCH_RHS option.
  
@@ -12297,6 +12358,16 @@ parsed but not evaluated.
  This section contains an alphabetical list of all the expansion variables. Some
  of them are available only when Exim is compiled with specific options such as
  support for TLS or the content scanning extension.
  This section contains an alphabetical list of all the expansion variables. Some
  of them are available only when Exim is compiled with specific options such as
  support for TLS or the content scanning extension.
+.new
+.cindex "tainted data"
+Variables marked as &'tainted'& are likely to carry data supplied by
+a potential attacker.
+Variables without such marking may also, depending on how their
+values are created.
+Such variables should not be further expanded,
+used as filenames
+or used as command-line arguments for external commands.
+.wen
  
  .vlist
  .vitem "&$0$&, &$1$&, etc"
  
  .vlist
  .vitem "&$0$&, &$1$&, etc"
@@ -12311,6 +12382,9 @@ variables may also be set externally by some other matching process which
  precedes the expansion of the string. For example, the commands available in
  Exim filter files include an &%if%& command with its own regular expression
  matching condition.
  precedes the expansion of the string. For example, the commands available in
  Exim filter files include an &%if%& command with its own regular expression
  matching condition.
+.new
+If the subject string was tainted then any captured substring will also be.
+.wen
  
  .vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
  Within an acl condition, expansion condition or expansion item
  
  .vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
  Within an acl condition, expansion condition or expansion item
@@ -12436,11 +12510,10 @@ authentication, which means this variable could also be visible in all of
  the ACL's as well.
  
  
  the ACL's as well.
  
  
-.vitem &$authenticated_sender$&
+.tvar &$authenticated_sender$&
  .cindex "sender" "authenticated"
  .cindex "authentication" "sender"
  .cindex "AUTH" "on MAIL command"
  .cindex "sender" "authenticated"
  .cindex "authentication" "sender"
  .cindex "AUTH" "on MAIL command"
-.vindex "&$authenticated_sender$&"
  When acting as a server, Exim takes note of the AUTH= parameter on an incoming
  SMTP MAIL command if it believes the sender is sufficiently trusted, as
  described in section &<<SECTauthparamail>>&. Unless the data is the string
  When acting as a server, Exim takes note of the AUTH= parameter on an incoming
  SMTP MAIL command if it believes the sender is sufficiently trusted, as
  described in section &<<SECTauthparamail>>&. Unless the data is the string
@@ -12463,9 +12536,10 @@ command that does not succeed. Otherwise it is set to &"0"&. This makes it
  possible to distinguish between &"did not try to authenticate"&
  (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to
  &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$&
  possible to distinguish between &"did not try to authenticate"&
  (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to
  &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$&
-is empty and &$authentication_failed$& is set to &"1"&). Failure includes any
-negative response to an AUTH command, including (for example) an attempt to use
-an undefined mechanism.
+is empty and &$authentication_failed$& is set to &"1"&).
+Failure includes cancellation of a authentication attempt,
+and any negative response to an AUTH command,
+(including, for example, an attempt to use an undefined mechanism).
  
  .vitem &$av_failed$&
  .cindex "content scanning" "AV scanner failure"
  
  .vitem &$av_failed$&
  .cindex "content scanning" "AV scanner failure"
@@ -12592,8 +12666,7 @@ the following data from the lookup: the list's domain name, the key that was
  looked up, the contents of any associated TXT record, and the value from the
  main A record. See section &<<SECID204>>& for more details.
  
  looked up, the contents of any associated TXT record, and the value from the
  main A record. See section &<<SECID204>>& for more details.
  
-.vitem &$domain$&
-.vindex "&$domain$&"
+.tvar &$domain$&
  When an address is being routed, or delivered on its own, this variable
  contains the domain. Uppercase letters in the domain are converted into lower
  case for &$domain$&.
  When an address is being routed, or delivered on its own, this variable
  contains the domain. Uppercase letters in the domain are converted into lower
  case for &$domain$&.
@@ -12694,6 +12767,7 @@ There may be other characters following the minor version.
  This value may be overridden by the &%exim_version%& main config option.
  
  .vitem &$header_$&<&'name'&>
  This value may be overridden by the &%exim_version%& main config option.
  
  .vitem &$header_$&<&'name'&>
+.tmark
  This is not strictly an expansion variable. It is expansion syntax for
  inserting the message header line with the given name. Note that the name must
  be terminated by colon or white space, because it may contain a wide variety of
  This is not strictly an expansion variable. It is expansion syntax for
  inserting the message header line with the given name. Note that the name must
  be terminated by colon or white space, because it may contain a wide variety of
@@ -12754,6 +12828,7 @@ allows you, for example, to do things like this:
  deny  hosts = net-lsearch;/some/file
        message = $host_data
  .endd
  deny  hosts = net-lsearch;/some/file
        message = $host_data
  .endd
+
  .vitem &$host_lookup_deferred$&
  .cindex "host name" "lookup, failure of"
  .vindex "&$host_lookup_deferred$&"
  .vitem &$host_lookup_deferred$&
  .cindex "host name" "lookup, failure of"
  .vindex "&$host_lookup_deferred$&"
@@ -12836,8 +12911,7 @@ This variable contains the system load average, multiplied by 1000 so that it
  is an integer. For example, if the load average is 0.21, the value of the
  variable is 210. The value is recomputed every time the variable is referenced.
  
  is an integer. For example, if the load average is 0.21, the value of the
  variable is 210. The value is recomputed every time the variable is referenced.
  
-.vitem &$local_part$&
-.vindex "&$local_part$&"
+.tvar &$local_part$&
  When an address is being routed, or delivered on its own, this
  variable contains the local part. When a number of addresses are being
  delivered together (for example, multiple RCPT commands in an SMTP
  When an address is being routed, or delivered on its own, this
  variable contains the local part. When a number of addresses are being
  delivered together (for example, multiple RCPT commands in an SMTP
@@ -13012,11 +13086,10 @@ This variable is set at the start of a delivery attempt to contain the number
  of seconds since the message was received. It does not change during a single
  delivery attempt.
  
  of seconds since the message was received. It does not change during a single
  delivery attempt.
  
-.vitem &$message_body$&
+.tvar &$message_body$&
  .cindex "body of message" "expansion variable"
  .cindex "message body" "in expansion"
  .cindex "binary zero" "in message body"
  .cindex "body of message" "expansion variable"
  .cindex "message body" "in expansion"
  .cindex "binary zero" "in message body"
-.vindex "&$message_body$&"
  .oindex "&%message_body_visible%&"
  This variable contains the initial portion of a message's body while it is
  being delivered, and is intended mainly for use in filter files. The maximum
  .oindex "&%message_body_visible%&"
  This variable contains the initial portion of a message's body while it is
  being delivered, and is intended mainly for use in filter files. The maximum
@@ -13029,10 +13102,9 @@ easier to search for phrases that might be split over a line break. However,
  this can be disabled by setting &%message_body_newlines%& to be true. Binary
  zeros are always converted into spaces.
  
  this can be disabled by setting &%message_body_newlines%& to be true. Binary
  zeros are always converted into spaces.
  
-.vitem &$message_body_end$&
+.tvar &$message_body_end$&
  .cindex "body of message" "expansion variable"
  .cindex "message body" "in expansion"
  .cindex "body of message" "expansion variable"
  .cindex "message body" "in expansion"
-.vindex "&$message_body_end$&"
  This variable contains the final portion of a message's
  body while it is being delivered. The format and maximum size are as for
  &$message_body$&.
  This variable contains the final portion of a message's
  body while it is being delivered. The format and maximum size are as for
  &$message_body$&.
@@ -13059,15 +13131,13 @@ received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header
  line; it is the local id that Exim assigns to the message, for example:
  &`1BXTIK-0001yO-VA`&.
  
  line; it is the local id that Exim assigns to the message, for example:
  &`1BXTIK-0001yO-VA`&.
  
-.vitem &$message_headers$&
-.vindex &$message_headers$&
+.tvar &$message_headers$&
  This variable contains a concatenation of all the header lines when a message
  is being processed, except for lines added by routers or transports. The header
  lines are separated by newline characters. Their contents are decoded in the
  same way as a header line that is inserted by &%bheader%&.
  
  This variable contains a concatenation of all the header lines when a message
  is being processed, except for lines added by routers or transports. The header
  lines are separated by newline characters. Their contents are decoded in the
  same way as a header line that is inserted by &%bheader%&.
  
-.vitem &$message_headers_raw$&
-.vindex &$message_headers_raw$&
+.tvar &$message_headers_raw$&
  This variable is like &$message_headers$& except that no processing of the
  contents of header lines is done.
  
  This variable is like &$message_headers$& except that no processing of the
  contents of header lines is done.
  
@@ -13144,9 +13214,8 @@ details, see section &<<SECTscanmimepart>>&.
  These variables are counters that can be incremented by means
  of the &%add%& command in filter files.
  
  These variables are counters that can be incremented by means
  of the &%add%& command in filter files.
  
-.vitem &$original_domain$&
+.tvar &$original_domain$&
  .vindex "&$domain$&"
  .vindex "&$domain$&"
-.vindex "&$original_domain$&"
  When a top-level address is being processed for delivery, this contains the
  same value as &$domain$&. However, if a &"child"& address (for example,
  generated by an alias, forward, or filter file) is being processed, this
  When a top-level address is being processed for delivery, this contains the
  same value as &$domain$&. However, if a &"child"& address (for example,
  generated by an alias, forward, or filter file) is being processed, this
@@ -13159,9 +13228,8 @@ If a new address is created by means of a &%deliver%& command in a system
  filter, it is set up with an artificial &"parent"& address. This has the local
  part &'system-filter'& and the default qualify domain.
  
  filter, it is set up with an artificial &"parent"& address. This has the local
  part &'system-filter'& and the default qualify domain.
  
-.vitem &$original_local_part$&
+.tvar &$original_local_part$&
  .vindex "&$local_part$&"
  .vindex "&$local_part$&"
-.vindex "&$original_local_part$&"
  When a top-level address is being processed for delivery, this contains the
  same value as &$local_part$&, unless a prefix or suffix was removed from the
  local part, because &$original_local_part$& always contains the full local
  When a top-level address is being processed for delivery, this contains the
  same value as &$local_part$&, unless a prefix or suffix was removed from the
  local part, because &$original_local_part$& always contains the full local
@@ -13199,13 +13267,11 @@ messages received via the command line, this is the uid of the sending user.
  For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
  user.
  
  For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
  user.
  
-.vitem &$parent_domain$&
-.vindex "&$parent_domain$&"
+.tvar &$parent_domain$&
  This variable is similar to &$original_domain$& (see
  above), except that it refers to the immediately preceding parent address.
  
  This variable is similar to &$original_domain$& (see
  above), except that it refers to the immediately preceding parent address.
  
-.vitem &$parent_local_part$&
-.vindex "&$parent_local_part$&"
+.tvar &$parent_local_part$&
  This variable is similar to &$original_local_part$&
  (see above), except that it refers to the immediately preceding parent address.
  
  This variable is similar to &$original_local_part$&
  (see above), except that it refers to the immediately preceding parent address.
  
@@ -13224,6 +13290,11 @@ This is not an expansion variable, but is mentioned here because the string
  (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
  It cannot be used in general expansion strings, and provokes an &"unknown
  variable"& error if encountered.
  (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
  It cannot be used in general expansion strings, and provokes an &"unknown
  variable"& error if encountered.
+.new
+&*Note*&: This value permits data supplied by a potential attacker to
+be used in the command for a &(pipe)& transport.
+Such configurations should be carefully assessed for security vulnerbilities.
+.wen
  
  .vitem &$primary_hostname$&
  .vindex "&$primary_hostname$&"
  
  .vitem &$primary_hostname$&
  .vindex "&$primary_hostname$&"
@@ -13313,8 +13384,7 @@ including the one added by Exim (so its value is always greater than zero). It
  is available in the DATA ACL, the non-SMTP ACL, and while routing and
  delivering.
  
  is available in the DATA ACL, the non-SMTP ACL, and while routing and
  delivering.
  
-.vitem &$received_for$&
-.vindex "&$received_for$&"
+.tvar &$received_for$&
  If there is only a single recipient address in an incoming message, this
  variable contains that address when the &'Received:'& header line is being
  built. The value is copied after recipient rewriting has happened, but before
  If there is only a single recipient address in an incoming message, this
  variable contains that address when the &'Received:'& header line is being
  built. The value is copied after recipient rewriting has happened, but before
@@ -13406,8 +13476,7 @@ MAIL).
  The main use of this variable is expected to be to distinguish between
  rejections of MAIL and rejections of RCPT.
  
  The main use of this variable is expected to be to distinguish between
  rejections of MAIL and rejections of RCPT.
  
-.vitem &$recipients$&
-.vindex "&$recipients$&"
+.tvar &$recipients$&
  This variable contains a list of envelope recipients for a message. A comma and
  a space separate the addresses in the replacement text. However, the variable
  is not generally available, to prevent exposure of Bcc recipients in
  This variable contains a list of envelope recipients for a message. A comma and
  a space separate the addresses in the replacement text. However, the variable
  is not generally available, to prevent exposure of Bcc recipients in
@@ -13444,10 +13513,12 @@ This variable is set to contain the matching regular expression after a
  When a &%regex%& or &%mime_regex%& ACL condition succeeds,
  these variables contain the
  captured substrings identified by the regular expression.
  When a &%regex%& or &%mime_regex%& ACL condition succeeds,
  these variables contain the
  captured substrings identified by the regular expression.
+.new
+If the subject string was tainted then so will any captured substring.
+.wen
  
  
  
  
-.vitem &$reply_address$&
-.vindex "&$reply_address$&"
+.tvar &$reply_address$&
  When a message is being processed, this variable contains the contents of the
  &'Reply-To:'& header line if one exists and it is not empty, or otherwise the
  contents of the &'From:'& header line. Apart from the removal of leading
  When a message is being processed, this variable contains the contents of the
  &'Reply-To:'& header line if one exists and it is not empty, or otherwise the
  contents of the &'From:'& header line. Apart from the removal of leading
@@ -13496,8 +13567,7 @@ One of its values causes the address to be passed to another router. When this
  happens, &$self_hostname$& is set to the name of the local host that the
  original router encountered. In other circumstances its contents are null.
  
  happens, &$self_hostname$& is set to the name of the local host that the
  original router encountered. In other circumstances its contents are null.
  
-.vitem &$sender_address$&
-.vindex "&$sender_address$&"
+.tvar &$sender_address$&
  When a message is being processed, this variable contains the sender's address
  that was received in the message's envelope. The case of letters in the address
  is retained, in both the local part and the domain. For bounce messages, the
  When a message is being processed, this variable contains the sender's address
  that was received in the message's envelope. The case of letters in the address
  is retained, in both the local part and the domain. For bounce messages, the
@@ -13512,12 +13582,10 @@ distinguish it from data from a recipient address. The value does not persist
  after the end of the current ACL statement. If you want to preserve it for
  longer, you can save it in an ACL variable.
  
  after the end of the current ACL statement. If you want to preserve it for
  longer, you can save it in an ACL variable.
  
-.vitem &$sender_address_domain$&
-.vindex "&$sender_address_domain$&"
+.tvar &$sender_address_domain$&
  The domain portion of &$sender_address$&.
  
  The domain portion of &$sender_address$&.
  
-.vitem &$sender_address_local_part$&
-.vindex "&$sender_address_local_part$&"
+.tvar &$sender_address_local_part$&
  The local part portion of &$sender_address$&.
  
  .vitem &$sender_data$&
  The local part portion of &$sender_address$&.
  
  .vitem &$sender_data$&
@@ -13555,8 +13623,7 @@ This boolean variable is true if a successful HELO verification was
  .cindex "DNS" "DNSSEC"
  done using DNS information the resolver library stated was authenticated data.
  
  .cindex "DNS" "DNSSEC"
  done using DNS information the resolver library stated was authenticated data.
  
-.vitem &$sender_helo_name$&
-.vindex "&$sender_helo_name$&"
+.tvar &$sender_helo_name$&
  When a message is received from a remote host that has issued a HELO or EHLO
  command, the argument of that command is placed in this variable. It is also
  set if HELO or EHLO is used when a message is received using SMTP locally via
  When a message is received from a remote host that has issued a HELO or EHLO
  command, the argument of that command is placed in this variable. It is also
  set if HELO or EHLO is used when a message is received using SMTP locally via
@@ -13613,8 +13680,7 @@ all EDNS0 options, then this will have no effect.  OpenBSD's asr resolver
  is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
  
  
  is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
  
  
-.vitem &$sender_host_name$&
-.vindex "&$sender_host_name$&"
+.tvar &$sender_host_name$&
  When a message is received from a remote host, this variable contains the
  host's name as obtained by looking up its IP address. For messages received by
  other means, this variable is empty.
  When a message is received from a remote host, this variable contains the
  host's name as obtained by looking up its IP address. For messages received by
  other means, this variable is empty.
@@ -13732,8 +13798,7 @@ host name, as specified by the &%smtp_active_hostname%& option. The value of
  &$smtp_active_hostname$& is saved with any message that is received, so its
  value can be consulted during routing and delivery.
  
  &$smtp_active_hostname$& is saved with any message that is received, so its
  value can be consulted during routing and delivery.
  
-.vitem &$smtp_command$&
-.vindex "&$smtp_command$&"
+.tvar &$smtp_command$&
  During the processing of an incoming SMTP command, this variable contains the
  entire command. This makes it possible to distinguish between HELO and EHLO in
  the HELO ACL, and also to distinguish between commands such as these:
  During the processing of an incoming SMTP command, this variable contains the
  entire command. This makes it possible to distinguish between HELO and EHLO in
  the HELO ACL, and also to distinguish between commands such as these:
@@ -13746,9 +13811,8 @@ command, the address in &$smtp_command$& is the original address before any
  rewriting, whereas the values in &$local_part$& and &$domain$& are taken from
  the address after SMTP-time rewriting.
  
  rewriting, whereas the values in &$local_part$& and &$domain$& are taken from
  the address after SMTP-time rewriting.
  
-.vitem &$smtp_command_argument$&
+.tvar &$smtp_command_argument$&
  .cindex "SMTP" "command, argument for"
  .cindex "SMTP" "command, argument for"
-.vindex "&$smtp_command_argument$&"
  While an ACL is running to check an SMTP command, this variable contains the
  argument, that is, the text that follows the command name, with leading white
  space removed. Following the introduction of &$smtp_command$&, this variable is
  While an ACL is running to check an SMTP command, this variable contains the
  argument, that is, the text that follows the command name, with leading white
  space removed. Following the introduction of &$smtp_command$&, this variable is
@@ -13989,8 +14053,7 @@ which is not the leaf.
  Observability for TLS session resumption.  See &<<SECTresumption>>& for details.
  
  
  Observability for TLS session resumption.  See &<<SECTresumption>>& for details.
  
  
-.vitem &$tls_in_sni$&
-.vindex "&$tls_in_sni$&"
+.tvar &$tls_in_sni$&
  .vindex "&$tls_sni$&"
  .cindex "TLS" "Server Name Indication"
  .cindex "TLS" SNI
  .vindex "&$tls_sni$&"
  .cindex "TLS" "Server Name Indication"
  .cindex "TLS" SNI
@@ -14609,7 +14672,6 @@ listed in more than one group.
  .section "Miscellaneous" "SECID96"
  .table2
  .row &%add_environment%&             "environment variables"
  .section "Miscellaneous" "SECID96"
  .table2
  .row &%add_environment%&             "environment variables"
-.row &%allow_insecure_tainted_data%& "turn taint errors into warnings"
  .row &%bi_command%&                  "to run for &%-bi%& command line option"
  .row &%debug_store%&                 "do extra internal checks"
  .row &%disable_ipv6%&                "do no IPv6 processing"
  .row &%bi_command%&                  "to run for &%-bi%& command line option"
  .row &%debug_store%&                 "do extra internal checks"
  .row &%disable_ipv6%&                "do no IPv6 processing"
@@ -14836,6 +14898,7 @@ listed in more than one group.
  .row &%gnutls_compat_mode%&          "use GnuTLS compatibility mode"
  .row &%gnutls_allow_auto_pkcs11%&    "allow GnuTLS to autoload PKCS11 modules"
  .row &%hosts_require_alpn%&          "mandatory ALPN"
  .row &%gnutls_compat_mode%&          "use GnuTLS compatibility mode"
  .row &%gnutls_allow_auto_pkcs11%&    "allow GnuTLS to autoload PKCS11 modules"
  .row &%hosts_require_alpn%&          "mandatory ALPN"
+.row &%hosts_require_helo%&          "mandatory HELO/EHLO"
  .row &%openssl_options%&             "adjust OpenSSL compatibility options"
  .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
  .row &%tls_alpn%&                   "acceptable protocol names"
  .row &%openssl_options%&             "adjust OpenSSL compatibility options"
  .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
  .row &%tls_alpn%&                   "acceptable protocol names"
@@ -15223,17 +15286,6 @@ domains (defined in the named domain list &%local_domains%& in the default
  configuration). This &"magic string"& matches the domain literal form of all
  the local host's IP addresses.
  
  configuration). This &"magic string"& matches the domain literal form of all
  the local host's IP addresses.
  
-.option allow_insecure_tainted_data main boolean false
-.cindex "de-tainting"
-.oindex "allow_insecure_tainted_data"
-The handling of tainted data may break older (pre 4.94) configurations.
-Setting this option to "true" turns taint errors (which result in a temporary
-message rejection) into warnings. This option is meant as mitigation only
-and deprecated already today. Future releases of Exim may ignore it.
-The &%taint%& log selector can be used to suppress even the warnings.
-
-
-
  .option allow_mx_to_ip main boolean false
  .cindex "MX record" "pointing to IP address"
  It appears that more and more DNS zone administrators are breaking the rules
  .option allow_mx_to_ip main boolean false
  .cindex "MX record" "pointing to IP address"
  It appears that more and more DNS zone administrators are breaking the rules
@@ -16350,6 +16402,12 @@ See also the &%tls_alpn%& option.
  managed by this option, and should be done separately.
  
  
  managed by this option, and should be done separately.
  
  
+.option hosts_require_helo main "host list&!!" *
+.cindex "HELO/EHLO" requiring
+Exim will require an accepted HELO or EHLO command from a host matching
+this list, before accepting a MAIL command.
+
+
  .option hosts_proxy main "host list&!!" unset
  .cindex proxy "proxy protocol"
  This option enables use of Proxy Protocol proxies for incoming
  .option hosts_proxy main "host list&!!" unset
  .cindex proxy "proxy protocol"
  This option enables use of Proxy Protocol proxies for incoming
@@ -17078,9 +17136,9 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&).
  
  .option pipelining_connect_advertise_hosts main "host list&!!" *
  .cindex "pipelining" "early connection"
  
  .option pipelining_connect_advertise_hosts main "host list&!!" *
  .cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
-.cindex "ESMTP extensions" PIPE_CONNECT
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+.cindex "pipelining" PIPECONNECT
+.cindex "ESMTP extensions" PIPECONNECT
+If Exim is built without the DISABLE_PIPE_CONNECT build option
  this option controls which hosts the facility is advertised to
  and from which pipeline early-connection (before MAIL) SMTP
  commands are acceptable.
  this option controls which hosts the facility is advertised to
  and from which pipeline early-connection (before MAIL) SMTP
  commands are acceptable.
@@ -17088,7 +17146,11 @@ When used, the pipelining saves on roundtrip times.
  
  See also the &%hosts_pipe_connect%& smtp transport option.
  
  
  See also the &%hosts_pipe_connect%& smtp transport option.
  
-The SMTP service extension keyword advertised is &"PIPE_CONNECT"&.
+The SMTP service extension keyword advertised is &"PIPECONNECT"&;
+it permits the client to pipeline
+TCP connection and hello command (inclear phase),
+or TLS-establishment and hello command (encrypted phase),
+on later connections to the same host.
  
  
  .option prdr_enable main boolean false
  
  
  .option prdr_enable main boolean false
@@ -18989,6 +19051,7 @@ than trying to read &_/etc/passwd_& directly. This means that other methods of
  holding password data (such as NIS) are supported. If the local part is a local
  user,
  .cindex "tainted data" "de-tainting"
  holding password data (such as NIS) are supported. If the local part is a local
  user,
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router check_local_user option"
  &$local_part_data$& is set to an untainted version of the local part and
  &$home$& is set from the password data. The latter can be tested in other
  preconditions that are evaluated after this one (the order of evaluation is
  &$local_part_data$& is set to an untainted version of the local part and
  &$home$& is set from the password data. The latter can be tested in other
  preconditions that are evaluated after this one (the order of evaluation is
@@ -22822,9 +22885,10 @@ an ideal name for this feature here, but as it was already implemented for the
  The expansion variables &$host$& and &$host_address$& are available when the
  transport is a remote one. They contain the name and IP address of the host to
  which the message is being sent. For example:
  The expansion variables &$host$& and &$host_address$& are available when the
  transport is a remote one. They contain the name and IP address of the host to
  which the message is being sent. For example:
+. used to have $sender_address in this cmdline, but it's tainted
  .code
  transport_filter = /some/directory/transport-filter.pl \
  .code
  transport_filter = /some/directory/transport-filter.pl \
-  $host $host_address $sender_address $pipe_addresses
+  $host $host_address $pipe_addresses
  .endd
  
  Two problems arise if you want to use more complicated expansion items to
  .endd
  
  Two problems arise if you want to use more complicated expansion items to
@@ -23260,6 +23324,7 @@ The value is used for checking instead of a home directory;
  checking is done in "belowhome" mode.
  
  .cindex "tainted data" "de-tainting"
  checking is done in "belowhome" mode.
  
  .cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using appendfile create_file option"
  If "belowhome" checking is used, the file or directory path
  becomes de-tainted.
  
  If "belowhome" checking is used, the file or directory path
  becomes de-tainted.
  
@@ -24695,6 +24760,11 @@ This list is a compromise for maximum compatibility with other MTAs. Note that
  the &%environment%& option can be used to add additional variables to this
  environment. The environment for the &(pipe)& transport is not subject
  to the &%add_environment%& and &%keep_environment%& main config options.
  the &%environment%& option can be used to add additional variables to this
  environment. The environment for the &(pipe)& transport is not subject
  to the &%add_environment%& and &%keep_environment%& main config options.
+.new
+&*Note*&: Using enviroment variables loses track of tainted data.
+Writers of &(pipe)& transport commands should be wary of data supplied
+by potential attackers.
+.wen
  .display
  &`DOMAIN            `&   the domain of the address
  &`HOME              `&   the home directory, if set
  .display
  &`DOMAIN            `&   the domain of the address
  &`HOME              `&   the home directory, if set
@@ -24786,6 +24856,11 @@ the &%path%& option below). The command is split up into separate arguments by
  Exim, and each argument is separately expanded, as described in section
  &<<SECThowcommandrun>>& above.
  
  Exim, and each argument is separately expanded, as described in section
  &<<SECThowcommandrun>>& above.
  
+.new
+.cindex "tainted data"
+No part of the resulting command may be tainted.
+.wen
+
  
  .option environment pipe string&!! unset
  .cindex "&(pipe)& transport" "environment for command"
  
  .option environment pipe string&!! unset
  .cindex "&(pipe)& transport" "environment for command"
@@ -25101,12 +25176,15 @@ use a shell to run pipe commands.
  .cindex "Cyrus"
  The next example shows a transport and a router for a system where local
  deliveries are handled by the Cyrus IMAP server.
  .cindex "Cyrus"
  The next example shows a transport and a router for a system where local
  deliveries are handled by the Cyrus IMAP server.
+. Used to have R: local_part_suffix = .* +  T:   -m $local_part_suffix_v
+. but that suffix is tainted so cannot be used in a command arg
+. Really, you'd want to use a lookup for acceptable suffixes to do real detainting
  .code
  # transport
  local_delivery_cyrus:
    driver = pipe
    command = /usr/cyrus/bin/deliver \
  .code
  # transport
  local_delivery_cyrus:
    driver = pipe
    command = /usr/cyrus/bin/deliver \
-            -m ${substr_1:$local_part_suffix} -- $local_part
+            -- $local_part_data
    user = cyrus
    group = mail
    return_output
    user = cyrus
    group = mail
    return_output
@@ -25118,7 +25196,6 @@ local_delivery_cyrus:
  local_user_cyrus:
    driver = accept
    check_local_user
  local_user_cyrus:
    driver = accept
    check_local_user
-  local_part_suffix = .*
    transport = local_delivery_cyrus
  .endd
  Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of
    transport = local_delivery_cyrus
  .endd
  Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of
@@ -25484,12 +25561,45 @@ servers or different local IP addresses. For example, if you want the string
  that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing
  interface address, you could use this:
  .code
  that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing
  interface address, you could use this:
  .code
-helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
+helo_data = ${lookup dnsdb{ptr=$sending_ip_address} \
+  {${listextract{1}{<\n $value}}} \
    {$primary_hostname}}
  .endd
  The use of &%helo_data%& applies both to sending messages and when doing
  callouts.
  
    {$primary_hostname}}
  .endd
  The use of &%helo_data%& applies both to sending messages and when doing
  callouts.
  
+.new
+.option host_name_extract smtp "string list&!!" "see below"
+.cindex "load balancer" "hosts behind"
+.cindex TLS resumption
+Some mail-accepting sites
+(notably Microsoft)
+operate many servers behind a network load-balancer.  When this is done,
+with separated TLS session caches, TLS session resuption becomes problematic.
+It will only succeed when the same server happens to be selected by the
+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.
+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.
+During the expansion of this option the &$item$& variable will have the
+server's EHLO response.
+The result of the option expansion is included in the key used to store and
+retrieve the TLS session, for session resumption.
+
+Operators of high-load sites may wish to evaluate their logs for indications
+of other destination sites operating load-balancers, and develop a suitable
+expression for this option.
+The smtp:ehlo event and the &$tls_out_resumption$& variable
+will be useful for such work.
+.wen
+
  .option hosts smtp "string list&!!" unset
  Hosts are associated with an address by a router such as &(dnslookup)&, which
  finds the hosts by looking up the address domain in the DNS, or by
  .option hosts smtp "string list&!!" unset
  Hosts are associated with an address by a router such as &(dnslookup)&, which
  finds the hosts by looking up the address domain in the DNS, or by
@@ -25543,7 +25653,7 @@ that matches this list, even if the server host advertises PIPELINING support.
  
  .option hosts_pipe_connect smtp "host list&!!" unset
  .cindex "pipelining" "early connection"
  
  .option hosts_pipe_connect smtp "host list&!!" unset
  .cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
+.cindex "pipelining" PIPECONNECT
  If Exim is built with the SUPPORT_PIPE_CONNECT build option
  this option controls which to hosts the facility watched for
  and recorded, and used for subsequent connections.
  If Exim is built with the SUPPORT_PIPE_CONNECT build option
  this option controls which to hosts the facility watched for
  and recorded, and used for subsequent connections.
@@ -25557,7 +25667,10 @@ so combines well with TCP Fast Open.
  See also the &%pipelining_connect_advertise_hosts%& main option.
  
  Note:
  See also the &%pipelining_connect_advertise_hosts%& main option.
  
  Note:
-When the facility is used, the transport &%helo_data%& option
+.new
+When the facility is used, if the transport &%interface%& option is unset
+the &%helo_data%& option
+.wen
  will be expanded before the &$sending_ip_address$& variable
  is filled in.
  A check is made for the use of that variable, without the
  will be expanded before the &$sending_ip_address$& variable
  is filled in.
  A check is made for the use of that variable, without the
@@ -25690,11 +25803,6 @@ There will be no fallback to in-clear communication.
  See the &%dnssec_request_domains%& router and transport options.
  See section &<<SECDANE>>&.
  
  See the &%dnssec_request_domains%& router and transport options.
  See section &<<SECDANE>>&.
  
-.option hosts_require_helo smtp "host list&!!" *
-.cindex "HELO/EHLO" requiring
-Exim will require an accepted HELO or EHLO command from a host matching
-this list, before accepting a MAIL command.
-
  .option hosts_require_ocsp smtp "host list&!!" unset
  .cindex "TLS" "requiring for certain servers"
  Exim will request, and check for a valid Certificate Status being given, on a
  .option hosts_require_ocsp smtp "host list&!!" unset
  .cindex "TLS" "requiring for certain servers"
  Exim will request, and check for a valid Certificate Status being given, on a
@@ -29833,8 +29941,10 @@ nothing more to it.  Choosing a sensible value not derived insecurely is the
  only point of caution.  The &$tls_out_sni$& variable will be set to this string
  for the lifetime of the client connection (including during authentication).
  
  only point of caution.  The &$tls_out_sni$& variable will be set to this string
  for the lifetime of the client connection (including during authentication).
  
+.new
  If DANE validated the connection attempt then the value of the &%tls_sni%& option
  If DANE validated the connection attempt then the value of the &%tls_sni%& option
-is forced to the domain part of the recipient address.
+is forced to the name of the destination host, after any MX- or CNAME-following.
+.wen
  
  Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string
  received from a client.
  
  Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string
  received from a client.
@@ -31613,6 +31723,8 @@ with &`-d`&, with the output going to a new logfile in the usual logs directory,
  by default called &'debuglog'&.
  
  .new
  by default called &'debuglog'&.
  
  .new
+Logging set up by the control will be maintained across spool residency.
+
  Options are a slash-separated list.
  If an option takes an argument, the option name and argument are separated by
  an equals character.
  Options are a slash-separated list.
  If an option takes an argument, the option name and argument are separated by
  an equals character.
@@ -32554,11 +32666,11 @@ This is usually the required action when &%dnslists%& is used with &%deny%&
  (which is the most common usage), because it prevents a DNS failure from
  blocking mail. However, you can change this behaviour by putting one of the
  following special items in the list:
  (which is the most common usage), because it prevents a DNS failure from
  blocking mail. However, you can change this behaviour by putting one of the
  following special items in the list:
-.display
-&`+include_unknown `&   behave as if the item is on the list
-&`+exclude_unknown `&   behave as if the item is not on the list (default)
-&`+defer_unknown   `&   give a temporary error
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow "+include_unknown"   "behave as if the item is on the list"
+.irow "+exclude_unknown"   "behave as if the item is not on the list (default)"
+.irow "+defer_unknown  "   "give a temporary error"
+.endtable
  .cindex "&`+include_unknown`&"
  .cindex "&`+exclude_unknown`&"
  .cindex "&`+defer_unknown`&"
  .cindex "&`+include_unknown`&"
  .cindex "&`+exclude_unknown`&"
  .cindex "&`+defer_unknown`&"
@@ -32707,15 +32819,15 @@ DNS lists are constructed using address records in the DNS. The original RBL
  just used the address 127.0.0.1 on the right hand side of each record, but the
  RBL+ list and some other lists use a number of values with different meanings.
  The values used on the RBL+ list are:
  just used the address 127.0.0.1 on the right hand side of each record, but the
  RBL+ list and some other lists use a number of values with different meanings.
  The values used on the RBL+ list are:
-.display
-127.1.0.1  RBL
-127.1.0.2  DUL
-127.1.0.3  DUL and RBL
-127.1.0.4  RSS
-127.1.0.5  RSS and RBL
-127.1.0.6  RSS and DUL
-127.1.0.7  RSS and DUL and RBL
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow 127.1.0.1  "RBL"
+.irow 127.1.0.2  "DUL"
+.irow 127.1.0.3  "DUL and RBL"
+.irow 127.1.0.4  "RSS"
+.irow 127.1.0.5  "RSS and RBL"
+.irow 127.1.0.6  "RSS and DUL"
+.irow 127.1.0.7  "RSS and DUL and RBL"
+.endtable
  Section &<<SECTaddmatcon>>& below describes how you can distinguish between
  different values. Some DNS lists may return more than one address record;
  see section &<<SECThanmuldnsrec>>& for details of how they are checked.
  Section &<<SECTaddmatcon>>& below describes how you can distinguish between
  different values. Some DNS lists may return more than one address record;
  see section &<<SECThanmuldnsrec>>& for details of how they are checked.
@@ -33028,7 +33140,7 @@ situation has been previously met.
  It uses a hints database to record a timestamp against a key.
  host. The syntax of the condition is:
  .display
  It uses a hints database to record a timestamp against a key.
  host. The syntax of the condition is:
  .display
-&`seen =`& <&'time interval'&> &`/`& <&'options'&>
+&`seen =`& <&'optional flag'&><&'time interval'&> &`/`& <&'options'&>
  .endd
  
  For example,
  .endd
  
  For example,
@@ -33037,8 +33149,10 @@ defer  seen = -5m / key=${sender_host_address}_$local_part@$domain
  .endd
  in a RCPT ACL will implement simple greylisting.
  
  .endd
  in a RCPT ACL will implement simple greylisting.
  
-The parameters for the condition
-are an interval followed, slash-separated, by a list of options.
+The parameters for the condition are
+a possible minus sign,
+then an interval,
+then, slash-separated, a list of options.
  The interval is taken as an offset before the current time,
  and used for the test.
  If the interval is preceded by a minus sign then the condition returns
  The interval is taken as an offset before the current time,
  and used for the test.
  If the interval is preceded by a minus sign then the condition returns
@@ -33056,6 +33170,8 @@ no record create or update is done.
  If a &%write%& option is given then
  a record create or update is always done.
  An update is done if the test is for &"since"&.
  If a &%write%& option is given then
  a record create or update is always done.
  An update is done if the test is for &"since"&.
+If none of those hold and there was no existing record,
+a record is created.
  
  Creates and updates are marked with the current time.
  
  
  Creates and updates are marked with the current time.
  
@@ -33513,6 +33629,15 @@ output before performing a callout in an ACL, to avoid unexpected timeouts in
  clients when the SMTP PIPELINING extension is in use. The flushing can be
  disabled by using a &%control%& modifier to set &%no_callout_flush%&.
  
  clients when the SMTP PIPELINING extension is in use. The flushing can be
  disabled by using a &%control%& modifier to set &%no_callout_flush%&.
  
+.new
+.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using receipient verify"
+A recipient callout which gets a 2&'xx'& code
+will assign untainted values to the
+&$domain_data$& and &$local_part_data$& variables,
+corresponding to the domain and local parts of the recipient address.
+.wen
+
  
  
  
  
  
  
@@ -35626,11 +35751,11 @@ added zero byte is not included in the returned count.
  .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*&
  This function checks for a match in a domain list. Domains are always
  matched caselessly. The return value is one of the following:
  .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*&
  This function checks for a match in a domain list. Domains are always
  matched caselessly. The return value is one of the following:
-.display
-&`OK     `& match succeeded
-&`FAIL   `& match failed
-&`DEFER  `& match deferred
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &`OK`&    "match succeeded"
+.irow &`FAIL`&  "match failed"
+.irow &`DEFER`& "match deferred"
+.endtable
  DEFER is usually caused by some kind of lookup defer, such as the
  inability to contact a database.
  
  DEFER is usually caused by some kind of lookup defer, such as the
  inability to contact a database.
  
@@ -38337,7 +38462,7 @@ LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
  &"syslog"&. This means that an empty item in &%log_file_path%& can be used to
  mean &"use the path specified at build time"&. If no such item exists, log
  files are written in the &_log_& subdirectory of the spool directory. This is
  &"syslog"&. This means that an empty item in &%log_file_path%& can be used to
  mean &"use the path specified at build time"&. If no such item exists, log
  files are written in the &_log_& subdirectory of the spool directory. This is
-equivalent to the setting:
+equivalent to the configuration file setting:
  .code
  log_file_path = $spool_directory/log/%slog
  .endd
  .code
  log_file_path = $spool_directory/log/%slog
  .endd
@@ -38348,7 +38473,7 @@ that is where the logs are written.
  A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames
  are in use &-- see section &<<SECTdatlogfil>>& below.
  
  A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames
  are in use &-- see section &<<SECTdatlogfil>>& below.
  
-Here are some examples of possible settings:
+Here are some examples of possible Makefile settings:
  .display
  &`LOG_FILE_PATH=syslog                    `& syslog only
  &`LOG_FILE_PATH=:syslog                   `& syslog and default path
  .display
  &`LOG_FILE_PATH=syslog                    `& syslog only
  &`LOG_FILE_PATH=:syslog                   `& syslog and default path
@@ -38523,16 +38648,16 @@ One line is written to the main log for each message received, and for each
  successful, unsuccessful, and delayed delivery. These lines can readily be
  picked out by the distinctive two-character flags that immediately follow the
  timestamp. The flags are:
  successful, unsuccessful, and delayed delivery. These lines can readily be
  picked out by the distinctive two-character flags that immediately follow the
  timestamp. The flags are:
-.display
-&`<=`&     message arrival
-&`(=`&     message fakereject
-&`=>`&     normal message delivery
-&`->`&     additional address in same delivery
-&`>>`&     cutthrough message delivery
-&`*>`&     delivery suppressed by &%-N%&
-&`**`&     delivery failed; address bounced
-&`==`&     delivery deferred; temporary problem
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &%<=%&     "message arrival"
+.irow &%(=%&     "message fakereject"
+.irow &%=>%&     "normal message delivery"
+.irow &%->%&     "additional address in same delivery"
+.irow &%>>%&     "cutthrough message delivery"
+.irow &%*>%&     "delivery suppressed by &%-N%&"
+.irow &%**%&     "delivery failed; address bounced"
+.irow &%==%&     "delivery deferred; temporary problem"
+.endtable
  
  
  .section "Logging message reception" "SECID251"
  
  
  .section "Logging message reception" "SECID251"
@@ -38851,66 +38976,64 @@ log_selector = +arguments -retry_defer
  .endd
  The list of optional log items is in the following table, with the default
  selection marked by asterisks:
  .endd
  The list of optional log items is in the following table, with the default
  selection marked by asterisks:
-.display
-&` 8bitmime                   `&  received 8BITMIME status
-&`*acl_warn_skipped           `&  skipped &%warn%& statement in ACL
-&` address_rewrite            `&  address rewriting
-&` all_parents                `&  all parents in => lines
-&` arguments                  `&  command line arguments
-&`*connection_reject          `&  connection rejections
-&`*delay_delivery             `&  immediate delivery delayed
-&` deliver_time               `&  time taken to attempt delivery
-&` delivery_size              `&  add &`S=`&&'nnn'& to => lines
-&`*dkim                       `&  DKIM verified domain on <= lines
-&` dkim_verbose               `&  separate full DKIM verification result line, per signature
-&`*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
-&` incoming_interface         `&  local interface on <= and => lines
-&` incoming_port              `&  remote port on <= lines
-&`*lost_incoming_connection   `&  as it says (includes timeouts)
-&` millisec                   `&  millisecond timestamps and RT,QT,DT,D times
-&`*msg_id                     `&  on <= lines, Message-ID: header value
-&` msg_id_created             `&  on <= lines, Message-ID: header value when one had to be added
-&` outgoing_interface         `&  local interface on => lines
-&` outgoing_port              `&  add remote port to => lines
-&`*queue_run                  `&  start and end queue runs
-&` queue_time                 `&  time on queue for one recipient
-&`*queue_time_exclusive       `&  exclude recieve time from QT times
-&` queue_time_overall         `&  time on queue for whole message
-&` pid                        `&  Exim process id
-&` pipelining                 `&  PIPELINING use, on <= and => lines
-&` proxy                      `&  proxy address on <= and => lines
-&` receive_time               `&  time taken to receive message
-&` received_recipients        `&  recipients on <= lines
-&` received_sender            `&  sender on <= lines
-&`*rejected_header            `&  header contents on reject log
-&`*retry_defer                `&  &"retry time not reached"&
-&` return_path_on_delivery    `&  put return path on => and ** lines
-&` sender_on_delivery         `&  add sender to => lines
-&`*sender_verify_fail         `&  sender verification failures
-&`*size_reject                `&  rejection because too big
-&`*skip_delivery              `&  delivery skipped in a queue run
-&`*smtp_confirmation          `&  SMTP confirmation on => lines
-&` smtp_connection            `&  incoming SMTP connections
-&` smtp_incomplete_transaction`&  incomplete SMTP transactions
-&` smtp_mailauth              `&  AUTH argument to MAIL commands
-&` smtp_no_mail               `&  session with no MAIL commands
-&` smtp_protocol_error        `&  SMTP protocol errors
-&` smtp_syntax_error          `&  SMTP syntax errors
-&` subject                    `&  contents of &'Subject:'& on <= lines
-&`*taint                      `&  taint errors or warnings
-&`*tls_certificate_verified   `&  certificate verification status
-&`*tls_cipher                 `&  TLS cipher suite on <= and => lines
-&` tls_peerdn                 `&  TLS peer DN on <= and => lines
-&` tls_resumption             `&  append * to cipher field
-&` tls_sni                    `&  TLS SNI on <= lines
-&` unknown_in_list            `&  DNS lookup failed in list match
-
-&` all                        `&  all of the above
-.endd
+.itable none 0 0 3 1pt left 10pt center 1pt left
+.irow &`8bitmime`&                     &nbsp; "received 8BITMIME status"
+.irow &`acl_warn_skipped`&             *       "skipped &%warn%& statement in ACL"
+.irow &`address_rewrite`&              &nbsp; "address rewriting"
+.irow &`all_parents`&                  &nbsp; "all parents in => lines"
+.irow &`arguments`&                    &nbsp; "command line arguments"
+.irow &`connection_reject`&            *       "connection rejections"
+.irow &`delay_delivery`&               *       "immediate delivery delayed"
+.irow &`deliver_time`&                 &nbsp; "time taken to attempt delivery"
+.irow &`delivery_size`&                        &nbsp; "add &`S=`&&'nnn'& to => lines"
+.irow &`dkim`&                         *       "DKIM verified domain on <= lines"
+.irow &`dkim_verbose`&                 &nbsp; "separate full DKIM verification result line, per signature"
+.irow &`dnslist_defer`&                        *       "defers of DNS list (aka RBL) lookups"
+.irow &`dnssec`&                       &nbsp; "DNSSEC secured lookups"
+.irow &`etrn`&                         *       "ETRN commands"
+.irow &`host_lookup_failed`&           *       "as it says"
+.irow &`ident_timeout`&                        &nbsp; "timeout for ident connection"
+.irow &`incoming_interface`&           &nbsp; "local interface on <= and => lines"
+.irow &`incoming_port`&                        &nbsp; "remote port on <= lines"
+.irow &`lost_incoming_connection`&     *       "as it says (includes timeouts)"
+.irow &`millisec`&                     &nbsp; "millisecond timestamps and RT,QT,DT,D times"
+.irow &`msg_id`&                       *       "on <= lines, Message-ID: header value"
+.irow &`msg_id_created`&               &nbsp; "on <= lines, Message-ID: header value when one had to be added"
+.irow &`outgoing_interface`&           &nbsp; "local interface on => lines"
+.irow &`outgoing_port`&                        &nbsp; "add remote port to => lines"
+.irow &`queue_run`&                    *       "start and end queue runs"
+.irow &`queue_time`&                   &nbsp; "time on queue for one recipient"
+.irow &`queue_time_exclusive`&         &nbsp; "exclude recieve time from QT times"
+.irow &`queue_time_overall`&           &nbsp; "time on queue for whole message"
+.irow &`pid`&                          &nbsp; "Exim process id"
+.irow &`pipelining`&                   &nbsp; "PIPELINING use, on <= and => lines"
+.irow &`proxy`&                                &nbsp; "proxy address on <= and => lines"
+.irow &`receive_time`&                 &nbsp; "time taken to receive message"
+.irow &`received_recipients`&          &nbsp; "recipients on <= lines"
+.irow &`received_sender`&              &nbsp; "sender on <= lines"
+.irow &`rejected_header`&              *       "header contents on reject log"
+.irow &`retry_defer`&                  *       "&<quote>&retry time not reached&</quote>&"
+.irow &`return_path_on_delivery`&      &nbsp; "put return path on => and ** lines"
+.irow &`sender_on_delivery`&           &nbsp; "add sender to => lines"
+.irow &`sender_verify_fail`&           *       "sender verification failures"
+.irow &`size_reject`&                  *       "rejection because too big"
+.irow &`skip_delivery`&                        *       "delivery skipped in a queue run"
+.irow &`smtp_confirmation`&            *       "SMTP confirmation on => lines"
+.irow &`smtp_connection`&              &nbsp; "incoming SMTP connections"
+.irow &`smtp_incomplete_transaction`&  &nbsp; "incomplete SMTP transactions"
+.irow &`smtp_mailauth`&                        &nbsp; "AUTH argument to MAIL commands"
+.irow &`smtp_no_mail`&                 &nbsp; "session with no MAIL commands"
+.irow &`smtp_protocol_error`&          &nbsp; "SMTP protocol errors"
+.irow &`smtp_syntax_error`&            &nbsp; "SMTP syntax errors"
+.irow &`subject`&                      &nbsp; "contents of &'Subject:'& on <= lines"
+.irow &`tls_certificate_verified`&     *       "certificate verification status"
+.irow &`tls_cipher`&                   *       "TLS cipher suite on <= and => 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 &`all`&                          &nbsp; "&*all of the above*&"
+.endtable
  See also the &%slow_lookup_log%& main configuration option,
  section &<<SECID99>>&
  
  See also the &%slow_lookup_log%& main configuration option,
  section &<<SECID99>>&
  
@@ -39106,7 +39229,7 @@ On accept lines, where PIPELINING was offered but not used by the client,
  the field has a minus appended.
  
  .cindex "pipelining" "early connection"
  the field has a minus appended.
  
  .cindex "pipelining" "early connection"
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+If Exim is built without the DISABLE_PIPE_CONNECT build option
  accept "L" fields have a period appended if the feature was
  offered but not used, or an asterisk appended if used.
  Delivery "L" fields have an asterisk appended if used.
  accept "L" fields have a period appended if the feature was
  offered but not used, or an asterisk appended if used.
  Delivery "L" fields have an asterisk appended if used.
@@ -39295,11 +39418,6 @@ using a CA trust anchor,
  &`CV=dane`& if using a DNS trust anchor,
  and &`CV=no`& if not.
  .next
  &`CV=dane`& if using a DNS trust anchor,
  and &`CV=no`& if not.
  .next
-.cindex "log" "Taint warnings"
-&%taint%&: Log warnings about tainted data. This selector can't be
-turned of if &%allow_insecure_tainted_data%& is false (which is the
-default).
-.next
  .cindex "log" "TLS cipher"
  .cindex "TLS" "logging cipher"
  &%tls_cipher%&: When a message is sent or received over an encrypted
  .cindex "log" "TLS cipher"
  .cindex "TLS" "logging cipher"
  &%tls_cipher%&: When a message is sent or received over an encrypted
@@ -39413,12 +39531,12 @@ but the format of the output is different. For this reason, there are some
  system configuration options that configure exactly how &'exiwhat'& works. If
  it doesn't seem to be working for you, check the following compile-time
  options:
  system configuration options that configure exactly how &'exiwhat'& works. If
  it doesn't seem to be working for you, check the following compile-time
  options:
-.display
-&`EXIWHAT_PS_CMD    `& the command for running &'ps'&
-&`EXIWHAT_PS_ARG    `& the argument for &'ps'&
-&`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output
-&`EXIWHAT_KILL_ARG  `& the argument for the &'kill'& command
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &`EXIWHAT_PS_CMD`&       "the command for running &'ps'&"
+.irow &`EXIWHAT_PS_ARG`&       "the argument for &'ps'&"
+.irow &`EXIWHAT_EGREP_ARG`&    "the argument for &'egrep'& to select from &'ps'& output"
+.irow &`EXIWHAT_KILL_ARG`&     "the argument for the &'kill'& command"
+.endtable
  An example of typical output from &'exiwhat'& is
  .code
  164 daemon: -q1h, listening on port 25
  An example of typical output from &'exiwhat'& is
  .code
  164 daemon: -q1h, listening on port 25
@@ -39444,9 +39562,6 @@ or (in case &*-a*& switch is specified)
  .code
  exim -bp
  .endd
  .code
  exim -bp
  .endd
-The &*-C*& option is used to specify an alternate &_exim.conf_& which might
-contain alternate exim configuration the queue management might be using.
-
  to obtain a queue listing, and then greps the output to select messages
  that match given criteria. The following selection options are available:
  
  to obtain a queue listing, and then greps the output to select messages
  that match given criteria. The following selection options are available:
  
@@ -39503,7 +39618,22 @@ Display messages in reverse order.
  Include delivered recipients in queue listing.
  .endlist
  
  Include delivered recipients in queue listing.
  .endlist
  
+The following options give alternates for configuration:
+
+.vlist
+.vitem &*-C*&&~<&'config&~file'&>
+is used to specify an alternate &_exim.conf_& which might
+contain alternate exim configuration the queue management might be using.
+
+.vitem &*-E*&&~<&'path'&>
+can be used to specify a path for the exim binary,
+overriding the built-in one.
+.endlist
+
  There is one more option, &%-h%&, which outputs a list of options.
  There is one more option, &%-h%&, which outputs a list of options.
+.new
+At least one selection option, or either the &*-c*& or &*-h*& option, must be given.
+.wen
  
  
  
  
  
  
@@ -39888,8 +40018,9 @@ The entire contents of a database are written to the standard output by the
  &'exim_dumpdb'& program,
  .new
  taking as arguments the spool and database names.
  &'exim_dumpdb'& program,
  .new
  taking as arguments the spool and database names.
-An option &'-z'& may be given to regest times in UTC;
+An option &'-z'& may be given to request times in UTC;
  otherwise times are in the local timezone.
  otherwise times are in the local timezone.
+An option &'-k'& may be given to dump only the record keys.
  .wen
  For example, to dump the retry database:
  .code
  .wen
  For example, to dump the retry database:
  .code
@@ -41022,8 +41153,18 @@ was received, in the conventional Unix form &-- the number of seconds since the
  start of the epoch. The second number is a count of the number of messages
  warning of delayed delivery that have been sent to the sender.
  
  start of the epoch. The second number is a count of the number of messages
  warning of delayed delivery that have been sent to the sender.
  
-There follow a number of lines starting with a hyphen. These can appear in any
-order, and are omitted when not relevant:
+.new
+There follow a number of lines starting with a hyphen.
+These contain variables, can appear in any
+order, and are omitted when not relevant.
+
+If there is a second hyphen after the first,
+the corresponding data is tainted.
+If there is a value in parentheses, the data is quoted for a lookup.
+
+The following word specifies a variable,
+and the remainder of the item depends on the variable.
+.wen
  
  .vlist
  .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
  
  .vlist
  .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
@@ -41179,9 +41320,6 @@ was received from the client, this records the Distinguished Name from that
  certificate.
  .endlist
  
  certificate.
  .endlist
  
-Any of the above may have an extra hyphen prepended, to indicate the the
-corresponding data is untrusted.
-
  Following the options there is a list of those addresses to which the message
  is not to be delivered. This set of addresses is initialized from the command
  line when the &%-t%& option is used and &%extract_addresses_remove_arguments%&
  Following the options there is a list of those addresses to which the message
  is not to be delivered. This set of addresses is initialized from the command
  line when the &%-t%& option is used and &%extract_addresses_remove_arguments%&
@@ -42033,6 +42171,9 @@ There is no need to periodically change this key; a timestamp is also
  encoded.
  The second argument should be given as the envelope sender address before this
  encoding operation.
  encoded.
  The second argument should be given as the envelope sender address before this
  encoding operation.
+.new
+If this value is empty the the expansion result will be empty.
+.wen
  The third argument should be the recipient domain of the message when
  it arrived at this system.
  .endlist
  The third argument should be the recipient domain of the message when
  it arrived at this system.
  .endlist
@@ -42206,16 +42347,16 @@ The &"dmarc_status"& condition takes a list of strings on its
  right-hand side.  These strings describe recommended action based
  on the DMARC check.  To understand what the policy recommendations
  mean, refer to the DMARC website above.  Valid strings are:
  right-hand side.  These strings describe recommended action based
  on the DMARC check.  To understand what the policy recommendations
  mean, refer to the DMARC website above.  Valid strings are:
-.display
-&'accept      '& The DMARC check passed and the library recommends accepting the email.
-&'reject      '& The DMARC check failed and the library recommends rejecting the email.
-&'quarantine  '& The DMARC check failed and the library recommends keeping it for further inspection.
-&'none        '& The DMARC check passed and the library recommends no specific action, neutral.
-&'norecord    '& No policy section in the DMARC record for this RFC5322.From field
-&'nofrom      '& Unable to determine the domain of the sender.
-&'temperror   '& Library error or dns error.
-&'off         '& The DMARC check was disabled for this email.
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &'accept'&       "The DMARC check passed and the library recommends accepting the email"
+.irow &'reject'&       "The DMARC check failed and the library recommends rejecting the email"
+.irow &'quarantine'&   "The DMARC check failed and the library recommends keeping it for further inspection"
+.irow &'none'&         "The DMARC check passed and the library recommends no specific action, neutral"
+.irow &'norecord'&     "No policy section in the DMARC record for this RFC5322.From field"
+.irow &'nofrom'&       "Unable to determine the domain of the sender"
+.irow &'temperror'&    "Library error or dns error"
+.irow &'off'&          "The DMARC check was disabled for this email"
+.endtable
  You can prefix each string with an exclamation mark to invert its
  meaning, for example "!accept" will match all results but
  "accept".  The string list is evaluated left-to-right in a
  You can prefix each string with an exclamation mark to invert its
  meaning, for example "!accept" will match all results but
  "accept".  The string list is evaluated left-to-right in a
@@ -42381,13 +42522,13 @@ within &%proxy_protocol_timeout%&, which defaults to 3s.
  The following expansion variables are usable
  (&"internal"& and &"external"& here refer to the interfaces
  of the proxy):
  The following expansion variables are usable
  (&"internal"& and &"external"& here refer to the interfaces
  of the proxy):
-.display
-&'proxy_external_address   '& IP of host being proxied or IP of remote interface of proxy
-&'proxy_external_port      '& Port of host being proxied or Port on remote interface of proxy
-&'proxy_local_address      '& IP of proxy server inbound or IP of local interface of proxy
-&'proxy_local_port         '& Port of proxy server inbound or Port on local interface of proxy
-&'proxy_session            '& boolean: SMTP connection via proxy
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow $proxy_external_address  "IP of host being proxied or IP of remote interface of proxy"
+.irow $proxy_external_port     "Port of host being proxied or Port on remote interface of proxy"
+.irow $proxy_local_address     "IP of proxy server inbound or IP of local interface of proxy"
+.irow $proxy_local_port                "Port of proxy server inbound or Port on local interface of proxy"
+.irow $proxy_session           "boolean: SMTP connection via proxy"
+.endtable
  If &$proxy_session$& is set but &$proxy_external_address$& is empty
  there was a protocol error.
  The variables &$sender_host_address$& and &$sender_host_port$&
  If &$proxy_session$& is set but &$proxy_external_address$& is empty
  there was a protocol error.
  The variables &$sender_host_address$& and &$sender_host_port$&
@@ -42434,15 +42575,15 @@ is an IP address and any subsequent elements are options.
  
  Options are a string <name>=<value>.
  The list of options is in the following table:
  
  Options are a string <name>=<value>.
  The list of options is in the following table:
-.display
-&'auth   '& authentication method
-&'name   '& authentication username
-&'pass   '& authentication password
-&'port   '& tcp port
-&'tmo    '& connection timeout
-&'pri    '& priority
-&'weight '& selection bias
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &'auth'& "authentication method"
+.irow &'name'& "authentication username"
+.irow &'pass'& "authentication password"
+.irow &'port'& "tcp port"
+.irow &'tmo'&  "connection timeout"
+.irow &'pri'&  "priority"
+.irow &'weight'& "selection bias"
+.endtable
  
  More details on each of these options follows:
  
  
  More details on each of these options follows:
  
@@ -42558,11 +42699,11 @@ This is usually for use in a Message Submission Agent context,
  but could be used for any message.
  
  If a value is appended it may be:
  but could be used for any message.
  
  If a value is appended it may be:
-.display
-&`1  `& mandatory downconversion
-&`0  `& no downconversion
-&`-1 `& if SMTPUTF8 not supported by destination host
-.endd
+.itable none 0 0 2 1pt right 1pt left
+.irow &`1`&    "mandatory downconversion"
+.irow &`0`&    "no downconversion"
+.irow &`-1`&   "if SMTPUTF8 not supported by destination host"
+.endtable
  If no value is given, 1 is used.
  
  If mua_wrapper is set, the utf8_downconvert control
  If no value is given, 1 is used.
  
  If mua_wrapper is set, the utf8_downconvert control
@@ -42664,23 +42805,23 @@ expansion must check this, as it will be called for every possible event type.
  
  .new
  The current list of events is:
  
  .new
  The current list of events is:
-.display
-&`dane:fail              after    transport  `& per connection
-&`msg:complete           after    main       `& per message
-&`msg:defer              after    transport  `& per message per delivery try
-&`msg:delivery           after    transport  `& per recipient
-&`msg:rcpt:host:defer    after    transport  `& per recipient per host
-&`msg:rcpt:defer         after    transport  `& per recipient
-&`msg:host:defer         after    transport  `& per host per delivery try; host errors
-&`msg:fail:delivery      after    transport  `& per recipient
-&`msg:fail:internal      after    main       `& per recipient
-&`tcp:connect            before   transport  `& per connection
-&`tcp:close              after    transport  `& per connection
-&`tls:cert               before   both       `& per certificate in verification chain
-&`tls:fail:connect       after    main       `& per connection
-&`smtp:connect           after    transport  `& per connection
-&`smtp:ehlo              after    transport  `& per connection
-.endd
+.itable all 0 0 4 1pt left 1pt center 1pt center 1pt left
+.irow dane:fail              after    transport  "per connection"
+.irow msg:complete           after    main       "per message"
+.irow msg:defer              after    transport  "per message per delivery try"
+.irow msg:delivery           after    transport  "per recipient"
+.irow msg:rcpt:host:defer    after    transport  "per recipient per host"
+.irow msg:rcpt:defer         after    transport  "per recipient"
+.irow msg:host:defer         after    transport  "per host per delivery try; host errors"
+.irow msg:fail:delivery      after    transport  "per recipient"
+.irow msg:fail:internal      after    main       "per recipient"
+.irow tcp:connect            before   transport  "per connection"
+.irow tcp:close              after    transport  "per connection"
+.irow tls:cert               before   both       "per certificate in verification chain"
+.irow tls:fail:connect       after    main       "per connection"
+.irow smtp:connect           after    transport  "per connection"
+.irow smtp:ehlo              after    transport  "per connection"
+.endtable
  .wen
  New event types may be added in future.
  
  .wen
  New event types may be added in future.
  
@@ -42697,24 +42838,24 @@ should define the event action.
  
  An additional variable, &$event_data$&, is filled with information varying
  with the event type:
  
  An additional variable, &$event_data$&, is filled with information varying
  with the event type:
-.display
-&`dane:fail            `& failure reason
-&`msg:defer            `& error string
-&`msg:delivery         `& smtp confirmation message
-&`msg:fail:internal    `& failure reason
-&`msg:fail:delivery    `& smtp error message
-&`msg:host:defer       `& error string
-&`msg:rcpt:host:defer  `& error string
-&`msg:rcpt:defer       `& error string
-&`tls:cert             `& verification chain depth
-&`tls:fail:connect     `& error string
-&`smtp:connect         `& smtp banner
-&`smtp:ehlo            `& smtp ehlo response
-.endd
+.itable all 0 0 2 1pt left 1pt left
+.irow dane:fail            "failure reason"
+.irow msg:defer            "error string"
+.irow msg:delivery         "smtp confirmation message"
+.irow msg:fail:internal    "failure reason"
+.irow msg:fail:delivery    "smtp error message"
+.irow msg:host:defer       "error string"
+.irow msg:rcpt:host:defer  "error string"
+.irow msg:rcpt:defer       "error string"
+.irow tls:cert             "verification chain depth"
+.irow tls:fail:connect     "error string"
+.irow smtp:connect         "smtp banner"
+.irow smtp:ehlo            "smtp ehlo response"
+.endtable
  
  The :defer events populate one extra variable: &$event_defer_errno$&.
  
  
  The :defer events populate one extra variable: &$event_defer_errno$&.
  
-For complex operations an ACL expansion can be used in &%event_action%&
+For complex operations an ACL expansion can be used in &%event_action%&,
  however due to the multiple contexts that Exim operates in during
  the course of its processing:
  .ilist
  however due to the multiple contexts that Exim operates in during
  the course of its processing:
  .ilist
@@ -42730,11 +42871,11 @@ a useful way of writing to the main log.
  The expansion of the event_action option should normally
  return an empty string.  Should it return anything else the
  following will be forced:
  The expansion of the event_action option should normally
  return an empty string.  Should it return anything else the
  following will be forced:
-.display
-&`tcp:connect      `&  do not connect
-&`tls:cert         `&  refuse verification
-&`smtp:connect     `&  close connection
-.endd
+.itable all 0 0 2 1pt left 1pt left
+.irow tcp:connect      "do not connect"
+.irow tls:cert         "refuse verification"
+.irow smtp:connect     "close connection"
+.endtable
  All other message types ignore the result string, and
  no other use is made of it.
  
  All other message types ignore the result string, and
  no other use is made of it.