Docs: fix tables in PDF
[exim.git] / doc / doc-docbook / spec.xfpt
index eafd56fbadb2ccc18b1d26386ce98b2eb00bd2d9..e34fe792015e22d3185342b8fe499e7ce9f81f09 100644 (file)
@@ -45,7 +45,7 @@
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 
-.set previousversion "4.95"
+.set previousversion "4.96"
 .include ./local_params
 
 .set ACL "access control lists (ACLs)"
 
 
 . /////////////////////////////////////////////////////////////////////////////
-. This chunk of literal XML implements index entries of the form "x, see y" and
-. "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
+. These implement index entries of the form "x, see y" and "x, see also y".
+. However, the DocBook DTD doesn't allow <indexterm> entries
 . at the top level, so we have to put the .chapter directive first.
-
-. These do not turn up in the HTML output, unfortunately.  The PDF does get them.
 . /////////////////////////////////////////////////////////////////////////////
 
 .chapter "Introduction" "CHID1"
-.literal xml
 
-<indexterm role="variable">
-  <primary>$1, $2, etc.</primary>
-  <see><emphasis>numerical variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>address</primary>
-  <secondary>rewriting</secondary>
-  <see><emphasis>rewriting</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>Bounce Address Tag Validation</primary>
-  <see><emphasis>BATV</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>Client SMTP Authorization</primary>
-  <see><emphasis>CSA</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>CR character</primary>
-  <see><emphasis>carriage return</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>CRL</primary>
-  <see><emphasis>certificate revocation list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>delivery</primary>
-  <secondary>failure report</secondary>
-  <see><emphasis>bounce message</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>dialup</primary>
-  <see><emphasis>intermittently connected hosts</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>exiscan</primary>
-  <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>failover</primary>
-  <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>fallover</primary>
-  <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>filter</primary>
-  <secondary>Sieve</secondary>
-  <see><emphasis>Sieve filter</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>ident</primary>
-  <see><emphasis>RFC 1413</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>LF character</primary>
-  <see><emphasis>linefeed</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>maximum</primary>
-  <seealso><emphasis>limit</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
-  <primary>monitor</primary>
-  <see><emphasis>Exim monitor</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>no_<emphasis>xxx</emphasis></primary>
-  <see>entry for xxx</see>
-</indexterm>
-<indexterm role="concept">
-  <primary>NUL</primary>
-  <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>passwd file</primary>
-  <see><emphasis>/etc/passwd</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>process id</primary>
-  <see><emphasis>pid</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>RBL</primary>
-  <see><emphasis>DNS list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>redirection</primary>
-  <see><emphasis>address redirection</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>return path</primary>
-  <seealso><emphasis>envelope sender</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
-  <primary>scanning</primary>
-  <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>SSL</primary>
-  <see><emphasis>TLS</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>string</primary>
-  <secondary>expansion</secondary>
-  <see><emphasis>expansion</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>top bit</primary>
-  <see><emphasis>8-bit characters</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>variables</primary>
-  <see><emphasis>expansion, variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>zero, binary</primary>
-  <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>headers</primary>
-  <see><emphasis>header lines</emphasis></see>
+.macro seeother
+.literal xml
+<indexterm role="$2">
+  <primary>$3</primary>
+.arg 5
+  <secondary>$5</secondary>
+.endarg
+  <$1><emphasis>$4</emphasis></$1>
 </indexterm>
-
 .literal off
+.endmacro
+
+. NB: for the 4-arg variant the ordering is awkward
+.macro see
+.seeother see "$1" "$2" "$3" "$4"
+.endmacro
+.macro seealso
+.seeother seealso "$1" "$2" "$3" "$4"
+.endmacro
+
+.see     variable "<emphasis>$1</emphasis>, <emphasis>$2</emphasis>, etc." "numerical variables"
+.see     concept address       rewriting                       rewriting
+.see     concept "Bounce Address Tag Validation"       BATV
+.see     concept "Client SMTP Authorization"           CSA
+.see     concept "CR character"        "carriage return"
+.see     concept CRL           "certificate revocation list"
+.seealso concept de-tainting   "tainted data"
+.see     concept delivery      "bounce message"                "failure report"
+.see     concept dialup                "intermittently connected hosts"
+.see     concept exiscan       "content scanning"
+.see     concept fallover      fallback
+.see     concept filter        "Sieve filter"                  Sieve
+.see     concept headers       "header lines"
+.see     concept ident         "RFC 1413"
+.see     concept "LF character"        "linefeed"
+.seealso concept maximum       limit
+.see     concept monitor       "Exim monitor"
+.see     concept "no_<emphasis>xxx</emphasis>"         "entry for xxx"
+.see     concept NUL           "binary zero"
+.see     concept "passwd file" "/etc/passwd"
+.see     concept "process id"  pid
+.see     concept RBL           "DNS list"
+.see     concept redirection   "address redirection"
+.see     concept "return path" "envelope sender"
+.see     concept scanning      "content scanning"
+.see     concept SSL           TLS
+.see     concept string                expansion expansion
+.see     concept "top bit"     "8-bit characters"
+.see     concept variables     "expansion, variables"
+.see     concept "zero, binary"        "binary zero"
 
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -1820,11 +1741,9 @@ the traditional &'ndbm'& interface.
 To complicate things further, there are several very different versions of the
 Berkeley DB package. Version 1.85 was stable for a very long time, releases
 2.&'x'& and 3.&'x'& were current for a while,
