Skip to content
master
Go to file
Code

README.md

frp

 Build Status

README | Chinese documents

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

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

  1. Modify frps.ini on server A and set the bind_ port to be connected to frp clients:
 # frps.ini
 [common]
 bind_ port = 7000
  1. Start frps on server A:

./frps -c ./frps.ini

  1. 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.

  1. Start frpc on server B:

./frpc -c ./frpc.ini

  1. 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.

  1. Modify frps.ini , set the vhost HTTP port to 8080:
 # frps.ini
 [common]
 bind_ port = 7000 vhost_ http_ port = 8080
  1. Start frps :

./frps -c ./frps.ini

  1. 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
  1. Start frpc :

./frpc -c ./frpc.ini

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

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

Forward DNS query request

  1. Modify frps.ini :
 # frps.ini
 [common]
 bind_ port = 7000
  1. Start frps :

./frps -c ./frps.ini

  1. 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
  1. Start frpc:

./frpc -c ./frpc.ini

  1. 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.

  1. 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
  1. 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.

  1. 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
  1. 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

  1. 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
  1. Visit https://test.example.com .

Expose your service privately

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.

Configure frps same as above.

  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:
 # 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
  1. Start another frpc (typically on another machine C) with the following config to access the SSH service with a security key ( sk field):
 # 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
  1. On machine C, connect to SSH on machine B, using this command:

ssh -oPort=6000 127.0.0.1

P2P Mode

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.

Note it can't penetrate all types of NAT devices. You might want to fallback to stcp if xtcp doesn't work.

  1. In frps.ini configure a UDP port for xtcp:
 # frps.ini
 bind_ udp_ port = 7001
  1. Start frpc on machine B, expose the SSH port. Note that remote_ port field is removed:
 # 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
  1. Start another frpc (typically on another machine C) with the config to connect to SSH using P2P mode:
 # 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
  1. On machine C, connect to SSH on machine B, using this command:

ssh -oPort=6000 127.0.0.1

Features

Configuration Files

Read the full example configuration files to find out even more features not described here.

Full configuration file for frps (Server)

Full configuration file for frpc (Client)

Using Environment Variables

Environment variables can be referenced in the configuration file, using 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 }}

With the config above, variables can be passed into frpc program like this:

 export FRP_ SERVER_ ADDR="x.x.x.x"
export FRP_ SSH_ REMOTE_ PORT="6000"
./frpc -c ./frpc.ini

frpc will render configuration file template using OS environment variables. Remember to prefix your reference with .Envs .

Dashboard

Check frp's status and proxies' 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 = admin

Then visit http://[server_ addr]:7500 to see the dashboard, with username and password both being admin by default.

 dashboard

Admin UI

The Admin UI helps you check and manage frpc's configuration.

