Skip to main content
Version: 3.10

real-ip

Description#

The real-ip Plugin is used to dynamically change the client's IP address and port as seen by APISIX.

This is more flexible but functions similarly to Nginx's ngx_http_realip_module.

IMPORTANT

This Plugin requires APISIX to run on APISIX-Runtime.

Attributes#

NameTypeRequiredValid valuesDescription
sourcestringTrueAny 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.
trusted_addressesarray[string]FalseList of IPs or CIDR ranges.Dynamically sets the set_real_ip_from field.
recursivebooleanFalseTrue to enable, false to disable, default is falseIf 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.
note

If the address specified in source is missing or invalid, the Plugin would not change the client address.

Enable Plugin#

The example below enables the real-ip Plugin on the specified Route:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
curl -i http://127.0.0.1:9180/apisix/admin/routes/1  -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"plugins": {
"real-ip": {
"source": "arg_realip",
"trusted_addresses": ["127.0.0.0/24"]
},
"response-rewrite": {
"headers": {
"remote_addr": "$remote_addr",
"remote_port": "$remote_port"
}
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

Example usage#

After you have enabled the Plugin as mentioned above, you can test it as shown below:

curl 'http://127.0.0.1:9080/index.html?realip=1.2.3.4:9080' -I
...
remote-addr: 1.2.3.4
remote-port: 9080

Delete Plugin#

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.

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'