Skip to content
GProxy
Sign up
Glossary 8 Connection Type: 1 views

PROXY Protocol

Understand the PROXY Protocol and how it enables services like GProxy to correctly identify the original client IP address when behind a proxy, enhancing logging and analytics.

The PROXY Protocol enables a proxy or load balancer to communicate the original client's connection information, including their real IP address and port, to the backend server by prepending a small, standardized header to the beginning of the TCP connection.

Why PROXY Protocol? The Problem It Solves

Standard TCP proxies operate by establishing a new connection to the backend server on behalf of the client. From the backend server's perspective, the connection originates from the proxy's IP address, not the original client's. This behavior obscures the client's true identity, creating several challenges:

  • Logging: Server access logs record the proxy's IP, making it impossible to trace requests back to individual clients.
  • Security: Web Application Firewalls (WAFs), rate limiters, and access control lists (ACLs) on backend servers cannot accurately identify and block malicious clients based on their real IP addresses.
  • Analytics: Geo-targeting, personalized content delivery, and abuse detection systems lose critical client location and behavioral data.
  • Debugging: Troubleshooting network issues or specific client behaviors becomes significantly more complex without visibility into the original client source.

The PROXY Protocol addresses this by providing a mechanism for the proxy to transmit the client's connection details (source IP, source port, destination IP, destination port) across the proxy layer, allowing the backend server to correctly identify the original client.

How PROXY Protocol Works

The PROXY Protocol operates at the transport layer (Layer 4) of the OSI model. When a proxy or load balancer that supports the PROXY Protocol receives a connection from a client, it establishes a new connection to the backend server. Before sending any application-layer data (e.g., HTTP requests, database queries), the proxy first sends a PROXY Protocol header. This header contains the client's connection information.

For the PROXY Protocol to function correctly, two conditions must be met:
1. The proxy or load balancer must be configured to send the PROXY Protocol header.
2. The backend server must be configured to receive and parse the PROXY Protocol header before processing any application-layer data. If the backend server does not understand the header, it will interpret it as malformed application data, leading to connection errors.

PROXY Protocol Versions

There are two primary versions of the PROXY Protocol: v1 and v2.

Version 1 (v1)

PROXY Protocol v1 is an ASCII-based, human-readable format. It supports IPv4 and IPv6 over TCP.

Format:
PROXY <INET_PROTOCOL> <CLIENT_IP> <PROXY_IP> <CLIENT_PORT> <PROXY_PORT>\r\n

  • <INET_PROTOCOL>: TCP4 for IPv4 or TCP6 for IPv6.
  • <CLIENT_IP>: The original client's IP address.
  • <PROXY_IP>: The proxy's IP address (the IP the backend sees as the source of the connection).
  • <CLIENT_PORT>: The original client's source port.
  • <PROXY_PORT>: The destination port on the proxy that the client connected to.

Example (IPv4):

PROXY TCP4 192.168.1.1 10.0.0.1 52345 80\r\n

This header indicates a TCPv4 connection from client 192.168.1.1:52345 to the proxy, which then connected to the backend on 10.0.0.1:80.

Limitations of v1:
* Limited to TCP connections.
* ASCII overhead can be slightly less efficient.
* Does not support additional metadata.

Version 2 (v2)

PROXY Protocol v2 is a binary format designed for efficiency and extensibility. It supports IPv4, IPv6, and UNIX sockets over TCP and UDP, and includes a Type-Length-Value (TLV) field mechanism for transmitting additional connection metadata.

Advantages of v2:
* Efficiency: Binary format reduces header size.
* Wider Protocol Support: Supports TCP, UDP, and UNIX sockets.
* IPv6 Support: Fully integrates IPv6.
* Extensibility (TLV): Allows for arbitrary metadata to be passed, such as SSL connection information, unique connection IDs, or other application-specific data.

Structure Overview (simplified):
The v2 header starts with a 13-byte signature, followed by a 1-byte version/command field, a 1-byte protocol field, a 2-byte address length field, and then the variable-length address information and optional TLV fields.

While the raw binary format is complex, the key takeaway is its ability to transmit more information efficiently and across a broader range of protocols.

PROXY Protocol vs. X-Forwarded-For (XFF)

Both PROXY Protocol and the X-Forwarded-For (XFF) HTTP header aim to pass client IP information through a proxy. However, they operate at different layers and have distinct characteristics.

Feature PROXY Protocol X-Forwarded-For (XFF) Header
Layer of Operation Transport Layer (L4) Application Layer (L7 - specifically HTTP)
Protocol Scope Any TCP/UDP-based protocol (HTTP, FTP, SSH, SMTP, etc.) HTTP/HTTPS only
Mechanism Prepended header to the raw TCP/UDP stream HTTP request header
Client Control Cannot be forged by a malicious client after the first trusted proxy Can be forged by a malicious client if not properly handled by the first trusted proxy
Information Client IP, client port, proxy IP, proxy port, (v2: TLVs) Client IP (and potentially previous proxy IPs)
Overhead Minimal, fixed-size (v1) or small binary (v2) Small string added to HTTP headers
Use Cases Any TCP/UDP service needing real client IP HTTP/HTTPS services needing real client IP

The PROXY Protocol offers a more robust and universal solution for passing client IP information, especially for non-HTTP services or scenarios where strong guarantees against client IP spoofing are required at the network layer.

Implementing PROXY Protocol

Implementing PROXY Protocol requires configuration on both the sending proxy/load balancer and the receiving backend server.

