diff --git a/doc/server_plugin.md b/doc/server_plugin.md index 7d9be12..fa511b3 100644 --- a/doc/server_plugin.md +++ b/doc/server_plugin.md @@ -1,24 +1,25 @@ -### Manage Plugin +### Server Plugin -frp manage plugin is aim to extend frp's ability without modifing self code. +frp server plugin is aimed to extend frp's ability without modifying the Golang 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. +An external server should run in a different process receiving RPC calls from frps. +Before frps is doing some operations, it will send RPC requests to notify the external RPC server and act according to its response. ### RPC request -Support HTTP first. +RPC requests are based on JSON over HTTP. -When manage plugin accept the operation request, it can give three different responses. +When a server plugin accepts an operation request, it can respond with three different responses: -* Reject operation and return the reason. +* Reject operation and return a 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`. +HTTP path can be configured for each manage plugin in frps. We'll assume for this example that it's `/handler`. -Request +A request to the RPC server will look like: ``` POST /handler @@ -30,15 +31,15 @@ POST /handler } } -Request Header +Request Header: X-Frp-Reqid: for tracing ``` -Response +The response can look like any of the following: -Error if not return 200 http code. +* Non-200 HTTP response status code (this will automatically tell frps that the request should fail) -Reject opeartion +* Reject operation: ``` { @@ -47,7 +48,7 @@ Reject opeartion } ``` -Allow operation and keep original content +* Allow operation and keep original content: ``` { @@ -56,7 +57,7 @@ Allow operation and keep original content } ``` -Allow opeartion and modify content +* Allow operation and modify content ``` { @@ -69,7 +70,7 @@ Allow opeartion and modify content ### Operation -Now it supports `Login` and `NewProxy`. +Currently `Login` and `NewProxy` operations are supported. #### Login @@ -102,6 +103,7 @@ Create new proxy "user": { "user": , "metas": mapstring + "run_id": }, "proxy_name": , "proxy_type": , @@ -122,14 +124,21 @@ Create new proxy "host_header_rewrite": , "headers": mapstring, + // stcp only + "sk": , + + // tcpmux only + "multiplexer": + "metas": mapstring } } ``` -### manage plugin configure +### Server Plugin Configuration ```ini +# frps.ini [common] bind_port = 7000 @@ -144,15 +153,19 @@ path = /handler ops = NewProxy ``` -addr: plugin listen on. -path: http request url path. -ops: opeartions plugin needs handle. +addr: the address where the external RPC service listens on. +path: http request url path for the POST request. +ops: operations plugin needs to handle (e.g. "Login", "NewProxy"). -### meta data +### Metadata -Meta data will be sent to manage plugin in each RCP request. +Metadata will be sent to the server plugin in each RPC request. -Meta data start with `meta_`. It can be configured in `common` and each proxy. +There are 2 types of metadata entries - 1 under `[common]` and the other under each proxy configuration. +Metadata entries under `[common]` will be sent in `Login` under the key `metas`, and in any other RPC request under `user.metas`. +Metadata entries under each proxy configuration will be sent in `NewProxy` op only, under `metas`. + +Metadata entries start with `meta_`. This is an example of metadata entries in `[common]` and under the proxy named `[ssh]`: ``` # frpc.ini diff --git a/models/plugin/server/types.go b/models/plugin/server/types.go index 4e392b7..5d9c695 100644 --- a/models/plugin/server/types.go +++ b/models/plugin/server/types.go @@ -38,6 +38,7 @@ type LoginContent struct { type UserInfo struct { User string `json:"user"` Metas map[string]string `json:"metas"` + RunId string `json:"run_id"` } type NewProxyContent struct { diff --git a/server/control.go b/server/control.go index f4ed481..e832ea9 100644 --- a/server/control.go +++ b/server/control.go @@ -422,6 +422,7 @@ func (ctl *Control) manager() { User: plugin.UserInfo{ User: ctl.loginMsg.User, Metas: ctl.loginMsg.Metas, + RunId: ctl.loginMsg.RunId, }, NewProxy: *m, }