Spec update.

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

index e778e51811440f9e58c7c65db78939eb7113a7ce..5856b3f979b6ef27d9ac4de2b98ed2d38f7be809 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.10 2006/07/24 11:55:15 fanf2 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.14 2007/01/15 15:58:40 ph10 Exp $
  .
  . /////////////////////////////////////////////////////////////////////////////
  . This is the primary source of the Exim Manual. It is an xfpt document that is
  .
  . /////////////////////////////////////////////////////////////////////////////
  . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -18,8 +18,23 @@
  . /////////////////////////////////////////////////////////////////////////////
  
  .set ACL "access control lists (ACLs)"
  . /////////////////////////////////////////////////////////////////////////////
  
  .set ACL "access control lists (ACLs)"
-.set previousversion "4.61"
-.set version "4.62"
+.set previousversion "4.63"
+.set version "4.66"
+
+
+. /////////////////////////////////////////////////////////////////////////////
+. These lines are processing instructions for the Simple DocBook Processor that
+. Philip Hazel is developing in odd moments as a less cumbersome way of making
+. PostScript and PDFs than using xmlto and fop. They will be ignored by all
+. other XML processors.
+. /////////////////////////////////////////////////////////////////////////////
+
+.literal xml
+<?sdop
+  toc_chapter_blanks="yes,yes"
+  table_warn_soft_overflow="no"
+?>
+.literal off
  
  
  . /////////////////////////////////////////////////////////////////////////////
  
  
  . /////////////////////////////////////////////////////////////////////////////
@@ -41,7 +56,7 @@
  . --- table with four columns.
  
  .macro option
  . --- table with four columns.
  
  .macro option
-.oindex "$1"
+.oindex "&%$1%&"
  .itable all 0 0 4 8* left 5* center 5* center 6* right
  .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
  .endtable
  .itable all 0 0 4 8* left 5* center 5* center 6* right
  .row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
  .endtable
@@ -51,7 +66,7 @@
  . --- is suitable for the many tables at the start of the main options chapter;
  . --- the small number of other 2-column tables override it.
  
  . --- is suitable for the many tables at the start of the main options chapter;
  . --- the small number of other 2-column tables override it.
  
-.macro table2 190pt 260pt
+.macro table2 196pt 254pt
  .itable none 0 0 2 $1 left $2 left
  .endmacro
  
  .itable none 0 0 2 $1 left $2 left
  .endmacro
  
@@ -106,17 +121,17 @@
  <bookinfo>
  <title>Specification of the Exim Mail Transfer Agent</title>
  <titleabbrev>The Exim MTA</titleabbrev>
  <bookinfo>
  <title>Specification of the Exim Mail Transfer Agent</title>
  <titleabbrev>The Exim MTA</titleabbrev>
-<date>27 April 2006</date>
+<date>08 January 2007</date>
  <author><firstname>Philip</firstname><surname>Hazel</surname></author>
  <authorinitials>PH</authorinitials>
  <affiliation><orgname>University of Cambridge Computing Service</orgname></affiliation>
  <address>New Museums Site, Pembroke Street, Cambridge CB2 3QH, England</address>
  <revhistory><revision>
  <author><firstname>Philip</firstname><surname>Hazel</surname></author>
  <authorinitials>PH</authorinitials>
  <affiliation><orgname>University of Cambridge Computing Service</orgname></affiliation>
  <address>New Museums Site, Pembroke Street, Cambridge CB2 3QH, England</address>
  <revhistory><revision>
-  <revnumber>4.62</revnumber>
-  <date>27 April 2006</date>
+  <revnumber>4.66</revnumber>
+  <date>08 January 2007</date>
    <authorinitials>PH</authorinitials>
  </revision></revhistory>
    <authorinitials>PH</authorinitials>
  </revision></revhistory>
-<copyright><year>2006</year><holder>University of Cambridge</holder></copyright>
+<copyright><year>2007</year><holder>University of Cambridge</holder></copyright>
  </bookinfo>
  .literal off
  
  </bookinfo>
  .literal off
  
@@ -414,7 +429,13 @@ You can subscribe to these lists, change your existing subscriptions, and view
  or search the archives via the mailing lists link on the Exim home page.
  .cindex "Debian" "mailing list for"
  If you are using a Debian distribution of Exim, you may wish to subscribe to
  or search the archives via the mailing lists link on the Exim home page.
  .cindex "Debian" "mailing list for"
  If you are using a Debian distribution of Exim, you may wish to subscribe to
-the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'&.
+the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'&
+via this web page:
+.display
+&url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users)
+.endd
+Please ask Debian-specific questions on this list and not on the general Exim
+lists.
  
  .section "Exim training"
  .cindex "training courses"
  
  .section "Exim training"
  .cindex "training courses"
@@ -503,9 +524,9 @@ often the most convenient way of finding your way around.
  .section "Wish list"
  .cindex "wish list"
  A wish list is maintained, containing ideas for new features that have been
  .section "Wish list"
  .cindex "wish list"
  A wish list is maintained, containing ideas for new features that have been
-submitted. From time to time the file is exported to the ftp site into the file
-&_exim4/WishList_&. Items are removed from the list if they get implemented.
-
+submitted. This used to be a single file that from time to time was exported to
+the ftp site into the file &_exim4/WishList_&. However, it has now been
+imported into Exim's Bugzilla data.
  
  
  .section "Contributed material"
  
  
  .section "Contributed material"
@@ -1035,10 +1056,10 @@ By default all these message files are held in a single directory called
  not perform very well if the number of files in a directory gets large; to
  improve performance in such cases, the &%split_spool_directory%& option can be
  used. This causes Exim to split up the input files into 62 sub-directories
  not perform very well if the number of files in a directory gets large; to
  improve performance in such cases, the &%split_spool_directory%& option can be
  used. This causes Exim to split up the input files into 62 sub-directories
-whose names are single letters or digits. &new("When this is done, the queue is
+whose names are single letters or digits. When this is done, the queue is
  processed one sub-directory at a time instead of all at once, which can improve
  overall performance even when there are not enough files in each directory to
  processed one sub-directory at a time instead of all at once, which can improve
  overall performance even when there are not enough files in each directory to
-affect file system performance.")
+affect file system performance.
  
  The envelope information consists of the address of the message's sender and
  the addresses of the recipients. This information is entirely separate from
  
  The envelope information consists of the address of the message's sender and
  the addresses of the recipients. This information is entirely separate from
@@ -1275,9 +1296,13 @@ facility for this purpose.
  .section "Duplicate addresses"
  .cindex "case of local parts"
  .cindex "address duplicate" "discarding"
  .section "Duplicate addresses"
  .cindex "case of local parts"
  .cindex "address duplicate" "discarding"
+.cindex "duplicate addresses"
  Once routing is complete, Exim scans the addresses that are assigned to local
  and remote transports, and discards any duplicates that it finds. During this
  Once routing is complete, Exim scans the addresses that are assigned to local
  and remote transports, and discards any duplicates that it finds. During this
-check, local parts are treated as case-sensitive.
+check, local parts are treated as case-sensitive. This happens only when
+actually delivering a message; when testing routers with &%-bt%&, all the
+routed addresses are shown.
+
  
  
  .section "Router preconditions" "SECTrouprecon"
  
  
  .section "Router preconditions" "SECTrouprecon"
@@ -1745,7 +1770,7 @@ chapter &<<CHAPexiscan>>&.
  
  
  .cindex "&_Local/eximon.conf_&"
  
  
  .cindex "&_Local/eximon.conf_&"
-.cindex "_exim_monitor/EDITME_"
+.cindex "&_exim_monitor/EDITME_&"
  If you are going to build the Exim monitor, a similar configuration process is
  required. The file &_exim_monitor/EDITME_& must be edited appropriately for
  your installation and saved under the name &_Local/eximon.conf_&. If you are
  If you are going to build the Exim monitor, a similar configuration process is
  required. The file &_exim_monitor/EDITME_& must be edited appropriately for
  your installation and saved under the name &_Local/eximon.conf_&. If you are
@@ -1922,7 +1947,7 @@ FULLECHO='' make -e
  .endd
  The value of FULLECHO defaults to &"@"&, the flag character that suppresses
  command reflection in &'make'&. When you ask for the full output, it is
  .endd
  The value of FULLECHO defaults to &"@"&, the flag character that suppresses
  command reflection in &'make'&. When you ask for the full output, it is
-given in addition to the the short output.
+given in addition to the short output.
  
  
  
  
  
  
@@ -2513,7 +2538,13 @@ getting root. There is further discussion of this issue at the start of chapter
  
  
  .section "Command line options"
  
  
  .section "Command line options"
-The command options are described in alphabetical order below.
+Exim's command line options are described in alphabetical order below. If none
+of the options that specifies a specific action (such as starting the daemon or
+a queue runner, or testing an address, or receiving a message in a specific
+format, or listing the queue) are present, and there is at least one argument
+on the command line, &%-bm%& (accept a local message on the standard input,
+with the arguments specifying the recipients) is assumed. Otherwise, Exim
+outputs a brief message about itself and exits.
  
  . ////////////////////////////////////////////////////////////////////////////
  . Insert a stylized XML comment here, to identify the start of the command line
  
  . ////////////////////////////////////////////////////////////////////////////
  . Insert a stylized XML comment here, to identify the start of the command line
@@ -2581,10 +2612,11 @@ used to specify a path on the command line if a pid file is required.
  
  The SIGHUP signal
  .cindex "SIGHUP"
  
  The SIGHUP signal
  .cindex "SIGHUP"
-can be used to cause the daemon to re-exec itself. This should be done whenever
-Exim's configuration file, or any file that is incorporated into it by means of
-the &%.include%& facility, is changed, and also whenever a new version of Exim
-is installed. It is not necessary to do this when other files that are
+.cindex "daemon" "restarting"
+can be used to cause the daemon to re-execute itself. This should be done
+whenever Exim's configuration file, or any file that is incorporated into it by
+means of the &%.include%& facility, is changed, and also whenever a new version
+of Exim is installed. It is not necessary to do this when other files that are
  referenced from the configuration (for example, alias files) are changed,
  because these are reread each time they are used.
  
  referenced from the configuration (for example, alias files) are changed,
  because these are reread each time they are used.
  
@@ -2613,14 +2645,34 @@ continuations. As in Exim's run time configuration, white space at the start of
  continuation lines is ignored. Each argument or data line is passed through the
  string expansion mechanism, and the result is output. Variable values from the
  configuration file (for example, &$qualify_domain$&) are available, but no
  continuation lines is ignored. Each argument or data line is passed through the
  string expansion mechanism, and the result is output. Variable values from the
  configuration file (for example, &$qualify_domain$&) are available, but no
-message-specific values (such as &$domain$&) are set, because no message is
-being processed.
+message-specific values (such as &$sender_domain$&) are set, because no message
+is being processed &new("(but see &%-bem%& and &%-Mset%&)").
  
  &*Note*&: If you use this mechanism to test lookups, and you change the data
  files or databases you are using, you must exit and restart Exim before trying
  the same lookup again. Otherwise, because each Exim process caches the results
  of lookups, you will just get the same result as before.
  
  
  &*Note*&: If you use this mechanism to test lookups, and you change the data
  files or databases you are using, you must exit and restart Exim before trying
  the same lookup again. Otherwise, because each Exim process caches the results
  of lookups, you will just get the same result as before.
  
+.new
+.vitem &%-bem%&&~<&'filename'&>
+.oindex "&%-bem%&"
+.cindex "testing" "string expansion"
+.cindex "expansion" "testing"
+This option operates like &%-be%& except that it must be followed by the name
+of a file. For example:
+.code
+exim -bem /tmp/testmessage
+.endd
+The file is read as a message (as if receiving a locally-submitted non-SMTP
+message) before any of the test expansions are done. Thus, message-specific
+variables such as &$message_size$& and &$header_from:$& are available. However,
+no &'Received:'& header is added to the message. If the &%-t%& option is set,
+recipients are read from the headers in the normal way, and are shown in the
+&$recipients$& variable. Note that recipients cannot be given on the command
+line, because further arguments are taken as strings to expand (just like
+&%-be%&).
+.wen
+
  .vitem &%-bF%&&~<&'filename'&>
  .oindex "&%-bF%&"
  .cindex "system filter" "testing"
  .vitem &%-bF%&&~<&'filename'&>
  .oindex "&%-bF%&"
  .cindex "system filter" "testing"
@@ -2730,9 +2782,10 @@ test your relay controls using &%-bh%&.
  
  &*Warning 1*&:
  .cindex "RFC 1413"
  
  &*Warning 1*&:
  .cindex "RFC 1413"
-You cannot test features of the configuration that rely on
-ident (RFC 1413) callouts. These cannot be done when testing using
-&%-bh%& because there is no incoming SMTP connection.
+You can test features of the configuration that rely on ident (RFC 1413)
+information by using the &%-oMt%& option. However, Exim cannot actually perform
+an ident callout when testing using &%-bh%& because there is no incoming SMTP
+connection.
  
  &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&)
  are also skipped when testing using &%-bh%&. If you want these callouts to
  
  &*Warning 2*&: Address verification callouts (see section &<<SECTcallver>>&)
  are also skipped when testing using &%-bh%&. If you want these callouts to
@@ -2741,12 +2794,20 @@ occur, use &%-bhc%& instead.
  Messages supplied during the testing session are discarded, and nothing is
  written to any of the real log files. There may be pauses when DNS (and other)
  lookups are taking place, and of course these may time out. The &%-oMi%& option
  Messages supplied during the testing session are discarded, and nothing is
  written to any of the real log files. There may be pauses when DNS (and other)
  lookups are taking place, and of course these may time out. The &%-oMi%& option
-can be used to specify a specific IP interface and port if this is important.
+can be used to specify a specific IP interface and port if this is important,
+and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP
+session were authenticated.
  
  The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose
  output just states whether a given recipient address from a given host is
  acceptable or not. See section &<<SECTcheckaccess>>&.
  
  
  The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose
  output just states whether a given recipient address from a given host is
  acceptable or not. See section &<<SECTcheckaccess>>&.
  
