De-duplicate two documentation sections

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index abf69a00de0ff260b022cdacee696c3fb8706445..04678b4808c3e40ef28177174f20893c901fbb74 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8298,7 +8298,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 +8334,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 +8406,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"


@@ -10171,6 +10151,14 @@ number of larger units and output in Exim's normal time format, for example,
 .cindex "expansion" "case forcing"
 .cindex "&%uc%& expansion item"
 This forces the letters in the string into upper-case.
 .cindex "expansion" "case forcing"
 .cindex "&%uc%& expansion item"
 This forces the letters in the string into upper-case.

+
+.vitem &*${utf8clean:*&<&'string'&>&*}*&
+.cindex "correction of invalid utf-8 sequences in strings"
+.cindex "utf-8" "utf-8 sequences"
+.cindex "incorrect utf-8"
+.cindex "expansion" "utf-8 forcing"
+.cindex "&%utf8clean%& expansion item"
+This replaces any invalid utf-8 sequence in the string by the character &`?`&.

 .endlist
 
 
 .endlist
 
 


@@ -10239,7 +10227,7 @@ If the ACL returns defer the result is a forced-fail.
 .cindex "&%bool%& expansion condition"
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
 .cindex "&%bool%& expansion condition"
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&

-(case-insensitively); also positive integer numbers map to true if non-zero,
+(case-insensitively); also integer numbers map to true if non-zero,

 false if zero.
 An empty string is treated as false.
 Leading and trailing whitespace is ignored;
 false if zero.
 An empty string is treated as false.
 Leading and trailing whitespace is ignored;


@@ -11978,7 +11966,7 @@ other times, this variable is false.
 It is likely that you will need to coerce DNSSEC support on in the resolver
 library, by setting:
 .code
 It is likely that you will need to coerce DNSSEC support on in the resolver
 library, by setting:
 .code

-dns_use_dnssec = 1
+dns_dnssec_ok = 1

 .endd
 
 Exim does not perform DNSSEC validation itself, instead leaving that to a
 .endd
 
 Exim does not perform DNSSEC validation itself, instead leaving that to a


@@ -13190,10 +13178,10 @@ See also the &'Policy controls'& section above.
 .row &%disable_ipv6%&                "do no IPv6 processing"
 .row &%dns_again_means_nonexist%&    "for broken domains"
 .row &%dns_check_names_pattern%&     "pre-DNS syntax check"
 .row &%disable_ipv6%&                "do no IPv6 processing"
 .row &%dns_again_means_nonexist%&    "for broken domains"
 .row &%dns_check_names_pattern%&     "pre-DNS syntax check"

+.row &%dns_dnssec_ok%&               "parameter for resolver"

 .row &%dns_ipv4_lookup%&             "only v4 lookup for these domains"
 .row &%dns_retrans%&                 "parameter for resolver"
 .row &%dns_retry%&                   "parameter for resolver"
 .row &%dns_ipv4_lookup%&             "only v4 lookup for these domains"
 .row &%dns_retrans%&                 "parameter for resolver"
 .row &%dns_retry%&                   "parameter for resolver"

-.row &%dns_use_dnssec%&              "parameter for resolver"

 .row &%dns_use_edns0%&               "parameter for resolver"
 .row &%hold_domains%&                "hold delivery for these domains"
 .row &%local_interfaces%&            "for routing checks"
 .row &%dns_use_edns0%&               "parameter for resolver"
 .row &%hold_domains%&                "hold delivery for these domains"
 .row &%local_interfaces%&            "for routing checks"


@@ -13814,6 +13802,17 @@ This option controls whether or not an IP address, given as a CSA domain, is
 reversed and looked up in the reverse DNS, as described in more detail in
 section &<<SECTverifyCSA>>&.
 
 reversed and looked up in the reverse DNS, as described in more detail in
 section &<<SECTverifyCSA>>&.
 

+
+.option dns_dnssec_ok main integer -1
+.cindex "DNS" "resolver options"
+.cindex "DNS" "DNSSEC"
+If this option is set to a non-negative number then Exim will initialise the
+DNS resolver library to either use or not use DNSSEC, overriding the system
+default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
+
+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"


@@ -13844,16 +13843,6 @@ to set in them.
 See &%dns_retrans%& above.
 
 
 See &%dns_retrans%& above.
 
 

