From deb750652f56622fb01e6308511c7815fe3960b9 Mon Sep 17 00:00:00 2001 From: fatedier Date: Tue, 19 Apr 2016 18:53:48 +0800 Subject: [PATCH] doc: update --- README.md | 16 +++++--- README_zh.md | 22 ++++++----- doc/quick_start_en.md | 86 +++++++++++++++++++++++++++++++++++++------ doc/quick_start_zh.md | 86 ++++++++++++++++++++++++++++++++++++++----- 4 files changed, 175 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index acd285b..070ea4d 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,12 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet. +## What can I do with frp? + +* Expose any http service behind a NAT or firewall to the internet by a server with public IP address(Name-based Virtual Host Support). +* Expose any tcp service behind a NAT or firewall to the internet by a server with public IP address. +* Inspect all http requests/responses that are transmitted over the tunnel(future). + ## Status frp is under development and you can try it with latest release version.Master branch for releasing stable version when dev branch for developing. @@ -18,16 +24,14 @@ frp is under development and you can try it with latest release version.Master b Read the [QuickStart](doc/quick_start_en.md) | [使用文档](doc/quick_start_zh.md) +[Tcp port forwarding](doc/quick_start_en.md#Tcp-port-forwarding) + +[Http port forwarding and Custom domain binding](doc/quick_start_en.md#Http-port-forwarding-and-Custom-domains-binding) + ## Architecture ![architecture](doc/pic/architecture.png) -## What can I do with frp? - -* Expose any http service behind a NAT or firewall to the internet by a server with public IP address(Name-based Virtual Host Support). -* Expose any tcp service behind a NAT or firewall to the internet by a server with public IP address. -* Inspect all http requests/responses that are transmitted over the tunnel(future). - ## Contributing Interested in getting involved? We would love to help you! diff --git a/README_zh.md b/README_zh.md index 9da5255..64c3e1f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -4,7 +4,14 @@ [README](README.md) | [中文文档](README_zh.md) ->frp 是一个高性能的反向代理应用，可以帮助你轻松的进行内网穿透，对外网提供服务，对于 http 服务还支持虚拟主机的功能，访问80端口，可以根据域名路由到后端不同的 http 服务。 +>frp 是一个高性能的反向代理应用，可以帮助你轻松的进行内网穿透，对外网提供服务，对于 http 服务还支持虚拟主机功能，访问80端口，可以根据域名路由到后端不同的 http 服务。 + +## frp 的作用? + +* 利用处于内网或防火墙后的机器，对外网环境提供 http 服务。 +* 对于 http 服务支持基于域名的虚拟主机，支持自定义域名绑定，使多个域名可以共用一个80端口。 +* 利用处于内网或防火墙后的机器，对外网环境提供 tcp 服务，例如在家里通过 ssh 访问公司局域网内的主机。 +* 可查看通过代理的所有 http 请求和响应的详细信息。（待开发） ## 开发状态 @@ -14,19 +21,16 @@ frp 目前正在前期开发阶段，master分支用于发布稳定版本，dev ## 快速开始 -[QuickStart](doc/quick_start_en.md) | [使用文档](doc/quick_start_zh.md) +[使用文档](doc/quick_start_zh.md) + +[tcp 端口转发](doc/quick_start_zh.md#tcp-端口转发) + +[http 端口转发，自定义域名绑定](doc/quick_start_zh.md#http-端口转发，绑定自定义域名) ## 架构 ![architecture](doc/pic/architecture.png) -## frp 的作用? - -* 利用处于内网或防火墙后的机器，对外网环境提供 http 服务 -* 对于 http 服务支持基于域名的虚拟主机，支持自定义域名绑定，使多个域名可以共用一个80端口。 -* 利用处于内网或防火墙后的机器，对外网环境提供 tcp 服务，例如在家里通过 ssh 访问公司局域网内的主机。 -* 可查看通过代理的所有 http 请求和响应的详细信息。（待开发） - ## 贡献代码 如果您对这个项目感兴趣，我们非常欢迎您参与其中！ diff --git a/doc/quick_start_en.md b/doc/quick_start_en.md index 6b2a00c..4e4c767 100644 --- a/doc/quick_start_en.md +++ b/doc/quick_start_en.md @@ -2,7 +2,10 @@ frp is easier to use compared with other similar projects. -We will use a simple demo to demonstrate how to create a connection to server A's ssh port by server B with public IP address x.x.x.x(replace to the real IP address of your server). +We will use two simple demo to demonstrate how to use frp. + +1. How to create a connection to **server A**'s **ssh port** by **server B** with **public IP address** x.x.x.x(replace to the real IP address of your server). +2. How to visit web service in **server A**'s **8000 port** and **8001 port** by **web01.yourdomain.com** and **web02.yourdomain.com** through **server B** with public ID address. ### Download SourceCode @@ -10,6 +13,8 @@ We will use a simple demo to demonstrate how to create a connection to server A' Or you can use `git clone https://github.com/fatedier/frp.git $GOPATH/src/github.com/fatedier/frp`. +If you want to try it quickly, download the compiled program and configuration files from [https://github.com/fatedier/frp/releases](https://github.com/fatedier/frp/releases). + ### Compile Enter the root directory and execute `make`, then wait until finished. @@ -19,16 +24,18 @@ Enter the root directory and execute `make`, then wait until finished. ### Pre-requirement * Go environment. Version of go >= 1.4. -* Godep (if not exist, go get will be executed to download godep when compiling) +* Godep (if not exist, `go get` will be executed to download godep when compiling) ### Deploy -1. Move `./bin/frps` and `./conf/frps.ini` to any directory of server B. -2. Move `./bin/frpc` and `./conf/frpc.ini` to any directory of server A. +1. Move `./bin/frps` and `./conf/frps.ini` to any directory of **server B**. +2. Move `./bin/frpc` and `./conf/frpc.ini` to any directory of **server A**. 3. Modify all configuration files, details in next paragraph. -4. Execute `nohup ./frps &` or `nohup ./frps -c ./frps.ini &` in server B. -5. Execute `nohup ./frpc &` or `nohup ./frpc -c ./frpc.ini &` in server A. -6. Use `ssh -oPort=6000 {user}@x.x.x.x` to test if frp is work(replace {user} to real username in server A). +4. Execute `nohup ./frps &` or `nohup ./frps -c ./frps.ini &` in **server B**. +5. Execute `nohup ./frpc &` or `nohup ./frpc -c ./frpc.ini &` in **server A**. +6. Use `ssh -oPort=6000 {user}@x.x.x.x` to test if frp is work(replace {user} to real username in **server A**), or visit custom domains by browser. + +## Tcp port forwarding ### Configuration files @@ -42,8 +49,8 @@ bind_port = 7000 log_file = ./frps.log log_level = info -# test is the custom name of proxy and there can be many proxies with unique name in one configure file -[test] +# ssh is the custom name of proxy and there can be many proxies with unique name in one configure file +[ssh] auth_token = 123 bind_addr = 0.0.0.0 # finally we connect to server A by this port @@ -62,10 +69,67 @@ log_level = info # for authentication auth_token = 123 -# test is proxy name same with configure in frps.ini -[test] +# ssh is proxy name same with configure in frps.ini +[ssh] # local port which need to be transferred local_port = 22 # if use_encryption equals true, messages between frpc and frps will be encrypted, default is false use_encryption = true ``` + +## Http port forwarding and Custom domains binding + +If you only want to forward port one by one, you just need refer to [Tcp port forwarding](doc/quick_start_en.md#Tcp-port-forwarding).If you want to visit different web pages deployed in different web servers by **server B**'s **80 port**, you should specify the type as **http**. + +You also need to resolve your **A record** of your custom domain to [server_addr], or resolve your **CNAME record** to [server_addr] if [server_addr] is a domain. + +After that, you can visit your web pages in local server by custom domains. + +### Configuration files + +#### frps.ini + +```ini +[common] +bind_addr = 0.0.0.0 +bind_port = 7000 +# if you want to support vhost, specify one port for http services +vhost_http_port = 80 +log_file = ./frps.log +log_level = info + +[web01] +type = http +auth_token = 123 +# # if proxy type equals http, custom_domains must be set separated by commas +custom_domains = web01.yourdomain.com + +[web02] +type = http +auth_token = 123 +custom_domains = web02.yourdomain.com +``` + +#### frpc.ini + +```ini +[common] +server_addr = x.x.x.x +server_port = 7000 +log_file = ./frpc.log +log_level = info +auth_token = 123 + +# custom domains are set in frps.ini +[web01] +type = http +local_ip = 127.0.0.1 +local_port = 8000 +# encryption is optional, default is false +use_encryption = true + +[web02] +type = http +local_ip = 127.0.0.1 +local_port = 8001 +``` diff --git a/doc/quick_start_zh.md b/doc/quick_start_zh.md index e12e6d2..4b2c21d 100644 --- a/doc/quick_start_zh.md +++ b/doc/quick_start_zh.md @@ -1,6 +1,9 @@ # frp 使用文档 -frp 相比于其他项目而言非常易于部署和使用，这里我们用一个简单的示例演示如何通过一台拥有公网IP地址的服务器B，访问处于内网环境中的服务器A的ssh端口，服务器B的IP地址为 x.x.x.x（测试时替换为真实的IP地址）。 +相比于其他项目而言 frp 更易于部署和使用，这里我们用两个简单的示例来演示 frp 的使用过程。 + +1. 如何通过一台拥有公网IP地址的**服务器B**，访问处于公司内部网络环境中的**服务器A**的**ssh**端口，**服务器B**的IP地址为 x.x.x.x（测试时替换为真实的IP地址）。 +2. 如何利用一台拥有公网IP地址的**服务器B**，使通过 **web01.yourdomain.com** 可以访问内网环境中**服务器A**上**8000端口**的web服务，**web02.yourdomain.com** 可以访问**服务器A**上**8001端口**的web服务。 ### 下载源码 @@ -8,6 +11,8 @@ frp 相比于其他项目而言非常易于部署和使用，这里我们用一 或者可以使用 `git clone https://github.com/fatedier/frp.git $GOPATH/src/github.com/fatedier/frp` 拷贝到相应目录下。 +如果您想快速进行测试，也可以根据您服务器的操作系统及架构直接下载编译好的程序及示例配置文件，[https://github.com/fatedier/frp/releases](https://github.com/fatedier/frp/releases)。 + ### 编译 进入下载后的源码根目录，执行 `make` 命令，等待编译完成。 @@ -21,12 +26,16 @@ frp 相比于其他项目而言非常易于部署和使用，这里我们用一 ### 部署 -1. 将 ./bin/frps 和 ./conf/frps.ini 拷贝至服务器B任意目录。 -2. 将 ./bin/frpc 和 ./conf/frpc.ini 拷贝至服务器A任意目录。 -3. 修改两边的配置文件，见下一节说明。 +1. 将 ./bin/frps 和 ./conf/frps.ini 拷贝至**服务器B**任意目录。 +2. 将 ./bin/frpc 和 ./conf/frpc.ini 拷贝至**服务器A**任意目录。 +3. 根据要实现的功能修改两边的配置文件，详细内容见后续章节说明。 4. 在服务器B执行 `nohup ./frps &` 或者 `nohup ./frps -c ./frps.ini &`。 5. 在服务器A执行 `nohup ./frpc &` 或者 `nohup ./frpc -c ./frpc.ini &`。 -6. 通过 `ssh -oPort=6000 {user}@x.x.x.x` 测试是否能够成功连接服务器A（{user}替换为服务器A上存在的真实用户）。 +6. 通过 `ssh -oPort=6000 {user}@x.x.x.x` 测试是否能够成功连接**服务器A**（{user}替换为**服务器A**上存在的真实用户），或通过浏览器访问自定义域名验证 http 服务是否转发成功。 + +## tcp 端口转发 + +转发 tcp 端口需要按照需求修改 frps 和 frpc 的配置文件。 ### 配置文件 @@ -40,9 +49,9 @@ bind_port = 7000 log_file = ./frps.log log_level = info -# test 为代理的自定义名称，可以有多个，不能重复，和frpc中名称对应 +# ssh 为代理的自定义名称，可以有多个，不能重复，和frpc中名称对应 [ssh] -auth_token = 123 +auth_token = 123 bind_addr = 0.0.0.0 # 最后将通过此端口访问后端服务 listen_port = 6000 @@ -58,12 +67,71 @@ server_port = 7000 log_file = ./frpc.log log_level = info # 用于身份验证 -auth_token = 123 +auth_token = 123 -# test需要和 frps.ini 中配置一致 +# ssh 需要和 frps.ini 中配置一致 [ssh] # 需要转发的本地端口 local_port = 22 # 启用加密，frpc与frps之间通信加密，默认为 false use_encryption = true ``` + +## http 端口转发，绑定自定义域名 + +如果只需要一对一的转发，例如**服务器B**的**80端口**转发**服务器A**的**8000端口**，则只需要配置 [tcp 端口转发](doc/quick_start_zh.md#tcp-端口转发) 即可，如果需要使**服务器B**的**80端口**可以转发至**多个**web服务端口，则需要指定代理的类型为 http，并且在 frps 的配置文件中配置用于提供 http 转发服务的端口。 + +按照如下的内容修改配置文件后，需要将自定义域名的 **A 记录**解析到 [server_addr]，如果 [server_addr] 是域名也可以将自定义域名的 **CNAME 记录**解析到 [server_addr]。 + +之后就可以通过自定义域名访问到本地的多个 web 服务。 + +### 配置文件 + +#### frps.ini + +```ini +[common] +bind_addr = 0.0.0.0 +bind_port = 7000 +# 如果需要支持http类型的代理则需要指定一个端口 +vhost_http_port = 80 +log_file = ./frps.log +log_level = info + +[web01] +# type 默认为 tcp，这里需要特别指定为 http +type = http +auth_token = 123 +# 自定义域名绑定，如果需要同时绑定多个以英文逗号分隔 +custom_domains = web01.yourdomain.com + +[web02] +type = http +auth_token = 123 +custom_domains = web02.yourdomain.com +``` + +#### frpc.ini + +```ini +[common] +server_addr = x.x.x.x +server_port = 7000 +log_file = ./frpc.log +log_level = info +auth_token = 123 + + +# 自定义域名在 frps.ini 中配置，方便做统一管理 +[web01] +type = http +local_ip = 127.0.0.1 +local_port = 8000 +# 可选是否加密 +use_encryption = true + +[web02] +type = http +local_ip = 127.0.0.1 +local_port = 8001 +```