+.new
+Features such as authentication and encryption, where the client input is not
+plain text, are most easily tested using specialized SMTP test programs such as
+&url(http://jetmore.org/john/code/#swaks,swaks).
+.wen
+
  .vitem &%-bhc%&&~<&'IP&~address'&>
  .oindex "&%-bhc%&"
  This option operates in the same way as &%-bh%&, except that address
  .vitem &%-bhc%&&~<&'IP&~address'&>
  .oindex "&%-bhc%&"
  This option operates in the same way as &%-bh%&, except that address
@@ -3100,6 +3161,12 @@ return code is 2 if any address failed outright; it is 1 if no address
  failed outright but at least one could not be resolved for some reason. Return
  code 0 is given only when all addresses succeed.
  
  failed outright but at least one could not be resolved for some reason. Return
  code 0 is given only when all addresses succeed.
  
+.cindex "duplicate addresses"
+&*Note*&: When actually delivering a message, Exim removes duplicate recipient
+addresses after routing is complete, so that only one delivery takes place.
+This does not happen when testing with &%-bt%&; the full results of routing are
+always shown.
+
  &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the
  routers in the configuration makes any tests on the sender address of a
  message,
  &*Warning*&: &%-bt%& can only do relatively simple testing. If any of the
  routers in the configuration makes any tests on the sender address of a
  message,
@@ -3133,10 +3200,11 @@ dynamic testing facilities.
  .cindex "verifying address" "using &%-bv%&"
  .cindex "address" "verification"
  This option runs Exim in address verification mode, in which each argument is
  .cindex "verifying address" "using &%-bv%&"
  .cindex "address" "verification"
  This option runs Exim in address verification mode, in which each argument is
-taken as an address to be verified. During normal operation, verification
-happens mostly as a consequence processing a &%verify%& condition in an ACL
-(see chapter &<<CHAPACL>>&). If you want to test an entire ACL, see the &%-bh%&
-option.
+taken as an address to be verified by the routers. (This does not involve any
+verification callouts). During normal operation, verification happens mostly as
+a consequence processing a &%verify%& condition in an ACL (see chapter
+&<<CHAPACL>>&). If you want to test an entire ACL, possibly including callouts,
+see the &%-bh%& and &%-bhc%& options.
  
  If verification fails, and the caller is not an admin user, no details of the
  failure are output, because these might contain sensitive information such as
  
  If verification fails, and the caller is not an admin user, no details of the
  failure are output, because these might contain sensitive information such as
@@ -3155,12 +3223,19 @@ router that has &%fail_verify%& set, verification fails. The address is
  verified as a recipient if &%-bv%& is used; to test verification for a sender
  address, &%-bvs%& should be used.
  
  verified as a recipient if &%-bv%& is used; to test verification for a sender
  address, &%-bvs%& should be used.
  
+.new
  If the &%-v%& option is not set, the output consists of a single line for each
  address, stating whether it was verified or not, and giving a reason in the
  If the &%-v%& option is not set, the output consists of a single line for each
  address, stating whether it was verified or not, and giving a reason in the
-latter case. Otherwise, more details are given of how the address has been
-handled, and in the case of address redirection, all the generated addresses
-are also considered. Without &%-v%&, generating more than one address by
-redirection causes verification to end successfully.
+latter case. Without &%-v%&, generating more than one address by redirection
+causes verification to end successfully, without considering the generated
+addresses. However, if just one address is generated, processing continues,
+and the generated address must verify successfully for the overall verification
+to succeed.
+
+When &%-v%& is set, more details are given of how the address has been handled,
+and in the case of address redirection, all the generated addresses are also
+considered. Verification may succeed for some and fail for others.
+.wen
  
  The
  .cindex "return code" "for &%-bv%&"
  
  The
  .cindex "return code" "for &%-bv%&"
@@ -3262,14 +3337,18 @@ exim '-D ABC = something' ...
  This option causes debugging information to be written to the standard
  error stream. It is restricted to admin users because debugging output may show
  database queries that contain password information. Also, the details of users'
  This option causes debugging information to be written to the standard
  error stream. It is restricted to admin users because debugging output may show
  database queries that contain password information. Also, the details of users'
-filter files should be protected. When &%-d%& is used, &%-v%& is assumed. If
-&%-d%& is given on its own, a lot of standard debugging data is output. This
-can be reduced, or increased to include some more rarely needed information, by
-directly following &%-d%& with a string made up of names preceded by plus or
-minus characters. These add or remove sets 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:
+filter files should be protected. &new("If a non-admin user uses &%-d%&, Exim
+writes an error message to the standard error stream and exits with a non-zero
+return code.")
+
+When &%-d%& is used, &%-v%& is assumed. If &%-d%& is given on its own, a lot of
+standard debugging data is output. This can be reduced, or increased to include
+some more rarely needed information, by directly following &%-d%& with a string
+made up of names preceded by plus or minus characters. These add or remove sets
+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:
  .display
  &`acl            `& ACL interpretation
  &`auth           `& authenticators
  .display
  &`acl            `& ACL interpretation
  &`auth           `& authenticators
@@ -3598,6 +3677,20 @@ the messages are active, their status is not altered. This option can be used
  only by an admin user or by the user who originally caused the message to be
  placed on the queue.
  
  only by an admin user or by the user who originally caused the message to be
  placed on the queue.
  
+.new
+.vitem &%-Mset%&&~<&'message&~id'&>
+.oindex "&%-Mset%&
+.cindex "testing" "string expansion"
+.cindex "expansion" "testing"
+This option is useful only in conjunction with &%-be%& (that is, when testing
+string expansions). Exim loads the given message from its spool before doing
+the test expansions, thus setting message-specific variables such as
+&$message_size$& and the header variables. The &$recipients$& variable is made
+available. This feature is provided to make it easier to test expansions that
+make use of these variables. However, this option can be used only by an admin
+user. See also &%-bem%&.
+.wen
+
  .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
  .oindex "&%-Mt%&"
  .cindex "thawing messages"
  .vitem &%-Mt%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
  .oindex "&%-Mt%&"
  .cindex "thawing messages"
@@ -3838,7 +3931,9 @@ followed by a colon and the port number:
  exim -bs -oMa [10.9.8.7]:1234
  .endd
  The IP address is placed in the &$sender_host_address$& variable, and the
  exim -bs -oMa [10.9.8.7]:1234
  .endd
  The IP address is placed in the &$sender_host_address$& variable, and the
-port, if present, in &$sender_host_port$&.
+port, if present, in &$sender_host_port$&. If both &%-oMa%& and &%-bh%&
+are present on the command line, the sender host IP address is taken from
+whichever one is last.
  
  .vitem &%-oMaa%&&~<&'name'&>
  .oindex "&%-oMaa%&"
  
  .vitem &%-oMaa%&&~<&'name'&>
  .oindex "&%-oMaa%&"
@@ -3846,15 +3941,17 @@ port, if present, in &$sender_host_port$&.
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%&
  option sets the value of &$sender_host_authenticated$& (the authenticator
  name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication.
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%&
  option sets the value of &$sender_host_authenticated$& (the authenticator
  name). See chapter &<<CHAPSMTPAUTH>>& for a discussion of SMTP authentication.
+This option can be used with &%-bh%& and &%-bs%& to set up an
+authenticated SMTP session without actually using the SMTP AUTH command.
  
  .vitem &%-oMai%&&~<&'string'&>
  .oindex "&%-oMai%&"
  .cindex "authentication id" "specifying for local message"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%&
  option sets the value of &$authenticated_id$& (the id that was authenticated).
  
  .vitem &%-oMai%&&~<&'string'&>
  .oindex "&%-oMai%&"
  .cindex "authentication id" "specifying for local message"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%&
  option sets the value of &$authenticated_id$& (the id that was authenticated).
-This overrides the default value (the caller's login id) for messages from
-local sources. See chapter &<<CHAPSMTPAUTH>>& for a discussion of authenticated
-ids.
+This overrides the default value (the caller's login id, except with &%-bh%&,
+where there is no default) for messages from local sources. See chapter
+&<<CHAPSMTPAUTH>>& for a discussion of authenticated ids.
  
  .vitem &%-oMas%&&~<&'address'&>
  .oindex "&%-oMas%&"
  
  .vitem &%-oMas%&&~<&'address'&>
  .oindex "&%-oMas%&"
@@ -3862,16 +3959,20 @@ ids.
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%&
  option sets the authenticated sender value in &$authenticated_sender$&. It
  overrides the sender address that is created from the caller's login id for
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%&
  option sets the authenticated sender value in &$authenticated_sender$&. It
  overrides the sender address that is created from the caller's login id for
-messages from local sources. See chapter &<<CHAPSMTPAUTH>>& for a discussion of
-authenticated senders.
+messages from local sources, except when &%-bh%& is used, when there is no
+default. For both &%-bh%& and &%-bs%&, an authenticated sender that is
+specified on a MAIL command overrides this value. See chapter
+&<<CHAPSMTPAUTH>>& for a discussion of authenticated senders.
  
  .vitem &%-oMi%&&~<&'interface&~address'&>
  .oindex "&%-oMi%&"
  .cindex "interface address" "specifying for local message"
  
  .vitem &%-oMi%&&~<&'interface&~address'&>
  .oindex "&%-oMi%&"
  .cindex "interface address" "specifying for local message"
+.new
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%&
  option sets the IP interface address value. A port number may be included,
  using the same syntax as for &%-oMa%&. The interface address is placed in
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMi%&
  option sets the IP interface address value. A port number may be included,
  using the same syntax as for &%-oMa%&. The interface address is placed in
-&$interface_address$& and the port number, if present, in &$interface_port$&.
+&$received_ip_address$& and the port number, if present, in &$received_port$&.
+.wen
  
  .vitem &%-oMr%&&~<&'protocol&~name'&>
  .oindex "&%-oMr%&"
  
  .vitem &%-oMr%&&~<&'protocol&~name'&>
  .oindex "&%-oMr%&"
@@ -3879,11 +3980,12 @@ using the same syntax as for &%-oMa%&. The interface address is placed in
  .cindex "&$received_protocol$&"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%&
  option sets the received protocol value that is stored in
  .cindex "&$received_protocol$&"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%&
  option sets the received protocol value that is stored in
-&$received_protocol$&. However, this applies only when &%-bs%& is not used. For
-interactive SMTP input (&%-bs%&), the protocol is always &"local-"& followed by
-one of the standard SMTP protocol names (see the description of
-&$received_protocol$& in section &<<SECTexpvar>>&). For &%-bS%& (batch SMTP)
-however, the protocol can be set by &%-oMr%&.
+&$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%&
+or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard
+SMTP protocol names (see the description of &$received_protocol$& in section
+&<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by
+one of those same names. For &%-bS%& (batched SMTP) however, the protocol can
+be set by &%-oMr%&.
  
  .vitem &%-oMs%&&~<&'host&~name'&>
  .oindex "&%-oMs%&"
  
  .vitem &%-oMs%&&~<&'host&~name'&>
  .oindex "&%-oMs%&"
@@ -3898,7 +4000,8 @@ uses the name it is given.
  .cindex "sender ident string" "specifying for local message"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%&
  option sets the sender ident value in &$sender_ident$&. The default setting for
  .cindex "sender ident string" "specifying for local message"
  See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%&
  option sets the sender ident value in &$sender_ident$&. The default setting for
-local callers is the login id of the calling process.
+local callers is the login id of the calling process, except when &%-bh%& is
+used, when there is no default.
  
  .vitem &%-om%&
  .oindex "&%-om%&"
  
  .vitem &%-om%&
  .oindex "&%-om%&"
@@ -4142,14 +4245,26 @@ address containing the given string, which is checked in a case-independent
  way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a
  regular expression; otherwise it is a literal string.
  
  way. If the <&'rsflags'&> start with &'r'&, <&'string'&> is interpreted as a
  regular expression; otherwise it is a literal string.
  
-Once a message is selected, all its addresses are processed. For the first
-selected message, Exim overrides any retry information and forces a delivery
-attempt for each undelivered address. This means that if delivery of any
-address in the first message is successful, any existing retry information is
-deleted, and so delivery attempts for that address in subsequently selected
-messages (which are processed without forcing) will run. However, if delivery
-of any address does not succeed, the retry information is updated, and in
-subsequently selected messages, the failing address will be skipped.
+.new
+If you want to do periodic queue runs for messages with specific recipients,
+you can combine &%-R%& with &%-q%& and a time value. For example:
+.code
+exim -q25m -R @special.domain.example
+.endd
+This example does a queue run for messages with recipients in the given domain
+every 25 minutes. Any additional flags that are specified with &%-q%& are
+applied to each queue run.
+.wen
+
+Once a message is selected for delivery by this mechanism, all its addresses
+are processed. For the first selected message, Exim overrides any retry
+information and forces a delivery attempt for each undelivered address. This
+means that if delivery of any address in the first message is successful, any
+existing retry information is deleted, and so delivery attempts for that
+address in subsequently selected messages (which are processed without forcing)
+will run. However, if delivery of any address does not succeed, the retry
+information is updated, and in subsequently selected messages, the failing
+address will be skipped.
  
  .cindex "frozen messages" "forcing delivery"
  If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to
  
  .cindex "frozen messages" "forcing delivery"
  If the <&'rsflags'&> contain &'f'& or &'ff'&, the delivery forcing applies to
@@ -5041,28 +5156,34 @@ Three more commented-out option settings follow:
  # tls_privatekey = /etc/ssl/exim.pem
  .endd
  These are example settings that can be used when Exim is compiled with
  # tls_privatekey = /etc/ssl/exim.pem
  .endd
  These are example settings that can be used when Exim is compiled with
-support for TLS (aka SSL) as described in &<<SECTinctlsssl>>&. The
-first one specifies the list of clients that are allowed to use TLS
-when connecting to this server; in this case the wildcard means all
-clients. The other options specify where Exim should find its TLS
-certificate and private key, which together prove the server's
-identity to any clients that connect. More details are given in
-&<<CHAPTLS>>&.
+support for TLS (aka SSL) as described in section &<<SECTinctlsssl>>&. The
+first one specifies the list of clients that are allowed to use TLS when
+connecting to this server; in this case the wildcard means all clients. The
+other options specify where Exim should find its TLS certificate and private
+key, which together prove the server's identity to any clients that connect.
+More details are given in chapter &<<CHAPTLS>>&.
  
  Another two commented-out option settings follow:
  .code
  # daemon_smtp_ports = 25 : 465 : 587
  # tls_on_connect_ports = 465
  .endd
  
  Another two commented-out option settings follow:
  .code
  # daemon_smtp_ports = 25 : 465 : 587
  # tls_on_connect_ports = 465
  .endd
-These options provide better support for roaming users who wish to use
-this server for message submission. They are not much use unless you
-have turned on TLS (as described in the previous paragraph) and
-authentication (about which more in &<<SECTdefconfauth>>&). The usual
-SMTP port 25 is often blocked on end-user networks, so RFC 4409
-specifies that message submission should use port 587 instead. However
-some software (notably Microsoft Outlook) cannot be configured to use
-port 587 correctly, so these settings also enable the non-standard
-&"smtps"& port 465.
+.cindex "port" "465 and 587"
+.cindex "port" "for message submission"
+.cindex "message" "submission, ports for"
+.cindex "ssmtp protocol"
+.cindex "smtps protocol"
+.cindex "SMTP" "ssmtp protocol"
+.cindex "SMTP" "smtps protocol"
+These options provide better support for roaming users who wish to use this
+server for message submission. They are not much use unless you have turned on
+TLS (as described in the previous paragraph) and authentication (about which
+more in section &<<SECTdefconfauth>>&). The usual SMTP port 25 is often blocked
+on end-user networks, so RFC 4409 specifies that message submission should use
+port 587 instead. However some software (notably Microsoft Outlook) cannot be
+configured to use port 587 correctly, so these settings also enable the
+non-standard &"smtps"& (aka &"ssmtp"&) port 465 (see section
+&<<SECTsupobssmt>>&).
  
  Two more commented-out options settings follow:
  .code
  
  Two more commented-out options settings follow:
  .code
@@ -5119,12 +5240,10 @@ unreachable.
  
  The next two lines are concerned with &'ident'& callbacks, as defined by RFC
  1413 (hence their names):
  
  The next two lines are concerned with &'ident'& callbacks, as defined by RFC
  1413 (hence their names):
-.new
  .code
  rfc1413_hosts = *
  rfc1413_query_timeout = 5s
  .endd
  .code
  rfc1413_hosts = *
  rfc1413_query_timeout = 5s
  .endd
-.wen
  These settings cause Exim to make ident callbacks for all incoming SMTP calls.
  You can limit the hosts to which these calls are made, or change the timeout
  that is used. If you set the timeout to zero, all ident calls are disabled.
  These settings cause Exim to make ident callbacks for all incoming SMTP calls.
  You can limit the hosts to which these calls are made, or change the timeout
  that is used. If you set the timeout to zero, all ident calls are disabled.
@@ -5309,47 +5428,42 @@ authenticators, though it does include some nearly complete commented-out
  examples described in &<<SECTdefconfauth>>&. This means that no client can in
  fact authenticate until you complete the authenticator definitions.
  .code
  examples described in &<<SECTdefconfauth>>&. This means that no client can in
  fact authenticate until you complete the authenticator definitions.
  .code
+require message = relay not permitted
+        domains = +local_domains : +relay_domains
+.endd
+This statement rejects the address if its domain is neither a local domain nor
+one of the domains for which this host is a relay.
+.code
+require verify = recipient
+.endd
+This statement requires the recipient address to be verified; if verification
+fails, the address is rejected.
+.code
  # deny    message     = rejected because $sender_host_address \
  #                       is in a black list at $dnslist_domain\n\
  #                       $dnslist_text
  #         dnslists    = black.list.example
  #
  # deny    message     = rejected because $sender_host_address \
  #                       is in a black list at $dnslist_domain\n\
  #                       $dnslist_text
  #         dnslists    = black.list.example
  #
-# warn    message     = X-Warning: $sender_host_address is \
-#                       in a black list at $dnslist_domain
+# warn    dnslists    = black.list.example
+#         add_header  = X-Warning: $sender_host_address is in \
+#                       a black list at $dnslist_domain
  #         log_message = found in $dnslist_domain
  #         log_message = found in $dnslist_domain
-#         dnslists    = black.list.example
  .endd
  These commented-out lines are examples of how you could configure Exim to check
  sending hosts against a DNS black list. The first statement rejects messages
  .endd
  These commented-out lines are examples of how you could configure Exim to check
  sending hosts against a DNS black list. The first statement rejects messages
-from blacklisted hosts, whereas the second merely inserts a warning header
+from blacklisted hosts, whereas the second just inserts a warning header
  line.
  .code
  line.
  .code
-accept  domains       = +local_domains
-        endpass
-        verify        = recipient
-.endd
-This statement accepts the incoming recipient address if its domain is one of
-the local domains, but only if the address can be verified. Verification of
-local addresses normally checks both the local part and the domain. The
-&%endpass%& line needs some explanation: if the condition above &%endpass%&
-fails, that is, if the address is not in a local domain, control is passed to
-the next ACL statement. However, if the condition below &%endpass%& fails, that
-is, if a recipient in a local domain cannot be verified, access is denied and
-the recipient is rejected.
-.code
-accept  domains       = +relay_to_domains
-        endpass
-        verify        = recipient
+# require verify = csa
  .endd
  .endd
-This statement accepts the incoming recipient address if its domain is one of
-the domains for which this host is a relay, but again, only if the address can
-be verified.
+This commented-out line is an example of how you could turn on client SMTP
+authorization (CSA) checking. Such checks do DNS lookups for special SRV
+records.
  .code
  .code
-deny    message       = relay not permitted
+accept
  .endd
  .endd
-The final statement denies access, giving a specific error message. Reaching
-the end of the ACL also causes access to be denied, but with the generic
-message &"administrative prohibition"&.
+The final statement in the first ACL unconditionally accepts any recipient
+address that has successfully passed all the previous tests.
  .code
  acl_check_data:
  .endd
  .code
  acl_check_data:
  .endd
@@ -6001,16 +6115,19 @@ lookup types support only literal keys.
  &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that
  the implicit key is the host's IP address rather than its name (see section
  &<<SECThoslispatsikey>>&).
  &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that
  the implicit key is the host's IP address rather than its name (see section
  &<<SECThoslispatsikey>>&).
-
  .next
  .cindex "linear search"
  .cindex "lookup" "lsearch"
  .cindex "lsearch lookup type"
  .next
  .cindex "linear search"
  .cindex "lookup" "lsearch"
  .cindex "lsearch lookup type"
+.cindex "case sensitivity" "in lsearch lookup"
  &(lsearch)&: The given file is a text file that is searched linearly for a
  line beginning with the search key, terminated by a colon or white space or the
  &(lsearch)&: The given file is a text file that is searched linearly for a
  line beginning with the search key, terminated by a colon or white space or the
-end of the line. The first occurrence that is found in the file is used. White
-space between the key and the colon is permitted. The remainder of the line,
-with leading and trailing white space removed, is the data. This can be
+end of the line. The search is case-insensitive; that is, upper and lower case
+letters are treated as the same. The first occurrence of the key that is found
+in the file is used.
+
+White space between the key and the colon is permitted. The remainder of the
+line, with leading and trailing white space removed, is the data. This can be
  continued onto subsequent lines by starting them with any amount of white
  space, but only a single space character is included in the data at such a
  junction. If the data begins with a colon, the key must be terminated by a
  continued onto subsequent lines by starting them with any amount of white
  space, but only a single space character is included in the data at such a
  junction. If the data begins with a colon, the key must be terminated by a
@@ -6054,8 +6171,10 @@ the file may be wildcarded. The difference between these two lookup types is
  that for &(wildlsearch)&, each key in the file is string-expanded before being
  used, whereas for &(nwildlsearch)&, no expansion takes place.
  
  that for &(wildlsearch)&, each key in the file is string-expanded before being
  used, whereas for &(nwildlsearch)&, no expansion takes place.
  
-Like &(lsearch)&, the testing is done case-insensitively. The following forms
-of wildcard are recognized:
+.cindex "case sensitivity" "in (n)wildlsearch lookup"
+Like &(lsearch)&, the testing is done case-insensitively. However, keys in the
+file that are regular expressions can be made case-sensitive by the use of
+&`(-i)`& within the pattern. The following forms of wildcard are recognized:
  
  . ==== As this is a nested list, any displays it contains must be indented
  . ==== as otherwise they are too far to the left.
  
  . ==== As this is a nested list, any displays it contains must be indented
  . ==== as otherwise they are too far to the left.
@@ -6078,6 +6197,13 @@ string-expanded, the equivalent entry is:
  .code
      ^\d+\.a\.b        data for <digits>.a.b
  .endd
  .code
      ^\d+\.a\.b        data for <digits>.a.b
  .endd
+The case-insensitive flag is set at the start of compiling the regular
+expression, but it can be turned off by using &`(-i)`& at an appropriate point.
+For example, to make the entire pattern case-sensitive:
+.code
+    ^(?-i)\d+\.a\.b        data for <digits>.a.b
+.endd
+
  If the regular expression contains white space or colon characters, you must
  either quote it (see &(lsearch)& above), or represent these characters in other
  ways. For example, &`\s`& can be used for white space and &`\x3A`& for a
  If the regular expression contains white space or colon characters, you must
  either quote it (see &(lsearch)& above), or represent these characters in other
  ways. For example, &`\s`& can be used for white space and &`\x3A`& for a
@@ -6124,9 +6250,9 @@ many of them are given in later sections.
  are given in the supplied query. The resulting data is the contents of the
  records. See section &<<SECTdnsdb>>&.
  .next
  are given in the supplied query. The resulting data is the contents of the
  records. See section &<<SECTdnsdb>>&.
  .next
-.cindex "Interbase lookup type"
-.cindex "lookup" "Interbase"
-&(ibase)&: This does a lookup in an Interbase database.
+.cindex "InterBase lookup type"
+.cindex "lookup" "InterBase"
+&(ibase)&: This does a lookup in an InterBase database.
  .next
  .cindex "LDAP" "lookup type"
  .cindex "lookup" "LDAP"
  .next
  .cindex "LDAP" "lookup type"
  .cindex "lookup" "LDAP"
@@ -6221,6 +6347,12 @@ or may give up altogether.
  In this context, a &"default value"& is a value specified by the administrator
  that is to be used if a lookup fails.
  
  In this context, a &"default value"& is a value specified by the administrator
  that is to be used if a lookup fails.
  
+.new
+&*Note:*& This section applies only to single-key lookups. For query-style
+lookups, the facilities of the query language must be used. An attempt to
+specify a default for a query-style lookup provokes an error.
+.wen
+
  If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&)
  and the initial lookup fails, the key &"*"& is looked up in the file to
  provide a default value. See also the section on partial matching below.
  If &"*"& is added to a single-key lookup type (for example, &%lsearch*%&)
  and the initial lookup fails, the key &"*"& is looked up in the file to
  provide a default value. See also the section on partial matching below.
@@ -6426,9 +6558,9 @@ an expansion string could contain:
  ${lookup dnsdb{mx=a.b.example}{$value}fail}
  .endd
  If the lookup succeeds, the result is placed in &$value$&, which in this case
  ${lookup dnsdb{mx=a.b.example}{$value}fail}
  .endd
  If the lookup succeeds, the result is placed in &$value$&, which in this case
-is used on its own as the result. If the lookup succeeds, the &`fail`& keyword
-causes a &'forced expansion failure'& &-- see section &<<SECTforexpfai>>& for
-an explanation of what this means.
+is used on its own as the result. If the lookup does not succeed, the
+&`fail`& keyword causes a &'forced expansion failure'& &-- see section
+&<<SECTforexpfai>>& for an explanation of what this means.
  
  The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and,
  when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
  
  The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and,
  when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
@@ -6748,11 +6880,14 @@ them. The following names are recognized:
  &`NETTIME    `&  set a timeout for a network operation
  &`USER       `&  set the DN, for authenticating the LDAP bind
  &`PASS       `&  set the password, likewise
  &`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
  &`SIZE       `&  set the limit for the number of entries returned
  &`TIME       `&  set the maximum waiting time for a query
  .endd
  The value of the DEREFERENCE parameter must be one of the words &"never"&,
  &`SIZE       `&  set the limit for the number of entries returned
  &`TIME       `&  set the maximum waiting time for a query
  .endd
  The value of the DEREFERENCE parameter must be one of the words &"never"&,
-&"searching"&, &"finding"&, or &"always"&.
+&"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter
+must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP
+library from trying to follow referrals issued by the LDAP server.
  
  The name CONNECT is an obsolete name for NETTIME, retained for
  backwards compatibility. This timeout (specified as a number of seconds) is
  
  The name CONNECT is an obsolete name for NETTIME, retained for
  backwards compatibility. This timeout (specified as a number of seconds) is
@@ -6898,7 +7033,7 @@ operator is to double any quote characters within the text.
  
  .section "SQL lookups" "SECTsql"
  .cindex "SQL lookup types"
  
  .section "SQL lookups" "SECTsql"
  .cindex "SQL lookup types"
-Exim can support lookups in Interbase, MySQL, Oracle, PostgreSQL, and SQLite
+Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite
  databases. Queries for these databases contain SQL statements, so an example
  might be
  .code
  databases. Queries for these databases contain SQL statements, so an example
  might be
  .code
@@ -6925,16 +7060,16 @@ If the result of the query yields more than one row, it is all concatenated,
  with a newline between the data for each row.
  
  
  with a newline between the data for each row.
  
  
-.section "More about MySQL, PostgreSQL, Oracle, and Interbase"
+.section "More about MySQL, PostgreSQL, Oracle, and InterBase"
  .cindex "MySQL" "lookup type"
  .cindex "PostgreSQL lookup type"
  .cindex "lookup" "MySQL"
  .cindex "lookup" "PostgreSQL"
  .cindex "Oracle" "lookup type"
  .cindex "lookup" "Oracle"
  .cindex "MySQL" "lookup type"
  .cindex "PostgreSQL lookup type"
  .cindex "lookup" "MySQL"
  .cindex "lookup" "PostgreSQL"
  .cindex "Oracle" "lookup type"
  .cindex "lookup" "Oracle"
-.cindex "Interbase lookup type"
-.cindex "lookup" "Interbase"
-If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the
+.cindex "InterBase lookup type"
+.cindex "lookup" "InterBase"
+If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the
  &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%&
  option (as appropriate) must be set to a colon-separated list of server
  information. Each item in the list is a slash-separated list of four items:
  &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%&
  option (as appropriate) must be set to a colon-separated list of server
  information. Each item in the list is a slash-separated list of four items:
@@ -7173,7 +7308,8 @@ always fixed strings, just as for any other single-key lookup type.
  
  If you want to use a file to contain wild-card patterns that form part of a
  list, just give the file name on its own, without a search type, as described
  
  If you want to use a file to contain wild-card patterns that form part of a
  list, just give the file name on its own, without a search type, as described
-in the previous section.
+in the previous section. You could also use the &(wildlsearch)& or
+&(nwildlsearch)&, but there is no advantage in doing this.
  
  
  
  
  
  
@@ -7676,10 +7812,17 @@ Consider what will happen if a name cannot be found.
  Because of the problems of determining host names from IP addresses, matching
  against host names is not as common as matching against IP addresses.
  
  Because of the problems of determining host names from IP addresses, matching
  against host names is not as common as matching against IP addresses.
  
+.new
  By default, in order to find a host name, Exim first does a reverse DNS lookup;
  if no name is found in the DNS, the system function (&[gethostbyaddr()]& or
  &[getipnodebyaddr()]& if available) is tried. The order in which these lookups
  By default, in order to find a host name, Exim first does a reverse DNS lookup;
  if no name is found in the DNS, the system function (&[gethostbyaddr()]& or
  &[getipnodebyaddr()]& if available) is tried. The order in which these lookups
-are done can be changed by setting the &%host_lookup_order%& option.
+are done can be changed by setting the &%host_lookup_order%& option. For
+security, once Exim has found one or more names, it looks up the IP addresses
+for these names and compares them with the IP address that it started with.
+Only those names whose IP addresses match are accepted. Any other names are
+discarded. If no names are left, Exim behaves as if the host name cannot be
+found. In the most common case there is only one name and one IP address.
+.wen
  
  There are some options that control what happens if a host name cannot be
  found. These are described in section &<<SECTbehipnot>>& below.
  
  There are some options that control what happens if a host name cannot be
  found. These are described in section &<<SECTbehipnot>>& below.
@@ -8178,6 +8321,23 @@ Exim gives up its root privilege when it is called with the &%-be%& option, and
  instead runs under the uid and gid it was called with, to prevent users from
  using &%-be%& for reading files to which they do not have access.
  
  instead runs under the uid and gid it was called with, to prevent users from
  using &%-be%& for reading files to which they do not have access.
  
+.new
+.cindex "&%-bem%& option"
+If you want to test expansions that include variables whose values are taken
+from a message, there are two other options that can be used. The &%-bem%&
+option is like &%-be%& except that it is followed by a file name. The file is
+read as a message before doing the test expansions. For example:
+.code
+exim -bem /tmp/test.message '$h_subject:'
+.endd
+The &%-Mset%& option is used in conjunction with &%-be%& and is followed by an
+Exim message identifier. For example:
+.code
+exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
+.endd
+This loads the message from Exim's spool before doing the test expansions, and
+is therefore restricted to admin users.
+.wen
  
  
  .section "Forced expansion failure" "SECTforexpfai"
  
  
  .section "Forced expansion failure" "SECTforexpfai"
@@ -8437,18 +8597,20 @@ any printing characters except space and colon. Consequently, curly brackets
  &'do not'& terminate header names, and should not be used to enclose them as
  if they were variables. Attempting to do so causes a syntax error.
  
  &'do not'& terminate header names, and should not be used to enclose them as
  if they were variables. Attempting to do so causes a syntax error.
  
+.new
  Only header lines that are common to all copies of a message are visible to
  this mechanism. These are the original header lines that are received with the
  Only header lines that are common to all copies of a message are visible to
  this mechanism. These are the original header lines that are received with the
-message, and any that are added by an ACL &%warn%& statement or by a system
+message, and any that are added by an ACL statement or by a system
  filter. Header lines that are added to a particular copy of a message by a
  router or transport are not accessible.
  
  For incoming SMTP messages, no header lines are visible in ACLs that are obeyed
  before the DATA ACL, because the header structure is not set up until the
  filter. Header lines that are added to a particular copy of a message by a
  router or transport are not accessible.
  
  For incoming SMTP messages, no header lines are visible in ACLs that are obeyed
  before the DATA ACL, because the header structure is not set up until the
-message is received. Header lines that are added by &%warn%& statements in a
-RCPT ACL (for example) are saved until the message's incoming header lines
-are available, at which point they are added. When a DATA ACL is running,
-however, header lines added by earlier ACLs are visible.
+message is received. Header lines that are added in a RCPT ACL (for example)
+are saved until the message's incoming header lines are available, at which
+point they are added. When a DATA ACL is running, however, header lines added
+by earlier ACLs are visible.
+.wen
  
  Upper case and lower case letters are synonymous in header names. If the
  following character is white space, the terminating colon may be omitted, but
  
  Upper case and lower case letters are synonymous in header names. If the
  following character is white space, the terminating colon may be omitted, but
@@ -8458,12 +8620,16 @@ If the message does not contain the given header, the expansion item is
  replaced by an empty string. (See the &%def%& condition in section
  &<<SECTexpcond>>& for a means of testing for the existence of a header.)
  
  replaced by an empty string. (See the &%def%& condition in section
  &<<SECTexpcond>>& for a means of testing for the existence of a header.)
  
-If there is more than one header with the same name, they are all
-concatenated to form the substitution string, up to a maximum length of 64K. A
-newline character is inserted between each line. For the &%header%& expansion,
-for those headers that contain lists of addresses, a comma is also inserted at
-the junctions between lines. This does not happen for the &%rheader%&
-expansion.
+.new
+If there is more than one header with the same name, they are all concatenated
+to form the substitution string, up to a maximum length of 64K. Unless
+&%rheader%& is being used, leading and trailing white space is removed from
+each header before concatenation, and a completely empty header is ignored. A
+newline character is then inserted between non-empty headers, but there is no
+newline at the very end. For the &%header%& and &%bheader%& expansion, for
+those headers that contain lists of addresses, a comma is also inserted at the
+junctions between headers. This does not happen for the &%rheader%& expansion.
+.wen
  
  
  .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*&
  
  
  .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*&
@@ -8710,7 +8876,6 @@ locks out the use of this expansion item in filter files.
  .cindex "expansion" "inserting from a socket"
  .cindex "socket" "use of in expansion"
  .cindex "&%readsocket%& expansion item"
  .cindex "expansion" "inserting from a socket"
  .cindex "socket" "use of in expansion"
  .cindex "&%readsocket%& expansion item"
-.new
  This item inserts data from a Unix domain or Internet socket into the expanded
  string. The minimal way of using it uses just two arguments, as in these
  examples:
  This item inserts data from a Unix domain or Internet socket into the expanded
  string. The minimal way of using it uses just two arguments, as in these
  examples:
@@ -8733,18 +8898,15 @@ both kinds of socket, Exim makes a connection, writes the request string
  (unless it is an empty string) and reads from the socket until an end-of-file
  is read. A timeout of 5 seconds is applied. Additional, optional arguments
  extend what can be done. Firstly, you can vary the timeout. For example:
  (unless it is an empty string) and reads from the socket until an end-of-file
  is read. A timeout of 5 seconds is applied. Additional, optional arguments
  extend what can be done. Firstly, you can vary the timeout. For example:
-.wen
  .code
  .code
-${readsocket{/socket/name}{request-string}{3s}}
+${readsocket{/socket/name}{request string}{3s}}
  .endd
  A fourth argument allows you to change any newlines that are in the data
  that is read, in the same way as for &%readfile%& (see above). This example
  turns them into spaces:
  .endd
  A fourth argument allows you to change any newlines that are in the data
  that is read, in the same way as for &%readfile%& (see above). This example
  turns them into spaces:
-.new
  .code
  .code
-${readsocket{inet:127.0.0.1:3294}{request-string}{3s}{ }}
+${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
  .endd
  .endd
-.wen
  As with all expansions, the substrings are expanded before the processing
  happens. Errors in these sub-expansions cause the expansion to fail. In
  addition, the following errors can occur:
  As with all expansions, the substrings are expanded before the processing
  happens. Errors in these sub-expansions cause the expansion to fail. In
  addition, the following errors can occur:
@@ -8754,7 +8916,7 @@ Failure to create a socket file descriptor;
  .next
  Failure to connect the socket;
  .next
  .next
  Failure to connect the socket;
  .next
-Failure to write the request-string;
+Failure to write the request string;
  .next
  Timeout on reading from the socket.
  .endlist
  .next
  Timeout on reading from the socket.
  .endlist
@@ -8763,16 +8925,14 @@ By default, any of these errors causes the expansion to fail. However, if
  you supply a fifth substring, it is expanded and used when any of the above
  errors occurs. For example:
  .code
  you supply a fifth substring, it is expanded and used when any of the above
  errors occurs. For example:
  .code
-${readsocket{/socket/name}{request-string}{3s}{\n}\
+${readsocket{/socket/name}{request string}{3s}{\n}\
    {socket failure}}
  .endd
    {socket failure}}
  .endd
-.new
  You can test for the existence of a Unix domain socket by wrapping this
  expansion in &`${if exists`&, but there is a race condition between that test
  and the actual opening of the socket, so it is safer to use the fifth argument
  if you want to be absolutely sure of avoiding an expansion error for a
  non-existent Unix domain socket, or a failure to connect to an Internet socket.
  You can test for the existence of a Unix domain socket by wrapping this
  expansion in &`${if exists`&, but there is a race condition between that test
  and the actual opening of the socket, so it is safer to use the fifth argument
  if you want to be absolutely sure of avoiding an expansion error for a
  non-existent Unix domain socket, or a failure to connect to an Internet socket.
-.wen
  
  The &(redirect)& router has an option called &%forbid_filter_readsocket%& which
  locks out the use of this expansion item in filter files.
  
  The &(redirect)& router has an option called &%forbid_filter_readsocket%& which
  locks out the use of this expansion item in filter files.
@@ -8790,17 +8950,23 @@ 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 you want
  a shell, you must explicitly code it.
  
  other command executions from Exim, a shell is not used by default. If you want
  a shell, you must explicitly code it.
  
+.new
+The standard input for the command exists, but is empty. The standard output
+and standard error are set to the same file descriptor.
  .cindex "return code" "from &%run%& expansion"
  .cindex "&$value$&"
  If the command succeeds (gives a zero return code) <&'string1'&> is expanded
  .cindex "return code" "from &%run%& expansion"
  .cindex "&$value$&"
  If the command succeeds (gives a zero return code) <&'string1'&> is expanded
-and replaces the entire item; during this expansion, the standard output from
-the command is in the variable &$value$&. If the command fails, <&'string2'&>,
-if present, is expanded and used. Once again, during the expansion, the
-standard output from the command is in the variable &$value$&. If <&'string2'&>
-is absent, the result is empty. Alternatively, <&'string2'&> can be the word
-&"fail"& (not in braces) to force expansion failure if the command does not
-succeed. If both strings are omitted, the result is contents of the standard
-output on success, and nothing on failure.
+and replaces the entire item; during this expansion, the standard output/error
+from the command is in the variable &$value$&. If the command fails,
+<&'string2'&>, if present, is expanded and used. Once again, during the
+expansion, the standard output/error from the command is in the variable
+&$value$&.
+
+If <&'string2'&> is absent, the result is empty. Alternatively, <&'string2'&>
+can be the word &"fail"& (not in braces) to force expansion failure if the
+command does not succeed. If both strings are omitted, the result is contents
+of the standard output/error on success, and nothing on failure.
+.wen
  
  .cindex "&$runrc$&"
  The return code from the command is put in the variable &$runrc$&, and this
  
  .cindex "&$runrc$&"
  The return code from the command is put in the variable &$runrc$&, and this
@@ -8979,29 +9145,49 @@ is controlled by the &%print_topbitchars%& option.
  .cindex "expansion" "expression evaluation"
  .cindex "expansion" "arithmetic expression"
  .cindex "&%eval%& expansion item"
  .cindex "expansion" "expression evaluation"
  .cindex "expansion" "arithmetic expression"
  .cindex "&%eval%& expansion item"
-These items supports simple arithmetic in expansion strings. The string (after
-expansion) must be a conventional arithmetic expression, but it is limited to
-five basic operators (plus, minus, times, divide, remainder) and parentheses.
-All operations are carried out using integer arithmetic. Plus and minus have a
-lower priority than times, divide, and remainder; operators with the same
-priority are evaluated from left to right.
+.new
+These items supports simple arithmetic and bitwise logical operations in
+expansion strings. The string (after expansion) must be a conventional
+arithmetic expression, but it is limited to basic arithmetic operators, bitwise
+logical operators, and parentheses. All operations are carried out using
+integer arithmetic. The operator priorities are as follows (the same as in the
+C programming language):
+.table2 90pt 300pt
+.row &~&~&~&~&~&~&~&~&'highest:'& "not (~), negate (-)"
+.row ""   "multiply (*), divide (/), remainder (%)"
+.row ""   "plus (+), minus (-)"
+.row ""   "shift-left (<<), shift-right (>>)"
+.row ""   "and (&&)"
+.row ""   "xor (^)"
+.row &~&~&~&~&~&~&~&~&'lowest:'&  "or (|)"
+.endtable
+Binary operators with the same priority are evaluated from left to right. White
+space is permitted before or after operators.
  
  For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or
  hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as
  
  For &%eval%&, numbers may be decimal, octal (starting with &"0"&) or
  hexadecimal (starting with &"0x"&). For &%eval10%&, all numbers are taken as
-decimal, even if they start with a leading zero. This can be useful when
-processing numbers extracted from dates or times, which often do have leading
-zeros.
+decimal, even if they start with a leading zero; hexadecimal numbers are not
+permitted. This can be useful when processing numbers extracted from dates or
+times, which often do have leading zeros.
  
  A number may be followed by &"K"& or &"M"& to multiply it by 1024 or 1024*1024,
  respectively. Negative numbers are supported. The result of the computation is
  a decimal representation of the answer (without &"K"& or &"M"&). For example:
  
  .display
  
  A number may be followed by &"K"& or &"M"& to multiply it by 1024 or 1024*1024,
  respectively. Negative numbers are supported. The result of the computation is
  a decimal representation of the answer (without &"K"& or &"M"&). For example:
  
  .display
-&`${eval:1+1}     `&  yields 2
-&`${eval:1+2*3}   `&  yields 7
-&`${eval:(1+2)*3} `&  yields 9
-&`${eval:2+42%5}  `&  yields 4
+&`${eval:1+1}            `&  yields 2
+&`${eval:1+2*3}          `&  yields 7
+&`${eval:(1+2)*3}        `&  yields 9
+&`${eval:2+42%5}         `&  yields 4
+&`${eval:0xc&amp;5}          `&  yields 4
+&`${eval:0xc|5}          `&  yields 13
+&`${eval:0xc^5}          `&  yields 9
+&`${eval:0xc>>1}         `&  yields 6
+&`${eval:0xc<<1}         `&  yields 24
+&`${eval:~255&amp;0x1234}    `&  yields 4608
+&`${eval:-(~255&amp;0x1234)} `&  yields -4608
  .endd
  .endd
+.wen
  
  As a more realistic example, in an ACL you might have
  .code
  
  As a more realistic example, in an ACL you might have
  .code
@@ -9200,15 +9386,6 @@ For single-key lookup types, no quoting is ever necessary and this operator
  yields an unchanged string.
  
  
  yields an unchanged string.
  
  
-.vitem &*${rxquote:*&<&'string'&>&*}*&
-.cindex "quoting" "in regular expressions"
-.cindex "regular expressions" "quoting"
-.cindex "&%rxquote%& expansion item"
-The &%rxquote%& operator inserts a backslash before any non-alphanumeric
-characters in its argument. This is useful when substituting the values of
-variables or headers inside regular expressions.
-
-
  .vitem &*${rfc2047:*&<&'string'&>&*}*&
  .cindex "expansion" "RFC 2047"
  .cindex "RFC 2047" "expansion operator"
  .vitem &*${rfc2047:*&<&'string'&>&*}*&
  .cindex "expansion" "RFC 2047"
  .cindex "RFC 2047" "expansion operator"
@@ -9228,6 +9405,15 @@ characters.
  
  
  
  
  
  
+.vitem &*${rxquote:*&<&'string'&>&*}*&
+.cindex "quoting" "in regular expressions"
+.cindex "regular expressions" "quoting"
+.cindex "&%rxquote%& expansion item"
+The &%rxquote%& operator inserts a backslash before any non-alphanumeric
+characters in its argument. This is useful when substituting the values of
+variables or headers inside regular expressions.
+
+
  .vitem &*${sha1:*&<&'string'&>&*}*&
  .cindex "SHA-1 hash"
  .cindex "expansion" "SHA-1 hashing"
  .vitem &*${sha1:*&<&'string'&>&*}*&
  .cindex "SHA-1 hash"
  .cindex "expansion" "SHA-1 hashing"
@@ -9312,7 +9498,7 @@ This forces the letters in the string into upper-case.
  
  
  .section "Expansion conditions" "SECTexpcond"
  
  
  .section "Expansion conditions" "SECTexpcond"
-.cindex "expansion" "conditions"
+.scindex IIDexpcond "expansion" "conditions"
  The following conditions are available for testing by the &%${if%& construct
  while expanding strings:
  
  The following conditions are available for testing by the &%${if%& construct
  while expanding strings:
  
@@ -9344,6 +9530,8 @@ Note that the general negation operator provides for inequality testing. The
  two strings must take the form of optionally signed decimal integers,
  optionally followed by one of the letters &"K"& or &"M"& (in either upper or
  lower case), signifying multiplication by 1024 or 1024*1024, respectively.
  two strings must take the form of optionally signed decimal integers,
  optionally followed by one of the letters &"K"& or &"M"& (in either upper or
  lower case), signifying multiplication by 1024 or 1024*1024, respectively.
+&new("As a special case, the numerical value of an empty string is taken as
+zero.")
  
  .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
  .cindex "expansion" "encrypted comparison"
  
  .vitem &*crypteq&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
  .cindex "expansion" "encrypted comparison"
@@ -9397,30 +9585,37 @@ SHA-1 digest. If the length is not 28 or 40, the comparison fails.
  only the first eight characters of the password. However, in modern operating
  systems this is no longer true, and in many cases the entire password is used,
  whatever its length.
  only the first eight characters of the password. However, in modern operating
  systems this is no longer true, and in many cases the entire password is used,
  whatever its length.
+
  .next
  .next
+.new
  .cindex "&[crypt16()]&"
  .cindex "&[crypt16()]&"
-&%{crypt16}%& calls the &[crypt16()]& function (also known as &[bigcrypt()]&),
-which was orginally created to use up to 16 characters of the password. Again,
-in modern operating systems, more characters may be used.
+&%{crypt16}%& calls the &[crypt16()]& function, which was orginally created to
+use up to 16 characters of the password in some operating systems. Again, in
+modern operating systems, more characters may be used.
  .endlist
  .endlist
-
-Exim has its own version of &[crypt16()]& (which is just a double call to
-&[crypt()]&). For operating systems that have their own version, setting
+Exim has its own version of &[crypt16()]&, which is just a double call to
+&[crypt()]&. For operating systems that have their own version, setting
  HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the
  operating system version instead of its own. This option is set by default in
  the OS-dependent &_Makefile_& for those operating systems that are known to
  support &[crypt16()]&.
  
  HAVE_CRYPT16 in &_Local/Makefile_& when building Exim causes it to use the
  operating system version instead of its own. This option is set by default in
  the OS-dependent &_Makefile_& for those operating systems that are known to
  support &[crypt16()]&.
  
-If you do not put any curly bracket encryption type in a &%crypteq%&
-comparison, the default is either &`{crypt}`& or &`{crypt16}`&, as determined
-by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default default is
-&`{crypt}`&. Whatever the default, you can always use either function by
-specifying it explicitly in curly brackets.
-
-Note that if a password is no longer than 8 characters, the results of
-encrypting it with &[crypt()]& and &[crypt16()]& are identical. That means that
-&[crypt16()]& is backwards compatible, as long as nobody feeds it a password
-longer than 8 characters.
+Some years after Exim's &[crypt16()]& was implemented, a user discovered that
+it was not using the same algorithm as some operating systems' versions. It
+turns out that as well as &[crypt16()]& there is a function called
+&[bigcrypt()]& in some operating systems. This may or may not use the same
+algorithm, and both of them may be different to Exim's built-in &[crypt16()]&.
+
+However, since there is now a move away from the traditional &[crypt()]&
+functions towards using SHA1 and other algorithms, tidying up this area of
+Exim is seen as very low priority.
+
+If you do not put a encryption type (in curly brackets) in a &%crypteq%&
+comparison, the default is usually either &`{crypt}`& or &`{crypt16}`&, as
+determined by the setting of DEFAULT_CRYPT in &_Local/Makefile_&. The default
+default is &`{crypt}`&. Whatever the default, you can always use either
+function by specifying it explicitly in curly brackets.
+.wen
  
  .vitem &*def:*&<&'variable&~name'&>
  .cindex "expansion" "checking for empty variable"
  
  .vitem &*def:*&<&'variable&~name'&>
  .cindex "expansion" "checking for empty variable"
@@ -9644,7 +9839,12 @@ specified. Thus, the following are equivalent:
    ${if match_ip{$sender_host_address}{net-lsearch;/some/file}...
  .endd
  You do need to specify the &`net-`& prefix if you want to specify a
    ${if match_ip{$sender_host_address}{net-lsearch;/some/file}...
  .endd
  You do need to specify the &`net-`& prefix if you want to specify a
-specific address mask, for example, by using &`net24-`&.
+specific address mask, for example, by using &`net24-`&. However, unless you
+are combining a &%match_ip%& condition with others, it is usually neater to use
+an expansion lookup such as:
+.code
+  ${lookup{${mask:$sender_host_address/24}}lsearch{/some/file}...
+.endd
  .endlist ilist
  
  Consult section &<<SECThoslispatip>>& for further details of these patterns.
  .endlist ilist
  
  Consult section &<<SECThoslispatip>>& for further details of these patterns.
@@ -9710,11 +9910,11 @@ separators. If the data is being inserted from a variable, the &%sg%& expansion
  item can be used to double any existing colons. For example, the configuration
  of a LOGIN authenticator might contain this setting:
  .code
  item can be used to double any existing colons. For example, the configuration
  of a LOGIN authenticator might contain this setting:
  .code
-server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}}
+server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}}
  .endd
  For a PLAIN authenticator you could use:
  .code
  .endd
  For a PLAIN authenticator you could use:
  .code
-server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}}
+server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}}
  .endd
  In some operating systems, PAM authentication can be done only from a process
  running as root. Since Exim is running as the Exim user when receiving
  .endd
  In some operating systems, PAM authentication can be done only from a process
  running as root. Since Exim is running as the Exim user when receiving
@@ -9751,7 +9951,7 @@ The &%pwcheck%& condition takes one argument, which must be the user name and
  password, separated by a colon. For example, in a LOGIN authenticator
  configuration, you might have this:
  .code
  password, separated by a colon. For example, in a LOGIN authenticator
  configuration, you might have this:
  .code
-server_condition = ${if pwcheck{$1:$2}{1}{0}}
+server_condition = ${if pwcheck{$auth1:$auth2}}
  .endd
  .vitem &*queue_running*&
  .cindex "queue runner" "detecting when delivering from"
  .endd
  .vitem &*queue_running*&
  .cindex "queue runner" "detecting when delivering from"
@@ -9764,7 +9964,7 @@ initiated by queue runner processes, and false otherwise.
  .vitem &*radius&~{*&<&'authentication&~string'&>&*}*&
  .cindex "Radius"
  .cindex "expansion" "Radius authentication"
  .vitem &*radius&~{*&<&'authentication&~string'&>&*}*&
  .cindex "Radius"
  .cindex "expansion" "Radius authentication"
-.cindex "&%radiu%& expansion condition"
+.cindex "&%radius%& expansion condition"
  Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
  set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of
  the Radius client configuration file in order to build Exim with Radius
  Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
  set RADIUS_CONFIG_FILE in &_Local/Makefile_& to specify the location of
  the Radius client configuration file in order to build Exim with Radius
@@ -9789,7 +9989,7 @@ The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
  Radius client library, which calls the Radius server. The condition is true if
  the authentication is successful. For example:
  .code
  Radius client library, which calls the Radius server. The condition is true if
  the authentication is successful. For example:
  .code
-server_condition = ${if radius{<arguments>}{yes}{no}}
+server_condition = ${if radius{<arguments>}}
  .endd
  
  
  .endd
  
  
@@ -9817,7 +10017,7 @@ from the Cyrus SASL library.
  Up to four arguments can be supplied to the &%saslauthd%& condition, but only
  two are mandatory. For example:
  .code
  Up to four arguments can be supplied to the &%saslauthd%& condition, but only
  two are mandatory. For example:
  .code
-server_condition = ${if saslauthd{{$1}{$2}}{1}{0}}
+server_condition = ${if saslauthd{{$auth1}{$auth2}}}
  .endd
  The service and the realm are optional (which is why the arguments are enclosed
  in their own set of braces). For details of the meaning of the service and
  .endd
  The service and the realm are optional (which is why the arguments are enclosed
  in their own set of braces). For details of the meaning of the service and
@@ -9858,6 +10058,7 @@ sub-conditions, the values of the numeric variables afterwards are taken from
  the last one. When a false sub-condition is found, the following ones are
  parsed but not evaluated.
  .endlist
  the last one. When a false sub-condition is found, the following ones are
  parsed but not evaluated.
  .endlist
+.ecindex IIDexpcond
  
  
  
  
  
  
@@ -9882,9 +10083,9 @@ condition.
  .vitem "&$acl_c0$& &-- &$acl_c19$&"
  Values can be placed in these variables by the &%set%& modifier in an ACL. The
  values persist throughout the lifetime of an SMTP connection. They can be used
  .vitem "&$acl_c0$& &-- &$acl_c19$&"
  Values can be placed in these variables by the &%set%& modifier in an ACL. The
  values persist throughout the lifetime of an SMTP connection. They can be used
-to pass information between ACLs and different invocations of the same ACL.
-When a message is received, the values of these variables are saved with the
-message, and can be accessed by filters, routers, and transports during
+to pass information between ACLs and between different invocations of the same
+ACL. When a message is received, the values of these variables are saved with
+the message, and can be accessed by filters, routers, and transports during
  subsequent delivery.
  
  .vitem "&$acl_m0$& &-- &$acl_m19$&"
  subsequent delivery.
  
  .vitem "&$acl_m0$& &-- &$acl_m19$&"
@@ -9968,9 +10169,14 @@ preserve some of the authentication information in the variable
  &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a
  user/password authenticator configuration might preserve the user name for use
  in the routers. Note that this is not the same information that is saved in
  &$authenticated_id$& (see chapter &<<CHAPSMTPAUTH>>&). For example, a
  user/password authenticator configuration might preserve the user name for use
  in the routers. Note that this is not the same information that is saved in
-&$sender_host_authenticated$&. When a message is submitted locally (that is,
-not over a TCP connection) and if the submitter is not a trusted user,
-the value of &$authenticated_id$& is the login name of the calling process.
+&$sender_host_authenticated$&.
+When a message is submitted locally (that is, not over a TCP connection)
+the value of &$authenticated_id$& is normally the login name of the calling
+process. However, a trusted user can override this by means of the &%-oMai%&
+command line option.
+
+
+
  
  .vitem &$authenticated_sender$&
  .cindex "sender" "authenticated"
  
  .vitem &$authenticated_sender$&
  .cindex "sender" "authenticated"
@@ -9987,7 +10193,8 @@ sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data.
  .cindex "&$qualify_domain$&"
  When a message is submitted locally (that is, not over a TCP connection), the
  value of &$authenticated_sender$& is an address constructed from the login
  .cindex "&$qualify_domain$&"
  When a message is submitted locally (that is, not over a TCP connection), the
  value of &$authenticated_sender$& is an address constructed from the login
-name of the calling process and &$qualify_domain$&.
+name of the calling process and &$qualify_domain$&, except that a trusted user
+can override this by means of the &%-oMas%& command line option.
  
  
  .vitem &$authentication_failed$&
  
  
  .vitem &$authentication_failed$&
@@ -10088,13 +10295,17 @@ If there are multiple records, all the addresses are included, comma-space
  separated.
  
  .vitem &$domain$&
  separated.
  
  .vitem &$domain$&
+.new
  .cindex "&$domain$&"
  When an address is being routed, or delivered on its own, this variable
  .cindex "&$domain$&"
  When an address is being routed, or delivered on its own, this variable
-contains the domain. Global address rewriting happens when a message is
-received, so the value of &$domain$& during routing and delivery is the value
-after rewriting. &$domain$& is set during user filtering, but not during system
-filtering, because a message may have many recipients and the system filter is
-called just once.
+contains the domain. Uppercase letters in the domain are converted into lower
+case for &$domain$&.
+.wen
+
+Global address rewriting happens when a message is received, so the value of
+&$domain$& during routing and delivery is the value after rewriting. &$domain$&
+is set during user filtering, but not during system filtering, because a
+message may have many recipients and the system filter is called just once.
  
  When more than one address is being delivered at once (for example, several
  RCPT commands in one SMTP delivery), &$domain$& is set only if they all
  
  When more than one address is being delivered at once (for example, several
  RCPT commands in one SMTP delivery), &$domain$& is set only if they all
@@ -10191,18 +10402,24 @@ of the environment variable HOME.
  
  .vitem &$host$&
  .cindex "&$host$&"
  
  .vitem &$host$&
  .cindex "&$host$&"
-When the &(smtp)& transport is expanding its options for encryption using TLS,
-&$host$& contains the name of the host to which it is connected. Likewise, when
-used in the client part of an authenticator configuration (see chapter
-&<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the
-client is connected.
+If a router assigns an address to a transport (any transport), and passes a
+list of hosts with the address, the value of &$host$& when the transport starts
+to run is the name of the first host on the list. Note that this applies both
+to local and remote transports.
  
  .cindex "transport" "filter"
  .cindex "filter" "transport filter"
  
  .cindex "transport" "filter"
  .cindex "filter" "transport filter"
-When used in a transport filter (see chapter &<<CHAPtransportgeneric>>&)
-&$host$& refers to the host involved in the current connection. When a local
-transport is run as a result of a router that sets up a host list, &$host$&
-contains the name of the first host.
+For the &(smtp)& transport, if there is more than one host, the value of
+&$host$& changes as the transport works its way through the list. In
+particular, when the &(smtp)& transport is expanding its options for encryption
+using TLS, or for specifying a transport filter (see chapter
+&<<CHAPtransportgeneric>>&), &$host$& contains the name of the host to which it
+is connected.
+
+When used in the client part of an authenticator configuration (see chapter
+&<<CHAPSMTPAUTH>>&), &$host$& contains the name of the server to which the
+client is connected.
+
  
  .vitem &$host_address$&
  .cindex "&$host_address$&"
  
  .vitem &$host_address$&
  .cindex "&$host_address$&"
@@ -10260,18 +10477,15 @@ option in the &(appendfile)& transport. The variable contains the inode number
  of the temporary file which is about to be renamed. It can be used to construct
  a unique name for the file.
  
  of the temporary file which is about to be renamed. It can be used to construct
  a unique name for the file.
  
+.new
  .vitem &$interface_address$&
  .cindex "&$interface_address$&"
  .vitem &$interface_address$&
  .cindex "&$interface_address$&"
-As soon as a server starts processing a TCP/IP connection, this variable is set
-to the address of the local IP interface, and &$interface_port$& is set to the
-port number. These values are therefore available for use in the &"connect"&
-ACL. See also the &%-oMi%& command line option. As well as being used in ACLs,
-these variable could be used, for example, to make the file name for a TLS
-certificate depend on which interface and/or port is being used.
+This is an obsolete name for &$received_ip_address$&.
  
  .vitem &$interface_port$&
  .cindex "&$interface_port$&"
  
  .vitem &$interface_port$&
  .cindex "&$interface_port$&"
-See &$interface_address$&.
+This is an obsolete name for &$received_port$&.
+.wen
  
  .vitem &$ldap_dn$&
  .cindex "&$ldap_dn$&"
  
  .vitem &$ldap_dn$&
  .cindex "&$ldap_dn$&"
@@ -10465,9 +10679,18 @@ line; it is the local id that Exim assigns to the message, for example:
  &`1BXTIK-0001yO-VA`&.
  
  .vitem &$message_headers$&
  &`1BXTIK-0001yO-VA`&.
  
  .vitem &$message_headers$&
+.new
+.cindex &$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
  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.
+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$&
+.cindex &$message_headers_raw$&
+This variable is like &$message_headers$& except that no processing of the
+contents of header lines is done.
+.wen
  
  .vitem &$message_id$&
  This is an old name for &$message_exim_id$&, which is now deprecated.
  
  .vitem &$message_id$&
  This is an old name for &$message_exim_id$&, which is now deprecated.
@@ -10524,10 +10747,10 @@ of the &%add%& command in filter files.
  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
-variable contains the domain of the original address. This differs from
-&$parent_domain$& only when there is more than one level of aliasing or
-forwarding. When more than one address is being delivered in a single transport
-run, &$original_domain$& is not set.
+variable contains the domain of the original address (lower cased). This
+differs from &$parent_domain$& only when there is more than one level of
+aliasing or forwarding. When more than one address is being delivered in a
+single transport run, &$original_domain$& is not set.
  
  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
  
  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
@@ -10640,6 +10863,7 @@ RCPT ACL, its value includes the current command.
  
  .vitem &$rcpt_defer_count$&
  .cindex "&$rcpt_defer_count$&"
  
  .vitem &$rcpt_defer_count$&
  .cindex "&$rcpt_defer_count$&"
+.cindex "4&'xx'& responses" "count of"
  When a message is being received by SMTP, this variable contains the number of
  RCPT commands in the current message that have previously been rejected with a
  temporary (4&'xx'&) response.
  When a message is being received by SMTP, this variable contains the number of
  RCPT commands in the current message that have previously been rejected with a
  temporary (4&'xx'&) response.
@@ -10664,6 +10888,32 @@ variable contains that address when the &'Received:'& header line is being
  built. The value is copied after recipient rewriting has happened, but before
  the &[local_scan()]& function is run.
  
  built. The value is copied after recipient rewriting has happened, but before
  the &[local_scan()]& function is run.
  
+.new
+.vitem &$received_ip_address$&
+.cindex "&$received_ip_address$&"
+As soon as an Exim server starts processing an incoming TCP/IP connection, this
+variable is set to the address of the local IP interface, and &$received_port$&
+is set to the local port number. (The remote IP address and port are in
+&$sender_host_address$& and &$sender_host_port$&.) When testing with &%-bh%&,
+the port value is -1 unless it has been set using the &%-oMi%& command line
+option.
+
+As well as being useful in ACLs (including the &"connect"& ACL), these variable
+could be used, for example, to make the file name for a TLS certificate depend
+on which interface and/or port is being used for the incoming connection. The
+values of &$received_ip_address$& and &$received_port$& are saved with any
+messages that are received, thus making these variables available at delivery
+time.
+
+&*Note:*& There are no equivalent variables for outgoing connections, because
+the values are unknown (unless they are explicitly set by options of the
+&(smtp)& transport).
+
+.vitem &$received_port$&
+.cindex "&$received_port$&"
+See &$received_ip_address$&.
+.wen
+
  .vitem &$received_protocol$&
  .cindex "&$received_protocol$&"
  When a message is being processed, this variable contains the name of the
  .vitem &$received_protocol$&
  .cindex "&$received_protocol$&"
  When a message is being processed, this variable contains the name of the
@@ -10742,8 +10992,10 @@ in these two cases:
  .olist
  In a system filter file.
  .next
  .olist
  In a system filter file.
  .next
-In the ACLs associated with the DATA command, that is, the ACLs defined by
-&%acl_smtp_predata%& and &%acl_smtp_data%&.
+In the ACLs associated with the DATA command and with non-SMTP messages, that
+is, the ACLs defined by &%acl_smtp_predata%&, &%acl_smtp_data%&,
+&%acl_smtp_mime%&, &%acl_not_smtp_start%&, &%acl_not_smtp%&, and
+&%acl_not_smtp_mime%&.
  .endlist
  
  
  .endlist
  
  
@@ -10754,6 +11006,13 @@ envelope recipients that came with the message. Duplicates are not excluded
  from the count. While a message is being received over SMTP, the number
  increases for each accepted recipient. It can be referenced in an ACL.
  
  from the count. While a message is being received over SMTP, the number
  increases for each accepted recipient. It can be referenced in an ACL.
  
+
+.vitem &$regex_match_string$&
+.cindex "&$regex_match_string$&"
+This variable is set to contain the matching regular expression after a
+&%regex%& ACL condition has matched (see section &<<SECTscanregex>>&).
+
+
  .vitem &$reply_address$&
  .cindex "&$reply_address$&"
  When a message is being processed, this variable contains the contents of the
  .vitem &$reply_address$&
  .cindex "&$reply_address$&"
  When a message is being processed, this variable contains the contents of the
@@ -10799,10 +11058,13 @@ 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$&
  original router encountered. In other circumstances its contents are null.
  
  .vitem &$sender_address$&
+.new
  .cindex "&$sender_address$&"
  When a message is being processed, this variable contains the sender's address
  .cindex "&$sender_address$&"
  When a message is being processed, this variable contains the sender's address
-that was received in the message's envelope. For bounce messages, the value of
-this variable is the empty string. See also &$return_path$&.
+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
+value of this variable is the empty string. See also &$return_path$&.
+.wen
  
  .vitem &$sender_address_data$&
  .cindex "&$address_data$&"
  
  .vitem &$sender_address_data$&
  .cindex "&$address_data$&"
@@ -10890,7 +11152,7 @@ DNS timeout), &$host_lookup_deferred$& is set to &"1"&, and
  
  Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the
  host name again if there is a subsequent reference to &$sender_host_name$&
  
  Once &$host_lookup_failed$& is set to &"1"&, Exim does not try to look up the
  host name again if there is a subsequent reference to &$sender_host_name$&
-in the same Exim process, but it does try again if &$sender_host_deferred$&
+in the same Exim process, but it does try again if &$host_lookup_deferred$&
  is set to &"1"&.
  
  Exim does not automatically look up every calling host's name. If you want
  is set to &"1"&.
  
  Exim does not automatically look up every calling host's name. If you want
@@ -10969,8 +11231,8 @@ about the failure. The details are the same as for
  
  .vitem &$smtp_active_hostname$&
  .cindex "&$smtp_active_hostname$&"
  
  .vitem &$smtp_active_hostname$&
  .cindex "&$smtp_active_hostname$&"
-During an SMTP session, this variable contains the value of the active host
-name, as specified by the &%smtp_active_hostname%& option. The value of
+During an incoming SMTP session, this variable contains the value of the active
+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.
  
@@ -11303,8 +11565,10 @@ interfaces, or on different ports, and for this reason there are a number of
  options that can be used to influence Exim's behaviour. The rest of this
  chapter describes how they operate.
  
  options that can be used to influence Exim's behaviour. The rest of this
  chapter describes how they operate.
  
+.new
  When a message is received over TCP/IP, the interface and port that were
  When a message is received over TCP/IP, the interface and port that were
-actually used are set in &$interface_address$& and &$interface_port$&.
+actually used are set in &$received_ip_address$& and &$received_port$&.
+.wen
  
  
  
  
  
  
@@ -11718,7 +11982,7 @@ listed in more than one group.
  .row &%queue_run_max%&               "maximum simultaneous queue runners"
  .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
  .row &%smtp_accept_max%&             "simultaneous incoming connections"
  .row &%queue_run_max%&               "maximum simultaneous queue runners"
  .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
  .row &%smtp_accept_max%&             "simultaneous incoming connections"
-.row &%smtp_accept_max_nommail%&     "non-mail commands"
+.row &%smtp_accept_max_nonmail%&     "non-mail commands"
  .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies"
  .row &%smtp_accept_max_per_connection%& "messages per connection"
  .row &%smtp_accept_max_per_host%&    "connections from one host"
  .row &%smtp_accept_max_nonmail_hosts%& "hosts to which the limit applies"
  .row &%smtp_accept_max_per_connection%& "messages per connection"
  .row &%smtp_accept_max_per_host%&    "connections from one host"
@@ -11773,6 +12037,7 @@ listed in more than one group.
  .row &%message_size_limit%&          "for all messages"
  .row &%percent_hack_domains%&        "recognize %-hack for these domains"
  .row &%spamd_address%&               "set interface to SpamAssassin"
  .row &%message_size_limit%&          "for all messages"
  .row &%percent_hack_domains%&        "recognize %-hack for these domains"
  .row &%spamd_address%&               "set interface to SpamAssassin"
+.row &%strict_acl_vars%&             "object to unset ACL variables"
  .endtable
  
  
  .endtable
  
  
@@ -11904,7 +12169,7 @@ See also the &'Policy controls'& section above.
  .row &%check_rfc2047_length%&        "check length of RFC 2047 &""encoded &&&
                                        words""&"
  .row &%delivery_date_remove%&        "from incoming messages"
  .row &%check_rfc2047_length%&        "check length of RFC 2047 &""encoded &&&
                                        words""&"
  .row &%delivery_date_remove%&        "from incoming messages"
-.row &%envelope_to_remote%&          "from incoming messages"
+.row &%envelope_to_remove%&          "from incoming messages"
  .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing"
  .row &%headers_charset%&             "default for translations"
  .row &%qualify_domain%&              "default for senders"
  .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing"
  .row &%headers_charset%&             "default for translations"
  .row &%qualify_domain%&              "default for senders"
@@ -12343,7 +12608,7 @@ message is accepted.
  .cindex "&$spool_space$&"
  When any of these options are set, they apply to all incoming messages. If you
  want to apply different checks to different kinds of message, you can do so by
  .cindex "&$spool_space$&"
  When any of these options are set, they apply to all incoming messages. If you
  want to apply different checks to different kinds of message, you can do so by
-testing the the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and
+testing the variables &$log_inodes$&, &$log_space$&, &$spool_inodes$&, and
  &$spool_space$& in an ACL with appropriate additional conditions.
  
  
  &$spool_space$& in an ACL with appropriate additional conditions.
  
  
@@ -12426,13 +12691,18 @@ deferred addresses have the same domain, it is set in &$domain$& during the
  expansion. Otherwise &$domain$& is empty. If the result of the expansion is a
  forced failure, an empty string, or a string matching any of &"0"&, &"no"& or
  &"false"& (the comparison being done caselessly) then the warning message is
  expansion. Otherwise &$domain$& is empty. If the result of the expansion is a
  forced failure, an empty string, or a string matching any of &"0"&, &"no"& or
  &"false"& (the comparison being done caselessly) then the warning message is
-not sent. The default is
+not sent. The default is:
  .code
  .code
-delay_warning_condition = \
-  ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}}
+delay_warning_condition = ${if or {\
+  { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
+  { match{$h_precedence:}{(?i)bulk|list|junk} }\
+  { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
+  } {no}{yes}}
  .endd
  .endd
-which suppresses the sending of warnings about messages that have &"bulk"&,
-&"list"& or &"junk"& in a &'Precedence:'& header.
+This suppresses the sending of warnings for messages that contain &'List-ID:'&,
+&'List-Post:'&, or &'List-Subscribe:'& headers, or have &"bulk"&, &"list"& or
+&"junk"& in a &'Precedence:'& header, or have &"auto-generated"& or
+&"auto-replied"& in an &'Auto-Submitted:'& header.
  
  .option deliver_drop_privilege main boolean false
  .cindex "unprivileged delivery"
  
  .option deliver_drop_privilege main boolean false
  .cindex "unprivileged delivery"
@@ -13263,13 +13533,16 @@ which is not affected by this option.
  .cindex "limit" "message size"
  .cindex "size of message" "limit"
  This option limits the maximum size of message that Exim will process. The
  .cindex "limit" "message size"
  .cindex "size of message" "limit"
  This option limits the maximum size of message that Exim will process. The
-value is expanded for each incoming
-connection so, for example, it can be made to depend on the IP address of the
-remote host for messages arriving via TCP/IP. &*Note*&: This limit cannot be
-made to depend on a message's sender or any other properties of an individual
-message, because it has to be advertised in the server's response to EHLO.
-String expansion failure causes a temporary error. A value of zero means no
-limit, but its use is not recommended. See also &%bounce_return_size_limit%&.
+value is expanded for each incoming connection so, for example, it can be made
+to depend on the IP address of the remote host for messages arriving via
+TCP/IP. &new("After expansion, the value must be a sequence of decimal digits,
+optionally followed by K or M.")
+
+&*Note*&: This limit cannot be made to depend on a message's sender or any
+other properties of an individual message, because it has to be advertised in
+the server's response to EHLO. String expansion failure causes a temporary
+error. A value of zero means no limit, but its use is not recommended. See also
+&%bounce_return_size_limit%&.
  
  Incoming SMTP messages are failed with a 552 error if the limit is
  exceeded; locally-generated messages either get a stderr message or a delivery
  
  Incoming SMTP messages are failed with a 552 error if the limit is
  exceeded; locally-generated messages either get a stderr message or a delivery
@@ -13951,20 +14224,20 @@ See also &%smtp_accept_max_per_host%&.
  
  
  .option smtp_active_hostname main string&!! unset
  
  
  .option smtp_active_hostname main string&!! unset
+.new
  .cindex "host" "name in SMTP responses"
  .cindex "SMTP" "host name in responses"
  .cindex "&$primary_hostname$&"
  This option is provided for multi-homed servers that want to masquerade as
  .cindex "host" "name in SMTP responses"
  .cindex "SMTP" "host name in responses"
  .cindex "&$primary_hostname$&"
  This option is provided for multi-homed servers that want to masquerade as
-several different hosts. At the start of an SMTP connection, its value is
-expanded and used instead of the value of &$primary_hostname$& in SMTP
+several different hosts. At the start of an incoming SMTP connection, its value
+is expanded and used instead of the value of &$primary_hostname$& in SMTP
  responses. For example, it is used as domain name in the response to an
  incoming HELO or EHLO command.
  
  .cindex "&$smtp_active_hostname$&"
  responses. For example, it is used as domain name in the response to an
  incoming HELO or EHLO command.
  
  .cindex "&$smtp_active_hostname$&"
-It is also used in HELO commands for callout verification. The active hostname
-is placed in the &$smtp_active_hostname$& variable, which is saved with any
-messages that are received. It is therefore available for use in routers and
-transports when the message is later delivered.
+The active hostname is placed in the &$smtp_active_hostname$& variable, which
+is saved with any messages that are received. It is therefore available for use
+in routers and transports when the message is later delivered.
  
  If this option is unset, or if its expansion is forced to fail, or if the
  expansion results in an empty string, the value of &$primary_hostname$& is
  
  If this option is unset, or if its expansion is forced to fail, or if the
  expansion results in an empty string, the value of &$primary_hostname$& is
@@ -13973,10 +14246,16 @@ panic logs, and the SMTP command receives a temporary error. Typically, the
  value of &%smtp_active_hostname%& depends on the incoming interface address.
  For example:
  .code
  value of &%smtp_active_hostname%& depends on the incoming interface address.
  For example:
  .code
-smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\
+smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\
    {cox.mydomain}{box.mydomain}}
  .endd
  
    {cox.mydomain}{box.mydomain}}
  .endd
  
+Although &$smtp_active_hostname$& is primarily concerned with incoming
+messages, it is also used as the default for HELO commands in callout
+verification if there is no remote transport from which to obtain a
+&%helo_data%& value.
+.wen
+
  .option smtp_banner main string&!! "see below"
  .cindex "SMTP" "welcome banner"
  .cindex "banner for SMTP"
  .option smtp_banner main string&!! "see below"
  .cindex "SMTP" "welcome banner"
  .cindex "banner for SMTP"
@@ -14278,6 +14557,15 @@ tests of Exim without using the standard spool.
  This option controls the timeout that the &(sqlite)& lookup uses when trying to
  access an SQLite database. See section &<<SECTsqlite>>& for more details.
  
  This option controls the timeout that the &(sqlite)& lookup uses when trying to
  access an SQLite database. See section &<<SECTsqlite>>& for more details.
  
+.new
+.option strict_acl_vars main boolean false
+.cindex "ACL variables" "handling unset"
+This option controls what happens if a syntactically valid but undefined ACL
+variable is referenced. If it is false (the default), an empty string
+is substituted; if it is true, an error is generated. See section
+&<<SECTaclvariables>>& for details of ACL variables.
+.wen
+
  .option strip_excess_angle_brackets main boolean false
  .cindex "angle brackets" "excess"
  If this option is set, redundant pairs of angle brackets round &"route-addr"&
  .option strip_excess_angle_brackets main boolean false
  .cindex "angle brackets" "excess"
  If this option is set, redundant pairs of angle brackets round &"route-addr"&
@@ -14418,12 +14706,18 @@ TCP_NODELAY.
  .cindex "frozen messages" "timing out"
  .cindex "timeout" "frozen messages"
  If &%timeout_frozen_after%& is set to a time greater than zero, a frozen
  .cindex "frozen messages" "timing out"
  .cindex "timeout" "frozen messages"
  If &%timeout_frozen_after%& is set to a time greater than zero, a frozen
-message of any kind that has been on the queue for longer than the given
-time is automatically cancelled at the next queue run. If it is a bounce
-message, it is just discarded; otherwise, a bounce is sent to the sender, in a
-similar manner to cancellation by the &%-Mg%& command line option. If you want
-to timeout frozen bounce messages earlier than other kinds of frozen message,
-see &%ignore_bounce_errors_after%&.
+message of any kind that has been on the queue for longer than the given time
+is automatically cancelled at the next queue run. If the frozen message is a
+bounce message, it is just discarded; otherwise, a bounce is sent to the
+sender, in a similar manner to cancellation by the &%-Mg%& command line option.
+If you want to timeout frozen bounce messages earlier than other kinds of
+frozen message, see &%ignore_bounce_errors_after%&.
+
+.new
+&*Note:*& the default value of zero means no timeouts; with this setting,
+frozen messages remain on the queue forever (except for any frozen bounce
+messages that are released by &%ignore_bounce_errors_after%&).
+.wen
  
  
  .option timezone main string unset
  
  
  .option timezone main string unset
@@ -16869,10 +17163,9 @@ It is usual to set &%no_verify%& on &(redirect)& routers which handle users'
  
  .ilist
  When Exim is receiving an incoming SMTP message from a remote host, it is
  
  .ilist
  When Exim is receiving an incoming SMTP message from a remote host, it is
-running under the Exim uid, not as root.
-Exim is unable to change uid to read the file as the user, and it may not be
-able to read it as the Exim user. So in practice the router may not be able to
-operate.
+running under the Exim uid, not as root. Exim is unable to change uid to read
+the file as the user, and it may not be able to read it as the Exim user. So in
+practice the router may not be able to operate.
  .next
  However, even when the router can operate, the existence of a &_.forward_& file
  is unimportant when verifying an address. What should be checked is whether the
  .next
  However, even when the router can operate, the existence of a &_.forward_& file
  is unimportant when verifying an address. What should be checked is whether the
@@ -17121,14 +17414,24 @@ of a
  VRFY command, the text is included in the SMTP error response by
  default.
  .cindex "EXPN error text" "display of"
  VRFY command, the text is included in the SMTP error response by
  default.
  .cindex "EXPN error text" "display of"
-The text is not included in the response to an EXPN command.
+The text is not included in the response to an EXPN command. In non-SMTP cases
+the text is included in the error message that Exim generates.
+
+.cindex "SMTP" "error codes"
+By default, Exim sends a 451 SMTP code for a &':defer:'&, and 550 for
+&':fail:'&. However, if the message starts with three digits followed by a
+space, optionally followed by an extended code of the form &'n.n.n'&, also
+followed by a space, and the very first digit is the same as the default error
+code, the code from the message is used instead. If the very first digit is
+incorrect, a panic error is logged, and the default code is used. You can
+suppress the use of the supplied code in a redirect router by setting the
+&%forbid_smtp_code%& option true. In this case, any SMTP code is quietly
+ignored.
  
  .cindex "&$acl_verify_message$&"
  In an ACL, an explicitly provided message overrides the default, but the
  default message is available in the variable &$acl_verify_message$& and can
  
  .cindex "&$acl_verify_message$&"
  In an ACL, an explicitly provided message overrides the default, but the
  default message is available in the variable &$acl_verify_message$& and can
-therefore be included in a custom message if this is desired. Exim sends a 451
-SMTP code for a &':defer:'&, and 550 for &':fail:'&. In non-SMTP cases the text
-is included in the error message that Exim generates.
+therefore be included in a custom message if this is desired.
  
  Normally the error text is the rest of the redirection list &-- a comma does
  not terminate it &-- but a newline does act as a terminator. Newlines are not
  
  Normally the error text is the rest of the redirection list &-- a comma does
  not terminate it &-- but a newline does act as a terminator. Newlines are not
@@ -17349,6 +17652,13 @@ configured transport. This should normally be an &(appendfile)& transport. When
  it is running, the file name is in &$address_file$&.
  
  
  it is running, the file name is in &$address_file$&.
  
  
+.option filter_prepend_home redirect boolean true
+When this option is true, if a &(save)& command in an Exim filter specifies a
+relative path, and &$home$& is defined, it is automatically prepended to the
+relative path. If this option is set false, this action does not happen. The
+relative path is then passed to the transport unmodified.
+
+
  .option forbid_blackhole redirect boolean false
  If this option is true, the &':blackhole:'& item may not appear in a
  redirection list.
  .option forbid_blackhole redirect boolean false
  If this option is true, the &':blackhole:'& item may not appear in a
  redirection list.
@@ -17443,6 +17753,13 @@ If this option is set true, only Exim filters are permitted when
  &%allow_filter%& is true.
  
  
  &%allow_filter%& is true.
  
  
+.cindex "SMTP" "error codes"
+.option forbid_smtp_code redirect boolean false
+If this option is set true, any SMTP error codes that are present at the start
+of messages specified for &`:defer:`& or &`:fail:`& are quietly ignored, and
+the default codes (451 and 550, respectively) are always used.
+
+
  
  
  .option hide_child_in_errmsg redirect boolean false
  
  
  .option hide_child_in_errmsg redirect boolean false
@@ -18066,15 +18383,15 @@ to ensure that any additional groups associated with the uid are set up.
  .cindex "size of message" "limit"
  .cindex "transport" "message size; limiting"
  This option controls the size of messages passed through the transport. It is
  .cindex "size of message" "limit"
  .cindex "transport" "message size; limiting"
  This option controls the size of messages passed through the transport. It is
-expanded before use; the result of the expansion must be a sequence of digits,
-optionally followed by K or M.
-If the expansion fails for any reason, including forced failure, or if the
-result is not of the required form, delivery is deferred.
-If the value is greater than zero and the size of a message exceeds this
-limit, the address is failed. If there is any chance that the resulting bounce
-message could be routed to the same transport, you should ensure that
-&%return_size_limit%& is less than the transport's &%message_size_limit%&, as
-otherwise the bounce message will fail to get delivered.
+expanded before use; the result of the expansion must be a sequence of decimal
+digits, optionally followed by K or M. If the expansion fails for any reason,
+including forced failure, or if the result is not of the required form,
+delivery is deferred. If the value is greater than zero and the size of a
+message exceeds this limit, the address is failed. If there is any chance that
+the resulting bounce message could be routed to the same transport, you should
+ensure that &%return_size_limit%& is less than the transport's
+&%message_size_limit%&, as otherwise the bounce message will fail to get
+delivered.
  
  
  
  
  
  
@@ -18134,6 +18451,9 @@ SMTP MAIL command. If you set &%return_path%& for a local transport, the
  only effect is to change the address that is placed in the &'Return-path:'&
  header line, if one is added to the message (see the next option).
  
  only effect is to change the address that is placed in the &'Return-path:'&
  header line, if one is added to the message (see the next option).
  
+&*Note:*& A changed return path is not logged unless you add
+&%return_path_on_delivery%& to the log selector.
+
  .cindex "&$return_path$&"
  The expansion can refer to the existing value via &$return_path$&. This is
  either the message's envelope sender, or an address set by the
  .cindex "&$return_path$&"
  The expansion can refer to the existing value via &$return_path$&. This is
  either the message's envelope sender, or an address set by the
@@ -18385,7 +18705,6 @@ to some other delivery mechanism such as UUCP, multiple recipients may be
  acceptable.
  .endlist
  
  acceptable.
  .endlist
  
-.new
  These three local transports all have the same options for controlling multiple
  (&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save
  repeating the information for each transport, these options are described here.
  These three local transports all have the same options for controlling multiple
  (&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save
  repeating the information for each transport, these options are described here.
@@ -18396,7 +18715,6 @@ delivered together in a single run of the transport. Its default value is one
  &%batch_max%& value greater than one, the addresses are delivered in a batch
  (that is, in a single run of the transport with multiple recipients), subject
  to certain conditions:
  &%batch_max%& value greater than one, the addresses are delivered in a batch
  (that is, in a single run of the transport with multiple recipients), subject
  to certain conditions:
-.wen
  
  .ilist
  .cindex "&$local_part$&"
  
  .ilist
  .cindex "&$local_part$&"
@@ -18420,7 +18738,6 @@ group for the transport, and if a host list is present, the first host must
  be the same.
  .endlist
  
  be the same.
  .endlist
  
-.new
  In the case of the &(appendfile)& and &(pipe)& transports, batching applies
  both when the file or pipe command is specified in the transport, and when it
  is specified by a &(redirect)& router, but all the batched addresses must of
  In the case of the &(appendfile)& and &(pipe)& transports, batching applies
  both when the file or pipe command is specified in the transport, and when it
  is specified by a &(redirect)& router, but all the batched addresses must of
@@ -18452,7 +18769,6 @@ of the recipient addresses to be inserted into the command as a separate
  argument. This provides a way of accessing all the addresses that are being
  delivered in the batch. &*Note:*& This is not possible for pipe commands that
  are specififed by a &(redirect)& router.
  argument. This provides a way of accessing all the addresses that are being
  delivered in the batch. &*Note:*& This is not possible for pipe commands that
  are specififed by a &(redirect)& router.
-.wen
  
  
  
  
  
  
@@ -18768,9 +19084,9 @@ delivery is deferred.
  
  
  .option file_must_exist appendfile boolean false
  
  
  .option file_must_exist appendfile boolean false
-If this option is true, the file specified by the &%file%& option must exist,
-and an error occurs if it does not. Otherwise, it is created if it does not
-exist.
+If this option is true, the file specified by the &%file%& option must exist.
+A temporary error occurs if it does not, causing delivery to be deferred.
+If this option is false, the file is created if it does not exist.
  
  
  .option lock_fcntl_timeout appendfile time 0s
  
  
  .option lock_fcntl_timeout appendfile time 0s
@@ -18824,10 +19140,8 @@ is treated as 1. See below for details of locking.
  
  
  .option lockfile_mode appendfile "octal integer" 0600
  
  
  .option lockfile_mode appendfile "octal integer" 0600
-.new
  This specifies the mode of the created lock file, when a lock file is being
  used (see &%use_lockfile%& and &%use_mbx_lock%&).
  This specifies the mode of the created lock file, when a lock file is being
  used (see &%use_lockfile%& and &%use_mbx_lock%&).
-.wen
  
  
  .option lockfile_timeout appendfile time 30m
  
  
  .option lockfile_timeout appendfile time 30m
@@ -18872,12 +19186,10 @@ SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section
  .option maildir_quota_directory_regex appendfile string "See below"
  .cindex "maildir format" "quota; directories included in"
  .cindex "quota" "maildir; directories included in"
  .option maildir_quota_directory_regex appendfile string "See below"
  .cindex "maildir format" "quota; directories included in"
  .cindex "quota" "maildir; directories included in"
-.new
  This option is relevant only when &%maildir_use_size_file%& is set. It defines
  a regular expression for specifying directories, relative to the quota
  directory (see &%quota_directory%&), that should be included in the quota
  calculation. The default value is:
  This option is relevant only when &%maildir_use_size_file%& is set. It defines
  a regular expression for specifying directories, relative to the quota
  directory (see &%quota_directory%&), that should be included in the quota
  calculation. The default value is:
-.wen
  .code
  maildir_quota_directory_regex = ^(?:cur|new|\..*)$
  .endd
  .code
  maildir_quota_directory_regex = ^(?:cur|new|\..*)$
  .endd
@@ -18888,12 +19200,10 @@ folder from the count (as some sites do), you need to change this setting to
  .code
  maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
  .endd
  .code
  maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$
  .endd
-.new
  This uses a negative lookahead in the regular expression to exclude the
  directory whose name is &_.Trash_&. When a directory is excluded from quota
  calculations, quota processing is bypassed for any messages that are delivered
  directly into that directory.
  This uses a negative lookahead in the regular expression to exclude the
  directory whose name is &_.Trash_&. When a directory is excluded from quota
  calculations, quota processing is bypassed for any messages that are delivered
  directly into that directory.
-.wen
  
  
  .option maildir_retries appendfile integer 10
  
  
  .option maildir_retries appendfile integer 10
@@ -18908,26 +19218,22 @@ section &<<SECTmaildirdelivery>>& below.
  
  .option maildir_use_size_file appendfile boolean false
  .cindex "maildir format" "&_maildirsize_& file"
  
  .option maildir_use_size_file appendfile boolean false
  .cindex "maildir format" "&_maildirsize_& file"
-.new
  Setting this option true enables support for &_maildirsize_& files. Exim
  creates a &_maildirsize_& file in a maildir if one does not exist, taking the
  quota from the &%quota%& option of the transport. If &%quota%& is unset, the
  value is zero. See &%maildir_quota_directory_regex%& above and section
  &<<SECTmaildirdelivery>>& below for further details.
  Setting this option true enables support for &_maildirsize_& files. Exim
  creates a &_maildirsize_& file in a maildir if one does not exist, taking the
  quota from the &%quota%& option of the transport. If &%quota%& is unset, the
  value is zero. See &%maildir_quota_directory_regex%& above and section
  &<<SECTmaildirdelivery>>& below for further details.
-.wen
  
  
-.new
  .option maildirfolder_create_regex appendfile string unset
  .cindex "maildir format" "&_maildirfolder_& file"
  .cindex "&_maildirfolder_&, creating"
  The value of this option is a regular expression. If it is unset, it has no
  .option maildirfolder_create_regex appendfile string unset
  .cindex "maildir format" "&_maildirfolder_& file"
  .cindex "&_maildirfolder_&, creating"
  The value of this option is a regular expression. If it is unset, it has no
-effect. Otherwise, before a maildir delivery takes place place, the pattern is
+effect. Otherwise, before a maildir delivery takes place, the pattern is
  matched against the name of the maildir directory, that is, the directory
  containing the &_new_& and &_tmp_& subdirectories that will be used for the
  delivery. If there is a match, Exim checks for the existence of a file called
  &_maildirfolder_& in the directory, and creates it if it does not exist.
  See section &<<SECTmaildirdelivery>>& for more details.
  matched against the name of the maildir directory, that is, the directory
  containing the &_new_& and &_tmp_& subdirectories that will be used for the
  delivery. If there is a match, Exim checks for the existence of a file called
  &_maildirfolder_& in the directory, and creates it if it does not exist.
  See section &<<SECTmaildirdelivery>>& for more details.
-.wen
  
  
  .option mailstore_format appendfile boolean false
  
  
  .option mailstore_format appendfile boolean false
@@ -19377,11 +19683,9 @@ file, and an exclusive lock on the file whose name is
  .code
  /tmp/.<device-number>.<inode-number>
  .endd
  .code
  /tmp/.<device-number>.<inode-number>
  .endd
-.new
  using the device and inode numbers of the open mailbox file, in accordance with
  the MBX locking rules. This file is created with a mode that is specified by
  the &%lockfile_mode%& option.
  using the device and inode numbers of the open mailbox file, in accordance with
  the MBX locking rules. This file is created with a mode that is specified by
  the &%lockfile_mode%& option.
-.wen
  
  If Exim fails to lock the file, there are two possible courses of action,
  depending on the value of the locking timeout. This is obtained from
  
  If Exim fails to lock the file, there are two possible courses of action,
  depending on the value of the locking timeout. This is obtained from
@@ -19452,13 +19756,11 @@ deferred.
  
  .section "Maildir delivery" "SECTmaildirdelivery"
  .cindex "maildir format" "description of"
  
  .section "Maildir delivery" "SECTmaildirdelivery"
  .cindex "maildir format" "description of"
-.new
  If the &%maildir_format%& option is true, Exim delivers each message by writing
  it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the
  directory that is defined by the &%directory%& option (the &"delivery
  directory"&). If the delivery is successful, the file is renamed into the
  &_new_& subdirectory.
  If the &%maildir_format%& option is true, Exim delivers each message by writing
  it to a file whose name is &_tmp/<stime>.H<mtime>P<pid>.<host>_& in the
  directory that is defined by the &%directory%& option (the &"delivery
  directory"&). If the delivery is successful, the file is renamed into the
  &_new_& subdirectory.
-.wen
  
  In the file name, <&'stime'&> is the current time of day in seconds, and
  <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery,
  
  In the file name, <&'stime'&> is the current time of day in seconds, and
  <&'mtime'&> is the microsecond fraction of the time. After a maildir delivery,
@@ -19468,7 +19770,6 @@ file name. However, as a precaution, Exim calls &[stat()]& for the file before
  opening it. If any response other than ENOENT (does not exist) is given,
  Exim waits 2 seconds and tries again, up to &%maildir_retries%& times.
  
  opening it. If any response other than ENOENT (does not exist) is given,
  Exim waits 2 seconds and tries again, up to &%maildir_retries%& times.
  
-.new
  Before Exim carries out a maildir delivery, it ensures that subdirectories
  called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they
  do not exist, Exim tries to create them and any superior directories in their
  Before Exim carries out a maildir delivery, it ensures that subdirectories
  called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they
  do not exist, Exim tries to create them and any superior directories in their
@@ -19491,7 +19792,7 @@ maildirfolder_create_regex = /\.[^/]+$
  If &$local_part_suffix$& is empty (there was no suffix for the local part),
  delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for
  the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does
  If &$local_part_suffix$& is empty (there was no suffix for the local part),
  delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for
  the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does
-not match this name, so Exim will not look for or create
+not match this name, so Exim will not look for or create the file
  &_/var/mail/pimbo/maildirfolder_&, though it will create
  &_/var/mail/pimbo/{cur,new,tmp}_& if necessary.
  
  &_/var/mail/pimbo/maildirfolder_&, though it will create
  &_/var/mail/pimbo/{cur,new,tmp}_& if necessary.
  
@@ -19504,7 +19805,6 @@ directories &_/var/mail/pimbo/.eximusers/{cur,new,tmp}_&.
  &*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does
  not inadvertently match the toplevel maildir directory, because a
  &_maildirfolder_& file at top level would completely break quota calculations.
  &*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does
  not inadvertently match the toplevel maildir directory, because a
  &_maildirfolder_& file at top level would completely break quota calculations.
-.wen
  
  .cindex "quota" "in maildir delivery"
  .cindex "maildir++"
  
  .cindex "quota" "in maildir delivery"
  .cindex "maildir++"
@@ -19566,12 +19866,10 @@ need to know the quota.
  If the &%quota%& option in the transport is unset or zero, the &_maildirsize_&
  file is maintained (with a zero quota setting), but no quota is imposed.
  
  If the &%quota%& option in the transport is unset or zero, the &_maildirsize_&
  file is maintained (with a zero quota setting), but no quota is imposed.
  
-.new
  A regular expression is available for controlling which directories in the
  maildir participate in quota calculations when a &_maildirsizefile_& is in use.
  See the description of the &%maildir_quota_directory_regex%& option above for
  details.
  A regular expression is available for controlling which directories in the
  maildir participate in quota calculations when a &_maildirsizefile_& is in use.
  See the description of the &%maildir_quota_directory_regex%& option above for
  details.
-.wen
  
  
  .section "Mailstore delivery"
  
  
  .section "Mailstore delivery"
@@ -19744,12 +20042,10 @@ used.
  
  
  .option never_mail autoreply "address list&!!" unset
  
  
  .option never_mail autoreply "address list&!!" unset
-.new
  If any run of the transport creates a message with a recipient that matches any
  item in the list, that recipient is quietly discarded. If all recipients are
  discarded, no message is created. This applies both when the recipients are
  generated by a filter and when they are specified in the transport.
  If any run of the transport creates a message with a recipient that matches any
  item in the list, that recipient is quietly discarded. If all recipients are
  discarded, no message is created. This applies both when the recipients are
  generated by a filter and when they are specified in the transport.
-.wen
  
  
  
  
  
  
@@ -19925,7 +20221,6 @@ transport is configured as a &(pipe)& transport. In this case, &$local_part$&
  contains the local part of the address (as usual), and the command that is run
  is specified by the &%command%& option on the transport.
  .next
  contains the local part of the address (as usual), and the command that is run
  is specified by the &%command%& option on the transport.
  .next
-.new
  .cindex "&$pipe_addresses$&"
  If the &%batch_max%& option is set greater than 1 (the default is 1), the
  transport can handle more than one address in a single run. In this case, when
  .cindex "&$pipe_addresses$&"
  If the &%batch_max%& option is set greater than 1 (the default is 1), the
  transport can handle more than one address in a single run. In this case, when
@@ -19941,7 +20236,6 @@ pipe command, and the &%command%& option on the transport is ignored. If only
  one address is being transported (&%batch_max%& is not greater than one, or
  only one address was redirected to this pipe command), &$local_part$& contains
  the local part that was redirected.
  one address is being transported (&%batch_max%& is not greater than one, or
  only one address was redirected to this pipe command), &$local_part$& contains
  the local part that was redirected.
-.wen
  .endlist
  
  
  .endlist
  
  
@@ -19954,8 +20248,8 @@ In the case when &(pipe)& is run as a consequence of an entry in a local user's
  other cases, the uid and gid have to be specified explicitly, either on the
  transport or on the router that handles the address. Current and &"home"&
  directories are also controllable. See chapter &<<CHAPenvironment>>& for
  other cases, the uid and gid have to be specified explicitly, either on the
  transport or on the router that handles the address. Current and &"home"&
  directories are also controllable. See chapter &<<CHAPenvironment>>& for
-details of the local delivery environment &new("and chapter &<<CHAPbatching>>&
-for a discussion of local delivery batching.")
+details of the local delivery environment and chapter &<<CHAPbatching>>&
+for a discussion of local delivery batching.
  
  
  .section "Concurrent delivery"
  
  
  .section "Concurrent delivery"
@@ -20519,6 +20813,17 @@ that are in force when the &%helo_data%&, &%hosts_try_auth%&, &%interface%&,
  The private options of the &(smtp)& transport are as follows:
  
  
  The private options of the &(smtp)& transport are as follows:
  
  
+.new
+.option address_retry_include_sender smtp boolean true
+.cindex "4&'xx'& responses" "retrying after"
+When an address is delayed because of a 4&'xx'& response to a RCPT command, it
+is the combination of sender and recipient that is delayed in subsequent queue
+runs until the retry time is reached. You can delay the recipient without
+reference to the sender (which is what earlier versions of Exim did), by
+setting &%address_retry_include_sender%& false. However, this can lead to
+problems with servers that regularly issue 4&'xx'& responses to RCPT commands.
+.wen
+
  .option allow_localhost smtp boolean false
  .cindex "local host" "sending to"
  .cindex "fallback" "hosts specified on transport"
  .option allow_localhost smtp boolean false
  .cindex "local host" "sending to"
  .cindex "fallback" "hosts specified on transport"
@@ -20685,12 +20990,10 @@ it may also consult other sources of information such as &_/etc/hosts_&.
  .cindex "HELO argument" "setting"
  .cindex "EHLO argument" "setting"
  .cindex "LHLO argument" "setting"
  .cindex "HELO argument" "setting"
  .cindex "EHLO argument" "setting"
  .cindex "LHLO argument" "setting"
-.new
  The value of this option is expanded, and used as the argument for the EHLO,
  HELO, or LHLO command that starts the outgoing SMTP or LMTP session. The
  variables &$host$& and &$host_address$& are set to the identity of the remote
  host, and can be used to generate different values for different servers.
  The value of this option is expanded, and used as the argument for the EHLO,
  HELO, or LHLO command that starts the outgoing SMTP or LMTP session. The
  variables &$host$& and &$host_address$& are set to the identity of the remote
  host, and can be used to generate different values for different servers.
-.wen
  
  .option hosts smtp "string list&!!" unset
  Hosts are associated with an address by a router such as &(dnslookup)&, which
  
  .option hosts smtp "string list&!!" unset
  Hosts are associated with an address by a router such as &(dnslookup)&, which
@@ -20826,18 +21129,26 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter
  &<<CHAPSMTPAUTH>>& for details of authentication.
  
  .option interface smtp "string list&!!" unset
  &<<CHAPSMTPAUTH>>& for details of authentication.
  
  .option interface smtp "string list&!!" unset
+.new
  .cindex "bind IP address"
  .cindex "IP address" "binding"
  .cindex "&$host$&"
  .cindex "&$host_address$&"
  This option specifies which interface to bind to when making an outgoing SMTP
  .cindex "bind IP address"
  .cindex "IP address" "binding"
  .cindex "&$host$&"
  .cindex "&$host_address$&"
  This option specifies which interface to bind to when making an outgoing SMTP
-call. The variables &$host$& and &$host_address$& refer to the host to which a
-connection is about to be made during the expansion of the string. Forced
-expansion failure, or an empty string result causes the option to be ignored.
-Otherwise, after expansion,
-the string must be a list of IP addresses, colon-separated by default, but the
-separator can be changed in the usual way.
-For example:
+call. &*Note:*& Do not confuse this with the interface address that was used
+when a message was received, which is in &$received_ip_address$&, formerly
+known as &$interface_address$&. The name was changed to minimize confusion with
+the outgoing interface address. There is no variable that contains an outgoing
+interface address because, unless it is set by this option, its value is
+unknown.
+.wen
+
+During the expansion of the &%interface%& option the variables &$host$& and
+&$host_address$& refer to the host to which a connection is about to be made
+during the expansion of the string. Forced expansion failure, or an empty
+string result causes the option to be ignored. Otherwise, after expansion, the
+string must be a list of IP addresses, colon-separated by default, but the
+separator can be changed in the usual way. For example:
  .code
  interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
  .endd
  .code
  interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
  .endd
@@ -20885,14 +21196,21 @@ is a single domain involved in a remote delivery.
  
  
  .option port smtp string&!! "see below"
  
  
  .option port smtp string&!! "see below"
+.new
  .cindex "port" "sending TCP/IP"
  .cindex "TCP/IP" "setting outgoing port"
  .cindex "port" "sending TCP/IP"
  .cindex "TCP/IP" "setting outgoing port"
-This option specifies the TCP/IP port on the server to which Exim connects. If
-it begins with a digit it is taken as a port number; otherwise it is looked up
-using &[getservbyname()]&. The default value is normally &"smtp"&, but if
-&%protocol%& is set to &"lmtp"&, the default is &"lmtp"&.
-If the expansion fails, or if a port number cannot be found, delivery is
-deferred.
+This option specifies the TCP/IP port on the server to which Exim connects.
+&*Note:*& Do not confuse this with the port that was used when a message was
+received, which is in &$received_port$&, formerly known as &$interface_port$&.
+The name was changed to minimize confusion with the outgoing port. There is no
+variable that contains an outgoing port.
+.wen
+
+If the value of this option begins with a digit it is taken as a port number;
+otherwise it is looked up using &[getservbyname()]&. The default value is
+normally &"smtp"&, but if &%protocol%& is set to &"lmtp"&, the default is
+&"lmtp"&. If the expansion fails, or if a port number cannot be found, delivery
+is deferred.
  
  
  
  
  
  
@@ -21016,6 +21334,7 @@ ciphers is a preference order.
  
  
  .option tls_tempfail_tryclear smtp boolean true
  
  
  .option tls_tempfail_tryclear smtp boolean true
+.cindex "4&'xx'& responses" "to STARTTLS"
  When the server host is not in &%hosts_require_tls%&, and there is a problem in
  setting up a TLS session, this option determines whether or not Exim should try
  to deliver the message unencrypted. If it is set false, delivery to the
  When the server host is not in &%hosts_require_tls%&, and there is a problem in
  setting up a TLS session, this option determines whether or not Exim should try
  to deliver the message unencrypted. If it is set false, delivery to the
@@ -21158,12 +21477,19 @@ configuration file are applied to addresses in incoming messages, both envelope
  addresses and addresses in header lines. Each rule specifies the types of
  address to which it applies.
  
  addresses and addresses in header lines. Each rule specifies the types of
  address to which it applies.
  
-Rewriting of addresses in header lines applies only to those headers that
-were received with the message, and, in the case of transport rewriting, those
-that were added by a system filter. That is, it applies only to those headers
-that are common to all copies of the message. Header lines that are added by
-individual routers or transports (and which are therefore specific to
-individual recipient addresses) are not rewritten.
+Whether or not addresses in header lines are rewritten depends on the origin of
+the headers and the type of rewriting. Global rewriting, that is, rewriting
+rules from the rewrite section of the configuration file, is applied only to
+those headers that were received with the message. Header lines that are added
+by ACLs or by a system filter or by individual routers or transports (which
+are specific to individual recipient addresses) are not rewritten by the global
+rules.
+
+Rewriting at transport time, by means of the &%headers_rewrite%& option,
+applies all headers except those added by routers and transports. That is, as
+well as the headers that were received with the message, it also applies to
+headers that were added by an ACL or a system filter.
+
  
  In general, rewriting addresses from your own system or domain has some
  legitimacy. Rewriting other addresses should be done only with great care and
  
  In general, rewriting addresses from your own system or domain has some
  legitimacy. Rewriting other addresses should be done only with great care and
@@ -21606,9 +21932,22 @@ suffers a temporary failure, the retry data is updated as normal, and
  subsequent delivery attempts from queue runs occur only when the retry time for
  the local address is reached.
  
  subsequent delivery attempts from queue runs occur only when the retry time for
  the local address is reached.
  
+.section "Changing retry rules"
+If you change the retry rules in your configuration, you should consider
+whether or not to delete the retry data that is stored in Exim's spool area in
+files with names like &_db/retry_&. Deleting any of Exim's hints files is
+always safe; that is why they are called &"hints"&.
+
+The hints retry data contains suggested retry times based on the previous
+rules. In the case of a long-running problem with a remote host, it might
+record the fact that the host has timed out. If your new rules increase the
+timeout time for such a host, you should definitely remove the old retry data
+and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
+messages that it should now be retaining.
+
  
  
  
  
-.section "Retry rules"
+.section "Format of retry rules"
  .cindex "retry" "rules"
  Each retry rule occupies one line and consists of three or four parts,
  separated by white space: a pattern, an error name, an optional list of sender
  .cindex "retry" "rules"
  Each retry rule occupies one line and consists of three or four parts,
  separated by white space: a pattern, an error name, an optional list of sender
@@ -21622,9 +21961,10 @@ message's sender, respectively.
  The pattern is any single item that may appear in an address list (see section
  &<<SECTaddresslist>>&). It is in fact processed as a one-item address list,
  which means that it is expanded before being tested against the address that
  The pattern is any single item that may appear in an address list (see section
  &<<SECTaddresslist>>&). It is in fact processed as a one-item address list,
  which means that it is expanded before being tested against the address that
-has been delayed. Address list processing treats a plain domain name as if it
-were preceded by &"*@"&, which makes it possible for many retry rules to start
-with just a domain. For example,
+has been delayed. A negated address list item is permitted. Address
+list processing treats a plain domain name as if it were preceded by &"*@"&,
+which makes it possible for many retry rules to start with just a domain. For
+example,
  .code
  lookingglass.fict.example        *  F,24h,30m;
  .endd
  .code
  lookingglass.fict.example        *  F,24h,30m;
  .endd
@@ -21663,10 +22003,20 @@ configuration is tested against the complete address only if
  &%retry_use_local_part%& is set for the transport (it defaults true for all
  local transports).
  
  &%retry_use_local_part%& is set for the transport (it defaults true for all
  local transports).
  
+.new
+.cindex "4&'xx'& responses" "retry rules for"
  However, when Exim is looking for a retry rule after a remote delivery attempt
  suffers an address error (a 4&'xx'& SMTP response for a recipient address), the
  whole address is always used as the key when searching the retry rules. The
  However, when Exim is looking for a retry rule after a remote delivery attempt
  suffers an address error (a 4&'xx'& SMTP response for a recipient address), the
  whole address is always used as the key when searching the retry rules. The
-rule that is found is used to create a retry time for the failing address.
+rule that is found is used to create a retry time for the combination of the
+failing address and the message's sender. It is the combination of sender and
+recipient that is delayed in subsequent queue runs until its retry time is
+reached. You can delay the recipient without regard to the sender by setting
+&%address_retry_include_sender%& false in the &(smtp)& transport but this can
+lead to problems with servers that regularly issue 4&'xx'& responses to RCPT
+commands.
+.wen
+
  
  
  .section "Choosing which retry rule to use for host and message errors"
  
  
  .section "Choosing which retry rule to use for host and message errors"
@@ -21994,7 +22344,7 @@ Exim tries a month later, using the old retry data would imply that it had been
  down all the time, which is not a justified assumption.
  
  If a host really is permanently dead, this behaviour causes a burst of retries
  down all the time, which is not a justified assumption.
  
  If a host really is permanently dead, this behaviour causes a burst of retries
-every now and again, but only if messages routed to it are rare. It there is a
+every now and again, but only if messages routed to it are rare. If there is a
  message at least once every 7 days the retry data never expires.
  
  
  message at least once every 7 days the retry data never expires.
  
  
@@ -22052,7 +22402,6 @@ true.
  
  .section "Deliveries that work intermittently"
  .cindex "retry" "intermittently working deliveries"
  
  .section "Deliveries that work intermittently"
  .cindex "retry" "intermittently working deliveries"
-.new
  Some additional logic is needed to cope with cases where a host is
  intermittently available, or when a message has some attribute that prevents
  its delivery when others to the same address get through. In this situation,
  Some additional logic is needed to cope with cases where a host is
  intermittently available, or when a message has some attribute that prevents
  its delivery when others to the same address get through. In this situation,
@@ -22076,7 +22425,6 @@ given address, a delivery is attempted for that address, even if it is not yet
  time, and if this delivery fails, the address is timed out. A new retry time is
  not computed in this case, so that other messages for the same address are
  considered immediately.
  time, and if this delivery fails, the address is timed out. A new retry time is
  not computed in this case, so that other messages for the same address are
  considered immediately.
-.wen
  .ecindex IIDretconf1
  .ecindex IIDregconf2
  
  .ecindex IIDretconf1
  .ecindex IIDregconf2
  
@@ -22222,6 +22570,25 @@ forced, and was not caused by a lookup defer, the incident is logged.
  See section &<<SECTauthexiser>>& below for further discussion.
  
  
  See section &<<SECTauthexiser>>& below for further discussion.
  
  
+.new
+.option server_condition authenticators string&!! unset
+This option must be set for a &%plaintext%& server authenticator, where it
+is used directly to control authentication. See section &<<SECTplainserver>>&
+for details.
+
+For the other authenticators, &%server_condition%& can be used as an additional
+authentication or authorization mechanism that is applied after the other
+authenticator conditions succeed. If it is set, it is expanded when the
+authenticator would otherwise return a success code. If the expansion is forced
+to fail, authentication fails. Any other expansion failure causes a temporary
+error code to be returned. If the result of a successful expansion is an empty
+string, &"0"&, &"no"&, or &"false"&, authentication fails. If the result of the
+expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds. For any
+other result, a temporary error code is returned, with the expanded string as
+the error text.
+.wen
+
+
  .option server_debug_print authenticators string&!! unset
  If this option is set and authentication debugging is enabled (see the &%-d%&
  command line option), the string is expanded and included in the debugging
  .option server_debug_print authenticators string&!! unset
  If this option is set and authentication debugging is enabled (see the &%-d%&
  command line option), the string is expanded and included in the debugging
@@ -22501,32 +22868,36 @@ security risk; you are strongly advised to insist on the use of SMTP encryption
  use unencrypted plain text, you should not use the same passwords for SMTP
  connections as you do for login accounts.
  
  use unencrypted plain text, you should not use the same passwords for SMTP
  connections as you do for login accounts.
  
-.section "Using plaintext in a server"
+.new
+.section "Plaintext options"
  .cindex "options" "&(plaintext)& authenticator (server)"
  .cindex "options" "&(plaintext)& authenticator (server)"
-When running as a server, &(plaintext)& performs the authentication test by
-expanding a string. It has the following options:
+When configured as a server, &(plaintext)& uses the following options:
+
+.option server_condition authenticators string&!! unset
+This is actually a global authentication option, but it must be set in order to
+configure the &(plaintext)& driver as a server. Its use is described below.
+.wen
  
  .option server_prompts plaintext string&!! unset
  The contents of this option, after expansion, must be a colon-separated list of
  prompt strings. If expansion fails, a temporary authentication rejection is
  given.
  
  
  .option server_prompts plaintext string&!! unset
  The contents of this option, after expansion, must be a colon-separated list of
  prompt strings. If expansion fails, a temporary authentication rejection is
  given.
  
-.option server_condition plaintext string&!! unset
-This option must be set in order to configure the driver as a server. Its use
-is described below.
-
+.section "Using plaintext in a server" "SECTplainserver"
  .cindex "AUTH" "in &(plaintext)& authenticator"
  .cindex "binary zero" "in &(plaintext)& authenticator"
  .cindex "numerical variables (&$1$& &$2$& etc)" &&&
          "in &(plaintext)& authenticator"
  .cindex "&$auth1$&, &$auth2$&, etc"
  .cindex "base64 encoding" "in &(plaintext)& authenticator"
  .cindex "AUTH" "in &(plaintext)& authenticator"
  .cindex "binary zero" "in &(plaintext)& authenticator"
  .cindex "numerical variables (&$1$& &$2$& etc)" &&&
          "in &(plaintext)& authenticator"
  .cindex "&$auth1$&, &$auth2$&, etc"
  .cindex "base64 encoding" "in &(plaintext)& authenticator"
-The data sent by the client with the AUTH command, or in response to
-subsequent prompts, is base64 encoded, and so may contain any byte values
-when decoded. If any data is supplied with the command, it is treated as a
-list of strings, separated by NULs (binary zeros), the first three of which are
-placed in the expansion variables &$auth1$&, &$auth2$&, and &$auth3$& (neither
-LOGIN nor PLAIN uses more than three strings).
+
+When running as a server, &(plaintext)& performs the authentication test by
+expanding a string. The data sent by the client with the AUTH command, or in
+response to subsequent prompts, is base64 encoded, and so may contain any byte
+values when decoded. If any data is supplied with the command, it is treated as
+a list of strings, separated by NULs (binary zeros), the first three of which
+are placed in the expansion variables &$auth1$&, &$auth2$&, and &$auth3$&
+(neither LOGIN nor PLAIN uses more than three strings).
  
  For compatibility with previous releases of Exim, the values are also placed in
  the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these
  
  For compatibility with previous releases of Exim, the values are also placed in
  the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these
@@ -22572,10 +22943,14 @@ fixed_plain:
    public_name = PLAIN
    server_prompts = :
    server_condition = \
    public_name = PLAIN
    server_prompts = :
    server_condition = \
-    ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}\
-      {yes}{no}}
+    ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
    server_set_id = $auth2
  .endd
    server_set_id = $auth2
  .endd
+Note that the default result strings from &%if%& (&"true"& or an empty string)
+are exactly what we want here, so they need not be specified. Obviously, if the
+password contains expansion-significant characters such as dollar, backslash,
+or closing brace, they have to be escaped.
+
  The &%server_prompts%& setting specifies a single, empty prompt (empty items at
  the end of a string list are ignored). If all the data comes as part of the
  AUTH command, as is commonly the case, the prompt is not used. This
  The &%server_prompts%& setting specifies a single, empty prompt (empty items at
  the end of a string list are ignored). If all the data comes as part of the
  AUTH command, as is commonly the case, the prompt is not used. This
@@ -22612,7 +22987,7 @@ this approach, where the passwords are looked up in a DBM file. &*Warning*&:
  This is an incorrect example:
  .code
  server_condition = \
  This is an incorrect example:
  .code
  server_condition = \
-  ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}{yes}{no}}
+  ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
  .endd
  The expansion uses the user name (&$auth2$&) as the key to look up a password,
  which it then compares to the supplied password (&$auth3$&). Why is this example
  .endd
  The expansion uses the user name (&$auth2$&) as the key to look up a password,
  which it then compares to the supplied password (&$auth3$&). Why is this example
@@ -22623,14 +22998,13 @@ the authentication, all a client has to do is to supply a non-existent user
  name and an empty password. The correct way of writing this test is:
  .code
  server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
  name and an empty password. The correct way of writing this test is:
  .code
  server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
-  {${if eq{$value}{$auth3}{yes}{no}}}{no}}
+  {${if eq{$value}{$auth3}}} {false}}
  .endd
  In this case, if the lookup succeeds, the result is checked; if the lookup
  .endd
  In this case, if the lookup succeeds, the result is checked; if the lookup
-fails, authentication fails. If &%crypteq%& is being used instead of &%eq%&,
-the first example is in fact safe, because &%crypteq%& always fails if its
-second argument is empty. However, the second way of writing the test makes the
-logic clearer.
-
+fails, &"false"& is returned and authentication fails. If &%crypteq%& is being
+used instead of &%eq%&, the first example is in fact safe, because &%crypteq%&
+always fails if its second argument is empty. However, the second way of
+writing the test makes the logic clearer.
  
  
  .section "The LOGIN authentication mechanism"
  
  
  .section "The LOGIN authentication mechanism"
@@ -22646,8 +23020,7 @@ fixed_login:
    public_name = LOGIN
    server_prompts = User Name : Password
    server_condition = \
    public_name = LOGIN
    server_prompts = User Name : Password
    server_condition = \
-    ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}\
-      {yes}{no}}
+    ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
    server_set_id = $auth1
  .endd
  Because of the way plaintext operates, this authenticator accepts data supplied
    server_set_id = $auth1
  .endd
  Because of the way plaintext operates, this authenticator accepts data supplied
@@ -22668,7 +23041,7 @@ login:
    server_condition = ${if ldapauth \
      {user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
      pass=${quote:$auth2} \
    server_condition = ${if ldapauth \
      {user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
      pass=${quote:$auth2} \
-    ldap://ldap.example.org/}{yes}{no}}
+    ldap://ldap.example.org/}}
    server_set_id = uid=$auth1,ou=people,o=example.org
  .endd
  Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for
    server_set_id = uid=$auth1,ou=people,o=example.org
  .endd
  Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for
@@ -22855,6 +23228,7 @@ fixed_cram:
  .scindex IIDcyrauth1 "&(cyrus_sasl)& authenticator"
  .scindex IIDcyrauth2 "authenticators" "&(cyrus_sasl)&"
  .cindex "Cyrus" "SASL library"
  .scindex IIDcyrauth1 "&(cyrus_sasl)& authenticator"
  .scindex IIDcyrauth2 "authenticators" "&(cyrus_sasl)&"
  .cindex "Cyrus" "SASL library"
+.cindex "Kerberos"
  The code for this authenticator was provided by Matthew Byng-Maddick of A L
  Digital Ltd (&url(http://www.aldigital.co.uk)).
  
  The code for this authenticator was provided by Matthew Byng-Maddick of A L
  Digital Ltd (&url(http://www.aldigital.co.uk)).
  
@@ -22875,6 +23249,18 @@ user, and that the Cyrus SASL library has no way of escalating privileges
  by default. You may also find you need to set environment variables,
  depending on the driver you are using.
  
  by default. You may also find you need to set environment variables,
  depending on the driver you are using.
  
+.new
+The application name provided by Exim is &"exim"&, so various SASL options may
+be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for
+Kerberos, note that because of limitations in the GSSAPI interface,
+changing the server keytab might need to be communicated down to the Kerberos
+layer independently. The mechanism for doing so is dependent upon the Kerberos
+implementation. For example, for Heimdal, the environment variable KRB5_KTNAME
+may be set to point to an alternative keytab file. Exim will pass this
+variable through from its own inherited environment when started as root or the
+Exim user. The keytab file needs to be readable by the Exim user.
+.wen
+
  
  .section "Using cyrus_sasl as a server"
  The &(cyrus_sasl)& authenticator has four private options. It puts the username
  
  .section "Using cyrus_sasl as a server"
  The &(cyrus_sasl)& authenticator has four private options. It puts the username
@@ -22935,6 +23321,47 @@ but it is present in many binary distributions.
  
  
  
  
  
  
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+.new
+.chapter "The dovecot authenticator" "CHAPdovecot"
+.scindex IIDdcotauth1 "&(dovecot)& authenticator"
+.scindex IIDdcotauth2 "authenticators" "&(dovecot)&"
+This authenticator is an interface to the authentication facility of the
+Dovecot POP/IMAP server, which can support a number of authentication methods.
+If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
+to use the same mechanisms for SMTP authentication. This is a server
+authenticator only. There is only one option:
+
+.option server_socket dovecot string unset
+
+This option must specify the socket that is the interface to Dovecot
+authentication. The &%public_name%& option must specify an authentication
+mechanism that Dovecot is configured to support. You can have several
+authenticators for different mechanisms. For example:
+.code
+dovecot_plain:
+  driver = dovecot
+  public_name = PLAIN
+  server_socket = /var/run/dovecot/auth-client
+  server_setid = $auth1
+
+dovecot_ntlm:
+  driver = dovecot
+  public_name = NTLM
+  server_socket = /var/run/dovecot/auth-client
+  server_setid = $auth1
+.endd
+If the SMTP connection is encrypted, or if &$sender_host_address$& is equal to
+&$received_ip_address$& (that is, the connection is local), the &"secured"&
+option is passed in the Dovecot authentication command. If, for a TLS
+connection, a client certificate has been verified, the &"valid-client-cert"&
+option is passed.
+.ecindex IIDdcotauth1
+.ecindex IIDdcotauth2
+.wen
+
+
  . ////////////////////////////////////////////////////////////////////////////
  . ////////////////////////////////////////////////////////////////////////////
  
  . ////////////////////////////////////////////////////////////////////////////
  . ////////////////////////////////////////////////////////////////////////////
  
@@ -23141,8 +23568,8 @@ sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&.
  
  
  .section "GnuTLS parameter computation"
  
  
  .section "GnuTLS parameter computation"
-GnuTLS uses RSA and D-H parameters that take a substantial amount of time to
-compute. It is unreasonable to re-compute them for every TLS session.
+GnuTLS uses RSA and D-H parameters that may take a substantial amount of time
+to compute. It is unreasonable to re-compute them for every TLS session.
  Therefore, Exim keeps this data in a file in its spool directory, called
  &_gnutls-params_&. The file is owned by the Exim user and is readable only by
  its owner. Every Exim process that start up GnuTLS reads the RSA and D-H
  Therefore, Exim keeps this data in a file in its spool directory, called
  &_gnutls-params_&. The file is owned by the Exim user and is readable only by
  its owner. Every Exim process that start up GnuTLS reads the RSA and D-H
@@ -23652,7 +24079,7 @@ options in the main part of the configuration. These options are:
  .cindex "STARTTLS" "ACL for"
  .cindex "VRFY" "ACL for"
  .cindex "SMTP connection" "ACL for"
  .cindex "STARTTLS" "ACL for"
  .cindex "VRFY" "ACL for"
  .cindex "SMTP connection" "ACL for"
-.cindex "non-smtp message" "ACL for"
+.cindex "non-smtp message" "ACLs for"
  .cindex "MIME parts" "ACL for"
  
  .table2 140pt
  .cindex "MIME parts" "ACL for"
  
  .table2 140pt
@@ -23688,22 +24115,67 @@ trying to deliver the message. It is therefore recommended that you do as much
  testing as possible at RCPT time.
  
  
  testing as possible at RCPT time.
  
  
-.section "The non-SMTP ACL"
-.cindex "non-smtp message" "ACL for"
-The non-SMTP ACL applies to all non-interactive incoming messages, that is, it
-applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not
-really SMTP.) This ACL is run just before the &[local_scan()]& function. Any
+.section "The non-SMTP ACLs"
+.cindex "non-smtp message" "ACLs for"
+The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
+apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
+really SMTP.) Many of the ACL conditions (for example, host tests, and tests on
+the state of the SMTP connection such as encryption and authentication) are not
+relevant and are forbidden in these ACLs. However, the sender and recipients
+are known, so the &%senders%& and &%sender_domains%& conditions and the
+&$sender_address$& and &$recipients$& variables can be used. Variables such as
+&$authenticated_sender$& are also available. You can specify added header lines
+in any of these ACLs.
+
+The &%acl_not_smtp_start%& ACL is run right at the start of receiving a
+non-SMTP message, before any of the message has been read. (This is the
+analogue of the &%acl_smtp_predata%& ACL for SMTP input.) The result of this
+ACL is ignored; it cannot be used to reject a message. If you really need to,
+you could set a value in an ACL variable here and reject based on that in the
+&%acl_not_smtp%& ACL. However, this ACL can be used to set controls, and in
+particular, it can be used to set
+.code
+control = suppress_local_fixups
+.endd
+This cannot be used in the other non-SMTP ACLs because by the time they are
+run, it is too late.
+
+The &%acl_not_smtp_mime%& ACL is available only when Exim is compiled with the
+content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
+
+The &%acl_not_smtp%& ACL is run just before the &[local_scan()]& function. Any
  kind of rejection is treated as permanent, because there is no way of sending a
  kind of rejection is treated as permanent, because there is no way of sending a
-temporary error for these kinds of message. Many of the ACL conditions (for
-example, host tests, and tests on the state of the SMTP connection such as
-encryption and authentication) are not relevant and are forbidden in this ACL.
+temporary error for these kinds of message.
  
  
  
  
-.section "The connect ACL"
+.section "The SMTP connect ACL"
+.new
  .cindex "SMTP connection" "ACL for"
  .cindex "SMTP connection" "ACL for"
-The ACL test specified by &%acl_smtp_connect%& happens after the test specified
-by &%host_reject_connection%& (which is now an anomaly) and any TCP Wrappers
-testing (if configured).
+.cindex &%smtp_banner%&
+The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP
+session, after the test specified by &%host_reject_connection%& (which is now
+an anomaly) and any TCP Wrappers testing (if configured). If the connection is
+accepted by an &%accept%& verb that has a &%message%& modifier, the contents of
+the message override the banner message that is otherwise specified by the
+&%smtp_banner%& option.
+
+
+.section "The EHLO/HELO ACL"
+.cindex "EHLO" "ACL for"
+.cindex "HELO" "ACL for"
+The ACL test specified by &%acl_smtp_helo%& happens when the client issues an
+EHLO or HELO command, after the tests specified by &%helo_accept_junk_hosts%&,
+&%helo_allow_chars%&, &%helo_verify_hosts%&, and &%helo_try_verify_hosts%&.
+Note that a client may issue more than one EHLO or HELO command in an SMTP
+session, and indeed is required to issue a new EHLO or HELO after successfully
+setting up encryption following a STARTTLS command.
+
+If the command is accepted by an &%accept%& verb that has a &%message%&
+modifier, the message may not contain more than one line (it will be truncated
+at the first newline and a panic logged if it does). Such a message cannot
+affect the EHLO options that are listed on the second and subsequent lines of
+an EHLO response.
+.wen
  
  
  .section "The DATA ACLs"
  
  
  .section "The DATA ACLs"
@@ -23732,7 +24204,7 @@ and try again later, but that is their problem, though it does waste some of
  your resources.
  
  
  your resources.
  
  
-.section "The MIME ACL"
+.section "The SMTP MIME ACL"
  The &%acl_smtp_mime%& option is available only when Exim is compiled with the
  content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
  
  The &%acl_smtp_mime%& option is available only when Exim is compiled with the
  content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
  
@@ -23858,10 +24330,14 @@ all the same. &*Note*&: These defaults apply only when the relevant ACL is
  not defined at all. For any defined ACL, the default action when control
  reaches the end of the ACL statements is &"deny"&.
  
  not defined at all. For any defined ACL, the default action when control
  reaches the end of the ACL statements is &"deny"&.
  
+For &%acl_smtp_quit%& and &%acl_not_smtp_start%& there is no default because
+these two are ACLs that are used only for their side effects. They cannot be
+used to accept or reject anything.
+
  For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&,
  &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&,
  For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&,
  &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&,
-&%acl_smtp_mime%&, &%acl_smtp_predata%&, &%acl_smtp_quit%&, and
-&%acl_smtp_starttls%&, the action when the ACL is not defined is &"accept"&.
+&%acl_smtp_mime%&, &%acl_smtp_predata%&, and &%acl_smtp_starttls%&, the action
+when the ACL is not defined is &"accept"&.
  
  For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and
  &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&.
  
  For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and
  &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&.
@@ -23982,14 +24458,43 @@ the command is accepted if verification succeeds. However, if verification
  fails, the ACL yields &"deny"&, because the failing condition is after
  &%endpass%&.
  
  fails, the ACL yields &"deny"&, because the failing condition is after
  &%endpass%&.
  
+.new
+The &%endpass%& feature has turned out to be confusing to many people, so its
+use is not recommended nowadays. It is always possible to rewrite an ACL so
+that &%endpass%& is not needed, and it is no longer used in the default
+configuration.
+
+.cindex "&%message%&" "ACL modifier, with &%accept%&"
+If a &%message%& modifier appears on an &%accept%& statement, its action
+depends on whether or not &%endpass%& is present. In the absence of &%endpass%&
+(when an &%accept%& verb either accepts or passes control to the next
+statement), &%message%& can be used to vary the message that is sent when an
+SMTP command is accepted. For example, in a RCPT ACL you could have:
+.display
+&`accept  `&<&'some conditions'&>
+&`        message = OK, I'll allow you through today`&
+.endd
+You can specify an SMTP response code, optionally followed by an &"extended
+response code"& at the start of the message, but the first digit must be the
+same as would be sent by default, which is 2 for an &%accept%& verb.
+
+If &%endpass%& is present in an &%accept%& statement, &%message%& specifies
+an error message that is used when access is denied. This behaviour is retained
+for backward compatibility, but current &"best practice"& is to avoid the use
+of &%endpass%&.
+.wen
+
+
  .next
  .cindex "&%defer%&" "ACL verb"
  .next
  .cindex "&%defer%&" "ACL verb"
-&%defer%&: If all the conditions are met, the ACL returns &"defer"& which, in
+&%defer%&: If all the conditions are true, the ACL returns &"defer"& which, in
  an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL,
  &%defer%& is the same as &%deny%&, because there is no way of sending a
  temporary error. For a RCPT command, &%defer%& is much the same as using a
  &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can
  be used in any ACL, and even for a recipient it might be a simpler approach.
  an SMTP session, causes a 4&'xx'& response to be given. For a non-SMTP ACL,
  &%defer%& is the same as &%deny%&, because there is no way of sending a
  temporary error. For a RCPT command, &%defer%& is much the same as using a
  &(redirect)& router and &`:defer:`& while verifying, but the &%defer%& verb can
  be used in any ACL, and even for a recipient it might be a simpler approach.
+
+
  .next
  .cindex "&%deny%&" "ACL verb"
  &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of
  .next
  .cindex "&%deny%&" "ACL verb"
  &%deny%&: If all the conditions are met, the ACL returns &"deny"&. If any of
@@ -24000,19 +24505,25 @@ deny dnslists = blackholes.mail-abuse.org
  .endd
  rejects commands from hosts that are on a DNS black list.
  
  .endd
  rejects commands from hosts that are on a DNS black list.
  
+
  .next
  .next
+.new
  .cindex "&%discard%&" "ACL verb"
  &%discard%&: This verb behaves like &%accept%&, except that it returns
  &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs
  .cindex "&%discard%&" "ACL verb"
  &%discard%&: This verb behaves like &%accept%&, except that it returns
  &"discard"& from the ACL instead of &"accept"&. It is permitted only on ACLs
-that are concerned with receiving messages, and it causes recipients to be
-discarded. If the &%log_message%& modifier is set when &%discard%& operates,
+that are concerned with receiving messages. When all the conditions are true,
+the sending entity receives a &"success"& response. However, &%discard%& causes
+recipients to be discarded. If it is used in an ACL for RCPT, just the one
+recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the
+message's recipients are discarded. Recipients that are discarded before DATA
+do not appear in the log line when the &%log_recipients%& log selector is set.
+
+If the &%log_message%& modifier is set when &%discard%& operates,
  its contents are added to the line that is automatically written to the log.
  its contents are added to the line that is automatically written to the log.
+The &%message%& modifier operates exactly as it does for &%accept%&.
+.wen
+
  
  
-If &%discard%& is used in an ACL for RCPT, just the one recipient is
-discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the
-message's recipients are discarded. Recipients that are discarded before
-DATA do not appear in the log line when the &%log_recipients%& log selector
-is set.
  .next
  .cindex "&%drop%&" "ACL verb"
  &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is
  .next
  .cindex "&%drop%&" "ACL verb"
  &%drop%&: This verb behaves like &%deny%&, except that an SMTP connection is
@@ -24037,28 +24548,27 @@ verified. Otherwise, it rejects the command.
  
  .next
  .cindex "&%warn%&" "ACL verb"
  
  .next
  .cindex "&%warn%&" "ACL verb"
-&%warn%&: If all the conditions are met, a header line is added to an incoming
-message and/or a line is written to Exim's main log. In all cases, control
-passes to the next ACL statement. The text of the added header line and the log
-line are specified by modifiers; if they are not present, a &%warn%& verb just
-checks its conditions and obeys any &"immediate"& modifiers such as &%set%& and
-&%logwrite%&. There is more about adding header lines in section
+&%warn%&: If all the conditions are true, a line specified by the
+&%log_message%& modifier is written to Exim's main log. Control always passes
+to the next ACL statement. If any condition is false, the log line is not
+written. If an identical log line is requested several times in the same
+message, only one copy is actually written to the log. If you want to force
+duplicates to be written, use the &%logwrite%& modifier instead.
+
+If &%log_message%& is not present, a &%warn%& verb just checks its conditions
+and obeys any &"immediate"& modifiers (such as &%control%&, &%set%&,
+&%logwrite%&, and &%add_header%&) that appear before the first failing
+condition. There is more about adding header lines in section
  &<<SECTaddheadacl>>&.
  
  If any condition on a &%warn%& statement cannot be completed (that is, there is
  &<<SECTaddheadacl>>&.
  
  If any condition on a &%warn%& statement cannot be completed (that is, there is
-some sort of defer), no header lines are added and the configured log line is
-not written. No further conditions or modifiers in the &%warn%& statement are
-processed. The incident is logged, but the ACL continues to be processed, from
-the next statement onwards.
-
-If a &%message%& modifier is present on a &%warn%& verb in an ACL that is not
-testing an incoming message, it is ignored, and the incident is logged.
+some sort of defer), the log line specified by &%log_message%& is not written.
+&new("This does not include the case of a forced failure from a lookup, which
+is considered to be a successful completion. After a defer,") no further
+conditions or modifiers in the &%warn%& statement are processed. The incident
+is logged, and the ACL continues to be processed, from the next statement
+onwards.
  
  
-A &%warn%& statement may use the &%log_message%& modifier to cause a line to be
-written to the main log when the statement's conditions are true.
-If an identical log line is requested several times in the same message, only
-one copy is actually written to the log. If you want to force duplicates to be
-written, use the &%logwrite%& modifier instead.
  
  .cindex "&$acl_verify_message$&"
  When one of the &%warn%& conditions is an address verification that fails, the
  
  .cindex "&$acl_verify_message$&"
  When one of the &%warn%& conditions is an address verification that fails, the
@@ -24081,35 +24591,49 @@ mechanism. It is conventional to align the conditions vertically.
  
  
  .section "ACL variables" "SECTaclvariables"
  
  
  .section "ACL variables" "SECTaclvariables"
+.new
  .cindex "&ACL;" "variables"
  There are some special variables that can be set during ACL processing. They
  can be used to pass information between different ACLs, different invocations
  of the same ACL in the same SMTP connection, and between ACLs and the routers,
  .cindex "&ACL;" "variables"
  There are some special variables that can be set during ACL processing. They
  can be used to pass information between different ACLs, different invocations
  of the same ACL in the same SMTP connection, and between ACLs and the routers,
-transports, and filters that are used to deliver a message. There are two sets
-of these variables:
-
+transports, and filters that are used to deliver a message. The names of these
+variables must begin with &$acl_c$& or &$acl_m$&, followed either by a digit or
+an underscore, but the remainder of the name can be any sequence of
+alphanumeric characters and underscores that you choose. There is no limit on
+the number of ACL variables. The two sets act as follows:
  .ilist
  .ilist
-The values of &$acl_c0$& to &$acl_c19$& persist throughout an SMTP
-connection. They are never reset. Thus, a value that is set while receiving one
-message is still available when receiving the next message on the same SMTP
-connection.
-.next
-The values of &$acl_m0$& to &$acl_m19$& persist only while a message is
-being received. They are reset afterwards. They are also reset by MAIL, RSET,
-EHLO, HELO, and after starting up a TLS session.
+The values of those variables whose names begin with &$acl_c$& persist
+throughout an SMTP connection. They are never reset. Thus, a value that is set
+while receiving one message is still available when receiving the next message
+on the same SMTP connection.
+.next
+The values of those variables whose names beging with &$acl_m$& persist only
+while a message is being received. They are reset afterwards. They are also
+reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.
  .endlist
  
  When a message is accepted, the current values of all the ACL variables are
  preserved with the message and are subsequently made available at delivery
  .endlist
  
  When a message is accepted, the current values of all the ACL variables are
  preserved with the message and are subsequently made available at delivery
-time. The ACL variables are set by modifier called &%set%&. For example:
+time. The ACL variables are set by a modifier called &%set%&. For example:
  .code
  accept hosts = whatever
         set acl_m4 = some value
  .code
  accept hosts = whatever
         set acl_m4 = some value
+accept authenticated = *
+       set acl_c_auth = yes
  .endd
  &*Note*&: A leading dollar sign is not used when naming a variable that is to
  be set. If you want to set a variable without taking any action, you can use a
  &%warn%& verb without any other modifiers or conditions.
  
  .endd
  &*Note*&: A leading dollar sign is not used when naming a variable that is to
  be set. If you want to set a variable without taking any action, you can use a
  &%warn%& verb without any other modifiers or conditions.
  
+.oindex &%strict_acl_vars%&
+What happens if a syntactically valid but undefined ACL variable is
+referenced depends on the setting of the &%strict_acl_vars%& option. If it is
+false (the default), an empty string is substituted; if it is true, an
+error is generated.
+
+Versions of Exim before 4.64 have a limited set of numbered variables, but
+their names are compatible, so there is no problem with upgrading.
+.wen
  
  
  .section "Condition and modifier processing"
  
  
  .section "Condition and modifier processing"
@@ -24192,7 +24716,7 @@ The ACL modifiers are as follows:
  
  .vlist
  .vitem &*add_header*&&~=&~<&'text'&>
  
  .vlist
  .vitem &*add_header*&&~=&~<&'text'&>
-This modifier specifies one of more header lines that are to be added to an
+This modifier specifies one or more header lines that are to be added to an
  incoming message, assuming, of course, that the message is ultimately
  accepted. For details, see section &<<SECTaddheadacl>>&.
  
  incoming message, assuming, of course, that the message is ultimately
  accepted. For details, see section &<<SECTaddheadacl>>&.
  
@@ -24284,12 +24808,17 @@ warn    ...some conditions...
  accept  ...
  .endd
  
  accept  ...
  .endd
  
+.new
  .vitem &*endpass*&
  .cindex "&%endpass%&" "ACL modifier"
  .vitem &*endpass*&
  .cindex "&%endpass%&" "ACL modifier"
-This modifier, which has no argument, is recognized only in &%accept%&
-statements. It marks the boundary between the conditions whose failure causes
-control to pass to the next statement, and the conditions whose failure causes
-the ACL to return &"deny"&. See the description of &%accept%& above.
+This modifier, which has no argument, is recognized only in &%accept%& and
+&%discard%& statements. It marks the boundary between the conditions whose
+failure causes control to pass to the next statement, and the conditions whose
+failure causes the ACL to return &"deny"&. This concept has proved to be
+confusing to some people, so the use of &%endpass%& is no longer recommended as
+&"best practice"&. See the description of &%accept%& above for more details.
+.wen
+
  
  .vitem &*log_message*&&~=&~<&'text'&>
  .cindex "&%log_message%&" "ACL modifier"
  
  .vitem &*log_message*&&~=&~<&'text'&>
  .cindex "&%log_message%&" "ACL modifier"
@@ -24299,15 +24828,26 @@ ACL denies access or a &%warn%& statement's conditions are true. For example:
  require log_message = wrong cipher suite $tls_cipher
          encrypted   = DES-CBC3-SHA
  .endd
  require log_message = wrong cipher suite $tls_cipher
          encrypted   = DES-CBC3-SHA
  .endd
-&%log_message%& adds to any underlying error message that may exist because of
-the condition failure. For example, while verifying a recipient address, a
-&':fail:'& redirection might have already set up a message. Although the
-message is usually defined before the conditions to which it applies, the
-expansion does not happen until Exim decides that access is to be denied. This
-means that any variables that are set by the condition are available for
-inclusion in the message. For example, the &$dnslist_$&<&'xxx'&> variables are
-set after a DNS black list lookup succeeds. If the expansion of &%log_message%&
-fails, or if the result is an empty string, the modifier is ignored.
+.new
+&%log_message%& is also used when recipients are discarded by &%discard%&. For
+example:
+.display
+&`discard `&<&'some conditions'&>
+&`        log_message = Discarded $local_part@$domain because...`&
+.endd
+When access is denied, &%log_message%& adds to any underlying error message
+that may exist because of a condition failure. For example, while verifying a
+recipient address, a &':fail:'& redirection might have already set up a
+message.
+
+The message may be defined before the conditions to which it applies, because
+the string expansion does not happen until Exim decides that access is to be
+denied. This means that any variables that are set by the condition are
+available for inclusion in the message. For example, the &$dnslist_$&<&'xxx'&>
+variables are set after a DNS black list lookup succeeds. If the expansion of
+&%log_message%& fails, or if the result is an empty string, the modifier is
+ignored.
+.wen
  
  .cindex "&$acl_verify_message$&"
  If you want to use a &%warn%& statement to log the result of an address
  
  .cindex "&$acl_verify_message$&"
  If you want to use a &%warn%& statement to log the result of an address
@@ -24328,13 +24868,33 @@ logging contains newlines, only the first line is logged. In the absence of
  both &%log_message%& and &%message%&, a default built-in message is used for
  logging rejections.
  
  both &%log_message%& and &%message%&, a default built-in message is used for
  logging rejections.
  
+
+.new
+.vitem "&*log_reject_target*&&~=&~<&'log name list'&>"
+.cindex "&%log_reject_target%&" "ACL modifier"
+.cindex "logging in ACL" "specifying which log"
+This modifier makes it possible to specify which logs are used for messages
+about ACL rejections. Its argument is a colon-separated list of words that can
+be &"main"&, &"reject"&, or &"panic"&. The default is &`main:reject`&. The list
+may be empty, in which case a rejection is not logged at all. For example, this
+ACL fragment writes no logging information when access is denied:
+.display
+&`deny `&<&'some conditions'&>
+&`     log_reject_target =`&
+.endd
+This modifier can be used in SMTP and non-SMTP ACLs. It applies to both
+permanent and temporary rejections.
+.wen
+
+
  .vitem &*logwrite*&&~=&~<&'text'&>
  .cindex "&%logwrite%&" "ACL modifier"
  .cindex "logging in ACL" "immediate"
  This modifier writes a message to a log file as soon as it is encountered when
  processing an ACL. (Compare &%log_message%&, which, except in the case of
  .vitem &*logwrite*&&~=&~<&'text'&>
  .cindex "&%logwrite%&" "ACL modifier"
  .cindex "logging in ACL" "immediate"
  This modifier writes a message to a log file as soon as it is encountered when
  processing an ACL. (Compare &%log_message%&, which, except in the case of
-&%warn%&, is used only if the ACL statement denies access.) The &%logwrite%&
-modifier can be used to log special incidents in ACLs. For example:
+&%warn%& &new("and &%discard%&"), is used only if the ACL statement denies
+access.) The &%logwrite%& modifier can be used to log special incidents in
+ACLs. For example:
  .display
  &`accept `&<&'some special conditions'&>
  &`       control  = freeze`&
  .display
  &`accept `&<&'some special conditions'&>
  &`       control  = freeze`&
@@ -24349,20 +24909,59 @@ logwrite = :main,reject: text for main and reject logs
  logwrite = :panic: text for panic log only
  .endd
  
  logwrite = :panic: text for panic log only
  .endd
  
+
  .vitem &*message*&&~=&~<&'text'&>
  .vitem &*message*&&~=&~<&'text'&>
+.new
  .cindex "&%message%&" "ACL modifier"
  .cindex "&%message%&" "ACL modifier"
-This modifier sets up a text string that is expanded and used as an error
-message if the current statement causes the ACL to deny access. The expansion
-happens at the time Exim decides that access is to be denied, not at the time
-it processes &%message%&. If the expansion fails, or generates an empty string,
-the modifier is ignored. For ACLs that are triggered by SMTP commands, the
-message is returned as part of the SMTP error response.
-
-The text is literal; any quotes are taken as literals, but because the string
-is expanded, backslash escapes are processed anyway. If the message contains
-newlines, this gives rise to a multi-line SMTP response. Like &%log_message%&,
-the contents of &%message%& are not expanded until after a condition has
-failed.
+This modifier sets up a text string that is expanded and used as a response
+message when an ACL statement terminates the ACL with an &"accept"&, &"deny"&,
+or &"defer"& response. (In the case of the &%accept%& and &%discard%& verbs,
+there is some complication if &%endpass%& is involved; see the description of
+&%accept%& for details.)
+
+The expansion of the message happens at the time Exim decides that the ACL is
+to end, not at the time it processes &%message%&. If the expansion fails, or
+generates an empty string, the modifier is ignored. Here is an example where
+&%message%& must be specified first, because the ACL ends with a rejection if
+the &%hosts%& condition fails:
+.code
+require  message = Host not recognized
+         hosts = 10.0.0.0/8
+.endd
+(Once a condition has failed, no further conditions or modifiers are
+processed.)
+
+.cindex "SMTP" "error codes"
+.cindex "&%smtp_banner%&
+For ACLs that are triggered by SMTP commands, the message is returned as part
+of the SMTP response. The use of &%message%& with &%accept%& (or &%discard%&)
+is meaningful only for SMTP, as no message is returned when a non-SMTP message
+is accepted. In the case of the connect ACL, accepting with a message modifier
+overrides the value of &%smtp_banner%&. For the EHLO/HELO ACL, a customized
+accept message may not contain more than one line (otherwise it will be
+truncated at the first newline and a panic logged), and it cannot affect the
+EHLO options.
+
+When SMTP is involved, the message may begin with an overriding response code,
+consisting of three digits optionally followed by an &"extended response code"&
+of the form &'n.n.n'&, each code being followed by a space. For example:
+.code
+deny  message = 599 1.2.3 Host not welcome
+      hosts = 192.168.34.0/24
+.endd
+The first digit of the supplied response code must be the same as would be sent
+by default. A panic occurs if it is not. Exim uses a 550 code when it denies
+access, but for the predata ACL, note that the default success code is 354, not
+2&'xx'&.
+
+Notwithstanding the previous paragraph, for the QUIT ACL, unlike the others,
+the message modifier cannot override the 221 response code.
+
+The text in a &%message%& modifier is literal; any quotes are taken as
+literals, but because the string is expanded, backslash escapes are processed
+anyway. If the message contains newlines, this gives rise to a multi-line SMTP
+response.
+.wen
  
  .cindex "&$acl_verify_message$&"
  If &%message%& is used on a statement that verifies an address, the message
  
  .cindex "&$acl_verify_message$&"
  If &%message%& is used on a statement that verifies an address, the message
@@ -24381,6 +24980,7 @@ all the conditions are true, wherever it appears in an ACL command, whereas
  &%warn%& in an ACL that is not concerned with receiving a message, it has no
  effect.
  
  &%warn%& in an ACL that is not concerned with receiving a message, it has no
  effect.
  
+
  .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&>
  .cindex "&%set%&" "ACL modifier"
  This modifier puts a value into one of the ACL variables (see section
  .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&>
  .cindex "&%set%&" "ACL modifier"
  This modifier puts a value into one of the ACL variables (see section
@@ -24589,8 +25189,11 @@ No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added.
  There is no check that &'From:'& corresponds to the actual sender.
  .endlist ilist
  
  There is no check that &'From:'& corresponds to the actual sender.
  .endlist ilist
  
-This feature may be useful when a remotely-originated message is accepted,
-passed to some scanning program, and then re-submitted for delivery.
+This control may be useful when a remotely-originated message is accepted,
+passed to some scanning program, and then re-submitted for delivery. It can be
+used only in the &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&,
+and &%acl_not_smtp_start%& ACLs, because it has to be set before the message's
+data is read.
  .endlist vlist
  
  All four possibilities for message fixups can be specified:
  .endlist vlist
  
  All four possibilities for message fixups can be specified:
@@ -24639,9 +25242,9 @@ during the DATA and MIME ACLs, after which they are added to the message, again
  with duplicates suppressed. Thus, it is possible to add two identical header
  lines to an SMTP message, but only if one is added before DATA and one after.
  In the case of non-SMTP messages, new headers are accumulated during the
  with duplicates suppressed. Thus, it is possible to add two identical header
  lines to an SMTP message, but only if one is added before DATA and one after.
  In the case of non-SMTP messages, new headers are accumulated during the
-non-SMTP ACL, and added to the message at the end. If a message is rejected
-after DATA or by the non-SMTP ACL, all added header lines are included in the
-entry that is written to the reject log.
+non-SMTP ACLs, and are added to the message after all the ACLs have run. If a
+message is rejected after DATA or by the non-SMTP ACL, all added header lines
+are included in the entry that is written to the reject log.
  
  .cindex "header lines" "added; visibility of"
  Header lines are not visible in string expansions until they are added to the
  
  .cindex "header lines" "added; visibility of"
  Header lines are not visible in string expansions until they are added to the
@@ -24762,13 +25365,15 @@ This feature allows you to make up custom conditions. If the result of
  expanding the string is an empty string, the number zero, or one of the strings
  &"no"& or &"false"&, the condition is false. If the result is any non-zero
  number, or one of the strings &"yes"& or &"true"&, the condition is true. For
  expanding the string is an empty string, the number zero, or one of the strings
  &"no"& or &"false"&, the condition is false. If the result is any non-zero
  number, or one of the strings &"yes"& or &"true"&, the condition is true. For
-any other values, some error is assumed to have occurred, and the ACL returns
-&"defer"&.
+any other value, some error is assumed to have occurred, and the ACL returns
+&"defer"&. However, if the expansion is forced to fail, the condition is
+ignored. The effect is to treat it as true, whether it is positive or
+negative.
  
  .vitem &*decode&~=&~*&<&'location'&>
  .cindex "&%decode%&" "ACL condition"
  This condition is available only when Exim is compiled with the
  
  .vitem &*decode&~=&~*&<&'location'&>
  .cindex "&%decode%&" "ACL condition"
  This condition is available only when Exim is compiled with the
-content-scanning extension, and it is allowed only the the ACL defined by
+content-scanning extension, and it is allowed only in the ACL defined by
  &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file.
  For details, see chapter &<<CHAPexiscan>>&.
  
  &%acl_smtp_mime%&. It causes the current MIME part to be decoded into a file.
  For details, see chapter &<<CHAPexiscan>>&.
  
@@ -24800,6 +25405,12 @@ enabled, it is done before this test is done. If the check succeeds with a
  lookup, the result of the lookup is placed in &$domain_data$& until the next
  &%domains%& test.
  
  lookup, the result of the lookup is placed in &$domain_data$& until the next
  &%domains%& test.
  
+.new
+&*Note carefully*& (because many people seem to fall foul of this): you cannot
+use &%domains%& in a DATA ACL.
+.wen
+
+
  .vitem &*encrypted&~=&~*&<&'string&~list'&>
  .cindex "&%encrypted%&" "ACL condition"
  .cindex "encryption" "checking in an ACL"
  .vitem &*encrypted&~=&~*&<&'string&~list'&>
  .cindex "&%encrypted%&" "ACL condition"
  .cindex "encryption" "checking in an ACL"
@@ -24811,6 +25422,7 @@ encryption without testing for any specific cipher suite(s), set
  encrypted = *
  .endd
  
  encrypted = *
  .endd
  
+
  .vitem &*hosts&~=&~*&<&'&~host&~list'&>
  .cindex "&%hosts%&" "ACL condition"
  .cindex "host" "ACL checking"
  .vitem &*hosts&~=&~*&<&'&~host&~list'&>
  .cindex "&%hosts%&" "ACL condition"
  .cindex "host" "ACL checking"
@@ -24821,12 +25433,18 @@ you should normally put the IP addresses first. For example, you could have:
  .code
  accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
  .endd
  .code
  accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts
  .endd
-The reason for this lies in the left-to-right way that Exim processes lists.
-It can test IP addresses without doing any DNS lookups, but when it reaches an
-item that requires a host name, it fails if it cannot find a host name to
-compare with the pattern. If the above list is given in the opposite order, the
-&%accept%& statement fails for a host whose name cannot be found, even if its
-IP address is 10.9.8.7.
+.new
+The lookup in this example uses the host name for its key. This is implied by
+the lookup type &"dbm"&. (For a host address lookup you would use &"net-dbm"&
+and it wouldn't matter which way round you had these two items.)
+.wen
+
+The reason for the problem with host names lies in the left-to-right way that
+Exim processes lists. It can test IP addresses without doing any DNS lookups,
+but when it reaches an item that requires a host name, it fails if it cannot
+find a host name to compare with the pattern. If the above list is given in the
+opposite order, the &%accept%& statement fails for a host whose name cannot be
+found, even if its IP address is 10.9.8.7.
  
  If you really do want to do the name check first, and still recognize the IP
  address even if the name lookup fails, you can rewrite the ACL like this:
  
  If you really do want to do the name check first, and still recognize the IP
  address even if the name lookup fails, you can rewrite the ACL like this:
@@ -24871,7 +25489,7 @@ viruses. For details, see chapter &<<CHAPexiscan>>&.
  .cindex "&%mime_regex%&" "ACL condition"
  .cindex "&ACL;" "testing by regex matching"
  This condition is available only when Exim is compiled with the
  .cindex "&%mime_regex%&" "ACL condition"
  .cindex "&ACL;" "testing by regex matching"
  This condition is available only when Exim is compiled with the
-content-scanning extension, and it is allowed only the the ACL defined by
+content-scanning extension, and it is allowed only in the ACL defined by
  &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match
  with any of the regular expressions. For details, see chapter
  &<<CHAPexiscan>>&.
  &%acl_smtp_mime%&. It causes the current MIME part to be scanned for a match
  with any of the regular expressions. For details, see chapter
  &<<CHAPexiscan>>&.
@@ -25005,12 +25623,18 @@ common as they used to be.
  .cindex "verifying" "EHLO"
  .cindex "verifying" "HELO"
  This condition is true if a HELO or EHLO command has been received from the
  .cindex "verifying" "EHLO"
  .cindex "verifying" "HELO"
  This condition is true if a HELO or EHLO command has been received from the
-client host, and its contents have been verified. It there has been no previous
-attempt to verify the the HELO/EHLO contents, it is carried out when this
+client host, and its contents have been verified. If there has been no previous
+attempt to verify the HELO/EHLO contents, it is carried out when this
  condition is encountered. See the description of the &%helo_verify_hosts%& and
  &%helo_try_verify_hosts%& options for details of how to request verification
  independently of this condition.
  
  condition is encountered. See the description of the &%helo_verify_hosts%& and
  &%helo_try_verify_hosts%& options for details of how to request verification
  independently of this condition.
  
+.new
+For SMTP input that does not come over TCP/IP (the &%-bs%& command line
+option), this condition is always true.
+.wen
+
+
  .vitem &*verify&~=&~not_blind*&
  .cindex "verifying" "not blind"
  .cindex "bcc recipients" "verifying none"
  .vitem &*verify&~=&~not_blind*&
  .cindex "verifying" "not blind"
  .cindex "bcc recipients" "verifying none"
@@ -25270,24 +25894,31 @@ The values used on the RBL+ list are:
  127.1.0.6  RSS and DUL
  127.1.0.7  RSS and DUL and RBL
  .endd
  127.1.0.6  RSS and DUL
  127.1.0.7  RSS and DUL and RBL
  .endd
-Some DNS lists may return more than one address record.
-
+.new
+Section &<<SECTaddmatcon>>& below describes how you can distinguish between
+different values. Some DNS lists may return more than one address record; they
+are all checked.
+.wen
  
  .section "Variables set from DNS lists"
  
  .section "Variables set from DNS lists"
+.new
  .cindex "DNS list" "variables set from"
  .cindex "&$dnslist_domain$&"
  .cindex "&$dnslist_text$&"
  .cindex "&$dnslist_value$&"
  When an entry is found in a DNS list, the variable &$dnslist_domain$&
  .cindex "DNS list" "variables set from"
  .cindex "&$dnslist_domain$&"
  .cindex "&$dnslist_text$&"
  .cindex "&$dnslist_value$&"
  When an entry is found in a DNS list, the variable &$dnslist_domain$&
-contains the name of the domain that matched, &$dnslist_value$& contains the
-data from the entry, and &$dnslist_text$& contains the contents of any
-associated TXT record. If more than one address record is returned by the DNS
+contains the name of the domain that matched, and &$dnslist_value$& contains
+the data from the entry. If more than one address record is returned by the DNS
  lookup, all the IP addresses are included in &$dnslist_value$&, separated by
  lookup, all the IP addresses are included in &$dnslist_value$&, separated by
-commas and spaces.
+commas and spaces. The variable &$dnslist_text$& contains the contents of any
+associated TXT record. For lists such as RBL+ the TXT record for a merged entry
+is often not very meaningful. See section &<<SECTmordetinf>>& for a way of
+obtaining more information.
+.wen
  
  
-You can use these variables in &%message%& or &%log_message%& modifiers &--
-although these appear before the condition in the ACL, they are not expanded
-until after it has failed. For example:
+You can use the DNS list variables in &%message%& or &%log_message%& modifiers
+&-- although these appear before the condition in the ACL, they are not
+expanded until after it has failed. For example:
  .code
  deny    hosts = !+local_networks
          message = $sender_host_address is listed \
  .code
  deny    hosts = !+local_networks
          message = $sender_host_address is listed \
@@ -25386,6 +26017,55 @@ deny  dnslists = relays.ordb.org
  which is less clear, and harder to maintain.
  
  
  which is less clear, and harder to maintain.
  
  
+.new
+.section "Detailed information from merged DNS lists" "SECTmordetinf"
+.cindex "DNS list" "information from merged"
+When the facility for restricting the matching IP values in a DNS list is used,
+the text from the TXT record that is set in &$dnslist_text$& may not reflect
+the true reason for rejection. This happens when lists are merged and the IP
+address in the A record is used to distinguish them; unfortunately there is
+only one TXT record. One way round this is not to use merged lists, but that
+can be inefficient because it requires multiple DNS lookups where one would do
+in the vast majority of cases when the host of interest is not on any of the
+lists.
+
+A less inefficient way of solving this problem is available. If
+two domain names, comma-separated, are given, the second is used first to
+do an initial check, making use of any IP value restrictions that are set.
+If there is a match, the first domain is used, without any IP value
+restrictions, to get the TXT record. As a byproduct of this, there is also
+a check that the IP being tested is indeed on the first list. The first
+domain is the one that is put in &$dnslist_domain$&. For example:
+.code
+reject message  = \
+         rejected because $sender_ip_address is blacklisted \
+         at $dnslist_domain\n$dnslist_text
+       dnslists = \
+         sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
+         dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
+.endd
+For the first blacklist item, this starts by doing a lookup in
+&'sbl-xbl.spamhaus.org'& and testing for a 127.0.0.2 return. If there is a
+match, it then looks in &'sbl.spamhaus.org'&, without checking the return
+value, and as long as something is found, it looks for the corresponding TXT
+record. If there is no match in &'sbl-xbl.spamhaus.org'&, nothing more is done.
+The second blacklist item is processed similarly.
+
+If you are interested in more than one merged list, the same list must be
+given several times, but because the results of the DNS lookups are cached,
+the DNS calls themselves are not repeated. For example:
+.code
+reject dnslists = \
+         http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
+         socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
+         misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
+         dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
+.endd
+In this case there is one lookup in &'dnsbl.sorbs.net'&, and if none of the IP
+values matches (or if no record is found), this is the only lookup that is
+done. Only if there is a match is one of the more specific lists consulted.
+.wen
+
  
  
  .section "DNS lists and IPv6" "SECTmorednslistslast"
  
  
  .section "DNS lists and IPv6" "SECTmorednslistslast"
@@ -25417,7 +26097,7 @@ deny   condition = ${if isip4{$sender_host_address}}
  .section "Rate limiting senders" "SECTratelimiting"
  .cindex "rate limiting" "client sending"
  .cindex "limiting client sending rates"
  .section "Rate limiting senders" "SECTratelimiting"
  .cindex "rate limiting" "client sending"
  .cindex "limiting client sending rates"
-.oindex "&%smpt_ratelimit_*%&"
+.oindex "&%smtp_ratelimit_*%&"
  The &%ratelimit%& ACL condition can be used to measure and control the rate at
  which clients can send email. This is more powerful than the
  &%smtp_ratelimit_*%& options, because those options control the rate of
  The &%ratelimit%& ACL condition can be used to measure and control the rate at
  which clients can send email. This is more powerful than the
  &%smtp_ratelimit_*%& options, because those options control the rate of
@@ -25459,7 +26139,7 @@ of ratelimiting. For example, to limit the sending rate of each authenticated
  user, independent of the computer they are sending from, set the key to
  &$authenticated_id$&. You must ensure that the lookup key is meaningful; for
  example, &$authenticated_id$& is only meaningful if the client has
  user, independent of the computer they are sending from, set the key to
  &$authenticated_id$&. You must ensure that the lookup key is meaningful; for
  example, &$authenticated_id$& is only meaningful if the client has
-authenticated, and you can check with with the &%authenticated%& ACL condition.
+authenticated, and you can check with the &%authenticated%& ACL condition.
  
  Internally, Exim includes the smoothing constant &'p'& and the options in the
  lookup key because they alter the meaning of the stored data. This is not true
  
  Internally, Exim includes the smoothing constant &'p'& and the options in the
  lookup key because they alter the meaning of the stored data. This is not true
@@ -25511,10 +26191,10 @@ ln(peakrate/maxrate)
  The &%leaky%& option means that the client's recorded rate is not updated if it
  is above the limit. The effect of this is that Exim measures the client's
  average rate of successfully sent email, which cannot be greater than the
  The &%leaky%& option means that the client's recorded rate is not updated if it
  is above the limit. The effect of this is that Exim measures the client's
  average rate of successfully sent email, which cannot be greater than the
-maximum. If the client is over the limit it will suffer some counter-measures,
-but it will still be able to send email at the configured maximum rate,
-whatever the rate of its attempts. This is generally the better choice if you
-have clients that retry automatically.
+maximum. If the client is over the limit it &new("may suffer some
+counter-measures (as specified in the ACL)"), but it will still be able to send
+email at the configured maximum rate, whatever the rate of its attempts. This
+is generally the better choice if you have clients that retry automatically.
  
  Exim's other ACL facilities are used to define what counter-measures are taken
  when the rate limit is exceeded. This might be anything from logging a warning
  
  Exim's other ACL facilities are used to define what counter-measures are taken
  when the rate limit is exceeded. This might be anything from logging a warning
@@ -25523,35 +26203,30 @@ policy), through time delays to slow down fast senders, up to rejecting the
  message. For example:
  .code
  # Log all senders' rates
  message. For example:
  .code
  # Log all senders' rates
-warn
-  ratelimit = 0 / 1h / strict
-  log_message = Sender rate $sender_rate / $sender_rate_period
+warn ratelimit = 0 / 1h / strict
+     log_message = Sender rate $sender_rate / $sender_rate_period
  
  # Slow down fast senders; note the need to truncate $sender_rate
  # at the decimal point.
  
  # Slow down fast senders; note the need to truncate $sender_rate
  # at the decimal point.
-warn
-  ratelimit = 100 / 1h / per_rcpt / strict
-  delay     = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
-                $sender_rate_limit }s
+warn ratelimit = 100 / 1h / per_rcpt / strict
+     delay     = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
+                   $sender_rate_limit }s
  
  # Keep authenticated users under control
  
  # Keep authenticated users under control
-deny
-  authenticated = *
-  ratelimit = 100 / 1d / strict / $authenticated_id
+deny authenticated = *
+     ratelimit = 100 / 1d / strict / $authenticated_id
  
  # System-wide rate limit
  
  # System-wide rate limit
-defer
-  message = Sorry, too busy. Try again later.
-  ratelimit = 10 / 1s / $primary_hostname
+defer message = Sorry, too busy. Try again later.
+     ratelimit = 10 / 1s / $primary_hostname
  
  # Restrict incoming rate from each host, with a default
  # set using a macro and special cases looked up in a table.
  
  # Restrict incoming rate from each host, with a default
  # set using a macro and special cases looked up in a table.
-defer
-  message = Sender rate exceeds $sender_rate_limit \
-            messages per $sender_rate_period
-  ratelimit = ${lookup {$sender_host_address} \
-                cdb {DB/ratelimits.cdb} \
-                {$value} {RATELIMIT} }
+defer message = Sender rate exceeds $sender_rate_limit \
+               messages per $sender_rate_period
+     ratelimit = ${lookup {$sender_host_address} \
+                   cdb {DB/ratelimits.cdb} \
+                   {$value} {RATELIMIT} }
  .endd
  &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests,
  especially with the &%per_rcpt%& option, you may suffer from a performance
  .endd
  &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests,
  especially with the &%per_rcpt%& option, you may suffer from a performance
@@ -25566,10 +26241,11 @@ hints, the callout cache, and ratelimit data).
  .cindex "verifying address" "options for"
  .cindex "policy control" "address verification"
  Several of the &%verify%& conditions described in section
  .cindex "verifying address" "options for"
  .cindex "policy control" "address verification"
  Several of the &%verify%& conditions described in section
-&<<SECTaclconditions>>& cause addresses to be verified. These conditions can be
-followed by options that modify the verification process. The options are
-separated from the keyword and from each other by slashes, and some of them
-contain parameters. For example:
+&<<SECTaclconditions>>& cause addresses to be verified. Section
+&<<SECTsenaddver>>& discusses the reporting of sender verification failures.
+The verification conditions can be followed by options that modify the
+verification process. The options are separated from the keyword and from each
+other by slashes, and some of them contain parameters. For example:
  .code
  verify = sender/callout
  verify = recipient/defer_ok/callout=10s,defer_ok
  .code
  verify = sender/callout
  verify = recipient/defer_ok/callout=10s,defer_ok
@@ -25675,21 +26351,25 @@ router that does not set up hosts routes to an &(smtp)& transport with a
  &%hosts_override%& set, its hosts are always used, whether or not the router
  supplies a host list.
  
  &%hosts_override%& set, its hosts are always used, whether or not the router
  supplies a host list.
  
+.new
  The port that is used is taken from the transport, if it is specified and is a
  remote transport. (For routers that do verification only, no transport need be
  specified.) Otherwise, the default SMTP port is used. If a remote transport
  specifies an outgoing interface, this is used; otherwise the interface is not
  The port that is used is taken from the transport, if it is specified and is a
  remote transport. (For routers that do verification only, no transport need be
  specified.) Otherwise, the default SMTP port is used. If a remote transport
  specifies an outgoing interface, this is used; otherwise the interface is not
-specified.
+specified. Likewise, the text that is used for the HELO command is taken from
+the transport's &%helo_data%& option; if there is no transport, the value of
+&$smtp_active_hostname$& is used.
  
  For a sender callout check, Exim makes SMTP connections to the remote hosts, to
  test whether a bounce message could be delivered to the sender address. The
  following SMTP commands are sent:
  .display
  
  For a sender callout check, Exim makes SMTP connections to the remote hosts, to
  test whether a bounce message could be delivered to the sender address. The
  following SMTP commands are sent:
  .display
-&`HELO `&<&'smtp active host name'&>
+&`HELO `&<&'local host name'&>
  &`MAIL FROM:<>`&
  &`RCPT TO:`&<&'the address to be tested'&>
  &`QUIT`&
  .endd
  &`MAIL FROM:<>`&
  &`RCPT TO:`&<&'the address to be tested'&>
  &`QUIT`&
  .endd
+.wen
  LHLO is used instead of HELO if the transport's &%protocol%& option is
  set to &"lmtp"&.
  
  LHLO is used instead of HELO if the transport's &%protocol%& option is
  set to &"lmtp"&.
  
@@ -25929,9 +26609,10 @@ behaviour will be the same.
  
  .section "Sender address verification reporting" "SECTsenaddver"
  .cindex "verifying" "suppressing error details"
  
  .section "Sender address verification reporting" "SECTsenaddver"
  .cindex "verifying" "suppressing error details"
-When sender verification fails in an ACL, the details of the failure are
-given as additional output lines before the 550 response to the relevant
-SMTP command (RCPT or DATA). For example, if sender callout is in use,
+See section &<<SECTaddressverification>>& for a general discussion of
+verification. When sender verification fails in an ACL, the details of the
+failure are given as additional output lines before the 550 response to the
+relevant SMTP command (RCPT or DATA). For example, if sender callout is in use,
  you might see:
  .code
  MAIL FROM:<xyz@abc.example>
  you might see:
  .code
  MAIL FROM:<xyz@abc.example>
@@ -25991,6 +26672,12 @@ require verify = recipient/success_on_redirect/callout=10s
  In this example, verification succeeds if a router generates a new address, and
  the callout does not occur, because no address was routed to a remote host.
  
  In this example, verification succeeds if a router generates a new address, and
  the callout does not occur, because no address was routed to a remote host.
  
+.new
+When verification is being tested via the &%-bv%& option, the treatment of
+redirections is as just described, unless the &%-v%& or any debugging option is
+also specified. In that case, full verification is done for every generated
+address and a report is output for each of them.
+.wen
  
  
  
  
  
  
@@ -26080,10 +26767,10 @@ spam"&), because the recipients of such messages do not include valid tags.
  
  There are two expansion items to help with the implementation of the BATV
  &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs
  
  There are two expansion items to help with the implementation of the BATV
  &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs
-the original envelope sender address by using a simple shared key to add a hash
-of the address and some time-based randomizing information. The &%prvs%&
-expansion item creates a signed address, and the &%prvscheck%& expansion item
-checks one. The syntax of these expansion items is described in section
+the original envelope sender address by using a simple key to add a hash of the
+address and some time-based randomizing information. The &%prvs%& expansion
+item creates a signed address, and the &%prvscheck%& expansion item checks one.
+The syntax of these expansion items is described in section
  &<<SECTexpansionitems>>&.
  
  As an example, suppose the secret per-address keys are stored in an MySQL
  &<<SECTexpansionitems>>&.
  
  As an example, suppose the secret per-address keys are stored in an MySQL
@@ -26389,14 +27076,15 @@ For example, Sophos Sweep reports a virus on a line like this:
  .code
  Virus 'W32/Magistr-B' found in file ./those.bat
  .endd
  .code
  Virus 'W32/Magistr-B' found in file ./those.bat
  .endd
-For the trigger expression, we can just match the word &"found"&. For the name
-expression, we want to extract the W32/Magistr-B string, so we can match for
-the single quotes left and right of it. Altogether, this makes the
+.new
+For the trigger expression, we can match the phrase &"found in file"&. For the
+name expression, we want to extract the W32/Magistr-B string, so we can match
+for the single quotes left and right of it. Altogether, this makes the
  configuration setting:
  .code
  av_scanner = cmdline:\
  configuration setting:
  .code
  av_scanner = cmdline:\
-             /path/to/sweep -all -rec -archive %s:\
-             found:'(.+)'
+             /path/to/sweep -ss -all -rec -archive %s:\
+             found in file:'(.+)'
  .endd
  .vitem &%drweb%&
  .cindex "virus scanners" "DrWeb"
  .endd
  .vitem &%drweb%&
  .cindex "virus scanners" "DrWeb"
@@ -26447,9 +27135,9 @@ You can safely omit this option (the default value is 1).
  .vitem &%sophie%&
  .cindex "virus scanners" "Sophos and Sophie"
  Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses.
  .vitem &%sophie%&
  .cindex "virus scanners" "Sophos and Sophie"
  Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses.
-You can get Sophie at &url(http://www.vanja.com/tools/sophie/). The only
-option for this scanner type is the path to the UNIX socket that Sophie uses
-for client communication. For example:
+You can get Sophie at &url(http://www.clanfield.info/sophie/). The only option
+for this scanner type is the path to the UNIX socket that Sophie uses for
+client communication. For example:
  .code
  av_scanner = sophie:/tmp/sophie
  .endd
  .code
  av_scanner = sophie:/tmp/sophie
  .endd
@@ -26477,8 +27165,8 @@ use. It can then be one of
  The condition succeeds if a virus was found, and fail otherwise. This is the
  recommended usage.
  .next
  The condition succeeds if a virus was found, and fail otherwise. This is the
  recommended usage.
  .next
-&"false"& or &"0"&, in which case no scanning is done and the condition fails
-immediately.
+&"false"& or &"0"& or an empty string, in which case no scanning is done and
+the condition fails immediately.
  .next
  A regular expression, in which case the message is scanned for viruses. The
  condition succeeds if a virus is found and its name matches the regular
  .next
  A regular expression, in which case the message is scanned for viruses. The
  condition succeeds if a virus is found and its name matches the regular
@@ -26486,7 +27174,8 @@ expression. This allows you to take special actions on certain types of virus.
  .endlist
  
  You can append &`/defer_ok`& to the &%malware%& condition to accept messages
  .endlist
  
  You can append &`/defer_ok`& to the &%malware%& condition to accept messages
-even if there is a problem with the virus scanner.
+even if there is a problem with the virus scanner. Otherwise, such a problem
+causes the ACL to defer.
  
  .cindex "&$malware_name$&"
  When a virus is found, the condition sets up an expansion variable called
  
  .cindex "&$malware_name$&"
  When a virus is found, the condition sets up an expansion variable called
@@ -26581,16 +27270,25 @@ Here is a simple example of the use of the &%spam%& condition in a DATA ACL:
  deny message = This message was classified as SPAM
       spam = joe
  .endd
  deny message = This message was classified as SPAM
       spam = joe
  .endd
-The right-hand side of the &%spam%& condition specifies the username that
-SpamAssassin should scan for. If you do not want to scan for a particular user,
-but rather use the SpamAssassin system-wide default profile, you can scan for
-an unknown user, or simply use &"nobody"&. However, you must put something on
-the right-hand side.
+.new
+The right-hand side of the &%spam%& condition specifies a name. This is
+relevant if you have set up multiple SpamAssassin profiles. If you do not want
+to scan using a specific profile, but rather use the SpamAssassin system-wide
+default profile, you can scan for an unknown name, or simply use &"nobody"&.
+However, you must put something on the right-hand side.
+
+The name allows you to use per-domain or per-user antispam profiles in
+principle, but this is not straightforward in practice, because a message may
+have multiple recipients, not necessarily all in the same domain. Because the
+&%spam%& condition has to be called from a DATA ACL in order to be able to
+read the contents of the message, the variables &$local_part$& and &$domain$&
+are not set.
+
+The right-hand side of the &%spam%& condition is expanded before being used, so
+you can put lookups or conditions there. When the right-hand side evaluates to
+&"0"& or &"false"&, no scanning is done and the condition fails immediately.
+.wen
  
  
-The username allows you to use per-domain or per-user antispam profiles. The
-right-hand side is expanded before being used, so you can put lookups or
-conditions there. When the right-hand side evaluates to &"0"& or &"false"&, no
-scanning is done and the condition fails immediately.
  
  Scanning with SpamAssassin uses a lot of resources. If you scan every message,
  large ones may cause significant performance degredation. As most spam messages
  
  Scanning with SpamAssassin uses a lot of resources. If you scan every message,
  large ones may cause significant performance degredation. As most spam messages
@@ -26608,12 +27306,10 @@ SpamAssassin profile has been matched or exceeded. If you want to use the
  it always return &"true"& by appending &`:true`& to the username.
  
  .cindex "spam scanning" "returned variables"
  it always return &"true"& by appending &`:true`& to the username.
  
  .cindex "spam scanning" "returned variables"
-.new
  When the &%spam%& condition is run, it sets up a number of expansion
  variables. With the exception of &$spam_score_int$&, these are usable only
  within ACLs; their values are not retained with the message and so cannot be
  used at delivery time.
  When the &%spam%& condition is run, it sets up a number of expansion
  variables. With the exception of &$spam_score_int$&, these are usable only
  within ACLs; their values are not retained with the message and so cannot be
  used at delivery time.
-.wen
  
  .vlist
  .vitem &$spam_score$&
  
  .vlist
  .vitem &$spam_score$&
@@ -26657,15 +27353,14 @@ Here is a longer, commented example of the use of the &%spam%&
  condition:
  .code
  # put headers in all messages (no matter if spam or not)
  condition:
  .code
  # put headers in all messages (no matter if spam or not)
-warn  message = X-Spam-Score: $spam_score ($spam_bar)
-      spam = nobody:true
-warn  message = X-Spam-Report: $spam_report
-      spam = nobody:true
+warn  spam = nobody:true
+      add_header = X-Spam-Score: $spam_score ($spam_bar)
+      add_header = X-Spam-Report: $spam_report
  
  # add second subject line with *SPAM* marker when message
  # is over threshold
  
  # add second subject line with *SPAM* marker when message
  # is over threshold
-warn  message = Subject: *SPAM* $h_Subject:
-      spam = nobody
+warn  spam = nobody
+      add_header = Subject: *SPAM* $h_Subject:
  
  # reject spam at high scores (> 12)
  deny  message = This message scored $spam_score spam points.
  
  # reject spam at high scores (> 12)
  deny  message = This message scored $spam_score spam points.
@@ -26687,13 +27382,13 @@ specifies an ACL that is used for the MIME parts of non-SMTP messages. These
  options may both refer to the same ACL if you want the same processing in both
  cases.
  
  options may both refer to the same ACL if you want the same processing in both
  cases.
  
-These ACLs are called (possibly many times) just before the &%acl_smtp_data%&
-ACL in the case of an SMTP message, or just before a non-SMTP message is
-accepted. However, a MIME ACL is called only if the message contains a
-&'MIME-Version:'& header line. When a call to a MIME ACL does not yield
-&"accept"&, ACL processing is aborted and the appropriate result code is sent
-to the client. In the case of an SMTP message, the &%acl_smtp_data%& ACL is not
-called when this happens.
+These ACLs are called (possibly many times) just before the
+&%acl_smtp_data%& ACL in the case of an SMTP message, or just before the
+&%acl_not_smtp%& ACL in the case of a non-SMTP message. However, a MIME ACL
+is called only if the message contains a &'MIME-Version:'& header line. When a
+call to a MIME ACL does not yield &"accept"&, ACL processing is aborted and the
+appropriate result code is sent to the client. In the case of an SMTP message,
+the &%acl_smtp_data%& ACL is not called when this happens.
  
  You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can
  only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%&
  
  You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can
  only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%&
@@ -27294,7 +27989,11 @@ The IP address of the interface that received the message, as a string. This
  is NULL for locally submitted messages.
  
  .vitem &*int&~interface_port*&
  is NULL for locally submitted messages.
  
  .vitem &*int&~interface_port*&
-The port on which this message was received.
+.new
+The port on which this message was received. When testing with the &%-bh%&
+command line option, the value of this variable is -1 unless a port has been
+specified via the &%-oMi%& option.
+.wen
  
  .vitem &*uschar&~*message_id*&
  This variable contains Exim's message id for the incoming message (the value of
  
  .vitem &*uschar&~*message_id*&
  This variable contains Exim's message id for the incoming message (the value of
@@ -27620,9 +28319,9 @@ described with the structure of &%recipient_item%& above), because it pre-dates
  the addition of that field to the structure. However, it is easy to add such a
  value afterwards. For example:
  .code
  the addition of that field to the structure. However, it is easy to add such a
  value afterwards. For example:
  .code
-receive_add_recipient(US"monitor@mydom.example", -1);
-recipients_list[recipients_count-1].errors_to =
-US"postmaster@mydom.example";
+ receive_add_recipient(US"monitor@mydom.example", -1);
+ recipients_list[recipients_count-1].errors_to =
+   US"postmaster@mydom.example";
  .endd
  
  .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*&
  .endd
  
  .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*&
@@ -28387,7 +29086,7 @@ If no domain is specified by the submission control, the local part is
  &$authenticated_id$& and the domain is &$qualify_domain$&.
  .next
  If a non-empty domain is specified by the submission control, the local
  &$authenticated_id$& and the domain is &$qualify_domain$&.
  .next
  If a non-empty domain is specified by the submission control, the local
-part is &$authenticated_id$&, and the the domain is the specified domain.
+part is &$authenticated_id$&, and the domain is the specified domain.
  .next
  If an empty domain is specified by the submission control,
  &$authenticated_id$& is assumed to be the complete address.
  .next
  If an empty domain is specified by the submission control,
  &$authenticated_id$& is assumed to be the complete address.
@@ -28507,7 +29206,7 @@ If no domain is specified by the submission control, the local part is
  &$authenticated_id$& and the domain is &$qualify_domain$&.
  .next
  If a non-empty domain is specified by the submission control, the local part
  &$authenticated_id$& and the domain is &$qualify_domain$&.
  .next
  If a non-empty domain is specified by the submission control, the local part
-is &$authenticated_id$&, and the the domain is the specified domain.
+is &$authenticated_id$&, and the domain is the specified domain.
  .next
  If an empty domain is specified by the submission control,
  &$authenticated_id$& is assumed to be the complete address.
  .next
  If an empty domain is specified by the submission control,
  &$authenticated_id$& is assumed to be the complete address.
@@ -29420,7 +30119,7 @@ A message ${if eq{$sender_address}{$bounce_recipient}
  <$sender_address>
  
  }}could not be delivered to all of its recipients.
  <$sender_address>
  
  }}could not be delivered to all of its recipients.
-The following address(es) failed:
+This is a permanent error. The following address(es) failed:
  ****
  The following text was generated during the delivery attempt(s):
  ****
  ****
  The following text was generated during the delivery attempt(s):
  ****
@@ -29692,7 +30391,7 @@ verp_smtp:
    max_rcpt = 1
    return_path = \
      ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
    max_rcpt = 1
    return_path = \
      ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
-      {$1-request=$local_part%$domain@your.dom.example}fail}
+      {$1-request+$local_part=$domain@your.dom.example}fail}
  .endd
  This has the effect of rewriting the return path (envelope sender) on outgoing
  SMTP messages, if the local part of the original return path ends in
  .endd
  This has the effect of rewriting the return path (envelope sender) on outgoing
  SMTP messages, if the local part of the original return path ends in
@@ -29703,19 +30402,19 @@ example, that a message whose return path has been set to
  &'subscriber@other.dom.example'&. In the transport, the return path is
  rewritten as
  .code
  &'subscriber@other.dom.example'&. In the transport, the return path is
  rewritten as
  .code
-somelist-request=subscriber%other.dom.example@your.dom.example
+somelist-request+subscriber=other.dom.example@your.dom.example
  .endd
  .cindex "&$local_part$&"
  .endd
  .cindex "&$local_part$&"
-For this to work, you must also arrange for outgoing messages that have
-&"-request"& in their return paths to have just a single recipient. That is
+For this to work, you must tell Exim to send multiple copies of messages that
+have more than one recipient, so that each copy has just one recipient. This is
  achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message
  might be sent to several different recipients in the same domain, in which case
  &$local_part$& is not available in the transport, because it is not unique.
  
  Unless your host is doing nothing but mailing list deliveries, you should
  probably use a separate transport for the VERP deliveries, so as not to use
  achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message
  might be sent to several different recipients in the same domain, in which case
  &$local_part$& is not available in the transport, because it is not unique.
  
  Unless your host is doing nothing but mailing list deliveries, you should
  probably use a separate transport for the VERP deliveries, so as not to use
-extra resources for the others. This can easily be done by expanding the
-&%transport%& option in the router:
+extra resources in making one-per-recipient copies for other deliveries. This
+can easily be done by expanding the &%transport%& option in the router:
  .code
  dnslookup:
    driver = dnslookup
  .code
  dnslookup:
    driver = dnslookup
@@ -29743,7 +30442,7 @@ verp_dnslookup:
    transport = remote_smtp
    errors_to = \
      ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
    transport = remote_smtp
    errors_to = \
      ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
-     {$1-request=$local_part%$domain@your.dom.example}fail}
+     {$1-request+$local_part=$domain@your.dom.example}fail}
    no_more
  .endd
  Before you start sending out messages with VERPed return paths, you must also
    no_more
  .endd
  Before you start sending out messages with VERPed return paths, you must also
