tidying

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 8bf643632ca243754d1d7269f54903055b888ea2..d4ebf464d7fc7f593bedd4a00a0dc42536bbcf5e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6878,16 +6878,9 @@ is used on its own as the result. If the lookup does not succeed, the
 &`fail`& keyword causes a &'forced expansion failure'& &-- see section
 &<<SECTforexpfai>>& for an explanation of what this means.
 
 &`fail`& keyword causes a &'forced expansion failure'& &-- see section
 &<<SECTforexpfai>>& for an explanation of what this means.
 

-The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and TXT,
-and, when Exim is compiled with IPv6 support, AAAA.
-If no type is given, TXT is assumed. When the type is PTR,
-the data can be an IP address, written as normal; inversion and the addition of
-&%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example:
-.code
-${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
-.endd
-If the data for a PTR record is not a syntactically valid IP address, it is not
-altered and nothing is added.
+The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
+and TXT, and, when Exim is compiled with IPv6 support, AAAA.
+If no type is given, TXT is assumed.

 
 For any record type, if multiple records are found, the data is returned as a
 concatenation, with newline as the default separator. The order, of course,
 
 For any record type, if multiple records are found, the data is returned as a
 concatenation, with newline as the default separator. The order, of course,


@@ -6899,21 +6892,33 @@ ${lookup dnsdb{>: a=host1.example}}
 .endd
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 .endd
 It is permitted to specify a space as the separator character. Further
 white space is ignored.

+For lookup types that return multiple fields per record,
+an alternate field separator can be specified using a comma after the main
+separator character, followed immediately by the field separator.
+
+.cindex "PTR record" "in &(dnsdb)& lookup"
+When the type is PTR,
+the data can be an IP address, written as normal; inversion and the addition of
+&%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example:
+.code
+${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
+.endd
+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.
 
 .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.

-An alternate field separator can be specified using a comma after the main
-separator character, followed immediately by the field separator.
+The field separator can be modified as above.

 
 .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,
 
 .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,

-unless a separator for them is specified using a comma after the separator
-character followed immediately by the TXT record item separator. To concatenate
-items without a separator, use a semicolon instead. For SPF records the
+unless a field separator is specified.
+To concatenate items without a separator, use a semicolon instead.
+For SPF records the

 default behaviour is to concatenate multiple items without using a separator.
 .code
 ${lookup dnsdb{>\n,: txt=a.b.example}}
 default behaviour is to concatenate multiple items without using a separator.
 .code
 ${lookup dnsdb{>\n,: txt=a.b.example}}


@@ -6923,6 +6928,15 @@ ${lookup dnsdb{spf=example.org}}
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 

+.cindex "SOA record" "in &(dnsdb)& lookup"
+For an SOA lookup, while no result is obtained the lookup is redone with
+successively more leading components dropped from the given domain.
+Only the primary-nameserver field is returned unless a field separator is
+specified.
+.code
+${lookup dnsdb{>:,; soa=a.b.example.com}}
+.endd
+

 .section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
 .cindex "dnsdb modifiers"
 .cindex "modifiers" "dnsdb"
 .section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
 .cindex "dnsdb modifiers"
 .cindex "modifiers" "dnsdb"


@@ -6962,6 +6976,17 @@ The default is &"never"&.
 
 See also the &$lookup_dnssec_authenticated$& variable.
 
 
 See also the &$lookup_dnssec_authenticated$& variable.
 

+.cindex timeout "dns lookup"
+.cindex "DNS" timeout
+Timeout for the dnsdb lookup can be controlled by a retrans modifier.
+The form is &"retrans_VAL"& where VAL is an Exim time specification
+(eg &"5s"&).
+The default value is set by the main configuration option &%dns_retrans%&.
+
+Retries for the dnsdb lookup can be controlled by a retry modifier.
+The form if &"retry_VAL"& where VAL is an integer.
+The default count is set by the main configuration option &%dns_retry%&.
+

 
 .section "Pseudo dnsdb record types" "SECID66"
 .cindex "MX record" "in &(dnsdb)& lookup"
 
 .section "Pseudo dnsdb record types" "SECID66"
 .cindex "MX record" "in &(dnsdb)& lookup"


@@ -8940,7 +8965,7 @@ The field selectors marked as "RFC4514" above
 output a Distinguished Name string which is
 not quite
 parseable by Exim as a comma-separated tagged list
 output a Distinguished Name string which is
 not quite
 parseable by Exim as a comma-separated tagged list

-(the exceptions being elements containin commas).
+(the exceptions being elements containing commas).

 RDN elements of a single type may be selected by
 a modifier of the type label; if so the expansion
 result is a list (newline-separated by default).
 RDN elements of a single type may be selected by
 a modifier of the type label; if so the expansion
 result is a list (newline-separated by default).


@@ -9711,8 +9736,9 @@ the regular expression from string expansion.
 
 
 .vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&
 
 
 .vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&

-.cindex sorting a list
+.cindex sorting "a list"

 .cindex list sorting
 .cindex list sorting

+.cindex expansion "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
 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


@@ -13175,6 +13201,7 @@ listed in more than one group.
 .row &%message_logs%&                "create per-message logs"
 .row &%preserve_message_logs%&       "after message completion"
 .row &%process_log_path%&            "for SIGUSR1 and &'exiwhat'&"
 .row &%message_logs%&                "create per-message logs"
 .row &%preserve_message_logs%&       "after message completion"
 .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"
 .row &%syslog_facility%&             "set syslog &""facility""& field"
 .row &%syslog_processname%&          "set syslog &""ident""& field"
 .row &%syslog_duplication%&          "controls duplicate log lines on syslog"
 .row &%syslog_facility%&             "set syslog &""facility""& field"
 .row &%syslog_processname%&          "set syslog &""ident""& field"


@@ -14154,6 +14181,8 @@ servers have all been upgraded, there should be no need for this option.
 
 .option dns_retrans main time 0s
 .cindex "DNS" "resolver options"
 
 .option dns_retrans main time 0s
 .cindex "DNS" "resolver options"

+.cindex timeout "dns lookup"
+.cindex "DNS" timeout

 The options &%dns_retrans%& and &%dns_retry%& can be used to set the
 retransmission and retry parameters for DNS lookups. Values of zero (the
 defaults) leave the system default settings unchanged. The first value is the
 The options &%dns_retrans%& and &%dns_retry%& can be used to set the
 retransmission and retry parameters for DNS lookups. Values of zero (the
 defaults) leave the system default settings unchanged. The first value is the


@@ -14163,6 +14192,7 @@ take. I haven't found any documentation about timeouts on DNS lookups; these
 parameter values are available in the external resolver interface structure,
 but nowhere does it seem to describe how they are used or what you might want
 to set in them.
 parameter values are available in the external resolver interface structure,
 but nowhere does it seem to describe how they are used or what you might want
 to set in them.

+See also the &%slow_lookup_log%& option.

 
 
 .option dns_retry main integer 0
 
 
 .option dns_retry main integer 0


@@ -15722,6 +15752,16 @@ it qualifies them only if the message came from a host that matches
 using TCP/IP), and the &%-bnq%& option was not set.
 
 
 using TCP/IP), and the &%-bnq%& option was not set.
 
 

