Docs: add note on verify = senders= . Bug 2028
[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt
index 75f28ef67916df319d2cd17feebfe728c93c56da..64807899824d0b976d5fc6388182364c7c7cb6d7 100644 (file)
@@ -4480,7 +4480,7 @@ will specify a queue to operate on.
 For example:
 .code
 exim -bp -qGquarantine
-mailq -qGquarantime
+mailq -qGquarantine
 exim -qGoffpeak -Rf @special.domain.example
 .endd
 
@@ -7110,7 +7110,7 @@ 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%&.
 
-.cindex cacheing "of dns lookup"
+.cindex caching "of dns lookup"
 .cindex TTL "of dns lookup"
 .cindex DNS TTL
 Dnsdb lookup results are cached within a single process (and its children).
@@ -9105,7 +9105,7 @@ If the ACL returns defer the result is a forced-fail.  Otherwise the expansion f
 
 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
        {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
-.cindex "expansion" "extracting cerificate fields"
+.cindex "expansion" "extracting certificate fields"
 .cindex "&%certextract%&" "certificate fields"
 .cindex "certificate" "extracting fields"
 The <&'certificate'&> must be a variable of type certificate.
@@ -12210,7 +12210,7 @@ normally the gid of the Exim user.
 .cindex "uid (user id)" "of originating user"
 .cindex "sender" "uid"
 .vindex "&$caller_uid$&"
-.vindex "&$originaltor_uid$&"
+.vindex "&$originator_uid$&"
 The value of &$caller_uid$& that was set when the message was received. For
 messages received via the command line, this is the uid of the sending user.
 For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
@@ -12607,6 +12607,13 @@ validating resolver (e.g. unbound, or bind with suitable configuration).
 If you have changed &%host_lookup_order%& so that &`bydns`& is not the first
 mechanism in the list, then this variable will be false.
 
+.new
+This requires that your system resolver library support EDNS0 (and that
+DNSSEC flags exist in the system headers).  If the resolver silently drops
+all EDNS0 options, then this will have no effect.  OpenBSD's asr resolver
+is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
+.wen
+
 
 .vitem &$sender_host_name$&
 .vindex "&$sender_host_name$&"
@@ -12828,7 +12835,7 @@ If TLS has not been negotiated, the value will be 0.
 
 .vitem &$tls_in_ourcert$&
 .vindex "&$tls_in_ourcert$&"
-.cindex certificate veriables
+.cindex certificate variables
 This variable refers to the certificate presented to the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
@@ -13098,7 +13105,7 @@ initial startup, even if &%perl_at_start%& is set.
 .oindex "&%perl_taintmode%&"
 .cindex "Perl" "taintmode"
 To provide more security executing Perl code via the embedded Perl
-interpeter, the &%perl_taintmode%& option can be set. This enables the
+interpreter, the &%perl_taintmode%& option can be set. This enables the
 taint mode of the Perl interpreter. You are encouraged to set this
 option to a true value. To avoid breaking existing installations, it
 defaults to false.
@@ -14018,6 +14025,7 @@ acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
 .option acl_smtp_dkim main string&!! unset
 .cindex DKIM "ACL for"
 This option defines the ACL that is run for each DKIM signature
+(by default, or as specified in the dkim_verify_signers option)
 of a received message.
 See chapter &<<CHAPdkim>>& for further details.
 
@@ -14405,7 +14413,7 @@ it obviously cannot send an error message of any kind.
 
 There is a slight performance penalty for these checks.
 Versions of Exim preceding 4.88 had these disabled by default;
-high-rate intallations confident they will never run out of resources
+high-rate installations confident they will never run out of resources
 may wish to deliberately disable them.
 
 .option chunking_advertise_hosts main "host list&!!" *
@@ -14664,6 +14672,7 @@ record in the authoritative section is used instead.
 .option dns_use_edns0 main integer -1
 .cindex "DNS" "resolver options"
 .cindex "DNS" "EDNS0"
+.cindex "DNS" "OpenBSD
 If this option is set to a non-negative number then Exim will initialise the
 DNS resolver library to either use or not use EDNS0 extensions, overriding
 the system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0
@@ -14671,6 +14680,12 @@ on.
 
 If the resolver library does not support EDNS0 then this option has no effect.
 
+.new
+OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this
+means that DNSSEC will not work with Exim on that platform either, unless Exim
+is linked against an alternative DNS client library.
+.wen
+
 
 .option drop_cr main boolean false
 This is an obsolete option that is now a no-op. It used to affect the way Exim
@@ -16713,7 +16728,7 @@ example, instead of &"Administrative prohibition"&, it might give:
 .option smtputf8_advertise_hosts main "host list&!!" *
 .cindex "SMTPUTF8" "advertising"
 When Exim is built with support for internationalised mail names,
-the availability therof is advertised in
+the availability thereof is advertised in
 response to EHLO only to those client hosts that match this option. See
 chapter &<<CHAPi18n>>& for details of Exim's support for internationalisation.
 
@@ -16870,6 +16885,9 @@ generates any deliveries to files or pipes, or any new mail messages, the
 appropriate &%system_filter_..._transport%& option(s) must be set, to define
 which transports are to be used. Details of this facility are given in chapter
 &<<CHAPsystemfilter>>&.
+.new
+A forced expansion failure results in no filter operation.
+.wen
 
 
 .option system_filter_directory_transport main string&!! unset
@@ -21006,7 +21024,7 @@ The control does not apply to shadow transports.
 
 .cindex "hints database" "transport concurrency control"
 Exim implements this control by means of a hints database in which a record is
-incremented whenever a transport process is beaing created. The record
+incremented whenever a transport process is being created. The record
 is decremented and possibly removed when the process terminates.
 Obviously there is scope for
 records to get left lying around if there is a system or program crash. To
@@ -23970,7 +23988,7 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter
 .cindex "RFC 3030" "CHUNKING"
 This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
-BDAT will not be used in conjuction with a transport filter.
+BDAT will not be used in conjunction with a transport filter.
 
 .option hosts_try_fastopen smtp "host list!!" unset
 .cindex "fast open, TCP" "enabling, in client"
@@ -25864,6 +25882,19 @@ turned into a permanent error if you wish. In the second case, Exim tries to
 deliver the message unauthenticated.
 .endlist
 
+.new
+Note that the hostlist test for whether to do authentication can be
+confused if name-IP lookups change between the time the peer is decided
+on and the transport running.  For example, with a manualroute
+router given a host name, and DNS "round-robin" use by that name: if
+the local resolver cache times out between the router and the transport
+running, the transport may get an IP for the name for its authentication
+check which does not match the connection peer IP.
+No authentication will then be done, despite the names being identical.
+
+For such cases use a separate transport which always authenticates.
+.wen
+
 .cindex "AUTH" "on MAIL command"
 When Exim has authenticated itself to a remote server, it adds the AUTH
 parameter to the MAIL commands it sends, if it has an authenticated sender for
@@ -27535,7 +27566,7 @@ Great care should be taken to deal with matters of case, various injection
 attacks in the string (&`../`& or SQL), and ensuring that a valid filename
 can always be referenced; it is important to remember that &$tls_in_sni$& is
 arbitrary unverified data provided prior to authentication.
-Further, the initial cerificate is loaded before SNI is arrived, so
+Further, the initial certificate is loaded before SNI is arrived, so
 an expansion for &%tls_certificate%& must have a default which is used
 when &$tls_in_sni$& is empty.
 
@@ -28079,6 +28110,11 @@ run. A &"discard"& return from the DATA or the non-SMTP ACL discards all the
 remaining recipients. The &"discard"& return is not permitted for the
 &%acl_smtp_predata%& ACL.
 
+.new
+If the ACL for VRFY returns &"accept"&, a recipient verify (without callout)
+is done on the address and the result determines the SMTP response.
+.wen
+
 
 .cindex "&[local_scan()]& function" "when all recipients discarded"
 The &[local_scan()]& function is always run, even if there are no remaining
@@ -28912,7 +28948,7 @@ This behaviour can be adjusted by appending the option &*defer=*&<&'value'&>
 to the control; the default value is &"spool"& and the alternate value
 &"pass"& copies an SMTP defer response from the target back to the initiator
 and does not queue the message.
-Note that this is independent of any receipient verify conditions in the ACL.
+Note that this is independent of any recipient verify conditions in the ACL.
 
 Delivery in this mode avoids the generation of a bounce mail to a
 (possibly faked)
@@ -29749,6 +29785,15 @@ to avoid doing it more than once per message.
 .cindex "&%verify%& ACL condition"
 This is a variation of the previous option, in which a modified address is
 verified as a sender.
+
+.new
+Note that '/' is legal in local-parts; if the address may have such
+(eg. is generated from the received message)
+they must be protected from the options parsing by doubling:
+.code
+verify = sender=${sg{${address:$h_sender:}}{/}{//}}
+.endd
+.wen
 .endlist
 
 
@@ -29808,7 +29853,7 @@ deny  dnslists = blackholes.mail-abuse.org
 warn  message  = X-Warn: sending host is on dialups list
       dnslists = dialups.mail-abuse.org
 .endd
-.cindex cacheing "of dns lookup"
+.cindex caching "of dns lookup"
 .cindex DNS TTL
 DNS list lookups are cached by Exim for the duration of the SMTP session
 (but limited by the DNS return TTL value),
@@ -29921,7 +29966,7 @@ multiple DNS records. The inner dnsdb lookup produces a list of MX hosts
 and the outer dnsdb lookup finds the IP addresses for these hosts. The result
 of expanding the condition might be something like this:
 .code
-dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|...
+dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|...
 .endd
 Thus, this example checks whether or not the IP addresses of the sender
 domain's mail servers are on the Spamhaus black list.
@@ -36045,7 +36090,7 @@ off the &%outgoing_interface%& option.
 .next
 .cindex "log" "outgoing remote port"
 .cindex "port" "logging outgoint remote"
-.cindex "TCP/IP" "logging ougtoing remote port"
+.cindex "TCP/IP" "logging outgoing remote port"
 &%outgoing_port%&: The remote port number is added to delivery log lines (those
 containing => tags) following the IP address.
 The local port is also added if &%incoming_interface%& and
@@ -38489,9 +38534,9 @@ To include this support, include &"SUPPORT_PROXY=yes"&
 in Local/Makefile.
 
 It was built on specifications from:
-http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
+(&url(http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt)).
 That URL was revised in May 2014 to version 2 spec:
-http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e
+(&url(http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e)).
 
 The purpose of this facility is so that an application load balancer,
 such as HAProxy, can sit in front of several Exim servers
@@ -38797,7 +38842,7 @@ can be used to affect that action (more on this below).
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:
 .display
-&`msg:delivery         `& smtp confirmation mssage
+&`msg:delivery         `& smtp confirmation message
 &`msg:rcpt:host:defer  `& error string
 &`msg:rcpt:defer       `& error string
 &`msg:host:defer       `& error string