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.
Now it also try to support p2p connect.
- Status
- Architecture
- Example Usage
- Features
- Configuration File
- Configuration file template
- Dashboard
- Admin UI
- Authentication
- Encryption and Compression
- Hot-Reload frpc configuration
- Get proxy status from client
- Port White List
- Port Reuse
- TCP Stream Multiplexing
- Support KCP Protocol
- Connection Pool
- Load balancing
- Health Check
- Rewriting the Host Header
- Set Headers In HTTP Request
- Get Real IP
- Password protecting your web service
- Custom subdomain names
- URL routing
- Connect frps by HTTP PROXY
- Range ports mapping
- Plugin
- Development Plan
- Contributing
- Donation
frp is under development and you can try it with latest release version. Master branch for releasing stable version when dev branch for developing.
We may change any protocol and can't promise backward compatible. Please check the release log when upgrading.
Firstly, download the latest programs from Release page according to your os and arch.
Put frps and frps.ini to your server with public IP.
Put frpc and frpc.ini to your server in LAN.
- Modify frps.ini:
# frps.ini
[common]
bind_port = 7000- Start frps:
./frps -c ./frps.ini
- Modify frpc.ini,
server_addris your frps's server IP:
# 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- Start frpc:
./frpc -c ./frpc.ini
- Connect to server in LAN by ssh assuming that username is test:
ssh -oPort=6000 test@x.x.x.x
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 a http or https service using frp.
- Modify frps.ini, configure http port 8080:
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080- Start frps:
./frps -c ./frps.ini
- Modify frpc.ini and set remote frps server's IP as x.x.x.x. The
local_portis 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.yourdomain.com- Start frpc:
./frpc -c ./frpc.ini
-
Resolve A record of
www.yourdomain.comto IPx.x.x.xor CNAME record to your origin domain. -
Now visit your local web service using url
http://www.yourdomain.com:8080.
- Modify frps.ini:
# frps.ini
[common]
bind_port = 7000- Start frps:
./frps -c ./frps.ini
- Modify frpc.ini, set remote frps's server IP as x.x.x.x, forward dns query request to google dns server
8.8.8.8:53:
# 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
- Send dns query request by dig:
dig @x.x.x.x -p 6000 www.google.com
Using tcp port to connect unix domain socket like docker daemon.
Configure frps same as above.
- Start frpc with configurations:
# 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- Get docker version by curl command:
curl http://x.x.x.x:6000/version
A simple way to visit files in the LAN.
Configure frps same as above.
- Start frpc with configurations:
# 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- Visit
http://x.x.x.x:6000/static/by your browser, set correct user and password, so you can see files in/tmp/file.
- Start frpc with configurations:
# 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- Visit
https://test.yourdomain.com.
For some services, if expose them to the public network directly will be a security risk.
stcp(secret tcp) helps you create a proxy avoiding any one can access it.
Configure frps same as above.
- Start frpc, forward ssh port and
remote_portis useless:
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[secret_ssh]
type = stcp
sk = abcdefg
local_ip = 127.0.0.1
local_port = 22- Start another frpc in which you want to connect this ssh server:
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[secret_ssh_visitor]
type = stcp
role = visitor
server_name = secret_ssh
sk = abcdefg
bind_addr = 127.0.0.1
bind_port = 6000- Connect to server in LAN by ssh assuming that username is test:
ssh -oPort=6000 test@127.0.0.1
xtcp is designed for transmitting a large amount of data directly between two client.
Now it can't penetrate all types of NAT devices. You can try stcp if xtcp doesn't work.
- Configure a udp port for xtcp:
bind_udp_port = 7001- Start frpc, forward ssh port and
remote_portis useless:
# 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- Start another frpc in which you want to connect this ssh server:
# 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- Connect to server in LAN by ssh assuming that username is test:
ssh -oPort=6000 test@127.0.0.1
You can find features which this document not metioned from full example configuration files.
Configuration file tempalte can be rendered using os environments. Template uses Go's standard format.
# 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.
Check frp's status and proxies's statistics information by Dashboard.
Configure a port for dashboard to enable this feature:
[common]
dashboard_port = 7500
# dashboard's username and password are both optional，if not set, default is admin.
dashboard_user = admin
dashboard_pwd = adminThen visit http://[server_addr]:7500 to see dashboard, default username and password are both admin.
Admin UI help you check and manage frpc's configure.
Configure a address for admin UI to enable this feature:
[common]
admin_addr = 127.0.0.1
admin_port = 7400
admin_user = admin
admin_pwd = adminThen visit http://127.0.0.1:7400 to see admin UI, default username and password are both admin.
token in frps.ini and frpc.ini should be same.
Defalut value is false, you could decide if the proxy will use encryption or compression:
# frpc.ini
[ssh]
type = tcp
local_port = 22
remote_port = 6000
use_encryption = true
use_compression = truefrp support TLS protocol between frpc and frps since v0.25.0.
Config tls_enable = true in common section to frpc.ini to enable this feature.
For port multiplexing, frp send a first byte 0x17 to dial a TLS connection.
First you need to set admin port in frpc's configure file to let it provide HTTP API for more features.
# frpc.ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400Then run command frpc reload -c ./frpc.ini and wait for about 10 seconds to let frpc create or update or delete proxies.
Note that parameters in [common] section won't be modified except 'start' now.
Use frpc status -c ./frpc.ini to get status of all proxies. You need to set admin port in frpc's configure file.
allow_ports in frps.ini is used for preventing abuse of ports:
# frps.ini
[common]
allow_ports = 2000-3000,3001,3003,4000-50000allow_ports consists of a specific port or a range of ports divided by ,.
Now vhost_http_port and vhost_https_port in frps can use same port with bind_port. frps will detect connection's protocol and handle it correspondingly.
We would like to try to allow multiple proxies bind a same remote port with different protocols in the future.
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:
# frps.ini and frpc.ini, must be same
[common]
tcp_mux = falseKCP 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:
- Enable kcp protocol in frps:
# frps.ini
[common]
bind_port = 7000
# kcp needs to bind a udp port, it can be same with 'bind_port'
kcp_bind_port = 7000- Configure the protocol used in frpc to connect frps:
# frpc.ini
[common]
server_addr = x.x.x.x
# specify the 'kcp_bind_port' in frps
server_port = 7000
protocol = kcpBy default, frps send message to frpc for create a new connection to backward service when getting an user request.If a proxy's connection pool is enabled, there will be a specified number of connections pre-established.
This feature is fit for a large number of short connections.
- Configure the limit of pool count each proxy can use in frps.ini:
# frps.ini
[common]
max_pool_count = 5- Enable and specify the number of connection pool:
# frpc.ini
[common]
pool_count = 1Load balancing is supported by group.
This feature is available only for type tcp and http now.
# 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 = 123group_key is used for authentication.
Proxies in same group will accept connections from port 80 randomly.
For tcp type, remote_port in one group shoud be same.
For http type, custom_domains, subdomain, locations shoud be same.
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.
Type tcp will dial the service port and type http will send a http rquest to service and require a 200 response.
Type tcp configuration:
# 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
# if continuous failed in 3 times, the proxy will be removed from frps
health_check_max_failed = 3
# every 10 seconds will do a health check
health_check_interval_s = 10Type http configuration:
# 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 = 3When 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.
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.comThe Host request header will be rewritten to Host: dev.yourdomain.com before it reach your local http server.
You can set headers for proxy which type is http.
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.com
header_X-From-Where = frpNote that params which have prefix header_ will be added to http request headers.
In this example, it will set header X-From-Where: frp to http request.
Features for http proxy only.
You can get user's real IP from HTTP request header X-Forwarded-For and X-Real-IP.
frp support Proxy Protocol to send user's real IP to local service. It support all types without UDP.
Here is an example for https service:
# frpc.ini
[web]
type = https
local_port = 443
custom_domains = test.yourdomain.com
# now v1 and v2 is supported
proxy_protocol_version = v2You 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.
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.
It can only be enabled when proxy type is http.
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
http_user = abc
http_pwd = abcVisit http://test.yourdomain.com and now you need to input username and password.
It is convenient to use subdomain configure for http、https type when many people use one frps server together.
# frps.ini
subdomain_host = frps.comResolve *.frps.com to the frps server's IP.
# frpc.ini
[web]
type = http
local_port = 80
subdomain = testNow 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.
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.
# 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,/aboutHttp requests with url prefix /news and /about will be forwarded to web02 and others to web01.
frpc can connect frps using HTTP PROXY if you set os environment HTTP_PROXY or configure http_proxy param in frpc.ini file.
It only works when protocol is tcp.
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
http_proxy = http://user:pwd@192.168.1.128:8080Proxy name has prefix range: will support mapping range ports.
# frpc.ini
[range:test_tcp]
type = tcp
local_ip = 127.0.0.1
local_port = 6000-6006,6007
remote_port = 6000-6006,6007frpc will generate 8 proxies like test_tcp_0, test_tcp_1 ... test_tcp_7.
frpc only forward request to local tcp or udp port by default.
Plugin is 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.
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:
# frpc.ini
[http_proxy]
type = tcp
remote_port = 6000
plugin = http_proxy
plugin_http_user = abc
plugin_http_passwd = abcplugin_http_user and plugin_http_passwd are configuration parameters used in http_proxy plugin.
- Log http request information in frps.
Interested in getting involved? We would like to help you!
- Take a look at our issues list and consider sending a Pull Request to dev branch.
- If you want to add a new feature, please create an issue first to describe the new feature, as well as the implementation approach. Once a proposal is accepted, create an implementation of the new features and submit it as a pull request.
- Sorry for my poor english and improvement for this document is welcome even some typo fix.
- If you have some wonderful ideas, send email to fatedier@gmail.com.
Note: We prefer you to give your advise in issues, so others with a same question can search it quickly and we don't need to answer them repeatly.
If frp help you a lot, you can support us by:
frp QQ group: 606194980
Donate money by paypal to my account fatedier@gmail.com.