+.option slow_lookup_log main integer 0
+.cindex "logging" "slow lookups"
+.cindex "dns" "logging slow lookups"
+This option controls logging of slow lookups.
+If the value is nonzero it is taken as a number of milliseconds
+and lookups taking longer than this are logged.
+Currently this applies only to DNS lookups.
+
+
+

 .option smtp_accept_keepalive main boolean true
 .cindex "keepalive" "on incoming connection"
 This option controls the setting of the SO_KEEPALIVE option on incoming
 .option smtp_accept_keepalive main boolean true
 .cindex "keepalive" "on incoming connection"
 This option controls the setting of the SO_KEEPALIVE option on incoming


@@ -17018,6 +17058,25 @@ or for any deliveries caused by this router. You should not set this option
 unless you really, really know what you are doing. See also the generic
 transport option of the same name.
 
 unless you really, really know what you are doing. See also the generic
 transport option of the same name.
 

+.option dnssec_request_domains routers "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set.
+This applies to all of the SRV, MX, AAAA, A lookup sequence.
+
+.option dnssec_require_domains routers "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set.  Any returns not having the Authenticated Data bit
+(AD bit) set will be ignored and logged as a host-lookup failure.
+This applies to all of the SRV, MX, AAAA, A lookup sequence.
+

 
 .option domains routers&!? "domain list&!!" unset
 .cindex "router" "restricting to specific domains"
 
 .option domains routers&!? "domain list&!!" unset
 .cindex "router" "restricting to specific domains"


@@ -17989,6 +18048,9 @@ There are a few cases where a &(dnslookup)& router will decline to accept
 an address; if such a router is expected to handle "all remaining non-local
 domains", then it is important to set &%no_more%&.
 
 an address; if such a router is expected to handle "all remaining non-local
 domains", then it is important to set &%no_more%&.
 

+The router will defer rather than decline if the domain
+is found in the &%fail_defer_domains%& router option.
+

 Reasons for a &(dnslookup)& router to decline currently include:
 .ilist
 The domain does not exist in DNS
 Reasons for a &(dnslookup)& router to decline currently include:
 .ilist
 The domain does not exist in DNS


