doc: update

This commit is contained in:
fatedier 2017-05-18 19:08:43 +08:00
parent 3fe50df200
commit c67f9d5e76
4 changed files with 56 additions and 136 deletions

View File

@ -1,21 +1,26 @@
Issue is only used for submiting bug report and documents typo. If there are same issues or answers can be found in documents, we will close it directly. Issue is only used for submiting bug report and documents typo. If there are same issues or answers can be found in documents, we will close it directly.
Please answer these questions before submitting your issue. Thanks! Use the commands below to provide key information from your environment:
You do NOT have to include this information if this is a FEATURE REQUEST
1. What did you do? **What version of frp are you using (./frpc -v or ./frps -v)?**
If possible, provide a recipe for reproducing the error.
2. What did you expect to see? **What operating system and processor architecture are you using (`go env`)?**
**Steps to reproduce the issue:**
1.
2.
3.
3. What did you see instead? **Describe the results you received:**
**Describe the results you expected:**
4. What version of frp are you using (./frpc -v or ./frps -v)?
**Additional information you deem important (e.g. issue happens only occasionally):**
5. Can you point out what caused this issue (optional)?
**Can you point out what caused this issue (optional)**

167
README.md
View File

@ -15,7 +15,7 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
* [Status](#status) * [Status](#status)
* [Architecture](#architecture) * [Architecture](#architecture)
* [Example Usage](#example-usage) * [Example Usage](#example-usage)
* [Communicate with your computer in LAN by SSH](#communicate-with-your-computer-in-lan-by-ssh) * [Access your computer in LAN by SSH](#access-your-computer-in-lan-by-ssh)
* [Visit your web service in LAN by custom domains](#visit-your-web-service-in-lan-by-custom-domains) * [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 DNS query request](#forward-dns-query-request)
* [Features](#features) * [Features](#features)
@ -25,6 +25,7 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
* [Reload configures without frps stopped](#reload-configures-without-frps-stopped) * [Reload configures without frps stopped](#reload-configures-without-frps-stopped)
* [Privilege Mode](#privilege-mode) * [Privilege Mode](#privilege-mode)
* [Port White List](#port-white-list) * [Port White List](#port-white-list)
* [TCP Stream Multiplexing](#tcp-stream-multiplexing)
* [Connection Pool](#connection-pool) * [Connection Pool](#connection-pool)
* [Rewriting the Host Header](#rewriting-the-host-header) * [Rewriting the Host Header](#rewriting-the-host-header)
* [Password protecting your web service](#password-protecting-your-web-service) * [Password protecting your web service](#password-protecting-your-web-service)
@ -42,8 +43,7 @@ frp is a fast reverse proxy to help you expose a local server behind a NAT or fi
## What can I do with frp? ## 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). * 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).
* Expose any tcp service behind a NAT or firewall to the internet by a server with public IP address. * Expose any tcp or udp 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 ## Status
@ -63,37 +63,33 @@ Put **frps** and **frps.ini** to your server with public IP.
Put **frpc** and **frpc.ini** to your server in LAN. Put **frpc** and **frpc.ini** to your server in LAN.
### Communicate with your computer in LAN by SSH ### Access your computer in LAN by SSH
1. Modify frps.ini, configure a reverse proxy named [ssh]: 1. Modify frps.ini:
```ini ```ini
# frps.ini # frps.ini
[common] [common]
bind_port = 7000 bind_port = 7000
[ssh]
listen_port = 6000
auth_token = 123
``` ```
2. Start frps: 2. Start frps:
`./frps -c ./frps.ini` `./frps -c ./frps.ini`
3. Modify frpc.ini, set remote frps's server IP as x.x.x.x: 3. Modify frpc.ini, `server_addr` is your frps's server IP:
```ini ```ini
# frpc.ini # frpc.ini
[common] [common]
server_addr = x.x.x.x server_addr = x.x.x.x
server_port = 7000 server_port = 7000
auth_token = 123
[ssh] [ssh]
type = tcp type = tcp
local_ip = 127.0.0.1 local_ip = 127.0.0.1
local_port = 22 local_port = 22
remote_port = 6000
``` ```
4. Start frpc: 4. Start frpc:
@ -110,18 +106,13 @@ Sometimes we want to expose a local web service behind a NAT network to others f
However, we can expose a http or https service using frp. However, 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 http port 8080:
```ini ```ini
# frps.ini # frps.ini
[common] [common]
bind_port = 7000 bind_port = 7000
vhost_http_port = 8080 vhost_http_port = 8080
[web]
type = http
custom_domains = www.yourdomain.com
auth_token = 123
``` ```
2. Start frps: 2. Start frps:
@ -135,11 +126,11 @@ However, we can expose a http or https service using frp.
[common] [common]
server_addr = x.x.x.x server_addr = x.x.x.x
server_port = 7000 server_port = 7000
auth_token = 123
[web] [web]
type = http type = http
local_port = 80 local_port = 80
custom_domains = www.yourdomain.com
``` ```
4. Start frpc: 4. Start frpc:
@ -158,11 +149,6 @@ However, we can expose a http or https service using frp.
# frps.ini # frps.ini
[common] [common]
bind_port = 7000 bind_port = 7000
[dns]
type = udp
listen_port = 6000
auth_token = 123
``` ```
2. Start frps: 2. Start frps:
@ -176,12 +162,12 @@ However, we can expose a http or https service using frp.
[common] [common]
server_addr = x.x.x.x server_addr = x.x.x.x
server_port = 7000 server_port = 7000
auth_token = 123
[dns] [dns]
type = udp type = udp
local_ip = 8.8.8.8 local_ip = 8.8.8.8
local_port = 53 local_port = 53
remote_port = 6000
``` ```
4. Start frpc: 4. Start frpc:
@ -214,121 +200,58 @@ Then visit `http://[server_addr]:7500` to see dashboard, default username and pa
### Authentication ### Authentication
`auth_token` in frps.ini is configured for each proxy and check for authentication when frpc login in. Since v0.10.0, you only need to set `privilege_token` in frps.ini and frpc.ini.
Client that want's to register must set a global `auth_token` equals to frps.ini. Note that time duration between server of frpc and frps mustn't exceed 15 minutes because timestamp is used for authentication.
Note that time duration between 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. 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 ### Encryption and Compression
Defalut value is false, you could decide if the proxy will use encryption or compression whether the type is: Defalut value is false, you could decide if the proxy will use encryption or compression:
```ini ```ini
# frpc.ini # frpc.ini
[ssh] [ssh]
type = tcp type = tcp
listen_port = 6000 local_port = 22
auth_token = 123 remote_port = 6000
use_encryption = true use_encryption = true
use_gzip = true use_compression = true
``` ```
### Reload configures without frps stopped ### Reload configures without frps stopped
If you want to add a new reverse proxy and avoid restarting frps, you can use this function: This feature is removed since v0.10.0.
1. `dashboard_port` should be set in frps.ini:
```ini
# frps.ini
[common]
bind_port = 7000
dashboard_port = 7500
```
2. Start frps:
`./frps -c ./frps.ini`
3. Modify frps.ini to add a new proxy [new_ssh]:
```ini
# frps.ini
[common]
bind_port = 7000
dashboard_port = 7500
[new_ssh]
listen_port = 6001
auth_token = 123
```
4. Execute `reload` command:
`./frps -c ./frps.ini --reload`
5. Start frpc and [new_ssh] is available now.
### Privilege Mode ### Privilege Mode
Privilege mode is used for who don't want to do operations in frps everytime adding a new proxy. Privilege mode is the default and only mode support in frp since v0.10.0. All proxy configurations are set in client.
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:
```ini
# frps.ini
[common]
bind_port = 7000
privilege_mode = true
privilege_token = 1234
```
2. Start frps:
`./frps -c ./frps.ini`
3. Enable privilege mode for proxy [ssh]:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
privilege_token = 1234
[ssh]
privilege_mode = true
local_port = 22
remote_port = 6000
```
4. Start frpc:
`./frpc -c ./frpc.ini`
5. Connect to server in LAN by ssh assuming username is test:
`ssh -oPort=6000 test@x.x.x.x`
#### Port White List #### Port White List
`privilege_allow_ports` in frps.ini is used for preventing abuse of ports in privilege mode: `privilege_allow_ports` in frps.ini is used for preventing abuse of ports:
```ini ```ini
# frps.ini # frps.ini
[common] [common]
privilege_mode = true
privilege_token = 1234
privilege_allow_ports = 2000-3000,3001,3003,4000-50000 privilege_allow_ports = 2000-3000,3001,3003,4000-50000
``` ```
`privilege_allow_ports` consists of a specific port or a range of ports divided by `,`. `privilege_allow_ports` consists of a specific port or a range of ports divided by `,`.
### TCP Stream Multiplexing
frp support tcp stream multiplexing since v0.10.0 like HTTP2 Multiplexing. All user requests to same frpc can use only one tcp connection.
You can disable this feature by modify frps.ini and frpc.ini:
```ini
# frps.ini and frpc.ini, must be same
[common]
tcp_mux = false
```
### Connection Pool ### 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. 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.
@ -337,30 +260,27 @@ 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: 1. Configure the limit of pool count each proxy can use in frps.ini:
```ini ```ini
# frps.ini # frps.ini
[common] [common]
max_pool_count = 50 max_pool_count = 5
``` ```
2. Enable and specify the number of connection pool: 2. Enable and specify the number of connection pool:
```ini ```ini
# frpc.ini # frpc.ini
[ssh] [common]
type = tcp pool_count = 1
local_port = 22
pool_count = 10
``` ```
### Rewriting the Host Header ### 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. 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 ```ini
# frpc.ini # frpc.ini
[web] [web]
privilege_mode = true
type = http type = http
local_port = 80 local_port = 80
custom_domains = test.yourdomain.com custom_domains = test.yourdomain.com
@ -375,12 +295,11 @@ Anyone who can guess your tunnel URL can access your local web server unless you
This enforces HTTP Basic Auth on all requests with the username and password you specify in frpc's configure file. 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. It can only be enabled when proxy type is http.
```ini ```ini
# frpc.ini # frpc.ini
[web] [web]
privilege_mode = true
type = http type = http
local_port = 80 local_port = 80
custom_domains = test.yourdomain.com custom_domains = test.yourdomain.com
@ -388,7 +307,7 @@ http_user = abc
http_pwd = abc http_pwd = abc
``` ```
Visit `test.yourdomain.com` and now you need to input username and password. Visit `http://test.yourdomain.com` and now you need to input username and password.
### Custom subdomain names ### Custom subdomain names
@ -404,7 +323,6 @@ Resolve `*.frps.com` to the frps server's IP.
```ini ```ini
# frpc.ini # frpc.ini
[web] [web]
privilege_mode = true
type = http type = http
local_port = 80 local_port = 80
subdomain = test subdomain = test
@ -423,14 +341,12 @@ frp support forward http requests to different backward web services by url rout
```ini ```ini
# frpc.ini # frpc.ini
[web01] [web01]
privilege_mode = true
type = http type = http
local_port = 80 local_port = 80
custom_domains = web.yourdomain.com custom_domains = web.yourdomain.com
locations = / locations = /
[web02] [web02]
privilege_mode = true
type = http type = http
local_port = 81 local_port = 81
custom_domains = web.yourdomain.com custom_domains = web.yourdomain.com
@ -454,11 +370,12 @@ http_proxy = http://user:pwd@192.168.1.128:8080
* Log http request information in frps. * Log http request information in frps.
* Direct reverse proxy, like haproxy. * Direct reverse proxy, like haproxy.
* Load balance to different service in frpc. * 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. * Frpc can directly be a webserver for static files.
* Full control mode, dynamically modify frpc's configure with dashboard in frps. * Full control mode, dynamically modify frpc's configure with dashboard in frps.
* P2p communicate by make udp hole to penetrate NAT. * P2p communicate by make udp hole to penetrate NAT.
* Client Plugin (http proxy).
* kubernetes ingress support.
## Contributing ## Contributing

View File

@ -87,6 +87,7 @@ master 分支用于发布稳定版本dev 分支用于开发,您可以尝试
server_port = 7000 server_port = 7000
[ssh] [ssh]
type = tcp
local_ip = 127.0.0.1 local_ip = 127.0.0.1
local_port = 22 local_port = 22
remote_port = 6000 remote_port = 6000
@ -162,7 +163,6 @@ DNS 查询请求通常使用 UDP 协议frp 支持对内网 UDP 服务的穿
[common] [common]
server_addr = x.x.x.x server_addr = x.x.x.x
server_port = 7000 server_port = 7000
auth_token = 123
[dns] [dns]
type = udp type = udp
@ -263,8 +263,6 @@ tcp_mux = false
这一功能比较适合有大量短连接请求时开启。 这一功能比较适合有大量短连接请求时开启。
**由于从 v0.10.0 版本开始支持了 tcp 连接的多路复用,如果启用了 tcp 的多路复用功能,则不再需要使用此功能或者连接池数量设置为 1 即可。**
1. 首先可以在 frps.ini 中设置每个代理可以创建的连接池上限,避免大量资源占用,客户端设置超过此配置后会被调整到当前值: 1. 首先可以在 frps.ini 中设置每个代理可以创建的连接池上限,避免大量资源占用,客户端设置超过此配置后会被调整到当前值:
```ini ```ini

Binary file not shown.

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 31 KiB