Add options dnssec_request_domains, dnssec_require_domains to the smtp transport

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c00469b0dd674e1110a595aef6b0d165d3402b90..0ecbaac5a9d3de3e421b11e108364fca73b25b00 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6959,11 +6959,16 @@ The data from each lookup is concatenated, with newline separators by default,
 in the same way that multiple DNS records for a single item are handled. A
 different separator can be specified, as described above.
 
 in the same way that multiple DNS records for a single item are handled. A
 different separator can be specified, as described above.
 

+Modifiers for &(dnsdb)& lookups are givien by optional keywords,
+each followed by a comma,
+that may appear before the record type.
+

 The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a
 temporary DNS error for any of them, the behaviour is controlled by
 The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a
 temporary DNS error for any of them, the behaviour is controlled by

-an optional keyword followed by a comma that may appear before the record
-type. The possible keywords are &"defer_strict"&, &"defer_never"&, and
-&"defer_lax"&. With &"strict"& behaviour, any temporary DNS error causes the
+a defer-option modifier.
+The possible keywords are
+&"defer_strict"&, &"defer_never"&, and &"defer_lax"&.
+With &"strict"& behaviour, any temporary DNS error causes the

 whole lookup to defer. With &"never"& behaviour, a temporary DNS error is
 ignored, and the behaviour is as if the DNS lookup failed to find anything.
 With &"lax"& behaviour, all the queries are attempted, but a temporary DNS
 whole lookup to defer. With &"never"& behaviour, a temporary DNS error is
 ignored, and the behaviour is as if the DNS lookup failed to find anything.
 With &"lax"& behaviour, all the queries are attempted, but a temporary DNS


@@ -6976,6 +6981,21 @@ ${lookup dnsdb{a=one.host.com:two.host.com}}
 Thus, in the default case, as long as at least one of the DNS lookups
 yields some data, the lookup succeeds.
 
 Thus, in the default case, as long as at least one of the DNS lookups
 yields some data, the lookup succeeds.
 

+.new
+.cindex "DNSSEC" "dns lookup"
+Use of &(DNSSEC)& is controlled by a dnssec modifier.
+The possible keywords are
+&"dnssec_strict"&, &"dnssec_lax"&, and &"dnssec_never"&.
+With &"strict"& or &"lax"& DNSSEC information is requested
+with the lookup.
+With &"strict"& a response from the DNS resolver that
+is not labelled as authenticated data
+is treated as equivalent to a temporary DNS error.
+The default is &"never"&.
+
+See also the &$lookup_dnssec_authenticated$& variable.
+.wen
+

 
 
 
 
 
 


@@ -7198,6 +7218,9 @@ them. The following names are recognized:
 &`USER       `&  set the DN, for authenticating the LDAP bind
 &`PASS       `&  set the password, likewise
 &`REFERRALS  `&  set the referrals parameter
 &`USER       `&  set the DN, for authenticating the LDAP bind
 &`PASS       `&  set the password, likewise
 &`REFERRALS  `&  set the referrals parameter

+.new
+&`SERVERS    `&  set alternate server list for this query only
+.wen

 &`SIZE       `&  set the limit for the number of entries returned
 &`TIME       `&  set the maximum waiting time for a query
 .endd
 &`SIZE       `&  set the limit for the number of entries returned
 &`TIME       `&  set the maximum waiting time for a query
 .endd


@@ -7219,6 +7242,15 @@ Netscape SDK; for OpenLDAP no action is taken.
 The TIME parameter (also a number of seconds) is passed to the server to
 set a server-side limit on the time taken to complete a search.
 
 The TIME parameter (also a number of seconds) is passed to the server to
 set a server-side limit on the time taken to complete a search.
 

+.new
+The SERVERS parameter allows you to specify an alternate list of ldap servers
+to use for an individual lookup.  The global ldap_servers option provides a
+default list of ldap servers, and a single lookup can specify a single ldap
+server to use.  But when you need to do a lookup with a list of servers that is
+different than the default list (maybe different order, maybe a completely
+different set of servers), the SERVERS parameter allows you to specify this
+alternate list.
+.wen

 
 Here is an example of an LDAP query in an Exim lookup that uses some of these
 values. This is a single line, folded to fit on the page:
 
 Here is an example of an LDAP query in an Exim lookup that uses some of these
 values. This is a single line, folded to fit on the page:


@@ -8298,7 +8330,14 @@ Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same
 list. The effect of each one lasts until the next, or until the end of the
 list.
 
 list. The effect of each one lasts until the next, or until the end of the
 list.
 

-To explain the host/ip processing logic a different way for the same ACL:
+.new
+.section "Mixing wildcarded host names and addresses in host lists" &&&
+         "SECTmixwilhos"
+.cindex "host list" "mixing names and addresses in"
+
+This section explains the host/ip processing logic with the same concepts
+as the previous section, but specifically addresses what happens when a
+wildcarded hostname is one of the items in the hostlist.

 
 .ilist
 If you have name lookups or wildcarded host names and
 
 .ilist
 If you have name lookups or wildcarded host names and


@@ -8327,7 +8366,7 @@ If the first &%accept%& fails, Exim goes on to try the second one. See chapter
 &`+ignore_unknown`&, which was discussed in depth in the first example in
 this section.
 .endlist
 &`+ignore_unknown`&, which was discussed in depth in the first example in
 this section.
 .endlist

-
+.wen

 
 
 .section "Temporary DNS errors when looking up host information" &&&
 
 
 .section "Temporary DNS errors when looking up host information" &&&


@@ -8399,33 +8438,6 @@ See section &<<SECThoslispatsikey>>&.)
 
 
 
 
 
 

-.section "Mixing wildcarded host names and addresses in host lists" &&&
-         "SECTmixwilhos"
-.cindex "host list" "mixing names and addresses in"
-If you have name lookups or wildcarded host names and IP addresses in the same
-host list, you should normally put the IP addresses first. For example, in an
-ACL you could have:
-.code
-accept hosts = 10.9.8.7 : *.friend.example
-.endd
-The reason for this lies in the left-to-right way that Exim processes lists.
-It can test IP addresses without doing any DNS lookups, but when it reaches an
-item that requires a host name, it fails if it cannot find a host name to
-compare with the pattern. If the above list is given in the opposite order, the
-&%accept%& statement fails for a host whose name cannot be found, even if its
-IP address is 10.9.8.7.
-
-If you really do want to do the name check first, and still recognize the IP
-address, you can rewrite the ACL like this:
-.code
-accept hosts = *.friend.example
-accept hosts = 10.9.8.7
-.endd
-If the first &%accept%& fails, Exim goes on to try the second one. See chapter
-&<<CHAPACL>>& for details of ACLs.
-
-
-

 
 
 .section "Address lists" "SECTaddresslist"
 
 
 .section "Address lists" "SECTaddresslist"


@@ -11441,6 +11453,16 @@ ability to find the amount of free space (only true for experimental systems),
 the space value is -1. See also the &%check_log_space%& option.
 
 
 the space value is -1. See also the &%check_log_space%& option.
 
 

+.new
+.vitem &$lookup_dnssec_authenticated$&
+.vindex "&$lookup_dnssec_authenticated$&"
+This variable is set after a DNS lookup done by
+a dnsdb lookup expansion, dnslookup router or smtp transport.
+It will be empty if &(DNSSEC)& was not requested,
+&"no"& if the result was not labelled as authenticated data
+and &"yes"& if it was.
+.wen
+

 .vitem &$mailstore_basename$&
 .vindex "&$mailstore_basename$&"
 This variable is set only when doing deliveries in &"mailstore"& format in the
 .vitem &$mailstore_basename$&
 .vindex "&$mailstore_basename$&"
 This variable is set only when doing deliveries in &"mailstore"& format in the


@@ -16747,11 +16769,12 @@ and the discussion in chapter &<<CHAPenvironment>>&.
 
 
 
 
 
 

-.option headers_add routers string&!! unset
+.option headers_add routers list&!! unset

 .cindex "header lines" "adding"
 .cindex "router" "adding header lines"
 .cindex "header lines" "adding"
 .cindex "router" "adding header lines"

-This option specifies a string of text that is expanded at routing time, and
-associated with any addresses that are accepted by the router. However, this
+This option specifies a list of text headers, newline-separated,
+that is associated with any addresses that are accepted by the router.
+Each item is separately expanded, at routing time.  However, this

 option has no effect when an address is just being verified. The way in which
 the text is used to add header lines at transport time is described in section
 &<<SECTheadersaddrem>>&. New header lines are not actually added until the
 option has no effect when an address is just being verified. The way in which
 the text is used to add header lines at transport time is described in section
 &<<SECTheadersaddrem>>&. New header lines are not actually added until the


@@ -16760,8 +16783,8 @@ header lines in string expansions in the transport's configuration do not
 &"see"& the added header lines.
 
 The &%headers_add%& option is expanded after &%errors_to%&, but before
 &"see"& the added header lines.
 
 The &%headers_add%& option is expanded after &%errors_to%&, but before

-&%headers_remove%& and &%transport%&. If the expanded string is empty, or if
-the expansion is forced to fail, the option has no effect. Other expansion
+&%headers_remove%& and &%transport%&. If an item is empty, or if
+an item expansion is forced to fail, the item has no effect. Other expansion

 failures are treated as configuration errors.
 
 Unlike most options, &%headers_add%& can be specified multiple times
 failures are treated as configuration errors.
 
 Unlike most options, &%headers_add%& can be specified multiple times


