OpenFlare/docs/en/reference/configuration.md

Configuration Options

You will learn: What configuration sources are supported by OpenFlare Server, frontend builds, and Agents; what the default configuration values are; and how to configure common deployment combinations.

This document aggregates the currently supported configuration options for OpenFlare Server and Agent in version 1.0.0, keeping only running parameters that are currently active.

Configuration Sources

The Server supports three types of configuration sources:

1. CLI arguments.
2. Environment variables.
3. Runtime configurations in the database options table.

The Agent supports:

1. The -config CLI argument.
2. The agent.json configuration file.
3. A small set of environment variables for overriding logs and settings.

The Relay (Server-side) supports:

1. The -config CLI argument.
2. The relay.json configuration file.
3. Persistent environment variables for overriding runtime flags.

The Client (Intranet Client) supports:

1. The -config CLI argument.
2. The flared.json configuration file.
3. Startup overrides and logging environment variables.

Configuration File Locations

Component	Default Location	Description
Server SQLite	openflare.db	Can be customized via SQLITE_PATH
Agent Config	./agent.json	Can be specified via -config
One-Click Agent	/opt/openflare-agent/agent.json	Generated by the installation script by default
Agent Data Dir	data in the config folder	Can be customized via data_dir
Relay Config	./relay.json	Can be specified via -config
One-Click Relay	/opt/openflare-relay/relay.json	Generated by the installation script by default
Client Config	./flared.json	Can be specified via -config
One-Click Client	/opt/openflared/flared.json	Generated by the installation script by default

Server CLI Arguments

cd openflare-server
go run . --port 3000 --log-dir ./logs

Argument	Description	Default Value
--port	Port the Server listens on	3000
--log-dir	Directory to output logs	Empty (stdout)
--version	Outputs current version and exits	false
--help	Outputs help information and exits	false

Server Environment Variables

Environment Variable	Description	Default Value
PORT	Port the Server listens on	3000
GIN_MODE	Gin framework running mode	Defaults to release unless debug
LOG_LEVEL	Logging level	info
SESSION_SECRET	Session signing key	Randomly generated on startup
SQLITE_PATH	SQLite database file path	openflare.db
DSN	PostgreSQL DSN (takes precedence over SQLite)	Empty
SQL_DSN	Legacy PostgreSQL DSN (lower priority than DSN)	Empty
REDIS_CONN_STRING	Redis connection string	Empty
AGENT_TOKEN	Legacy global Agent Token	Empty

Notes:

• If both DSN and SQL_DSN exist, DSN is prioritized.
• If either DSN or SQL_DSN coexist with SQLITE_PATH, PostgreSQL is prioritized.
• If the target PostgreSQL database is empty and a local SQLite file exists at SQLITE_PATH, the Server automatically migrates SQLite data table-by-table on startup.
• SESSION_SECRET must be explicitly configured in production.
• If REDIS_CONN_STRING is unconfigured, co-located features fall back to in-memory implementations.

Runtime Options

The following options are maintained in the admin settings page and support hot reloading:

Parameter	Description	Default Value
AgentHeartbeatInterval	Heartbeat interval for Agents (ms)	10000
AgentWebsocketUpgradeEnabled	Toggles WebSocket upgrades after successful HTTP heartbeat	true
NodeOfflineThreshold	Threshold duration to mark a node offline (ms)	120000
AgentUpdateRepo	GitHub repository for Agent self-updates	Rain-kl/OpenFlare
GeoIPProvider	Geolocation resolution provider	ipinfo
DatabaseAutoCleanupEnabled	Toggles daily automatic cleanup of observability logs	false
DatabaseAutoCleanupRetentionDays	Data retention duration in days, minimum 1 day	30
GlobalApiRateLimitNum / GlobalApiRateLimitDuration	Global API rate limit count / window	300 / 180
GlobalWebRateLimitNum / GlobalWebRateLimitDuration	Global Web rate limit count / window	300 / 180
CriticalRateLimitNum / CriticalRateLimitDuration	Sensitive API rate limit count / window	100 / 1200

Notes:

