Add option to control use of shutdown by ${readsocket }. Bug 400
[exim.git] / doc / doc-docbook / spec.xfpt
index 75f28ef67916df319d2cd17feebfe728c93c56da..054a135b93201d2fd8d25df47d99910e6177365f 100644 (file)
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
-2016
+2017
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -3830,7 +3830,13 @@ remote host supports the ESMTP &_DSN_& extension.
 .oindex "&%-MCG%&"
 This option is not intended for use by external callers. It is used internally
 by Exim in conjunction with the &%-MC%& option. It signifies that an
-alternate queue is used, named by the following option.
+alternate queue is used, named by the following argument.
+
+.vitem &%-MCK%&
+.oindex "&%-MCK%&"
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the &%-MC%& option. It signifies that an
+remote host supports the ESMTP &_CHUNKING_& extension.
 
 .vitem &%-MCP%&
 .oindex "&%-MCP%&"
@@ -4480,7 +4486,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 +7116,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 +9111,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.
@@ -9761,7 +9767,7 @@ locks out the use of this expansion item in filter files.
 
 
 .vitem "&*${readsocket{*&<&'name'&>&*}{*&<&'request'&>&*}&&&
-        {*&<&'timeout'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&"
+        {*&<&'options'&>&*}{*&<&'eol&~string'&>&*}{*&<&'fail&~string'&>&*}}*&"
 .cindex "expansion" "inserting from a socket"
 .cindex "socket, use of in expansion"
 .cindex "&%readsocket%& expansion item"
@@ -9791,6 +9797,17 @@ extend what can be done. Firstly, you can vary the timeout. For example:
 .code
 ${readsocket{/socket/name}{request string}{3s}}
 .endd
+.new
+The third argument is a list of options, of which the first element is the timeout
+and must be present if the argument is given.
+Further elements are options of form &'name=value'&.
+One option type is currently recognised, defining whether (the default)
+or not a shutdown is done on the connection after sending the request.
+Example, to not do so (preferred, eg. by some webservers):
+.code
+${readsocket{/socket/name}{request string}{3s:shutdown=no}}
+.endd
+.wen
 A fourth argument allows you to change any newlines that are in the data
 that is read, in the same way as for &%readfile%& (see above). This example
 turns them into spaces:
@@ -12210,7 +12227,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
@@ -12257,7 +12274,7 @@ qualified host name. See also &$smtp_active_hostname$&.
        &$proxy_local_port$& &&&
        &$proxy_session$&
 These variables are only available when built with Proxy Protocol
-or Socks5 support
+or SOCKS5 support.
 For details see chapter &<<SECTproxyInbound>>&.
 
 .vitem &$prdr_requested$&
@@ -12607,6 +12624,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 +12852,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 +13122,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.
@@ -13528,6 +13552,7 @@ listed in more than one group.
 .section "Miscellaneous" "SECID96"
 .table2
 .row &%bi_command%&                  "to run for &%-bi%& command line option"
+.row &%debug_store%&                 "do extra internal checks"
 .row &%disable_ipv6%&                "do no IPv6 processing"
 .row &%keep_malformed%&              "for broken files &-- should not happen"
 .row &%localhost_number%&            "for unique message ids in clusters"
@@ -14018,6 +14043,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 +14431,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&!!" *
@@ -14415,6 +14441,15 @@ The CHUNKING extension (RFC3030) will be advertised in the EHLO message to
 these hosts.
 Hosts may use the BDAT command as an alternate to DATA.
 
+.new
+.option debug_store main boolean &`false`&
+.cindex debugging "memory corruption"
+.cindex memory debugging
+This option, when true, enables extra checking in Exim's internal memory
+management.  For use when a memory corruption issue is being investigated,
+it should normally be left as default.
+.wen
+
 .option daemon_smtp_ports main string &`smtp`&
 .cindex "port" "for daemon"
 .cindex "TCP/IP" "setting listening ports"
@@ -14664,6 +14699,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 +14707,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 +16755,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 +16912,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
@@ -17112,7 +17157,8 @@ acceptable bound from 1024 to 2048.
 
 .option tls_eccurve main string&!! &`auto`&
 .cindex TLS "EC cryptography"
-This option selects a EC curve for use by Exim.
+This option selects a EC curve for use by Exim when used with OpenSSL.
+It has no effect when Exim is used with GnuTLS.
 
 After expansion it must contain a valid EC curve parameter, such as
 &`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual
@@ -21006,7 +21052,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 +24016,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 +25910,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 +27594,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 +28138,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
@@ -28898,7 +28962,11 @@ message body.
 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.
-It is not supported for messages received with the SMTP PRDR option in use.
+It is not supported for messages received with the SMTP PRDR
+.new
+or CHUNKING
+.wen
+options in use.
 
 Should the ultimate destination system positively accept or reject the mail,
 a corresponding indication is given to the source system and nothing is queued.
@@ -28912,7 +28980,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 +29817,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 +29885,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 +29998,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.
@@ -36014,7 +36091,7 @@ The latter can be disabled by turning off the &%outgoing_interface%& option.
 &%proxy%&: The internal (closest to the system running Exim) IP address
 of the proxy, tagged by PRX=, on the &"<="& line for a message accepted
 on a proxied connection
-or the &"=>"& line for a message delivered on a proxied connection..
+or the &"=>"& line for a message delivered on a proxied connection.
 See &<<SECTproxyInbound>>& for more information.
 .next
 .cindex "log" "incoming remote port"
@@ -36045,7 +36122,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
@@ -37874,9 +37951,8 @@ lock will be lost at the instant of rename.
 .next
 .vindex "&$body_linecount$&"
 If you change the number of lines in the file, the value of
-&$body_linecount$&, which is stored in the -H file, will be incorrect. At
-present, this value is not used by Exim, but there is no guarantee that this
-will always be the case.
+&$body_linecount$&, which is stored in the -H file, will be incorrect and can
+cause incomplete transmission of messages or undeliverable messages.
 .next
 If the message is in MIME format, you must take care not to break it.
 .next
@@ -38489,9 +38565,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
@@ -38505,6 +38581,13 @@ recorded in an ACL (example is below).
 Use of a proxy is enabled by setting the &%hosts_proxy%&
 main configuration option to a hostlist; connections from these
 hosts will use Proxy Protocol.
+Exim supports both version 1 and version 2 of the Proxy Protocol and
+automatically determines which version is in use.
+
+The Proxy Protocol header is the first data received on a TCP connection
+and is inserted before any TLS-on-connect handshake from the client; Exim
+negotiates TLS between Exim-as-server and the remote client, not between
+Exim and the proxy server.
 
 The following expansion variables are usable
 (&"internal"& and &"external"& here refer to the interfaces
@@ -38625,6 +38708,12 @@ Exim has support for Internationalised mail names.
 To include this it must be built with SUPPORT_I18N and the libidn library.
 Standards supported are RFCs 2060, 5890, 6530 and 6533.
 
+.new
+If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not
+instead of it) then IDNA2008 is supported; this adds an extra library
+requirement, upon libidn2.
+.wen
+
 .section "MTA operations" SECTi18nMTA
 .cindex SMTPUTF8 "ESMTP option"
 The main configuration option &%smtputf8_advertise_hosts%& specifies
@@ -38797,7 +38886,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