@@ -30472,7 +31171,7 @@ extensions (ESMTP), encryption, or authentication were used. If the SMTP
  session was encrypted, there is an additional X field that records the cipher
  suite that was used.
  
  session was encrypted, there is an additional X field that records the cipher
  suite that was used.
  
-The protocol is set to &"esmptsa"& or &"esmtpa"& for messages received from
+The protocol is set to &"esmtpsa"& or &"esmtpa"& for messages received from
  hosts that have authenticated themselves using the SMTP AUTH command. The first
  value is used when the SMTP connection was encrypted (&"secure"&). In this case
  there is an additional item A= followed by the name of the authenticator that
  hosts that have authenticated themselves using the SMTP AUTH command. The first
  value is used when the SMTP connection was encrypted (&"secure"&). In this case
  there is an additional item A= followed by the name of the authenticator that
@@ -30723,7 +31422,7 @@ selection marked by asterisks:
  &` received_sender            `&  sender on <= lines
  &`*rejected_header            `&  header contents on reject log
  &`*retry_defer                `&  &"retry time not reached"&
  &` 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
+&` 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
  &` sender_on_delivery         `&  add sender to => lines
  &`*sender_verify_fail         `&  sender verification failures
  &`*size_reject                `&  rejection because too big
@@ -30801,7 +31500,7 @@ DNS black list suffers a temporary error.
  .next
  .cindex "log" "ETRN commands"
  .cindex "ETRN" "logging"
  .next
  .cindex "log" "ETRN commands"
  .cindex "ETRN" "logging"
