Merge pull request #47 from fatedier/fatedier/update_doc

update README.md
This commit is contained in:
fatedier 2016-07-11 23:44:24 +08:00 committed by GitHub
commit fefc0a38c3
2 changed files with 232 additions and 14 deletions

241
README.md
View File

@ -6,11 +6,28 @@
## What is frp? ## What is frp?
frp is a fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet. frp is a fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet.Now, it supports tcp, http and https protocol when requests can be forwarded by domains to backward web services.
## 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 specific domain](#visit-your-web-service-in-lan-by-specific-domain)
* [Features](#features)
* [Authentication](#authentication)
* [Encryption and Compression](#encryption-and-compression)
* [Reload configures without frps stopped](#reload-configures-without-frps-stopped)
* [Privilege Mode](#privilege-mode)
* [Development Plan](#development-plan)
* [Contributing](#contributing)
* [Contributors](#contributors)
## What can I do with frp? ## 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 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 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). * Inspect all http requests/responses that are transmitted over the tunnel(future).
@ -18,20 +35,222 @@ 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. 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 before version 1.x.** **We may change any protocol and can't promise backward compatible.Please note the release log when upgrading.**
## Quick Start
Read the [QuickStart](/doc/quick_start_en.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
![architecture](/doc/pic/architecture.png) ![architecture](/doc/pic/architecture.png)
## Example Usage
First, download the latest version 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.
Put **frpc** and **frpc.ini** to your server in LAN.
### Communicate with your computer in LAN by SSH
1. Modify frps.ini, configure a reverse proxy named [ssh]:
```ini
# frps.ini
[common]
bind_port = 7000
[ssh]
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:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
auth_token = 123
[ssh]
local_port = 22
```
4. Start frpc:
`./frpc -c ./frpc.ini`
5. Connect to server in LAN by ssh assuming that username is test:
`ssh -oPort=6000 test@x.x.x.x`
### Visit your web service in LAN by specific domain
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.
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:
```ini
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080
[web]
type = http
custom_domains = www.yourdomain.com
auth_token = 123
```
2. Start frps:
`./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:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
auth_token = 123
[web]
type = http
local_port = 80
```
4. Start frpc:
`./frpc -c ./frpc.ini`
5. Resolve A record of www.yourdomain.com to 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`.
## Features
### Authentication
`auth_token` is used in frps.ini for authentication when frpc login in and you should configure it for each proxy.
Client should 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.
### Encryption and Compression
Defalut value is false, you could decide if the proxy should use encryption or compression whether the type is:
```ini
# frpc.ini
[ssh]
type = tcp
listen_port = 6000
auth_token = 123
use_encryption = true
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.
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 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.
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 that username is test:
`ssh -oPort=6000 test@x.x.x.x`
## 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.
* P2p communicate by make udp hole to penetrate NAT.
## Contributing ## Contributing
Interested in getting involved? We would like to help you! Interested in getting involved? We would like to help you!

View File

@ -178,12 +178,11 @@ reload 命令仅能用于修改代理的配置内容,[common] 内的公共配
`./frps -c ./frps.ini` `./frps -c ./frps.ini`
3. 修改 frpc.ini 增加一个新的代理 [new_ssh] 3. 修改 frps.ini 增加一个新的代理 [new_ssh]:
```ini ```ini
# frpc.ini # frps.ini
[common] [common]
server_addr = x.x.x.x
bind_port = 7000 bind_port = 7000
dashboard_port = 7500 dashboard_port = 7500