From 94ddeebc21fabcd4eba8c09ae2e198b5bb0f997d Mon Sep 17 00:00:00 2001 From: fatedier Date: Wed, 21 Dec 2016 01:18:12 +0800 Subject: [PATCH] update doc --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++----- README_zh.md | 148 +++++++++++++++++++++++++++++++++++++++++++++----- conf/frpc.ini | 1 + 3 files changed, 260 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 205e153..b95cfe2 100644 --- 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 + * [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) + + ## 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:pwd@192.168.1.128: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 index 6f389f2..787fabb 100644 --- a/README_zh.md +++ b/README_zh.md @@ -8,26 +8,35 @@ frp 是一个高性能的反向代理应用，可以帮助您轻松地进行内 ## 目录 + * [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-捐赠) * [贡献者](#贡献者) + + ## 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:pwd@192.168.1.128:8080 +``` + ## 开发计划 计划在后续版本中加入的功能与优化，排名不分先后，如果有其他功能建议欢迎在 [issues](https://github.com/fatedier/frp/issues) 中反馈。 -* 支持 udp 协议。 -* 支持泛域名。 * 支持 url 路由转发。 +* frps 记录 http 请求日志。 +* frps 支持直接反向代理，类似 haproxy。 * frpc 支持负载均衡到后端不同服务。 * frpc debug 模式，控制台显示代理状态，类似 ngrok 启动后的界面。 * frpc http 请求及响应信息展示。 diff --git a/conf/frpc.ini b/conf/frpc.ini index 9a2d729..1f8e6f4 100644 --- a/conf/frpc.ini +++ b/conf/frpc.ini @@ -7,6 +7,7 @@ server_port = 7000 # if you want to connect frps by http proxy, you can set http_proxy here or in global environment variables # http_proxy = http://user:pwd@192.168.1.128:8080 + # console or real logFile path like ./frpc.log log_file = ./frpc.log