-.option dns_use_dnssec main integer -1
-.cindex "DNS" "resolver options"
-.cindex "DNS" "DNSSEC"
-If this option is set to a non-negative number then Exim will initialise the
-DNS resolver library to either use or not use DNSSEC, overriding the system
-default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on.
-
-If the resolver library does not support DNSSEC then this option has no effect.
-
-

 .option dns_use_edns0 main integer -1
 .cindex "DNS" "resolver options"
 .cindex "DNS" "EDNS0"
 .option dns_use_edns0 main integer -1
 .cindex "DNS" "resolver options"
 .cindex "DNS" "EDNS0"


@@ -23021,7 +23010,7 @@ in clear.
 .option tls_try_verify_hosts smtp "host list&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 .option tls_try_verify_hosts smtp "host list&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"

-For OpenSSL only, this option gives a list of hosts for which, on encrypted connections,
+This option gives a list of hosts for which, on encrypted connections,

 certificate verification will be tried but need not succeed.
 The &%tls_verify_certificates%& option must also be set.
 
 certificate verification will be tried but need not succeed.
 The &%tls_verify_certificates%& option must also be set.
 


@@ -23040,7 +23029,7 @@ single file if you are using GnuTLS. 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 &<<CHAPTLS>>& for details of TLS.
 
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
 

-For back-compatability, or when GnuTLS is used,
+For back-compatability,

 if neither tls_verify_hosts nor tls_try_verify_hosts are set
 and certificate verification fails the TLS connection is closed.
 
 if neither tls_verify_hosts nor tls_try_verify_hosts are set
 and certificate verification fails the TLS connection is closed.
 


@@ -23048,7 +23037,7 @@ and certificate verification fails the TLS connection is closed.
 .option tls_verify_hosts smtp "host list&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 .option tls_verify_hosts smtp "host list&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"

-For OpenSSL only, this option gives a list of hosts for which. on encrypted connections,
+This option gives a list of hosts for which. on encrypted connections,

 certificate verification must succeed.
 The &%tls_verify_certificates%& option must also be set.
 If both this option and &%tls_try_verify_hosts%& are unset
 certificate verification must succeed.
 The &%tls_verify_certificates%& option must also be set.
 If both this option and &%tls_try_verify_hosts%& are unset


@@ -27321,8 +27310,12 @@ from one SMTP connection to another.  If a recipient-verify callout connection i
 requested in the same ACL it is held open and used for the data, otherwise one is made
 after the ACL completes.
 
 requested in the same ACL it is held open and used for the data, otherwise one is made
 after the ACL completes.
 

-Note that routers are used in verify mode.  Note also that headers cannot be
+Note that routers are used in verify mode,
+and cannot depend on content of received headers.
+Note also that headers cannot be

 modified by any of the post-data ACLs (DATA, MIME and DKIM).
 modified by any of the post-data ACLs (DATA, MIME and DKIM).

+Headers may be modified by routers (subject to the above) and transports.
+

 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.
 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.


@@ -28010,6 +28003,23 @@ This condition checks whether the sending host (the client) is authorized to
 send email. Details of how this works are given in section
 &<<SECTverifyCSA>>&.
 
 send email. Details of how this works are given in section
 &<<SECTverifyCSA>>&.
 

