add server manage plugin doc

2026-03-19 08:19:14 +08:00 · 2020-01-03 11:35:12 +08:00
parent 13e48c6ca0
commit e91c9473be
4 changed files with 357 additions and 5 deletions
--- a/doc/server_plugin.md
+++ b/doc/server_plugin.md
@@ -0,0 +1,171 @@
+### Manage Plugin
+
+frp manage plugin is aim to extend frp's ability without modifing self code.
+
+It runs as a process and listen on a port to provide RPC interface. Before frps doing some operations, frps will send RPC requests to manage plugin and do operations by it's response.
+
+### RPC request
+
+Support HTTP first.
+
+When manage plugin accept the operation request, it can give three different responses.
+
+* Reject operation and return the reason.
+* Allow operation and keep original content.
+* Allow operation and return modified content.
+
+### Interface
+
+HTTP path can be configured for each manage plugin in frps. Assume here is `/handler`.
+
+Request
+
+```
+POST /handler
+{
+    "version": "0.1.0",
+    "op": "Login",
+    "content": {
+        ... // Operation info
+    }
+}
+
+Request Header
+X-Frp-Reqid: for tracing
+```
+
+Response
+
+Error if not return 200 http code.
+
+Reject opeartion
+
+```
+{
+    "reject": true,
+    "reject_reason": "invalid user"
+}
+```
+
+Allow operation and keep original content
+
+```
+{
+    "reject": false,
+    "unchange": true
+}
+```
+
+Allow opeartion and modify content
+
+```
+{
+    "unchange": "false",
+    "content": {
+        ... // Replaced content
+    }
+}
+```
+
+### Operation
+
+Now it supports `Login` and `NewProxy`.
+
+#### Login
+
+Client login operation
+
+```
+{
+    "content": {
+        "version": <string>,
+        "hostname": <string>,
+        "os": <string>,
+        "arch": <string>,
+        "user": <string>,
+        "timestamp": <int64>,
+        "privilege_key": <string>,
+        "run_id": <string>,
+        "pool_count": <int>,
+        "metas": map<string>string
+    }
+}
+```
+
+#### NewProxy
+
+Create new proxy
+
+```
+{
+    "content": {
+        "user": {
+            "user": <string>,
+            "metas": map<string>string
+        },
+        "proxy_name": <string>,
+        "proxy_type": <string>,
+        "use_encryption": <bool>,
+        "use_compression": <bool>,
+        "group": <string>,
+        "group_key": <string>,
+
+        // tcp and udp only
+        "remote_port": <int>,
+
+        // http and https only
+        "custom_domains": []<string>,
+        "subdomain": <string>,
+        "locations": <string>,
+        "http_user": <string>,
+        "http_pwd": <string>,
+        "host_header_rewrite": <string>,
+        "headers": map<string>string,
+
+        "metas": map<string>string
+    }
+}
+```
+
+### manage plugin configure
+
+```ini
+[common]
+bind_port = 7000
+
+[plugin.user-manager]
+addr = 127.0.0.1:9000
+path = /handler
+ops = Login
+
+[plugin.port-manager]
+addr = 127.0.0.1:9001
+path = /handler
+ops = NewProxy
+```
+
+addr: plugin listen on.
+path: http request url path.
+ops: opeartions plugin needs handle.
+
+### meta data
+
+Meta data will be sent to manage plugin in each RCP request.
+
+Meta data start with `meta_`. It can be configured in `common` and each proxy.
+
+```
+# frpc.ini
+[common]
+server_addr = 127.0.0.1
+server_port = 7000
+user = fake
+meta_token = fake
+meta_version = 1.0.0
+
+[ssh]
+type = tcp
+local_port = 22
+remote_port = 6000
+meta_id = 123
+```