Routing: dnslookup and manualroute routers: ipv4_only, ipv4_prefer options. Bug...

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index aa6da73d3bed0422741f26e0f891ae9da8e8a773..7ad6f0275dde96911b6be03512e56aba6e973ef1 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -14693,6 +14693,7 @@ If the resolver library does not support DNSSEC then this option has no effect.
 .option dns_ipv4_lookup main "domain list&!!" unset
 .cindex "IPv6" "DNS lookup for AAAA records"
 .cindex "DNS" "IPv6 lookup for AAAA records"
 .option dns_ipv4_lookup main "domain list&!!" unset
 .cindex "IPv6" "DNS lookup for AAAA records"
 .cindex "DNS" "IPv6 lookup for AAAA records"

+.cindex DNS "IPv6 disabling"

 When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it
 looks for IPv6 address records (AAAA records) as well as IPv4 address records
 (A records) when trying to find IP addresses for hosts, unless the host's
 When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it
 looks for IPv6 address records (AAAA records) as well as IPv4 address records
 (A records) when trying to find IP addresses for hosts, unless the host's


@@ -18745,7 +18746,9 @@ records.
 MX records of equal priority are sorted by Exim into a random order. Exim then
 looks for address records for the host names obtained from MX or SRV records.
 When a host has more than one IP address, they are sorted into a random order,
 MX records of equal priority are sorted by Exim into a random order. Exim then
 looks for address records for the host names obtained from MX or SRV records.
 When a host has more than one IP address, they are sorted into a random order,

-except that IPv6 addresses are always sorted before IPv4 addresses. If all the
+.new
+except that IPv6 addresses are sorted before IPv4 addresses. If all the
+.wen

 IP addresses found are discarded by a setting of the &%ignore_target_hosts%&
 generic option, the router declines.
 
 IP addresses found are discarded by a setting of the &%ignore_target_hosts%&
 generic option, the router declines.
 


@@ -18878,6 +18881,24 @@ However, it will result in any message with mistyped domains
 also being queued.
 
 
 also being queued.
 
 

+.new
+.option ipv4_only "string&!!" unset
+.cindex IPv6 disabling
+.cindex DNS "IPv6 disabling"
+The string is expanded, and if the result is anything but a forced failure,
+or an empty string, or one of the strings “0” or “no” or “false”
+(checked without regard to the case of the letters),
+only A records are used.
+
+.option ipv4_prefer "string&!!" unset
+.cindex IPv4 preference
+.cindex DNS "IPv4 preference"
+The string is expanded, and if the result is anything but a forced failure,
+or an empty string, or one of the strings “0” or “no” or “false”
+(checked without regard to the case of the letters),
+A records are sorted before AAAA records (inverting the default).
+.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"


@@ -19482,8 +19503,8 @@ whether obtained from an MX lookup or not.
 
 
 .section "How the options are used" "SECThowoptused"
 
 
 .section "How the options are used" "SECThowoptused"

-The options are a sequence of words; in practice no more than three are ever
-present. One of the words can be the name of a transport; this overrides the
+The options are a sequence of words, space-separated.
+One of the words can be the name of a transport; this overrides the

 &%transport%& option on the router for this particular routing rule only. The
 other words (if present) control randomization of the list of hosts on a
 per-rule basis, and how the IP addresses of the hosts are to be found when
 &%transport%& option on the router for this particular routing rule only. The
 other words (if present) control randomization of the list of hosts on a
 per-rule basis, and how the IP addresses of the hosts are to be found when


@@ -19503,6 +19524,12 @@ also look in &_/etc/hosts_& or other sources of information.
 &%bydns%&: look up address records for the hosts directly in the DNS; fail if
 no address records are found. If there is a temporary DNS error (such as a
 timeout), delivery is deferred.
 &%bydns%&: look up address records for the hosts directly in the DNS; fail if
 no address records are found. If there is a temporary DNS error (such as a
 timeout), delivery is deferred.

+.new
+.next
+&%ipv4_only%&: in direct DNS lookups, look up only A records.
+.next
+&%ipv4_prefer%&: in direct DNS lookups, sort A records before AAAA records.
+.wen

 .endlist
 
 For example:
 .endlist
 
 For example:


