diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/doc-docbook/spec.xfpt | 103 | ||||
-rw-r--r-- | doc/doc-txt/ChangeLog | 4 | ||||
-rw-r--r-- | doc/doc-txt/experimental-spec.txt | 145 |
3 files changed, 106 insertions, 146 deletions
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 73887d4e7..6096e1df2 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -12033,6 +12033,16 @@ qualified host name. See also &$smtp_active_hostname$&. .new +.vitem &$proxy_host_address$& &&& + &$proxy_host_port$& &&& + &$proxy_target_address$& &&& + &$proxy_target_port$& &&& + &$proxy_session$& +These variables are only available when built with Proxy Protocol support +For details see chapter &<<SECTproxyInbound>>&. +.wen + +.new .vitem &$prdr_requested$& .cindex "PRDR" "variable for" This variable is set to &"yes"& if PRDR was requested by the client for the @@ -13469,6 +13479,7 @@ listed in more than one group. .row &%helo_verify_hosts%& "HELO hard-checked for these hosts" .row &%host_lookup%& "host name looked up for these hosts" .row &%host_lookup_order%& "order of DNS and local name lookups" +.row &%hosts_proxy%& "use proxy protocol for these hosts" .row &%host_reject_connection%& "reject connection from these hosts" .row &%hosts_treat_as_local%& "useful in some cluster configurations" .row &%local_scan_timeout%& "timeout for &[local_scan()]&" @@ -14824,6 +14835,14 @@ If the &%smtp_connection%& log selector is not set, this option has no effect. +.new +.option hosts_proxy main "host list&!!" unset +.cindex proxy "proxy protocol" +This option enables use of Proxy Protocol proxies for incoming +connections. For details see &<<SECTproxyInbound>>&. +.wen + + .option hosts_treat_as_local main "domain list&!!" unset .cindex "local host" "domains treated as" .cindex "host" "treated as local" @@ -35461,6 +35480,9 @@ selection marked by asterisks: &` queue_time `& time on queue for one recipient &` queue_time_overall `& time on queue for whole message &` pid `& Exim process id +.new +&` proxy `& proxy address on <= lines +.wen &` received_recipients `& recipients on <= lines &` received_sender `& sender on <= lines &`*rejected_header `& header contents on reject log @@ -35587,6 +35609,16 @@ rejection lines, and (despite the name) to outgoing &"=>"& and &"->"& lines. The latter can be disabled by turning off the &%outgoing_interface%& option. .wen .next +.new +.cindex log "incoming proxy address" +.cindex proxy "logging proxy address" +.cindex "TCP/IP" "logging proxy address" +&%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. +See &<<SECTproxyInbound>>& for more information. +.wen +.next .cindex "log" "incoming remote port" .cindex "port" "logging remote" .cindex "TCP/IP" "logging incoming remote port" @@ -38025,6 +38057,74 @@ for more information of what they mean. A proxy is an intermediate system through which communication is passed. Proxies may provide a security, availability or load-distribution function. + +.section "Inbound proxies" SECTproxyInbound +.cindex proxy inbound +.cindex proxy "server side" +.cindex proxy "Proxy protocol" +.cindex "Proxy protocol" proxy + +Exim has support for receiving inbound SMTP connections via a proxy +that uses &"Proxy Protocol"& to speak to it. +To include this support, include &"SUPPORT_PROXY=yes"& +in Local/Makefile. + +It was built on specifications from: +http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt +That URL was revised in May 2014 to version 2 spec: +http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e + +The purpose of this facility is so that an application load balancer, +such as HAProxy, can sit in front of several Exim servers +to distribute load. +Exim uses the local protocol communication with the proxy to obtain +the remote SMTP system IP address and port information. +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). + +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. + +To log the IP of the proxy in the incoming logline, add &"+proxy"& +to the &%log_selector%& option. +This will add a component tagged with &"PRX="& to the line. + +The following expansion variables are usable +(&"internal"& and &"external"& here refer to the interfaces +of the proxy): +.display +&'proxy_host_address '& internal IP address of the proxy +&'proxy_host_port '& internal TCP port of the proxy +&'proxy_target_address '& external IP address of the proxy +&'proxy_target_port '& external TCP port of the proxy +&'proxy_session '& boolean: SMTP connection via proxy +.endd +If &$proxy_session$& is set but &$proxy_host_address$& is empty +there was a protocol error. + +Since the real connections are all coming from the 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 option set so high, you lose the ability +to protect your server from many connections from one IP. +In order to prevent your server from overload, you +need to add a per connection ratelimit to your connect ACL. +A possible solution is: +.display + # 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 +.endd + + + .section "Outbound proxies" SECTproxySOCKS .cindex proxy outbound .cindex proxy "client side" @@ -38035,7 +38135,8 @@ using a protocol called SOCKS5 (defined by RFC1928). The support can be optionally included by defining SUPPORT_SOCKS=yes in Local/Makefile. -Use of a proxy is enabled by setting the &%socks_proxy%& on an smtp transport. +Use of a proxy is enabled by setting the &%socks_proxy%& option +on an smtp transport. The option value is expanded and should then be a list (colon-separated by default) of proxy specifiers. Each proxy specifier is a list diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog index d57c3db00..1fa19daad 100644 --- a/doc/doc-txt/ChangeLog +++ b/doc/doc-txt/ChangeLog @@ -115,6 +115,10 @@ JH/22 Bugs 963, 1721: Fix some corner cases in message body canonicalisation JH/23 Move SOCKS5 support from Experimental to mainline, enabled for a build by defining SUPPORT_SOCKS. +JH/26 Move PROXY support from Experimental to mainline, enabled for a build + by defining SUPPORT_PROXY. Note that the proxy_required_hosts option + is renamed to hosts_proxy. + Exim version 4.86 ----------------- diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index f0f1035ea..45e7d1ba1 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -973,151 +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 - - - - DANE ------------------------------------------------------------ DNS-based Authentication of Named Entities, as applied |