@@ -16783,11 +16806,12 @@ avoided. The &%repeat_use%& option of the &%redirect%& router may be of help.
 
 
 
 
 
 

-.option headers_remove routers string&!! unset
+.option headers_remove routers list&!! unset

 .cindex "header lines" "removing"
 .cindex "router" "removing header lines"
 .cindex "header lines" "removing"
 .cindex "router" "removing header lines"

-This option specifies a string of text that is expanded at routing time, and
-associated with any addresses that are accepted by the router. However, this
+This option specifies a list of text headers, colon-separated,
+that is associated with any addresses that are accepted by the router.
+Each item is separately expanded, at routing time.  However, this

 option has no effect when an address is just being verified. The way in which
 the text is used to remove header lines at transport time is described in
 section &<<SECTheadersaddrem>>&. Header lines are not actually removed until
 option has no effect when an address is just being verified. The way in which
 the text is used to remove header lines at transport time is described in
 section &<<SECTheadersaddrem>>&. Header lines are not actually removed until


@@ -16796,8 +16820,8 @@ to header lines in string expansions in the transport's configuration still
 &"see"& the original header lines.
 
 The &%headers_remove%& option is expanded after &%errors_to%& and
 &"see"& the original header lines.
 
 The &%headers_remove%& option is expanded after &%errors_to%& and

-&%headers_add%&, but before &%transport%&. If the expansion is forced to fail,
-the option has no effect. Other expansion failures are treated as configuration
+&%headers_add%&, but before &%transport%&. If an item expansion is forced to fail,
+the item has no effect. Other expansion failures are treated as configuration

 errors.
 
 Unlike most options, &%headers_remove%& can be specified multiple times
 errors.
 
 Unlike most options, &%headers_remove%& can be specified multiple times


@@ -17640,6 +17664,33 @@ when there is a DNS lookup error.
 
 
 
 
 
 

+.new
+.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 A6, AAAA, A lookup sequence.
+.wen
+
+
+
+.new
+.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 A6, AAAA, A lookup sequence.
+.wen
+
+
+

 .option mx_domains dnslookup "domain list&!!" unset
 .cindex "MX record" "required to exist"
 .cindex "SRV record" "required to exist"
 .option mx_domains dnslookup "domain list&!!" unset
 .cindex "MX record" "required to exist"
 .cindex "SRV record" "required to exist"


@@ -19797,10 +19848,11 @@ value that the router supplies, and also overriding any value associated with
 &%user%& (see below).
 
 
 &%user%& (see below).
 
 

-.option headers_add transports string&!! unset
+.option headers_add transports list&!! unset

 .cindex "header lines" "adding in transport"
 .cindex "transport" "header lines; adding"
 .cindex "header lines" "adding in transport"
 .cindex "transport" "header lines; adding"

-This option specifies a string of text that is expanded and added to the header
+This option specifies a list of text headers, newline-separated,
+which are (separately) expanded and added to the header

 portion of a message as it is transported, as described in section
 &<<SECTheadersaddrem>>&. Additional header lines can also be specified by
 routers. If the result of the expansion is an empty string, or if the expansion
 portion of a message as it is transported, as described in section
 &<<SECTheadersaddrem>>&. Additional header lines can also be specified by
 routers. If the result of the expansion is an empty string, or if the expansion


@@ -19821,18 +19873,20 @@ transports, the settings of &%message_prefix%& and &%message_suffix%& should be
 checked, since this option does not automatically suppress them.
 
 
 checked, since this option does not automatically suppress them.
 
 

-.option headers_remove transports string&!! unset
+.option headers_remove transports list&!! unset

 .cindex "header lines" "removing"
 .cindex "transport" "header lines; removing"
 .cindex "header lines" "removing"
 .cindex "transport" "header lines; removing"

-This option specifies a string that is expanded into a list of header names;
+This option specifies a list of header names, colon-separated;

 these headers are omitted from the message as it is transported, as described
 in section &<<SECTheadersaddrem>>&. Header removal can also be specified by
 these headers are omitted from the message as it is transported, as described
 in section &<<SECTheadersaddrem>>&. Header removal can also be specified by

-routers. If the result of the expansion is an empty string, or if the expansion
+routers.
+Each list item is separately expanded.
+If the result of the expansion is an empty string, or if the expansion

 is forced to fail, no action is taken. Other expansion failures are treated as
 errors and cause the delivery to be deferred.
 
 Unlike most options, &%headers_remove%& can be specified multiple times
 is forced to fail, no action is taken. Other expansion failures are treated as
 errors and cause the delivery to be deferred.
 
 Unlike most options, &%headers_remove%& can be specified multiple times