-&%etrn%&: Every legal ETRN command that is received is logged, before the ACL
+&%etrn%&: Every valid ETRN command that is received is logged, before the ACL
  is run to determine whether or not it is actually accepted. An invalid ETRN
  command, or one received within a message transaction is not logged by this
  selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&).
  is run to determine whether or not it is actually accepted. An invalid ETRN
  command, or one received within a message transaction is not logged by this
  selector (see &%smtp_syntax_error%& and &%smtp_protocol_error%&).
@@ -30906,10 +31605,10 @@ This is the original sender that was received with the message; it is not
  necessarily the same as the outgoing return path.
  .next
  .cindex "log" "sender verify failure"
  necessarily the same as the outgoing return path.
  .next
  .cindex "log" "sender verify failure"
-&%sender_verify_failure%&: If this selector is unset, the separate log line
-that gives details of a sender verification failure is not written. Log lines
-for the rejection of SMTP commands contain just &"sender verify failed"&, so
-some detail is lost.
+&%sender_verify_fail%&: If this selector is unset, the separate log line that
+gives details of a sender verification failure is not written. Log lines for
+the rejection of SMTP commands contain just &"sender verify failed"&, so some
+detail is lost.
  .next
  .cindex "log" "size rejection"
  &%size_reject%&: A log line is written whenever a message is rejected because
  .next
  .cindex "log" "size rejection"
  &%size_reject%&: A log line is written whenever a message is rejected because
