frp/README.md

846 lines
22 KiB
Markdown
Raw Normal View History

2015-12-21 23:25:54 +08:00
# frp
2017-05-19 02:59:51 +08:00
[![Build Status](https://travis-ci.org/fatedier/frp.svg?branch=master)](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?
2019-10-14 05:46:08 +08:00
frp is a fast reverse proxy to help you expose a local server behind a NAT or firewall to the Internet. As of now, it supports **TCP** and **UDP**, as well as **HTTP** and **HTTPS** protocols, where requests can be forwarded to internal services by domain name.
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
frp also has a P2P connect mode.
2019-01-15 11:27:53 +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 -->
2017-12-05 01:34:33 +08:00
2019-10-14 05:46:08 +08:00
* [Development Status](#development-status)
2016-07-11 23:35:34 +08:00
* [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)
2019-10-14 05:46:08 +08:00
* [Forward Unix domain socket](#forward-unix-domain-socket)
* [Expose a simple HTTP file server](#expose-a-simple-http-file-server)
2019-04-10 13:39:26 +08:00
* [Enable HTTPS for local HTTP service](#enable-https-for-local-http-service)
2019-10-14 05:46:08 +08:00
* [Expose your service privately](#expose-your-service-privately)
2017-12-05 01:34:33 +08:00
* [P2P Mode](#p2p-mode)
2016-07-11 23:35:34 +08:00
* [Features](#features)
2019-10-14 05:46:08 +08:00
* [Configuration Files](#configuration-files)
* [Using Environment Variables](#using-environment-variables)
2016-12-21 01:18:12 +08:00
* [Dashboard](#dashboard)
2019-03-11 16:24:54 +08:00
* [Admin UI](#admin-ui)
2019-10-14 05:46:08 +08:00
* [Authenticating the Client](#authenticating-the-client)
2016-12-21 01:18:12 +08:00
* [Encryption and Compression](#encryption-and-compression)
2019-03-11 16:24:54 +08:00
* [TLS](#tls)
2019-10-14 05:46:08 +08:00
* [Hot-Reloading frpc configuration](#hot-reloading-frpc-configuration)
2018-01-18 16:43:03 +08:00
* [Get proxy status from client](#get-proxy-status-from-client)
2019-10-14 05:46:08 +08:00
* [Only allowing certain ports on the server](#only-allowing-certain-ports-on-the-server)
2018-05-07 16:46:04 +08:00
* [Port Reuse](#port-reuse)
2017-05-18 19:08:43 +08:00
* [TCP Stream Multiplexing](#tcp-stream-multiplexing)
2017-06-14 01:23:34 +08:00
* [Support KCP Protocol](#support-kcp-protocol)
2019-10-14 05:46:08 +08:00
* [Connection Pooling](#connection-pooling)
2018-05-25 01:25:36 +08:00
* [Load balancing](#load-balancing)
2019-10-14 05:46:08 +08:00
* [Service Health Check](#service-health-check)
* [Rewriting the HTTP Host Header](#rewriting-the-http-host-header)
* [Setting other HTTP Headers](#setting-other-http-headers)
2017-07-17 00:57:10 +08:00
* [Get Real IP](#get-real-ip)
2019-04-10 13:39:26 +08:00
* [HTTP X-Forwarded-For](#http-x-forwarded-for)
* [Proxy Protocol](#proxy-protocol)
2019-10-14 05:46:08 +08:00
* [Require HTTP Basic auth (password) for web services](#require-http-basic-auth-password-for-web-services)
2016-12-21 01:18:12 +08:00
* [Custom subdomain names](#custom-subdomain-names)
2016-12-28 00:26:50 +08:00
* [URL routing](#url-routing)
2019-10-14 05:46:08 +08:00
* [Connecting to frps via HTTP PROXY](#connecting-to-frps-via-http-proxy)
2018-04-24 01:26:05 +08:00
* [Range ports mapping](#range-ports-mapping)
2019-10-14 05:46:08 +08:00
* [Plugins](#plugins)
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)
2017-06-12 01:31:33 +08:00
* [Wechat Pay](#wechat-pay)
2016-12-21 01:18:12 +08:00
* [Paypal](#paypal)
2016-03-14 15:26:26 +08:00
2016-12-21 01:18:12 +08:00
<!-- vim-markdown-toc -->
2019-10-14 05:46:08 +08:00
## Development Status
2016-03-14 15:26:26 +08:00
2019-10-14 05:46:08 +08:00
frp is under development. Try the latest release version in the `master` branch, or use the `dev` branch for the version in development.
2016-04-06 11:43:50 +08:00
2019-10-14 05:46:08 +08:00
**The protocol might change at a release and we don't promise backwards compatibility. Please check the release log when upgrading the client and the server.**
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
2019-10-14 05:46:08 +08:00
Firstly, download the latest programs from [Release](https://github.com/fatedier/frp/releases) page according to your operating system and architecture.
2016-03-14 15:26:26 +08:00
2019-10-14 05:46:08 +08:00
Put `frps` and `frps.ini` onto your server A with public IP.
2016-03-14 15:26:26 +08:00
2019-10-14 05:46:08 +08:00
Put `frpc` and `frpc.ini` onto your server B in LAN (that can't be connected from public Internet).
2016-07-11 23:31:35 +08:00
2017-05-18 19:08:43 +08:00
### Access your computer in LAN by SSH
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
1. Modify `frps.ini` on server A:
2016-07-11 23:31:35 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2019-10-14 05:46:08 +08:00
2. Start `frps` on server A:
2016-07-11 23:31:35 +08:00
`./frps -c ./frps.ini`
2019-10-14 05:46:08 +08:00
3. On server B, modify `frpc.ini` to put in your `frps` server public IP as `server_addr` field:
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
```
2019-10-14 05:46:08 +08:00
4. Start `frpc` on server B:
2016-07-11 23:31:35 +08:00
`./frpc -c ./frpc.ini`
2019-10-14 05:46:08 +08:00
5. From another machine, SSH to server B like this (assuming that username is `test`):
2016-07-11 23:31:35 +08:00
`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
2019-10-14 05:46:08 +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
2019-10-14 05:46:08 +08:00
However, we can expose an HTTP(S) service using frp.
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
1. Modify `frps.ini`, set the vhost HTTP port to 8080:
2016-07-11 23:31:35 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080
```
2019-10-14 05:46:08 +08:00
2. Start `frps`:
2016-07-11 23:31:35 +08:00
`./frps -c ./frps.ini`
2019-10-14 05:46:08 +08:00
3. Modify `frpc.ini` and set `server_addr` to the IP address of the remote frps server. 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
2019-10-14 05:46:08 +08:00
custom_domains = www.example.com
2016-07-11 23:31:35 +08:00
```
2019-10-14 05:46:08 +08:00
4. Start `frpc`:
2016-07-11 23:31:35 +08:00
`./frpc -c ./frpc.ini`
2019-10-14 05:46:08 +08:00
5. Resolve A record of `www.example.com` to the public IP of the remote frps server or CNAME record to your origin domain.
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
6. Now visit your local web service using url `http://www.example.com:8080`.
2016-07-11 23:31:35 +08:00
2016-12-21 01:18:12 +08:00
### Forward DNS query request
2019-10-14 05:46:08 +08:00
1. Modify `frps.ini`:
2016-12-21 01:18:12 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2019-10-14 05:46:08 +08:00
2. Start `frps`:
2016-12-21 01:18:12 +08:00
`./frps -c ./frps.ini`
2019-10-14 05:46:08 +08:00
3. Modify `frpc.ini` and set `server_addr` to the IP address of the remote frps server, forward DNS query request to Google Public DNS server `8.8.8.8:53`:
2016-12-21 01:18:12 +08:00
```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`
2019-10-14 05:46:08 +08:00
5. Test DNS resolution using `dig` command:
2016-12-21 01:18:12 +08:00
2017-09-26 21:06:28 +08:00
`dig @x.x.x.x -p 6000 www.google.com`
2016-12-21 01:18:12 +08:00
2019-10-14 05:46:08 +08:00
### Forward Unix domain socket
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
Expose a Unix domain socket (e.g. the Docker daemon socket) as TCP.
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
Configure `frps` same as above.
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
1. Start `frpc` with configuration:
2017-06-12 01:31:33 +08:00
```ini
2017-07-17 00:57:10 +08:00
# frpc.ini
2017-06-12 01:31:33 +08:00
[common]
2017-07-17 00:57:10 +08:00
server_addr = x.x.x.x
server_port = 7000
[unix_domain_socket]
type = tcp
remote_port = 6000
plugin = unix_domain_socket
plugin_unix_path = /var/run/docker.sock
2017-06-12 01:31:33 +08:00
```
2019-10-14 05:46:08 +08:00
2. Test: Get Docker version using `curl`:
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
`curl http://x.x.x.x:6000/version`
2019-10-14 05:46:08 +08:00
### Expose a simple HTTP file server
2018-01-24 23:27:03 +08:00
2019-10-14 05:46:08 +08:00
Browser your files stored in the LAN, from public Internet.
2018-01-24 23:27:03 +08:00
2019-10-14 05:46:08 +08:00
Configure `frps` same as above.
2018-01-24 23:27:03 +08:00
2019-10-14 05:46:08 +08:00
1. Start `frpc` with configuration:
2018-01-24 23:27:03 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_static_file]
type = tcp
remote_port = 6000
plugin = static_file
2019-10-14 05:46:08 +08:00
plugin_local_path = /tmp/files
2018-01-24 23:27:03 +08:00
plugin_strip_prefix = static
plugin_http_user = abc
plugin_http_passwd = abc
```
2019-10-14 05:46:08 +08:00
2. Visit `http://x.x.x.x:6000/static/` from your browser and specify correct user and password to view files in `/tmp/files` on the `frpc` machine.
2018-01-24 23:27:03 +08:00
2019-04-10 13:39:26 +08:00
### Enable HTTPS for local HTTP service
2019-10-14 05:46:08 +08:00
1. Start `frpc` with configuration:
2019-04-10 13:39:26 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
2019-10-14 05:46:08 +08:00
[test_https2http]
2019-04-10 13:39:26 +08:00
type = https
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
2019-04-10 13:39:26 +08:00
plugin = https2http
plugin_local_addr = 127.0.0.1:80
plugin_crt_path = ./server.crt
plugin_key_path = ./server.key
plugin_host_header_rewrite = 127.0.0.1
2019-08-14 20:44:44 +08:00
plugin_header_X-From-Where = frp
2019-04-10 13:39:26 +08:00
```
2019-10-14 05:46:08 +08:00
2. Visit `https://test.example.com`.
2019-04-10 13:39:26 +08:00
2019-10-14 05:46:08 +08:00
### Expose your service privately
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
Some services will be at risk if exposed directly to the public network. With **STCP** (secret TCP) mode, a preshared key is needed to access the service from another client.
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
Configure `frps` same as above.
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
1. Start `frpc` on machine B with the following config. This example is for exposing the SSH service (port 22), and note the `sk` field for the preshared key, and that the `remote_port` field is removed here:
2017-06-12 01:31:33 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
2017-07-17 00:57:10 +08:00
[secret_ssh]
type = stcp
sk = abcdefg
local_ip = 127.0.0.1
local_port = 22
2017-06-12 01:31:33 +08:00
```
2019-10-14 05:46:08 +08:00
2. Start another `frpc` (typically on another machine C) with the following config to access the SSH service with a security key (`sk` field):
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
2017-12-05 01:34:33 +08:00
[secret_ssh_visitor]
2017-07-17 00:57:10 +08:00
type = stcp
2017-12-05 01:34:33 +08:00
role = visitor
2017-07-17 00:57:10 +08:00
server_name = secret_ssh
sk = abcdefg
bind_addr = 127.0.0.1
bind_port = 6000
```
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
3. On machine C, connect to SSH on machine B, using this command:
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
`ssh -oPort=6000 127.0.0.1`
2017-06-12 01:31:33 +08:00
2017-12-05 01:34:33 +08:00
### P2P Mode
2019-10-14 05:46:08 +08:00
**xtcp** is designed for transmitting large amounts of data directly between clients. A frps server is still needed, as P2P here only refers the actual data transmission.
2017-12-05 01:34:33 +08:00
2019-10-14 05:46:08 +08:00
Note it can't penetrate all types of NAT devices. You might want to fallback to **stcp** if **xtcp** doesn't work.
2017-12-05 01:34:33 +08:00
2019-10-14 05:46:08 +08:00
1. In `frps.ini` configure a UDP port for xtcp:
2017-12-05 01:34:33 +08:00
```ini
2019-10-14 05:46:08 +08:00
# frps.ini
2017-12-05 01:34:33 +08:00
bind_udp_port = 7001
```
2019-10-14 05:46:08 +08:00
2. Start `frpc` on machine B, expose the SSH port. Note that `remote_port` field is removed:
2017-12-05 01:34:33 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[p2p_ssh]
type = xtcp
sk = abcdefg
local_ip = 127.0.0.1
local_port = 22
```
2019-10-14 05:46:08 +08:00
3. Start another `frpc` (typically on another machine C) with the config to connect to SSH using P2P mode:
2017-12-05 01:34:33 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[p2p_ssh_visitor]
type = xtcp
role = visitor
server_name = p2p_ssh
sk = abcdefg
bind_addr = 127.0.0.1
bind_port = 6000
```
2019-10-14 05:46:08 +08:00
4. On machine C, connect to SSH on machine B, using this command:
2017-12-05 01:34:33 +08:00
2019-10-14 05:46:08 +08:00
`ssh -oPort=6000 127.0.0.1`
2017-12-05 01:34:33 +08:00
2017-07-17 00:57:10 +08:00
## Features
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
### Configuration Files
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
Read the full example configuration files to find out even more features not described here.
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
[Full configuration file for frps (Server)](./conf/frps_full.ini)
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
[Full configuration file for frpc (Client)](./conf/frpc_full.ini)
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
### Using Environment Variables
2018-12-11 11:56:00 +08:00
2019-10-14 05:46:08 +08:00
Environment variables can be referenced in the configuration file, using Go's standard format:
2018-12-11 11:56:00 +08:00
```ini
# frpc.ini
[common]
server_addr = {{ .Envs.FRP_SERVER_ADDR }}
server_port = 7000
[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = {{ .Envs.FRP_SSH_REMOTE_PORT }}
```
2019-10-14 05:46:08 +08:00
With the config above, variables can be passed into `frpc` program like this:
2018-12-11 11:56:00 +08:00
```
export FRP_SERVER_ADDR="x.x.x.x"
export FRP_SSH_REMOTE_PORT="6000"
./frpc -c ./frpc.ini
```
2019-10-14 05:46:08 +08:00
`frpc` will render configuration file template using OS environment variables. Remember to prefix your reference with `.Envs`.
2018-12-11 11:56:00 +08:00
2016-08-12 12:50:12 +08:00
### Dashboard
2019-10-02 03:58:35 +08:00
Check frp's status and proxies' statistics information by Dashboard.
2016-08-12 12:50:12 +08:00
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
```
2019-10-14 05:46:08 +08:00
Then visit `http://[server_addr]:7500` to see the dashboard, with username and password both being `admin` by default.
2016-08-12 12:50:12 +08:00
![dashboard](/doc/pic/dashboard.png)
2019-03-11 16:24:54 +08:00
### Admin UI
2019-10-14 05:46:08 +08:00
The Admin UI helps you check and manage frpc's configuration.
2019-03-11 16:24:54 +08:00
2019-10-02 03:58:35 +08:00
Configure an address for admin UI to enable this feature:
2019-03-11 16:24:54 +08:00
```ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400
admin_user = admin
admin_pwd = admin
```
2019-10-14 05:46:08 +08:00
Then visit `http://127.0.0.1:7400` to see admin UI, with username and password both being `admin` by default.
2019-03-11 16:24:54 +08:00
2019-10-14 05:46:08 +08:00
### Authenticating the Client
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
Always use the same `token` in the `[common]` section in `frps.ini` and `frpc.ini`.
2016-07-11 23:31:35 +08:00
### Encryption and Compression
2019-10-14 05:46:08 +08:00
The features are off by default. You can turn on encryption and/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
```
2019-03-11 16:24:54 +08:00
#### TLS
2019-10-14 05:46:08 +08:00
frp supports the TLS protocol between `frpc` and `frps` since v0.25.0.
2019-03-11 16:24:54 +08:00
2019-10-14 05:46:08 +08:00
Config `tls_enable = true` in the `[common]` section to `frpc.ini` to enable this feature.
2019-03-11 16:24:54 +08:00
2019-10-14 05:46:08 +08:00
For port multiplexing, frp sends a first byte `0x17` to dial a TLS connection.
2019-03-11 16:24:54 +08:00
2019-10-14 05:46:08 +08:00
### Hot-Reloading frpc configuration
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
The `admin_addr` and `admin_port` fields are required for enabling HTTP API:
2017-07-17 00:57:10 +08:00
```ini
# frpc.ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400
```
2019-10-14 05:46:08 +08:00
Then run command `frpc reload -c ./frpc.ini` and wait for about 10 seconds to let `frpc` create or update or delete proxies.
2016-07-11 23:31:35 +08:00
2019-10-02 03:58:35 +08:00
**Note that parameters in [common] section won't be modified except 'start'.**
2016-07-11 23:31:35 +08:00
2018-01-18 16:43:03 +08:00
### Get proxy status from client
2019-10-14 05:46:08 +08:00
Use `frpc status -c ./frpc.ini` to get status of all proxies. The `admin_addr` and `admin_port` fields are required for enabling HTTP API.
2018-01-18 16:43:03 +08:00
2019-10-14 05:46:08 +08:00
### Only allowing certain ports on the server
2016-07-11 23:31:35 +08:00
2019-10-14 05:46:08 +08:00
`allow_ports` in `frps.ini` is used to avoid abuse of ports:
2016-08-12 12:50:12 +08:00
```ini
# frps.ini
[common]
2018-04-24 01:26:05 +08:00
allow_ports = 2000-3000,3001,3003,4000-50000
2016-08-12 12:50:12 +08:00
```
2019-10-14 05:46:08 +08:00
`allow_ports` consists of specific ports or port ranges (lowest port number, dash `-`, highest port number), separated by comma `,`.
2016-08-12 12:50:12 +08:00
2018-05-07 16:46:04 +08:00
### Port Reuse
2019-10-02 03:58:35 +08:00
`vhost_http_port` and `vhost_https_port` in frps can use same port with `bind_port`. frps will detect the connection's protocol and handle it correspondingly.
2018-05-07 16:46:04 +08:00
We would like to try to allow multiple proxies bind a same remote port with different protocols in the future.
2017-05-18 19:08:43 +08:00
### TCP Stream Multiplexing
2019-10-14 05:46:08 +08:00
frp supports tcp stream multiplexing since v0.10.0 like HTTP2 Multiplexing, in which case all logic connections to the same frpc are multiplexed into the same TCP connection.
2017-05-18 19:08:43 +08:00
2019-10-14 05:46:08 +08:00
You can disable this feature by modify `frps.ini` and `frpc.ini`:
2017-05-18 19:08:43 +08:00
```ini
# frps.ini and frpc.ini, must be same
[common]
tcp_mux = false
```
2017-06-14 01:23:34 +08:00
### Support KCP Protocol
KCP is a fast and reliable protocol that can achieve the transmission effect of a reduction of the average latency by 30% to 40% and reduction of the maximum delay by a factor of three, at the cost of 10% to 20% more bandwidth wasted than TCP.
2019-10-14 05:46:08 +08:00
KCP mode uses UDP as the underlying transport. Using KCP in frp:
2017-06-14 01:23:34 +08:00
2019-10-14 05:46:08 +08:00
1. Enable KCP in frps:
2017-06-14 01:23:34 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
2019-10-14 05:46:08 +08:00
# Specify a UDP port for KCP.
2017-06-14 01:23:34 +08:00
kcp_bind_port = 7000
```
2019-10-14 05:46:08 +08:00
The `kcp_bind_port` number can be the same number as `bind_port`, since `bind_port` field specifies a TCP port.
2. Configure `frpc.ini` to use KCP to connect to frps:
2017-06-14 01:23:34 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
2019-10-14 05:46:08 +08:00
# Same as the 'kcp_bind_port' in frps.ini
2017-06-14 01:23:34 +08:00
server_port = 7000
protocol = kcp
```
2019-10-14 05:46:08 +08:00
### Connection Pooling
2016-08-12 12:50:12 +08:00
2019-10-14 05:46:08 +08:00
By default, frps creates a new frpc connection to the backend service upon a user request. With connection pooling, frps keeps a certain number of pre-established connections, reducing the time needed to establish a connection.
2016-08-12 12:50:12 +08:00
2019-10-14 05:46:08 +08:00
This feature is suitable for a large number of short connections.
2016-08-12 12:50:12 +08:00
2019-10-14 05:46:08 +08:00
1. Configure the limit of pool count each proxy can use in `frps.ini`:
2016-08-12 12:50:12 +08:00
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
```
2018-05-25 01:25:36 +08:00
### Load balancing
Load balancing is supported by `group`.
2019-07-31 00:41:43 +08:00
2019-10-14 05:46:08 +08:00
This feature is only available for types `tcp` and `http` now.
2018-05-25 01:25:36 +08:00
```ini
# frpc.ini
[test1]
type = tcp
local_port = 8080
remote_port = 80
group = web
group_key = 123
[test2]
type = tcp
local_port = 8081
remote_port = 80
group = web
group_key = 123
```
`group_key` is used for authentication.
2019-10-14 05:46:08 +08:00
Connections to port 80 will be dispatched to proxies in the same group randomly.
2018-05-25 01:25:36 +08:00
2019-10-14 05:46:08 +08:00
For type `tcp`, `remote_port` in the same group should be the same.
2019-07-31 00:41:43 +08:00
2019-10-14 05:46:08 +08:00
For type `http`, `custom_domains`, `subdomain`, `locations` should be the same.
2019-07-31 00:41:43 +08:00
2019-10-14 05:46:08 +08:00
### Service Health Check
2019-01-15 11:27:53 +08:00
Health check feature can help you achieve high availability with load balancing.
2019-10-14 05:46:08 +08:00
Add `health_check_type = tcp` or `health_check_type = http` to enable health check.
2019-01-15 11:27:53 +08:00
2019-10-14 05:46:08 +08:00
With health check type **tcp**, the service port will be pinged (TCPing):
2019-01-15 11:27:53 +08:00
```ini
# frpc.ini
[test1]
type = tcp
local_port = 22
remote_port = 6000
2019-10-14 05:46:08 +08:00
# Enable TCP health check
2019-01-15 11:27:53 +08:00
health_check_type = tcp
2019-10-14 05:46:08 +08:00
# TCPing timeout seconds
2019-01-15 11:27:53 +08:00
health_check_timeout_s = 3
2019-10-14 05:46:08 +08:00
# If health check failed 3 times in a row, the proxy will be removed from frps
2019-01-15 11:27:53 +08:00
health_check_max_failed = 3
2019-10-14 05:46:08 +08:00
# A health check every 10 seconds
2019-01-15 11:27:53 +08:00
health_check_interval_s = 10
```
2019-10-14 05:46:08 +08:00
With health check type **http**, an HTTP request will be sent to the service and an HTTP 2xx OK response is expected:
2019-01-15 11:27:53 +08:00
```ini
# frpc.ini
[web]
type = http
local_ip = 127.0.0.1
local_port = 80
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
# Enable HTTP health check
2019-01-15 11:27:53 +08:00
health_check_type = http
2019-10-14 05:46:08 +08:00
# frpc will send a GET request to '/status'
# and expect an HTTP 2xx OK response
2019-01-15 11:27:53 +08:00
health_check_url = /status
health_check_timeout_s = 3
2019-10-14 05:46:08 +08:00
health_check_max_failed = 3
health_check_interval_s = 10
2019-01-15 11:27:53 +08:00
```
2019-10-14 05:46:08 +08:00
### Rewriting the HTTP Host Header
2016-08-12 12:50:12 +08:00
2019-10-14 05:46:08 +08:00
By default frp does not modify the tunneled HTTP requests at all as it's a byte-for-byte copy.
However, speaking of web servers and HTTP requests, your web server might rely on the `Host` HTTP header to determine the website to be accessed. frp can rewrite the `Host` header when forwarding the HTTP requests, with the `host_header_rewrite` field:
2016-08-12 12:50:12 +08:00
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
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
host_header_rewrite = dev.example.com
2016-08-12 12:50:12 +08:00
```
2019-10-14 05:46:08 +08:00
The HTTP request will have the the `Host` header rewritten to `Host: dev.example.com` when it reaches the actual web server, although the request from the browser probably has `Host: test.example.com`.
2018-05-20 23:41:15 +08:00
2019-10-14 05:46:08 +08:00
### Setting other HTTP Headers
2018-05-20 23:41:15 +08:00
2019-10-14 05:46:08 +08:00
Similar to `Host`, You can override other HTTP request headers with proxy type `http`.
2018-05-20 23:41:15 +08:00
```ini
# frpc.ini
[web]
type = http
local_port = 80
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
host_header_rewrite = dev.example.com
2018-05-20 23:41:15 +08:00
header_X-From-Where = frp
```
2019-10-14 05:46:08 +08:00
Note that parameter(s) prefixed with `header_` will be added to HTTP request headers.
In this example, it will set header `X-From-Where: frp` in the HTTP request.
2016-08-12 12:50:12 +08:00
2017-07-17 00:57:10 +08:00
### Get Real IP
2019-04-10 13:39:26 +08:00
#### HTTP X-Forwarded-For
2019-10-14 05:46:08 +08:00
This feature is for http proxy only.
2017-07-17 00:57:10 +08:00
2019-10-14 05:46:08 +08:00
You can get user's real IP from HTTP request headers `X-Forwarded-For` and `X-Real-IP`.
2019-04-10 13:39:26 +08:00
#### Proxy Protocol
2019-10-14 05:46:08 +08:00
frp supports Proxy Protocol to send user's real IP to local services. It support all types except UDP.
2019-04-10 13:39:26 +08:00
Here is an example for https service:
```ini
# frpc.ini
[web]
type = https
local_port = 443
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
2019-04-10 13:39:26 +08:00
2019-10-14 05:46:08 +08:00
# now v1 and v2 are supported
2019-04-10 13:39:26 +08:00
proxy_protocol_version = v2
```
2019-10-14 05:46:08 +08:00
You can enable Proxy Protocol support in nginx to expose user's real IP in HTTP header `X-Real-IP`, and then read `X-Real-IP` header in your web service for the real IP.
2019-04-10 13:39:26 +08:00
2019-10-14 05:46:08 +08:00
### Require HTTP Basic auth (password) for web services
2016-12-21 01:18:12 +08:00
Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password.
2019-10-14 05:46:08 +08:00
This enforces HTTP Basic Auth on all requests with the username and password specified in frpc's configure file.
2016-12-21 01:18:12 +08:00
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
2019-10-14 05:46:08 +08:00
custom_domains = test.example.com
2016-12-21 01:18:12 +08:00
http_user = abc
2018-11-16 12:53:35 +08:00
http_pwd = abc
2016-12-21 01:18:12 +08:00
```
2019-10-14 05:46:08 +08:00
Visit `http://test.example.com` in the browser and now you are prompted to enter the username and password.
2016-12-21 01:18:12 +08:00
### Custom subdomain names
2019-10-14 05:46:08 +08:00
It is convenient to use `subdomain` configure for http and https types when many people share one frps server.
2016-12-21 01:18:12 +08:00
```ini
# frps.ini
subdomain_host = frps.com
```
2019-10-14 05:46:08 +08:00
Resolve `*.frps.com` to the frps server's IP. This is usually called a Wildcard DNS record.
2016-12-21 01:18:12 +08:00
```ini
# frpc.ini
[web]
type = http
local_port = 80
subdomain = test
```
2019-10-14 05:46:08 +08:00
Now you can visit your web service on `test.frps.com`.
2016-12-21 01:18:12 +08:00
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
2019-10-14 05:46:08 +08:00
frp supports forwarding HTTP requests to different backend web services by url routing.
2016-12-28 00:26:50 +08:00
2019-10-14 05:46:08 +08:00
`locations` specifies 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.
2016-12-28 00:26:50 +08:00
```ini
# frpc.ini
[web01]
type = http
local_port = 80
2019-10-14 05:46:08 +08:00
custom_domains = web.example.com
2016-12-28 00:26:50 +08:00
locations = /
[web02]
type = http
local_port = 81
2019-10-14 05:46:08 +08:00
custom_domains = web.example.com
2016-12-28 00:26:50 +08:00
locations = /news,/about
```
2019-10-14 05:46:08 +08:00
HTTP requests with URL prefix `/news` or `/about` will be forwarded to **web02** and other requests to **web01**.
### Connecting to frps via HTTP PROXY
2016-12-21 01:18:12 +08:00
2019-10-14 05:46:08 +08:00
frpc can connect to frps using HTTP proxy if you set OS environment variable `HTTP_PROXY`, or if `http_proxy` is set in frpc.ini file.
2016-12-21 01:18:12 +08:00
2017-06-17 18:01:08 +08:00
It only works when protocol is tcp.
2016-12-21 01:18:12 +08:00
```ini
# frpc.ini
2017-06-12 01:31:33 +08:00
[common]
2016-12-21 01:18:12 +08:00
server_addr = x.x.x.x
server_port = 7000
http_proxy = http://user:pwd@192.168.1.128:8080
```
2018-01-29 23:05:17 +08:00
### Range ports mapping
2019-10-14 05:46:08 +08:00
Proxy with names that start with `range:` will support mapping range ports.
2018-01-29 23:05:17 +08:00
```ini
# frpc.ini
[range:test_tcp]
type = tcp
local_ip = 127.0.0.1
local_port = 6000-6006,6007
remote_port = 6000-6006,6007
```
2019-10-14 05:46:08 +08:00
frpc will generate 8 proxies like `test_tcp_0`, `test_tcp_1`, ..., `test_tcp_7`.
2018-01-29 23:05:17 +08:00
2019-10-14 05:46:08 +08:00
### Plugins
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
frpc only forwards requests to local TCP or UDP ports by default.
2017-06-12 01:31:33 +08:00
2019-10-02 03:58:35 +08:00
Plugins are used for providing rich features. There are built-in plugins such as `unix_domain_socket`, `http_proxy`, `socks5`, `static_file` and you can see [example usage](#example-usage).
2017-06-12 01:31:33 +08:00
2019-10-14 05:46:08 +08:00
Specify which plugin to use with the `plugin` parameter. Configuration parameters of plugin should be started with `plugin_`. `local_ip` and `local_port` are not used for plugin.
2017-06-12 01:31:33 +08:00
Using plugin **http_proxy**:
```ini
# frpc.ini
[http_proxy]
type = tcp
remote_port = 6000
plugin = http_proxy
plugin_http_user = abc
plugin_http_passwd = abc
```
`plugin_http_user` and `plugin_http_passwd` are configuration parameters used in `http_proxy` plugin.
2016-07-11 23:31:35 +08:00
## Development Plan
2019-10-14 05:46:08 +08:00
* Log HTTP request information in frps.
2017-05-18 19:08:43 +08:00
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.
2019-10-02 03:58:35 +08:00
* Sorry for my poor English. Improvements for this document are welcome, even some typo fixes.
* If you have great ideas, send an email to fatedier@gmail.com.
2016-04-06 11:43:50 +08:00
2019-10-02 03:58:35 +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 repeatedly.**
2016-06-03 18:15:01 +08:00
2016-08-24 13:36:38 +08:00
## Donation
2019-10-02 03:58:35 +08:00
If frp helps you a lot, you can support us by:
2016-08-24 13:36:38 +08:00
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)
2017-06-12 01:31:33 +08:00
### Wechat Pay
![donation-wechatpay](/doc/pic/donate-wechatpay.png)
2016-08-24 13:36:38 +08:00
### Paypal
Donate money by [paypal](https://www.paypal.me/fatedier) to my account **fatedier@gmail.com**.