• When DatabaseAutoCleanupEnabled is enabled, the Server deletes node_access_logs, node_metric_snapshots, and node_request_reports daily at 3:00 AM.
• DatabaseAutoCleanupRetentionDays must be greater than or equal to 1.
• Leaving retention days blank during a manual trigger in the console deletes all historic logs instantly.
• The GitHub Release in AgentUpdateRepo must contain a matching .sha256 checksum file for every Agent binary (e.g., openflare-agent-linux-amd64.sha256); the Agent validates this checksum before replacing the local executable.
• Third-party logins no longer use GitHubOAuthEnabled, GitHubClientId, and GitHubClientSecret as main configuration entrypoints; these legacy options are used only for migrating default GitHub credentials during upgrades.
• The legacy WeChat login options are kept for backward compatibility, but the option page no longer edits them.
• Legacy Cloudflare Turnstile options and validation logic are retained and will work normally.

OpenResty Parameters

OpenResty performance and caching parameters are managed in the options table, including:

• OpenRestyWorkerProcesses
• OpenRestyWorkerConnections
• OpenRestyWorkerRlimitNofile
• OpenRestyKeepaliveTimeout
• OpenRestyProxyConnectTimeout
• OpenRestyProxySendTimeout
• OpenRestyProxyReadTimeout
• OpenRestyProxyBufferingEnabled
• OpenRestyGzipEnabled
• OpenRestyCacheEnabled
• OpenRestyCachePath
• OpenRestyCacheMaxSize

These parameters must be validated, saved, and rendered structurally.

Constraints:

• The console no longer exposes resolver settings.
• Upstreams are rendered uniformly as named upstream blocks with keepalive enabled.
• Single upstreams carrying a base path or query have their URI correctly appended in proxy_pass.
• Multi-upstreams must be pure scheme://host[:port] using the same protocol within a single rule.
• OpenRestyCacheEnabled enables cache infrastructure and global defaults; the actual caching matching policies (by URL, suffix, or path) are configured per proxy_routes.
• The default cache key is $scheme$host$request_uri.
• Default keepalive_timeout is 20 seconds; default proxy_connect_timeout is 3 seconds.
• The default event model is epoll with multi_accept enabled.
• HTTPS listeners use the independent http2 on; directive to avoid deprecation warnings for listen ... http2 in newer Nginx/OpenResty versions.

Frontend Build Environment Variables

Environment Variable	Description	Default Value
NEXT_PUBLIC_API_BASE_URL	Base path for frontend API calls	/api
NEXT_PUBLIC_APP_VERSION	Application version shown in the UI	dev
NEXT_DEV_BACKEND_URL	Target backend proxied by the local dev server	http://127.0.0.1:3000

Agent Environment Variables

Environment Variable	Description	Default Value
LOG_LEVEL	Logging level for the Agent	info
OPENFLARE_SERVER_URL	Server URL; overrides agent.json	Empty
OPENFLARE_AGENT_TOKEN	Node-specific Token; overrides agent.json	Empty
OPENFLARE_DISCOVERY_TOKEN	Auto-registration Token; overrides agent.json	Empty
OPENFLARE_NODE_NAME	Node name; overrides agent.json	Empty
OPENFLARE_NODE_IP	Node IP; overrides agent.json	Empty
OPENFLARE_DATA_DIR	Agent data directory; overrides agent.json	Empty
OPENFLARE_OPENRESTY_PATH	Path to OpenResty binary; overrides agent.json	Empty
OPENFLARE_HEARTBEAT_INTERVAL	Heartbeat interval; overrides agent.json	Empty
OPENFLARE_REQUEST_TIMEOUT	Request timeout; overrides agent.json	Empty
OPENFLARE_OPENRESTY_OBSERVABILITY_PORT	Local observability port; overrides agent.json	Empty
OPENFLARE_MMDB_PATH	WAF GeoIP mmdb path; overrides agent.json	Empty
OPENFLARE_MMDB_UPDATE_INTERVAL	GeoIP mmdb update interval; overrides agent.json	Empty
OPENFLARE_MMDB_DOWNLOAD_URL	GeoIP mmdb download link; overrides agent.json	Empty

Agent CLI Arguments

