X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2Fdoc-txt%2Fexperimental-spec.txt;h=aa4cb464d12c40ffe8b45e9b5bdb05b005214d15;hb=8c5d388a6e12d1a8bd4aa565920238f8a921414a;hp=317f40101c74f46535d47305290013cde7fb1e25;hpb=950aa3fb3524550045e4f6b3eac84354e5fd4553;p=exim.git diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 317f40101..aa4cb464d 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -480,6 +480,7 @@ in your Local/Makefile. DCC Support -------------------------------------------------------------- +Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/ *) Building exim @@ -797,6 +798,8 @@ expansion is done. The current list of events is: msg:complete after main per message msg:delivery after transport per recipient + 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:internal after main per recipient @@ -810,16 +813,20 @@ variable to decide when to act. The value of the variable is a colon-separated list, defining a position in the tree of possible events; it may be used as a list or just matched on as a whole. There will be no whitespace. +New event types may be added in the future. + There is an auxilary variable, $event_data, for which the content is event_dependent: msg:delivery smtp confirmation mssage + msg:rcpt:host:defer error string + msg:rcpt:defer error string msg:host:defer error string tls:cert verification chain depth smtp:connect smtp banner -The msg:host:defer event populates one extra variable, $event_defer_errno. +The :defer events populate one extra variable, $event_defer_errno. The following variables are likely to be useful depending on the event type: @@ -847,7 +854,16 @@ event_action = ${if eq {msg:delivery}{$event_name} \ The string is expanded when each of the supported events occur and any side-effects of the expansion will happen. -Note that for complex operations an ACL expansion can be used. + +Note that for complex operations an ACL expansion can be used, +however due to the multiple contexts the Exim operates in +a) variables set in events raised from transports will not + be visible outside that transport call. +b) acl_m variables in a server context are lost on a new connection, + and after helo/ehlo/mail/starttls/rset commands +Using an ACL expansion with the logwrite modifier can be a +useful way of writing to the main log. + The expansion of the event_action option should normally @@ -864,6 +880,9 @@ following will be forced: No other use is made of the result string. +If transport proxying is used, the remote IP/port during a +tcp:connect event will be that of the proxy. + Known issues: - the tls:cert event is only called for the cert chain elements @@ -954,184 +973,6 @@ Where SPAMMER_SET is a macro and it is defined as set acl_c_spam_host = ${lookup redis{GET...}} -Proxy Protocol Support --------------------------------------------------------------- - -Exim now has Experimental "Proxy Protocol" support. It was built on -specifications from: -http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt -Above URL revised May 2014 to change version 2 spec: -http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e - -The purpose of this function is so that an application load balancer, -such as HAProxy, can sit in front of several Exim servers and Exim -will log the IP that is connecting to the proxy server instead of -the IP of the proxy server when it connects to Exim. It resets the -$sender_address_host and $sender_address_port to the IP:port of the -connection to the proxy. It also re-queries the DNS information for -this new IP address so that the original sender's hostname and IP -get logged in the Exim logfile. There is no logging if a host passes or -fails Proxy Protocol negotiation, but it can easily be determined and -recorded in an ACL (example is below). - -1. To compile Exim with Proxy Protocol support, put this in -Local/Makefile: - -EXPERIMENTAL_PROXY=yes - -2. Global configuration settings: - -proxy_required_hosts = HOSTLIST - -The proxy_required_hosts option will require any IP in that hostlist -to use Proxy Protocol. The specification of Proxy Protocol is very -strict, and if proxy negotiation fails, Exim will not allow any SMTP -command other than QUIT. (See end of this section for an example.) -The option is expanded when used, so it can be a hostlist as well as -string of IP addresses. Since it is expanded, specifying an alternate -separator is supported for ease of use with IPv6 addresses. - -To log the IP of the proxy in the incoming logline, add: - log_selector = +proxy - -A default incoming logline (wrapped for appearance) will look like this: - - 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net - H=mail.example.net [1.2.3.4] P=esmtp S=433 - -With the log selector enabled, an email that was proxied through a -Proxy Protocol server at 192.168.1.2 will look like this: - - 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net - H=mail.example.net [1.2.3.4] P=esmtp PRX=192.168.1.2 S=433 - -3. In the ACL's the following expansion variables are available. - -proxy_host_address The (internal) src IP of the proxy server - making the connection to the Exim server. -proxy_host_port The (internal) src port the proxy server is - using to connect to the Exim server. -proxy_target_address The dest (public) IP of the remote host to - the proxy server. -proxy_target_port The dest port the remote host is using to - connect to the proxy server. -proxy_session Boolean, yes/no, the connected host is required - to use Proxy Protocol. - -There is no expansion for a failed proxy session, however you can detect -it by checking if $proxy_session is true but $proxy_host is empty. As -an example, in my connect ACL, I have: - - warn condition = ${if and{ {bool{$proxy_session}} \ - {eq{$proxy_host_address}{}} } } - log_message = Failed required proxy protocol negotiation \ - from $sender_host_name [$sender_host_address] - - warn condition = ${if and{ {bool{$proxy_session}} \ - {!eq{$proxy_host_address}{}} } } - # But don't log health probes from the proxy itself - condition = ${if eq{$proxy_host_address}{$sender_host_address} \ - {false}{true}} - log_message = Successfully proxied from $sender_host_name \ - [$sender_host_address] through proxy protocol \ - host $proxy_host_address - - # Possibly more clear - warn logwrite = Remote Source Address: $sender_host_address:$sender_host_port - logwrite = Proxy Target Address: $proxy_target_address:$proxy_target_port - logwrite = Proxy Internal Address: $proxy_host_address:$proxy_host_port - logwrite = Internal Server Address: $received_ip_address:$received_port - - -4. Recommended ACL additions: - - Since the real connections are all coming from your proxy, and the - per host connection tracking is done before Proxy Protocol is - evaluated, smtp_accept_max_per_host must be set high enough to - handle all of the parallel volume you expect per inbound proxy. - - With the smtp_accept_max_per_host set so high, you lose the ability - to protect your server from massive numbers of inbound connections - from one IP. In order to prevent your server from being DOS'd, you - need to add a per connection ratelimit to your connect ACL. I - suggest something like this: - - # Set max number of connections per host - LIMIT = 5 - # Or do some kind of IP lookup in a flat file or database - # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}} - - defer message = Too many connections from this IP right now - ratelimit = LIMIT / 5s / per_conn / strict - - -5. Runtime issues to be aware of: - - The proxy has 3 seconds (hard-coded in the source code) to send the - required Proxy Protocol header after it connects. If it does not, - the response to any commands will be: - "503 Command refused, required Proxy negotiation failed" - - If the incoming connection is configured in Exim to be a Proxy - Protocol host, but the proxy is not sending the header, the banner - does not get sent until the timeout occurs. If the sending host - sent any input (before the banner), this causes a standard Exim - synchronization error (i.e. trying to pipeline before PIPELINING - was advertised). - - This is not advised, but is mentioned for completeness if you have - a specific internal configuration that you want this: If the Exim - server only has an internal IP address and no other machines in your - organization will connect to it to try to send email, you may - simply set the hostlist to "*", however, this will prevent local - mail programs from working because that would require mail from - localhost to use Proxy Protocol. Again, not advised! - -6. Example of a refused connection because the Proxy Protocol header was -not sent from a host configured to use Proxy Protocol. In the example, -the 3 second timeout occurred (when a Proxy Protocol banner should have -been sent), the banner was displayed to the user, but all commands are -rejected except for QUIT: - -# nc mail.example.net 25 -220-mail.example.net, ESMTP Exim 4.82+proxy, Mon, 04 Nov 2013 10:45:59 -220 -0800 RFC's enforced -EHLO localhost -503 Command refused, required Proxy negotiation failed -QUIT -221 mail.example.net closing connection - - - - -SOCKS ------------------------------------------------------------- -Support for proxying outbound SMTP via a Socks 5 proxy -(RFC 1928) is included if Exim is compiled with -EXPERIMENTAL_SOCKS defined. - -If an smtp transport has a nonempty socks_proxy option -defined, this is active. The option is expanded and -should be a list (colon-separated by default) of -proxy specifiers. Each proxy specifier is a list -(space-separated by default) where the initial element -is an IP address and any subsequent elements are options. - -Options are a string =. -These options are currently defined: -- "auth", with possible values "none" and "name". - Using "name" selects username/password authentication - per RFC 1929. Default is "none". -- "name" sets the authentication username. Default is empty. -- "pass" sets the authentication password. Default is empty. -- "port" sets the tcp port number for the proxy. Default is 1080. -- "tmo" sets a connection timeout in seconds for this proxy. Default is 5. - -Proxies from the list are tried in order until -one responds. The timeout for the overall connection -applies to the set of proxied attempts. - -If events are used, the remote IP/port during a -tcp:connect event will be that of the proxy. - - - - DANE ------------------------------------------------------------ DNS-based Authentication of Named Entities, as applied @@ -1284,99 +1125,46 @@ $tls_out_tlsa_usage (detailed above). -INTERNATIONAL ------------------------------------------------------------- -SMTPUTF8 -Internationalised mail name handling. -RFCs 6530, 6533, 5890 - -Compile with EXPERIMENTAL_INTERNATIONAL and libidn. - -New main config option smtputf8_advertise_hosts, default '*', -a host list. If this matches the sending host and -accept_8bitmime is true (the default) then the ESMTP option -SMTPUTF8 will be advertised. - -If the sender specifies the SMTPUTF8 option on a MAIL command -international handling for the message is enabled and -the expansion variable $message_smtputf8 will have value TRUE. - -The option allow_utf8_domains is set to true for this -message. All DNS lookups are converted to a-label form -whatever the setting of allow_utf8_domains. - -Both localparts and domain are maintained as the original -utf8 form internally; any matching or regex use will -require appropriate care. Filenames created, eg. by -the appendfile transport, will have utf8 name. - -Helo names sent by the smtp transport will have any utf8 -components expanded to a-label form. - -Any certificate name checks will be done using the a-label -form of the name. - -Log lines and Received-by: header lines will aquire a "utf8" -prefix on the protocol element, eg. utf8esmtp. - -New expansion operators: - ${utf8_domain_to_alabel:str} - ${utf8_domain_from_alabel:str} - ${utf8_localpart_to_alabel:str} - ${utf8_localpart_from_alabel:str} - -New "control = utf8_downconvert" ACL modifier, -sets a flag requiring that addresses are converted to -a-label form before smtp delivery, for use in a -Message Submission Agent context. Can also be -phrased as "control = utf8_downconvert/1" and is -mandatory. The flag defaults to zero and can be cleared -by "control = utf8_downconvert/0". The value "-1" -may also be used, to use a-label for only if the -destination host does not support SMTPUTF8. - -If mua_wrapper is set, the utf8_downconvert control -defaults to -1 (convert if needed). - - -There is no explicit support for VRFY and EXPN. -Configurations supporting these should inspect -$smtp_command_argument for an SMTPUTF8 argument. - -There is no support for LMTP on Unix sockets. -Using the "lmtp" protocol option on an smtp transport, -for LMTP over TCP, should work as expected. - -Known issues: - - DSN unitext handling is not present - - no provision for converting logging from or to UTF-8 - ----- -IMAP folder names +DSN extra information +--------------------- +If compiled with EXPERIMENTAL_DSN_INFO extra information will be added +to DSN fail messages ("bounces"), when available. The intent is to aid +tracing of specific failing messages, when presented with a "bounce" +complaint and needing to search logs. -New expansion operator: -${imapfolder {} {} {}} +The remote MTA IP address, with port number if nonstandard. +Example: + Remote-MTA: X-ip; [127.0.0.1]:587 +Rationale: + Several addresses may correspond to the (already available) + dns name for the remote MTA. -The string is converted from the charset specified by the headers charset -command (in a filter file) or headers_charset global option, to the -modified UTF-7 encoding specified by RFC 2060, with the following -exception: All occurences of (which has to be a single character) -are replaced with periods ("."), and all periods and slashes that aren't - and are not in the string are BASE64 encoded. +The remote MTA connect-time greeting. +Example: + X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000 +Rationale: + This string sometimes presents the remote MTA's idea of its + own name, and sometimes identifies the MTA software. -The third argument can be omitted, defaulting to an empty string. -The second argument can be omitted, defaulting to "/". +The remote MTA response to HELO or EHLO. +Example: + X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1] +Limitations: + Only the first line of a multiline response is recorded. +Rationale: + This string sometimes presents the remote MTA's view of + the peer IP connecting to it. -This is the encoding used by Courier for Maildir names on disk, and followed -by many other IMAP servers. +The reporting MTA detailed diagnostic. +Example: + X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:: 550 hard error +Rationale: + This string somtimes give extra information over the + existing (already available) Diagnostic-Code field. - Example 1: ${imapfolder {Foo/Bar}} yields "Foo.Bar". - Example 2: ${imapfolder {Foo/Bar}{.}{/}} yields "Foo&AC8-Bar". - Example 3: ${imapfolder {Räksmörgås}} yields "R&AOQ-ksm&APY-rg&AOU-s". -Note that the source charset setting is vital, and also that characters -must be representable in UTF-16. +Note that non-RFC-documented field names and data types are used.