frp/doc/server_plugin.md

Server Plugin

frp server plugin is aimed to extend frp's ability without modifying the Golang code.

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

RPC requests are based on JSON over HTTP.

When a server plugin accepts an operation request, it can respond with three different responses:

• 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. We'll assume for this example that it's /handler.

A request to the RPC server will look like:

POST /handler?version=0.1.0&op=Login
{
    "version": "0.1.0",
    "op": "Login",
    "content": {
        ... // Operation info
    }
}

Request Header:
X-Frp-Reqid: for tracing

The response can look like any of the following:

• Non-200 HTTP response status code (this will automatically tell frps that the request should fail)

• Reject operation:

{
    "reject": true,
    "reject_reason": "invalid user"
}

• Allow operation and keep original content:

{
    "reject": false,
    "unchange": true
}

• Allow operation and modify content

{
    "unchange": "false",
    "content": {
        ... // Replaced content
    }
}

Operation

Currently Login, NewProxy, Ping, NewWorkConn and NewUserConn operations are supported.

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
            "run_id": <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,

        // stcp only
        "sk": <string>,

        // tcpmux only
        "multiplexer": <string>

        "metas": map<string>string
    }
}

Ping

Heartbeat from frpc

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "timestamp": <int64>,
        "privilege_key": <string>
    }
}

NewWorkConn

New work connection received from frpc (RPC sent after run_id is matched with an existing frp connection)

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "run_id": <string>
        "timestamp": <int64>,
        "privilege_key": <string>
    }
}

NewUserConn

New user connection received from proxy (support tcp, stcp, https and tcpmux) .

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "proxy_name": <string>,
        "proxy_type": <string>,
        "remote_addr": <string>
    }
}

Server Plugin Configuration

# frps.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: 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", ...).

Metadata

Metadata will be sent to the server plugin in each RPC request.

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
[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