X-Real-IP: what the header means and when to trust it
Definition
X-Real-IP is a proxy convention for one client address. Learn when Nginx can trust it and how a direct client can forge it.
X-Real-IP is a common single-address request header used by reverse proxies to pass an observed client address to an upstream application. It is a convention, not a proof of identity. The value is useful after a trusted proxy has stripped and rewritten it; it is input from an untrusted client everywhere else.
How Nginx uses it
Nginx’s ngx_http_realip_module supports X-Real-IP, X-Forwarded-For and the PROXY protocol. The module changes the client address only when the peer matches set_real_ip_from. A minimal configuration looks like this:
# Use the address range of your own trusted load balancer.
set_real_ip_from 192.0.2.0/24;
real_ip_header X-Real-IP;
real_ip_recursive off;
The range above is from the documentation address space and is an example, not a production allowlist. Replace it with the addresses that actually connect to your Nginx server. If Nginx is behind multiple trusted proxies, decide whether the last trusted hop or the full chain is authoritative before enabling recursive processing.
Why a direct header is not a client address
Our local Python 3.15.0 echo server received a direct curl 8.7.1 request with a made-up value:
$ curl -sS http://127.0.0.1:57011/ -H 'X-Real-IP: 198.51.100.7'
REMOTE_ADDR=127.0.0.1
CF-Connecting-IP=<missing>
X-Real-IP=198.51.100.7
exit=0
The kernel supplied 127.0.0.1 as the TCP peer. The header was only text chosen by curl. A public application that uses it for an allowlist without a source check gives the caller control of the allowlist input.
| Where the request came from | What X-Real-IP means | Correct action |
|---|---|---|
| Trusted load balancer that overwrites the header | The address selected by that balancer | Accept it after checking the peer range |
| Direct client to the application | An unverified claim | Use the socket peer and ignore the header |
| Several proxies, each appending or rewriting | Implementation-specific | Document the chain and choose one authority |
| Cloudflare edge | Usually use CF-Connecting-IP instead |
Trust only after restricting origin access to Cloudflare |
Header versus X-Forwarded-For
X-Real-IP normally carries one value. X-Forwarded-For can carry a comma-separated path of addresses. Neither format creates trust by itself. A proxy should remove incoming copies from the client, set or append its own value, and send the result over a path where the upstream can identify the proxy. The standardized Forwarded header is another option, but it also needs a hop-by-hop trust policy.
Cloudflare uses its own CF-Connecting-IP header for the origin client value. See the CF-Connecting-IP reference for the source-range boundary. The default headers study shows that ordinary HTTP clients do not add this header on their own, while the proxy-server guide explains the two connections a reverse proxy manages.
Safe deployment checks
Capture the peer address and header in a staging access log. Send one request through the real proxy and one direct request with a forged header. The first should produce the expected client value; the second should either be blocked at the firewall or retain its direct peer. Then check IPv4 and IPv6 separately. A configuration that trusts a private range but leaves a public interface open is still forgeable from another route.
Keep the original header name visible in diagnostics until the chain is proven. Once the proxy is trusted, applications can use the server’s normalized client variable, such as Nginx’s $remote_addr, instead of parsing request headers in every framework.
Trust should be established at each hop, because a header that was safe at a load balancer can become forgeable after an internal redirect or direct service exposure. Document which interface accepts proxy traffic, which source ranges are allowed, and whether the application receives a normalized variable or the raw header. Make those assumptions part of deployment review so a new listener cannot silently bypass them.
For an audit trail, retain the raw header separately from the normalized address and label both with the receiving peer.