Configure an address for admin UI to enable this feature:

 [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, with username and password both being admin by default.

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.

Authenticating the Client

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 .

To use this authentication type - configure frpc.ini and frps.ini as follows:

 # frps.ini
 [common]
 authentication_ method = oidc oidc_ issuer = https://example-oidc-issuer.com/ oidc_ audience = https://oidc-audience.com/.default
 # 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

Encryption and Compression

The features are off by default. You can turn on encryption and/or compression:

 # frpc.ini
 [ssh]
 type = tcp local_ port = 22 remote_ port = 6000 use_ encryption = true use_ compression = true

TLS

frp supports the TLS protocol between frpc and frps since v0.25.0.

Config tls_ enable = true in the [common] section to frpc.ini to enable this feature.

For port multiplexing, frp sends a first byte 0x17 to dial a TLS connection.

To enforce frps to only accept TLS connections - configure tls_ only = true in the [common] section in frps.ini .

Hot-Reloading frpc configuration

The admin_ addr and admin_ port fields are required for enabling HTTP API:

 # frpc.ini
 [common]
 admin_ addr = 127.0.0.1 admin_ port = 7400

Then 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'.

Get proxy status from client

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.

Only allowing certain ports on the server

allow_ ports in frps.ini is used to avoid abuse of ports:

 # frps.ini
 [common]
 allow_ ports = 2000-3000,3001,3003,4000-50000

allow_ ports consists of specific ports or port ranges (lowest port number, dash - , highest port number), separated by comma , .

Port Reuse

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.

We would like to try to allow multiple proxies bind a same remote port with different protocols in the future.

Bandwidth Limit

For Each Proxy

 # 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 .

TCP Stream Multiplexing

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.

You can disable this feature by modify frps.ini and frpc.ini :

 # frps.ini and frpc.ini, must be same
 [common]
 tcp_ mux = false

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.

KCP mode uses UDP as the underlying transport. Using KCP in frp:

  1. Enable KCP in frps:
 # frps.ini
 [common]
 bind_ port = 7000 # Specify a UDP port for KCP.
 kcp_ bind_ port = 7000

The kcp_ bind_ port number can be the same number as bind_ port , since bind_ port field specifies a TCP port.

  1. Configure frpc.ini to use KCP to connect to frps:
 # frpc.ini
 [common]
 server_ addr = x.x.x.x # Same as the 'kcp_ bind_ port' in frps.ini
 server_ port = 7000 protocol = kcp

Connection Pooling

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.

This feature is suitable for a large number of short connections.

  1. Configure the limit of pool count each proxy can use in frps.ini :
 # frps.ini
 [common]
 max_ pool_ count = 5
  1. Enable and specify the number of connection pool:
 # frpc.ini
 [common]
 pool_ count = 1

Load balancing

Load balancing is supported by group .

This feature is only available for types 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 = 123

group_ key is used for authentication.

Connections to port 80 will be dispatched to proxies in the same group randomly.

For type tcp , remote_ port in the same group should be the same.

For type http , custom_ domains , subdomain , locations should be the same.

Service Health Check

Health check feature can help you achieve high availability with load balancing.

Add health_ check_ type = tcp or health_ check_ type = http to enable health check.

With health check type tcp , the service port will be pinged (TCPing):

 # frpc.ini
 [test1]
 type = tcp local_ port = 22 remote_ port = 6000 # Enable TCP health check
 health_ check_ type = tcp # TCPing timeout seconds
 health_ check_ timeout_s = 3 # If health check failed 3 times in a row, the proxy will be removed from frps
 health_ check_ max_ failed = 3 # A health check every 10 seconds
 health_ check_ interval_s = 10

With health check type http , an HTTP request will be sent to the service and an HTTP 2xx OK response is expected:

 # frpc.ini
 [web]
 type = http local_ ip = 127.0.0.1 local_ port = 80 custom_ domains = test.example.com # Enable HTTP health check
 health_ check_ type = http # frpc will send a GET request to '/status'
 # and expect an HTTP 2xx OK response
 health_ check_ url = /status health_ check_ timeout_s = 3 health_ check_ max_ failed = 3 health_ check_ interval_s = 10

Rewriting the HTTP Host Header

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:

 # frpc.ini
 [web]
 type = http local_ port = 80 custom_ domains = test.example.com host_ header_ rewrite = dev.example.com

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 .

Setting other HTTP Headers

Similar to Host , You can override other HTTP request headers with proxy type http .

 # frpc.ini
 [web]
 type = http local_ port = 80 custom_ domains = test.example.com host_ header_ rewrite = dev.example.com header_ X-From-Where = frp

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.

Get Real IP

HTTP X-Forwarded-For

This feature is for http proxy only.

You can get user's real IP from HTTP request headers X-Forwarded-For and X-Real-IP .

Proxy Protocol

frp supports Proxy Protocol to send user's real IP to local services. It support all types except UDP.

Here is an example for https service:

 # frpc.ini
 [web]
 type = https local_ port = 443 custom_ domains = test.example.com # now v1 and v2 are supported
 proxy_ protocol_ version = v2

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.

Require HTTP Basic Auth (Password) for Web Services

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 specified 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.example.com http_ user = abc http_ pwd = abc

Visit http://test.example.com in the browser and now you are prompted to enter the username and password.

Custom Subdomain Names

It is convenient to use subdomain configure for http and https types when many people share one frps server.

 # frps.ini
 subdomain_ host = frps.com

Resolve *.frps.com to the frps server's IP. This is usually called a Wildcard DNS record.

 # frpc.ini
 [web]
 type = http local_ port = 80 subdomain = test

Now you can visit your web service on test.frps.com .

Note that if subdomain_ host is not empty, custom_ domains should not be the subdomain of subdomain_ host .

URL Routing

frp supports forwarding HTTP requests to different backend web services by url routing.

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.

 # frpc.ini
 [web01]
 type = http local_ port = 80 custom_ domains = web.example.com locations = / [web02]
 type = http local_ port = 81 custom_ domains = web.example.com locations = /news,/about

HTTP requests with URL prefix /news or /about will be forwarded to web02 and other requests to web01 .

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 .

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:

 # frps.ini
 [common]
 bind_ port = 7000 tcpmux_ httpconnect_ port = 1337
 # 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 .

Connecting to frps via HTTP PROXY

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.

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:8080

Range ports mapping

Proxy with names that start with 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,6007

frpc will generate 8 proxies like test_ tcp_0 , test_ tcp_1 , ..., test_ tcp_7 .

Client Plugins

frpc only forwards requests to local TCP or UDP ports by default.

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 .

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.

Using plugin http_ proxy :

 # 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.

Server Manage Plugins

Read the document .

Find more plugins in gofrp/plugin .

Development Plan

  • Log HTTP request information in frps.

Contributing

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. Improvements for this document are welcome, even some typo fixes.
  • If you have great ideas, send an 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 repeatedly.

Donation

If frp helps you a lot, you can support us by:

frp QQ group: 606194980

AliPay

 donation-alipay

Wechat Pay

 donation-wechatpay

Paypal

Donate money by paypal to my account fatedier@gmail.com .

You can’t perform that action at this time.