Merge pull request #65 from fatedier/0.8doc

0.8doc

README.md

@@ -15,12 +15,16 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
 * [Architecture](#architecture)
 * [Example Usage](#example-usage) 
   * [Communicate with your computer in LAN by SSH](#communicate-with-your-computer-in-lan-by-ssh)
-  * [Visit your web service in LAN by specific domain](#visit-your-web-service-in-lan-by-specific-domain)
+  * [Visit your web service in LAN by custom domains](#visit-your-web-service-in-lan-by-custom-domains)
 * [Features](#features)
+  * [Dashboard](#dashboard)
   * [Authentication](#authentication)
   * [Encryption and Compression](#encryption-and-compression)
   * [Reload configures without frps stopped](#reload-configures-without-frps-stopped)
   * [Privilege Mode](#privilege-mode)
+    * [Port White List](#port-white-list)
+  * [Connection Pool](#connection-pool)
+  * [Rewriting the Host Header](#rewriting-the-host-header)
 * [Development Plan](#development-plan)
 * [Contributing](#contributing)
 * [Contributors](#contributors)
@@ -35,7 +39,7 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
 
 frp is under development and you can try it with latest release version.Master branch for releasing stable version when dev branch for developing.
 
-**We may change any protocol and can't promise backward compatible.Please note the release log when upgrading.**
+**We may change any protocol and can't promise backward compatible.Please check the release log when upgrading.**
 
 ## Architecture
 
@@ -43,7 +47,7 @@ frp is under development and you can try it with latest release version.Master b
 
 ## Example Usage
 
-First, download the latest version programs from [Release](https://github.com/fatedier/frp/releases) page according to your os and arch.
+Firstly, download the latest programs from [Release](https://github.com/fatedier/frp/releases) page according to your os and arch.
 
 Put **frps** and **frps.ini** to your server with public IP.
 
@@ -88,13 +92,13 @@ Put **frpc** and **frpc.ini** to your server in LAN.
 
   `ssh -oPort=6000 test@x.x.x.x`
 
-### Visit your web service in LAN by specific domain
+### Visit your web service in LAN by custom domains
 
-Sometimes we need to expose a local web service behind a NAT network to others for testing with your own domain and unfortunately we can't resolve a domain to a local ip.
+Sometimes we want to expose a local web service behind a NAT network to others for testing with your own domain name and unfortunately we can't resolve a domain name to a local ip.
 
 Howerver, we can expose a http or https service using frp.
 
-1. Modify frps.ini, configure a http reverse proxy named [web] and set http port as 8080, custom domain as www.yourdomain.com:
+1. Modify frps.ini, configure a http reverse proxy named [web] and set http port as 8080, custom domain as `www.yourdomain.com`:
 
   ```ini
   # frps.ini
@@ -112,7 +116,7 @@ Howerver, we can expose a http or https service using frp.
 
   `./frps -c ./frps.ini`
 
-3. Modify frpc.ini and set remote frps server's IP as x.x.x.x. The local_port is the port of your web service:
+3. Modify frpc.ini and set remote frps server's IP as x.x.x.x. The `local_port` is the port of your web service:
 
   ```ini
   # frpc.ini
@@ -130,23 +134,38 @@ Howerver, we can expose a http or https service using frp.
 
   `./frpc -c ./frpc.ini`
 
-5. Resolve A record of www.yourdomain.com to x.x.x.x or CNAME record to your origin domain.
+5. Resolve A record of `www.yourdomain.com` to IP `x.x.x.x` or CNAME record to your origin domain.
 
-6. Now your can visit your local web service from url `http://www.yourdomain.com:8080`.
+6. Now visit your local web service using url `http://www.yourdomain.com:8080`.
 
 ## Features
 
+### Dashboard
+
+Check frp's status and proxies's statistics information by Dashboard.
+
+Configure a port for dashboard to enable this feature:
+
+```ini
+[common]
+dashboard_port = 7500
+```
+
+Then visit `http://[server_addr]:7500` to see dashboard.
+
+![dashboard](/doc/pic/dashboard.png)
+
 ### Authentication
 
-`auth_token` is used in frps.ini for authentication when frpc login in and you should configure it for each proxy.
+`auth_token` in frps.ini is configured for each proxy and check for authentication when frpc login in.
 
-Client should set a global `auth_token` equals to frps.ini.
+Client that want's to register must set a global `auth_token` equals to frps.ini.
 
-Note that time duration bewtween frpc and frps shouldn't exceed 15 minutes because timestamp is used for authentication.
+Note that time duration bewtween frpc and frps mustn't exceed 15 minutes because timestamp is used for authentication.
 
 ### Encryption and Compression
 
-Defalut value is false, you could decide if the proxy should use encryption or compression whether the type is:
+Defalut value is false, you could decide if the proxy will use encryption or compression whether the type is:
 
 ```ini
 # frpc.ini
@@ -160,7 +179,7 @@ use_gzip = true
 
 ### Reload configures without frps stopped
 
-If your want to add a new reverse proxy and avoid restarting frps, you can use this feature.
+If your want to add a new reverse proxy and avoid restarting frps, you can use this function:
 
 1. `dashboard_port` should be set in frps.ini:
 
@@ -198,7 +217,7 @@ If your want to add a new reverse proxy and avoid restarting frps, you can use t
 
 Privilege mode is used for who don't want to do operations in frps everytime adding a new proxy.
 
-All proxies's configures are set in frpc.ini when privilege mode is enabled.
+All proxies's configurations are set in frpc.ini when privilege mode is enabled.
 
 1. Enable privilege mode and set `privilege_token`.Client with the same `privilege_token` can create proxy automaticly:
 
@@ -233,22 +252,74 @@ All proxies's configures are set in frpc.ini when privilege mode is enabled.
 
   `./frpc -c ./frpc.ini`
 
-5. Connect to server in LAN by ssh assuming that username is test:
+5. Connect to server in LAN by ssh assuming username is test:
 
   `ssh -oPort=6000 test@x.x.x.x`
 
+#### Port White List
+
+`privilege_allow_ports` in frps.ini is used for preventing abuse of ports in privilege mode:
+
+```ini
+# frps.ini
+[common]
+privilege_mode = true
+privilege_token = 1234
+privilege_allow_ports = 2000-3000,3001,3003,4000-50000
+```
+
+`privilege_allow_ports` consists of a specific port or a range of ports divided by `,`.
+
+### Connection Pool
+
+By default, frps send message to frpc for create a new connection to backward service when getting an user request.If a proxy's connection pool is enabled, there will be a specified number of connections pre-established.
+
+This feature is fit for a large number of short connections.
+
+1. Configure the limit of pool count each proxy can use in frps.ini:
+
+  ```ini         
+  # frps.ini
+  [common]
+  max_pool_count = 50
+  ```
+
+2. Enable and specify the number of connection pool:
+
+  ```ini 
+  # frpc.ini
+  [ssh] 
+  type = tcp
+  local_port = 22
+  pool_count = 10
+  ```
+
+### Rewriting the Host Header
+
+When forwarding to a local port, frp does not modify the tunneled HTTP requests at all, they are copied to your server byte-for-byte as they are received. Some application servers use the Host header for determining which development site to display. For this reason, frp can rewrite your requests with a modified Host header. Use the `host_header_rewrite` switch to rewrite incoming HTTP requests.
+
+```ini                                                             
+# frpc.ini                                                         
+[web] 
+privilege_mode = true
+type = http
+local_port = 80
+custom_domains = test.yourdomain.com
+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.
+
 ## Development Plan
 
-* Dashboard page.
-* Statistics and prestentation of traffic and connection info, etc.
 * Support udp protocol.
-* Connection pool.
-* White list for opening specific ports in privilege mode.
 * Support wildcard domain name.
 * Url router.
 * Load balance to different service in frpc.
 * Debug mode for frpc, prestent proxy status in terminal.
 * Inspect all http requests/responses that are transmitted over the tunnel.
+* Frpc can directly be a webserver for static files.
+* Full control mode, dynamically modify frpc's configure with dashboard in frps.
 * P2p communicate by make udp hole to penetrate NAT.
 
 ## Contributing

README_zh.md

@@ -13,12 +13,16 @@ frp 是一个高性能的反向代理应用，可以帮助您轻松地进行内
 * [架构](#架构)
 * [使用示例](#使用示例)
   * [通过 ssh 访问公司内网机器](#通过-ssh-访问公司内网机器)
-  * [通过指定域名访问部署于内网的 web 服务](#通过指定域名访问部署于内网的-web-服务) 
+  * [通过自定义域名访问部署于内网的 web 服务](#通过自定义域名访问部署于内网的-web-服务) 
 * [功能说明](#功能说明)
+  * [Dashboard](#dashboard)
   * [身份验证](#身份验证)
   * [加密与压缩](#加密与压缩)
   * [服务器端热加载配置文件](#服务器端热加载配置文件)
   * [特权模式](#特权模式)
+    * [端口白名单](#端口白名单)
+  * [连接池](#连接池)
+  * [修改 Host Header](#修改-host-header)
 * [开发计划](#开发计划)
 * [贡献代码](#贡献代码)
 * [贡献者](#贡献者)
@@ -87,11 +91,11 @@ frp 目前正在前期开发阶段，master 分支用于发布稳定版本，dev
 
   `ssh -oPort=6000 test@x.x.x.x`
 
-### 通过指定域名访问部署于内网的 web 服务
+### 通过自定义域名访问部署于内网的 web 服务
 
 有时想要让其他人通过域名访问或者测试我们在本地搭建的 web 服务，但是由于本地机器没有公网 IP，无法将域名解析到本地的机器，通过 frp 就可以实现这一功能，以下示例为 http 服务，https 服务配置方法相同， vhost_http_port 替换为 vhost_https_port， type 设置为 https 即可。
 
-1. 修改 frps.ini 文件，配置一个名为 web 的 http 反向代理，设置 http 访问端口为 8080，绑定自定义域名 www.yourdomain.com：
+1. 修改 frps.ini 文件，配置一个名为 web 的 http 反向代理，设置 http 访问端口为 8080，绑定自定义域名 `www.yourdomain.com`：
 
   ```ini
   # frps.ini
@@ -127,12 +131,27 @@ frp 目前正在前期开发阶段，master 分支用于发布稳定版本，dev
 
   `./frpc -c ./frpc.ini`
 
-5. 将 www.yourdomain.com 的域名 A 记录解析到 x.x.x.x，如果服务器已经有对应的域名，也可以将 CNAME 记录解析到服务器原先的域名。
+5. 将 `www.yourdomain.com` 的域名 A 记录解析到 IP `x.x.x.x`，如果服务器已经有对应的域名，也可以将 CNAME 记录解析到服务器原先的域名。
 
 6. 通过浏览器访问 `http://www.yourdomain.com:8080` 即可访问到处于内网机器上的 web 服务。
 
 ## 功能说明
 
+### Dashboard
+
+通过浏览器查看 frp 的状态以及代理统计信息展示。
+
+需要在 frps.ini 中指定 dashboard 服务使用的端口，即可开启此功能：
+
+```ini
+[common]
+dashboard_port = 7500
+```
+
+打开浏览器通过 `http://[server_addr]:7500` 访问 dashboard 界面。
+
+![dashboard](/doc/pic/dashboard.png)
+
 ### 身份验证
 
 出于安全性的考虑，服务器端可以在 frps.ini 中为每一个代理设置一个 auth_token 用于对客户端连接进行身份验证，例如上文中的 [ssh] 和 [web] 两个代理的 auth_token 都为 123。
@@ -242,20 +261,72 @@ reload 命令仅能用于修改代理的配置内容，[common] 内的公共配
 
   `ssh -oPort=6000 test@x.x.x.x`
 
+#### 端口白名单
+
+启用特权模式后为了防止端口被滥用，可以手动指定允许哪些端口被使用，在 frps.ini 中通过 privilege_allow_ports 来指定：
+
+```ini
+# frps.ini
+[common]
+privilege_mode = true
+privilege_token = 1234
+privilege_allow_ports = 2000-3000,3001,3003,4000-50000
+```
+
+privilege_allow_ports 可以配置允许使用的某个指定端口或者是一个范围内的所有端口，以 `,` 分隔，指定的范围以 `-` 分隔。
+
+### 连接池
+
+默认情况下，当用户请求建立连接后，frps 才会请求 frpc 主动与后端服务建立一个连接。当为指定的代理启用连接池后，frp 会预先和后端服务建立起指定数量的连接，每次接收到用户请求后，会从连接池中取出一个连接和用户连接关联起来，避免了等待与后端服务建立连接以及 frpc 和 frps 之间传递控制信息的时间。
+
+这一功能比较适合有大量短连接请求时开启。
+
+1. 首先可以在 frps.ini 中设置每个代理可以创建的连接池上限，避免大量资源占用，默认为 100，客户端设置超过此配置后会被调整到当前值：
+
+  ```ini
+  # frps.ini
+  [common]
+  max_pool_count = 50
+  ```
+
+2. 在 frpc.ini 中为指定代理启用连接池，指定预创建连接的数量：
+
+  ```ini
+  # frpc.ini
+  [ssh]
+  type = tcp
+  local_port = 22
+  pool_count = 10
+  ```
+
+### 修改 Host Header
+
+通常情况下 frp 不会修改转发的任何数据。但有一些后端服务会根据 http 请求 header 中的 host 字段来展现不同的网站，例如 nginx 的虚拟主机服务，启用 host-header 的修改功能可以动态修改 http 请求中的 host 字段。该功能仅限于 http 类型的代理。
+
+```ini
+# frpc.ini
+[web]
+privilege_mode = true
+type = http
+local_port = 80
+custom_domains = test.yourdomain.com
+host_header_rewrite = dev.yourdomain.com
+```
+
+原来 http 请求中的 host 字段 `test.yourdomain.com` 转发到后端服务时会被替换为 `dev.yourdomain.com`。
+
 ## 开发计划
 
 计划在后续版本中加入的功能与优化，排名不分先后，如果有其他功能建议欢迎在 [issues](https://github.com/fatedier/frp/issues) 中反馈。
 
-* Dashboard 界面。
+* 支持 udp 协议。
-* 流量，连接数等代理信息统计与展示。
-* udp 协议支持。
-* 针对短连接的连接池优化。
-* 特权模式支持端口白名单。
 * 支持泛域名。
 * 支持 url 路由转发。
 * frpc 支持负载均衡到后端不同服务。
 * frpc debug 模式，控制台显示代理状态，类似 ngrok 启动后的界面。
 * frpc http 请求及响应信息展示。
+* frpc 支持直接作为 webserver 访问指定静态页面。
+* frpc 完全控制模式，通过 dashboard 对 frpc 进行在线操作。
 * 支持 udp 打洞的方式，提供两边内网机器直接通信，流量不经过服务器转发。
 
 ## 贡献代码