doc: plugin ip-restriction and use 4 spaces to replace tab.

gavin0755 · Sep 3, 2019 · bd87448 · bd87448
1 parent ec82a7b
commit bd87448
Show file tree

Hide file tree

Showing 10 changed files with 252 additions and 162 deletions.
diff --git a/doc/plugins-cn.md b/doc/plugins-cn.md
@@ -11,7 +11,7 @@
 * [limit-conn](plugins/limit-conn-cn.md)：限制并发请求（或并发连接）。
 * [prometheus](plugins/prometheus.md)：以 Prometheus 格式导出 APISIX 自身的状态信息，方便被外部 Prometheus 服务抓取。
 * [OpenTracing](plugins/zipkin.md)：支持 Zikpin 和 Apache SkyWalking。
-* [grpc-transcode](../doc/plugins/grpc-transcode-cn.md)：REST <--> gRPC 转码。
-* [serverless](../doc/plugins/serverless-cn.md)：允许在 APISIX 中的不同阶段动态运行 Lua 代码。
-* ip-restriction
+* [grpc-transcode](plugins/grpc-transcode-cn.md)：REST <--> gRPC 转码。
+* [serverless](plugins/serverless-cn.md)：允许在 APISIX 中的不同阶段动态运行 Lua 代码。
+* [ip-restriction](plugins/ip-restriction.md): IP 黑白名单。
 * openid-connect
diff --git a/doc/plugins.md b/doc/plugins.md
@@ -13,7 +13,7 @@ Now we support the following plugins:
 * [limit-conn](plugins/limit-conn.md): limite request concurrency (or concurrent connections).
 * [prometheus](plugins/prometheus.md): expose metrics related to APISIX and proxied upstream services in Prometheus exposition format, which can be scraped by a Prometheus Server.
 * [OpenTracing](plugins/zipkin.md): support Zikpin and Apache SkyWalking.
-* [grpc-transcode](../doc/plugins/grpc-transcode-cn.md): REST <--> gRPC transcoding。
-* [serverless](../doc/plugins/serverless-cn.md)：allow to dynamically run Lua code at *different* phase in APISIX.
-* ip-restriction
+* [grpc-transcode](plugins/grpc-transcode-cn.md): REST <--> gRPC transcoding。
+* [serverless](plugins/serverless-cn.md)：allow to dynamically run Lua code at *different* phase in APISIX.
+* [ip-restriction](plugins/ip-restriction.md): IP whitelist/blacklist.
 * openid-connect
diff --git a/doc/plugins/grpc-transcoding-cn.md b/doc/plugins/grpc-transcoding-cn.md
@@ -15,17 +15,17 @@ HTTP(s) -> APISIX -> gRPC server
 ```shell
 curl http://127.0.0.1:9080/apisix/admin/proto/1 -X PUT -d '
 {
- "content" : "syntax = \"proto3\";
-   package helloworld;
-   service Greeter {
-       rpc SayHello (HelloRequest) returns (HelloReply) {}
-   }
-   message HelloRequest {
-       string name = 1;
-   }
-   message HelloReply {
-       string message = 1;
-      }"
+    "content" : "syntax = \"proto3\";
+    package helloworld;
+    service Greeter {
+        rpc SayHello (HelloRequest) returns (HelloReply) {}
+    }
+    message HelloRequest {
+        string name = 1;
+    }
+    message HelloReply {
+        string message = 1;
+    }"
 }'
 ```
 

diff --git a/doc/plugins/grpc-transcoding.md b/doc/plugins/grpc-transcoding.md
@@ -15,17 +15,17 @@ Here's an example, adding a proto which `id` is `1`:
 ```shell
 curl http://127.0.0.1:9080/apisix/admin/proto/1 -X PUT -d '
 {
- "content" : "syntax = \"proto3\";
-   package helloworld;
-   service Greeter {
-       rpc SayHello (HelloRequest) returns (HelloReply) {}
-   }
-   message HelloRequest {
-       string name = 1;
-   }
-   message HelloReply {
-       string message = 1;
-      }"
+    "content" : "syntax = \"proto3\";
+    package helloworld;
+    service Greeter {
+        rpc SayHello (HelloRequest) returns (HelloReply) {}
+    }
+    message HelloRequest {
+        string name = 1;
+    }
+    message HelloReply {
+        string message = 1;
+    }"
 }'
 ```
 