@@ -31183,16 +31882,20 @@ it, as in the following example:
  .code
  3   2322   74m   66m  msn.com.example
  .endd
  .code
  3   2322   74m   66m  msn.com.example
  .endd
-Each line lists the number of
-pending deliveries for a domain, their total volume, and the length of time
-that the oldest and the newest messages have been waiting. Note that the number
-of pending deliveries is greater than the number of messages when messages
-have more than one recipient.
+Each line lists the number of pending deliveries for a domain, their total
+volume, and the length of time that the oldest and the newest messages have
+been waiting. Note that the number of pending deliveries is greater than the
+number of messages when messages have more than one recipient.
  
  
+.new
  A summary line is output at the end. By default the output is sorted on the
  domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause
  the output to be sorted by oldest message and by count of messages,
  A summary line is output at the end. By default the output is sorted on the
  domain name, but &'exiqsumm'& has the options &%-a%& and &%-c%&, which cause
  the output to be sorted by oldest message and by count of messages,
-respectively.
+respectively. There are also three options that split the messages for each
+domain into two or more subcounts: &%-b%& separates bounce messages, &%-f%&
+separates frozen messages, and &%-s%& separates messages according to their
+sender.
+.wen
  
  The output of &'exim -bp'& contains the original addresses in the message, so
  this also applies to the output from &'exiqsumm'&. No domains from addresses
  
  The output of &'exim -bp'& contains the original addresses in the message, so
  this also applies to the output from &'exiqsumm'&. No domains from addresses
