X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/be36e5721725253b7529899884d7fe8ecd5120b9..aec45841f9139404fd61122e3db1401b13ebb0a8:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 69009e92d..d3a28a40a 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9698,6 +9698,37 @@ the regular expression from string expansion.
 
 
 
+.new
+.vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&
+.cindex sorting a list
+.cindex list sorting
+After expansion, <&'string'&> is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way.
+The <&'comparator'&> argument is interpreted as the operator
+of a two-argument expansion condition.
+The numeric operators plus ge, gt, le, lt (and ~i variants) are supported.
+The comparison should return true when applied to two values
+if the first value should sort before the second value.
+The <&'extractor'&> expansion is applied repeatedly to elements of the list,
+the element being placed in &$item$&,
+to give values for comparison.
+
+The item result is a sorted list,
+with the original list separator,
+of the list elements (in full) of the original.
+
+Examples:
+.code
+${sort{3:2:1:4}{<}{$item}}
+.endd
+sorts a list of numbers, and
+.code
+${sort {$lookup dnsdb{>:,,mx=example.com}} {<} {${listextract{1}{<,$item}}}}
+.endd
+will sort an MX lookup into priority order.
+.wen
+
+
 .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
 .cindex "&%substr%& expansion item"
 .cindex "substring extraction"
@@ -12561,6 +12592,13 @@ This variable contains the result of an expansion lookup, extraction operation,
 or external command, as described above. It is also used during a
 &*reduce*& expansion.
 
+.vitem &$verify_mode$&
+.vindex "&$verify_mode$&"
+While a router or transport is being run in verify mode
+or for cutthrough delivery,
+contains "S" for sender-verification or "R" for recipient-verification.
+Otherwise, empty.
+
 .vitem &$version_number$&
 .vindex "&$version_number$&"
 The version number of Exim.
@@ -16453,9 +16491,11 @@ See &%tls_verify_hosts%& below.
 The value of this option is expanded, and must then be the absolute path to
 a file containing permitted certificates for clients that
 match &%tls_verify_hosts%& or &%tls_try_verify_hosts%&. Alternatively, if you
-are using OpenSSL, you can set &%tls_verify_certificates%& to the name of a
-directory containing certificate files. This does not work with GnuTLS; the
-option must be set to the name of a single file if you are using GnuTLS.
+are using either GnuTLS version 3.3.6 (or later) or OpenSSL,
+you can set &%tls_verify_certificates%& to the name of a
+directory containing certificate files.
+For earlier versions of GnuTLS
+the option must be set to the name of a single file.
 
 These certificates should be for the certificate authorities trusted, rather
 than the public cert of individual clients.  With both OpenSSL and GnuTLS, if
@@ -16835,7 +16875,7 @@ be specified using &%condition%&.
 Historical note: We have &%condition%& on ACLs and on Routers.  Routers
 are far older, and use one set of semantics.  ACLs are newer and when
 they were created, the ACL &%condition%& process was given far stricter
-parse semantics.  The &%bool{}&% expansion condition uses the same rules as
+parse semantics.  The &%bool{}%& expansion condition uses the same rules as
 ACLs.  The &%bool_lax{}%& expansion condition uses the same rules as
 Routers.  More pointedly, the &%bool_lax{}%& was written to match the existing
 Router rules processing behavior.
@@ -17746,6 +17786,7 @@ delivering in cutthrough mode
 or testing recipient verification using &%-bv%&.
 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
 are evaluated.
+See also the &$verify_mode$& variable.
 
 
 .option verify_sender routers&!? boolean true
@@ -17753,6 +17794,7 @@ If this option is false, the router is skipped when verifying sender addresses
 or testing sender verification using &%-bvs%&.
 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
 are evaluated.
+See also the &$verify_mode$& variable.
 .ecindex IIDgenoprou1
 .ecindex IIDgenoprou2
 
@@ -23401,10 +23443,14 @@ certificate verification succeeds.
 .vindex "&$host_address$&"
 The value of this option must be the absolute path to a file containing
 permitted server certificates, for use when setting up an encrypted connection.
-Alternatively, if you are using OpenSSL, you can set
+Alternatively,
+if you are using either GnuTLS version 3.3.6 (or later) or OpenSSL,
+you can set
 &%tls_verify_certificates%& to the name of a directory containing certificate
-files. This does not work with GnuTLS; the option must be set to the name of a
-single file if you are using GnuTLS. The values of &$host$& and
+files.
+For earlier versions of GnuTLS the option must be set to the name of a
+single file.
+The values of &$host$& and
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
 
@@ -25886,7 +25932,8 @@ There are some differences in usage when using GnuTLS instead of OpenSSL:
 
 .ilist
 The &%tls_verify_certificates%& option must contain the name of a file, not the
-name of a directory (for OpenSSL it can be either).
+name of a directory for GnuTLS versions before 3.3.6
+(for later versions, or OpenSSL, it can be either).
 .next
 The default value for &%tls_dhparam%& differs for historical reasons.
 .next
@@ -26278,7 +26325,7 @@ an identically named option for the &(smtp)& transport. In each case, the value
 of the option is expanded and must then be the name of a file that contains a
 CRL in PEM format.
 The downside is that clients have to periodically re-download a potentially huge
-file from every certificate authority the know of.
+file from every certificate authority they know of.
 
 The way with most moving parts at query time is Online Certificate
 Status Protocol (OCSP), where the client verifies the certificate
@@ -28276,6 +28323,8 @@ can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9,
 and $acl_narg is set to the count of values.
 Previous values of these variables are restored after the call returns.
 The name and values are expanded separately.
+Note that spaces in complex expansions which are used as arguments
+will act as argument separators.
 
 If the nested &%acl%& returns &"drop"& and the outer condition denies access,
 the connection is dropped. If it returns &"discard"&, the verb must be
@@ -32489,6 +32538,9 @@ headers_remove = return-receipt-to:acknowledge-to
 Multiple &%headers_remove%& options for a single router or transport can be
 specified; the arguments will append to a single header-names list.
 Each item is separately expanded.
+Note that colons in complex expansions which are used to
+form all or part of a &%headers_remove%& list
+will act as list separators.
 
 When &%headers_add%& or &%headers_remove%& is specified on a router,
 items are expanded at routing time,
@@ -35242,9 +35294,11 @@ given message, or all mail for a given user, or for a given host, for example.
 The input files can be in Exim log format or syslog format.
 If a matching log line is not associated with a specific message, it is
 included in &'exigrep'&'s output without any additional lines. The usage is:
+.new
 .display
-&`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`&
+&`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-M] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`&
 .endd
+.wen
 If no log file names are given on the command line, the standard input is read.
 
 The &%-t%& argument specifies a number of seconds. It adds an additional
@@ -35264,6 +35318,21 @@ regular expression.
 The &%-v%& option inverts the matching condition. That is, a line is selected
 if it does &'not'& match the pattern.
 
+.new
+The &%-M%& options means &"related messages"&. &'exigrep'& will show messages
+that are generated as a result/response to a message that &'exigrep'& matched
+normally.
+
+Example of &%-M%&:
+user_a sends a message to user_b, which generates a bounce back to user_b. If
+&'exigrep'& is used to search for &"user_a"&, only the first message will be
+displayed.  But if &'exigrep'& is used to search for &"user_b"&, the first and
+the second (bounce) message will be displayed. Using &%-M%& with &'exigrep'&
+when searching for &"user_a"& will show both messages since the bounce is
+&"related"& to or a &"result"& of the first message that was found by the
+search term.
+.wen
+
 If the location of a &'zcat'& command is known from the definition of
 ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file
 whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it.