Reference on 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

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

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

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