Merge pull request fatedier#187 from fatedier/doc

update doc for v0.9.0
vvoody · Dec 21, 2016 · 5532881 · 5532881
2 parents ddbb56e + 94ddeeb
commit 5532881
Show file tree

Hide file tree

Showing 3 changed files with 260 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -10,26 +10,35 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
 
 ## Catalog
 
+<!-- vim-markdown-toc GFM -->
 * [What can I do with frp?](#what-can-i-do-with-frp)
 * [Status](#status)
 * [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 custom domains](#visit-your-web-service-in-lan-by-custom-domains)
+    * [Communicate with your computer in LAN by SSH](#communicate-with-your-computer-in-lan-by-ssh)
+    * [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)
 * [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)
+    * [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)
+    * [Password protecting your web service](#password-protecting-your-web-service)
+    * [Custom subdomain names](#custom-subdomain-names)
+    * [Connect frps by HTTP PROXY](#connect-frps-by-http-proxy)
 * [Development Plan](#development-plan)
 * [Contributing](#contributing)
 * [Donation](#donation)
+    * [AliPay](#alipay)
+    * [Paypal](#paypal)
 * [Contributors](#contributors)
 
+<!-- vim-markdown-toc -->
+
 ## What can I do with frp?
 
 * Expose any http and https service behind a NAT or firewall to the internet by a server with public IP address(Name-based Virtual Host Support).
@@ -82,6 +91,8 @@ Put **frpc** and **frpc.ini** to your server in LAN.
   auth_token = 123
 
   [ssh]
+  type = tcp
+  local_ip = 127.0.0.1
   local_port = 22
   ```
 
@@ -139,6 +150,48 @@ Howerver, we can expose a http or https service using frp.
 
 6. Now visit your local web service using url `http://www.yourdomain.com:8080`.
 
+### Forward DNS query request
+
+1. Modify frps.ini, configure a reverse proxy named [dns]:
+
+  ```ini
+  # frps.ini
+  [common]
+  bind_port = 7000
+
+  [dns]
+  type = udp
+  listen_port = 6000
+  auth_token = 123
+  ```
+
+2. Start frps:
+
+  `./frps -c ./frps.ini`
+
+3. Modify frpc.ini, set remote frps's server IP as x.x.x.x, forward dns query request to google dns server `8.8.8.8:53`:
+
+  ```ini
+  # frpc.ini
+  [common]
+  server_addr = x.x.x.x
+  server_port = 7000
+  auth_token = 123
+
+  [dns]
+  type = udp
+  local_ip = 8.8.8.8
+  local_port = 53
+  ```
+
+4. Start frpc:
+
+  `./frpc -c ./frpc.ini`
+
+5. Send dns query request by dig:
+
+  `dig @x.x.x.x -p 6000 www.goolge.com`
+
 ## Features
 
 ### Dashboard
@@ -151,8 +204,8 @@ Configure a port for dashboard to enable this feature:
 [common]
 dashboard_port = 7500
 # dashboard's username and password are both optional，if not set, default is admin.
-dashboard_username = abc
-dashboard_password = abc
+dashboard_user = admin
+dashboard_pwd = admin
 ```
 
 Then visit `http://[server_addr]:7500` to see dashboard, default username and password are both `admin`.
@@ -167,6 +220,8 @@ Client that want's to register must set a global `auth_token` equals to frps.ini
 
 Note that time duration bewtween frpc and frps mustn't exceed 15 minutes because timestamp is used for authentication.
 
+Howerver, this timeout duration can be modified by setting `authentication_timeout` in frps's configure file. It's defalut value is 900, means 15 minutes. If it is equals 0, then frps will not check authentication timeout.
+
 ### Encryption and Compression
 
 Defalut value is false, you could decide if the proxy will use encryption or compression whether the type is:
@@ -314,11 +369,67 @@ 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.
 
+### 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.
+
+This enforces HTTP Basic Auth on all requests with the username and password you specify in frpc's configure file.
+
+It can be only enabled when proxy type is http.
+
+```ini
+# frpc.ini
+[web]
+privilege_mode = true
+type = http
+local_port = 80
+custom_domains = test.yourdomain.com
+http_user = abc
+http_pwd = abc
+```
+
+Visit `test.yourdomain.com` and now you need to input username and password.
+
+### Custom subdomain names
+
+It is convenient to use `subdomain` configure for http、https type when many people use one frps server together.
+
+```ini
+# frps.ini
+subdomain_host = frps.com
+```
+
+Resolve `*.frps.com` to the frps server's IP.
+
+```ini
+# frpc.ini
+[web]
+privilege_mode = true
+type = http
+local_port = 80
+subdomain = test
+```
+
+Now you can visit your web service by host `test.frps.com`.
+
+Note that if `subdomain_host` is not empty, `custom_domains` should not be the subdomain of `subdomain_host`.
+
+### Connect frps by HTTP PROXY
+
+frpc can connect frps using HTTP PROXY if you set os environment `HTTP_PROXY` or configure `http_proxy` param in frpc.ini file.
+
+```ini
+# frpc.ini
+server_addr = x.x.x.x
+server_port = 7000
+http_proxy = http://user:[email protected]:8080
+```
+
 ## Development Plan
 
-* Support udp protocol.
-* Support wildcard domain name.
 * Url router.
+* Log http request information in frps.
+* Direct reverse proxy, like haproxy.
 * 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.

diff --git a/README_zh.md b/README_zh.md
@@ -8,26 +8,35 @@ frp 是一个高性能的反向代理应用，可以帮助您轻松地进行内
 
 ## 目录
 
+<!-- vim-markdown-toc GFM -->
 * [frp 的作用](#frp-的作用)
 * [开发状态](#开发状态)
 * [架构](#架构)
 * [使用示例](#使用示例)
-  * [通过 ssh 访问公司内网机器](#通过-ssh-访问公司内网机器)
-  * [通过自定义域名访问部署于内网的 web 服务](#通过自定义域名访问部署于内网的-web-服务) 
+    * [通过 ssh 访问公司内网机器](#通过-ssh-访问公司内网机器)
+    * [通过自定义域名访问部署于内网的 web 服务](#通过自定义域名访问部署于内网的-web-服务)
+    * [转发 DNS 查询请求](#转发-dns-查询请求)
 * [功能说明](#功能说明)
-  * [Dashboard](#dashboard)
-  * [身份验证](#身份验证)
-  * [加密与压缩](#加密与压缩)
-  * [服务器端热加载配置文件](#服务器端热加载配置文件)
-  * [特权模式](#特权模式)
-    * [端口白名单](#端口白名单)
-  * [连接池](#连接池)
-  * [修改 Host Header](#修改-host-header)
+    * [Dashboard](#dashboard)
+    * [身份验证](#身份验证)
+    * [加密与压缩](#加密与压缩)
+    * [服务器端热加载配置文件](#服务器端热加载配置文件)
+    * [特权模式](#特权模式)
+        * [端口白名单](#端口白名单)
+    * [连接池](#连接池)
+    * [修改 Host Header](#修改-host-header)
+    * [通过密码保护你的 web 服务](#通过密码保护你的-web-服务)
+    * [自定义二级域名](#自定义二级域名)
+    * [通过 HTTP PROXY 连接 frps](#通过-http-proxy-连接-frps)
 * [开发计划](#开发计划)
 * [为 frp 做贡献](#为-frp-做贡献)
 * [捐助](#捐助)
+    * [支付宝扫码捐赠](#支付宝扫码捐赠)
+    * [Paypal 捐赠](#paypal-捐赠)
 * [贡献者](#贡献者)
 
+<!-- vim-markdown-toc -->
+
 ## frp 的作用
 
 * 利用处于内网或防火墙后的机器，对外网环境提供 http 或 https 服务。
@@ -81,6 +90,7 @@ frp 目前正在前期开发阶段，master 分支用于发布稳定版本，dev
   auth_token = 123
 
   [ssh]
+  local_ip = 127.0.0.1
   local_port = 22
   ```
 
@@ -136,6 +146,50 @@ frp 目前正在前期开发阶段，master 分支用于发布稳定版本，dev
 
 6. 通过浏览器访问 `http://www.yourdomain.com:8080` 即可访问到处于内网机器上的 web 服务。
 
+### 转发 DNS 查询请求
+
+DNS 查询请求通常使用 UDP 协议，frp 支持对内网 UDP 服务的穿透，配置方式和 TCP 基本一致。
+
+1. 修改 frps.ini 文件，配置一个名为 dns 的反向代理：
+
+  ```ini
+  # frps.ini
+  [common]
+  bind_port = 7000
+
+  [dns]
+  type = udp
+  listen_port = 6000
+  auth_token = 123
+  ```
+
+2. 启动 frps：
+
+  `./frps -c ./frps.ini`
+
+3. 修改 frpc.ini 文件，设置 frps 所在服务器的 IP 为 x.x.x.x，转发到 Google 的 DNS 查询服务器 `8.8.8.8` 的 udp 53 端口：
+
+  ```ini
+  # frpc.ini
+  [common]
+  server_addr = x.x.x.x
+  server_port = 7000
+  auth_token = 123
+
+  [dns]
+  type = udp
+  local_ip = 8.8.8.8
+  local_port = 53
+  ```
+
+4. 启动 frpc：
+
+  `./frpc -c ./frpc.ini`
+
+5. 通过 dig 测试 UDP 包转发是否成功，预期会返回 `www.google.com` 域名的解析结果：
+
+  `dig @x.x.x.x -p 6000 www.goolge.com`
+
 ## 功能说明
 
 ### Dashboard
@@ -148,8 +202,8 @@ frp 目前正在前期开发阶段，master 分支用于发布稳定版本，dev
 [common]
 dashboard_port = 7500
 # dashboard 用户名密码可选，默认都为 admin
-dashboard_username = abc
-dashboard_password = abc
+dashboard_user = admin
+dashboard_pwd = admin
 ```
 
 打开浏览器通过 `http://[server_addr]:7500` 访问 dashboard 界面，用户名密码默认为 `admin`。
@@ -164,6 +218,8 @@ dashboard_password = abc
 
 需要注意的是 frpc 所在机器和 frps 所在机器的时间相差不能超过 15 分钟，因为时间戳会被用于加密验证中，防止报文被劫持后被其他人利用。
 
+这个超时时间可以在配置文件中通过 `authentication_timeout` 这个参数来修改，单位为秒，默认值为 900，即 15 分钟。如果修改为 0，则 frps 将不对身份验证报文的时间戳进行超时校验。
+
 ### 加密与压缩
 
 这两个功能默认是不开启的，需要在 frpc.ini 中通过配置来为指定的代理启用加密与压缩的功能，无论类型是 tcp, http 还是 https：
@@ -319,13 +375,77 @@ host_header_rewrite = dev.yourdomain.com
 
 原来 http 请求中的 host 字段 `test.yourdomain.com` 转发到后端服务时会被替换为 `dev.yourdomain.com`。
 
+### 通过密码保护你的 web 服务
+
+由于所有客户端共用一个 frps 的 http 服务端口，任何知道你的域名和 url 的人都能访问到你部署在内网的 web 服务，但是在某些场景下需要确保只有限定的用户才能访问。
+
+frp 支持通过 HTTP Basic Auth 来保护你的 web 服务，使用户需要通过用户名和密码才能访问到你的服务。
+
+该功能目前仅限于 http 类型的代理，需要在 frpc 的代理配置中添加用户名和密码的设置。
+
+```ini
+# frpc.ini
+[web]
+privilege_mode = true
+type = http
+local_port = 80
+custom_domains = test.yourdomain.com
+http_user = abc
+http_pwd = abc
+```
+
+通过浏览器访问 `test.yourdomain.com`，需要输入配置的用户名和密码才能访问。
+
+### 自定义二级域名
+
+在多人同时使用一个 frps 时，通过自定义二级域名的方式来使用会更加方便。
+
+通过在 frps 的配置文件中配置 `subdomain_host`，就可以启用该特性。之后在 frpc 的 http、https 类型的代理中可以不配置 `custom_domains`，而是配置一个 `subdomain` 参数。
+
+只需要将 `*.subdomain_host` 解析到 frps 所在服务器。之后用户可以通过 `subdomain` 自行指定自己的 web 服务所需要使用的二级域名，通过 `{subdomain}.{subdomain_host}` 来访问自己的 web 服务。
+
+```ini
+# frps.ini
+subdomain_host = frps.com
+```
+
+将泛域名 `*.frps.com` 解析到 frps 所在服务器的 IP 地址。
+
+```ini
+# frpc.ini
+[web]
+privilege_mode = true
+type = http
+local_port = 80
+subdomain = test
+```
+
+frps 和 fprc 都启动成功后，通过 `test.frps.com` 就可以访问到内网的 web 服务。
+
+需要注意的是如果 frps 配置了 `subdomain_host`，则 `custom_domains` 中不能是属于 `subdomain_host` 的子域名或者泛域名。
+
+同一个 http 或 https 类型的代理中 `custom_domains`  和 `subdomain` 可以同时配置。
+
+### 通过 HTTP PROXY 连接 frps
+
+在只能通过代理访问外网的环境内，frpc 支持通过 HTTP PROXY 和 frps 进行通信。
+
+可以通过设置 `HTTP_PROXY` 系统环境变量或者通过在 frpc 的配置文件中设置 `http_proxy` 参数来使用此功能。
+
+```ini
+# frpc.ini
+server_addr = x.x.x.x
+server_port = 7000
+http_proxy = http://user:[email protected]:8080
+```
+
 ## 开发计划
 
 计划在后续版本中加入的功能与优化，排名不分先后，如果有其他功能建议欢迎在 [issues](https://github.com/fatedier/frp/issues) 中反馈。
 
-* 支持 udp 协议。
-* 支持泛域名。
 * 支持 url 路由转发。
+* frps 记录 http 请求日志。
+* frps 支持直接反向代理，类似 haproxy。
 * frpc 支持负载均衡到后端不同服务。
 * frpc debug 模式，控制台显示代理状态，类似 ngrok 启动后的界面。
 * frpc http 请求及响应信息展示。