From f2e98ef8a40dd0795caad29e201e8dc007ab0eb7 Mon Sep 17 00:00:00 2001 From: fatedier Date: Wed, 11 Mar 2020 14:13:16 +0800 Subject: [PATCH] update doc --- README.md | 27 +++++++++--- README_zh.md | 104 +++++++++++++++++++++++++++++++++++++++++++-- conf/frpc_full.ini | 7 +++ conf/frps_full.ini | 38 +++++++++++++++++ 4 files changed, 168 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1a2e81b..f39b951 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,11 @@ frp also has a P2P connect mode. * [Using Environment Variables](#using-environment-variables) * [Dashboard](#dashboard) * [Admin UI](#admin-ui) + * [Monitor](#monitor) + * [Prometheus](#prometheus) * [Authenticating the Client](#authenticating-the-client) + * [Token Authentication](#token-authentication) + * [OIDC Authentication](#oidc-authentication) * [Encryption and Compression](#encryption-and-compression) * [TLS](#tls) * [Hot-Reloading frpc configuration](#hot-reloading-frpc-configuration) @@ -49,9 +53,10 @@ frp also has a P2P connect mode. * [Get Real IP](#get-real-ip) * [HTTP X-Forwarded-For](#http-x-forwarded-for) * [Proxy Protocol](#proxy-protocol) - * [Require HTTP Basic auth (password) for web services](#require-http-basic-auth-password-for-web-services) - * [Custom subdomain names](#custom-subdomain-names) - * [URL routing](#url-routing) + * [Require HTTP Basic Auth (Password) for Web Services](#require-http-basic-auth-password-for-web-services) + * [Custom Subdomain Names](#custom-subdomain-names) + * [URL Routing](#url-routing) + * [TCP Port Multiplexing](#tcp-port-multiplexing) * [Connecting to frps via HTTP PROXY](#connecting-to-frps-via-http-proxy) * [Range ports mapping](#range-ports-mapping) * [Client Plugins](#client-plugins) @@ -435,6 +440,18 @@ admin_pwd = admin Then visit `http://127.0.0.1:7400` to see admin UI, with username and password both being `admin` by default. +### Monitor + +When dashboard is enabled, frps will save monitor data in cache. It will be cleared after process restart. + +Prometheus is also supported. + +#### Prometheus + +Enable dashboard first, then configure `enable_prometheus = true` in `frps.ini`. + +`http://{dashboard_addr}/metrics` will provide prometheus monitor data. + ### Authenticating the Client There are 2 authentication methods to authenticate frpc with frps. @@ -818,11 +835,11 @@ locations = /news,/about HTTP requests with URL prefix `/news` or `/about` will be forwarded to **web02** and other requests to **web01**. -### TCP Multiplexing +### TCP Port Multiplexing frp supports receiving TCP sockets directed to different proxies on a single port on frps, similar to `vhost_http_port` and `vhost_https_port`. -The only supported TCP multiplexing method available at the moment is `httpconnect` - HTTP CONNECT tunnel. +The only supported TCP port multiplexing method available at the moment is `httpconnect` - HTTP CONNECT tunnel. When setting `tcpmux_httpconnect_port` to anything other than 0 in frps under `[common]`, frps will listen on this port for HTTP CONNECT requests. diff --git a/README_zh.md b/README_zh.md index f01efdf..0d16701 100644 --- a/README_zh.md +++ b/README_zh.md @@ -26,7 +26,11 @@ frp 是一个可用于内网穿透的高性能的反向代理应用，支持 tcp * [配置文件模版渲染](#配置文件模版渲染) * [Dashboard](#dashboard) * [Admin UI](#admin-ui) - * [身份验证](#身份验证) + * [监控](#监控) + * [Prometheus](#prometheus) + * [客户端身份验证](#客户端身份验证) + * [Token](#token) + * [OIDC](#oidc) * [加密与压缩](#加密与压缩) * [TLS](#tls) * [客户端热加载配置文件](#客户端热加载配置文件) @@ -48,6 +52,7 @@ frp 是一个可用于内网穿透的高性能的反向代理应用，支持 tcp * [通过密码保护你的 web 服务](#通过密码保护你的-web-服务) * [自定义二级域名](#自定义二级域名) * [URL 路由](#url-路由) + * [TCP 端口复用类型](#tcp-端口复用类型) * [通过代理连接 frps](#通过代理连接-frps) * [范围端口映射](#范围端口映射) * [客户端插件](#客户端插件) @@ -459,9 +464,56 @@ admin_pwd = admin 如果想要在外网环境访问 Admin UI，将 7400 端口映射出去即可，但需要重视安全风险。 -### 身份验证 +### 监控 -服务端和客户端的 common 配置中的 `token` 参数一致则身份验证通过。 +frps 当启用 Dashboard 后，会默认开启内部的监控，数据存放在内存中，每次重启进程后会清空，监控数据可以通过 dashboard 的地址发送 HTTP 请求获取。 + +目前还支持 Prometheus 作为可选的监控系统。 + +#### Prometheus + +在 `frps.ini` 中启用 Dashboard，并且设置 `enable_prometheus = true`，则通过 `http://{dashboard_addr}/metrics` 可以获取到 Prometheus 的监控数据。 + +### 客户端身份验证 + +目前 frpc 和 frps 之间支持两种身份验证方式，`token` 和 `oidc`。 + +通过 `frpc.ini` 和 `frps.ini` 中 `[common]` section 的 `authentication_method` 参数配置需要使用的验证方法。 + +`authenticate_heartbeats = true` 将会在每一个心跳包中附加上鉴权信息。 + +`authenticate_new_work_conns = true` 将会在每次建立新的工作连接时附加上鉴权信息。 + +#### Token + +当 `authentication_method = token`，将会启用基于 token 的验证方式。 + +需要在 `frpc.ini` 和 `frps.ini` 的 `[common]` section 中设置相同的 `token`。 + +#### OIDC + +当 `authentication_method = oidc`，将会启用基于 OIDC 的身份验证。 + +验证流程参考 [Client Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.4) + +启用这一验证方式，配置 `frpc.ini` 和 `frps.ini` 如下： + +```ini +# frps.ini +[common] +authentication_method = oidc +oidc_issuer = https://example-oidc-issuer.com/ +oidc_audience = https://oidc-audience.com/.default +``` + +```ini +[common] +authentication_method = oidc +oidc_client_id = 98692467-37de-409a-9fac-bb2585826f18 # Replace with OIDC client ID +oidc_client_secret = oidc_secret +oidc_audience = https://oidc-audience.com/.default +oidc_token_endpoint_url = https://example-oidc-endpoint.com/oauth2/v2.0/token +``` ### 加密与压缩 @@ -487,6 +539,8 @@ use_compression = true 为了端口复用，frp 建立 TLS 连接的第一个字节为 0x17。 +通过将 frps.ini 的 `[common]` 中 `tls_only` 设置为 true，可以强制 frps 只接受 TLS 连接。 + **注意: 启用此功能后除 xtcp 外，不需要再设置 use_encryption。** ### 客户端热加载配置文件 @@ -824,6 +878,50 @@ locations = /news,/about 按照上述的示例配置后，`web.yourdomain.com` 这个域名下所有以 `/news` 以及 `/about` 作为前缀的 URL 请求都会被转发到 web02，其余的请求会被转发到 web01。 +### TCP 端口复用类型 + +frp 支持将单个端口收到的连接路由到不同的代理，类似 `vhost_http_port` 和 `vhost_https_port`。 + +目前支持的复用器只有 `httpconnect`。 + +当在 `frps.ini` 的 `[common]` 中设置 `tcpmux_httpconnect_port`，frps 将会监听在这个端口，接收 HTTP CONNECT 请求。 + +frps 会根据 HTTP CONNECT 请求中的 host 路由到不同的后端代理。 + +示例配置如下： + +```ini +# frps.ini +[common] +bind_port = 7000 +tcpmux_httpconnect_port = 1337 +``` + +```ini +# frpc.ini +[common] +server_addr = x.x.x.x +server_port = 7000 + +[proxy1] +type = tcpmux +multiplexer = httpconnect +custom_domains = test1 + +[proxy2] +type = tcpmux +multiplexer = httpconnect +custom_domains = test2 +``` + +通过上面的配置，frps 如果接收到 HTTP CONNECT 请求内容: + +``` +CONNECT test1 HTTP/1.1\r\n\r\n +``` + +该连接将会被路由到 proxy1 。 + ### 通过代理连接 frps 在只能通过代理访问外网的环境内，frpc 支持通过 HTTP PROXY 和 frps 进行通信。 diff --git a/conf/frpc_full.ini b/conf/frpc_full.ini index c6d3d40..35fbb17 100644 --- a/conf/frpc_full.ini +++ b/conf/frpc_full.ini @@ -264,3 +264,10 @@ bind_addr = 127.0.0.1 bind_port = 9001 use_encryption = false use_compression = false + +[tcpmuxhttpconnect] +type = tcpmux +multiplexer = httpconnect +local_ip = 127.0.0.1 +local_port = 10701 +custom_domains = tunnel1 diff --git a/conf/frps_full.ini b/conf/frps_full.ini index 6713561..03896a2 100644 --- a/conf/frps_full.ini +++ b/conf/frps_full.ini @@ -23,6 +23,12 @@ vhost_https_port = 443 # response header timeout(seconds) for vhost http server, default is 60s # vhost_http_timeout = 60 +# TcpMuxHttpConnectPort specifies the port that the server listens for TCP +# HTTP CONNECT requests. If the value is 0, the server will not multiplex TCP +# requests on one single port. If it's not - it will listen on this value for +# HTTP CONNECT requests. By default, this value is 0. +# tcpmux_httpconnect_port = 1337 + # set dashboard_addr and dashboard_port to view dashboard of frps # dashboard_addr's default value is same with bind_addr # dashboard is available only if dashboard_port is set @@ -49,9 +55,38 @@ log_max_days = 3 # disable log colors when log_file is console, default is false disable_log_color = false +# DetailedErrorsToClient defines whether to send the specific error (with debug info) to frpc. By default, this value is true. +detailed_errors_to_client = true + +# AuthenticationMethod specifies what authentication method to use authenticate frpc with frps. +# If "token" is specified - token will be read into login message. +# If "oidc" is specified - OIDC (Open ID Connect) token will be issued using OIDC settings. By default, this value is "token". +authentication_method = token + +# AuthenticateHeartBeats specifies whether to include authentication token in heartbeats sent to frps. By default, this value is false. +authenticate_heartbeats = false + +# AuthenticateNewWorkConns specifies whether to include authentication token in new work connections sent to frps. By default, this value is false. +authenticate_new_work_conns = false + # auth token token = 12345678 +# OidcClientId specifies the client ID to use to get a token in OIDC authentication if AuthenticationMethod == "oidc". +# By default, this value is "". +oidc_client_id = + +# OidcClientSecret specifies the client secret to use to get a token in OIDC authentication if AuthenticationMethod == "oidc". +# By default, this value is "". +oidc_client_secret = + +# OidcAudience specifies the audience of the token in OIDC authentication if AuthenticationMethod == "oidc". By default, this value is "". +oidc_audience = + +# OidcTokenEndpointUrl specifies the URL which implements OIDC Token Endpoint. +# It will be used to get an OIDC token if AuthenticationMethod == "oidc". By default, this value is "". +oidc_token_endpoint_url = + # heartbeat configure, it's not recommended to modify the default value # the default value of heartbeat_timeout is 90 # heartbeat_timeout = 90 @@ -65,6 +100,9 @@ max_pool_count = 5 # max ports can be used for each client, default value is 0 means no limit max_ports_per_client = 0 +# TlsOnly specifies whether to only accept TLS-encrypted connections. By default, the value is false. +tls_only = false + # if subdomain_host is not empty, you can set subdomain when type is http or https in frpc's configure file # when subdomain is test, the host used by routing is test.frps.com subdomain_host = frps.com