@@ -36077,6 +36104,7 @@ the following table:
 &`    `&        on &"Completed"& lines: time spent on queue
 &`R   `&        on &`<=`& lines: reference for local bounce
 &`    `&        on &`=>`&  &`>>`& &`**`& and &`==`& lines: router name
 &`    `&        on &"Completed"& lines: time spent on queue
 &`R   `&        on &`<=`& lines: reference for local bounce
 &`    `&        on &`=>`&  &`>>`& &`**`& and &`==`& lines: router name

+&`RT  `&        on &`<=`& lines: time taken for reception

 &`S   `&        size of message in bytes
 &`SNI `&        server name indication from TLS client hello
 &`ST  `&        shadow transport name
 &`S   `&        size of message in bytes
 &`SNI `&        server name indication from TLS client hello
 &`ST  `&        shadow transport name


@@ -36171,7 +36199,7 @@ selection marked by asterisks:
 &` incoming_interface         `&  local interface on <= and => lines
 &` incoming_port              `&  remote port on <= lines
 &`*lost_incoming_connection   `&  as it says (includes timeouts)
 &` incoming_interface         `&  local interface on <= and => lines
 &` incoming_port              `&  remote port on <= lines
 &`*lost_incoming_connection   `&  as it says (includes timeouts)

-&` millisec                   `&  millisecond timestamps and QT,DT,D times
+&` millisec                   `&  millisecond timestamps and RT,QT,DT,D times

 &` outgoing_interface         `&  local interface on => lines
 &` outgoing_port              `&  add remote port to => lines
 &`*queue_run                  `&  start and end queue runs
 &` outgoing_interface         `&  local interface on => lines
 &` outgoing_port              `&  add remote port to => lines
 &`*queue_run                  `&  start and end queue runs


@@ -36262,7 +36290,7 @@ process is started because &%queue_only%& is set or &%-odq%& was used.
 &%deliver_time%&: For each delivery, the amount of real time it has taken to
 perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.
 If millisecond logging is enabled, short times will be shown with greater
 &%deliver_time%&: For each delivery, the amount of real time it has taken to
 perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.
 If millisecond logging is enabled, short times will be shown with greater

-precision, eg. &`DT=0.304`&.
+precision, eg. &`DT=0.304s`&.

 .next
 .cindex "log" "message size on delivery"
 .cindex "size" "of message"
 .next
 .cindex "log" "message size on delivery"
 .cindex "size" "of message"


@@ -36400,6 +36428,14 @@ precision, eg. &`QT=1.578s`&.
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
 example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
 message, so it includes reception time as well as the total delivery time.
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
 example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
 message, so it includes reception time as well as the total delivery time.

+.new
+.next
+.cindex "log" "receive duration"
+&%receive_time%&: For each message, the amount of real time it has taken to
+perform the reception is logged as RT=<&'time'&>, for example, &`RT=1s`&.
+If millisecond logging is enabled, short times will be shown with greater
+precision, eg. &`RT=0.204s`&.
+.wen

 .next
 .cindex "log" "recipients"
 &%received_recipients%&: The recipients of a message are listed in the main log
 .next
 .cindex "log" "recipients"
 &%received_recipients%&: The recipients of a message are listed in the main log


@@ -38551,8 +38587,12 @@ In typical Exim style, the verification implementation does not include any
 default "policy". Instead it enables you to build your own policy using
 Exim's standard controls.
 
 default "policy". Instead it enables you to build your own policy using
 Exim's standard controls.
 

+.new

 Please note that verification of DKIM signatures in incoming mail is turned
 Please note that verification of DKIM signatures in incoming mail is turned

-on by default for logging purposes. For each signature in incoming email,
+on by default for logging (in the <= line) purposes.
+
+Additional log detail can be enabled using the &%dkim_verbose%& log_selector.
+When set, for each signature in incoming email,

 exim will log a line displaying the most important signature details, and the
 signature status. Here is an example (with line-breaks added for clarity):
 .code
 exim will log a line displaying the most important signature details, and the
 signature status. Here is an example (with line-breaks added for clarity):
 .code


@@ -38561,6 +38601,8 @@ signature status. Here is an example (with line-breaks added for clarity):
     c=relaxed/relaxed a=rsa-sha1
     i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd
     c=relaxed/relaxed a=rsa-sha1
     i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd

+.wen
+

 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
 control modifier. This should typically be done in the RCPT ACL, at points
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
 control modifier. This should typically be done in the RCPT ACL, at points


@@ -38571,6 +38613,18 @@ senders).
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 

+.new
+For signing to be usable you must have published a DKIM record in DNS.
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+.endd
+.wen
+.wen
+

 Signing is enabled by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.
 
 Signing is enabled by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.
 


@@ -38579,7 +38633,8 @@ The domain(s) you want to sign with.
 After expansion, this can be a list.
 Each element in turn is put into the &%$dkim_domain%& expansion variable
 while expanding the remaining signing options.
 After expansion, this can be a list.
 Each element in turn is put into the &%$dkim_domain%& expansion variable
 while expanding the remaining signing options.

-If it is empty after expansion, DKIM signing is not done.
+If it is empty after expansion, DKIM signing is not done,
+and no error will result even if &%dkim_strict%& is set.

 
 .option dkim_selector smtp string list&!! unset
 This sets the key selector string.
 
 .option dkim_selector smtp string list&!! unset
 This sets the key selector string.


@@ -38587,7 +38642,8 @@ After expansion, which can use &$dkim_domain$&, this can be a list.
 Each element in turn is put in the expansion
 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.
 Each element in turn is put in the expansion
 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.

-If the option is empty after expansion, DKIM signing is not done for this domain.
+If the option is empty after expansion, DKIM signing is not done for this domain,
+and no error will result even if &%dkim_strict%& is set.

 
 .option dkim_private_key smtp string&!! unset
 This sets the private key to use.
 
 .option dkim_private_key smtp string&!! unset
 This sets the private key to use.


@@ -38604,11 +38660,25 @@ be "0", "false" or the empty string, in which case the message will not
 be signed. This case will not result in an error, even if &%dkim_strict%&
 is set.
 .endlist
 be signed. This case will not result in an error, even if &%dkim_strict%&
 is set.
 .endlist

-If the option is empty after expansion, DKIM signing is not done.
+
+.new
+Note that RFC 8301 says:
+.code
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+.endd
+.wen

 
 .option dkim_hash smtp string&!! sha256
 Can be set alternatively to &"sha1"& to use an alternate hash
 
 .option dkim_hash smtp string&!! sha256
 Can be set alternatively to &"sha1"& to use an alternate hash

-method.  Note that sha1 is now condidered insecure, and deprecated.
+method.
+
+.new
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+.endd
+.wen

 
 .option dkim_identity smtp string&!! unset
 If set after expansion, the value is used to set an "i=" tag in
 
 .option dkim_identity smtp string&!! unset
 If set after expansion, the value is used to set an "i=" tag in


@@ -38762,7 +38832,7 @@ re-written or otherwise changed in a way which is incompatible with
 DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 
 DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 

-This variable can be overwritten using an ACL 'set' modifier.
+This variable can be overwritten, with any value, using an ACL 'set' modifier.

 
 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is
 
 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is


@@ -38780,6 +38850,19 @@ The key record selector string.
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 

+.new
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+
+DKIM signatures identified as having been signed with historic
+algorithms (currently, rsa-sha1) have permanently failed evaluation
+.endd
+
+To enforce this you must have a DKIM ACL which checks this variable
+and overwrites the &$dkim_verify_status$& variable as discussed above.
+.wen
+

 .vitem &%$dkim_canon_body%&
 The body canonicalization method. One of 'relaxed' or 'simple'.
 
 .vitem &%$dkim_canon_body%&
 The body canonicalization method. One of 'relaxed' or 'simple'.
 


@@ -38830,6 +38913,18 @@ Notes from the key record (tag n=).
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.

+
+.new
+Note that RFC 8301 says:
+.code
+Verifiers MUST NOT consider signatures using RSA keys of
+less than 1024 bits as valid signatures.
+.endd
+
+To enforce this you must have a DKIM ACL which checks this variable
+and overwrites the &$dkim_verify_status$& variable as discussed above.
+.wen
+

 .endlist
 
 In addition, two ACL conditions are provided:
 .endlist
 
 In addition, two ACL conditions are provided: