frp

Common Configuration

Mon, 01 Jan 0001 00:00:00 +0000

LogConfig

Field	Type	Description	Required
to	string	Log output file path. If set to console, logs will be printed to standard output.	No
level	string	Log level. Options are trace, debug, info, warn, error. Default level is info.	No
maxDays	int	Maximum days to retain log files, default is 3 days.	No
disablePrintColor	bool	Disable log colors in standard output.	No

WebServerConfig

Field	Type	Description	Required
addr	string	webServer listening address, default is 127.0.0.1.	No
port	int	webServer listening port.	Yes
user	string	HTTP BasicAuth username.	No
password	string	HTTP BasicAuth password.	No
assetsDir	string	Static resource directory. Dashboard resources are packaged in the binary file by default. Use this parameter to specify custom static resources.	No
pprofEnable	bool	Enable Go HTTP pprof for application debugging.	No
tls	TLSConfig	TLS related configuration for Dashboard HTTPS.	No

TLSConfig

Field	Type	Description	Required
certFile	string	TLS certificate file path.	Yes
keyFile	string	TLS key file path.	Yes
trustedCaFile	string	CA certificate file path.	No
serverName	string	TLS Server name.	No

QUICOptions

Field	Type	Description	Required
keepalivePeriod	int	Default value is 10 seconds.	No
maxIdleTimeout	int	Default value is 30 seconds.	No
maxIncomingStreams	int	Default value is 100000.	No

PortsRange

Field	Type	Description	Required
start	int	Starting port.	No
end	int	Ending port.	No
single	int	Single port.	No

HeaderOperations

Field	Type	Description	Required
set	map[string]string	Set specified KV values in Header.	No

HTTPHeader

Field	Type	Description	Required
name	string	Header name.	Yes
value	string	Header value.	Yes

ValueSource

Field	Type	Description	Required
type	string	Data source type. Options are “file” and “exec”.	Yes
file	FileSource	File data source configuration, required when type is “file”.	No
exec	ExecSource	External command data source configuration, required when type is “exec”. Requires `--allow-unsafe=TokenSourceExec` flag at startup.	No

FileSource

Field	Type	Description	Required
path	string	File path.	Yes

ExecSource

Field	Type	Description	Required
command	string	Path to the command to execute.	Yes
args	[]string	List of command arguments.	No
env	[]ExecEnvVar	Additional environment variables.	No

ExecEnvVar

Field	Type	Description	Required
name	string	Environment variable name.	Yes
value	string	Environment variable value.	Yes

NatTraversalConfig

Field	Type	Description	Required
disableAssistedAddrs	bool	Disable assisted connections using local network interface addresses. When enabled, only uses STUN-discovered public addresses for NAT hole punching, avoiding potentially slow local network interfaces (e.g., VPN). Default is false.	No

Communication Security and Optimization

Mon, 01 Jan 0001 00:00:00 +0000

Encryption and Compression

Note: When TLS is enabled between frpc and frps, traffic will be globally encrypted, and encryption on individual proxies is no longer needed. This is enabled by default in newer versions.

Each proxy can choose whether to enable encryption and compression features.

The encryption algorithm uses aes-128-cfb, and the compression algorithm uses snappy.

Specify in each proxy’s configuration using the following parameters:

