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

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.
trusted_addresses	array[string]	False	List of IPs or CIDR ranges.	Dynamically sets the set_real_ip_from field.
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.

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
        }
    }
}'