Proxy/Load Balancer Configuration (Sending PROXY Protocol)

HAProxy:
HAProxy is a common choice for load balancing and fully supports PROXY Protocol.

frontend http_in
    bind *:80
    mode tcp
    default_backend web_servers

backend web_servers
    mode tcp
    server s1 192.168.1.10:80 send-proxy-v2 # Sends PROXY Protocol v2
    server s2 192.168.1.11:80 send-proxy    # Sends PROXY Protocol v1

AWS Network Load Balancer (NLB):
When configuring a Target Group for an NLB, you can enable PROXY Protocol v2 support. This setting is applied to the entire target group. All targets in that group must be configured to accept PROXY Protocol.

Cloudflare Spectrum:
For services proxied through Cloudflare Spectrum, you can enable PROXY Protocol support. Cloudflare will send PROXY Protocol v2 headers to your origin servers.

Nginx (Stream Module - as a proxy):
Nginx's ngx_stream_proxy_module can be configured to send PROXY Protocol, primarily in its commercial version or specific builds.

stream {
    upstream backend_servers {
        server 192.168.1.10:80;
        server 192.168.1.11:80;
    }
    server {
        listen 12345;
        proxy_pass backend_servers;
        proxy_protocol on; # Nginx sends PROXY Protocol v1
    }
}

Backend Server Configuration (Receiving and Parsing PROXY Protocol)

Nginx (as a backend web server):
Nginx can be configured to listen for and parse PROXY Protocol headers.

http {
    server {
        listen 80   proxy_protocol; # Listen for PROXY Protocol v1/v2 on port 80
        listen 443  ssl proxy_protocol;

        set_real_ip_from 10.0.0.0/8; # Trust IPs from your proxy network
        real_ip_header proxy_protocol; # Use the IP from the PROXY Protocol header

        location / {
            root /var/www/html;
            index index.html;
            # The client's real IP will now be available in $remote_addr
            # and $proxy_protocol_addr can be used for logging or specific logic
            log_format custom_log '$proxy_protocol_addr - $remote_user [$time_local] '
                                  '"$request" $status $body_bytes_sent '
                                  '"$http_referer" "$http_user_agent"';
            access_log /var/log/nginx/access.log custom_log;
        }
    }
}

In Nginx, $remote_addr will be set to the proxy's IP, but $proxy_protocol_addr and $proxy_protocol_port variables will contain the client's real IP and port. The set_real_ip_from and real_ip_header proxy_protocol directives allow Nginx to correctly populate $remote_addr with the client's actual IP.

Apache HTTP Server:
Apache can utilize the mod_remoteip module to parse PROXY Protocol headers.

<IfModule mod_remoteip.c>
    # Enable PROXY Protocol parsing
    RemoteIPProxyProtocol On

    # Define trusted proxies
    RemoteIPTrustedProxy 10.0.0.0/8
    RemoteIPTrustedProxy 192.168.0.0/16

    # Configure the log format to use the real client IP
    LogFormat "%a %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
</IfModule>

With RemoteIPProxyProtocol On, Apache will expect the PROXY Protocol header. The %a variable in LogFormat will then correctly reflect the client's real IP.

Custom Applications:
For custom applications written in languages like Python, Node.js, Go, or Java, the application itself needs to read the incoming TCP stream, check for the PROXY Protocol header, parse it, and then proceed with the application-specific protocol.

  • Detection: The application must first read a few bytes (e.g., 100-200 bytes) from the socket to check if they match the PROXY Protocol v1 signature (PROXY) or the v2 signature.
  • Parsing: If a PROXY Protocol header is detected, the application parses it to extract the client IP, port, etc.
  • Continuation: After parsing, the application then processes the remaining data on the socket as its native protocol.
  • No Header: If no PROXY Protocol header is found, the application assumes the connection is directly from a client or a non-PROXY Protocol proxy and processes the data directly.

Many networking libraries and frameworks offer middleware or built-in support for PROXY Protocol parsing.

Benefits of Using PROXY Protocol

  • Accurate IP Logging: Ensures that server access logs, firewalls, and monitoring systems record the true client IP address.
  • Enhanced Security: Allows security tools (WAFs, DDoS mitigation, rate limiters) on backend servers to enforce policies based on the client's real identity.
  • Improved Analytics: Provides accurate geographic and demographic data for analytics, A/B testing, and personalization.
  • Simplified Network Architecture: Consolidates client IP handling at the transport layer, reducing the need for application-specific headers like XFF.
  • Broad Compatibility: Works with any TCP/UDP-based application, not just HTTP.

Considerations and Best Practices

  • Trust Boundaries: Only enable PROXY Protocol from trusted proxies or load balancers that you control. If an untrusted entity sends a forged PROXY Protocol header, your backend server could be misled about the client's origin.
  • End-to-End Compatibility: Ensure both the proxy and the backend server are correctly configured to send and receive the specific PROXY Protocol version (v1 or v2). Mismatches will lead to connection failures.
  • Performance: The overhead introduced by the PROXY Protocol header is minimal, especially with v2's binary format. However, parsing on every connection adds a small, negligible processing cost.
  • Monitoring: Monitor your backend server logs and network traffic to verify that client IPs are being correctly identified and that no unexpected PROXY Protocol errors are occurring.
Auto-update: 03.03.2026
All Categories

Advantages of our proxies

25,000+ proxies from 120+ countries

Unlimited Proxies Residential Proxies