tidying: formatted listmaker

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4575bc87912b56a9dda6cbf463be3466a9816d76..72ecedc91d72f38ea0ded011eb9b68116b773829 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -45,7 +45,7 @@
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 

-.set previousversion "4.97"
+.set previousversion "4.98"

 .include ./local_params
 
 .set ACL "access control lists (ACLs)"
 .include ./local_params
 
 .set ACL "access control lists (ACLs)"


@@ -1764,6 +1764,12 @@ distributors have chosen to bundle different libraries with their packaged
 versions. However, the more recent releases seem to have standardized on the
 Berkeley DB library.
 
 versions. However, the more recent releases seem to have standardized on the
 Berkeley DB library.
 

+.new
+Ownership of the Berkeley DB library has moved to a major corporation;
+development seems to have stalled and documentation is not freely available.
+This is probably not tenable for the long term use by Exim.
+.wen
+

 Different DBM libraries have different conventions for naming the files they
 use. When a program opens a file called &_dbmfile_&, there are several
 possibilities:
 Different DBM libraries have different conventions for naming the files they
 use. When a program opens a file called &_dbmfile_&, there are several
 possibilities:


@@ -1805,10 +1811,8 @@ Yet another DBM library, called &'tdb'&, is available from
 &url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also
 operates on a single file.
 .next
 &url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also
 operates on a single file.
 .next

