PROXY Protocol: Trust the Sender Before the Client IP

PROXY protocol carries connection information from an intermediary to a receiving service. The reported original address is meaningful only when the receiver trusts the sender and accepts the protocol on the intended listener. Exposing that listener to arbitrary clients can turn useful metadata into a spoofable identity signal.

The HAProxy PROXY protocol specification describes this trust requirement. It is not an HTTP header and should not be enabled by guessing whether the first bytes of any public connection look like a PROXY message. Match the sender, receiver, and network boundary deliberately.

Identify both addresses

Record the transport peer that actually connects to the service and the original client address reported by the trusted intermediary. They are different observations. Keeping both helps diagnose configuration mistakes and prevents an imported address from erasing evidence about the connection source.

Decide why the original address is needed: logs, rate limits, geographic reporting, or another policy. Do not automatically use it as proof of a user's identity or permission. An IP address is not a replacement for application authentication.

Draw the expected path in a short configuration record: client, approved load balancer, restricted service listener. If there are several intermediaries, determine which one creates the metadata and how subsequent hops handle it. Avoid assuming that every device forwards it unchanged.

Match the protocol settings

Check the supported version and configuration on both ends. Enabling a sender while the receiver expects ordinary application bytes can break the connection. Enabling a receiver while the sender provides no PROXY information can also produce timeouts or protocol errors.

Review the order relative to TLS and the application protocol in the actual product documentation. Do not paste a configuration for a different termination arrangement. A TLS-terminating load balancer and a transport pass-through design can have different receiving expectations.

Use a separate controlled test listener if your environment supports it. Avoid changing a busy public listener without a rollback plan. A short metadata mismatch at the start of every connection can affect the entire service.

Restrict who can reach the receiver

Apply appropriate network filtering so only the intended intermediaries can connect to the PROXY-aware listener. Keep public access on the supported public entry point. Do not create an unrestricted alternate route to the backend merely to simplify testing.

Use the platform's supported access controls and maintain an owner for the allowed sender set. If intermediary addresses change, update the rules through a reviewed process. A stale allowlist can cause outages, while an overly broad one can weaken the boundary.

Don't rely on a secret port number as protection. The requirement is to restrict and verify the sender, not to hope that no one discovers the listener. Preserve normal authentication and authorization above the transport layer.

Test normal and rejected paths

In an authorized test environment, confirm that a request through the approved load balancer reaches the service and records both expected addresses. Then confirm that a direct connection from outside the allowed sender path is blocked by the intended control.

Test the actual application, not only a socket connection. A successful TCP handshake does not prove that the metadata, TLS negotiation, and application request were interpreted correctly. Use a synthetic account or harmless test request where authentication is needed.

Keep the test scoped to your own infrastructure. There is no need to send forged connection metadata to third-party systems. The goal is to verify the boundary you control, not to probe unrelated listeners.

Include health checks and monitoring

Health checks may use a different connection path from ordinary traffic. Confirm whether they send the expected metadata and whether the receiver supports that configuration. A service can appear unhealthy even while real requests work, or appear healthy while application traffic fails.

Record connection failures by stage where possible: sender restriction, metadata parsing, TLS, authentication, and application response. Avoid collapsing every failure into a generic backend-down alert. Distinct stages make the incident easier to diagnose.

Set appropriate parsing and connection deadlines through supported configuration. Do not allow an incomplete preamble to hold resources indefinitely. Conversely, do not choose an arbitrarily tiny timeout that rejects normal network variation without testing.

Roll out with a reversible change

Keep a known working configuration for both sender and receiver. Change a bounded traffic slice first where the platform supports it, verify address observations, and then expand. A rollback must restore the paired expectations rather than changing only one end.

Review logs after deployment to ensure that the transport peer remains visible and the reported client field has the expected source. Check that monitoring and rate-limit components consume the intended field rather than a similarly named untrusted value.

Text Diff can compare redacted listener and load-balancer settings. It cannot validate network filtering or authenticate a metadata sender. For broader API boundaries, see endpoint authentication checks.

Conclusion

PROXY protocol is useful connection metadata within an explicit trust boundary. Restrict the sender path, match both ends, and test TLS, health checks, and application behavior. Keep the actual transport peer separate from the reported original client instead of treating either field as universal identity proof.