You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This Plugin requires APISIX to run on [APISIX-Runtime](../FAQ.md#how-do-i-build-the-apisix-runtime-environment).
36
+
The `real-ip`Plugin allows APISIX to set the client's real IP by the IP address passed in the HTTP header or HTTP query string. This is particularly useful when APISIX is behind a reverse proxy since the proxy could act as the request-originating client otherwise.
39
37
40
-
:::
38
+
The Plugin is functionally similar to NGINX's [ngx_http_realip_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html) but offers more flexibility.
41
39
42
40
## Attributes
43
41
44
-
| Name | Type | Required| Valid values | Description|
| source | string | True| Any Nginx variable like `arg_realip` or `http_x_forwarded_for`. | Dynamically sets the client's IP address and an optional port, or the client's host name, from APISIX's view. |
47
-
| trusted_addresses | array[string]| False | List of IPs or CIDR ranges. | Dynamically sets the `set_real_ip_from` field. |
48
-
| recursive | boolean | False | True to enable, false to disable, default is false | If recursive search is disabled, the original client address that matches one of the trusted addresses is replaced by the last address sent in the configured `source`.If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the configured `source`. |
42
+
| Name | Type | Required | Default| Valid values | Description |
| source | string | True|||A built-in [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/) or [NGINX variable](https://nginx.org/en/docs/varindex.html), such as `http_x_forwarded_for` or `arg_realip`. The variable value should be a valid IP address that represents the client's real IP address, with an optional port.|
45
+
| trusted_addresses | array[string]| False || array of IPv4 or IPv6 addresses (CIDR notation acceptable) | Trusted addresses that are known to send correct replacement addresses. This configuration sets the [`set_real_ip_from`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive.|
46
+
| recursive | boolean | False | False || If false, replace the original client address that matches one of the trusted addresses by the last address sent in the configured `source`.<br>If true, replace the original client address that matches one of the trusted addresses by the last non-trusted address sent in the configured `source`. |
49
47
50
48
:::note
51
-
52
49
If the address specified in `source` is missing or invalid, the Plugin would not change the client address.
53
-
54
50
:::
55
51
56
-
## Enable Plugin
52
+
## Examples
57
53
58
-
The example below enables the `real-ip`Plugin on the specified Route:
54
+
The examples below demonstrate how you can configure `real-ip`in different scenarios.
59
55
60
56
:::note
57
+
61
58
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
62
59
63
60
```bash
@@ -66,58 +63,140 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
66
63
67
64
:::
68
65
66
+
### Obtain Real Client Address From URI Parameter
67
+
68
+
The following example demonstrates how to update the client IP address with a URI parameter.
69
+
70
+
Create a Route as follows. You should configure `source` to obtain value from the URL parameter `realip` using [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/) or [NGINX variable](https://nginx.org/en/docs/varindex.html). Use the `response-rewrite` Plugin to set response headers to verify if the client IP and port were actually updated.
71
+
69
72
```shell
70
-
curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
71
-
{
72
-
"uri": "/index.html",
73
+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
74
+
-H "X-API-KEY: ${admin_key}" \
75
+
-d '{
76
+
"id": "real-ip-route",
77
+
"uri": "/get",
73
78
"plugins": {
74
-
"real-ip": {
75
-
"source": "arg_realip",
76
-
"trusted_addresses": ["127.0.0.0/24"]
77
-
},
78
-
"response-rewrite": {
79
-
"headers": {
80
-
"remote_addr": "$remote_addr",
81
-
"remote_port": "$remote_port"
82
-
}
79
+
"real-ip": {
80
+
"source": "arg_realip",
81
+
"trusted_addresses": ["127.0.0.0/24"]
82
+
},
83
+
"response-rewrite": {
84
+
"headers": {
85
+
"remote_addr": "$remote_addr",
86
+
"remote_port": "$remote_port"
83
87
}
88
+
}
84
89
},
85
90
"upstream": {
86
-
"type": "roundrobin",
87
-
"nodes": {
88
-
"127.0.0.1:1980": 1
89
-
}
91
+
"type": "roundrobin",
92
+
"nodes": {
93
+
"httpbin.org:80": 1
94
+
}
90
95
}
91
-
}'
96
+
}'
92
97
```
93
98
94
-
## Example usage
95
-
96
-
After you have enabled the Plugin as mentioned above, you can test it as shown below:
99
+
Send a request to the Route with real IP and port in the URL parameter:
You should see the response includes the following header:
106
+
107
+
```text
104
108
remote-addr: 1.2.3.4
105
109
remote-port: 9080
106
110
```
107
111
108
-
## Delete Plugin
112
+
### Obtain Real Client Address From Header
113
+
114
+
The following example shows how to set the real client IP when APISIX is behind a reverse proxy, such as a load balancer when the proxy exposes the real client IP in the [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header.
109
115
110
-
To remove the `real-ip` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
116
+
Create a Route as follows. You should configure `source` to obtain value from the request header `X-Forwarded-For` using [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/) or [NGINX variable](https://nginx.org/en/docs/varindex.html). Use the `response-rewrite` Plugin to set a response header to verify if the client IP was actually updated.
111
117
112
118
```shell
113
-
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
114
-
{
115
-
"uri": "/index.html",
116
-
"upstream": {
117
-
"type": "roundrobin",
118
-
"nodes": {
119
-
"127.0.0.1:1980": 1
119
+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
120
+
-H "X-API-KEY: ${admin_key}" \
121
+
-d '{
122
+
"id": "real-ip-route",
123
+
"uri": "/get",
124
+
"plugins": {
125
+
"real-ip": {
126
+
"source": "http_x_forwarded_for",
127
+
"trusted_addresses": ["127.0.0.0/24"]
128
+
},
129
+
"response-rewrite": {
130
+
"headers": {
131
+
"remote_addr": "$remote_addr"
120
132
}
133
+
}
134
+
},
135
+
"upstream": {
136
+
"type": "roundrobin",
137
+
"nodes": {
138
+
"httpbin.org:80": 1
139
+
}
121
140
}
141
+
}'
142
+
```
143
+
144
+
Send a request to the Route:
145
+
146
+
```shell
147
+
curl -i "http://127.0.0.1:9080/get"
148
+
```
149
+
150
+
You should see a response including the following header:
151
+
152
+
```text
153
+
remote-addr: 10.26.3.19
154
+
```
155
+
156
+
The IP address should correspond to the IP address of the request-originating client.
157
+
158
+
### Obtain Real Client Address Behind Multiple Proxies
159
+
160
+
The following example shows how to get the real client IP when APISIX is behind multiple proxies, which causes [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) header to include a list of proxy IP addresses.
161
+
162
+
Create a Route as follows. You should configure `source` to obtain value from the request header `X-Forwarded-For` using [APISIX variable](https://apisix.apache.org/docs/apisix/apisix-variable/) or [NGINX variable](https://nginx.org/en/docs/varindex.html). Set `recursive` to `true` so that the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the configured `source`. Then, use the `response-rewrite` Plugin to set a response header to verify if the client IP was actually updated.
163
+
164
+
```shell
165
+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
0 commit comments