[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.useEncryption = true
transport.useCompression = true

By setting transport.useEncryption = true, the communication content between frpc and frps will be encrypted during transmission, effectively preventing transmission content from being intercepted.

Using systemd

Mon, 01 Jan 0001 00:00:00 +0000

On Linux systems, using systemd can conveniently control the start, stop, background running configuration, and boot auto-start of the frps server.

Here are the specific operation steps:

Install systemd

If systemd is not yet installed on your Linux server, you can use package managers like yum (for CentOS/RHEL) or apt (for Debian/Ubuntu) to install it:
```
# Install systemd using yum (CentOS/RHEL)
yum install systemd

# Install systemd using apt (Debian/Ubuntu)
apt install systemd
```
Create frps.service file

Custom TLS Protocol Encryption

Mon, 01 Jan 0001 00:00:00 +0000

transport.useEncryption and STCP functions can effectively prevent traffic content from being stolen during communication, but cannot determine whether the other party’s identity is legitimate, posing a risk of man-in-the-middle attacks. For this reason, frp supports traffic encryption between frpc and frps through TLS protocol, and supports client or server unidirectional verification, bidirectional verification, and other functions.

When transport.tls.force = true in frps.toml, it means the server only accepts TLS connection clients, which is also a prerequisite for frps to verify frpc identity. If the content of transport.tls.trustedCaFile in frps.toml is valid, then transport.tls.force = true will be enabled by default.

Modify HTTP Request Header

Mon, 01 Jan 0001 00:00:00 +0000

Modify Host Header

Normally, frp will not modify any forwarded data. However, some backend services will display different websites based on the Host field in HTTP request headers, such as nginx’s virtual host service. Enabling the Host Header modification feature can dynamically modify the Host field in HTTP requests. Note that this feature is only available for HTTP type proxies.

# frpc.toml
[[proxies]]
name = "web"
type = "http"
localPort = 80
customDomains = ["test.yourdomain.com"]
hostHeaderRewrite = "dev.yourdomain.com"

The original Host field test.yourdomain.com in the HTTP request will be replaced with dev.yourdomain.com when forwarded to the backend service.

Server Configuration

Mon, 01 Jan 0001 00:00:00 +0000

ServerConfig

Field	Type	Description	Required
auth	AuthServerConfig	Authentication configuration.	No
bindAddr	string	Server listening address for receiving frpc connections, default listens on 0.0.0.0.	No
bindPort	int	Server listening port, default value is 7000.	No
kcpBindPort	int	Server listening port for KCP protocol, used to receive frpc connections configured to use KCP protocol.	No
quicBindPort	int	Server listening port for QUIC protocol, used to receive frpc connections configured to use QUIC protocol.	No
proxyBindAddr	string	Proxy listening address, can make proxies listen on different network interface addresses, same as bindAddr by default.	No
vhostHTTPPort	int	Listening port for HTTP type proxies, must be enabled to support HTTP type proxies.	No
vhostHTTPTimeout	int	ResponseHeader timeout for HTTP type proxies on the server side, default is 60s.	No
vhostHTTPSPort	int	Listening port for HTTPS type proxies, must be enabled to support HTTPS type proxies.	No
tcpmuxHTTPConnectPort	int	Listening port for tcpmux type proxies with httpconnect multiplexer.	No
tcpmuxPassthrough	bool	Whether to pass through CONNECT requests for tcpmux type proxies.	No
subDomainHost	string	Subdomain suffix.	No
custom404Page	string	Custom 404 error page address.	No
sshTunnelGateway	SSHTunnelGateway	SSH tunnel gateway configuration.	No
webServer	WebServerConfig	Server Dashboard configuration.	No
enablePrometheus	bool	Whether to provide Prometheus monitoring interface, will only take effect when webServer is also enabled.	No
log	LogConfig	Log configuration.	No
transport	ServerTransportConfig	Network layer configuration.	No
detailedErrorsToClient	bool	Server returns detailed error information to client, default is true.	No
maxPortsPerClient	int	Limit the maximum number of simultaneous proxies for a single client, default is unlimited.	No
userConnTimeout	int	Timeout for waiting for client response after user establishes connection, in seconds, default is 10 seconds.	No
udpPacketSize	int	Maximum packet length supported when proxying UDP services, default is 1500. Server and client values need to be consistent.	No
natholeAnalysisDataReserveHours	int	Retention time for hole punching strategy data, default is 168 hours, i.e. 7 days.	No
allowPorts	[]PortsRange	Server ports allowed for proxy binding.	No
httpPlugins	[]HTTPPluginOptions	Server HTTP plugin configuration.	No

AuthServerConfig

Field	Type	Description	Required
method	string	Authentication method. Options are token or oidc, default is token.	No
additionalScopes	[]string	Additional scope for authentication information. Options are HeartBeats and NewWorkConns	No
token	string	Effective when method is token. Client needs to set the same value to pass authentication. Mutually exclusive with tokenSource field.	No
tokenSource	ValueSource	Configuration for loading token from file. Mutually exclusive with token field.	No
oidc	AuthOIDCServerConfig	OIDC authentication configuration.	No

AuthOIDCServerConfig

Field	Type	Required
issuer	string	No
audience	string	No
skipExpiryCheck	bool	No
skipIssuerCheck	bool	No

ServerTransportConfig

Field	Type	Description	Required
tcpMuxKeepaliveInterval	int	Heartbeat check interval time for tcp mux, in seconds.	No
tcpKeepalive	int	Keepalive interval time for underlying TCP connection with client, in seconds. Configure as negative number to disable.	No
maxPoolCount	int	Maximum connection pool size allowed for clients. If client configured value is greater than this value, it will be forcibly modified to the maximum value, default is 5.	No
heartbeatTimeout	int	Timeout for heartbeat connection between server and client, in seconds, default is 90 seconds.	No
quic	QUICOptions	QUIC protocol configuration parameters.	No
tls	TLSServerConfig	Server TLS protocol configuration.	No

TLSServerConfig

Field	Type	Description	Required
force	bool	Whether to only accept client connections with TLS enabled.	No
	TLSConfig	TLS protocol configuration, embedded structure.	No

HTTPPluginOptions

Field	Type	Description	Required
name	string	Plugin name.	Yes
addr	string	Plugin interface address.	Yes
path	string	Plugin interface path.	Yes
ops	[]string	List of operations that the plugin needs to take effect. For specific optional values, please refer to the server plugin documentation.	Yes
tlsVerify	bool	When plugin address is HTTPS protocol, whether to verify the plugin’s TLS certificate, default is not to verify.	No

SSHTunnelGateway

Field	Type	Description	Required
bindPort	int	SSH server listening port.	YES
privateKeyFile	string	SSH server private key file path. If empty, frps will read the private key file under autoGenPrivateKeyPath.	No
autoGenPrivateKeyPath	string	Private key file automatic generation path, default is ./.autogen_ssh_key. If the file does not exist or is empty, frps will automatically generate an RSA private key file and store it at this path.	No
authorizedKeysFile	string	SSH client authorized key file path. If empty, SSH client authentication will not be performed. Non-empty can implement SSH passwordless login authentication.	No

Client Configuration

Mon, 01 Jan 0001 00:00:00 +0000

ClientConfig

Field	Type	Description	Required
	ClientCommonConfig	Client common configuration.	Yes
proxies	[]ProxyConfig	Proxy configuration. Different proxy types correspond to different configurations, such as TCPProxyConfig or HTTPProxyConfig.	No
visitors	[]VisitorConfig	Visitor configuration. Different visitor types correspond to different configurations, such as STCPVisitorConfig.	No

ClientCommonConfig

Field	Type	Description	Required
auth	AuthClientConfig	Client authentication configuration.	No
user	string	Username. After setting this parameter, proxy names will be modified to {user}.{proxyName} to avoid proxy name conflicts with other users.	No
serverAddr	string	Address to connect to the server.	No
serverPort	int	Port to connect to the server, default is 7000.	No
natHoleStunServer	string	STUN server address required for xtcp hole punching, default is stun.easyvoip.com:3478.	No
dnsServer	string	DNS server address to use. By default, it uses the system-configured DNS server. Specifying this parameter can force replacement with a custom DNS server address.	No
loginFailExit	bool	Whether to exit after first login failure, default is true.	No
start	[]string	Specify to enable partial proxies. When many proxies are configured but only some of them are desired to be enabled, this parameter can be used to specify them. Default is to enable all.	No
log	LogConfig	Log configuration.	No
webServer	WebServerConfig	Client AdminServer configuration.	No
transport	ClientTransportConfig	Client network layer configuration.	No
virtualNet	VirtualNetConfig	Virtual network configuration, Alpha feature.	No
featureGates	map[string]bool	Feature gates, used to enable or disable experimental features.	No
udpPacketSize	int	Maximum packet length supported when proxying UDP services, default is 1500. Server and client need to maintain consistent configuration.	No
metadatas	map[string]string	Additional metadata that will be passed to server plugins to provide additional capabilities.	No
includes	[]string	Specify additional configuration file directories where proxy and visitor configurations will be read and loaded.	No
store	StoreConfig	Store configuration for persisting proxy and visitor configurations. Supports runtime management via Web UI or API when webServer is enabled.	No

StoreConfig

Field	Type	Description	Required
path	string	Store file path. When configured, enables the Store feature for runtime proxy and visitor management with persistence.	No

ClientTransportConfig

Field	Type	Description	Required
protocol	string	Communication protocol with frps. Options are tcp, kcp, quic, websocket, wss. Default is tcp.	No
dialServerTimeout	int	Timeout for connecting to the server, default is 10s.	No
dialServerKeepalive	int	Keepalive interval time for the underlying TCP connection with the server, in seconds.	No
connectServerLocalIP	string	Local IP bound when connecting to the server.	No
proxyURL	string	Proxy address used to connect to the server, format: {protocol}://user:passwd@192.168.1.128:8080. Protocol currently supports http, socks5, ntlm.	No
poolCount	int	Connection pool size.	No
tcpMux	bool	TCP multiplexing, enabled by default.	No
tcpMuxKeepaliveInterval	int	Heartbeat check interval time for `tcpMux`.	No
quic	QUICOptions	QUIC protocol configuration parameters.	No
heartbeatInterval	int	Interval time for sending heartbeat packets to the server, default is 30s. It is recommended to enable `tcpMuxKeepaliveInterval` and set this value to -1.	No
heartbeatTimeout	int	Timeout for heartbeat with the server, default is 90s.	No
tls	TLSClientConfig	Client TLS protocol configuration.	No

TLSClientConfig

Field	Type	Description	Required
enable	bool	Whether to enable TLS connection with the server, enabled by default.	No
disableCustomTLSFirstByte	bool	When TLS connection is enabled, do not send the 0x17 special byte. Default is true. When configured as true, it cannot be reused with vhostHTTPSPort port.	No
	TLSConfig	TLS protocol configuration, embedded structure.	No

AuthClientConfig

Field	Type	Description	Required
method	string	Authentication method. Options are token or oidc, default is token.	No
additionalScopes	[]string	Additional scope for authentication information. Options are HeartBeats and NewWorkConns	No
token	string	Effective when method is token. Client needs to set the same value to pass authentication. Mutually exclusive with tokenSource field.	No
tokenSource	ValueSource	Configuration for loading token from file. Mutually exclusive with token field.	No
oidc	AuthOIDCClientConfig	OIDC authentication configuration.	No

AuthOIDCClientConfig

Field	Type	Description	Required
clientID	string	OIDC client ID.	No
clientSecret	string	OIDC client secret.	No
audience	string	OIDC audience parameter.	No
scope	string	OIDC scope parameter.	No
tokenEndpointURL	string	OIDC token endpoint URL.	No
additionalEndpointParams	map[string]string	Additional endpoint parameters.	No
trustedCaFile	string	Trusted CA certificate file path for verifying OIDC server TLS certificate.	No
insecureSkipVerify	bool	Skip TLS certificate verification, not recommended for production use.	No
proxyURL	string	Proxy server URL to use when accessing OIDC token endpoint.	No
tokenSource	ValueSource	Configuration for dynamically obtaining OIDC token from external source. When configured, other OIDC configuration fields will be ignored.	No

VirtualNetConfig

Field	Type	Description	Required
address	string	IP address and network segment of the virtual network interface, format is CIDR (e.g. “100.86.0.1/24”).	Yes

Set BasicAuth Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Since all clients share one frps HTTP service port, anyone who knows your domain name and URL can access your services deployed in the intranet. However, in some scenarios, you need to ensure that only limited users can access.

frp supports protecting your web services through HTTP Basic Auth, requiring users to access your services through username and password.

This feature is currently limited to HTTP type proxies and requires adding username and password settings in frpc’s proxy configuration.

Custom Subdomain

Mon, 01 Jan 0001 00:00:00 +0000

When multiple people are using one frps simultaneously, using custom subdomains is more convenient.

By configuring subdomainHost in frps’s configuration file, you can enable this feature. After that, in frpc’s http and https type proxies, you can configure a subdomain parameter instead of configuring customDomains.

You only need to resolve *.{subdomainHost} to the server where frps is located. After that, users can specify their own subdomain for their web services through subdomain, and access their web services through {subdomain}.{subdomainHost}.

Proxy Configuration

Mon, 01 Jan 0001 00:00:00 +0000

ProxyBaseConfig

Field	Type	Description	Required
name	string	Proxy name.	Yes
type	string	Proxy type. Options are tcp, udp, http, https, tcpmux, stcp, sudp, xtcp.	Yes
enabled	*bool	Whether this proxy is enabled, default is true. Set to false to disable this proxy, allowing individual control over each proxy’s enabled state.	No
annotations	map[string]string	Proxy annotation information that will be displayed in the server’s dashboard.	No
transport	ProxyTransport	Proxy network layer configuration.	No
metadatas	map[string]string	Additional metadata that will be passed to server plugins to provide additional capabilities.	No
loadBalancer	LoadBalancerConfig	Load balancing configuration.	No
healthCheck	HealthCheckConfig	Health check configuration.	No
	ProxyBackend	Proxy backend service configuration.	Yes

ProxyTransport

Field	Type	Description	Required
useEncryption	bool	Whether to enable encryption functionality. When enabled, communication content between this proxy and the server will be encrypted. If frpc has enabled global TLS, this parameter is not needed.	No
useCompression	bool	Whether to enable compression functionality. When enabled, communication content between this proxy and the server will be compressed.	No
bandwidthLimit	string	Set bandwidth rate limiting for a single proxy, in MB or KB units. 0 means no limit. If enabled, it will apply to the corresponding frpc by default.	No
bandwidthLimitMode	string	Rate limiting type, client-side or server-side rate limiting. Options are client and server, default is client-side rate limiting.	No
proxyProtocolVersion	string	Version of proxy protocol to enable. Options are v1 and v2. If enabled, frpc will send proxy protocol after establishing connection with local service, containing original request IP address and port information.	No

ProxyBackend

Field	Type	Description	Required
localIP	string	IP of the local service being proxied, default is 127.0.0.1.	No
localPort	int	Port of the local service being proxied.	No
plugin	ClientPluginOptions	Client plugin configuration. If client plugin is enabled, localIP and localPort don’t need to be configured, and traffic will be handled by the client plugin. Different plugin types correspond to different configurations, such as HTTPProxyPluginOptions.	No

LoadBalancerConfig

Field	Type	Description	Required
group	string	Load balancing group name. User requests will be sent to proxies in the same group using round-robin.	Yes
groupKey	string	Load balancing group key for authenticating the load balancing group. Only proxies with the same groupKey will be added to the same group.	No

HealthCheckConfig

Field	Type	Description	Required
type	string	Health check type. Options are tcp and http. After configuration, health check is enabled. tcp considers service healthy if connection succeeds, http requires interface to return 2xx status codes to consider service healthy.	Yes
timeoutSeconds	int	Health check timeout (seconds), default is 3s.	No
maxFailed	int	Consecutive health check error count. How many consecutive check errors to consider service unhealthy, default is 1.	No
intervalSeconds	int	Health check interval (seconds). How often to perform health checks, default is 10s.	No
path	string	Health check HTTP interface. If health check type is http, this parameter needs to be configured to specify the path for sending http requests, such as `/health`.	No
httpHeaders	[]HTTPHeader	Health check HTTP request headers, only effective when health check type is http.	No

DomainConfig

Field	Type	Description	Required
customDomains	[]string	Custom domain list.	No
subdomain	string	Subdomain.	No

TCPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
remotePort	int	Port bound by the server. Traffic accessing this port on the server will be forwarded to the corresponding local service.	No

UDPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
remotePort	int	Port bound by the server. Traffic accessing this port on the server will be forwarded to the corresponding local service.	No

HTTPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
	DomainConfig	Domain configuration.	Yes
locations	[]string	URL routing configuration.	No
httpUser	string	HTTP Basic Auth username.	No
httpPassword	string	HTTP Basic Auth password.	No
hostHeaderRewrite	string	Replace Host Header.	No
requestHeaders	HeaderOperations	Request Header operation configuration.	No
responseHeaders	HeaderOperations	Response Header operation configuration.	No
routeByHTTPUser	string	Route by HTTP Basic Auth user.	No

HTTPSProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
	DomainConfig	Domain configuration.	Yes

TCPMuxProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
	DomainConfig	Domain configuration.	Yes
httpUser	string	Username. If this parameter is configured, correct identity information needs to be attached via Proxy-Authorization when establishing connection through HTTP CONNECT.	No
httpPassword	string	Password.	No
routeByHTTPUser	string	Route by HTTP Basic Auth user.	No
multiplexer	string	Multiplexer type, currently only supports httpconnect.	No

STCPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
secretKey	string	Secret key. The secret key between server and access side must be consistent for the access side to access the server.	No
allowUsers	[]string	List of visitor users allowed to access. By default, only visitors under the same user are allowed to access. Configure as * to allow any visitor to access.	No

XTCPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
secretKey	string	Secret key. The secret key between server and access side must be consistent for the access side to access the server.	No
allowUsers	[]string	List of visitor users allowed to access. By default, only visitors under the same user are allowed to access. Configure as * to allow any visitor to access.	No
natTraversal	NatTraversalConfig	NAT traversal configuration.	No

SUDPProxyConfig

Field	Type	Description	Required
	ProxyBaseConfig	Base configuration.	Yes
secretKey	string	Secret key. The secret key between server and access side must be consistent for the access side to access the server.	No
allowUsers	[]string	List of visitor users allowed to access. By default, only visitors under the same user are allowed to access. Configure as * to allow any visitor to access.	No

Access Intranet Machines via SSH

Mon, 01 Jan 0001 00:00:00 +0000

Steps

Deploy frps on a machine with public IP

Deploy frps and edit the frps.toml file. Here is a simplified configuration where we set the port for the frp server to receive client connections:
```
bindPort = 7000
```
Deploy frpc on the intranet machine that needs to be accessed

Deploy frpc and edit the frpc.toml file. Assume the public IP address of the server where frps is located is x.x.x.x. Here is an example configuration:

Routing

Mon, 01 Jan 0001 00:00:00 +0000

URL Routing

frp supports routing and forwarding to different backend services based on the URL path of the request.

Specify one or more URL prefixes that a proxy can match through the locations field in the configuration file (currently only supports maximum prefix matching, regex matching will be considered later). For example, specifying locations = "/news" means all requests with URLs starting with /news will be forwarded to this service.

Visitor Configuration

Mon, 01 Jan 0001 00:00:00 +0000

VisitorBaseConfig

Field	Type	Description	Required
name	string	Visitor name.	Yes
type	string	Visitor type. Options are stcp, sudp, xtcp.	Yes
enabled	*bool	Whether this visitor is enabled, default is true. Set to false to disable this visitor, allowing individual control over each visitor’s enabled state.	No
transport	VisitorTransport	Visitor network layer configuration.	No
secretKey	string	Secret key. The secret key between server and access side must be consistent for the access side to access the server.	No
serverUser	string	Username that the proxy to be accessed belongs to. If empty, defaults to current user.	No
serverName	string	Name of the proxy to be accessed.	Yes
bindAddr	string	Local address that visitor listens on. By accessing the listened address and port, connect to the remote proxy service.	No
bindPort	int	Local port that visitor listens on. If set to -1, means no need to listen on physical port, usually can be used as fallback for other visitors.	Yes
plugin	VisitorPluginOptions	Visitor plugin configuration for extending visitor functionality. Different plugin types correspond to different configurations.	No

VisitorTransport

Field	Type	Description	Required
useEncryption	bool	Whether to enable encryption functionality. When enabled, communication content between this proxy and the server will be encrypted. If frpc has enabled global TLS, this parameter is not needed.	No
useCompression	bool	Whether to enable compression functionality. When enabled, communication content between this proxy and the server will be compressed.	No

STCPVisitorConfig

Field	Type	Description	Required
	VisitorBaseConfig	Base configuration.	Yes

SUDPVisitorConfig

Field	Type	Description	Required
	VisitorBaseConfig	Base configuration.	Yes

XTCPVisitorConfig

Field	Type	Description	Required
	VisitorBaseConfig	Base configuration.	Yes
protocol	string	Tunnel underlying communication protocol. Options are quic and kcp, default is quic.	No
keepTunnelOpen	bool	Whether to keep tunnel open. If enabled, will periodically check tunnel status and try to keep it open.	No
maxRetriesAnHour	int	Number of attempts to open tunnel per hour, default value is 8.	No
minRetryInterval	int	Minimum interval time for retrying to open tunnel, in seconds, default is 90s.	No
fallbackTo	string	Name of other visitor to fallback to.	No
fallbackTimeoutMs	int	Fallback to other visitor after connection establishment exceeds this time (ms).	No
natTraversal	NatTraversalConfig	NAT traversal configuration.	No

Client Plugin Configuration

Mon, 01 Jan 0001 00:00:00 +0000

HTTPProxyPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “http_proxy”.	Yes
httpUser	string	HTTP proxy username.	No
httpPassword	string	HTTP proxy password.	No

Socks5PluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “socks5”.	Yes
username	string	Username.	No
password	string	Password.	No

StaticFilePluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “static_file”.	Yes
localPath	string	Local path where static files are located.	Yes
stripPrefix	string	Remove specific prefix from user HTTP request Path.	No
httpUser	string	HTTP Basic Auth username.	No
httpPassword	string	HTTP Basic Auth password.	No

UnixDomainSocketPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “unix_domain_socket”.	Yes
unixPath	string	UNIX domain socket address.	Yes

HTTP2HTTPSPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “http2https”.	Yes
localAddr	string	Local HTTPS service address.	Yes
hostHeaderRewrite	string	Replace Host header.	No
requestHeaders	HeaderOperations	Request Header operation configuration.	No

HTTPS2HTTPPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “https2http”.	Yes
localAddr	string	Local HTTPS service address.	Yes
hostHeaderRewrite	string	Replace Host header.	No
requestHeaders	HeaderOperations	Request Header operation configuration.	No
enableHTTP2	bool	Whether to enable HTTP/2, enabled by default.	No
crtPath	string	TLS certificate file path.	No
keyPath	string	TLS key file path.	No

HTTPS2HTTPSPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “https2https”.	Yes
localAddr	string	Local HTTPS service address.	Yes
hostHeaderRewrite	string	Replace Host header.	No
requestHeaders	HeaderOperations	Request Header operation configuration.	No
enableHTTP2	bool	Whether to enable HTTP/2, enabled by default.	No
crtPath	string	TLS certificate file path.	No
keyPath	string	TLS key file path.	No

TLS2RawPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “tls2raw”.	Yes
localAddr	string	Local service address.	Yes
crtPath	string	TLS certificate file path.	No
keyPath	string	TLS key file path.	No

VirtualNetPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “virtual_net”.	Yes

Visitor Plugin Configuration

Mon, 01 Jan 0001 00:00:00 +0000

VirtualNetVisitorPluginOptions

Field	Type	Description	Required
type	string	Plugin type, set to “virtual_net”.	Yes
destinationIP	string	Target virtual IP address to access. Usually the server’s virtual network address.	Yes

Configuration File

Mon, 01 Jan 0001 00:00:00 +0000

Starting from v0.52.0, frp began supporting TOML, YAML, and JSON as configuration file formats.

Please note that INI has been deprecated and will be removed in future releases. New features can only be used in TOML, YAML, or JSON. Users who wish to use these new features should switch their configuration format accordingly.

Format

You can use any format you like among TOML/YAML/JSON to write configuration files, and frp will automatically adapt and parse them.

Multiple SSH Services Sharing the Same Port

Mon, 01 Jan 0001 00:00:00 +0000

Steps

Deploy frps on a machine with public IP

Modify the frps.toml file to include the following content (using the most simplified configuration here):
```
bindPort = 7000
tcpmuxHTTPConnectPort = 5002
```

Deploy frpc on intranet machine A

Create an frpc configuration file, for example frpc.toml, and add the following content to the configuration file:

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh1"
type = "tcpmux"
multiplexer = "httpconnect"
customDomains = ["machine-a.example.com"]
localIP = "127.0.0.1"
localPort = 22

Deploy another frpc on intranet machine B

Create an frpc configuration file, for example frpc.toml, and add the following content to the configuration file:

Access Intranet Web Services via Custom Domain Names

Mon, 01 Jan 0001 00:00:00 +0000

HTTP type proxies are very suitable for providing intranet web services to external users through custom domain names. Compared to TCP type proxies, HTTP proxies can not only reuse ports but also provide many features based on the HTTP protocol.

HTTPS is similar to this, but it should be noted that frp’s HTTPS proxy requires the local service to be an HTTPS service, and frps will not perform TLS termination. You can also combine the https2http plugin to expose local HTTP services through the HTTPS protocol.

Forward DNS Query Requests

Mon, 01 Jan 0001 00:00:00 +0000

DNS query requests typically use the UDP protocol, and frp supports penetration of intranet UDP services, with configuration similar to TCP.

Steps

Configure frps.toml

Add the following content to the frps.toml file:
```
bindPort = 7000
```
Configure frpc.toml

Add the following content to the frpc.toml file:
```
serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "dns"
type = "udp"
localIP = "8.8.8.8"
localPort = 53
remotePort = 6000
```
Please note that this example reverse-proxies Google’s DNS query server address, which is only for testing UDP proxy and has no practical significance.

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Currently, frps server supports two monitoring systems: memory monitoring and Prometheus monitoring.

Memory Monitoring

Monitoring data stored in memory is primarily used for Dashboard display. When the Dashboard feature is enabled in frps configuration, memory monitoring is enabled by default.

Please note that monitoring data in memory will be cleared after each process restart, or retained for 7 days. Monitoring data can be obtained by sending HTTP requests to the Dashboard address, but this API is not currently standardized and direct use is not recommended.

Forward Unix Domain Socket

Mon, 01 Jan 0001 00:00:00 +0000

Steps

Configure frps.toml

Add the following content to the frps.toml file:
```
bindPort = 7000
```

Configure frpc.toml

Add the following content to the frpc.toml file, ensuring the correct Unix domain socket path is set:

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "unix_domain_socket"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "unix_domain_socket"
# Unix domain socket path
unixPath = "/var/run/docker.sock"

Start frps and frpc
Use curl to view Docker version information
```
curl http://x.x.x.x:6000/version
```

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Currently, frpc and frps support two authentication methods: token and oidc, with token being the default. These authentication methods allow you to verify communication between the client and server, ensuring that only authorized users can establish connections.

Token

Token authentication is a simple authentication method that only requires configuring the same token in both the frp client (frpc) and server (frps) configuration files.

Configuration Example

# frps.toml
bindPort = 7000
auth.token = "abc"

# frpc.toml
auth.token = "abc"

Loading Token from File

Added in v0.64.0

Provide Simple File Access Service

Mon, 01 Jan 0001 00:00:00 +0000

By using the static_file plugin, you can easily provide an HTTP-based file access service that allows others to access your specified files.

Steps

Configure frps.toml

Add the following content to the frps.toml file:
```
bindPort = 7000
```

Configure frpc.toml

Add the following content to the frpc.toml file, ensuring appropriate file paths, username, and password are set:

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "test_static_file"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "static_file"
# Local file directory to provide external access
localPath = "/tmp/file"
# Prefix in URL that will be removed, remaining content is the file path to access
stripPrefix = "static"
httpUser = "abc"
httpPassword = "abc"

Please modify localPath, stripPrefix, httpUser, and httpPassword according to your actual situation.

Enable HTTPS for Local HTTP Service

Mon, 01 Jan 0001 00:00:00 +0000

Steps

Configure frps.toml
```
bindPort = 7000
vhostHTTPSPort = 443
```

Configure frpc.toml

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "test_htts2http"
type = "https"
customDomains = ["test.yourdomain.com"]

[proxies.plugin]
type = "https2http"
localAddr = "127.0.0.1:80"

# HTTPS certificate related configuration
crtPath = "./server.crt"
keyPath = "./server.key"
hostHeaderRewrite = "127.0.0.1"
requestHeaders.set.x-from-where = "frp"

Please note that you need to modify the above configuration according to your domain name and certificate path.

Start frps and frpc
Access HTTPS Service

Open your web browser and visit https://test.yourdomain.com.

By following the above steps, you will be able to enable HTTPS for local HTTP services to achieve secure external access.

Securely Expose Intranet Services

Mon, 01 Jan 0001 00:00:00 +0000

Some intranet services may pose security risks if directly exposed on the public network. Using stcp (secret tcp) type proxies allows you to securely expose intranet services to authorized users, which requires visitors to also deploy frpc clients.

Steps

Configure frps.toml

Add the following content to the frps.toml file:
```
bindPort = 7000
```
Deploy frpc client and configure

Deploy frpc on the machine that needs to expose intranet services to the public network, and create the following configuration:

Web Interface

Mon, 01 Jan 0001 00:00:00 +0000

Currently, frpc and frps have built-in corresponding web interfaces for user convenience.

Server Dashboard

The server Dashboard allows users to view frp status and proxy statistics through a browser.

Note: Dashboard has not been optimized for displaying large amounts of proxy data. If you experience slow Dashboard access, please do not enable this feature.

You need to specify the port used by the dashboard service in frps.toml to enable this feature:

Point-to-Point Intranet Penetration

Mon, 01 Jan 0001 00:00:00 +0000

frp provides a new proxy type xtcp for intranet penetration when you need to transfer large amounts of data and don’t want traffic to go through the server.

Similar to stcp, using xtcp requires deploying frpc on both ends to establish a direct connection.

Note that xtcp is not suitable for all types of NAT devices. If penetration fails, you can try using stcp proxy.

Steps

Configure frpc.toml file on the machine that needs to be exposed to the external network

Virtual Network (VirtualNet)

Mon, 01 Jan 0001 00:00:00 +0000

Note: VirtualNet is an Alpha-stage feature that is currently unstable. Its configuration methods and functionality may change at any time in future versions. Please do not use this feature in production environments; it is only recommended for testing and evaluation purposes.

Overview

Virtual Network (VirtualNet) functionality is an Alpha feature introduced in frp v0.62.0, which allows frp to create and manage virtual network connections between clients and visitors through TUN interfaces, enabling complete network connectivity between devices.

Load Balancing and Health Check

Mon, 01 Jan 0001 00:00:00 +0000

Load Balancing

You can add multiple proxies of the same type to the same group to implement load balancing capabilities.

Currently supported proxy types include: tcp, http, https, tcpmux.

# frpc.toml
[[proxies]]
name = "test1"
type = "tcp"
localPort = 8080
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

[[proxies]]
name = "test2"
type = "tcp"
localPort = 8081
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

When users connect to port 80 of the frps server, frps will randomly distribute received user connections to one of the surviving proxies. This ensures that even if one frpc machine fails, other nodes can still provide services.

Get Real User IP

Mon, 01 Jan 0001 00:00:00 +0000

HTTP X-Forwarded-For

Currently, only http type proxies or proxies with https2http or https2https plugins enabled support this feature.

You can get the real user IP through the X-Forwarded-For in HTTP request headers, which is enabled by default.

Proxy Protocol

frp supports passing the real IP of requests proxied through frp via the Proxy Protocol protocol.

After the Proxy Protocol feature is enabled, frpc will first send a section of Proxy Protocol protocol content to the local service after establishing a connection with the local service. The local service can obtain the real IP of the accessing user by parsing this content. So not only HTTP services, but any TCP service that supports this protocol can obtain the user’s real IP address.

Port Range Mapping

Mon, 01 Jan 0001 00:00:00 +0000

Added in v0.56.0

We can use Go template’s range syntax combined with the built-in parseNumberRangePair function to implement port range mapping.

In the example below, after the application runs, 8 proxies will be created, named test-6000, test-6001 ... test-6007, which will map remote ports to local ports respectively.

{{- range $_, $v := parseNumberRangePair "6000-6006,6007" "6000-6006,6007" }}
[[proxies]]
name = "tcp-{{ $v.First }}"
type = "tcp"
localPort = {{ $v.First }}
remotePort = {{ $v.Second }}
{{- end }}

Client

Mon, 01 Jan 0001 00:00:00 +0000

Dynamic Configuration Updates

When you need to modify frpc proxy configuration, you can use the frpc reload command to achieve dynamic configuration file loading, usually completing proxy updates within seconds.

To enable this feature, you need to enable webServer in frpc to provide API services. The configuration is as follows:

webServer.addr = "127.0.0.1"
webServer.port = 7400

Then execute the following command to reload the configuration:

frpc reload -c ./frpc.toml

After waiting for a period of time, the client will create, update, or delete proxies according to the new configuration file. Note that parameters in the non-proxy related common section cannot currently be modified except for start.

Server Management

Mon, 01 Jan 0001 00:00:00 +0000

Port Whitelist

To prevent port abuse, you can manually specify which ports are allowed to be used. In the server configuration, specify through allowPorts:

# frps.ini
allowPorts = [
  { start = 2000, end = 3000 },
  { single = 3001 },
  { single = 3003 },
  { start = 4000, end = 50000 }
]

allowPorts can configure a specific port or all ports within a range to be allowed.

Port Reuse

Currently, vhostHTTPPort and vhostHTTPSPort in frps support being configured as the same port as bindPort. frps will analyze the connection protocol and then handle it differently.

Client Plugin

Mon, 01 Jan 0001 00:00:00 +0000

By default, frpc will only forward requests to local TCP or UDP ports, i.e., the local service address specified by localIP and localPort.

By enabling client plugin functionality, you can build in some simple local services when only starting frpc, thereby achieving functionality that would normally require starting additional services.

In each proxy’s configuration, you can configure the plugin to use and related parameters through plugin. After enabling client plugins, you no longer need to configure localIP and localPort.

Server Plugin

Mon, 01 Jan 0001 00:00:00 +0000

The purpose of frp server plugins is to extend the capabilities of the frp server without intruding on its own code.

frp server plugins run as separate processes and listen on a port, providing RPC interfaces externally to respond to frps requests.

Before executing certain operations, frps will send RPC requests to server plugins according to configuration, and execute corresponding operations based on the plugin’s response.

RPC Requests

After receiving operation requests, server plugins can give three types of responses:

SSH Tunnel Gateway

Mon, 01 Jan 0001 00:00:00 +0000

Added in v0.53.0

Concept

SSH supports reverse proxy capability rfc.

frp supports listening on an SSH port on the frps side, completing TCP protocol proxy through the SSH -R protocol. In this mode, there is no need to depend on frpc.

SSH reverse tunnel proxy and proxying SSH ports through frp are two different concepts. SSH reverse tunnel proxy is essentially using ssh client to connect to frps to complete basic reverse proxy when you don’t want to use frpc.

Virtual Network (VirtualNet)

Mon, 01 Jan 0001 00:00:00 +0000

Alpha feature, added in v0.62.0

Note: VirtualNet is an Alpha stage feature that is currently unstable. Its configuration methods and functionality may change at any time in future versions. Please do not use this feature in production environments; it is only recommended for testing and evaluation purposes.

Overview

The Virtual Network (VirtualNet) feature allows frp to create and manage virtual network connections between clients through TUN interfaces. This feature extends frp’s capabilities beyond traditional port forwarding to achieve complete network layer communication.

Mon, 01 Jan 0001 00:00:00 +0000

Search Results

Mon, 01 Jan 0001 00:00:00 +0000