Sync 4.next from master
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index 7d8b908f81a18c638d71408d9c85179518c65082..be93cf67075ebd93f4493b621ecd1c49f2a216a2 100644 (file)
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 
-.set previousversion "4.88"
+.set previousversion "4.89"
 .include ./local_params
 
 .set ACL "access control lists (ACLs)"
 .set I   "    "
 
 .macro copyyear
-2016
+2017
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -371,11 +371,13 @@ contributors.
 .section "Exim documentation" "SECID1"
 . Keep this example change bar when updating the documentation!
 
+.new
 .cindex "documentation"
 This edition of the Exim specification applies to version &version() of Exim.
 Substantive changes from the &previousversion; edition are marked in some
 renditions of the document; this paragraph is so marked if the rendition is
 capable of showing a change indicator.
+.wen
 
 This document is very much a reference manual; it is not a tutorial. The reader
 is expected to have some familiarity with the SMTP mail transfer protocol and
@@ -3826,11 +3828,17 @@ 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 the
 remote host supports the ESMTP &_DSN_& extension.
 
-.vitem &%-MCG%&
+.vitem &%-MCG%&&~<&'queue&~name'&>
 .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%&"
@@ -3860,6 +3868,15 @@ This option is not intended for use by external callers. It is used internally
 by Exim in conjunction with the &%-MC%& option, and passes on the fact that the
 host to which Exim is connected supports TLS encryption.
 
+.new
+.vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>
+.oindex "&%-MCt%&"
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the &%-MC%& option, and passes on the fact that the
+connection is being proxied by a parent process for handling TLS encryption.
+The pair of arguments give the local address and port being proxied.
+.wen
+
 .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~...
 .oindex "&%-Mc%&"
 .cindex "hints database" "not overridden by &%-Mc%&"
@@ -4920,11 +4937,9 @@ using this syntax:
 on a line by itself. Double quotes round the file name are optional. If you use
 the first form, a configuration error occurs if the file does not exist; the
 second form does nothing for non-existent files.
-.new
 The first form allows a relative name. It is resolved relative to
 the directory of the including file. For the second form an absolute file
 name is required.
-.wen
 
 Includes may be nested to any depth, but remember that Exim reads its
 configuration file often, so it is a good idea to keep them to a minimum.
@@ -6731,8 +6746,8 @@ PostgreSQL database. See section &<<SECTsql>>&.
 .next
 .cindex "Redis lookup type"
 .cindex lookup Redis
-&(redis)&: The format of the query is an SQL statement that is passed to a
-Redis database. See section &<<SECTsql>>&.
+&(redis)&: The format of the query is either a simple get or simple set,
+passed to a Redis database. See section &<<SECTsql>>&.
 
 .next
 .cindex "sqlite lookup type"
@@ -7805,6 +7820,17 @@ are rejected after a timeout period, during which the SQLite library
 waits for the lock to be released. In Exim, the default timeout is set
 to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%&
 option.
+
+.section "More about Redis" "SECTredis"
+.cindex "lookup" "Redis"
+.cindex "redis lookup type"
+Redis is a non-SQL database. Commands are simple get and set.
+Examples:
+.code
+${lookup redis{set keyname ${quote_redis:objvalue plus}}}
+${lookup redis{get keyname}}
+.endd
+
 .ecindex IIDfidalo1
 .ecindex IIDfidalo2
 
@@ -9423,17 +9449,13 @@ filter. Header lines that are added to a particular copy of a message by a
 router or transport are not accessible.
 
 For incoming SMTP messages, no header lines are visible in
-.new
 ACLs that are obeyed before the data phase completes,
-.wen
 because the header structure is not set up until the message is received.
 They are visible in DKIM, PRDR and DATA ACLs.
 Header lines that are added in a RCPT ACL (for example)
 are saved until the message's incoming header lines are available, at which
 point they are added.
-.new
 When any of the above ACLs ar
-.wen
 running, however, header lines added by earlier ACLs are visible.
 
 Upper case and lower case letters are synonymous in header names. If the
@@ -9761,7 +9783,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 +9813,15 @@ extend what can be done. Firstly, you can vary the timeout. For example:
 .code
 ${readsocket{/socket/name}{request string}{3s}}
 .endd
+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
 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:
@@ -12257,7 +12288,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 +12638,11 @@ 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.
 
+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).
+
 
 .vitem &$sender_host_name$&
 .vindex "&$sender_host_name$&"
@@ -13528,6 +13564,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"
@@ -14416,6 +14453,13 @@ 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.
 
+.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.
+
 .option daemon_smtp_ports main string &`smtp`&
 .cindex "port" "for daemon"
 .cindex "TCP/IP" "setting listening ports"
@@ -14665,6 +14709,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
@@ -14672,6 +14717,10 @@ on.
 
 If the resolver library does not support EDNS0 then this option has no effect.
 
+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.
+
 
 .option drop_cr main boolean false
 This is an obsolete option that is now a no-op. It used to affect the way Exim
@@ -15295,9 +15344,7 @@ connecting on a regular LDAP port.  This is the LDAP equivalent of SMTP's
 of SSL-on-connect.
 In the event of failure to negotiate TLS, the action taken is controlled
 by &%ldap_require_cert%&.
-.new
 This option is ignored for &`ldapi`& connections.
