Skip to content
AITroveRead. Build. Understand.
Reading list
Make this comfortable

PROXY protocol: accept client metadata only from the intended load balancer

Last updated: 5 Oct 20266 min read
tutorial
AdvancedBy AITrove Editorial

The PROXY protocol places connection metadata before the application protocol so a load balancer can convey the original client address. It is not an authentication scheme. A listener expecting this preface will reject ordinary clients that do not send it, while a listener exposed to untrusted senders can receive forged metadata. The proxy and backend must agree on the protocol version, listener mode, and trusted source boundary.

Operational decision

A receipt TCP gateway needs the caller address for abuse investigation. Create a dedicated backend listener that accepts PROXY metadata only from the load balancer's known network or identity boundary; keep the direct diagnostic listener separate. Configure the load balancer to send the agreed version and verify a real request reaches the application with both reported client address and immediate peer recorded. Try a direct test connection without the preface and confirm it cannot reach a privileged request path. Also test a forged preface from an untrusted network and confirm network controls block it before the application trusts it. Change one side of the protocol setting in an isolated environment to observe the failure signature, then restore it. During load-balancer replacement, update trusted sources and audit logs together so a temporary broad allow rule does not remain after cutover.

Output
Receipt PROXY listener contract
Upstream sender: named load balancer only
Transport: dedicated backend port and agreed PROXY version
Network rule: deny all other source networks
Application log: original client plus immediate peer
Negative test: direct and forged prefaces cannot bypass the boundary

Cost and verification

A separate listener and network rule add deployment and test work. The preface adds a small amount of connection data, but the material risk is an incorrect trust boundary that makes rate limits and audit records unreliable. Measure rejected direct connections, version mismatch errors, original-client coverage, and proxy peer changes. If the upstream already terminates HTTP and can set a validated forwarding header, compare the simpler route before adding another transport contract.

Common Mistakes

  • Do not expose a PROXY-aware listener directly to arbitrary clients.
  • Do not assume the embedded client address is authenticated.
  • Do not enable the protocol on only one side of a connection.

Connected lessons

Practice and check

devops
operations
Storage details