@@ -31728,7 +32431,7 @@ second argument &-- hence the quotes.
  .cindex "X-windows"
  .cindex "&'eximon'&"
  .cindex "Local/eximon.conf"
  .cindex "X-windows"
  .cindex "&'eximon'&"
  .cindex "Local/eximon.conf"
-.cindex "_exim_monitor/EDITME_"
+.cindex "&_exim_monitor/EDITME_&"
  The Exim monitor is an application which displays in an X window information
  about the state of Exim's queue and what Exim is doing. An admin user can
  perform certain operations on messages from this GUI interface; however all
  The Exim monitor is an application which displays in an X window information
  about the state of Exim's queue and what Exim is doing. An admin user can
  perform certain operations on messages from this GUI interface; however all
@@ -32235,16 +32938,17 @@ gid are changed to the Exim user and group at the start of a delivery process
  routing is no longer run as root, and the deliveries themselves cannot change
  to any other uid.
  
  routing is no longer run as root, and the deliveries themselves cannot change
  to any other uid.
  
+.cindex SIGHUP
+.cindex "daemon" "restarting"
  Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means
  that the daemon can still be started in the usual way, and it can respond
  correctly to SIGHUP because the re-invocation regains root privilege.
  
  An alternative approach is to make Exim setuid to the Exim user and also setgid
  Leaving the binary setuid to root, but setting &%deliver_drop_privilege%& means
  that the daemon can still be started in the usual way, and it can respond
  correctly to SIGHUP because the re-invocation regains root privilege.
  
  An alternative approach is to make Exim setuid to the Exim user and also setgid
