Client IP preservation

Enable the Proxy Protocol

When the load balancer proxies a TCP connection, it overwrites the client’s source IP address with its own when communicating with the backend server. The Proxy Protocol adds a header to a TCP connection to preserve the client’s IP address. This method solves the lost-client-IP problem for any application-layer protocol that transmits its messages over TCP/IP. To work, both the sender (the load balancer) and receiver (backend server) must support the protocol and have it enabled.

The load balancer adds the header to TCP connections before relaying them to upstream servers. When placed behind another proxy, it can also receive the Proxy Protocol header attached to the incoming connection. This feature supports IPv4 and IPv6 addresses.

Receive the Proxy Protocol Jump to heading

To accept a Proxy Protocol header on incoming TCP connections:

  1. Add an accept-proxy argument to the bind line in a frontend section. This argument detects both Proxy Protocol version 1 (text format) and Proxy Protocol version 2 (binary format).

    The example below accepts the Proxy Protocol header from incoming connections:

    haproxy
    frontend mywebsite
    bind :80 accept-proxy
    default_backend webservers
    haproxy
    frontend mywebsite
    bind :80 accept-proxy
    default_backend webservers

Send the Proxy Protocol Jump to heading

To send a Proxy Protocol version 1 header (text format) to the backend servers:

  • Add a send-proxy argument to the server lines in a backend section:

    haproxy
    backend webservers
    balance roundrobin
    server s1 192.168.56.20:3000 check send-proxy
    server s2 192.168.56.21:3000 check send-proxy
    haproxy
    backend webservers
    balance roundrobin
    server s1 192.168.56.20:3000 check send-proxy
    server s2 192.168.56.21:3000 check send-proxy

To send a Proxy Protocol version 2 header (binary format) to the backend servers:

  • Add a send-proxy-v2 argument to the server lines in a backend section:

    haproxy
    backend webservers
    balance roundrobin
    server s1 192.168.56.20:3000 check send-proxy-v2
    server s2 192.168.56.21:3000 check send-proxy-v2
    haproxy
    backend webservers
    balance roundrobin
    server s1 192.168.56.20:3000 check send-proxy-v2
    server s2 192.168.56.21:3000 check send-proxy-v2

Proxy Protocol on AWS Network Load Balancers Jump to heading

AWS NLB can use the Proxy Protocol to set the IP address in requests. Enable this feature as described here:

Then add the keyword accept-proxy to your bind line, as described in the section Receive the Proxy Protocol. The requests will then automatically have the right source IP address.

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?