---
title: "X-Real-IP: what the header means and when to trust it"
url: https://proxy.wiki/glossary/x-real-ip/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-10-21
updated: 2026-10-21
site: proxy.wiki
topics: ["Proxy fundamentals"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

# X-Real-IP: what the header means and when to trust it

> 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.

## Key takeaways

- X-Real-IP is a convention, not an identity proof.
- Nginx trusts it only after set_real_ip_from matches the peer.
- Strip and rewrite client copies at the trusted proxy.

**`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](/glossary/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](/glossary/cf-connecting-ip/) for the source-range boundary. The [default headers study](/research/default-request-headers/) shows that ordinary HTTP clients do not add this header on their own, while the [proxy-server guide](/guides/what-is-a-proxy-server/) 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.

## Frequently asked questions

### Is X-Real-IP an official HTTP standard?

No. It is a common convention. Nginx documents it as one input to its real IP module, but the name alone does not identify its sender.

### Should I use X-Real-IP for authentication?

No. Use it as a logging or rate-limit signal after a trusted proxy check. Use real authentication for access control.

### Why does my application see the proxy address?

The proxy may not rewrite the header, the application may be reading the socket peer, or Nginx's real IP module may not trust the proxy.

## Sources

1. [Nginx: ngx_http_realip_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html)
2. [RFC 7239: Forwarded HTTP Extension](https://www.rfc-editor.org/rfc/rfc7239.html)
3. [Cloudflare: HTTP headers](https://developers.cloudflare.com/fundamentals/reference/http-headers/)
