Accepting the PROXY Protocol

This article explains how to configure NGINX and F5 NGINX Plus to accept the PROXY protocol, rewrite the IP address of a load balancer or proxy to the one received in the PROXY protocol header, configure simple logging of a client’s IP address, and enable the PROXY protocol between NGINX and a TCP upstream server.

Introduction

The PROXY protocol enables NGINX and NGINX Plus to receive client connection information passed through proxy servers and load balancers such as HAproxy and Amazon Elastic Load Balancer (ELB).

With the PROXY protocol, NGINX can learn the originating IP address from HTTP, SSL, HTTP/2, SPDY, WebSocket, and TCP. Knowing the originating IP address of a client may be useful for setting a particular language for a website, keeping a denylist of IP addresses, or simply for logging and statistics purposes.

The information passed via the PROXY protocol is the client IP address, the proxy server IP address, and both port numbers.

Using this data, NGINX can get the originating IP address of the client in several ways:

With the $proxy_protocol_addr and $proxy_protocol_port variables which capture the original client IP address and port. The $remote_addr and $remote_port variables capture the IP address and port of the load balancer.
With the RealIP module which rewrites the values in the $remote_addr and $remote_port variables, replacing the IP address and port of the load balancer with the original client IP address and port. The $realip_remote_addr and $realip_remote_port variables retain the address and port of the load balancer, and the $proxy_protocol_addr and $proxy_protocol_port variables retain the original client IP address and port anyway.

Prerequisites

To accept the PROXY protocol v2, NGINX Plus R16 and later or NGINX Open Source 1.13.11 and later
To accept the PROXY protocol for HTTP, NGINX Plus R3 and later or NGINX Open Source 1.5.12 and later
For TCP client‑side PROXY protocol support, NGINX Plus R7 and later or NGINX Open Source 1.9.3 and later
To accept the PROXY protocol for TCP, NGINX Plus R11 and later or NGINX Open Source 1.11.4 and later
The Real‑IP modules for HTTP and Stream TCP are not included in NGINX Open Source by default; see Installing NGINX Open Source for details. No extra steps are required for NGINX Plus.

Configuring NGINX to Accept the PROXY Protocol

To configure NGINX to accept PROXY protocol headers, add the proxy_protocol parameter to the listen directive in a server block in the http {} or stream {} block.

http {
    #...
    server {
        listen 80   proxy_protocol;
        listen 443  ssl proxy_protocol;
        #...
    }
}

stream {
    #...
    server {
        listen 12345 proxy_protocol;
        #...
    }
}

Now you can use the $proxy_protocol_addr and $proxy_protocol_port variables for the client IP address and port and additionally configure the HTTP and stream RealIP modules to replace the IP address of the load balancer in the $remote_addr and $remote_port variables with the IP address and port of the client.

Changing the Load Balancer’s IP Address To the Client IP Address

You can replace the address of the load balancer or TCP proxy with the client IP address received from the PROXY protocol. This can be done with the HTTP and stream RealIP modules. With these modules, the $remote_addr and $remote_port variables retain the real IP address and port of the client, while the $realip_remote_addr and $realip_remote_port variables retain the IP address and port of the load balancer.

To change the IP address from the load balancer’s IP address to the client’s IP address:

Make sure you’ve configured NGINX to accept the PROXY protocol headers. See Configuring NGINX to Accept the PROXY Protocol.
Make sure that your NGINX installation includes the HTTP and Stream Real‑IP modules:
```
nginx -V 2>&1 | grep -- 'http_realip_module'
nginx -V 2>&1 | grep -- 'stream_realip_module'
```
If not, recompile NGINX with these modules. See Installing NGINX Open Source for details. No extra steps are required for NGINX Plus.
In the set_real_ip_from directive for HTTP, Stream, or both, specify the IP address or the CIDR range of addresses of the TCP proxy or load balancer:
```
server {
    #...
    set_real_ip_from 192.168.1.0/24;
   #...
}
```
In the http {} context, change the IP address of the load balancer to the IP address of the client received from the PROXY protocol header, by specifying the proxy_protocol parameter to the real_ip_header directive:
```
http {
    server {
        #...
        real_ip_header proxy_protocol;
      }
}
```

Logging the Original IP Address

When you know the original IP address of the client, you can configure the correct logging:

For HTTP, configure NGINX to pass the client IP address to upstream servers using the $proxy_protocol_addr variable with the proxy_set_header directive:

http {
    proxy_set_header X-Real-IP       $proxy_protocol_addr;
    proxy_set_header X-Forwarded-For $proxy_protocol_addr;
}

Add the $proxy_protocol_addr variable to the log_format directive (HTTP or Stream):

In the http block:

http {
    #...
    log_format combined '$proxy_protocol_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';
}

In the stream block:

stream {
    #...
    log_format basic '$proxy_protocol_addr - $remote_user [$time_local] '
                      '$protocol $status $bytes_sent $bytes_received '
                      '$session_time';
}

PROXY Protocol for a TCP Connection to an Upstream

For a TCP stream, the PROXY protocol can be enabled for connections between NGINX and an upstream server. To enable the PROXY protocol, include the proxy_protocol directive in a server block at the stream {} level:

stream {
    server {
        listen 12345;
        proxy_pass example.com:12345;
        proxy_protocol on;
    }
}

Example

http {
    log_format combined '$proxy_protocol_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';
    #...

    server {
        server_name localhost;

        listen 80   proxy_protocol;
        listen 443  ssl proxy_protocol;

        ssl_certificate      /etc/nginx/ssl/public.example.com.pem;
        ssl_certificate_key  /etc/nginx/ssl/public.example.com.key;

        location /app/ {
            proxy_pass       http://backend1;
            proxy_set_header Host            $host;
            proxy_set_header X-Real-IP       $proxy_protocol_addr;
            proxy_set_header X-Forwarded-For $proxy_protocol_addr;
        }
    }
}

stream {
    log_format basic '$proxy_protocol_addr - $remote_user [$time_local] '
                     '$protocol $status $bytes_sent $bytes_received '
                     '$session_time';
    #...
    server {
        listen              12345 ssl proxy_protocol;

        ssl_certificate     /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/cert.key;

        proxy_pass          backend.example.com:12345;
        proxy_protocol      on;
    }
}

The example assumes that there is a load balancer in front of NGINX to handle all incoming HTTPS traffic, for example Amazon ELB. NGINX accepts HTTPS traffic on port 443 (listen 443 ssl;), TCP traffic on port 12345, and accepts the client’s IP address passed from the load balancer via the PROXY protocol as well (the proxy_protocol parameter to the listen directive in both the http {} and stream {} blocks.

NGINX terminates HTTPS traffic (the ssl_certificate and ssl_certificate_key directives) and proxies the decrypted data to a backend server:

For HTTP: proxy_pass http://backend1;
For TCP: proxy_pass backend.example.com:12345

It includes the client IP address and port with the proxy_set_header directives.

The $proxy_protocol_addr variable specified in the log_format directive also passes the client’s IP address to the log for both HTTP and TCP.

Additionally, a TCP server (the stream {} block) sends its own PROXY protocol data to its backend servers (the proxy_protocol on directive).

Last modified August 22, 2024