X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/e5717a6aeeba6e49c13926f1bfead32953c67559..d8ac03161cd960f2ad026e0a11c2614519c4a8be:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 47341b163..c78995f82 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -45,7 +45,7 @@ . 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)" @@ -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 @@ -462,7 +464,7 @@ which contains what used to be a separate FAQ, as well as various other examples, tips, and know-how that have been contributed by Exim users. .cindex Bugzilla -An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use +An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use this to report bugs, and also to add items to the wish list. Please search first to check that you are not duplicating a previous entry. @@ -502,7 +504,7 @@ information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). .cindex "bug reports" .cindex "reporting bugs" Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported -via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure +via the Bugzilla (&url(https://bugs.exim.org)). However, if you are unsure whether some behaviour is a bug or not, the best thing to do is to post a message to the &'exim-dev'& mailing list and have it discussed. @@ -3826,7 +3828,7 @@ 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 @@ -3866,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'&>&~<&'cipher'&> +.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 arguments give the local address and port being proxied, and the TLS cipher. +.wen + .vitem &%-Mc%&&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-Mc%&" .cindex "hints database" "not overridden by &%-Mc%&" @@ -4926,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. @@ -6737,8 +6746,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" @@ -7811,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 @@ -9429,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 @@ -9767,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" @@ -9797,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: @@ -11017,9 +11042,14 @@ colon-separated components are permitted, each containing from one to four hexadecimal digits. There may be fewer than eight components if an empty component (adjacent colons) is present. Only one empty component is permitted. -&*Note*&: The checks are just on the form of the address; actual numerical -values are not considered. Thus, for example, 999.999.999.999 passes the IPv4 -check. The main use of these tests is to distinguish between IP addresses and +.new +&*Note*&: The checks used to be just on the form of the address; actual numerical +values were not considered. Thus, for example, 999.999.999.999 passed the IPv4 +check. +This is no longer the case. +.wen + +The main use of these tests is to distinguish between IP addresses and host names, or between IPv4 and IPv6 addresses. For example, you could use .code ${if isip4{$sender_host_address}... @@ -12613,12 +12643,10 @@ 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$& @@ -13541,6 +13569,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" @@ -14429,6 +14458,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" @@ -14686,11 +14722,9 @@ 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 @@ -15315,9 +15349,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 @@ -16891,9 +16923,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 &<>&. -.new A forced expansion failure results in no filter operation. -.wen .option system_filter_directory_transport main string&!! unset @@ -17136,7 +17166,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 @@ -23288,9 +23319,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 @@ -23920,6 +23949,25 @@ been started will not be passed to a new delivery process for sending another message on the same connection. See section &<>& 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 @@ -25888,7 +25936,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 @@ -25899,7 +25946,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 @@ -27172,10 +27218,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 @@ -28116,10 +28164,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" @@ -28941,9 +28987,7 @@ 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 -.new or CHUNKING -.wen options in use. Should the ultimate destination system positively accept or reject the mail, @@ -29796,14 +29840,12 @@ to avoid doing it more than once per message. 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 @@ -30866,6 +30908,23 @@ command when performing the callout, instead of an empty address. There is no need to use this option unless you know that the called hosts make use of the sender when checking recipients. If used indiscriminately, it reduces the usefulness of callout caching. + +.new +.vitem &*hold*& +This option applies to recipient callouts only. For example: +.code +require verify = recipient/callout=use_sender,hold +.endd +It causes the connection to be helod open and used for any further recipients +and for eventual delivery (should that be done quickly). +Doing this saves on TCP and SMTP startup costs, and TLS costs also +when that is used for the connections. +The advantage is only gained if there are no callout cache hits +(which could be enforced by the no_cache option), +if the use_sender option is used, +if neither the random nor the use_postmaster option is used, +and if no other callouts intervene. +.wen .endlist If you use any of the parameters that set a non-empty sender for the MAIL @@ -31502,6 +31561,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 @@ -35718,6 +35789,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 +DNS and some TLS-related information logged for the first message delivered +will not be present in the log lines for the second and subsequent messages. +TLS cipher information is still available. +.wen .cindex "delivery" "cutthrough; logging" .cindex "cutthrough" "logging" @@ -36578,8 +36655,7 @@ autodetection of some well known compression extensions. .cindex "&'exipick'&" John Jetmore's &'exipick'& utility is included in the Exim distribution. It lists messages from the queue according to a variety of criteria. For details -of &'exipick'&'s facilities, visit the web page at -&url(http://www.exim.org/eximwiki/ToolExipickManPage) or run &'exipick'& with +of &'exipick'&'s facilities, run &'exipick'& with the &%--help%& option. @@ -38573,9 +38649,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. @@ -38686,11 +38762,9 @@ 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" @@ -38844,7 +38918,7 @@ The current list of events is: &`msg:rcpt:host:defer after transport `& per recipient per host &`msg:rcpt:defer after transport `& per recipient &`msg:host:defer after transport `& per attempt -&`msg:fail:delivery after main `& per recipient +&`msg:fail:delivery after transport `& per recipient &`msg:fail:internal after main `& per recipient &`tcp:connect before transport `& per connection &`tcp:close after transport `& per connection @@ -38861,6 +38935,11 @@ The second column in the table above describes whether the event fires before or after the action is associates with. Those which fire before can be used to affect that action (more on this below). +.new +The third column in the table above says what section of the configumration +should define the event action. +.wen + An additional variable, &$event_data$&, is filled with information varying with the event type: .display