Proxy Protocol

• Table of Contents
• Introduction
• Configuration
• Example configuration
• Example usage of smtp_source_ip
• Example of a global proxy server
• PROXY establishment
• Caveat about Remote Delivery Attempt Error Messages
• Caveat about remote timeouts

Introduction

GreenArrow supports version 1 of HAProxy’s PROXY Protocol. This allows for delivery of email through IP addresses which are not bound to the system on which GreenArrow is installed.

Some use cases for this include:

• Running GreenArrow in Docker.
• Running GreenArrow behind NAT.
• Using the same IP addresses on multiple GreenArrow installations.

GreenArrow will establish a PROXY connection to the server upon delivery.

Configuration

The configuration directive proxy_server is used to configure PROXY support. Each IP address configured in GreenArrow can have one or more proxy_server directives configured. The proxy_server grouping context defines a proxy server to use when delivering email for an ip_address.

If multiple proxies are configured and GreenArrow cannot connect to the first proxy server, it will try the second and continue through the list. If it cannot connect to any listed proxy, the message will be temporarily deferred.

The following directives are used to configure PROXY support:

• proxy_server
• proxy_server_local_bind

Example configuration

ip_address ip-address-1 {
  smtp_source_ip 2.3.4.5
  smtp_source_hostname client.example.com

  # Preferred proxy server
  # If smtp_source_ip or smtp_source_hostname are not listed in the proxy_server
  # directive, then the IP address's settings will be used.
  proxy_server 1.2.3.4:3030

  # Backup proxy server - override the IP's smtp_source_ip and smtp_source_hostname
  # for the different proxy server's available IP address.
  proxy_server 1.2.3.5:3131 {
    smtp_source_ip 2.3.4.6
    smtp_source_hostname client2.example.com
  }
}

In the above example, when attempting to deliver from ip-address-1:

• GreenArrow will attempt to make a connection to the proxy server at 1.2.3.4:3030 and request that this proxy initiate an outgoing connection from 2.3.4.5 to the remote SMTP service. If a connection is established, client.example.com will be used as the server’s name in the HELO/EHLO command.

• If unable to connect to this first proxy, then GreenArrow will attempt to make a connection to the proxy at 1.2.3.5:3131 and request that this proxy initiate an outgoing connection from 2.3.4.6 to the remote SMTP service. If a connection is established, client2.example.com will be used as the server’s name in the HELO/EHLO command.

• If neither proxy server can be connected to, the message will be deferred. It can be useful to turn on log_smtp_commands for diagnosing proxy server connection issues.

Example usage of smtp_source_ip

The purpose of being able to specify smtp_source_ip for a proxy server is that you might have multiple proxy servers which are behind reverse-NAT. Specifying the directive smtp_source_ip on each proxy_server lets you have the following configuration.

• proxy server 10.0.10.2
  • has local IP 10.0.10.3 which is reverse-NAT’ed to the public ip 1.2.3.4
• proxy server 10.0.11.2
  • has local IP 10.0.11.3 which is reverse-NAT’ed to the public ip 1.2.3.4

In this case you would configure:

proxy_server 10.0.10.2:3030 {
   smtp_source_ip 10.0.10.3
}
proxy_server 10.0.11.2:3030 {
   smtp_source_ip 10.0.11.3
}

This provides you with failover in case the proxy server at IP address 10.0.10.2:3030 is unavailable.

Example of a global proxy server

If you have a single proxy server from which you’d like all connections to originate, the ip_address * syntax is useful for this.

ip_address * {
  proxy_server proxy.example.com:2020 {
    smtp_source_ip 1.2.3.4
    smtp_source_hostname client.example.com
  }
}

In the above example, all outbound SMTP connections from GreenArrow (across all IP addresses) will use the proxy server proxy.example.com:2020.

This configuration may be useful for users of GreenArrow Docker Integration, where the container might not have any externally bound IP addresses.

PROXY establishment

GreenArrow establishes the proxy with the PROXY command like:

PROXY TCP4 source-ip remote-ip source-port remote-port\r\n

• source-ip is the IP address as configured in GreenArrow (when configured in greenarrow.conf, this is the value of smtp_source_ip).
• remote-ip is the MX IP destination as resolved by the GreenArrow MTA.
• source-port is always 0, allowing the proxy to select a source port.
• remote-port is the remote port of the destination as resolved by the GreenArrow MTA. This is usually port 25.

Caveat about Remote Delivery Attempt Error Messages

Due to limitations of the PROXY protocol, when using proxy_server the remote delivery attempt error message “Sorry, I wasn’t able to establish an SMTP connection. (#4.4.1)” could mean any of the following:

1. The proxy could not establish a connection to the remote SMTP server.
2. The proxy established a connection to the remote SMTP server, which closed the connection without writing anything.
3. The proxy established a connection to the remote SMTP server, but the remote SMTP server didn’t write anything and then we reached the configured remote SMTP timeout.

If the proxy server itself cannot be connected to, the error message “Connection to proxy server cannot be established. (#4.4.1)” will be returned.

Caveat about remote timeouts

Ordinarily, the connection timeout is separate from the configured remote SMTP timeout. However, when using proxy_server, reading the remote SMTP server’s greeting is treated as part of the connection timeout, rather than the remote SMTP timeout.