frp/README.md

487 lines
13 KiB
Markdown
Raw Normal View History

2015-12-21 23:25:54 +08:00
# frp
[![Build Status](https://travis-ci.org/fatedier/frp.svg)](https://travis-ci.org/fatedier/frp)
2016-04-06 11:43:50 +08:00
[README](README.md) | [中文文档](README_zh.md)
2016-03-14 15:26:26 +08:00
## What is frp?
2016-12-21 21:22:10 +08:00
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, udp, http and https protocol when requests can be forwarded by domains to backward web services.
2016-07-11 23:31:35 +08:00
2016-12-25 14:21:29 +08:00
## Table of Contents
2016-07-11 23:31:35 +08:00
2016-12-21 01:18:12 +08:00
<!-- vim-markdown-toc GFM -->
2016-07-11 23:35:34 +08:00
* [What can I do with frp?](#what-can-i-do-with-frp)
* [Status](#status)
* [Architecture](#architecture)
2016-08-13 22:32:11 +08:00
* [Example Usage](#example-usage)
2016-12-21 01:18:12 +08:00
* [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)
2016-07-11 23:35:34 +08:00
* [Features](#features)
2016-12-21 01:18:12 +08:00
* [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)
2016-12-28 00:26:50 +08:00
* [URL routing](#url-routing)
2016-12-21 01:18:12 +08:00
* [Connect frps by HTTP PROXY](#connect-frps-by-http-proxy)
2016-07-11 23:35:34 +08:00
* [Development Plan](#development-plan)
* [Contributing](#contributing)
2016-08-24 13:36:38 +08:00
* [Donation](#donation)
2016-12-21 01:18:12 +08:00
* [AliPay](#alipay)
* [Paypal](#paypal)
2016-03-14 15:26:26 +08:00
2016-12-21 01:18:12 +08:00
<!-- vim-markdown-toc -->
2016-04-19 18:53:48 +08:00
## What can I do with frp?
2016-07-11 23:31:35 +08:00
* 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).
2016-04-19 18:53:48 +08:00
* 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).
2016-03-14 15:26:26 +08:00
## Status
2016-08-13 22:32:11 +08:00
frp is under development and you can try it with latest release version. Master branch for releasing stable version when dev branch for developing.
2016-04-06 11:43:50 +08:00
2016-08-13 22:32:11 +08:00
**We may change any protocol and can't promise backward compatible. Please check the release log when upgrading.**
2016-03-14 15:26:26 +08:00
2016-07-11 23:31:35 +08:00
## Architecture
2016-03-14 15:26:26 +08:00
2016-07-11 23:31:35 +08:00
![architecture](/doc/pic/architecture.png)
2016-03-14 15:26:26 +08:00
2016-07-11 23:31:35 +08:00
## Example Usage
2016-03-14 15:26:26 +08:00
2016-08-12 13:44:25 +08:00
Firstly, download the latest programs from [Release](https://github.com/fatedier/frp/releases) page according to your os and arch.
2016-03-14 15:26:26 +08:00
2016-07-11 23:31:35 +08:00
Put **frps** and **frps.ini** to your server with public IP.
2016-03-14 15:26:26 +08:00
2016-07-11 23:31:35 +08:00
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]
2016-12-21 01:18:12 +08:00
type = tcp
local_ip = 127.0.0.1
2016-07-11 23:31:35 +08:00
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`
2016-08-12 13:44:25 +08:00
### Visit your web service in LAN by custom domains
2016-07-11 23:31:35 +08:00
2016-08-12 13:44:25 +08:00
Sometimes we want to expose a local web service behind a NAT network to others for testing with your own domain name and unfortunately we can't resolve a domain name to a local ip.
2016-07-11 23:31:35 +08:00
2016-12-21 21:22:10 +08:00
However, we can expose a http or https service using frp.
2016-07-11 23:31:35 +08:00
2016-08-12 13:44:25 +08:00
1. Modify frps.ini, configure a http reverse proxy named [web] and set http port as 8080, custom domain as `www.yourdomain.com`:
2016-07-11 23:31:35 +08:00
```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`
2016-08-12 13:44:25 +08:00
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:
2016-07-11 23:31:35 +08:00
```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`
2016-08-12 13:44:25 +08:00
5. Resolve A record of `www.yourdomain.com` to IP `x.x.x.x` or CNAME record to your origin domain.
2016-07-11 23:31:35 +08:00
2016-08-12 13:44:25 +08:00
6. Now visit your local web service using url `http://www.yourdomain.com:8080`.
2016-07-11 23:31:35 +08:00
2016-12-21 01:18:12 +08:00
### 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`
2016-07-11 23:31:35 +08:00
## Features
2016-08-12 12:50:12 +08:00
### Dashboard
Check frp's status and proxies's statistics information by Dashboard.
Configure a port for dashboard to enable this feature:
```ini
[common]
dashboard_port = 7500
2016-08-13 22:32:11 +08:00
# dashboard's username and password are both optionalif not set, default is admin.
2016-12-21 01:18:12 +08:00
dashboard_user = admin
dashboard_pwd = admin
2016-08-12 12:50:12 +08:00
```
2016-08-13 22:32:11 +08:00
Then visit `http://[server_addr]:7500` to see dashboard, default username and password are both `admin`.
2016-08-12 12:50:12 +08:00
![dashboard](/doc/pic/dashboard.png)
2016-07-11 23:31:35 +08:00
### Authentication
2016-08-12 13:44:25 +08:00
`auth_token` in frps.ini is configured for each proxy and check for authentication when frpc login in.
2016-07-11 23:31:35 +08:00
2016-08-12 13:44:25 +08:00
Client that want's to register must set a global `auth_token` equals to frps.ini.
2016-07-11 23:31:35 +08:00
2017-01-05 20:02:59 +08:00
Note that time duration between frpc and frps mustn't exceed 15 minutes because timestamp is used for authentication.
2016-07-11 23:31:35 +08:00
2016-12-21 01:18:12 +08:00
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.
2016-07-11 23:31:35 +08:00
### Encryption and Compression
2016-08-12 13:44:25 +08:00
Defalut value is false, you could decide if the proxy will use encryption or compression whether the type is:
2016-07-11 23:31:35 +08:00
```ini
# frpc.ini
[ssh]
type = tcp
listen_port = 6000
auth_token = 123
use_encryption = true
use_gzip = true
```
### Reload configures without frps stopped
2016-12-21 21:22:10 +08:00
If you want to add a new reverse proxy and avoid restarting frps, you can use this function:
2016-07-11 23:31:35 +08:00
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.
2016-08-12 13:44:25 +08:00
All proxies's configurations are set in frpc.ini when privilege mode is enabled.
2016-07-11 23:31:35 +08:00
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`
2016-08-12 13:44:25 +08:00
5. Connect to server in LAN by ssh assuming username is test:
2016-07-11 23:31:35 +08:00
`ssh -oPort=6000 test@x.x.x.x`
2016-08-12 12:50:12 +08:00
#### Port White List
`privilege_allow_ports` in frps.ini is used for preventing abuse of ports in privilege mode:
```ini
# frps.ini
[common]
privilege_mode = true
privilege_token = 1234
privilege_allow_ports = 2000-3000,3001,3003,4000-50000
```
2016-08-12 13:44:25 +08:00
`privilege_allow_ports` consists of a specific port or a range of ports divided by `,`.
2016-08-12 12:50:12 +08:00
### 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.
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:
```ini
# frps.ini
[common]
max_pool_count = 50
```
2. Enable and specify the number of connection pool:
2016-08-13 22:32:11 +08:00
```ini
2016-08-12 12:50:12 +08:00
# frpc.ini
2016-08-13 22:32:11 +08:00
[ssh]
2016-08-12 12:50:12 +08:00
type = tcp
local_port = 22
pool_count = 10
```
### 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.
```ini
# frpc.ini
2016-08-13 22:32:11 +08:00
[web]
2016-08-12 12:50:12 +08:00
privilege_mode = true
type = http
local_port = 80
custom_domains = test.yourdomain.com
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.
2016-12-21 01:18:12 +08:00
### 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`.
2016-12-28 00:26:50 +08:00
### URL routing
frp support forward http requests to different backward web services by url routing.
`locations` specify the prefix of URL used for routing. frps first searches for the most specific prefix location given by literal strings regardless of the listed order.
```ini
# frpc.ini
[web01]
privilege_mode = true
type = http
local_port = 80
custom_domains = web.yourdomain.com
locations = /
[web02]
privilege_mode = true
type = http
local_port = 81
custom_domains = web.yourdomain.com
locations = /news,/about
```
Http requests with url prefix `/news` and `/about` will be forwarded to **web02** and others to **web01**.
2016-12-21 01:18:12 +08:00
### 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
```
2016-07-11 23:31:35 +08:00
## Development Plan
2016-12-21 01:18:12 +08:00
* Log http request information in frps.
* Direct reverse proxy, like haproxy.
2016-07-11 23:31:35 +08:00
* 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.
2016-08-12 12:50:12 +08:00
* Frpc can directly be a webserver for static files.
* Full control mode, dynamically modify frpc's configure with dashboard in frps.
2016-07-11 23:31:35 +08:00
* P2p communicate by make udp hole to penetrate NAT.
2016-03-14 16:18:29 +08:00
## Contributing
2016-06-03 18:15:01 +08:00
Interested in getting involved? We would like to help you!
2016-03-14 16:18:29 +08:00
2016-08-21 00:52:15 +08:00
* Take a look at our [issues list](https://github.com/fatedier/frp/issues) and consider sending a Pull Request to **dev branch**.
* If you want to add a new feature, please create an issue first to describe the new feature, as well as the implementation approach. Once a proposal is accepted, create an implementation of the new features and submit it as a pull request.
* Sorry for my poor english and improvement for this document is welcome even some typo fix.
2016-04-06 11:51:12 +08:00
* If you have some wanderful ideas, send email to fatedier@gmail.com.
2016-04-06 11:43:50 +08:00
2016-06-03 18:15:01 +08:00
**Note: We prefer you to give your advise in [issues](https://github.com/fatedier/frp/issues), so others with a same question can search it quickly and we don't need to answer them repeatly.**
2016-08-24 13:36:38 +08:00
## Donation
If frp help you a lot, you can support us by:
2016-12-26 12:18:46 +08:00
frp QQ group: 606194980
2016-08-24 13:36:38 +08:00
### AliPay
![donation-alipay](/doc/pic/donate-alipay.png)
### Paypal
Donate money by [paypal](https://www.paypal.me/fatedier) to my account **fatedier@gmail.com**.