-for a router; all listed headers are added.
+for a router; all listed headers are removed.

 
 
 
 
 
 


@@ -22540,6 +22594,33 @@ See the &%search_parents%& option in chapter &<<CHAPdnslookup>>& for more
 details.
 
 
 details.
 
 

+.new
+.option dnssec_request_domains smtp "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 A6, AAAA, A lookup sequence.
+.wen
+
+
+
+.new
+.option dnssec_require_domains smtp "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 A6, AAAA, A lookup sequence.
+.wen
+
+
+

 .option dscp smtp string&!! unset
 .cindex "DCSP" "outbound"
 This option causes the DSCP value associated with a socket to be set to one
 .option dscp smtp string&!! unset
 .cindex "DCSP" "outbound"
 This option causes the DSCP value associated with a socket to be set to one


@@ -31983,7 +32064,7 @@ they do not affect the values of the variables that refer to header lines.
 the transport cannot refer to the modified header lines, because such
 expansions all occur before the message is actually transported.
 
 the transport cannot refer to the modified header lines, because such
 expansions all occur before the message is actually transported.
 

-For both routers and transports, the result of expanding a &%headers_add%&
+For both routers and transports, the argument of a &%headers_add%&

 option must be in the form of one or more RFC 2822 header lines, separated by
 newlines (coded as &"\n"&). For example:
 .code
 option must be in the form of one or more RFC 2822 header lines, separated by
 newlines (coded as &"\n"&). For example:
 .code


@@ -31993,10 +32074,10 @@ headers_add = X-added-header: added by $primary_hostname\n\
 Exim does not check the syntax of these added header lines.
 
 Multiple &%headers_add%& options for a single router or transport can be
 Exim does not check the syntax of these added header lines.
 
 Multiple &%headers_add%& options for a single router or transport can be

-specified; the values will be concatenated (with a separating newline
-added) before expansion.
+specified; the values will append to a single list of header lines.
+Each header-line is separately expanded.

 
 

-The result of expanding &%headers_remove%& must consist of a colon-separated
+The argument of a &%headers_remove%& option must consist of a colon-separated

 list of header names. This is confusing, because header names themselves are
 often terminated by colons. In this case, the colons are the list separators,
 not part of the names. For example:
 list of header names. This is confusing, because header names themselves are
 often terminated by colons. In this case, the colons are the list separators,
 not part of the names. For example:


@@ -32005,11 +32086,12 @@ headers_remove = return-receipt-to:acknowledge-to
 .endd
 
 Multiple &%headers_remove%& options for a single router or transport can be
 .endd
 
 Multiple &%headers_remove%& options for a single router or transport can be

-specified; the values will be concatenated (with a separating colon
-added) before expansion.
+specified; the arguments will append to a single header-names list.
+Each item is separately expanded.

 
 

-When &%headers_add%& or &%headers_remove%& is specified on a router, its value
-is expanded at routing time, and then associated with all addresses that are
+When &%headers_add%& or &%headers_remove%& is specified on a router,
+items are expanded at routing time,
+and then associated with all addresses that are

 accepted by that router, and also with any new addresses that it generates. If
 an address passes through several routers as a result of aliasing or
 forwarding, the changes are cumulative.
 accepted by that router, and also with any new addresses that it generates. If
 an address passes through several routers as a result of aliasing or
 forwarding, the changes are cumulative.


@@ -34647,9 +34729,17 @@ This utility is a Perl script contributed by Matt Hubbard. It runs
 .code
 exim -bpu
 .endd
 .code
 exim -bpu
 .endd

-to obtain a queue listing with undelivered recipients only, and then greps the
-output to select messages that match given criteria. The following selection
-options are available:
+or (in case &*-a*& switch is specified)
+.code
+exim -bp
+.endd
+.new
+The &*-C*& option is used to specify an alternate &_exim.conf_& which might
+contain alternate exim configuration the queue management might be using.
+.wen
+
+to obtain a queue listing, and then greps the output to select messages 
+that match given criteria. The following selection options are available:

 
 .vlist
 .vitem &*-f*&&~<&'regex'&>
 
 .vlist
 .vitem &*-f*&&~<&'regex'&>


@@ -34696,6 +34786,9 @@ Brief format &-- one line per message.
 
 .vitem &*-R*&
 Display messages in reverse order.
 
 .vitem &*-R*&
 Display messages in reverse order.

+
+.vitem &*-a*&
+Include delivered recipients in queue listing.

 .endlist
 
 There is one more option, &%-h%&, which outputs a list of options.
 .endlist
 
 There is one more option, &%-h%&, which outputs a list of options.