frp 是一个可用于内网穿透的高性能的反向代理应用，支持 tcp, udp, http, https 协议-陌上烟雨遥

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.

Development Status
Architecture
Example Usage
Features
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

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

./frps -c ./frps.ini

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.

./frpc -c ./frpc.ini

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 an HTTP(S) service using frp.

./frps -c ./frps.ini

./frpc -c ./frpc.ini

./frps -c ./frps.ini

./frpc -c ./frpc.ini

dig @x.x.x.x -p 6000 www.google.com

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

Configure frps same as above.

curl http://x.x.x.x:6000/version

Browser your files stored in the LAN, from public Internet.

Configure frps same as above.

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.

ssh -oPort=6000 127.0.0.1

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.

ssh -oPort=6000 127.0.0.1

Features

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

Environment variables can be referenced in the configuration file, using Go’s standard format:

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.

Check frp’s status and proxies’ statistics information by Dashboard.

Configure a port for dashboard to enable this feature:

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

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

Configure an address for admin UI to enable this feature:

Then visit http://127.0.0.1:7400 to see admin UI, with username and password both being admin by default.

When dashboard is enabled, frps will save monitor data in cache. It will be cleared after process restart.

Prometheus is also supported.

Enable dashboard first, then configure enable_prometheus = true in frps.ini.

http://{dashboard_addr}/metrics will provide prometheus monitor data.

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.

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

When specifying authentication_method = oidc under [common] in frpc.ini and frps.ini – OIDC based authentication will be used.

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

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

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.

The admin_addr and admin_port fields are required for enabling HTTP API:

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

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.

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

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

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.

Set bandwidth_limit in each proxy’s configure to enable this feature. Supported units are MB and KB.

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:

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:

The kcp_bind_port number can be the same number as bind_port, since bind_port field specifies a TCP port.

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.

Load balancing is supported by group.

This feature is only available for types tcp and http now.

group_key is used for authentication.

For type tcp, remote_port in the same group should be the same.

For type http, custom_domains, subdomain, locations should be the same.

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

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

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:

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.

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

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.

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.

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:

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.

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.

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

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

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

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.

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.

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

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:

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.

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.

Proxy with names that start with range: will support mapping range ports.

frpc will generate 8 proxies like test_tcp_0, test_tcp_1, …, test_tcp_7.

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:

plugin_http_user and plugin_http_passwd are configuration parameters used in http_proxy 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.