Argument	Description	Default Value
-config	Path to the Agent configuration file	./agent.json

Agent Configurations Fields

Field	Description	Required	Default Value / Behavior
server_url	Control plane URL	Yes	None
agent_token	Node-specific access Token	Mutually exclusive with discovery_token	Empty
discovery_token	Global auto-registration Token	Mutually exclusive with agent_token	Empty
node_name	Node name	No	Hostname
node_ip	Node IP	No	Auto-detect, resolves outbound public IP via realip.cc first, falls back to local adapters
openresty_path	Path to the OpenResty binary	No	"openresty"
openresty_observability_port	Observability port for health checks	No	18081
data_dir	Agent data directory	No	data in the config folder
main_config_path	Write path for Nginx main configuration	No	data_dir/etc/nginx/nginx.conf
route_config_path	Write path for route configurations	No	data_dir/etc/nginx/conf.d/openflare_routes.conf
access_log_path	Write path for OpenResty access logs	No	data_dir/var/log/openflare/access.log
cert_dir	Write directory for SSL certificates	No	data_dir/etc/nginx/certs
openresty_cert_dir	Read directory for certificates in Nginx	No	Same as cert_dir
lua_dir	Write directory for Lua scripts and assets	No	data_dir/etc/nginx/lua
openresty_lua_dir	Read directory for Lua scripts in Nginx	No	Same as lua_dir
runtime_config_dir	Write directory for Agent runtime configs	No	data_dir/etc/openflare
mmdb_path	WAF GeoIP database file path	No	data_dir/etc/openflare/GeoLite2-Country.mmdb
mmdb_update_interval	WAF GeoIP database check interval	No	86400000 milliseconds
mmdb_download_url	WAF GeoIP database download URL	No	Built-in GeoLite2 Country URL
observability_buffer_path	Buffer path for retry metrics logs	No	data_dir/var/lib/openflare/observability-buffer.json
observability_replay_minutes	Lookback window for metric retries	No	15
state_path	Path to store local state JSON file	No	data_dir/var/lib/openflare/agent-state.json
heartbeat_interval	Heartbeat polling interval	No	10000 milliseconds
request_timeout	HTTP request timeout duration	No	10000 milliseconds

Notes:

• agent_token and discovery_token cannot both be empty.
• heartbeat_interval and request_timeout support integer milliseconds or Go duration strings.
• If AgentWebsocketUpgradeEnabled is enabled on the Server, the Agent upgrades the HTTP heartbeat to WebSocket; it automatically falls back to HTTP heartbeats if it fails or disconnects.
• If openresty_path is left blank, the Agent calls openresty on the host.
• Periodic health checks query http://127.0.0.1:<openresty_observability_port>/openflare/stub_status instead of executing openresty -t; validation prior to reloads, starts, or rollbacks still runs openresty -t -c <main_config_path>.
• The Agent initializes and periodically updates mmdb_path to support GeoIP region checks; failures to update write warnings and do not disrupt configuration synchronizations.
• The Agent boots normally if agent.json is missing but environment variables (OPENFLARE_SERVER_URL and a Token) are available; environment variables override JSON settings.
• If node_ip is left blank, the Agent resolves its outbound IP via https://realip.cc first, which is suitable for Docker/NAT networks.
• If the Agent registers a private node_ip, the Server prioritizes saving the public TCP connection IP, preventing NAT adapters from registering internal IPs.
• Enabling "Lock Node IP" in the console retains the manual IP; subsequent Agent registration or heartbeats do not overwrite it.

Relay Environment Variables

Environment Variable	Description	Default Value
LOG_LEVEL	Logging level for the Relay	info
OPENFLARE_SERVER_URL	Server URL; overrides relay.json	Empty
OPENFLARE_AGENT_TOKEN	Node-specific Token; overrides relay.json	Empty
OPENFLARE_DISCOVERY_TOKEN	Auto-registration Token; overrides relay.json	Empty
OPENFLARE_NODE_NAME	Node name; overrides relay.json	Empty
OPENFLARE_NODE_IP	Node IP; overrides relay.json	Empty
OPENFLARE_DATA_DIR	Relay data directory; overrides relay.json	Empty
OPENFLARE_FRPS_PATH	frps binary path; overrides relay.json	Empty

