update doc for v0.13.0

7 years ago · 0208ecd1d9
parent 2b1ba3a946
commit 0208ecd1d9
2 changed files with 171 additions and 49 deletions
--- a/README.md
+++ b/README.md
@ -19,18 +19,21 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
    * [Visit your web service in LAN by custom domains](#visit-your-web-service-in-lan-by-custom-domains)
    * [Forward DNS query request](#forward-dns-query-request)
    * [Forward unix domain socket](#forward-unix-domain-socket)
+    * [Expose your service in security](#expose-your-service-in-security)
    * [Connect website through frpc's network](#connect-website-through-frpcs-network)
 * [Features](#features)
+    * [Configuration File](#configuration-file)
    * [Dashboard](#dashboard)
    * [Authentication](#authentication)
    * [Encryption and Compression](#encryption-and-compression)
-    * [Reload configures without frps stopped](#reload-configures-without-frps-stopped)
+    * [Hot-Reload frpc configuration](#hot-reload-frpc-configuration)
    * [Privilege Mode](#privilege-mode)
        * [Port White List](#port-white-list)
    * [TCP Stream Multiplexing](#tcp-stream-multiplexing)
    * [Support KCP Protocol](#support-kcp-protocol)
    * [Connection Pool](#connection-pool)
    * [Rewriting the Host Header](#rewriting-the-host-header)
+    * [Get Real IP](#get-real-ip)
    * [Password protecting your web service](#password-protecting-your-web-service)
    * [Custom subdomain names](#custom-subdomain-names)
    * [URL routing](#url-routing)
@ -187,19 +190,36 @@ However, we can expose a http or https service using frp.

 Using tcp port to connect unix domain socket like docker daemon.

-1. Modify frps.ini:
+Configure frps same as above.
+
+1. Start frpc with configurations:

  ```ini
-  # frps.ini
+  # frpc.ini
  [common]
-  bind_port = 7000
+  server_addr = x.x.x.x
+  server_port = 7000
+
+  [unix_domain_socket]
+  type = tcp
+  remote_port = 6000
+  plugin = unix_domain_socket
+  plugin_unix_path = /var/run/docker.sock
  ```

-2. Start frps:
+2. Get docker version by curl command:

-  `./frps -c ./frps.ini`
+  `curl http://x.x.x.x:6000/version`
+
+### Expose your service in security
+
+For some services, if expose them to the public network directly will be a security risk.
+
+**stcp(secret tcp)** help you create a proxy avoiding any one can access it.
+
+Configure frps same as above.

-3. Modify frpc.ini:
+1. Start frpc, forward ssh port and `remote_port` is useless:

  ```ini
  # frpc.ini
@ -207,26 +227,39 @@ Using tcp port to connect unix domain socket like docker daemon.
  server_addr = x.x.x.x
  server_port = 7000

-  [unix_domain_socket]
-  type = tcp
-  remote_port = 6000
-  plugin = unix_domain_socket
-  plugin_unix_path = /var/run/docker.sock
+  [secret_ssh]
+  type = stcp
+  sk = abcdefg
+  local_ip = 127.0.0.1
+  local_port = 22
  ```

-4. Start frpc:
+2. Start another frpc in which you want to connect this ssh server:

-  `./frpc -c ./frpc.ini`
+  ```ini
+  # frpc.ini
+  [common]
+  server_addr = x.x.x.x
+  server_port = 7000
+
+  [secret_ssh_vistor]
+  type = stcp
+  role = vistor
+  server_name = secret_ssh
+  sk = abcdefg
+  bind_addr = 127.0.0.1
+  bind_port = 6000
+  ```

-5. Get docker version by curl command:
+3. Connect to server in LAN by ssh assuming that username is test:

-  `curl http://x.x.x.x:6000/version`
+  `ssh -oPort=6000 test@127.0.0.1`

 ### Connect website through frpc's network

 Configure frps same as above.

-1. Modify frpc.ini:
+1. Start frpc with configurations:

  ```ini
  # frpc.ini
@ -240,13 +273,17 @@ Configure frps same as above.
  plugin = http_proxy # or socks5
  ```

-4. Start frpc:
+2. Set http proxy or socks5 proxy `x.x.x.x:6000` in your browser and visit website through frpc's network.

-  `./frpc -c ./frpc.ini`
+## Features

-5. Set http proxy or socks5 proxy `x.x.x.x:6000` in your browser and visit website through frpc's network.
+### Configuration File

-## Features
+You can find features which this document not metioned from full example configuration files.
+
+[frps full configuration file](./conf/frps_full.ini)
+
+[frpc full configuration file](./conf/frpc_full.ini)

 ### Dashboard

@ -288,9 +325,20 @@ use_encryption = true
 use_compression = true
 ```

-### Reload configures without frps stopped
+### Hot-Reload frpc configuration
+
+First you need to set admin port in frpc's configure file to let it provide HTTP API for more features.
+
+```ini
+# frpc.ini
+[common]
+admin_addr = 127.0.0.1
+admin_port = 7400
+```
+
+Then run command `frpc -c ./frpc.ini --reload` and wait for about 10 seconds to let frpc create or update or delete proxies.

-This feature is removed since v0.10.0.
+**Note that parameters in [common] section won't be modified except 'start' now.**

 ### Privilege Mode

@ -386,6 +434,14 @@ host_header_rewrite = dev.yourdomain.com

 If `host_header_rewrite` is specified, the Host header will be rewritten to match the hostname portion of the forwarding address.

+### Get Real IP
+
+Features for http proxy only.
+
+You can get user's real IP from http request header `X-Forwarded-For` and `X-Real-IP`.
+
+**Note that now you can only get these two headers in first request of each user connection.**
+
 ### Password protecting your web service

 Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password.
--- a/README_zh.md
+++ b/README_zh.md
@ -17,18 +17,21 @@ frp 是一个可用于内网穿透的高性能的反向代理应用，支持 tcp
    * [通过自定义域名访问部署于内网的 web 服务](#通过自定义域名访问部署于内网的-web-服务)
    * [转发 DNS 查询请求](#转发-dns-查询请求)
    * [转发 Unix域套接字](#转发-unix域套接字)
+    * [安全地暴露内网服务](#安全地暴露内网服务)
    * [通过 frpc 所在机器访问外网](#通过-frpc-所在机器访问外网)
 * [功能说明](#功能说明)
+    * [配置文件](#配置文件)
    * [Dashboard](#dashboard)
    * [身份验证](#身份验证)
    * [加密与压缩](#加密与压缩)
-    * [服务器端热加载配置文件](#服务器端热加载配置文件)
+    * [客户端热加载配置文件](#客户端热加载配置文件)
    * [特权模式](#特权模式)
        * [端口白名单](#端口白名单)
    * [TCP 多路复用](#tcp-多路复用)
-    * [支持 kcp 协议](#支持-kcp-协议)
+    * [底层通信可选 kcp 协议](#底层通信可选-kcp-协议)
    * [连接池](#连接池)
    * [修改 Host Header](#修改-host-header)
+    * [获取用户真实 IP](#获取用户真实-ip)
    * [通过密码保护你的 web 服务](#通过密码保护你的-web-服务)
    * [自定义二级域名](#自定义二级域名)
    * [URL 路由](#url-路由)
@ -188,19 +191,38 @@ DNS 查询请求通常使用 UDP 协议，frp 支持对内网 UDP 服务的穿

 通过 tcp 端口访问内网的 unix域套接字(和 docker daemon 通信)。

-1. 修改 frps.ini 文件：
+frps 的部署步骤同上。
+
+1. 启动 frpc，启用 unix_domain_socket 插件，配置如下：

  ```ini
-  # frps.ini
+  # frpc.ini
  [common]
-  bind_port = 7000
+  server_addr = x.x.x.x
+  server_port = 7000
+  
+  [unix_domain_socket]
+  type = tcp
+  remote_port = 6000
+  plugin = unix_domain_socket
+  plugin_unix_path = /var/run/docker.sock
  ```

-2. 启动 frps：
+2. 通过 curl 命令查看 docker 版本信息

-  `./frps -c ./frps.ini`
+  `curl http://x.x.x.x:6000/version`
+
+### 安全地暴露内网服务
+
+对于某些服务来说如果直接暴露于公网上将会存在安全隐患。
+
+使用 **stcp(secret tcp)** 类型的代理可以避免让任何人都能访问到要穿透的服务，但是访问者也需要运行另外一个 frpc。
+
+以下示例将会创建一个只有自己能访问到的 ssh 服务代理。
+
+frps 的部署步骤同上。

-3. 修改 frpc.ini 文件，启用 unix_domain_socket 插件：
+1. 启动 frpc，转发内网的 ssh 服务，配置如下，不需要指定远程端口：

  ```ini
  # frpc.ini
@ -208,20 +230,37 @@ DNS 查询请求通常使用 UDP 协议，frp 支持对内网 UDP 服务的穿
  server_addr = x.x.x.x
  server_port = 7000

-  [unix_domain_socket]
-  type = tcp
-  remote_port = 6000
-  plugin = unix_domain_socket
-  plugin_unix_path = /var/run/docker.sock
+  [secret_ssh]
+  type = stcp
+  # 只有 sk 一致的用户才能访问到此服务
+  sk = abcdefg
+  local_ip = 127.0.0.1
+  local_port = 22
  ```

-4. 启动 frpc：
+2. 在要访问这个服务的机器上启动另外一个 frpc，配置如下：

-  `./frpc -c ./frpc.ini`
+  ```ini
+  # frpc.ini
+  [common]
+  server_addr = x.x.x.x
+  server_port = 7000

-5. 通过 curl 命令查看 docker 版本信息
+  [secret_ssh_vistor]
+  type = stcp
+  # stcp 的访问者
+  role = vistor
+  # 要访问的 stcp 代理的名字
+  server_name = secret_ssh
+  sk = abcdefg
+  # 绑定本地端口用于访问 ssh 服务
+  bind_addr = 127.0.0.1
+  bind_port = 6000
+  ```

-  `curl http://x.x.x.x:6000/version`
+3. 通过 ssh 访问内网机器，假设用户名为 test：
+
+  `ssh -oPort=6000 test@127.0.0.1`

 ### 通过 frpc 所在机器访问外网

@ -229,7 +268,7 @@ frpc 内置了 http proxy 和 socks5 插件，可以使其他机器通过 frpc

 frps 的部署步骤同上。

-1. 修改 frpc.ini 文件，启用 http_proxy 或 socks5 插件(plugin 换为 socks5 即可)：
+1. 启动 frpc，启用 http_proxy 或 socks5 插件(plugin 换为 socks5 即可)， 配置如下：

  ```ini
  # frpc.ini
@ -243,13 +282,17 @@ frps 的部署步骤同上。
  plugin = http_proxy
  ```

-4. 启动 frpc：
+2. 浏览器设置 http 或 socks5 代理地址为 `x.x.x.x:6000`，通过 frpc 机器的网络访问互联网。

-  `./frpc -c ./frpc.ini`
+## 功能说明

-5. 浏览器设置 http 或 socks5 代理地址为 `x.x.x.x:6000`，通过 frpc 机器的网络访问互联网。
+### 配置文件

-## 功能说明
+由于 frp 目前支持的功能和配置项较多，未在文档中列出的功能可以从完整的示例配置文件中发现。
+
+[frps 完整配置文件](./conf/frps_full.ini)
+
+[frpc 完整配置文件](./conf/frpc_full.ini)

 ### Dashboard

@ -295,9 +338,26 @@ use_compression = true

 如果传输的报文长度较长，通过设置 `use_compression = true` 对传输内容进行压缩，可以有效减小 frpc 与 frps 之间的网络流量，加快流量转发速度，但是会额外消耗一些 cpu 资源。

-### 服务器端热加载配置文件
+### 客户端热加载配置文件
+
+当修改了 frpc 中的代理配置，可以通过 `frpc --reload` 命令来动态加载配置文件，通常会在 10 秒内完成代理的更新。
+
+启用此功能需要在 frpc 中启用 admin 端口，用于提供 API 服务。配置如下：
+
+```ini
+# frpc.ini
+[common]
+admin_addr = 127.0.0.1
+admin_port = 7400
+```
+
+之后执行重启命令：
+
+`frpc -c ./frpc.ini --reload`
+
+等待一段时间后客户端会根据新的配置文件创建、更新、删除代理。

-由于从 v0.10.0 版本开始，所有 proxy 都在客户端配置，这个功能暂时移除。
+**需要注意的是，[common] 中的参数除了 start 外目前无法被修改。**

 ### 特权模式

@ -327,7 +387,7 @@ privilege_allow_ports 可以配置允许使用的某个指定端口或者是一
 tcp_mux = false
 ```

-### 支持 kcp 协议
+### 底层通信可选 kcp 协议

 从 v0.12.0 版本开始，底层通信协议支持选择 kcp 协议，在弱网环境下传输效率提升明显，但是会有一些额外的流量消耗。

@ -393,6 +453,12 @@ host_header_rewrite = dev.yourdomain.com

 原来 http 请求中的 host 字段 `test.yourdomain.com` 转发到后端服务时会被替换为 `dev.yourdomain.com`。

+### 获取用户真实 IP
+
+目前只有 **http** 类型的代理支持这一功能，可以通过用户请求的 header 中的 `X-Forwarded-For` 和 `X-Real-IP` 来获取用户真实 IP。
+
+**需要注意的是，目前只在每一个用户连接的第一个 HTTP 请求中添加了这两个 header。**
+
 ### 通过密码保护你的 web 服务

 由于所有客户端共用一个 frps 的 http 服务端口，任何知道你的域名和 url 的人都能访问到你部署在内网的 web 服务，但是在某些场景下需要确保只有限定的用户才能访问。