Add retrans/retry options to dnsdb lookup. Bug 1539
[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt
index 8bf643632ca243754d1d7269f54903055b888ea2..535e81ee643fdda3c378d877629aebab14d97cdc 100644 (file)
@@ -6962,6 +6962,17 @@ The default is &"never"&.
 
 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"
@@ -13175,6 +13186,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 &%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"
@@ -14154,6 +14166,8 @@ servers have all been upgraded, there should be no need for this option.
 
 .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
@@ -14163,6 +14177,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.
+See also the &%slow_lookup_log%& option.
 
 
 .option dns_retry main integer 0
@@ -15722,6 +15737,16 @@ it qualifies them only if the message came from a host that matches
 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
@@ -17018,6 +17043,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.
 
+.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 wil 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"
@@ -17989,6 +18033,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%&.
 
+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
@@ -18067,27 +18114,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
@@ -23176,12 +23212,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.
 
-.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.
-Note that the default is to not use TLS.
+.wen
 
 
 .option hosts_max_try smtp integer 5
@@ -24360,6 +24397,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.
 
+.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.
 
@@ -31138,7 +31182,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
-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$&
@@ -35693,6 +35738,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 ZCAT_COMMAND is not executable, &'exigrep'& tries to use
+autodetection of some well known compression extensions.
 
 
 .section "Selecting messages by various criteria (exipick)" "SECTexipick"