X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/4c04137d73637107669e02b21f890387aaa2ef34..54fda09b9a9042293ca2ed8b76e445b3ea312653:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index db4c6e2a2..9e1aa4e4b 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -45,14 +45,14 @@ . 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 @@ -3830,7 +3832,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%&" @@ -4920,11 +4928,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 +6737,8 @@ PostgreSQL database. See section &<>&. .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 &<>&. +&(redis)&: The format of the query is either a simple get or simple set, +passed to a Redis database. See section &<>&. .next .cindex "sqlite lookup type" @@ -7805,6 +7811,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 +9440,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 +9774,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 +9804,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 +12279,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 &<>&. .vitem &$prdr_requested$& @@ -12607,6 +12629,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 +13555,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 +14444,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 +14700,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 +14708,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 +15335,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 +16909,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 &<>&. +A forced expansion failure results in no filter operation. .option system_filter_directory_transport main string&!! unset @@ -17113,7 +17152,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 +23305,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 @@ -25865,6 +25903,17 @@ turned into a permanent error if you wish. In the second case, Exim tries to deliver the message unauthenticated. .endlist +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. + .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 @@ -28080,6 +28129,9 @@ 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. +If the ACL for VRFY returns &"accept"&, a recipient verify (without callout) +is done on the address and the result determines the SMTP response. + .cindex "&[local_scan()]& function" "when all recipients discarded" The &[local_scan()]& function is always run, even if there are no remaining @@ -28899,7 +28951,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. @@ -29750,6 +29804,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 @@ -36015,7 +36076,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 &<>& for more information. .next .cindex "log" "incoming remote port" @@ -37875,9 +37936,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 @@ -38506,6 +38566,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 @@ -38513,9 +38580,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. @@ -38626,6 +38693,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