When requests pass through proxies or load balancers, the gateway receives the proxy's IP address instead of the actual client IP. The http-real-ip plug-in extracts the real client IP from a request header and replaces the client address, enabling accurate access control, rate limiting, and logging. It is the WebAssembly (Wasm) implementation of the NGINX realip module.
Plug-in type
Throttling
Quick start
The following example trusts a load balancer at 192.168.1.0/24 and reads the real client IP from the X-Forwarded-For header:
{
"real_ip_from": "192.168.1.0/24",
"real_ip_header": "x-forwarded-for"
}After you apply this configuration, a request from a client at 203.0.113.50 that passes through the load balancer arrives with the header X-Forwarded-For: 203.0.113.50. The plug-in replaces the client address with 203.0.113.50.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
real_ip_from | string | Yes | -- | IP address or CIDR block of a trusted proxy or load balancer. The plug-in only modifies the client address when the immediate sender matches this value. |
real_ip_header | string | No | x-forwarded-for | Request header that contains the real client IP. The plug-in reads this header and uses its value to replace the client address. |
How it works
A client sends a request through one or more proxies to the cloud-native gateway.
Each proxy appends the previous hop's IP address to the
X-Forwarded-Forheader (or another configured header).The plug-in checks whether the immediate sender's IP matches the
real_ip_fromaddress.If the sender is trusted, the plug-in reads the real client IP from the
real_ip_headerheader and replaces the client address.If the sender is not trusted, the client address remains unchanged.
Configuration examples
Single proxy
A single load balancer at 10.0.0.1 forwards requests to the gateway:
{
"real_ip_from": "10.0.0.1",
"real_ip_header": "x-forwarded-for"
}A request with header X-Forwarded-For: 203.0.113.50 from 10.0.0.1 results in the client address 203.0.113.50.
CIDR block for a proxy subnet
Multiple proxies in the 172.16.0.0/16 subnet forward requests:
{
"real_ip_from": "172.16.0.0/16",
"real_ip_header": "x-forwarded-for"
}Any request from an IP within 172.16.0.0/16 is trusted, and the plug-in extracts the client IP from the X-Forwarded-For header.
Custom header
Some CDN providers use a proprietary header such as X-Real-IP or True-Client-IP instead of X-Forwarded-For:
{
"real_ip_from": "198.51.100.0/24",
"real_ip_header": "x-real-ip"
}The plug-in reads the client IP from the X-Real-IP header instead of the default X-Forwarded-For.
Behavior and edge cases
| Scenario | Behavior |
|---|---|
Sender IP does not match real_ip_from | The plug-in does not modify the client address. |
The header specified in real_ip_header is missing | The client address remains unchanged. |
| Multiple proxies between client and gateway | Set real_ip_from to cover all intermediate proxy addresses. Each proxy typically appends its address to the X-Forwarded-For header. |
If you do not include all intermediate proxy addresses in real_ip_from, the plug-in may treat a legitimate proxy as untrusted and skip IP extraction. Make sure real_ip_from covers every proxy between the client and the gateway.