Github url

frp

by fatedier

fatedier /frp

A fast reverse proxy to help you expose a local server behind a NAT or firewall to the internet.

37.4K Stars 7.1K Forks Last release: 3 months ago (v0.33.0) Apache License 2.0 845 Commits 54 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

frp

Build Status

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

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 [email protected]

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 ```
  2. 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:[email protected]: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 [email protected].

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 [email protected].

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.