frp/README.md

847 lines
20 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?
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 & 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-02 03:58:35 +08:00
Now it also tries to support p2p connect.
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
2016-07-11 23:35:34 +08:00
* [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)
2017-06-12 01:31:33 +08:00
* [Forward unix domain socket](#forward-unix-domain-socket)
2018-01-24 23:27:03 +08:00
* [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)
2017-07-17 00:57:10 +08:00
* [Expose your service in security](#expose-your-service-in-security)
2017-12-05 01:34:33 +08:00
* [P2P Mode](#p2p-mode)
2016-07-11 23:35:34 +08:00
* [Features](#features)
2017-07-17 00:57:10 +08:00
* [Configuration File](#configuration-file)
2018-12-11 11:56:00 +08:00
* [Configuration file template](#configuration-file-template)
2016-12-21 01:18:12 +08:00
* [Dashboard](#dashboard)
2019-03-11 16:24:54 +08:00
* [Admin UI](#admin-ui)
2016-12-21 01:18:12 +08:00
* [Authentication](#authentication)
* [Encryption and Compression](#encryption-and-compression)
2019-03-11 16:24:54 +08:00
* [TLS](#tls)
2017-07-17 00:57:10 +08:00
* [Hot-Reload frpc configuration](#hot-reload-frpc-configuration)
2018-01-18 16:43:03 +08:00
* [Get proxy status from client](#get-proxy-status-from-client)
2018-04-24 01:26:05 +08:00
* [Port White List](#port-white-list)
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)
2016-12-21 01:18:12 +08:00
* [Connection Pool](#connection-pool)
2018-05-25 01:25:36 +08:00
* [Load balancing](#load-balancing)
2019-01-15 11:27:53 +08:00
* [Health Check](#health-check)
2016-12-21 01:18:12 +08:00
* [Rewriting the Host Header](#rewriting-the-host-header)
2018-05-20 23:41:15 +08:00
* [Set Headers In HTTP Request](#set-headers-in-http-request)
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)
2016-12-21 01:18:12 +08:00
* [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)
2018-04-24 01:26:05 +08:00
* [Range ports mapping](#range-ports-mapping)
2017-06-12 01:31:33 +08:00
* [Plugin](#plugin)
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 -->
2016-03-14 15:26:26 +08:00
## Status
2019-10-10 04:41:05 +08:00
frp is under development, you can try by using the latest release version under the 'master' branch. You can use the 'dev' branch instead for the version in development.
2016-04-06 11:43:50 +08:00
2019-08-27 11:17:43 +08:00
**We may change any protocol and can't promise backward compatibility. 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
2017-06-12 01:31:33 +08:00
1. Modify frps.ini:
2016-12-21 01:18:12 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2. Start frps:
`./frps -c ./frps.ini`
2019-10-02 03:58:35 +08:00
3. Modify frpc.ini, set remote frps's server IP as x.x.x.x, forward dns query request to Google's 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`
5. Send dns query request by dig:
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
2017-06-12 01:31:33 +08:00
### Forward unix domain socket
2019-10-02 03:58:35 +08:00
Use tcp port to connect to a unix domain socket (e.g. Docker daemon's socket).
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
Configure frps same as above.
1. Start frpc with configurations:
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
```
2017-07-17 00:57:10 +08:00
2. Get docker version by curl command:
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
`curl http://x.x.x.x:6000/version`
2018-01-24 23:27:03 +08:00
### Expose a simple http file server
2019-10-02 03:58:35 +08:00
A simple way to browse files in the LAN.
2018-01-24 23:27:03 +08:00
Configure frps same as above.
1. Start frpc with configurations:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_static_file]
type = tcp
remote_port = 6000
plugin = static_file
plugin_local_path = /tmp/file
plugin_strip_prefix = static
plugin_http_user = abc
plugin_http_passwd = abc
```
2019-10-02 03:58:35 +08:00
2. Visit `http://x.x.x.x:6000/static/` by your browser, specify correct user and password, so you can see files in `/tmp/file`.
2018-01-24 23:27:03 +08:00
2019-04-10 13:39:26 +08:00
### Enable HTTPS for local HTTP service
1. Start frpc with configurations:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_htts2http]
type = https
custom_domains = test.yourdomain.com
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
```
2. Visit `https://test.yourdomain.com`.
2017-07-17 00:57:10 +08:00
### Expose your service in security
2019-10-02 03:58:35 +08:00
Some services will be at risk if exposed directly to the public network.
2017-07-17 00:57:10 +08:00
2019-10-02 03:58:35 +08:00
**stcp(secret tcp)** helps you create a proxy while keeping the service secure.
2017-07-17 00:57:10 +08:00
Configure frps same as above.
2017-06-12 01:31:33 +08:00
2019-10-02 03:58:35 +08:00
1. Start frpc, forward ssh port and `remote_port` are useless:
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
```
2017-07-17 00:57:10 +08:00
2. Start another frpc in which you want to connect this ssh server:
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-02 03:58:35 +08:00
3. Connect to server in LAN using ssh assuming that username is test:
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
`ssh -oPort=6000 test@127.0.0.1`
2017-06-12 01:31:33 +08:00
2017-12-05 01:34:33 +08:00
### P2P Mode
**xtcp** is designed for transmitting a large amount of data directly between two client.
2019-10-02 03:58:35 +08:00
It can't penetrate all types of NAT devices. You can try **stcp** if **xtcp** doesn't work.
2017-12-05 01:34:33 +08:00
1. Configure a udp port for xtcp:
```ini
bind_udp_port = 7001
```
2019-10-02 03:58:35 +08:00
2. Start frpc, forward ssh port and `remote_port` are useless:
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
```
3. Start another frpc in which you want to connect this ssh server:
```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-02 03:58:35 +08:00
4. Connect to server in LAN using ssh assuming that username is test:
2017-12-05 01:34:33 +08:00
`ssh -oPort=6000 test@127.0.0.1`
2017-07-17 00:57:10 +08:00
## Features
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
### Configuration File
2017-06-12 01:31:33 +08:00
2019-10-02 03:58:35 +08:00
You can find features not mentioned in this document from the full example configuration files.
2017-07-17 00:57:10 +08:00
[frps full configuration file](./conf/frps_full.ini)
[frpc full configuration file](./conf/frpc_full.ini)
2016-07-11 23:31:35 +08:00
2018-12-11 11:56:00 +08:00
### Configuration file template
2019-10-02 03:58:35 +08:00
Configuration file template can be rendered using os environments. Template uses 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 }}
```
Start frpc program:
```
export FRP_SERVER_ADDR="x.x.x.x"
export FRP_SSH_REMOTE_PORT="6000"
./frpc -c ./frpc.ini
```
frpc will auto render configuration file template using os environments.
All environments has prefix `.Envs`.
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-02 03:58:35 +08:00
Then visit `http://[server_addr]:7500` to see the dashboard, default username and password are both `admin`.
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-02 03:58:35 +08:00
Admin UI help 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
```
Then visit `http://127.0.0.1:7400` to see admin UI, default username and password are both `admin`.
2016-07-11 23:31:35 +08:00
### Authentication
2019-10-02 03:58:35 +08:00
`token` in frps.ini and frpc.ini should be equal.
2016-07-11 23:31:35 +08:00
### Encryption and Compression
2019-10-02 03:58:35 +08:00
Default 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
```
2019-03-11 16:24:54 +08:00
#### TLS
2019-10-02 03:58:35 +08:00
frp supports TLS protocol between frpc and frps since v0.25.0.
2019-03-11 16:24:54 +08:00
Config `tls_enable = true` in `common` section to frpc.ini to enable this feature.
2019-10-02 03:58:35 +08:00
For port multiplexing, frp sends a first byte 0x17 to dial a TLS connection.
2019-03-11 16:24:54 +08:00
2017-07-17 00:57:10 +08:00
### Hot-Reload frpc configuration
First you need to set admin port in frpc's configure file to let it provide HTTP API for more features.
```ini
# frpc.ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400
```
2018-01-18 16:43:03 +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-02 03:58:35 +08:00
Use `frpc status -c ./frpc.ini` to get status of all proxies. You need to set admin port in frpc's configuration file.
2018-01-18 16:43:03 +08:00
2018-04-24 01:26:05 +08:00
### Port White List
2016-07-11 23:31:35 +08:00
2019-10-02 03:58:35 +08:00
`allow_ports` in frps.ini is used to prevent 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
```
2018-04-24 01:26:05 +08:00
`allow_ports` consists of a specific port or a range of ports divided by `,`.
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
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
```
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.
Using kcp in frp:
1. Enable kcp protocol in frps:
```ini
# frps.ini
[common]
bind_port = 7000
# kcp needs to bind a udp port, it can be same with 'bind_port'
kcp_bind_port = 7000
```
2019-10-02 03:58:35 +08:00
2. Configure the protocol used in frpc to connect to frps:
2017-06-14 01:23:34 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
# specify the 'kcp_bind_port' in frps
server_port = 7000
protocol = kcp
```
2016-08-12 12:50:12 +08:00
### Connection Pool
2019-10-02 03:58:35 +08:00
By default, frps sends a message to frpc to create a new connection to the backward service when getting a user request. If a proxy's connection pool is enabled, there will be a specified number of connections pre-established.
2016-08-12 12:50:12 +08:00
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
```
2018-05-25 01:25:36 +08:00
### Load balancing
Load balancing is supported by `group`.
2019-07-31 00:41:43 +08:00
This feature is available only for type `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.
Proxies in same group will accept connections from port 80 randomly.
2019-10-02 03:58:35 +08:00
For `tcp` type, `remote_port` in the same group should be same.
2019-07-31 00:41:43 +08:00
2019-10-02 03:58:35 +08:00
For `http` type, `custom_domains, subdomain, locations` should be same.
2019-07-31 00:41:43 +08:00
2019-01-15 11:27:53 +08:00
### Health Check
Health check feature can help you achieve high availability with load balancing.
Add `health_check_type = {type}` to enable health check.
**type** can be tcp or http.
2019-10-02 03:58:35 +08:00
Type tcp will dial the service port and type http will send a http request to the service and require a HTTP 200 response.
2019-01-15 11:27:53 +08:00
Type tcp configuration:
```ini
# frpc.ini
[test1]
type = tcp
local_port = 22
remote_port = 6000
# enable tcp health check
health_check_type = tcp
# dial timeout seconds
health_check_timeout_s = 3
2019-10-02 03:58:35 +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-02 03:58:35 +08:00
# health check every 10 seconds
2019-01-15 11:27:53 +08:00
health_check_interval_s = 10
```
Type http configuration:
```ini
# frpc.ini
[web]
type = http
local_ip = 127.0.0.1
local_port = 80
custom_domains = test.yourdomain.com
# enable http health check
health_check_type = http
# frpc will send a GET http request '/status' to local http service
# http service is alive when it return 2xx http response code
health_check_url = /status
health_check_interval_s = 10
health_check_max_failed = 3
health_check_timeout_s = 3
```
2016-08-12 12:50:12 +08:00
### Rewriting the Host Header
2018-05-20 23:41:15 +08:00
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.
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
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.com
```
The `Host` request header will be rewritten to `Host: dev.yourdomain.com` before it reach your local http server.
2018-05-20 23:41:15 +08:00
### Set Headers In HTTP Request
You can set headers for proxy which type is `http`.
```ini
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.com
header_X-From-Where = frp
```
2019-10-02 03:58:35 +08:00
Note that parameters that have `header_` prefix will be added to http request headers.
2018-05-20 23:41:15 +08:00
In this example, it will set header `X-From-Where: frp` to 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-02 03:58:35 +08:00
These features are for http proxy only.
2017-07-17 00:57:10 +08:00
2019-10-02 03:58:35 +08:00
You can get the user's real IP from HTTP request header `X-Forwarded-For` and `X-Real-IP`.
2019-04-10 13:39:26 +08:00
#### Proxy Protocol
2019-10-02 03:58:35 +08:00
frp support Proxy Protocol to send user's real IP to local service. 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
custom_domains = test.yourdomain.com
# now v1 and v2 is supported
proxy_protocol_version = v2
```
You can enable Proxy Protocol support in nginx to parse user's real IP to http header `X-Real-IP`.
Then you can get it from HTTP request header in your local service.
2017-07-17 00:57:10 +08:00
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
2018-11-16 12:53:35 +08:00
http_pwd = abc
2016-12-21 01:18:12 +08:00
```
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.
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-02 03:58:35 +08:00
Proxy name that has starts 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
```
2018-05-20 23:55:22 +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
2017-06-12 01:31:33 +08:00
### Plugin
2019-10-02 03:58:35 +08:00
frpc only forwards request to local tcp or udp port 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
Specify which plugin to use by `plugin` parameter. Configuration parameters of plugin should be started with `plugin_`. `local_ip` and `local_port` is useless for plugin.
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
2016-12-21 01:18:12 +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**.