Relay CLI Arguments

Argument	Description	Default Value
-config	Path to the Relay configuration file	./relay.json

Relay Configuration Fields

Field	Description	Required	Default Value / Behavior
server_url	Control plane URL	Yes	None
agent_token	Node-specific access Token	Mutually exclusive with discovery_token	Empty
discovery_token	Global auto-registration Token	Mutually exclusive with agent_token	Empty
node_name	Node name	No	Hostname
node_ip	Relay listening IP for tunnel traffic	No	Auto-detect, prioritizes outbound public IP
frps_path	Path to the frps binary	No	frps (system PATH)
data_dir	Relay runtime data directory	No	data in the config folder
state_path	Path to store local state JSON file	No	data_dir/relay-state.json
heartbeat_interval	Heartbeat polling interval	No	10000 milliseconds, supports Go duration strings
request_timeout	HTTP request timeout duration	No	10000 milliseconds, supports Go duration strings

OpenFlared (Client) Environment Variables

Environment Variable	Description	Default Value
LOG_LEVEL	Logging level for the client	info
OPENFLARE_SERVER_URL	Server URL; overrides flared.json	Empty
OPENFLARE_TUNNEL_TOKEN	Tunnel access Token; overrides flared.json	Empty
OPENFLARE_DATA_DIR	Client data directory; overrides flared.json	Empty
OPENFLARE_FRPC_PATH	frpc binary path; overrides flared.json	Empty

OpenFlared (Client) CLI Arguments

Argument	Description	Default Value
-config	Path to the client configuration file	./flared.json

OpenFlared (Client) Configuration Fields

Field	Description	Required	Default Value / Behavior
server_url	Control plane URL	Yes	None
tunnel_token	Tunnel dedicated access Token	Yes	None
frpc_path	Path to the frpc binary	No	frpc (system PATH)
data_dir	Client runtime data directory	No	data in the config folder
state_path	Path to store local state JSON file	No	data_dir/flared-state.json
heartbeat_interval	Heartbeat polling interval	No	10000 milliseconds, supports Go duration strings
sync_interval	Configuration sync interval	No	30000 milliseconds, supports Go duration strings
request_timeout	HTTP request timeout duration	No	10000 milliseconds, supports Go duration strings

Common Configuration Combos

Production Server + PostgreSQL

export SESSION_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable'
export GIN_MODE='release'
export LOG_LEVEL='info'

Local Server + SQLite

export SESSION_SECRET='dev-session-secret'
export SQLITE_PATH='./openflare-dev.db'
export LOG_LEVEL='debug'
go run .

Agent + Default OpenResty

{
  "server_url": "http://your-server:3000",
  "agent_token": "replace-with-node-auth-token",
  "data_dir": "/opt/openflare-agent/data",
  "openresty_path": "openresty",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}

Agent + Customized OpenResty Paths

{
  "server_url": "http://your-server:3000",
  "agent_token": "replace-with-node-auth-token",
  "data_dir": "/var/lib/openflare-agent",
  "openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
  "main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
  "route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
  "access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
  "cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
  "lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
  "runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}

Relay (Server-side) Default Configuration

relay.json:

{
  "server_url": "http://your-server:3000",
  "agent_token": "replace-with-relay-auth-token",
  "frps_path": "frps",
  "data_dir": "/opt/openflare-relay/data",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}

OpenFlared (Client-side) Default Configuration

flared.json:

{
  "server_url": "http://your-server:3000",
  "tunnel_token": "replace-with-tunnel-token",
  "frpc_path": "frpc",
  "data_dir": "/opt/openflared/data",
  "heartbeat_interval": 10000,
  "sync_interval": 30000,
  "request_timeout": 10000
}

Maintenance Rules

This document must be updated in sync when any of the following change:

• Server CLI arguments.
• Server environment variables.
• Agent CLI arguments and configuration parameters.
• Relay CLI arguments and configuration parameters.
• Client CLI arguments and configuration parameters.
• Default values, scopes, or examples of any configuration items.