-.new
 but the latest versions when Exim last revamped support were numbered 5.&'x'&.
 Maintenance of some of the earlier releases has ceased,
 and Exim no longer supports versions before 3.&'x'&.
-.wen
 All versions of Berkeley DB could be obtained from
 &url(http://www.sleepycat.com/), which is now a redirect to their new owner's
 page with far newer versions listed.
@@ -1849,9 +1768,7 @@ USE_DB=yes
 .endd
 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An
 error is diagnosed if you set more than one of these.
-.new
 You can set USE_NDBM if needed to override an operating system default.
-.wen
 
 At the lowest level, the build-time configuration sets none of these options,
 thereby assuming an interface of type (1). However, some operating system
@@ -1868,9 +1785,7 @@ DBMLIB = -ldb
 DBMLIB = -ltdb
 DBMLIB = -lgdbm -lgdbm_compat
 .endd
-.new
 The last of those was for a Linux having GDBM provide emulated NDBM facilities.
-.wen
 Settings like that will work if the DBM library is installed in the standard
 place. Sometimes it is not, and the library's header file may also not be in
 the default path. You may need to set INCLUDE to specify where the header
@@ -2919,6 +2834,12 @@ defined and macros will be expanded.
 Because macros in the config file are often used for secrets, those are only
 available to admin users.
 
+.new
+The word &"set"& at the start of a line, followed by a single space,
+is recognised specially as defining a value for a variable.
+The syntax is otherwise the same as the ACL modifier &"set ="&.
+.wen
+
 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"
@@ -3708,7 +3629,7 @@ 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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
 .irow acl            "ACL interpretation"
 .irow auth           "authenticators"
 .irow deliver        "general delivery logic"
@@ -6774,9 +6695,7 @@ domains = ${lookup{$sender_host_address}lsearch{/some/file}}
 domains = lsearch;/some/file
 .endd
 The first uses a string expansion, the result of which must be a domain list.
-.new
 The key for an expansion-style lookup must be given explicitly.
-.wen
 No strings have been specified for a successful or a failing lookup; the
 defaults in this case are the looked-up data and an empty string, respectively.
 The expansion takes place before the string is processed as a list, and the
@@ -6802,11 +6721,9 @@ domain2:
 Any data that follows the keys is not relevant when checking that the domain
 matches the list item.
 
-.new
 The key for a list-style lookup is implicit, from the lookup context, if
 the lookup is a single-key type (see below).
 For query-style lookup types the key must be given explicitly.
-.wen
 
 It is possible, though no doubt confusing, to use both kinds of lookup at once.
 Consider a file containing lines like this:
@@ -6857,11 +6774,9 @@ The &'query-style'& type accepts a generalized database query. No particular
 key value is assumed by Exim for query-style lookups. You can use whichever
 Exim variables you need to construct the database query.
 .cindex "tainted data" "quoting for lookups"
-.new
 If tainted data is used in the query then it should be quuted by
 using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
 appropriate for the lookup.
-.wen
 .endlist
 
 The code for each lookup type is in a separate source file that is included in
@@ -7926,7 +7841,7 @@ be preceded by any number of <&'name'&>=<&'value'&> settings, separated by
 spaces. If a value contains spaces it must be enclosed in double quotes, and
 when double quotes are used, backslash is interpreted in the usual way inside
 them. The following names are recognized:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
 .irow DEREFERENCE "set the dereferencing parameter"
 .irow NETTIME     "set a timeout for a network operation"
 .irow USER        "set the DN, for authenticating the LDAP bind"
@@ -10687,7 +10602,6 @@ expansion item in section &<<SECTexpansionitems>>& above.
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
 This item runs an external command, as a subprocess.
-.new
 One option is supported after the word &'run'&, comma-separated.
 
 If the option &'preexpand'& is not used,
@@ -10704,7 +10618,6 @@ potential attacker;
 a careful assessment for security vulnerabilities should be done.
 
 If the option &'preexpand'& is used,
-.wen
 the command and its arguments are first expanded as one string. The result is
 split apart into individual arguments by spaces, and then the command is run
 as above.
@@ -10718,9 +10631,7 @@ in a string containing quotes, because it would interfere with the quotes
 around the command arguments. A possible guard against this is to wrap the
 variable in the &%sg%& operator to change any quote marks to some other
 character.
-.new
 Neither the command nor any argument may be tainted.
-.wen
 
 The standard input for the command exists, but is empty. The standard output
 and standard error are set to the same file descriptor.
@@ -11286,9 +11197,7 @@ returns the string &"10.111.131.192/28"&.
 
 Since this operation is expected to
 be mostly used for looking up masked addresses in files, the
-.new
 normal
-.wen
 result for an IPv6
 address uses dots to separate components instead of colons, because colon
 terminates a key string in lsearch files. So, for example,
@@ -11299,10 +11208,8 @@ returns the string
 .code
 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
 .endd
-.new
 If the optional form &*mask_n*& is used, IPv6 address result are instead
 returned in normailsed form, using colons and with zero-compression.
-.wen
 Letters in IPv6 addresses are always output in lower case.
 
 
@@ -11634,7 +11541,7 @@ condition.
 .cindex "expansion" "numeric comparison"
 There are a number of symbolic operators for doing numeric comparisons. They
 are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
 .irow "=   " "equal"
 .irow "==  " "equal"
 .irow ">   " "greater"
@@ -11940,7 +11847,6 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
   ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
 .endd
 
-.new
 The variable &$value$& will be set for a successful match and can be
 used in the success clause of an &%if%& expansion item using the condition.
 .cindex "tainted data" "de-tainting"
@@ -11951,7 +11857,6 @@ ${if inlist {$h_mycode:} {0 : 1 : 42} {$value}}
 .endd
 can be used for de-tainting.
 Any previous &$value$& is restored after the if.
-.wen
 
 
 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
@@ -12150,7 +12055,6 @@ item can be used, as in all address lists, to cause subsequent items to
 have their local parts matched casefully. Domains are always matched
 caselessly.
 
-.new
 The variable &$value$& will be set for a successful match and can be
 used in the success clause of an &%if%& expansion item using the condition.
 .cindex "tainted data" "de-tainting"
@@ -12161,7 +12065,6 @@ ${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}}
 .endd
 can be used for de-tainting.
 Any previous &$value$& is restored after the if.