-.new

 It is possible to use sqlite3 (&url(https://www.sqlite.org/index.html))
 for the DBM library.
 It is possible to use sqlite3 (&url(https://www.sqlite.org/index.html))
 for the DBM library.

-.wen

 .endlist
 
 .cindex "USE_DB"
 .endlist
 
 .cindex "USE_DB"


@@ -1854,6 +1858,17 @@ DBMLIB=/usr/local/lib/db-4.1/libdb.a
 There is further detailed discussion about the various DBM libraries in the
 file &_doc/dbm.discuss.txt_& in the Exim distribution.
 
 There is further detailed discussion about the various DBM libraries in the
 file &_doc/dbm.discuss.txt_& in the Exim distribution.
 

+.new
+When moving from one DBM library to another,
+for the hints databases it suffices to just remove all the files in the
+directory named &"db/"& under the spool directory.
+This is because hints are only for optimisation and will be rebuilt
+during normal operations.
+Non-hints DBM databases (used by &"dbm"& lookups in the configuration)
+will need individual rebuilds for the new DBM library.
+This is not done automatically
+.wen
+

 
 
 .section "Pre-building configuration" "SECID25"
 
 
 .section "Pre-building configuration" "SECID25"


@@ -2054,19 +2069,29 @@ withdrawn.
 
 
 
 
 
 

-.section "Dynamically loaded lookup module support" "SECTdynamicmodules"
+.section "Dynamically loaded module support" "SECTdynamicmodules"

 .cindex "lookup modules"
 .cindex "lookup modules"

+.cindex "router modules"
+.cindex "transport modules"
+.cindex "authenticator modules"

 .cindex "dynamic modules"
 .cindex ".so building"
 On some platforms, Exim supports not compiling all lookup types directly into
 the main binary, instead putting some into external modules which can be loaded
 on demand.
 This permits packagers to build Exim with support for lookups with extensive
 .cindex "dynamic modules"
 .cindex ".so building"
 On some platforms, Exim supports not compiling all lookup types directly into
 the main binary, instead putting some into external modules which can be loaded
 on demand.
 This permits packagers to build Exim with support for lookups with extensive

-library dependencies without requiring all users to install all of those
+library dependencies without requiring all systems to install all of those

 dependencies.
 dependencies.

-Most, but not all, lookup types can be built this way.
+.new
+Any combination of lookup types can be built this way.
+Lookup types that provide several variants will be loaded as
+Exim starts.
+Types that provide only one method are not loaded until used by
+the runtime configuration.
+.wen

 
 

-Set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be
+For building
+set &`LOOKUP_MODULE_DIR`& to the directory into which the modules will be

 installed; Exim will only load modules from that directory, as a security
 measure.  You will need to set &`CFLAGS_DYNAMIC`& if not already defined
 for your OS; see &_OS/Makefile-Linux_& for an example.
 installed; Exim will only load modules from that directory, as a security
 measure.  You will need to set &`CFLAGS_DYNAMIC`& if not already defined
 for your OS; see &_OS/Makefile-Linux_& for an example.


@@ -2076,12 +2101,25 @@ see &_src/EDITME_& for details.
 Then, for each module to be loaded dynamically, define the relevant
 &`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes".
 For example, this will build in lsearch but load sqlite and mysql support
 Then, for each module to be loaded dynamically, define the relevant
 &`LOOKUP_`&<&'lookup_type'&> flags to have the value "2" instead of "yes".
 For example, this will build in lsearch but load sqlite and mysql support

-on demand:
+only if each is installed:

 .code
 LOOKUP_LSEARCH=yes
 LOOKUP_SQLITE=2
 LOOKUP_MYSQL=2
 .endd
 .code
 LOOKUP_LSEARCH=yes
 LOOKUP_SQLITE=2
 LOOKUP_MYSQL=2
 .endd

+Set also &`LOOKUP_`&<&'lookup_type'&>&` INCLUDE`& and
+&`LOOKUP_`&<&'lookup_type'&>`_LIBS if needed for each lookup type,
+ensuring that duplicates are not present in more global values.
+
+.new
+Similarly, authenticator, router and transport drivers can be built
+as external modules.
+Modules will be searched for as demanded by the runtime configuration,
+permitting a smaller Exim binary.
+
+For building, as above but using
+&`AUTH_*`&, &`ROUTER_*`& and &`TRANSPORT_*`& instead of &`LOOKUP_*`&,
+.wen

 
 
 .section "The building process" "SECID29"
 
 
 .section "The building process" "SECID29"


@@ -2892,11 +2930,9 @@ available to admin users.
 
 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 word &"set"& at the start of a line, followed by a single space,
 is recognised specially as defining a value for a variable.

-.new

 .cindex "tainted data" "expansion testing"
 If the sequence &",t"& is inserted before the space,
 the value is marked as tainted.
 .cindex "tainted data" "expansion testing"
 If the sequence &",t"& is inserted before the space,
 the value is marked as tainted.

-.wen

 The syntax is otherwise the same as the ACL modifier &"set ="&.
 
 .cmdopt -bem <&'filename'&>
 The syntax is otherwise the same as the ACL modifier &"set ="&.
 
 .cmdopt -bem <&'filename'&>


@@ -5439,7 +5475,7 @@ list items, it is not ignored when parsing the list. The spaces around the first
 colon in the example above are necessary. If they were not there, the list would
 be interpreted as the two items 127.0.0.1:: and 1.
 
 colon in the example above are necessary. If they were not there, the list would
 be interpreted as the two items 127.0.0.1:: and 1.
 

-.section "Changing list separators" "SECTlistsepchange"
+.subsection "Changing list separators" "SECTlistsepchange"

 .cindex "list separator" "changing"
 .cindex "IPv6" "addresses in lists"
 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
 .cindex "list separator" "changing"
 .cindex "IPv6" "addresses in lists"
 Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was


@@ -5480,7 +5516,7 @@ enclosing an empty list item.
 
 
 
 
 
 

-.section "Empty items in lists" "SECTempitelis"
+.subsection "Empty items in lists" "SECTempitelis"

 .cindex "list" "empty item in"
 An empty item at the end of a list is always ignored. In other words, trailing
 separator characters are ignored. Thus, the list in
 .cindex "list" "empty item in"
 An empty item at the end of a list is always ignored. In other words, trailing
 separator characters are ignored. Thus, the list in


@@ -6852,9 +6888,7 @@ by default, but has an option to omit them (see section &<<SECTdbmbuild>>&).
 .cindex "dsearch lookup type"
 The given file must be an absolute directory path; this is searched for an entry
 whose name is the key by calling the &[lstat()]& function.
 .cindex "dsearch lookup type"
 The given file must be an absolute directory path; this is searched for an entry
 whose name is the key by calling the &[lstat()]& function.

-.new

 Unless the options (below) permit a path,
 Unless the options (below) permit a path,

-.wen

 the key may not contain any forward slash characters.
 If &[lstat()]& succeeds then so does the lookup.
 .cindex "tainted data" "dsearch result"
 the key may not contain any forward slash characters.
 If &[lstat()]& succeeds then so does the lookup.
 .cindex "tainted data" "dsearch result"


@@ -8179,7 +8213,6 @@ option, you can still update it by a query of this form:
 ${lookup pgsql,servers=master/db/name/pw {UPDATE ...} }
 .endd
 
 ${lookup pgsql,servers=master/db/name/pw {UPDATE ...} }
 .endd
 

-.new

 A now-deprecated syntax places the servers specification before the query,
 semicolon separated:
 .code
 A now-deprecated syntax places the servers specification before the query,
 semicolon separated:
 .code


@@ -8188,10 +8221,9 @@ ${lookup mysql{servers=master; UPDATE ...} }
 The new version avoids issues with tainted
 arguments explicitly expanded as part of the query.
 The entire string within the braces becomes tainted,
 The new version avoids issues with tainted
 arguments explicitly expanded as part of the query.
 The entire string within the braces becomes tainted,

-including the server sepcification - which is not permissible.
+including the server specification - which is not permissible.

 If the older sytax is used, a warning message will be logged.
 This syntax will be removed in a future release.
 If the older sytax is used, a warning message will be logged.
 This syntax will be removed in a future release.

-.wen

 
 &*Note*&: server specifications in list-style lookups are still problematic.
 
 
 &*Note*&: server specifications in list-style lookups are still problematic.
 


@@ -8220,10 +8252,8 @@ or delete command), the result of the lookup is the number of rows affected.
 anything (for example, setting a field to the value it already has), the result
 is zero because no rows are affected.
 
 anything (for example, setting a field to the value it already has), the result
 is zero because no rows are affected.
 

-.new

 To get an encryted connection, use a Mysql option file with the required
 parameters for the connection.
 To get an encryted connection, use a Mysql option file with the required
 parameters for the connection.

-.wen

 
 
 .subsection "Special PostgreSQL features" SECID74
 
 
 .subsection "Special PostgreSQL features" SECID74


@@ -10803,7 +10833,7 @@ will sort an MX lookup into priority order.
 
 
 .vitem &*${srs_encode&~{*&<&'secret'&>&*}{*&<&'return&~path'&>&*}{*&<&'original&~domain'&>&*}}*&
 
 
 .vitem &*${srs_encode&~{*&<&'secret'&>&*}{*&<&'return&~path'&>&*}{*&<&'original&~domain'&>&*}}*&

-SRS encoding.  See SECT &<<SECTSRS>>& for details.
+SRS encoding.  See section &<<SECTSRS>>& for details.

 
 
 
 
 
 


@@ -11593,14 +11623,12 @@ These convert EAI mail name components between UTF-8 and a-label forms.
 For information on internationalisation support see &<<SECTi18nMTA>>&.
 
 
 For information on internationalisation support see &<<SECTi18nMTA>>&.
 
 

-.new

 .vitem &*${xtextd:*&<&'string'&>&*}*&
 .cindex "text forcing in strings"
 .cindex "string" "xtext decoding"
 .cindex "xtext"
 .cindex "&%xtextd%& expansion item"
 This performs xtext decoding of the string (per RFC 3461 section 4).
 .vitem &*${xtextd:*&<&'string'&>&*}*&
 .cindex "text forcing in strings"
 .cindex "string" "xtext decoding"
 .cindex "xtext"
 .cindex "&%xtextd%& expansion item"
 This performs xtext decoding of the string (per RFC 3461 section 4).

-.wen

 
 
 
 
 
 


@@ -12606,6 +12634,11 @@ contain the trailing slash. If &$config_file$& does not contain a slash,
 .vindex "&$config_file$&"
 The name of the main configuration file Exim is using.
 
 .vindex "&$config_file$&"
 The name of the main configuration file Exim is using.
 

+.vitem &$connection_id$&
+.vindex "&$connection_id$&"
+.cindex connection "identifier logging"
+An identifier for the accepted connection, for use in custom logging.
+

 .vitem &$dkim_verify_status$&
 Results of DKIM verification.
 For details see section &<<SECDKIMVFY>>&.
 .vitem &$dkim_verify_status$&
 Results of DKIM verification.
 For details see section &<<SECDKIMVFY>>&.


@@ -15199,8 +15232,11 @@ See section &<<SECDKIMVFY>>& for further details.
 
 .option acl_smtp_etrn main string&!! unset
 .cindex "ETRN" "ACL for"
 
 .option acl_smtp_etrn main string&!! unset
 .cindex "ETRN" "ACL for"

+.cindex "ETRN" advertisement

 This option defines the ACL that is run when an SMTP ETRN command is
 This option defines the ACL that is run when an SMTP ETRN command is

-received. See chapter &<<CHAPACL>>& for further details.
+received.
+If no value is set then the ETRN facility is not advertised.
+See chapter &<<CHAPACL>>& for further details.

 
 .option acl_smtp_expn main string&!! unset
 .cindex "EXPN" "ACL for"
 
 .option acl_smtp_expn main string&!! unset
 .cindex "EXPN" "ACL for"


@@ -15263,12 +15299,10 @@ received. See chapter &<<CHAPACL>>& for further details.
 This option defines the ACL that is run when an SMTP VRFY command is
 received. See chapter &<<CHAPACL>>& for further details.
 
 This option defines the ACL that is run when an SMTP VRFY command is
 received. See chapter &<<CHAPACL>>& for further details.
 

-.new

 .option acl_smtp_wellknown main string&!! unset
 .cindex "WELLKNOWN, ACL for"
 This option defines the ACL that is run when an SMTP WELLKNOWN command is
 received. See section &<<SECTWELLKNOWNACL>>& for further details.
 .option acl_smtp_wellknown main string&!! unset
 .cindex "WELLKNOWN, ACL for"
 This option defines the ACL that is run when an SMTP WELLKNOWN command is
 received. See section &<<SECTWELLKNOWNACL>>& for further details.

-.wen

 
 .option add_environment main "string list" empty
 .cindex "environment" "set values"
 
 .option add_environment main "string list" empty
 .cindex "environment" "set values"


@@ -15775,9 +15809,9 @@ the ACL once for each signature in the message.
 See section &<<SECDKIMVFY>>&.
 
 
 See section &<<SECDKIMVFY>>&.
 
 

-.option dmarc_forensic_sender main string&!! unset &&&
-        dmarc_history_file main string unset &&&
-        dmarc_tld_file main string unset
+.options dmarc_forensic_sender main string&!! unset &&&
+         dmarc_history_file main string unset &&&
+         dmarc_tld_file main string unset

 .cindex DMARC "main section options"
 These options control DMARC processing.
 See section &<<SECDMARC>>& for details.
 .cindex DMARC "main section options"
 These options control DMARC processing.
 See section &<<SECDMARC>>& for details.


@@ -16103,9 +16137,11 @@ routing, but which are not used for listening by the daemon. See section
 
 . Allow this long option name to split; give it unsplit as a fifth argument
 . for the automatic .oindex that is generated by .option.
 
 . Allow this long option name to split; give it unsplit as a fifth argument
 . for the automatic .oindex that is generated by .option.

+. WAS:
+. .option "extract_addresses_remove_ &~&~arguments"
+. but apparently this results in searchability problems; bug 1197

 
 

-.option "extract_addresses_remove_arguments" main boolean true &&&
-         extract_addresses_remove_arguments
+.option extract_addresses_remove_arguments main boolean true

 .oindex "&%-t%&"
 .cindex "command line" "addresses with &%-t%&"
 .cindex "Sendmail compatibility" "&%-t%& option"
 .oindex "&%-t%&"
 .cindex "command line" "addresses with &%-t%&"
 .cindex "Sendmail compatibility" "&%-t%& option"


@@ -16245,7 +16281,7 @@ set.
 .cindex "underscore in EHLO/HELO"
 This option can be set to a string of rogue characters that are permitted in
 non-ip-literal EHLO and HELO names in addition to the standard letters, digits,
 .cindex "underscore in EHLO/HELO"
 This option can be set to a string of rogue characters that are permitted in
 non-ip-literal EHLO and HELO names in addition to the standard letters, digits,

-hyphens, and dots. For examplem if you really must allow underscores,
+hyphens, and dots. For example if you really must allow underscores,

 you can set
 .code
 helo_allow_chars = _
 you can set
 .code
 helo_allow_chars = _


@@ -16614,17 +16650,15 @@ has been built with LDAP support.
 
 
 
 
 
 

-.new

 .option limits_advertise_hosts main "host list&!!" *
 .cindex LIMITS "suppressing advertising"
 .cindex "ESMTP extensions" LIMITS
 This option can be used to suppress the advertisement of the SMTP
 LIMITS extension (RFC 9422) to specific hosts.
 .option limits_advertise_hosts main "host list&!!" *
 .cindex LIMITS "suppressing advertising"
 .cindex "ESMTP extensions" LIMITS
 This option can be used to suppress the advertisement of the SMTP
 LIMITS extension (RFC 9422) to specific hosts.

-If permitted, Exim as a servier will advertise in the EHLO response
+If permitted, Exim as a server will advertise in the EHLO response

 the limit for RCPT commands set by the &%recipients_max%& option (if it is set)
 and the limit for MAIL commands set by the &%smtp_accept_max_per_connection%&
 option.
 the limit for RCPT commands set by the &%recipients_max%& option (if it is set)
 and the limit for MAIL commands set by the &%smtp_accept_max_per_connection%&
 option.

-.wen

 
 .option local_from_check main boolean true
 .cindex "&'Sender:'& header line" "disabling addition of"
 
 .option local_from_check main boolean true
 .cindex "&'Sender:'& header line" "disabling addition of"


@@ -17185,7 +17219,7 @@ See also the &%hosts_pipe_connect%& smtp transport option.
 
 The SMTP service extension keyword advertised is &"PIPECONNECT"&;
 it permits the client to pipeline
 
 The SMTP service extension keyword advertised is &"PIPECONNECT"&;
 it permits the client to pipeline

-TCP connection and hello command (inclear phase),
+TCP connection and hello command (cleatext phase),

 or TLS-establishment and hello command (encrypted phase),
 on later connections to the same host.
 
 or TLS-establishment and hello command (encrypted phase),
 on later connections to the same host.
 


@@ -17540,14 +17574,12 @@ all recipients over the limit; earlier recipients are delivered as normal.
 Non-SMTP messages with too many recipients are failed, and no deliveries are
 done.
 
 Non-SMTP messages with too many recipients are failed, and no deliveries are
 done.
 

-.new

 For SMTP message the expansion is done after the connection is
 accepted (but before any SMTP conversation) and may depend on
 the IP addresses and port numbers of the connection.
 &*Note*&: If an expansion is used for the option,
 care should be taken that a resonable value results for
 non-SMTP messages.
 For SMTP message the expansion is done after the connection is
 accepted (but before any SMTP conversation) and may depend on
 the IP addresses and port numbers of the connection.
 &*Note*&: If an expansion is used for the option,
 care should be taken that a resonable value results for
 non-SMTP messages.

-.wen

 
 .cindex "RCPT" "maximum number of incoming"
 &*Note*&: The RFCs specify that an SMTP server should accept at least 100
 
 .cindex "RCPT" "maximum number of incoming"
 &*Note*&: The RFCs specify that an SMTP server should accept at least 100


@@ -17755,8 +17787,7 @@ live with.
 . searchable.  NM changed this occurrence for bug 1197 to no longer allow
 . the option name to split.
 
 . searchable.  NM changed this occurrence for bug 1197 to no longer allow
 . the option name to split.
 

-.option "smtp_accept_max_per_connection" main integer&!! 1000 &&&
-         smtp_accept_max_per_connection
+.option smtp_accept_max_per_connection main integer&!! 1000

 .cindex "SMTP" "limiting incoming message count"
 .cindex "limit" "messages per SMTP connection"
 The value of this option limits the number of MAIL commands that Exim is
 .cindex "SMTP" "limiting incoming message count"
 .cindex "limit" "messages per SMTP connection"
 The value of this option limits the number of MAIL commands that Exim is


@@ -17810,8 +17841,7 @@ various &%-od%&&'x'& command line options.
 
 . See the comment on smtp_accept_max_per_connection
 
 
 . See the comment on smtp_accept_max_per_connection
 

-.option "smtp_accept_queue_per_connection" main integer 10 &&&
-         smtp_accept_queue_per_connection
+.option smtp_accept_queue_per_connection main integer 10

 .cindex "queueing incoming messages"
 .cindex "message" "queueing by message count"
 This option limits the number of delivery processes that Exim starts
 .cindex "queueing incoming messages"
 .cindex "message" "queueing by message count"
 This option limits the number of delivery processes that Exim starts


@@ -18941,13 +18971,11 @@ absolute and untainted.
 See also &%bounce_message_file%&.
 
 
 See also &%bounce_message_file%&.
 
 

-.new

 .option wellknown_advertise_hosts main boolean unset
 .cindex WELLKNOWN advertisement
 .cindex "ESMTP extensions" WELLKNOWN
 This option enables the advertising of the SMTP WELLKNOWN extension.
 See also the &%acl_smtp_wellknown%& ACL (&<<SECTWELLKNOWNACL>>&).
 .option wellknown_advertise_hosts main boolean unset
 .cindex WELLKNOWN advertisement
 .cindex "ESMTP extensions" WELLKNOWN
 This option enables the advertising of the SMTP WELLKNOWN extension.
 See also the &%acl_smtp_wellknown%& ACL (&<<SECTWELLKNOWNACL>>&).

-.wen

 
 .option write_rejectlog main boolean true
 .cindex "reject log" "disabling"
 
 .option write_rejectlog main boolean true
 .cindex "reject log" "disabling"


@@ -22223,6 +22251,12 @@ subject to address rewriting. Otherwise, they are treated like new addresses
 and are rewritten according to the global rewriting rules.
 
 
 and are rewritten according to the global rewriting rules.
 
 

+.option sieve_inbox redirect string&!! inbox
+.new
+The value of this option is passed to a Sieve filter to specify the
+name of the mailbox used for "keep" operations (explicit or implicit).
+.wen
+

 .option sieve_subaddress redirect string&!! unset
 The value of this option is passed to a Sieve filter to specify the
 :subaddress part of an address.
 .option sieve_subaddress redirect string&!! unset
 The value of this option is passed to a Sieve filter to specify the
 :subaddress part of an address.


@@ -23259,7 +23293,11 @@ fileinto "folder23";
 .endd
 In this situation, the expansion of &%file%& or &%directory%& in the transport
 must transform the relative path into an appropriate absolute filename. In the
 .endd
 In this situation, the expansion of &%file%& or &%directory%& in the transport
 must transform the relative path into an appropriate absolute filename. In the

-case of Sieve filters, the name &'inbox'& must be handled. It is the name that
+case of Sieve filters, the name &'inbox'& must be handled. It is the
+.new
+default
+.wen
+name that

 is used as a result of a &"keep"& action in the filter. This example shows one
 way of handling this requirement:
 .code
 is used as a result of a &"keep"& action in the filter. This example shows one
 way of handling this requirement:
 .code


@@ -23275,6 +23313,12 @@ With this setting of &%file%&, &'inbox'& refers to the standard mailbox
 location, absolute paths are used without change, and other folders are in the
 &_mail_& directory within the home directory.
 
 location, absolute paths are used without change, and other folders are in the
 &_mail_& directory within the home directory.
 

+.new
+An alternative for the &"keep"& aspect is to use the &%sieve_inbox%& option
+on the redirect router that calls the Sieve filter,
+to explicitly set the filename used.
+.wen
+

 &*Note 1*&: While processing an Exim filter, a relative path such as
 &_folder23_& is turned into an absolute path if a home directory is known to
 the router. In particular, this is the case if &%check_local_user%& is set. If
 &*Note 1*&: While processing an Exim filter, a relative path such as
 &_folder23_& is turned into an absolute path if a home directory is known to
 the router. In particular, this is the case if &%check_local_user%& is set. If


@@ -23285,6 +23329,10 @@ path to the transport.
 &*Note 2*&: An absolute path in &$address_file$& is not treated specially;
 the &%file%& or &%directory%& option is still used if it is set.
 
 &*Note 2*&: An absolute path in &$address_file$& is not treated specially;
 the &%file%& or &%directory%& option is still used if it is set.
 

+.new
+&*Note 3*&: Permitting a user to enable writes to an absolute path
+may be a security issue.
+.wen

 
 
 
 
 
 


@@ -25444,12 +25492,10 @@ over a single TCP/IP connection. If the value is zero, there is no limit.
 For testing purposes, this value can be overridden by the &%-oB%& command line
 option.
 
 For testing purposes, this value can be overridden by the &%-oB%& command line
 option.
 

-.new

 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a MAILMAX value,
 and either TLSS is in use or was not advertised,
 that value also constrains the result of this option.
 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a MAILMAX value,
 and either TLSS is in use or was not advertised,
 that value also constrains the result of this option.

-.wen

 
 
 .option dane_require_tls_ciphers smtp string&!! unset
 
 
 .option dane_require_tls_ciphers smtp string&!! unset


@@ -25674,12 +25720,10 @@ suffices for one known case.
 During the expansion of this option the &$item$& variable will have the
 server's EHLO response.
 
 During the expansion of this option the &$item$& variable will have the
 server's EHLO response.
 

-.new

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

-.wen

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


@@ -26027,13 +26071,11 @@ each set of addresses is treated independently, and
 so can cause parallel connections to the same host if &%remote_max_parallel%&
 permits this.
 
 so can cause parallel connections to the same host if &%remote_max_parallel%&
 permits this.
 

-.new

 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a RCPTMAX value,
 and either TLSS is in use or was not advertised,
 that value also constrains the result of this option
 and no parallel connections will be caused on meeting the RCPTMAX limit.
 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a RCPTMAX value,
 and either TLSS is in use or was not advertised,
 that value also constrains the result of this option
 and no parallel connections will be caused on meeting the RCPTMAX limit.

-.wen

 
 
 .option message_linelength_limit smtp integer 998
 
 
 .option message_linelength_limit smtp integer 998


@@ -26066,12 +26108,10 @@ If the connection is DANE-enabled then this option is ignored;
 only messages having the domain used for the DANE TLSA lookup are
 sent on the connection.
 
 only messages having the domain used for the DANE TLSA lookup are
 sent on the connection.
 

-.new

 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a RCPTDOMAINMAX value,
 and either TLSS is in use or was not advertised,
 this option is regarded as being false.
 .cindex "ESMTP extensions" LIMITS
 If the peer advertises a LIMITS extension with a RCPTDOMAINMAX value,
 and either TLSS is in use or was not advertised,
 this option is regarded as being false.

-.wen

 
 
 .option port smtp string&!! "see below"
 
 
 .option port smtp string&!! "see below"


@@ -26107,10 +26147,8 @@ protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local
 deliveries into closed message stores. Exim also has support for running LMTP
 over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
 
 deliveries into closed message stores. Exim also has support for running LMTP
 over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
 

-.new

 &*Note*&: When using LMTP it should be considered whether the default values
 for some other features, such as DANE, are appropriate.
 &*Note*&: When using LMTP it should be considered whether the default values
 for some other features, such as DANE, are appropriate.

-.wen

 
 If this option is set to &"smtps"&, the default value for the &%port%& option
 changes to &"smtps"&, and the transport initiates TLS immediately after
 
 If this option is set to &"smtps"&, the default value for the &%port%& option
 changes to &"smtps"&, and the transport initiates TLS immediately after


@@ -30896,7 +30934,6 @@ This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
 If the ACL is not defined, processing completes as if
 the feature was not requested by the client.
 
 If the ACL is not defined, processing completes as if
 the feature was not requested by the client.
 

-.new

 .subsection "The SMTP WELLKNOWN ACL" SECTWELLKNOWNACL
 .cindex "WELLKNOWN" "ACL for"
 .oindex "&%acl_smtp_wellknown%&"
 .subsection "The SMTP WELLKNOWN ACL" SECTWELLKNOWNACL
 .cindex "WELLKNOWN" "ACL for"
 .oindex "&%acl_smtp_wellknown%&"


@@ -30949,7 +30986,6 @@ and service WELLKNOWN smtp verbs having a single parameter
 giving a key for an item of "site-wide metadata".
 The verb and key are separated by whitespace,
 and the key is xtext-encoded (per RFC 3461 section 4).
 giving a key for an item of "site-wide metadata".
 The verb and key are separated by whitespace,
 and the key is xtext-encoded (per RFC 3461 section 4).

-.wen

 
 
 .subsection "The QUIT ACL" SECTQUITACL
 
 
 .subsection "The QUIT ACL" SECTQUITACL


@@ -31124,9 +31160,7 @@ when the ACL is not defined is &"accept"&.
 
 For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&,
 &%acl_smtp_vrfy%&
 
 For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&,
 &%acl_smtp_vrfy%&

-.new

 and &%acl_smtp_wellknown%&),
 and &%acl_smtp_wellknown%&),

-.wen

 the action when the ACL
 is not defined is &"deny"&.  This means that &%acl_smtp_rcpt%& must be
 defined in order to receive any messages over an SMTP connection.
 the action when the ACL
 is not defined is &"deny"&.  This means that &%acl_smtp_rcpt%& must be
 defined in order to receive any messages over an SMTP connection.


@@ -32021,12 +32055,17 @@ This control turns off DKIM verification processing entirely.  For details on
 the operation and configuration of DKIM, see section &<<SECDKIM>>&.
 
 
 the operation and configuration of DKIM, see section &<<SECDKIM>>&.
 
 

-.vitem &*control&~=&~dmarc_disable_verify*&
+.vitem &*control&~=&~dmarc_disable_verify*& &&&
+       &*control&~=&~dmarc_enable_forensic*&

 .cindex "disable DMARC verify"
 .cindex "disable DMARC verify"

-.cindex "DMARC" "disable verify"
-This control turns off DMARC verification processing entirely.  For details on
+.cindex DMARC "disable verify"
+.cindex DMARC controls
+.cindex DMARC "forensic mails"
+These control affect DMARC processing.  For details on

 the operation and configuration of DMARC, see section &<<SECDMARC>>&.
 
 the operation and configuration of DMARC, see section &<<SECDMARC>>&.
 

+The &"disable"& turns off DMARC verification processing entirely.
+

 
 .vitem &*control&~=&~dscp/*&<&'value'&>
 .cindex "&ACL;" "setting DSCP value"
 
 .vitem &*control&~=&~dscp/*&<&'value'&>
 .cindex "&ACL;" "setting DSCP value"


@@ -32236,12 +32275,10 @@ This control enables conversion of UTF-8 in message envelope addresses
 to a-label form.
 For details see section &<<SECTi18nMTA>>&.
 
 to a-label form.
 For details see section &<<SECTi18nMTA>>&.
 

-.new

 .vitem &*control&~=&~wellknown*&
 This control sets up a response data file for a WELLKNOWN SMTP command.
 It may only be used in an ACL servicing that command.
 For details see section &<<SECTWELLKNOWNACL>>&.
 .vitem &*control&~=&~wellknown*&
 This control sets up a response data file for a WELLKNOWN SMTP command.
 It may only be used in an ACL servicing that command.
 For details see section &<<SECTWELLKNOWNACL>>&.

-.wen

 .endlist vlist
 
 
 .endlist vlist
 
 


@@ -35232,11 +35269,9 @@ filename, and the default path is then used.
 .endlist
 The &%decode%& condition normally succeeds. It is only false for syntax
 errors or unusual circumstances such as memory shortages.
 .endlist
 The &%decode%& condition normally succeeds. It is only false for syntax
 errors or unusual circumstances such as memory shortages.

-.new

 The variable &$mime_filename$& will have the suggested name for the file.
 Note however that this might contain anything, and is very difficult
 to safely use as all or even part of the filename.
 The variable &$mime_filename$& will have the suggested name for the file.
 Note however that this might contain anything, and is very difficult
 to safely use as all or even part of the filename.

-.wen

 If you place files outside of the default path, they are not
 automatically unlinked.
 
 If you place files outside of the default path, they are not
 automatically unlinked.
 


@@ -35947,7 +35982,7 @@ The third argument may be NULL, in which case the &%-oMas%& option is omitted.
 
 
 .vitem &*void&~debug_printf(char&~*,&~...)*&
 
 
 .vitem &*void&~debug_printf(char&~*,&~...)*&

-This is Exim's debugging function, with arguments as for &'(printf()'&. The
+This is Exim's debugging function, with arguments as for &'printf()'&. The

 output is written to the standard error stream. If no debugging is selected,
 calls to &'debug_printf()'& have no effect. Normally, you should make calls
 conditional on the &`local_scan`& debug selector by coding like this:
 output is written to the standard error stream. If no debugging is selected,
 calls to &'debug_printf()'& have no effect. Normally, you should make calls
 conditional on the &`local_scan`& debug selector by coding like this:


@@ -37338,12 +37373,8 @@ See the next section for more detail about error handling.
 .cindex "SMTP" "batching over TCP/IP"
 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
 looks in the hints database for the transport to see if there are any queued
 .cindex "SMTP" "batching over TCP/IP"
 When a message is successfully delivered over a TCP/IP SMTP connection, Exim
 looks in the hints database for the transport to see if there are any queued

-messages waiting for the host to which it is connected. If it finds one, it
-creates a new Exim process using the &%-MC%& option (which can only be used by
-a process running as root or the Exim user) and passes the TCP/IP socket to it
-so that it can deliver another message using the same socket. The new process
-does only those deliveries that are routed to the connected host, and may in
-turn pass the socket on to a third process, and so on.
+messages waiting for the host to which it is connected.
+If it finds one, it arranges to attempt that message on the same connection.

 
 The &%connection_max_messages%& option of the &(smtp)& transport can be used to
 limit the number of messages sent down a single TCP/IP connection.
 
 The &%connection_max_messages%& option of the &(smtp)& transport can be used to
 limit the number of messages sent down a single TCP/IP connection.


@@ -37681,6 +37712,14 @@ RCPT failures.
 .subsection "The ETRN command" SECTETRN
 .cindex "ETRN" "processing"
 .cindex "ESMTP extensions" ETRN
 .subsection "The ETRN command" SECTETRN
 .cindex "ETRN" "processing"
 .cindex "ESMTP extensions" ETRN

+Most modern installations never need to use this.
+It is used for managing messages queued for an intermittently-connecting
+destination (eg. one using a dialup connection).
+
+.oindex "&%acl_smtp_etrn%&"
+The command is only available if permitted by an ACL
+specfied by the main-section &%acl_smtp_etrn%& option.
+

 RFC 1985 describes an ESMTP command called ETRN that is designed to
 overcome the security problems of the TURN command (which has fallen into
 disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs
 RFC 1985 describes an ESMTP command called ETRN that is designed to
 overcome the security problems of the TURN command (which has fallen into
 disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs


@@ -39361,17 +39400,19 @@ because the arguments are checked before the configuration file is read. The
 only way to log such cases is to interpose a script such as &_util/logargs.sh_&
 between the caller and Exim.
 .next
 only way to log such cases is to interpose a script such as &_util/logargs.sh_&
 between the caller and Exim.
 .next

-.cindex "log" "connection identifier"
-&%connection_identifier%&: An identifier for the accepted connection is added to
+.cindex log "connection identifier"
+.cindex connection "identifier logging"
+&%connection_id%&: An identifier for the accepted connection is added to

 connection start and end lines and to message accept lines.
 The identifier is tagged by Ci=.
 The value is PID-based, so will reset on reboot and will wrap.
 .next
 connection start and end lines and to message accept lines.
 The identifier is tagged by Ci=.
 The value is PID-based, so will reset on reboot and will wrap.
 .next

-.cindex "log" "connection rejections"
+.cindex log "connection rejections"
+.cindex connection "rejection logging"

 &%connection_reject%&: A log entry is written whenever an incoming SMTP
 connection is rejected, for whatever reason.
 .next
 &%connection_reject%&: A log entry is written whenever an incoming SMTP
 connection is rejected, for whatever reason.
 .next

-.cindex "log" "delayed delivery"
+.cindex log "delayed delivery"

 .cindex "delayed delivery, logging"
 &%delay_delivery%&: A log entry is written whenever a delivery process is not
 started for an incoming message because the load is too high or too many
 .cindex "delayed delivery, logging"
 &%delay_delivery%&: A log entry is written whenever a delivery process is not
 started for an incoming message because the load is too high or too many


@@ -39397,10 +39438,8 @@ verifies successfully a tag of DKIM is added, with one of the verified domains.
 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim_verbose%&: A log entry is written for each attempted DKIM verification.
 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim_verbose%&: A log entry is written for each attempted DKIM verification.

-.new

 Also, on message delivery lines signing information (domain and selector)
 is added, tagged with DKIM=.
 Also, on message delivery lines signing information (domain and selector)
 is added, tagged with DKIM=.

-.wen

 .next
 .cindex "log" "dnslist defer"
 .cindex "DNS list" "logging defer"
 .next
 .cindex "log" "dnslist defer"
 .cindex "DNS list" "logging defer"


@@ -40295,8 +40334,6 @@ for remote hosts
 The &'misc'& database is used for
 
 .ilist
 The &'misc'& database is used for
 
 .ilist

-Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)
-.next

 Serializing delivery to a specific host (when &%serialize_hosts%& is set in an
 &(smtp)& transport)
 .next
 Serializing delivery to a specific host (when &%serialize_hosts%& is set in an
 &(smtp)& transport)
 .next


@@ -40304,11 +40341,13 @@ Limiting the concurrency of specific transports (when &%max_parallel%& is set
 in a transport)
 .next
 Recording EHLO-time facilities advertised by hosts
 in a transport)
 .next
 Recording EHLO-time facilities advertised by hosts

+.next
+Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)

 .endlist
 
 
 
 .endlist
 
 
 

-.section "exim_dumpdb" "SECTdumpdb"
+.subsection "exim_dumpdb" "SECTdumpdb"

 .cindex "&'exim_dumpdb'&"
 The entire contents of a database are written to the standard output by the
 &'exim_dumpdb'& program,
 .cindex "&'exim_dumpdb'&"
 The entire contents of a database are written to the standard output by the
 &'exim_dumpdb'& program,


@@ -40350,7 +40389,7 @@ cross-references.
 
 
 
 
 
 

-.section "exim_tidydb" "SECTtidydb"
+.subsection "exim_tidydb" "SECTtidydb"

 .cindex "&'exim_tidydb'&"
 The &'exim_tidydb'& utility program is used to tidy up the contents of a hints
 database. If run with no options, it removes all records that are more than 30
 .cindex "&'exim_tidydb'&"
 The &'exim_tidydb'& utility program is used to tidy up the contents of a hints
 database. If run with no options, it removes all records that are more than 30


@@ -40399,7 +40438,7 @@ databases is likely to keep on increasing.
 
 
 
 
 
 

-.section "exim_fixdb" "SECTfixdb"
+.subsection "exim_fixdb" "SECTfixdb"

 .cindex "&'exim_fixdb'&"
 The &'exim_fixdb'& program is a utility for interactively modifying databases.
 Its main use is for testing Exim, but it might also be occasionally useful for
 .cindex "&'exim_fixdb'&"
 The &'exim_fixdb'& program is a utility for interactively modifying databases.
 Its main use is for testing Exim, but it might also be occasionally useful for


@@ -41748,10 +41787,8 @@ Exim's DKIM implementation allows for
 Signing outgoing messages: This function is implemented in the SMTP transport.
 It can co-exist with all other Exim features
 (including transport filters) except cutthrough delivery.
 Signing outgoing messages: This function is implemented in the SMTP transport.
 It can co-exist with all other Exim features
 (including transport filters) except cutthrough delivery.

-.new

 However, signing options may not depend on headers modified by
 routers, the transport or a transport filter.
 However, signing options may not depend on headers modified by
 routers, the transport or a transport filter.

-.wen

 .next
 Verifying signatures in incoming messages: This is implemented by an additional
 ACL (acl_smtp_dkim), which can be called several times per message, with
 .next
 Verifying signatures in incoming messages: This is implemented by an additional
 ACL (acl_smtp_dkim), which can be called several times per message, with


@@ -41959,11 +41996,9 @@ name will be appended.
 .option dkim_timestamps smtp integer&!! unset
 This option controls the inclusion of timestamp information in the signature.
 If not set, no such information will be included.
 .option dkim_timestamps smtp integer&!! unset
 This option controls the inclusion of timestamp information in the signature.
 If not set, no such information will be included.

-.new

 Otherwise, must be an unsigned number giving an offset in seconds from the
 current time for the expiry tag (e.g. 1209600 for two weeks); both creation
 (t=) and expiry (x=) tags will be included unless the offset is 0 (no expiry).
 Otherwise, must be an unsigned number giving an offset in seconds from the
 current time for the expiry tag (e.g. 1209600 for two weeks); both creation
 (t=) and expiry (x=) tags will be included unless the offset is 0 (no expiry).

-.wen

 
 RFC 6376 lists these tags as RECOMMENDED.
 
 
 RFC 6376 lists these tags as RECOMMENDED.
 


@@ -42237,9 +42272,7 @@ for that check for empty &$h_DKIM-Signature:$& in the data ACL.
 ACL condition that checks a colon-separated list of possible DKIM verification
 results against the actual result of verification,
 given by &$dkim_verify_status$& if that is non-empty or "none" if empty.
 ACL condition that checks a colon-separated list of possible DKIM verification
 results against the actual result of verification,
 given by &$dkim_verify_status$& if that is non-empty or "none" if empty.

-.new

 This condition may be used in DKIM, MIME, PRDR and DATA ACLs.
 This condition may be used in DKIM, MIME, PRDR and DATA ACLs.

-.wen

 
 A basic verification might be:
 .code
 
 A basic verification might be:
 .code


@@ -42261,9 +42294,7 @@ see the documentation of the &%$dkim_verify_status%& expansion variable above
 for more information of what they mean.
 
 The condition is true if the status
 for more information of what they mean.
 
 The condition is true if the status

-.new

 (or any of the list of status values)
 (or any of the list of status values)

-.wen

 is any one of the supplied list.
 .endlist
 
 is any one of the supplied list.
 .endlist
 


@@ -42288,6 +42319,12 @@ This includes retransmissions done by traditional forwarders.
 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
 &_Local/Makefile_&.  The support uses the &_libspf2_& library
 &url(https://www.libspf2.org/).
 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
 &_Local/Makefile_&.  The support uses the &_libspf2_& library
 &url(https://www.libspf2.org/).

+.new
+.cindex "dynamic modules"
+The support can be built as a dynamic-load module if desired;
+see the comments in that Makefile.
+.wen
+

 There is no Exim involvement in the transmission of messages;
 publishing certain DNS records is all that is required.
 
 There is no Exim involvement in the transmission of messages;
 publishing certain DNS records is all that is required.
 


@@ -43149,7 +43186,6 @@ expansion must check this, as it will be called for every possible event type.
 
 .new
 The current list of events is:
 
 .new
 The current list of events is:

-.wen

 .itable all 0 0 4 25* left 10* center 15* center 50* left
 .row auth:fail             after    both       "per driver per authentication attempt"
 .row dane:fail              after    transport  "per connection"
 .itable all 0 0 4 25* left 10* center 15* center 50* left
 .row auth:fail             after    both       "per driver per authentication attempt"
 .row dane:fail              after    transport  "per connection"


@@ -43168,7 +43204,10 @@ The current list of events is:
 .row tls:fail:connect       after    main       "per connection"
 .row smtp:connect           after    transport  "per connection"
 .row smtp:ehlo              after    transport  "per connection"
 .row tls:fail:connect       after    main       "per connection"
 .row smtp:connect           after    transport  "per connection"
 .row smtp:ehlo              after    transport  "per connection"

+.row smtp:fail:protocol     after    main       "per connection"
+.row smtp:fail:syntax       after    main       "per connection"

 .endtable
 .endtable

+.wen

 New event types may be added in future.
 
 The event name is a colon-separated list, defining the type of
 New event types may be added in future.
 
 The event name is a colon-separated list, defining the type of


@@ -43184,6 +43223,7 @@ should define the event action.
 
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:
 
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:

+.new

 .itable all 0 0 2 20* left 80* left
 .row auth:fail           "smtp response"
 .row dane:fail            "failure reason"
 .itable all 0 0 2 20* left 80* left
 .row auth:fail           "smtp response"
 .row dane:fail            "failure reason"


@@ -43199,7 +43239,10 @@ with the event type:
 .row tls:fail:connect     "error string"
 .row smtp:connect         "smtp banner"
 .row smtp:ehlo            "smtp ehlo response"
 .row tls:fail:connect     "error string"
 .row smtp:connect         "smtp banner"
 .row smtp:ehlo            "smtp ehlo response"

+.row smtp:fail:protocol   "error string"
+.row smtp:fail:syntax     "error string"

 .endtable
 .endtable

+.wen

 
 The :defer events populate one extra variable: &$event_defer_errno$&.
 
 
 The :defer events populate one extra variable: &$event_defer_errno$&.
 


@@ -43237,10 +43280,8 @@ chain element received on the connection.
 For OpenSSL it will trigger for every chain element including those
 loaded locally.
 
 For OpenSSL it will trigger for every chain element including those
 loaded locally.
 

-.new

 For dns:fail events from dnsdb lookups, a &"defer_never"& option does not
 affect the reporting of DNS_AGAIN.
 For dns:fail events from dnsdb lookups, a &"defer_never"& option does not
 affect the reporting of DNS_AGAIN.

-.wen

 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////