-.wen
 
 
 .option ldap_version main integer unset
@@ -16871,6 +16918,7 @@ 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>>&.
+A forced expansion failure results in no filter operation.
 
 
 .option system_filter_directory_transport main string&!! unset
@@ -17113,7 +17161,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
@@ -23265,9 +23314,7 @@ message_suffix =
 
 
 .option path pipe string&!! "/bin:/usr/bin"
-.new
 This option is expanded and
-.wen
 specifies the string that is set up in the PATH environment
 variable of the subprocess.
 If the &%command%& option does not yield an absolute path name, the command is
@@ -23897,6 +23944,25 @@ been started will not be passed to a new delivery process for sending another
 message on the same connection. See section &<<SECTmulmessam>>& for an
 explanation of when this might be needed.
 
+.new
+.option hosts_noproxy_tls smtp "host list&!!" *
+.cindex "TLS" "passing connection"
+.cindex "multiple SMTP deliveries"
+.cindex "TLS" "multiple message deliveries"
+For any host that matches this list, a TLS session which has
+been started will not be passed to a new delivery process for sending another
+message on the same session.
+
+The traditional implementation closes down TLS and re-starts it in the new
+process, on the same open TCP connection, for each successive message
+sent.  If permitted by this option a pipe to to the new process is set up
+instead, and the original process maintains the TLS connection and proxies
+the SMTP connection from and to the new process and any subsequents.
+The new process has no access to TLS information, so cannot include it in
+logging.
+.wen
+
+
 
 .option hosts_override smtp boolean false
 If this option is set and the &%hosts%& option is also set, any hosts that are
@@ -25865,7 +25931,6 @@ 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
@@ -25876,7 +25941,6 @@ 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
@@ -27149,10 +27213,12 @@ tls_require_ciphers = ${if =={$received_port}{25}\
 .cindex "TLS" "configuring an Exim server"
 When Exim has been built with TLS support, it advertises the availability of
 the STARTTLS command to client hosts that match &%tls_advertise_hosts%&,
-but not to any others. The default value of this option is unset, which means
-that STARTTLS is not advertised at all. This default is chosen because you
-need to set some other options in order to make TLS available, and also it is
-sensible for systems that want to use TLS only as a client.
+but not to any others. The default value of this option is *, which means
+that STARTTLS is alway advertised.  Set it to blank to never advertise;
+this is reasonble for systems that want to use TLS only as a client.
+
+If STARTTLS is to be used you
+need to set some other options in order to make TLS available.
 
 If a client issues a STARTTLS command and there is some configuration
 problem in the server, the command is rejected with a 454 error. If the client
@@ -28093,10 +28159,8 @@ 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"
@@ -28917,7 +28981,9 @@ 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
+or CHUNKING
+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.
@@ -29768,6 +29834,13 @@ 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.
+
+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
 .endlist
 
 
@@ -31466,6 +31539,18 @@ av_scanner = f-protd:localhost 10200-10204
 .endd
 If you omit the argument, the default values show above are used.
 
+.new
+.vitem &%f-prot6d%&
+.cindex "virus scanners" "f-prot6d"
+The f-prot6d scanner is accessed using the FPSCAND protocol over TCP.
+One argument is taken, being a space-separated hostname and port number.
+For example:
+.code
+av_scanner = f-prot6d:localhost 10200
+.endd
+If you omit the argument, the default values show above are used.
+.wen
+
 .vitem &%fsecure%&
 .cindex "virus scanners" "F-Secure"
 The F-Secure daemon scanner (&url(http://www.f-secure.com)) takes one
@@ -35682,6 +35767,12 @@ SMTP RCPT commands in one transaction) the second and subsequent addresses are
 flagged with &`->`& instead of &`=>`&. When two or more messages are delivered
 down a single SMTP connection, an asterisk follows the IP address in the log
 lines for the second and subsequent messages.
+.new
+When two or more messages are delivered down a single TLS connection, the
+TLS-related information logged for the first message delivered
+(which may not be the earliest line in the log)
+will not be present in the log lines for the second and subsequent messages.
+.wen
 
 .cindex "delivery" "cutthrough; logging"
 .cindex "cutthrough" "logging"
@@ -36033,7 +36124,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"
@@ -37893,9 +37984,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
@@ -38524,6 +38614,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
@@ -38531,9 +38628,9 @@ of the proxy):
 .display
 &'proxy_external_address   '& IP of host being proxied or IP of remote interface of proxy
 &'proxy_external_port      '& Port of host being proxied or Port on remote interface of proxy
-&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy
-&'proxy_local_port    '& Port of proxy server inbound or Port on local interface of proxy
-&'proxy_session        '& boolean: SMTP connection via proxy
+&'proxy_local_address      '& IP of proxy server inbound or IP of local interface of proxy
+&'proxy_local_port         '& Port of proxy server inbound or Port on local interface of proxy
+&'proxy_session            '& boolean: SMTP connection via proxy
 .endd
 If &$proxy_session$& is set but &$proxy_external_address$& is empty
 there was a protocol error.
@@ -38644,6 +38741,10 @@ 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.
 
+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.
+
 .section "MTA operations" SECTi18nMTA
 .cindex SMTPUTF8 "ESMTP option"
 The main configuration option &%smtputf8_advertise_hosts%& specifies