Skip to content

Commit c0e07ad

Browse files
kayx23kayx23
authored
docs: improve ip-restriction plugin docs (#11925)
1 parent 4715a7a commit c0e07ad

File tree

2 files changed

+142
-167
lines changed

2 files changed

+142
-167
lines changed

‎docs/en/latest/plugins/ip-restriction.md

+72-82
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ keywords:
66
- Plugin
77
- IP restriction
88
- ip-restriction
9-
description: This document contains information about the Apache APISIX ip-restriction Plugin.
9+
description: The ip-restriction Plugin supports restricting access to upstream resources by IP addresses, through either configuring a whitelist or blacklist of IP addresses.
1010
---
1111

1212
<!--
@@ -28,11 +28,13 @@ description: This document contains information about the Apache APISIX ip-restr
2828
#
2929
-->
3030

31-
## Description
31+
<head>
32+
<link rel="canonical" href="https://docs.api7.ai/hub/ip-restriction" />
33+
</head>
3234

33-
The `ip-restriction` Plugin allows you to restrict access to a Service or a Route by either whitelisting or blacklisting IP addresses.
35+
## Description
3436

35-
Single IPs, multiple IPs or even IP ranges in CIDR notation like `10.10.10.0/24` can be used.
37+
The `ip-restriction` Plugin supports restricting access to upstream resources by IP addresses, through either configuring a whitelist or blacklist of IP addresses. Restricting IP to resources helps prevent unauthorized access and harden API security.
3638

3739
## Attributes
3840

@@ -45,15 +47,16 @@ Single IPs, multiple IPs or even IP ranges in CIDR notation like `10.10.10.0/24`
4547

4648
:::note
4749

48-
Either one of `whitelist` or `blacklist` attribute must be specified. They cannot be used together.
50+
At least one of the `whitelist` or `blacklist` should be configured, but they cannot be configured at the same time.
4951

5052
:::
5153

52-
## Enable Plugin
54+
## Examples
5355

54-
You can enable the Plugin on a Route or a Service as shown below:
56+
The examples below demonstrate how you can configure the `ip-restriction` Plugin for different scenarios.
5557

5658
:::note
59+
5760
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
5861

5962
```bash
@@ -62,103 +65,90 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
6265

6366
:::
6467

65-
```shell
66-
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
67-
{
68-
"uri": "/index.html",
69-
"upstream": {
70-
"type": "roundrobin",
71-
"nodes": {
72-
"127.0.0.1:1980": 1
73-
}
74-
},
75-
"plugins": {
76-
"ip-restriction": {
77-
"whitelist": [
78-
"127.0.0.1",
79-
"113.74.26.106/24"
80-
]
81-
}
82-
}
83-
}'
84-
```
68+
### Restrict Access by Whitelisting
8569

86-
To return a custom message when an IP address is not allowed access, configure it in the Plugin as shown below:
70+
The following example demonstrates how you can whitelist a list of IP addresses that should have access to the upstream resource and customize the error message for access denial.
8771

88-
```json
89-
"plugins": {
90-
"ip-restriction": {
72+
Create a Route with the `ip-restriction` Plugin to whitelist a range of IPs and customize the error message when the access is denied:
73+
74+
```shell
75+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
76+
-H "X-API-KEY: ${admin_key}" \
77+
-d '{
78+
"id": "ip-restriction-route",
79+
"uri": "/anything",
80+
"plugins": {
81+
"ip-restriction": {
9182
"whitelist": [
92-
"127.0.0.1",
93-
"113.74.26.106/24"
83+
"192.168.0.1/24"
9484
],
95-
"message": "Do you want to do something bad?"
85+
"message": "Access denied"
86+
}
87+
},
88+
"upstream": {
89+
"type": "roundrobin",
90+
"nodes": {
91+
"httpbin.org:80": 1
92+
}
9693
}
97-
}
94+
}'
9895
```
9996

100-
## Example usage
101-
102-
After you have configured the Plugin as shown above, when you make a request from the IP `127.0.0.1`:
103-
104-
```shell
105-
curl http://127.0.0.1:9080/index.html -i
106-
```
97+
Send a request to the Route:
10798

10899
```shell
109-
HTTP/1.1 200 OK
110-
...
100+
curl -i "http://127.0.0.1:9080/anything"
111101
```
112102

113-
But if you make requests from `127.0.0.2`:
103+
If your IP is allowed, you should receive an `HTTP/1.1 200 OK` response. If not, you should receive an `HTTP/1.1 403 Forbidden` response with the following error message:
114104

115-
```shell
116-
curl http://127.0.0.1:9080/index.html -i --interface 127.0.0.2
105+
```text
106+
{"message":"Access denied"}
117107
```
118108

119-
```
120-
HTTP/1.1 403 Forbidden
121-
...
122-
{"message":"Your IP address is not allowed"}
123-
```
109+
### Restrict Access Using Modified IP
110+
111+
The following example demonstrates how you can modify the IP used for IP restriction, using the `real-ip` Plugin. This is particularly useful if APISIX is behind a reverse proxy and the real client IP is not available to APISIX.
124112

125-
To change the whitelisted/blacklisted IPs, you can update the Plugin configuration. The changes are hot reloaded and there is no need to restart the service.
113+
Create a Route with the `ip-restriction` Plugin to whitelist a specific IP address and obtain client IP address from the URL parameter `realip`:
126114

127115
```shell
128-
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
129-
{
130-
"uri": "/index.html",
131-
"upstream": {
132-
"type": "roundrobin",
133-
"nodes": {
134-
"127.0.0.1:1980": 1
135-
}
136-
},
116+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
117+
-H "X-API-KEY: ${admin_key}" \
118+
-d '{
119+
"id": "ip-restriction-route",
120+
"uri": "/anything",
137121
"plugins": {
138-
"ip-restriction": {
139-
"whitelist": [
140-
"127.0.0.2",
141-
"113.74.26.106/24"
142-
]
143-
}
122+
"ip-restriction": {
123+
"whitelist": [
124+
"192.168.1.241"
125+
]
126+
},
127+
"real-ip": {
128+
"source": "arg_realip"
129+
}
130+
},
131+
"upstream": {
132+
"type": "roundrobin",
133+
"nodes": {
134+
"httpbin.org:80": 1
135+
}
144136
}
145-
}'
137+
}'
138+
```
139+
140+
Send a request to the Route:
141+
142+
```shell
143+
curl -i "http://127.0.0.1:9080/anything?realip=192.168.1.241"
146144
```
147145

148-
## Delete Plugin
146+
You should receive an `HTTP/1.1 200 OK` response.
149147

150-
To remove the `ip-restriction` 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.
148+
Send another request with a different IP address:
151149

152150
```shell
153-
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
154-
{
155-
"uri": "/index.html",
156-
"plugins": {},
157-
"upstream": {
158-
"type": "roundrobin",
159-
"nodes": {
160-
"127.0.0.1:1980": 1
161-
}
162-
}
163-
}'
151+
curl -i "http://127.0.0.1:9080/anything?realip=192.168.10.24"
164152
```
153+
154+
You should receive an `HTTP/1.1 403 Forbidden` response.

0 commit comments

Comments
 (0)