@@ -18067,27 +18129,16 @@ when there is a DNS lookup error.
 
 
 
 
 
 

-.option dnssec_request_domains dnslookup "domain list&!!" unset
-.cindex "MX record" "security"
-.cindex "DNSSEC" "MX lookup"
-.cindex "security" "MX lookup"
-.cindex "DNS" "DNSSEC"
-DNS lookups for domains matching &%dnssec_request_domains%& will be done with
-the dnssec request bit set.
-This applies to all of the SRV, MX, AAAA, A lookup sequence.
-
-
-
-.option dnssec_require_domains dnslookup "domain list&!!" unset
-.cindex "MX record" "security"
-.cindex "DNSSEC" "MX lookup"
-.cindex "security" "MX lookup"
-.cindex "DNS" "DNSSEC"
-DNS lookups for domains matching &%dnssec_request_domains%& will be done with
-the dnssec request bit set.  Any returns not having the Authenticated Data bit
-(AD bit) set wil be ignored and logged as a host-lookup failure.
-This applies to all of the SRV, MX, AAAA, A lookup sequence.

 
 

+.option fail_defer_domains dnslookup "domain list&!!" unset
+.cindex "MX record" "not found"
+DNS lookups for domains matching &%fail_defer_domains%&
+which find no matching record will cause the router to defer
+rather than the default behaviour of decline.
+This maybe be useful for queueing messages for a newly created
+domain while the DNS configuration is not ready.
+However, it will result in any message with mistyped domains
+also being queued.

 
 
 .option mx_domains dnslookup "domain list&!!" unset
 
 
 .option mx_domains dnslookup "domain list&!!" unset


@@ -23176,12 +23227,13 @@ that matches this list, even if the server host advertises PIPELINING support.
 Exim will not try to start a TLS session when delivering to any host that
 matches this list. See chapter &<<CHAPTLS>>& for details of TLS.
 
 Exim will not try to start a TLS session when delivering to any host that
 matches this list. See chapter &<<CHAPTLS>>& for details of TLS.
 

-.option hosts_verify_avoid_tls smtp "host list&!!" *
+.new
+.option hosts_verify_avoid_tls smtp "host list&!!" unset

 .cindex "TLS" "avoiding for certain hosts"
 Exim will not try to start a TLS session for a verify callout,
 or when delivering in cutthrough mode,
 to any host that matches this list.
 .cindex "TLS" "avoiding for certain hosts"
 Exim will not try to start a TLS session for a verify callout,
 or when delivering in cutthrough mode,
 to any host that matches this list.

-Note that the default is to not use TLS.
+.wen

 
 
 .option hosts_max_try smtp integer 5
 
 
 .option hosts_max_try smtp integer 5


@@ -24360,6 +24412,13 @@ A server unexpectedly closed the SMTP connection. There may, of course,
 legitimate reasons for this (host died, network died), but if it repeats a lot
 for the same host, it indicates something odd.
 
 legitimate reasons for this (host died, network died), but if it repeats a lot
 for the same host, it indicates something odd.
 

+.vitem &%lookup%&
+A DNS lookup for a host failed.
+Note that a &%dnslookup%& router will need to have matched
+its &%fail_defer_domains%& option for this retry type to be usable.
+Also note that a &%manualroute%& router will probably need
+its &%host_find_failed%& option set to &%defer%&.
+

 .vitem &%refused_MX%&
 A connection to a host obtained from an MX record was refused.
 
 .vitem &%refused_MX%&
 A connection to a host obtained from an MX record was refused.
 


@@ -31138,7 +31197,8 @@ containing the decoded data.
 This is perhaps the most important of the MIME variables. It contains a
 proposed filename for an attachment, if one was found in either the
 &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be
 This is perhaps the most important of the MIME variables. It contains a
 proposed filename for an attachment, if one was found in either the
 &'Content-Type:'& or &'Content-Disposition:'& headers. The filename will be

-RFC2047 decoded, but no additional sanity checks are done. If no filename was
+RFC2047 or RFC2231 decoded, but no additional sanity checks are done.
+ If no filename was

 found, this variable contains the empty string.
 
 .vitem &$mime_is_coverletter$&
 found, this variable contains the empty string.
 
 .vitem &$mime_is_coverletter$&


@@ -35693,6 +35753,8 @@ search term.
 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.
 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.

+If the ZCAT_COMMAND is not executable, &'exigrep'& tries to use
+autodetection of some well known compression extensions.

 
 
 .section "Selecting messages by various criteria (exipick)" "SECTexipick"
 
 
 .section "Selecting messages by various criteria (exipick)" "SECTexipick"