. 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
. /////////////////////////////////////////////////////////////////////////////
.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
.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%&"
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.
.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"
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
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
.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"
.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:
&$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$&
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$&
.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"
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"
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
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
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
.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
.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
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
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
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"
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.
.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
&%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"
.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
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
.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.
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
projects / exim.git / blobdiff