What is the Proxy Protocol setting, and when should it be enabled?

Short answer

When the Proxy field in the Backend Service is enabled (Proxy = Proxy Protocol v1, Proxy v2 = v2), on HTTP and L7 TCP vServices TR7 sends the real IP and port information of the client at the very beginning of each connection it opens to the Backend Service, before the application data; its default value is No Proxy. This way, the server knows the address of the client even though it receives the connection from TR7. It is enabled only if the server supports this protocol and is configured to expect it; otherwise the server takes the header for application data and the connections break. It is mostly used in TCP services where the client IP cannot be carried with an HTTP header (e.g. e-mail) and in cases where X-Forwarded-For is not enough.

How Does It Work?

1. TR7 opens the connection to the Backend Service.
2. As the first data, it sends a header that contains the IP and port of the client: Proxy (v1) is in text format, Proxy v2 is in binary format.
3. The server reads the header, records the client address and processes the rest of the connection as normal application data.

Option	What is sent
No Proxy (default)	No header is sent; the server sees the IP of TR7
Proxy	Text-based Proxy Protocol v1 header
Proxy v2	Binary Proxy Protocol v2 header

When Should It Be Enabled?

Situation	Proxy Protocol
HTTP vService, the server can read X-Forwarded-For	Not required; X-Forwarded-For is enough
A non-HTTP service with L7 TCP (SMTP, IMAP, custom TCP) and the client IP is required	Enabled if the server supports it
The client IP is required, but TR7 cannot be placed in the return path of the server (Use Client IP cannot be used)	Enabled if the server supports it
The server does not support Proxy Protocol	Not enabled; SNAT → Use Client IP is considered

In TR7

• Where: Load Balancer → Backend Services → Edit → Details switch → Proxy; it is saved with the Edit button at the bottom of the form. In a Backend Group, it is at the group level.
• vService type: HTTP and L7 TCP. On a Network vService, the field is not applied.
• Server side: The Proxy Protocol listener setting on the server is enabled at the same time as the change in TR7; connections fail in the time that passes between the settings. The server is made to trust only the header coming from the IP of TR7.
• Together with SSL Service: The header is sent before the TLS handshake; the TLS port of the server must also expect Proxy Protocol.
• Health check: The health checks of TR7 do not send the Proxy Protocol header. An HTTP or SMTP check made to the port that expects the header is rejected; a check of the TCP type is used, or a separate health port is checked with Use Different IP for Health Check.
• Cluster: While Clustering is on and Manual Sync Mode is off (default), the setting is transferred to the peer device automatically.

Common Misconceptions

• "Enabling Proxy Protocol is harmless; if the server does not understand it, it ignores it." The server reads the header as application data and the connection fails; the server is configured first.
• "v1 and v2 are the same." Their formats are different; the version the server expects is selected.
• "The health check also sends the header." It does not; a check of the HTTP type shows the server as down on a port that expects Proxy Protocol.

How it is done in the documentation

• Backend Services · Proxy
• Backend Services · Proxy v2
• Backend Services · Use Different IP for Health Check

Related questions

• What is the difference between X-Forwarded-For and Proxy Protocol?
• Why do my backend servers see all requests as coming from TR7's IP?
• Can I load balance SMTP / mail servers?