ngx_http_realip_module

Restore the client address from a proxy header or PROXY protocol

compiled inBSD-2-Clausesource docs

Overview

ngx_http_realip_module changes the client address, and optionally the client port, to the values sent in a specified header field. It is used when nginx sits behind a load balancer, CDN or other proxy and the address seen on the socket belongs to that proxy rather than to the visitor.

Replacement happens only for connections coming from addresses listed with set_real_ip_from, which accepts an address, a CIDR range, a hostname (1.13.1) or unix: for all UNIX-domain sockets. With real_ip_recursive on, the last address in the header that is not trusted is used instead of the last address. The original values stay available in $realip_remote_addr (1.9.7) and $realip_remote_port (1.11.0).

It is an official nginx module and is not built by default upstream, so it needs the --with-http_realip_module configure parameter. A typical use is reading X-Forwarded-For behind a CDN so that access logs, access rules and rate limits see the real visitor address.

Key directives

set_real_ip_fromDefines trusted addresses known to send correct replacement addresses: address, CIDR, hostname or unix:.

real_ip_headerHeader field whose value replaces the client address, default X-Real-IP; proxy_protocol uses the PROXY header.

real_ip_recursiveWhen on, uses the last non-trusted address from the header instead of the last address, default off.

$realip_remote_addrKeeps the original client address as seen on the connection (1.9.7).

$realip_remote_portKeeps the original client port (1.11.0).

Example

nginx.conf

server { listen 80; # only trust the address chain when the connection comes from our proxies set_real_ip_from 192.168.1.0/24; set_real_ip_from 192.168.2.1; set_real_ip_from 2001:0db8::/32; real_ip_header X-Forwarded-For; real_ip_recursive on; location / { proxy_pass http://backend; proxy_set_header X-Real-IP $remote_addr; } }

Availability

Compiled into every n.wtf nginx binary. Install nginx-extras and the directives above work out of the box, no load_module line needed.