-.wen
 
 Note that <&'string2'&> is not itself subject to string expansion, unless
 Exim was built with the EXPAND_LISTMATCH_RHS option.
@@ -12358,7 +12261,6 @@ parsed but not evaluated.
 This section contains an alphabetical list of all the expansion variables. Some
 of them are available only when Exim is compiled with specific options such as
 support for TLS or the content scanning extension.
-.new
 .cindex "tainted data"
 Variables marked as &'tainted'& are likely to carry data supplied by
 a potential attacker.
@@ -12367,7 +12269,6 @@ values are created.
 Such variables should not be further expanded,
 used as filenames
 or used as command-line arguments for external commands.
-.wen
 
 .vlist
 .vitem "&$0$&, &$1$&, etc"
@@ -12382,9 +12283,7 @@ variables may also be set externally by some other matching process which
 precedes the expansion of the string. For example, the commands available in
 Exim filter files include an &%if%& command with its own regular expression
 matching condition.
-.new
 If the subject string was tainted then any captured substring will also be.
-.wen
 
 .vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
 Within an acl condition, expansion condition or expansion item
@@ -13290,11 +13189,9 @@ This is not an expansion variable, but is mentioned here because the string
 (described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
 It cannot be used in general expansion strings, and provokes an &"unknown
 variable"& error if encountered.
-.new
 &*Note*&: This value permits data supplied by a potential attacker to
 be used in the command for a &(pipe)& transport.
 Such configurations should be carefully assessed for security vulnerbilities.
-.wen
 
 .vitem &$primary_hostname$&
 .vindex "&$primary_hostname$&"
@@ -13513,9 +13410,7 @@ This variable is set to contain the matching regular expression after a
 When a &%regex%& or &%mime_regex%& ACL condition succeeds,
 these variables contain the
 captured substrings identified by the regular expression.
-.new
 If the subject string was tainted then so will any captured substring.
-.wen
 
 
 .tvar &$reply_address$&
@@ -14726,6 +14621,7 @@ listed in more than one group.
 .row &%log_timezone%&                "add timezone to log lines"
 .row &%message_logs%&                "create per-message logs"
 .row &%preserve_message_logs%&       "after message completion"
+.row &%panic_coredump%&              "request coredump on fatal errors"
 .row &%process_log_path%&            "for SIGUSR1 and &'exiwhat'&"
 .row &%slow_lookup_log%&             "control logging of slow DNS lookups"
 .row &%syslog_duplication%&          "controls duplicate log lines on syslog"
@@ -14898,6 +14794,7 @@ listed in more than one group.
 .row &%gnutls_compat_mode%&          "use GnuTLS compatibility mode"
 .row &%gnutls_allow_auto_pkcs11%&    "allow GnuTLS to autoload PKCS11 modules"
 .row &%hosts_require_alpn%&          "mandatory ALPN"
+.row &%hosts_require_helo%&          "mandatory HELO/EHLO"
 .row &%openssl_options%&             "adjust OpenSSL compatibility options"
 .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
 .row &%tls_alpn%&                   "acceptable protocol names"
@@ -16385,7 +16282,10 @@ local processes, you must create a host list with an empty item. For example:
 .code
 hosts_connection_nolog = :
 .endd
-If the &%smtp_connection%& log selector is not set, this option has no effect.
+.new
+The hosts affected by this option also do not log "no MAIL in SMTP connection"
+lines, as may commonly be produced by a monitoring system.
+.wen
 
 
 .option hosts_require_alpn main "host list&!!" unset
@@ -16401,6 +16301,12 @@ See also the &%tls_alpn%& option.
 managed by this option, and should be done separately.
 
 
+.option hosts_require_helo main "host list&!!" *
+.cindex "HELO/EHLO" requiring
+Exim will require an accepted HELO or EHLO command from a host matching
+this list, before accepting a MAIL command.
+
+
 .option hosts_proxy main "host list&!!" unset
 .cindex proxy "proxy protocol"
 This option enables use of Proxy Protocol proxies for incoming
@@ -17055,6 +16961,19 @@ to be used in conjunction with &(oracle)& lookups (see section &<<SECID72>>&).
 The option is available only if Exim has been built with Oracle support.
 
 
+.new
+.option panic_coredump main boolean false
+This option is rarely needed but can help for some debugging investigations.
+If set, when an internal error is detected by Exim which is sufficient
+to terminate the process
+(all such are logged in the paniclog)
+then a coredump is requested.
+
+Note that most systems require additional administrative configuration
+to permit write a core file for a setuid program, which is Exim's
+common installed configuration.
+.wen
+
 .option percent_hack_domains main "domain list&!!" unset
 .cindex "&""percent hack""&"
 .cindex "source routing" "in email address"
@@ -17129,9 +17048,9 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&).
 
 .option pipelining_connect_advertise_hosts main "host list&!!" *
 .cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
