Yilialinn commented on code in PR #11963: URL: https://github.com/apache/apisix/pull/11963#discussion_r1950163489
########## docs/en/latest/plugins/real-ip.md: ########## @@ -27,97 +27,176 @@ description: This document contains information about the Apache APISIX real-ip # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/real-ip"; /> +</head> + ## Description -The `real-ip` Plugin is used to dynamically change the client's IP address and port as seen by APISIX. +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. -This is more flexible but functions similarly to Nginx's [ngx_http_realip_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html). +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. -:::info IMPORTANT +## Attributes -This Plugin requires APISIX to run on [APISIX-Runtime](../FAQ.md#how-do-i-build-the-apisix-runtime-environment). +| Name | Type | Required | Valid values | Description | +|-----------|---------|----------|----------------|---------------| +| source | string | Yes | Any Nginx variable like `arg_realip` or `http_x_forwarded_for`. |ically Dynam sets the client's IP address and an optional port, or the client's hostname, from APISIX's view.| +| trusted_addresses | array[string] | No | List of IPs or CIDR ranges. | Dynamically sets the `set_real_ip_from` field. | +| recursive | boolean | No | True to enable, false to disable (default is false) | If the 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 the 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`. | -::: +## Examples -## Attributes +The examples below demonstrate how you can configure `real-ip` in different scenarios. -| 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`. | +### Obtain Real Client Address From URI Parameter -:::note +The following example demonstrates how to update the client IP address with a URI parameter. -If the address specified in `source` is missing or invalid, the Plugin would not change the client address. +Create a route as follows: -::: +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "real-ip-route", + "uri": "/get", + "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": { + "httpbin.org:80": 1 + } + } + }' +``` -## Enable Plugin +❶ Configure `source` to obtain value from the URL parameter `realip` using the [built-in variables](/apisix/reference/built-in-variables). -The example below enables the `real-ip` Plugin on the specified Route: +❷ Use the `response-rewrite` plugin to set response headers to verify if the client IP and port were actually updated. -:::note -You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: +Send a request to the route with real IP and port in the URL parameter: -```bash -admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g') +```shell +curl -i "http://127.0.0.1:9080/get?realip=1.2.3.4:9080"; ``` -::: +You should see the response includes the following header: + +```text +remote-addr: 1.2.3.4 +remote-port: 9080 +``` + +### Obtain Real Client Address From Header + +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. + +Create a route as follows: Review Comment: ditto -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
