fatedie/frp

frp
Build Status GitHub release

README | 中文文档

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 and UDP, as well as HTTP and HTTPS protocols, where requests can be forwarded to internal services by domain name.

frp also has a P2P connect mode.

Table of Contents
Development Status
Architecture
Example Usage
Access your computer in LAN by SSH
Visit your web service in LAN by custom domains
Forward DNS query request
Forward Unix domain socket
Expose a simple HTTP file server
Enable HTTPS for local HTTP service
Expose your service privately
P2P Mode
Features
Configuration Files
Using Environment Variables
Dashboard
Admin UI
Monitor
Prometheus
Authenticating the Client
Token Authentication
OIDC Authentication
Encryption and Compression
TLS
Hot-Reloading frpc configuration
Get proxy status from client
Only allowing certain ports on the server
Port Reuse
Bandwidth Limit
For Each Proxy
TCP Stream Multiplexing
Support KCP Protocol
Connection Pooling
Load balancing
Service Health Check
Rewriting the HTTP Host Header
Setting other HTTP Headers
Get Real IP
HTTP X-Forwarded-For
Proxy Protocol
Require HTTP Basic Auth (Password) for Web Services
Custom Subdomain Names
URL Routing
TCP Port Multiplexing
Connecting to frps via HTTP PROXY
Range ports mapping
Client Plugins
Server Manage Plugins
Development Plan
Contributing
Donation
AliPay
Wechat Pay
Paypal
Development Status
frp is under development. Try the latest release version in the master branch, or use the dev branch for the version in development.

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.

Architecture
architecture

Example Usage
Firstly, download the latest programs from Release page according to your operating system and architecture.

Put frps and frps.ini onto your server A with public IP.

Put frpc and frpc.ini onto your server B in LAN (that can’t be connected from public Internet).

Access your computer in LAN by SSH
Modify frps.ini on server A and set the bind_port to be connected to frp clients:

frps.ini

[common]
bind_port = 7000
Start frps on server A:
./frps -c ./frps.ini

On server B, modify frpc.ini to put in your frps server public IP as server_addr field:

frpc.ini

[common]
server_addr = x.x.x.x
server_port = 7000

[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000
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.

Start frpc on server B:
./frpc -c ./frpc.ini

From another machine, SSH to server B like this (assuming that username is test):
ssh -oPort=6000 test@x.x.x.x

Visit your web service in LAN by custom domains
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.

However, we can expose an HTTP(S) service using frp.

Modify frps.ini, set the vhost HTTP port to 8080:

frps.ini

[common]
bind_port = 7000
vhost_http_port = 8080
Start frps:
./frps -c ./frps.ini

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:

frpc.ini

[common]
server_addr = x.x.x.x
server_port = 7000

[web]
type = http
local_port = 80
custom_domains = www.example.com
Start frpc:
./frpc -c ./frpc.ini

Resolve A record of www.example.com to the public IP of the remote frps server or CNAME record to your origin domain.

Now visit your local web service using url http://www.example.com:8080.

Forward DNS query request
Modify frps.ini:

frps.ini

[common]
bind_port = 7000
Start frps:
./frps -c ./frps.ini

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:

frpc.ini

[common]
server_addr = x.x.x.x
server_port = 7000

[dns]
type = udp
local_ip = 8.8.8.8
local_port = 53
remote_port = 6000
Start frpc:
./frpc -c ./frpc.ini

Test DNS resolution using dig command:
dig @x.x.x.x -p 6000 www.google.com

Forward Unix domain socket
Expose a Unix domain socket (e.g. the Docker daemon socket) as TCP.

Configure frps same as above.

Start frpc with configuration:

frpc.ini

[common]
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
Test: Get Docker version using curl:
curl http://x.x.x.x:6000/version

Expose a simple HTTP file server
Browser your files stored in the LAN, from public Internet.

Configure frps same as above.

Start frpc with configuration:

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/files
plugin_strip_prefix = static
plugin_http_user = abc
plugin_http_passwd = abc
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.
Enable HTTPS for local HTTP service
Start frpc with configuration:

frpc.ini

[common]
server_addr = x.x.x.x
server_port = 7000

[test_https2http]
type = https
custom_domains = test.example.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
plugin_header_X-From-Where = frp