-.cindex "ESMTP extensions" PIPE_CONNECT
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+.cindex "pipelining" PIPECONNECT
+.cindex "ESMTP extensions" PIPECONNECT
+If Exim is built without the DISABLE_PIPE_CONNECT build option
 this option controls which hosts the facility is advertised to
 and from which pipeline early-connection (before MAIL) SMTP
 commands are acceptable.
@@ -17139,7 +17058,11 @@ When used, the pipelining saves on roundtrip times.
 
 See also the &%hosts_pipe_connect%& smtp transport option.
 
-The SMTP service extension keyword advertised is &"PIPE_CONNECT"&.
+The SMTP service extension keyword advertised is &"PIPECONNECT"&;
+it permits the client to pipeline
+TCP connection and hello command (inclear phase),
+or TLS-establishment and hello command (encrypted phase),
+on later connections to the same host.
 
 
 .option prdr_enable main boolean false
@@ -17261,7 +17184,7 @@ domains that do not match are processed. All other deliveries wait until the
 next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&.
 
 
-.option queue_fast_ramp main boolean false
+.option queue_fast_ramp main boolean true
 .cindex "queue runner" "two phase"
 .cindex "queue" "double scanning"
 If set to true, two-phase queue runs, initiated using &%-qq%& on the
@@ -17505,7 +17428,7 @@ initial set of recipients. The remote server should then re-send the message
 for the remaining recipients at a later time.
 
 
-.option remote_max_parallel main integer 2
+.option remote_max_parallel main integer 4
 .cindex "delivery" "parallelism for remote"
 This option controls parallel delivery of one message to a number of remote
 hosts. If the value is less than 2, parallel delivery is disabled, and Exim
@@ -18554,7 +18477,6 @@ of the later IKE values, which led into RFC7919 providing new fixed constants
 At this point, all of the "ike" values should be considered obsolete;
 they are still in Exim to avoid breaking unusual configurations, but are
 candidates for removal the next time we have backwards-incompatible changes.
-.new
 Two of them in particular (&`ike1`& and &`ike22`&) are called out by RFC 8247
 as MUST NOT use for IPSEC, and two more (&`ike23`& and &`ike24`&) as
 SHOULD NOT.
@@ -18562,7 +18484,6 @@ Because of this, Exim regards them as deprecated; if either of the first pair
 are used, warnings will be logged in the paniclog, and if any are used then
 warnings will be logged in the mainlog.
 All four will be removed in a future Exim release.
-.wen
 
 The TLS protocol does not negotiate an acceptable size for this; clients tend
 to hard-drop connections if what is offered by the server is unacceptable,
@@ -24749,11 +24670,9 @@ This list is a compromise for maximum compatibility with other MTAs. Note that
 the &%environment%& option can be used to add additional variables to this
 environment. The environment for the &(pipe)& transport is not subject
 to the &%add_environment%& and &%keep_environment%& main config options.
-.new
 &*Note*&: Using enviroment variables loses track of tainted data.
 Writers of &(pipe)& transport commands should be wary of data supplied
 by potential attackers.
-.wen
 .display
 &`DOMAIN            `&   the domain of the address
 &`HOME              `&   the home directory, if set
@@ -24845,10 +24764,8 @@ the &%path%& option below). The command is split up into separate arguments by
 Exim, and each argument is separately expanded, as described in section
 &<<SECThowcommandrun>>& above.
 
