This document details the ClientCommonConfig structure and its related configuration options for the frpc client. This configuration defines global settings that apply to all proxies, including server connection parameters, authentication, logging, transport protocols, and the admin web interface.
The frpc client loads its configuration through a multi-stage pipeline. The root command initiates this process in runClient cmd/frpc/sub/root.go123-141 which calls config.LoadClientConfigResult to parse the file.
The validation logic is centralized in the validation package. The ConfigValidator struct pkg/config/v1/validation/client.go30-51 executes a series of specialized validators for feature gates, authentication, logging, web server, and transport settings.
Client Initialization Data Flow
Sources: cmd/frpc/sub/root.go123-141 cmd/frpc/sub/root.go192-219 pkg/config/v1/validation/client.go30-51 cmd/frpc/sub/verify.go32-59
The ClientCommonConfig structure contains all global settings for the frpc client. It is defined in pkg/config/v1/client.go32-83 and consists of the following major components:
ClientCommonConfig Code Entities
Sources: pkg/config/v1/client.go32-83 pkg/config/v1/client.go102-145 pkg/config/v1/common.go62-85
The client must be configured to connect to the frps server. These settings are defined at the top level of ClientCommonConfig:
| Field | Type | Description | Default |
|---|---|---|---|
serverAddr | string | Address of the frps server to connect to | "0.0.0.0" |
serverPort | int | Port to connect to on the frps server | 7000 |
user | string | Username prefix for all proxy names ({user}.{proxy}) | "" |
clientID | string | Optional unique identifier for this frpc instance | "" |
natHoleStunServer | string | STUN server for NAT hole punching | "stun.easyvoip.com:3478" |
dnsServer | string | Custom DNS server address for frpc to use | "" |
loginFailExit | *bool | Exit on login failure (if false, retry until success) | true |
The Complete() method pkg/config/v1/client.go85-100 ensures these defaults are applied if fields are omitted.
Sources: pkg/config/v1/client.go32-61 pkg/config/v1/client.go85-100
Authentication is configured via the auth field of type AuthClientConfig pkg/config/v1/client.go35 frp supports token-based and OIDC authentication.
Token authentication uses a shared secret. The validateAuthTokenSource function ensures that Token and TokenSource are not used simultaneously pkg/config/v1/validation/client.go71
Configured via AuthOIDCClientConfig pkg/config/v1/client.go204-235 It supports the Client Credentials Grant flow. If auth.oidc.tokenSource is used, other OIDC fields like clientID or clientSecret must be empty pkg/config/v1/validation/client.go84-104
The additionalScopes field pkg/config/v1/common.go35-40 allows extending authentication to:
HeartBeats: Authenticates every heartbeat packet.NewWorkConns: Authenticates every new work connection.Sources: pkg/config/v1/client.go180-202 pkg/config/v1/validation/client.go62-82 pkg/config/v1/common.go35-40
The ClientTransportConfig structure pkg/config/v1/client.go102-145 controls the communication layer.
Supported protocols include tcp, kcp, quic, websocket, and wss. Validation ensures the selected protocol is within the supported list pkg/config/v1/validation/client.go131-133
When tcpMux is enabled (default: true), multiple logical streams share a single TCP connection. If enabled, application-layer heartbeats are automatically disabled as the system relies on tcpMux keepalives pkg/config/v1/client.go156-159
TLSClientConfig pkg/config/v1/client.go161-178 provides fields for certFile, keyFile, and trustedCaFile. If transport.tls.enable is false, providing these files will trigger a configuration warning pkg/config/v1/validation/client.go118-129
Sources: pkg/config/v1/client.go102-145 pkg/config/v1/validation/client.go106-138
The WebServerConfig pkg/config/v1/common.go62-85 enables an internal HTTP server in frpc. This is required for several management features:
frpc reload command sends an HTTP request to this server to refresh configuration without restarting the process.frpc status command retrieves current proxy states via this interface.pprofEnable is true, Go runtime profiling endpoints are exposed.Sources: pkg/config/v1/common.go62-85 cmd/frpc/sub/root.go198
While the SshTunnelGateway is a server-side feature, frpc logic is used internally when a user connects via SSH. The TunnelServer pkg/ssh/server.go64-84 creates a virtual.Client which uses a ClientCommonConfig parsed from SSH command arguments pkg/ssh/server.go99-111
SSH Tunnel to Client Config Mapping
Sources: pkg/ssh/server.go99-111 pkg/ssh/server.go117-140 test/e2e/v1/features/ssh_tunnel.go21-45
The FeatureGates map pkg/config/v1/client.go70 allows enabling experimental features. For example, the VirtualNet feature requires both the configuration in VirtualNetConfig and the corresponding feature gate to be enabled, otherwise validation will fail pkg/config/v1/validation/client.go53-60
Sources: pkg/config/v1/client.go68-70 pkg/config/v1/validation/client.go53-60
Refresh this wiki