阅读中文版本

PROXY Protocol for Client Address Preservation

The PROXY protocol prepends the original client address to a connection so a backend behind a load balancer can see the real source IP and port instead of the proxy's.

Definition

PROXY protocol is a lightweight line of metadata that a trusted proxy sends before the real payload, conveying the original connection’s source and destination addresses so the next hop can log and authorise against the true client.

It appears whenever a TLS terminator or layer 4 load balancer must forward connections without rewriting the payload itself, which rules out headers such as X-Forwarded-For. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

The v1 form is a single ASCII line beginning with PROXY and v2 is a binary fixed header, but both rely entirely on the receiver trusting that only the proxy can connect.

Because the address is claimed rather than proven, an exposed listener that accepts PROXY headers lets any client forge its source address and defeat IP allowlists or rate limits.

Trade-offs and alternatives

Parse the header strictly, reject it on untrusted interfaces, and keep a separate port or network policy for health checks that arrive without the prefix. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that any client may send PROXY protocol safely because the server validates it. Another is that the header replaces the need to trust the immediate peer. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to enabling PROXY protocol on ports that are reachable from the public internet and to mixing PROXY-enabled and plain backend ports on the same listener. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Server-Timing Metrics Header, Hop-by-Hop Versus End-to-End Headers, HTTP Trailer Fields.