diff --git a/doc/plugins/ip-restriction.md b/doc/plugins/ip-restriction.md
@@ -0,0 +1,93 @@
+[中文](ip-restriction-cn.md)
+
+# Summary
+- [**Name**](#name)
+- [**Attributes**](#attributes)
+- [**How To Enable**](#how-to-enable)
+- [**Test Plugin**](#test-plugin)
+- [**Disable Plugin**](#disable-plugin)
+
+
+## Name
+
+The `ip-restriction` can restrict access to a Service or a Route by either
+whitelisting or blacklisting IP addresses. Single IPs, multiple IPs or ranges
+in CIDR notation like 10.10.10.0/24 can be used(will support IPv6 soon).
+
+## Attributes
+
+|name     |option  |description|
+|---------|--------|-----------|
+|whitelist|option  |List of IPs or CIDR ranges to whitelist|
+|blacklist|option  |List of IPs or CIDR ranges to blacklist|
+
+One of `whitelist` or `blacklist` must be specified, and they can not work
+together.
+
+## How To Enable
+
+Two steps are required:
+
+1. creates a route or service object, and enable plugin `ip-restriction`.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -d '
+{
+    "uri": "/hello",
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    },
+    "plugins": {
+        "ip-restriction": {
+            "whitelist": [
+                "127.0.0.1",
+                "113.74.26.106/24"
+            ]
+        }
+    }
+}'
+```
+
+## Test Plugin
+
+Requests to `127.0.0.1`:
+
+```shell
+$ curl http://127.0.0.1:9080/index.html
+HTTP/1.1 200 OK
+...
+```
+
+Requests to `127.0.0.2`:
+
+```shell
+$ curl http://127.0.0.2:9080/index.html -i
+HTTP/1.1 403 Unauthorized
+...
+{"message":"Your IP address is not allowed"}
+```
+
+## Disable Plugin
+
+When you want to disable the `ip-restriction` 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:
+
+```shell
+$ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
+{
+    "uri": "/index.html",
+    "plugins": {},
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
+}'
+```
+
+The `ip-restriction` plugin has been disabled now. It works for other plugins.
diff --git a/doc/plugins/key-auth-cn.md b/doc/plugins/key-auth-cn.md
@@ -26,11 +26,11 @@
 curl http://127.0.0.1:9080/apisix/admin/consumers -X PUT -d '
 {
     "username": "jack",
-	"plugins": {
-		"key-auth": {
-			"key": "keykey"
-		}
-	}
+    "plugins": {
+        "key-auth": {
+            "key": "keykey"
+        }
+    }
 }'
 ```
 
@@ -39,18 +39,18 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -X PUT -d '
 ```shell
 curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -d '
 {
-	"methods": ["GET"],
-	"uri": "/index.html",
-	"id": 1,
-	"plugins": {
-		"key-auth": {}
-	},
-	"upstream": {
-		"type": "roundrobin",
-		"nodes": {
-			"39.97.63.215:80": 1
-		}
-	}
+    "methods": ["GET"],
+    "uri": "/index.html",
+    "id": 1,
+    "plugins": {
+        "key-auth": {}
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
 }'
 ```
 
@@ -85,17 +85,17 @@ HTTP/1.1 401 Unauthorized
 ```shell
 $ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
 {
-	"methods": ["GET"],
-	"uri": "/index.html",
-	"id": 1,
-	"plugins": {
-	},
-	"upstream": {
-		"type": "roundrobin",
-		"nodes": {
-			"39.97.63.215:80": 1
-		}
-	}
+    "methods": ["GET"],
+    "uri": "/index.html",
+    "id": 1,
+    "plugins": {
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
 }'
 ```
 

diff --git a/doc/plugins/key-auth.md b/doc/plugins/key-auth.md
@@ -1,4 +1,4 @@
-[中文](key-auth-cn.md) 
+[中文](key-auth-cn.md)
 
 # Summary
 - [**Name**](#name)
@@ -28,11 +28,11 @@ Two steps are required:
     curl http://127.0.0.1:9080/apisix/admin/consumers -X PUT -d '
 {
     "username": "jack",
-	"plugins": {
-		"key-auth": {
-			"key": "keykey"
-		}
-	}
+    "plugins": {
+        "key-auth": {
+            "key": "keykey"
+        }
+    }
 }'
 ```
 
@@ -41,18 +41,18 @@ Two steps are required:
 ```shell
 curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -d '
 {
-	"methods": ["GET"],
-	"uri": "/index.html",
-	"id": 1,
-	"plugins": {
-		"key-auth": {}
-	},
-	"upstream": {
-		"type": "roundrobin",
-		"nodes": {
-			"39.97.63.215:80": 1
-		}
-	}
+    "methods": ["GET"],
+    "uri": "/index.html",
+    "id": 1,
+    "plugins": {
+        "key-auth": {}
+    },
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
 }'
 ```
 
@@ -82,25 +82,22 @@ HTTP/1.1 401 Unauthorized
 
 ## Disable Plugin
 
-When you want to disable the limit req plugin, it is very simple,
+When you want to disable the `key-auth` 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:
 
 ```shell
 $ curl http://127.0.0.1:2379/v2/keys/apisix/routes/1 -X PUT -d value='
 {
-	"methods": ["GET"],
-	"uri": "/index.html",
-	"id": 1,
-	"plugins": {
-	},
-	"upstream": {
-		"type": "roundrobin",
-		"nodes": {
-			"39.97.63.215:80": 1
-		}
-	}
+    "uri": "/index.html",
+    "plugins": {},
+    "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "39.97.63.215:80": 1
+        }
+    }
 }'
 ```
 
-The limit req plugin has been disabled now. It works for other plugins.
+The `key-auth` plugin has been disabled now. It works for other plugins.