frp/README.md

973 lines
26 KiB
Markdown
Raw Normal View History

2015-12-21 23:25:54 +08:00
# frp
2020-12-03 20:41:37 +08:00
[![Build Status](https://circleci.com/gh/fatedier/frp.svg?style=shield)](https://circleci.com/gh/fatedier/frp)
2020-05-24 14:05:31 +08:00
[![GitHub release](https://img.shields.io/github/tag/fatedier/frp.svg?label=release)](https://github.com/fatedier/frp/releases)
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)
2020-03-11 14:13:16 +08:00
* [Monitor](#monitor)
* [Prometheus](#prometheus)
2019-10-14 05:46:08 +08:00
* [Authenticating the Client](#authenticating-the-client)
2020-03-11 14:13:16 +08:00
* [Token Authentication](#token-authentication)
* [OIDC Authentication](#oidc-authentication)
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)
2019-11-26 10:23:37 +08:00
* [Bandwidth Limit](#bandwidth-limit)
* [For Each Proxy](#for-each-proxy)
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)
2020-03-11 14:13:16 +08:00
* [Require HTTP Basic Auth (Password) for Web Services](#require-http-basic-auth-password-for-web-services)
* [Custom Subdomain Names](#custom-subdomain-names)
* [URL Routing](#url-routing)
* [TCP Port Multiplexing](#tcp-port-multiplexing)
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)
2020-01-03 11:35:12 +08:00
* [Client Plugins](#client-plugins)
* [Server Manage Plugins](#server-manage-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
1. Modify `frps.ini` on server A and set the `bind_port` to be connected to frp clients:
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
```
Note that `local_port` (listened on client) and `remote_port` (exposed on server) are for traffic goes in/out the frp system, whereas `server_port` is used between frps.
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
2020-03-11 14:13:16 +08:00
### Monitor
When dashboard is enabled, frps will save monitor data in cache. It will be cleared after process restart.
Prometheus is also supported.
#### Prometheus
Enable dashboard first, then configure `enable_prometheus = true` in `frps.ini`.
`http://{dashboard_addr}/metrics` will provide prometheus monitor data.
2019-10-14 05:46:08 +08:00
### Authenticating the Client
2016-07-11 23:31:35 +08:00
There are 2 authentication methods to authenticate frpc with frps.
You can decide which one to use by configuring `authentication_method` under `[common]` in `frpc.ini` and `frps.ini`.
Configuring `authenticate_heartbeats = true` under `[common]` will use the configured authentication method to add and validate authentication on every heartbeat between frpc and frps.
Configuring `authenticate_new_work_conns = true` under `[common]` will do the same for every new work connection between frpc and frps.
#### Token Authentication
When specifying `authentication_method = token` under `[common]` in `frpc.ini` and `frps.ini` - token based authentication will be used.
Make sure to specify the same `token` in the `[common]` section in `frps.ini` and `frpc.ini` for frpc to pass frps validation
#### OIDC Authentication
When specifying `authentication_method = oidc` under `[common]` in `frpc.ini` and `frps.ini` - OIDC based authentication will be used.
OIDC stands for OpenID Connect, and the flow used is called [Client Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.4).
To use this authentication type - configure `frpc.ini` and `frps.ini` as follows:
```ini
# frps.ini
[common]
authentication_method = oidc
oidc_issuer = https://example-oidc-issuer.com/
oidc_audience = https://oidc-audience.com/.default
```
```ini
# frpc.ini
[common]
authentication_method = oidc
oidc_client_id = 98692467-37de-409a-9fac-bb2585826f18 # Replace with OIDC client ID
oidc_client_secret = oidc_secret
oidc_audience = https://oidc-audience.com/.default
oidc_token_endpoint_url = https://example-oidc-endpoint.com/oauth2/v2.0/token
```
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
2020-02-11 01:01:23 +08:00
To enforce `frps` to only accept TLS connections - configure `tls_only = true` in the `[common]` section in `frps.ini`.
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.
2019-11-26 10:23:37 +08:00
### Bandwidth Limit
#### For Each Proxy
```ini
# frpc.ini
[ssh]
type = tcp
local_port = 22
remote_port = 6000
bandwidth_limit = 1MB
```
Set `bandwidth_limit` in each proxy's configure to enable this feature. Supported units are `MB` and `KB`.
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
### 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
2016-12-21 01:18:12 +08:00
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`.
### URL Routing
2016-12-28 00:26:50 +08:00
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**.
2020-03-11 14:13:16 +08:00
### TCP Port Multiplexing
frp supports receiving TCP sockets directed to different proxies on a single port on frps, similar to `vhost_http_port` and `vhost_https_port`.
2020-03-11 14:13:16 +08:00
The only supported TCP port multiplexing method available at the moment is `httpconnect` - HTTP CONNECT tunnel.
When setting `tcpmux_httpconnect_port` to anything other than 0 in frps under `[common]`, frps will listen on this port for HTTP CONNECT requests.
The host of the HTTP CONNECT request will be used to match the proxy in frps. Proxy hosts can be configured in frpc by configuring `custom_domain` and / or `subdomain` under `type = tcpmux` proxies, when `multiplexer = httpconnect`.
For example:
```ini
# frps.ini
[common]
bind_port = 7000
tcpmux_httpconnect_port = 1337
```
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[proxy1]
type = tcpmux
multiplexer = httpconnect
custom_domains = test1
[proxy2]
type = tcpmux
multiplexer = httpconnect
custom_domains = test2
```
In the above configuration - frps can be contacted on port 1337 with a HTTP CONNECT header such as:
```
CONNECT test1 HTTP/1.1\r\n\r\n
```
and the connection will be routed to `proxy1`.
2019-10-14 05:46:08 +08:00
### 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
2020-01-03 11:35:12 +08:00
### Client 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.
2020-01-03 11:35:12 +08:00
### Server Manage Plugins
Read the [document](/doc/server_plugin.md).
2020-03-20 20:54:22 +08:00
Find more plugins in [gofrp/plugin](https://github.com/gofrp/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**.