real-ip.md

title
real-ip

Summary

• Name
• Attributes
• How To Enable
• Test Plugin
• Disable Plugin

Name

The real-ip plugin dynamically changes the client's IP and port seen by APISIX.

It works like Nginx's ngx_http_realip_module, but is more flexible.

This plugin requires APISIX to run on APISIX-OpenResty.

Attributes

Name	Type	Requirement	Default	Valid	Description
source	string	required		Any Nginx variable like arg_realip or http_x_forwarded_for	dynamically set the client's IP and port in APISIX's view, according to the value of variable. If the value doesn't contain a port, the client's port won't be changed.
trusted_addresses	array[string]	optional		List of IPs or CIDR ranges	dynamically set the set_real_ip_from directive

If the remote address comes from source is missing or invalid, this plugin will just let it go and don't change the client address.

How To Enable

Here's an example, enable this plugin on the specified route:

curl -i http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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
        }
    }
}'

Test Plugin

Use curl to access:

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

Disable Plugin

When you want to disable this plugin, it is very simple, you can delete the corresponding JSON configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

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

This plugin has been disabled now. It works for other plugins.