-.new
 .cindex "tainted data"
 No part of the resulting command may be tainted.
-.wen
 
 
 .option environment pipe string&!! unset
@@ -25557,7 +25474,6 @@ helo_data = ${lookup dnsdb{ptr=$sending_ip_address} \
 The use of &%helo_data%& applies both to sending messages and when doing
 callouts.
 
-.new
 .option host_name_extract smtp "string list&!!" "see below"
 .cindex "load balancer" "hosts behind"
 .cindex TLS resumption
@@ -25587,7 +25503,6 @@ of other destination sites operating load-balancers, and develop a suitable
 expression for this option.
 The smtp:ehlo event and the &$tls_out_resumption$& variable
 will be useful for such work.
-.wen
 
 .option hosts smtp "string list&!!" unset
 Hosts are associated with an address by a router such as &(dnslookup)&, which
@@ -25642,7 +25557,7 @@ that matches this list, even if the server host advertises PIPELINING support.
 
 .option hosts_pipe_connect smtp "host list&!!" unset
 .cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
+.cindex "pipelining" PIPECONNECT
 If Exim is built with the SUPPORT_PIPE_CONNECT build option
 this option controls which to hosts the facility watched for
 and recorded, and used for subsequent connections.
@@ -25656,10 +25571,8 @@ so combines well with TCP Fast Open.
 See also the &%pipelining_connect_advertise_hosts%& main option.
 
 Note:
-.new
 When the facility is used, if the transport &%interface%& option is unset
 the &%helo_data%& option
-.wen
 will be expanded before the &$sending_ip_address$& variable
 is filled in.
 A check is made for the use of that variable, without the
@@ -25792,11 +25705,6 @@ There will be no fallback to in-clear communication.
 See the &%dnssec_request_domains%& router and transport options.
 See section &<<SECDANE>>&.
 
-.option hosts_require_helo smtp "host list&!!" *
-.cindex "HELO/EHLO" requiring
-Exim will require an accepted HELO or EHLO command from a host matching
-this list, before accepting a MAIL command.
-
 .option hosts_require_ocsp smtp "host list&!!" unset
 .cindex "TLS" "requiring for certain servers"
 Exim will request, and check for a valid Certificate Status being given, on a
@@ -29935,10 +29843,8 @@ nothing more to it.  Choosing a sensible value not derived insecurely is the
 only point of caution.  The &$tls_out_sni$& variable will be set to this string
 for the lifetime of the client connection (including during authentication).
 
-.new
 If DANE validated the connection attempt then the value of the &%tls_sni%& option
 is forced to the name of the destination host, after any MX- or CNAME-following.
-.wen
 
 Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string
 received from a client.
@@ -30593,10 +30499,8 @@ 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.
 
-.new
 For tls-on-connect connections, the ACL is run after the TLS connection
 is accepted (however, &%host_reject_connection%& is tested before).
-.wen
 
 
 .section "The EHLO/HELO ACL" "SECID192"
@@ -31716,12 +31620,12 @@ This control turns on debug logging, almost as though Exim had been invoked
 with &`-d`&, with the output going to a new logfile in the usual logs directory,
 by default called &'debuglog'&.
 
-.new
+Logging set up by the control will be maintained across spool residency.
+
 Options are a slash-separated list.
 If an option takes an argument, the option name and argument are separated by
 an equals character.
 Several options are supported:
-.wen
 .display
 tag=<&'suffix'&>         The filename can be adjusted with thise option.
                     The argument, which may access any variables already defined,
@@ -32279,7 +32183,7 @@ different variants of this condition to describe briefly here. See sections
 .cindex "domain" "ACL checking"
 .cindex "&ACL;" "testing a recipient domain"
 .vindex "&$domain_data$&"
-This condition is relevant only after a RCPT command. It checks that the domain
+This condition is relevant only in a RCPT ACL. It checks that the domain
 of the recipient address is in the domain list. If percent-hack processing is
 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
@@ -32347,7 +32251,7 @@ which gives a custom error message for each denied host.
 .cindex "local part" "ACL checking"
 .cindex "&ACL;" "testing a local part"
 .vindex "&$local_part_data$&"
-This condition is relevant only after a RCPT command. It checks that the local
+This condition is relevant only in a RCPT ACL. It checks that the local
 part of the recipient address is in the list. If percent-hack processing is
 enabled, it is done before this test. If the check succeeds with a lookup, the
 result of the lookup is placed in &$local_part_data$&, which remains set until
@@ -32381,7 +32285,7 @@ messages. Details are given in section &<<SECTratelimiting>>&.
 .cindex "&%recipients%& ACL condition"
 .cindex "recipient" "ACL checking"
 .cindex "&ACL;" "testing a recipient"
-This condition is relevant only after a RCPT command. It checks the entire
+This condition is relevant only in a RCPT ACL. It checks the entire
 recipient address against a list of recipients.
 
 .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&>
@@ -32392,13 +32296,11 @@ content-scanning extension, and is available only in the DATA, MIME, and
 non-SMTP ACLs. It causes the incoming message to be scanned for a match with
 any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&.
 
-.new
 .vitem &*seen&~=&~*&<&'parameters'&>
-.cindex "&%sseen%& ACL condition"
+.cindex "&%seen%& ACL condition"
 This condition can be used to test if a situation has been previously met,
 for example for greylisting.
 Details are given in section &<<SECTseen>>&.
-.wen
 
 .vitem &*sender_domains&~=&~*&<&'domain&~list'&>
 .cindex "&%sender_domains%& ACL condition"
@@ -32658,7 +32560,7 @@ This is usually the required action when &%dnslists%& is used with &%deny%&
 (which is the most common usage), because it prevents a DNS failure from
 blocking mail. However, you can change this behaviour by putting one of the
 following special items in the list:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 25* left 75* left
 .irow "+include_unknown"   "behave as if the item is on the list"
 .irow "+exclude_unknown"   "behave as if the item is not on the list (default)"
 .irow "+defer_unknown  "   "give a temporary error"
@@ -32811,7 +32713,7 @@ DNS lists are constructed using address records in the DNS. The original RBL
 just used the address 127.0.0.1 on the right hand side of each record, but the
 RBL+ list and some other lists use a number of values with different meanings.
 The values used on the RBL+ list are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
 .irow 127.1.0.1  "RBL"
 .irow 127.1.0.2  "DUL"
 .irow 127.1.0.3  "DUL and RBL"
@@ -33123,9 +33025,8 @@ address you should specify alternate list separators for both the outer
 .endd
 
 
-.new
 .section "Previously seen user and hosts" "SECTseen"
-.cindex "&%sseen%& ACL condition"
+.cindex "&%een%& ACL condition"
 .cindex greylisting
 The &%seen%& ACL condition can be used to test whether a
 situation has been previously met.
@@ -33176,7 +33077,6 @@ An explicit interval can be set using a
 
 Note that &"seen"& should be added to the list of hints databases
 for maintenance if this ACL condition is used.
-.wen
 
 
 .section "Rate limiting incoming messages" "SECTratelimiting"
@@ -33621,14 +33521,12 @@ output before performing a callout in an ACL, to avoid unexpected timeouts in
 clients when the SMTP PIPELINING extension is in use. The flushing can be
 disabled by using a &%control%& modifier to set &%no_callout_flush%&.
 
-.new
 .cindex "tainted data" "de-tainting"
-.cindex "de-tainting" "using receipient verify"
+.cindex "de-tainting" "using recipient verify"
 A recipient callout which gets a 2&'xx'& code
 will assign untainted values to the
 &$domain_data$& and &$local_part_data$& variables,
 corresponding to the domain and local parts of the recipient address.
-.wen
 
 
 
@@ -35456,10 +35354,8 @@ discussed below.
 .vitem &*header_line&~*header_last*&
 A pointer to the last of the header lines.
 
-.new
 .vitem &*const&~uschar&~*headers_charset*&
 The value of the &%headers_charset%& configuration option.
-.wen
 
 .vitem &*BOOL&~host_checking*&
 This variable is TRUE during a host checking session that is initiated by the
@@ -35743,7 +35639,7 @@ added zero byte is not included in the returned count.
 .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*&
 This function checks for a match in a domain list. Domains are always
 matched caselessly. The return value is one of the following:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 15* left 85* left
 .irow &`OK`&    "match succeeded"
 .irow &`FAIL`&  "match failed"
 .irow &`DEFER`& "match deferred"
@@ -38454,7 +38350,7 @@ LOG_FILE_PATH, and uses the first item it finds that is neither empty nor
 &"syslog"&. This means that an empty item in &%log_file_path%& can be used to
 mean &"use the path specified at build time"&. If no such item exists, log
 files are written in the &_log_& subdirectory of the spool directory. This is
-equivalent to the setting:
+equivalent to the configuration file setting:
 .code
 log_file_path = $spool_directory/log/%slog
 .endd
@@ -38465,7 +38361,7 @@ that is where the logs are written.
 A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames
 are in use &-- see section &<<SECTdatlogfil>>& below.
 
-Here are some examples of possible settings:
+Here are some examples of possible Makefile settings:
 .display
 &`LOG_FILE_PATH=syslog                    `& syslog only
 &`LOG_FILE_PATH=:syslog                   `& syslog and default path
@@ -38640,7 +38536,7 @@ One line is written to the main log for each message received, and for each
 successful, unsuccessful, and delayed delivery. These lines can readily be
 picked out by the distinctive two-character flags that immediately follow the
 timestamp. The flags are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
 .irow &%<=%&     "message arrival"
 .irow &%(=%&     "message fakereject"
 .irow &%=>%&     "normal message delivery"
@@ -38968,7 +38864,7 @@ log_selector = +arguments -retry_defer
 .endd
 The list of optional log items is in the following table, with the default
 selection marked by asterisks:
-.itable none 0 0 3 1pt left 10pt center 1pt left
+.itable none 0 0 3 2.8in left 10pt center 3in left
 .irow &`8bitmime`&                     &nbsp; "received 8BITMIME status"
 .irow &`acl_warn_skipped`&             *       "skipped &%warn%& statement in ACL"
 .irow &`address_rewrite`&              &nbsp; "address rewriting"
@@ -39221,7 +39117,7 @@ On accept lines, where PIPELINING was offered but not used by the client,
 the field has a minus appended.
 
 .cindex "pipelining" "early connection"
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+If Exim is built without the DISABLE_PIPE_CONNECT build option
 accept "L" fields have a period appended if the feature was
 offered but not used, or an asterisk appended if used.
 Delivery "L" fields have an asterisk appended if used.
@@ -39523,7 +39419,7 @@ but the format of the output is different. For this reason, there are some
 system configuration options that configure exactly how &'exiwhat'& works. If
 it doesn't seem to be working for you, check the following compile-time
 options:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 30* left 70* left
 .irow &`EXIWHAT_PS_CMD`&       "the command for running &'ps'&"
 .irow &`EXIWHAT_PS_ARG`&       "the argument for &'ps'&"
 .irow &`EXIWHAT_EGREP_ARG`&    "the argument for &'egrep'& to select from &'ps'& output"
@@ -39623,9 +39519,7 @@ overriding the built-in one.
 .endlist
 
 There is one more option, &%-h%&, which outputs a list of options.
-.new
 At least one selection option, or either the &*-c*& or &*-h*& option, must be given.
-.wen
 
 
 
@@ -40008,12 +39902,10 @@ in a transport)
 .cindex "&'exim_dumpdb'&"
 The entire contents of a database are written to the standard output by the
 &'exim_dumpdb'& program,
-.new
 taking as arguments the spool and database names.
 An option &'-z'& may be given to request times in UTC;
 otherwise times are in the local timezone.
 An option &'-k'& may be given to dump only the record keys.
-.wen
 For example, to dump the retry database:
 .code
 exim_dumpdb /var/spool/exim retry
@@ -40118,11 +40010,9 @@ resets the time of the next delivery attempt. Time values are given as a
 sequence of digit pairs for year, month, day, hour, and minute. Colons can be
 used as optional separators.
 
-.new
 Both displayed and input times are in the local timezone by default.
 If an option &'-z'& is used on the command line, displayed times
 are in UTC.
-.wen
 
 
 
@@ -41145,7 +41035,6 @@ was received, in the conventional Unix form &-- the number of seconds since the
 start of the epoch. The second number is a count of the number of messages
 warning of delayed delivery that have been sent to the sender.
 
-.new
 There follow a number of lines starting with a hyphen.
 These contain variables, can appear in any
 order, and are omitted when not relevant.
@@ -41156,7 +41045,6 @@ If there is a value in parentheses, the data is quoted for a lookup.
 
 The following word specifies a variable,
 and the remainder of the item depends on the variable.
-.wen
 
 .vlist
 .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
@@ -41501,6 +41389,7 @@ The domain(s) you want to sign with.
 After expansion, this can be a list.
 Each element in turn,
 lowercased,
+.vindex "&$dkim_domain$&"
 is put into the &%$dkim_domain%& expansion variable
 while expanding the remaining signing options.
 If it is empty after expansion, DKIM signing is not done,
@@ -41510,6 +41399,7 @@ and no error will result even if &%dkim_strict%& is set.
 This sets the key selector string.
 After expansion, which can use &$dkim_domain$&, this can be a list.
 Each element in turn is put in the expansion
+.vindex "&$dkim_selector$&"
 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.
 If the option is empty after expansion, DKIM signing is not done for this domain,
@@ -42163,6 +42053,7 @@ There is no need to periodically change this key; a timestamp is also
 encoded.
 The second argument should be given as the envelope sender address before this
 encoding operation.
+If this value is empty the the expansion result will be empty.
 The third argument should be the recipient domain of the message when
 it arrived at this system.
 .endlist
@@ -42336,7 +42227,7 @@ The &"dmarc_status"& condition takes a list of strings on its
 right-hand side.  These strings describe recommended action based
 on the DMARC check.  To understand what the policy recommendations
 mean, refer to the DMARC website above.  Valid strings are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
 .irow &'accept'&       "The DMARC check passed and the library recommends accepting the email"
 .irow &'reject'&       "The DMARC check failed and the library recommends rejecting the email"
 .irow &'quarantine'&   "The DMARC check failed and the library recommends keeping it for further inspection"
@@ -42511,7 +42402,7 @@ within &%proxy_protocol_timeout%&, which defaults to 3s.
 The following expansion variables are usable
 (&"internal"& and &"external"& here refer to the interfaces
 of the proxy):
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 30* left 70* left
 .irow $proxy_external_address  "IP of host being proxied or IP of remote interface of proxy"
 .irow $proxy_external_port     "Port of host being proxied or Port on remote interface of proxy"
 .irow $proxy_local_address     "IP of proxy server inbound or IP of local interface of proxy"
@@ -42564,7 +42455,7 @@ is an IP address and any subsequent elements are options.
 
 Options are a string <name>=<value>.
 The list of options is in the following table:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
 .irow &'auth'& "authentication method"
 .irow &'name'& "authentication username"
 .irow &'pass'& "authentication password"
@@ -42688,7 +42579,7 @@ This is usually for use in a Message Submission Agent context,
 but could be used for any message.
 
 If a value is appended it may be:
-.itable none 0 0 2 1pt right 1pt left
+.itable none 0 0 2 5* right 95* left
 .irow &`1`&    "mandatory downconversion"
 .irow &`0`&    "no downconversion"
 .irow &`-1`&   "if SMTPUTF8 not supported by destination host"
@@ -42792,26 +42683,24 @@ Events have names which correspond to the point in process at which they fire.
 The name is placed in the variable &$event_name$& and the event action
 expansion must check this, as it will be called for every possible event type.
 
-.new
 The current list of events is:
-.itable all 0 0 4 1pt left 1pt center 1pt center 1pt left
-.irow dane:fail              after    transport  "per connection"
-.irow msg:complete           after    main       "per message"
-.irow msg:defer              after    transport  "per message per delivery try"
-.irow msg:delivery           after    transport  "per recipient"
-.irow msg:rcpt:host:defer    after    transport  "per recipient per host"
-.irow msg:rcpt:defer         after    transport  "per recipient"
-.irow msg:host:defer         after    transport  "per host per delivery try; host errors"
-.irow msg:fail:delivery      after    transport  "per recipient"
-.irow msg:fail:internal      after    main       "per recipient"
-.irow tcp:connect            before   transport  "per connection"
-.irow tcp:close              after    transport  "per connection"
-.irow tls:cert               before   both       "per certificate in verification chain"
-.irow tls:fail:connect       after    main       "per connection"
-.irow smtp:connect           after    transport  "per connection"
-.irow smtp:ehlo              after    transport  "per connection"
+.itable all 0 0 4 25* left 10* center 15* center 50* left
+.row dane:fail              after    transport  "per connection"
+.row msg:complete           after    main       "per message"
+.row msg:defer              after    transport  "per message per delivery try"
+.row msg:delivery           after    transport  "per recipient"
+.row msg:rcpt:host:defer    after    transport  "per recipient per host"
+.row msg:rcpt:defer         after    transport  "per recipient"
+.row msg:host:defer         after    transport  "per host per delivery try; host errors"
+.row msg:fail:delivery      after    transport  "per recipient"
+.row msg:fail:internal      after    main       "per recipient"
+.row tcp:connect            before   transport  "per connection"
+.row tcp:close              after    transport  "per connection"
+.row tls:cert               before   both       "per certificate in verification chain"
+.row tls:fail:connect       after    main       "per connection"
+.row smtp:connect           after    transport  "per connection"
+.row smtp:ehlo              after    transport  "per connection"
 .endtable
-.wen
 New event types may be added in future.
 
 The event name is a colon-separated list, defining the type of
@@ -42827,19 +42716,19 @@ should define the event action.
 
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:
-.itable all 0 0 2 1pt left 1pt left
-.irow dane:fail            "failure reason"
-.irow msg:defer            "error string"
-.irow msg:delivery         "smtp confirmation message"
-.irow msg:fail:internal    "failure reason"
-.irow msg:fail:delivery    "smtp error message"
-.irow msg:host:defer       "error string"
-.irow msg:rcpt:host:defer  "error string"
-.irow msg:rcpt:defer       "error string"
-.irow tls:cert             "verification chain depth"
-.irow tls:fail:connect     "error string"
-.irow smtp:connect         "smtp banner"
-.irow smtp:ehlo            "smtp ehlo response"
+.itable all 0 0 2 20* left 80* left
+.row dane:fail            "failure reason"
+.row msg:defer            "error string"
+.row msg:delivery         "smtp confirmation message"
+.row msg:fail:internal    "failure reason"
+.row msg:fail:delivery    "smtp error message"
+.row msg:host:defer       "error string"
+.row msg:rcpt:host:defer  "error string"
+.row msg:rcpt:defer       "error string"
+.row tls:cert             "verification chain depth"
+.row tls:fail:connect     "error string"
+.row smtp:connect         "smtp banner"
+.row smtp:ehlo            "smtp ehlo response"
 .endtable
 
 The :defer events populate one extra variable: &$event_defer_errno$&.
@@ -42860,10 +42749,10 @@ a useful way of writing to the main log.
 The expansion of the event_action option should normally
 return an empty string.  Should it return anything else the
 following will be forced:
-.itable all 0 0 2 1pt left 1pt left
-.irow tcp:connect      "do not connect"
-.irow tls:cert         "refuse verification"
-.irow smtp:connect     "close connection"
+.itable all 0 0 2 20* left 80* left
+.row tcp:connect      "do not connect"
+.row tls:cert         "refuse verification"
+.row smtp:connect     "close connection"
 .endtable
 All other message types ignore the result string, and
 no other use is made of it.