frp/README.md

404 lines
11 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)
2017-05-18 19:08:43 +08:00
* [Access your computer in LAN by SSH](#access-your-computer-in-lan-by-ssh)
2016-12-21 01:18:12 +08:00
* [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)
2017-05-18 19:08:43 +08:00
* [TCP Stream Multiplexing](#tcp-stream-multiplexing)
2016-12-21 01:18:12 +08:00
* [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).
2017-05-18 19:08:43 +08:00
* Expose any tcp or udp service behind a NAT or firewall to the internet by a server with public IP address.
2016-04-19 18:53:48 +08:00
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.
2017-05-18 19:08:43 +08:00
### Access your computer in LAN by SSH
2016-07-11 23:31:35 +08:00
2017-05-18 19:08:43 +08:00
1. Modify frps.ini:
2016-07-11 23:31:35 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2. Start frps:
`./frps -c ./frps.ini`
2017-05-18 19:08:43 +08:00
3. Modify frpc.ini, `server_addr` is your frps's server IP:
2016-07-11 23:31:35 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[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
2017-05-18 19:08:43 +08:00
remote_port = 6000
2016-07-11 23:31:35 +08:00
```
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
2017-05-18 19:08:43 +08:00
1. Modify frps.ini, configure http port 8080:
2016-07-11 23:31:35 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080
```
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
[web]
type = http
local_port = 80
2017-05-18 19:08:43 +08:00
custom_domains = www.yourdomain.com
2016-07-11 23:31:35 +08:00
```
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
```
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
[dns]
type = udp
local_ip = 8.8.8.8
local_port = 53
2017-05-18 19:08:43 +08:00
remote_port = 6000
2016-12-21 01:18:12 +08:00
```
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
2017-05-18 19:08:43 +08:00
Since v0.10.0, you only need to set `privilege_token` in frps.ini and frpc.ini.
2016-07-11 23:31:35 +08:00
2017-05-18 19:08:43 +08:00
Note that time duration between server of 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
2017-05-18 19:08:43 +08:00
Defalut value is false, you could decide if the proxy will use encryption or compression:
2016-07-11 23:31:35 +08:00
```ini
# frpc.ini
[ssh]
type = tcp
2017-05-18 19:08:43 +08:00
local_port = 22
remote_port = 6000
2016-07-11 23:31:35 +08:00
use_encryption = true
2017-05-18 19:08:43 +08:00
use_compression = true
2016-07-11 23:31:35 +08:00
```
### Reload configures without frps stopped
2017-05-18 19:08:43 +08:00
This feature is removed since v0.10.0.
2016-07-11 23:31:35 +08:00
### Privilege Mode
2017-05-18 19:08:43 +08:00
Privilege mode is the default and only mode support in frp since v0.10.0. All proxy configurations are set in client.
2016-07-11 23:31:35 +08:00
2016-08-12 12:50:12 +08:00
#### Port White List
2017-05-18 19:08:43 +08:00
`privilege_allow_ports` in frps.ini is used for preventing abuse of ports:
2016-08-12 12:50:12 +08:00
```ini
# frps.ini
[common]
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
2017-05-18 19:08:43 +08:00
### 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
```
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:
2017-05-18 19:08:43 +08:00
```ini
2016-08-12 12:50:12 +08:00
# frps.ini
[common]
2017-05-18 19:08:43 +08:00
max_pool_count = 5
2016-08-12 12:50:12 +08:00
```
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
2017-05-18 19:08:43 +08:00
[common]
pool_count = 1
2016-08-12 12:50:12 +08:00
```
### 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.
2017-05-18 19:08:43 +08:00
```ini
# frpc.ini
2016-08-13 22:32:11 +08:00
[web]
2016-08-12 12:50:12 +08:00
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.
2017-05-18 19:08:43 +08:00
It can only be enabled when proxy type is http.
2016-12-21 01:18:12 +08:00
```ini
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
http_user = abc
http_pwd = abc
```
2017-05-18 19:08:43 +08:00
Visit `http://test.yourdomain.com` and now you need to input username and password.
2016-12-21 01:18:12 +08:00
### 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]
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]
type = http
local_port = 80
custom_domains = web.yourdomain.com
locations = /
[web02]
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.
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.
2017-05-18 19:08:43 +08:00
* Client Plugin (http proxy).
* kubernetes ingress support.
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**.