X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/d69645bc124ce675326b0778d261962791855b38..0160bfb8f6435449f80ccd8a8d20a0d749c0624d:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 2a52666f6..e3df0854e 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6875,12 +6875,6 @@ ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} If the data for a PTR record is not a syntactically valid IP address, it is not altered and nothing is added. -.cindex "MX record" "in &(dnsdb)& lookup" -.cindex "SRV record" "in &(dnsdb)& lookup" -For an MX lookup, both the preference value and the host name are returned for -each record, separated by a space. For an SRV lookup, the priority, weight, -port, and host name are returned for each record, separated by spaces. - For any record type, if multiple records are found (or, for A6 lookups, if a single record leads to multiple addresses), the data is returned as a concatenation, with newline as the default separator. The order, of course, @@ -6893,6 +6887,16 @@ ${lookup dnsdb{>: a=host1.example}} It is permitted to specify a space as the separator character. Further white space is ignored. +.cindex "MX record" "in &(dnsdb)& lookup" +.cindex "SRV record" "in &(dnsdb)& lookup" +For an MX lookup, both the preference value and the host name are returned for +each record, separated by a space. For an SRV lookup, the priority, weight, +port, and host name are returned for each record, separated by spaces. +.new +An alternate field separator can be specified using a comma after the main +separator character, followed immediately by the field separator. +.wen + .cindex "TXT record" "in &(dnsdb)& lookup" .cindex "SPF record" "in &(dnsdb)& lookup" For TXT records with multiple items of data, only the first item is returned, @@ -9694,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" @@ -16449,9 +16484,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 @@ -16831,7 +16868,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. @@ -23397,10 +23434,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 &<>& for details of TLS. @@ -25882,7 +25923,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 @@ -26274,7 +26316,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 @@ -28272,6 +28314,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 @@ -32485,6 +32529,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, @@ -35238,9 +35285,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 @@ -35260,6 +35309,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.