-to the Exim group.
-If you do this, the daemon must be started from a root process. (Calling
-Exim from a root process makes it behave in the way it does when it is setuid
-root.) However, the daemon cannot restart itself after a SIGHUP signal because
-it cannot regain privilege.
+to the Exim group. If you do this, the daemon must be started from a root
+process. (Calling Exim from a root process makes it behave in the way it does
+when it is setuid root.) However, the daemon cannot restart itself after a
+SIGHUP signal because it cannot regain privilege.
  
  It is still useful to set &%deliver_drop_privilege%& in this case, because it
  stops Exim from trying to re-invoke itself to do a delivery after a message has
  
  It is still useful to set &%deliver_drop_privilege%& in this case, because it
  stops Exim from trying to re-invoke itself to do a delivery after a message has
@@ -32526,7 +33230,7 @@ There follow a number of lines starting with a hyphen. These can appear in any
  order, and are omitted when not relevant:
  
  .vlist
  order, and are omitted when not relevant:
  
  .vlist
-.vitem "&%-acl%& <&'number'&> <&'length'&>"
+.vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
  This item is obsolete, and is not generated from Exim release 4.61 onwards;
  &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still
  recognized, to provide backward compatibility. In the old format, a line of
  This item is obsolete, and is not generated from Exim release 4.61 onwards;
  &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still
  recognized, to provide backward compatibility. In the old format, a line of