+.new
+.vitem &*verify&~=&~header_names_ascii*&
+.cindex "&%verify%& ACL condition"
+.cindex "&ACL;" "verifying header names only ASCII"
+.cindex "header lines" "verifying header names only ASCII"
+.cindex "verifying" "header names only ASCII"
+This condition is relevant only in an ACL that is run after a message has been
+received, that is, in an ACL specified by &%acl_smtp_data%& or
+&%acl_not_smtp%&.  It checks all header names (not the content) to make sure
+there are no non-ASCII characters, also excluding control characters.  The
+allowable characters are decimal ASCII values 33 through 126.
+
+Exim itself will handle headers with non-ASCII characters, but it can cause
+problems for downstream applications, so this option will allow their
+detection and rejection in the DATA ACL's.
+.wen
+

 .vitem &*verify&~=&~header_sender/*&<&'options'&>
 .cindex "&%verify%& ACL condition"
 .cindex "&ACL;" "verifying sender in the header"
 .vitem &*verify&~=&~header_sender/*&<&'options'&>
 .cindex "&%verify%& ACL condition"
 .cindex "&ACL;" "verifying sender in the header"


@@ -28621,6 +28631,13 @@ deny   condition = ${if isip4{$sender_host_address}}
        dnslists  = some.list.example
 .endd
 
        dnslists  = some.list.example
 .endd
 

+If an explicit key is being used for a DNS lookup and it may be an IPv6
+address you should specify alternate list separators for both the outer
+(DNS list name) list and inner (lookup keys) list:
+.code
+       dnslists = <; dnsbl.example.com/<|$acl_m_addrslist
+.endd
+

 .section "Rate limiting incoming messages" "SECTratelimiting"
 .cindex "rate limiting" "client sending"
 .cindex "limiting client sending rates"
 .section "Rate limiting incoming messages" "SECTratelimiting"
 .cindex "rate limiting" "client sending"
 .cindex "limiting client sending rates"


@@ -29002,6 +29019,7 @@ router that does not set up hosts routes to an &(smtp)& transport with a
 &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has
 &%hosts_override%& set, its hosts are always used, whether or not the router
 supplies a host list.
 &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has
 &%hosts_override%& set, its hosts are always used, whether or not the router
 supplies a host list.

+Callouts are only supported on &(smtp)& transports.

 
 The port that is used is taken from the transport, if it is specified and is a
 remote transport. (For routers that do verification only, no transport need be
 
 The port that is used is taken from the transport, if it is specified and is a
 remote transport. (For routers that do verification only, no transport need be


@@ -29805,6 +29823,24 @@ av_scanner = mksd:2
 .endd
 You can safely omit this option (the default value is 1).
 
 .endd
 You can safely omit this option (the default value is 1).
 

+.vitem &%sock%&
+.cindex "virus scanners" "simple socket-connected"
+This is a general-purpose way of talking to simple scanner daemons
+running on the local machine.
+There are four options:
+an address (which may be an IP addres and port, or the path of a Unix socket),
+a commandline to send (may include a single %s which will be replaced with
+the path to the mail file to be scanned),
+an RE to trigger on from the returned data,
+an RE to extract malware_name from the returned data.
+For example:
+.code
+av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$
+.endd
+Default for the socket specifier is &_/tmp/malware.sock_&.
+Default for the commandline is &_%s\n_&.
+Both regular-expressions are required.
+

 .vitem &%sophie%&
 .cindex "virus scanners" "Sophos and Sophie"
 Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses.
 .vitem &%sophie%&
 .cindex "virus scanners" "Sophos and Sophie"
 Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses.


@@ -34051,6 +34087,7 @@ the following table:
 &`R   `&        on &`<=`& lines: reference for local bounce
 &`    `&        on &`=>`&  &`**`& and &`==`& lines: router name
 &`S   `&        size of message
 &`R   `&        on &`<=`& lines: reference for local bounce
 &`    `&        on &`=>`&  &`**`& and &`==`& lines: router name
 &`S   `&        size of message

+&`SNI `&        server name indication from TLS client hello

 &`ST  `&        shadow transport name
 &`T   `&        on &`<=`& lines: message subject (topic)
 &`    `&        on &`=>`& &`**`& and &`==`& lines: transport name
 &`ST  `&        shadow transport name
 &`T   `&        on &`<=`& lines: message subject (topic)
 &`    `&        on &`=>`& &`**`& and &`==`& lines: transport name


@@ -34360,7 +34397,8 @@ The message that is written is &"spool file is locked"&.
 .next
 .cindex "log" "smtp confirmation"
 .cindex "SMTP" "logging confirmation"
 .next
 .cindex "log" "smtp confirmation"
 .cindex "SMTP" "logging confirmation"

-&%smtp_confirmation%&: The response to the final &"."& in the SMTP dialogue for
+.cindex "LMTP" "logging confirmation"
+&%smtp_confirmation%&: The response to the final &"."& in the SMTP or LMTP dialogue for

 outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>.
 A number of MTAs (including Exim) return an identifying string in this
 response.
 outgoing messages is added to delivery log lines in the form &`C=`&<&'text'&>.
 A number of MTAs (including Exim) return an identifying string in this
 response.