@@ -32537,19 +33241,23 @@ the data string for the variable. The string itself starts at the beginning of
  the next line, and is followed by a newline character. It may contain internal
  newlines.
  
  the next line, and is followed by a newline character. It may contain internal
  newlines.
  
-.vitem "&%-aclc%& <&'number'&> <&'length'&>"
-A line of this form is present for every ACL connection variable that is not
-empty. The number identifies the variable. The length is the length of the data
-string for the variable. The string itself starts at the beginning of the next
-line, and is followed by a newline character. It may contain internal newlines.
-
-.vitem "&%-aclm%& <&'number'&> <&'length'&>"
-A line of this form is present for every ACL message variable that is not
-empty. The number identifies the variable. The length is the length of the data
-string for the variable. The string itself starts at the beginning of the next
-line, and is followed by a newline character. It may contain internal newlines.
+.new
+.vitem "&%-aclc%&&~<&'rest-of-name'&>&~<&'length'&>"
+A line of this form is present for every ACL connection variable that is
+defined. Note that there is a space between &%-aclc%& and the rest of the name.
+The length is the length of the data string for the variable. The string itself
+starts at the beginning of the next line, and is followed by a newline
+character. It may contain internal newlines.
+
+.vitem "&%-aclm%&&~<&'rest-of-name'&>&~<&'length'&>"
+A line of this form is present for every ACL message variable that is defined.
+Note that there is a space between &%-aclm%& and the rest of the name. The
+length is the length of the data string for the variable. The string itself
+starts at the beginning of the next line, and is followed by a newline
+character. It may contain internal newlines.
+.wen
  
  
-.vitem "&%-active_hostname%& <&'hostname'&>"
+.vitem "&%-active_hostname%&&~<&'hostname'&>"
  This is present if, when the message was received over SMTP, the value of
  &$smtp_active_hostname$& was different to the value of &$primary_hostname$&.
  
  This is present if, when the message was received over SMTP, the value of
  &$smtp_active_hostname$& was different to the value of &$primary_hostname$&.
  
@@ -32565,19 +33273,19 @@ This is present if unqualified sender addresses are permitted in header lines
  time). Local messages that were input using &%-bnq%& and remote messages from
  hosts that match &%sender_unqualified_hosts%& set this flag.
  
  time). Local messages that were input using &%-bnq%& and remote messages from
  hosts that match &%sender_unqualified_hosts%& set this flag.
  
-.vitem "&%-auth_id%& <&'text'&>"
+.vitem "&%-auth_id%&&~<&'text'&>"
  The id information for a message received on an authenticated SMTP connection
  &-- the value of the &$authenticated_id$& variable.
  
  The id information for a message received on an authenticated SMTP connection
  &-- the value of the &$authenticated_id$& variable.
  
-.vitem "&%-auth_sender%& <&'address'&>"
+.vitem "&%-auth_sender%&&~<&'address'&>"
  The address of an authenticated sender &-- the value of the
  &$authenticated_sender$& variable.
  
  The address of an authenticated sender &-- the value of the
  &$authenticated_sender$& variable.
  
-.vitem "&%-body_linecount%& <&'number'&>"
+.vitem "&%-body_linecount%&&~<&'number'&>"
  This records the number of lines in the body of the message, and is always
  present.
  
  This records the number of lines in the body of the message, and is always
  present.
  
-.vitem "&%-body_zerocount%& <&'number'&>"
+.vitem "&%-body_zerocount%&&~<&'number'&>"
  This records the number of binary zero bytes in the body of the message, and is
  present if the number is greater than zero.
  
  This records the number of binary zero bytes in the body of the message, and is
  present if the number is greater than zero.
  
@@ -32585,20 +33293,20 @@ present if the number is greater than zero.
  This is written when a new message is first added to the spool. When the spool
  file is updated after a deferral, it is omitted.
  
  This is written when a new message is first added to the spool. When the spool
  file is updated after a deferral, it is omitted.
  
-.vitem "&%-frozen%& <&'time'&>"
+.vitem "&%-frozen%&&~<&'time'&>"
  .cindex "frozen messages" "spool data"
  The message is frozen, and the freezing happened at <&'time'&>.
  
  .cindex "frozen messages" "spool data"
  The message is frozen, and the freezing happened at <&'time'&>.
  
-.vitem "&%-helo_name%& <&'text'&>"
+.vitem "&%-helo_name%&&~<&'text'&>"
  This records the host name as specified by a remote host in a HELO or EHLO
  command.
  
  This records the host name as specified by a remote host in a HELO or EHLO
  command.
  
-.vitem "&%-host_address%& <&'address'&>.<&'port'&>"
+.vitem "&%-host_address%&&~<&'address'&>.<&'port'&>"
  This records the IP address of the host from which the message was received and
  the remote port number that was used. It is omitted for locally generated
  messages.
  
  This records the IP address of the host from which the message was received and
  the remote port number that was used. It is omitted for locally generated
  messages.
  
-.vitem "&%-host_auth%& <&'text'&>"
+.vitem "&%-host_auth%&&~<&'text'&>"
  If the message was received on an authenticated SMTP connection, this records
  the name of the authenticator &-- the value of the
  &$sender_host_authenticated$& variable.
  If the message was received on an authenticated SMTP connection, this records
  the name of the authenticator &-- the value of the
  &$sender_host_authenticated$& variable.
@@ -32607,20 +33315,20 @@ the name of the authenticator &-- the value of the
  This is present if an attempt to look up the sending host's name from its IP
  address failed. It corresponds to the &$host_lookup_failed$& variable.
  
  This is present if an attempt to look up the sending host's name from its IP
  address failed. It corresponds to the &$host_lookup_failed$& variable.
  
-.vitem "&%-host_name%& <&'text'&>"
+.vitem "&%-host_name%&&~<&'text'&>"
  .cindex "reverse DNS lookup"
  .cindex "DNS" "reverse lookup"
  This records the name of the remote host from which the message was received,
  if the host name was looked up from the IP address when the message was being
  received. It is not present if no reverse lookup was done.
  
  .cindex "reverse DNS lookup"
  .cindex "DNS" "reverse lookup"
  This records the name of the remote host from which the message was received,
  if the host name was looked up from the IP address when the message was being
  received. It is not present if no reverse lookup was done.
  
-.vitem "&%-ident%& <&'text'&>"
+.vitem "&%-ident%&&~<&'text'&>"
  For locally submitted messages, this records the login of the originating user,
  unless it was a trusted user and the &%-oMt%& option was used to specify an
  ident value. For messages received over TCP/IP, this records the ident string
  supplied by the remote host, if any.
  
  For locally submitted messages, this records the login of the originating user,
  unless it was a trusted user and the &%-oMt%& option was used to specify an
  ident value. For messages received over TCP/IP, this records the ident string
  supplied by the remote host, if any.
  
-.vitem "&%-interface_address%& <&'address'&>.<&'port'&>"
+.vitem "&%-interface_address%&&~<&'address'&>.<&'port'&>"
  This records the IP address of the local interface and the port number through
  which a message was received from a remote host. It is omitted for locally
  generated messages.
  This records the IP address of the local interface and the port number through
  which a message was received from a remote host. It is omitted for locally
  generated messages.
@@ -32631,7 +33339,7 @@ The message is from a local sender.
  .vitem &%-localerror%&
  The message is a locally-generated bounce message.
  
  .vitem &%-localerror%&
  The message is a locally-generated bounce message.
  
-.vitem "&%-local_scan%& <&'string'&>"
+.vitem "&%-local_scan%&&~<&'string'&>"
  This records the data string that was returned by the &[local_scan()]& function
  when the message was received &-- the value of the &$local_scan_data$&
  variable. It is omitted if no data was returned.
  This records the data string that was returned by the &[local_scan()]& function
  when the message was received &-- the value of the &$local_scan_data$&
  variable. It is omitted if no data was returned.
@@ -32653,7 +33361,7 @@ the name of the protocol by which the message was received.
  The envelope sender of this message was set by an untrusted local caller (used
  to ensure that the caller is displayed in queue listings).
  
  The envelope sender of this message was set by an untrusted local caller (used
  to ensure that the caller is displayed in queue listings).
  
-.vitem "&%-spam_score_int%& <&'number'&>"
+.vitem "&%-spam_score_int%&&~<&'number'&>"
  If a message was scanned by SpamAssassin, this is present. It records the value
  of &$spam_score_int$&.
  
  If a message was scanned by SpamAssassin, this is present. It records the value
  of &$spam_score_int$&.
  
@@ -32661,11 +33369,11 @@ of &$spam_score_int$&.
  A TLS certificate was received from the client that sent this message, and the
  certificate was verified by the server.
  
  A TLS certificate was received from the client that sent this message, and the
  certificate was verified by the server.
  
-.vitem "&%-tls_cipher%& <&'cipher name'&>"
+.vitem "&%-tls_cipher%&&~<&'cipher name'&>"
  When the message was received over an encrypted connection, this records the
  name of the cipher suite that was used.
  
  When the message was received over an encrypted connection, this records the
  name of the cipher suite that was used.
  
-.vitem "&%-tls_peerdn%& <&'peer DN'&>"
+.vitem "&%-tls_peerdn%&&~<&'peer DN'&>"
  When the message was received over an encrypted connection, and a certificate
  was received from the client, this records the Distinguished Name from that
  certificate.
  When the message was received over an encrypted connection, and a certificate
  was received from the client, this records the Distinguished Name from that
  certificate.