OpenFlare/docs/en/reference/configuration.md

Configuration Reference

You will learn: What configuration sources are supported by OpenFlare Server, frontend builds, and Agents, what the default values of configuration items are, and how common deployment combinations should be configured.

This document summarizes the Server and Agent configuration items supported by OpenFlare 1.0.0, retaining only the startup, deployment, and runtime parameters that remain valid.

Configuration Sources

The Server supports three types of configuration sources:

1. Command-line parameters.
2. Environment variables.
3. Runtime configurations in the database Option table.

The Agent supports:

1. -config command-line parameter.
2. agent.json configuration file.
3. A few log-related environment variables.

Configuration File Locations

Component	Default Location	Description
Server SQLite	openflare.db	Can be modified via SQLITE_PATH
Server Uploads Directory	upload	Can be modified via UPLOAD_PATH
Agent Configuration File	./agent.json	Can be specified via -config
One-click Install Agent Config	/opt/openflare-agent/agent.json	Default generated by the installation script
Agent Data Directory	data under the config directory	Can be modified via data_dir

Server CLI Flags

cd openflare_server
go run . --port 3000 --log-dir ./logs

Flag	Purpose	Default
--port	Specify the port the Server listens on	3000
--log-dir	Specify the log directory	empty
--version	Print the current version and exit	false
--help	Print help information and exit	false

Server Environment Variables

Variable	Purpose	Default
PORT	Server listen port	3000
GIN_MODE	Gin execution mode	release unless debug
LOG_LEVEL	Log level	info
SESSION_SECRET	Session signing secret	randomly generated on startup
SQLITE_PATH	SQLite database file path	openflare.db
DSN	PostgreSQL DSN, preferred over SQLite when set	empty
SQL_DSN	Legacy PostgreSQL DSN, lower priority than DSN	empty
REDIS_CONN_STRING	Redis connection string	empty
UPLOAD_PATH	Upload directory	upload
AGENT_TOKEN	Legacy global Agent token	empty

Description:

• When both DSN and SQL_DSN exist, DSN takes precedence.
• When DSN/SQL_DSN and SQLITE_PATH exist simultaneously, PostgreSQL takes precedence.
• When the target PostgreSQL database is empty and a local SQLite file exists at SQLITE_PATH, the Server automatically migrates SQLite data at startup and prints table-by-table migration progress in the logs.
• SESSION_SECRET must be explicitly configured in production.
• When REDIS_CONN_STRING is not configured, related capabilities fall back to in-process implementations.

Runtime Options

The following options are maintained on the settings page of the management console and can be hot-updated:

Option	Purpose	Default
AgentHeartbeatInterval	Agent heartbeat interval (milliseconds)	10000
AgentWebsocketUpgradeEnabled	Whether to allow Agents to upgrade to WebSockets after successful HTTP heartbeats	true
NodeOfflineThreshold	Node offline threshold (milliseconds)	120000
AgentUpdateRepo	Agent self-update repository	Rain-kl/OpenFlare
GeoIPProvider	Node/IP region lookup provider	ipinfo
DatabaseAutoCleanupEnabled	Whether to enable daily automatic cleanup of observability data	false
DatabaseAutoCleanupRetentionDays	In-database retention days, at least 1 day	30
GlobalApiRateLimitNum / GlobalApiRateLimitDuration	Global API rate limit count / window	300 / 180
GlobalWebRateLimitNum / GlobalWebRateLimitDuration	Global Web rate limit count / window	300 / 180
UploadRateLimitNum / UploadRateLimitDuration	Upload API rate limit count / window	50 / 60
DownloadRateLimitNum / DownloadRateLimitDuration	Download API rate limit count / window	50 / 60
CriticalRateLimitNum / CriticalRateLimitDuration	Sensitive API rate limit count / window	100 / 1200

Description:

• When DatabaseAutoCleanupEnabled is enabled, the Server automatically cleans up three types of observability data (node_access_logs, node_metric_snapshots, node_request_reports) at 3:00 AM every day.
• DatabaseAutoCleanupRetentionDays is the unified retention count and must be greater than or equal to 1.
• The management console supports leaving the retention days blank during manual cleanup to directly delete all history of the corresponding datasets.
• The GitHub Release pointed to by AgentUpdateRepo must provide a matching .sha256 checksum file for each Agent binary, such as openflare-agent-linux-amd64.sha256; the self-update validates this SHA-256 digest before replacing the executable.
• Third-party logins no longer use GitHubOAuthEnabled, GitHubClientId, or GitHubClientSecret as primary configuration entries; these legacy options are only used for migration to the default GitHub authentication source during upgrades.
• Legacy options for WeChat login are retained for compatibility, but the management console no longer provides WeChat login configuration entries.
• Legacy options for Turnstile and backend verification remain, and existing configurations will continue to take effect.

OpenResty Parameters

OpenResty performance and caching parameters continue to be stored uniformly in the Option table. Currently common items include:

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

These parameters must be validated, saved, and participate in version rendering in a structured way.

Constraints:

• The management console no longer exposes resolver configuration.
• Upstreams are uniformly rendered as named upstream blocks with keepalives enabled.
• A single upstream carrying a base path or query will append the original URI in proxy_pass.
• Multiple upstreams still require each upstream to be pure scheme://host[:port], and the protocol must be consistent within the same rule.
• OpenRestyCacheEnabled is used to enable the caching infrastructure and global default parameters; the actual caching enablement and hit policies (based on URL, suffix, or path) are decided separately by each individual proxy_routes.
• The default cache key is $scheme$host$request_uri.
• The default keepalive_timeout is 20 seconds, and the default proxy_connect_timeout is 3 seconds.
• The default event model is epoll, and multi_accept is enabled by default.
• HTTPS listeners use the independent http2 on; directive by default to avoid deprecation warnings for listen ... http2 in newer Nginx/OpenResty versions.

Frontend Build Variables

Variable	Purpose	Default
NEXT_PUBLIC_API_BASE_URL	Frontend API request base path	/api
NEXT_PUBLIC_APP_VERSION	Frontend displayed version number	dev
NEXT_DEV_BACKEND_URL	Dev backend proxy target	http://127.0.0.1:3000

Agent Environment Variables

Variable	Purpose	Default
LOG_LEVEL	Agent log level	info
OPENFLARE_SERVER_URL	Control plane URL, can override agent.json	empty
OPENFLARE_AGENT_TOKEN	Node-exclusive auth token, can override agent.json	empty
OPENFLARE_DISCOVERY_TOKEN	Global token for first registration, can override agent.json	empty
OPENFLARE_NODE_NAME	Node name, can override agent.json	empty
OPENFLARE_NODE_IP	Node IP, can override agent.json	empty
OPENFLARE_DATA_DIR	Agent data directory, can override agent.json	empty
OPENFLARE_OPENRESTY_PATH	OpenResty binary path, can override agent.json	empty
OPENFLARE_HEARTBEAT_INTERVAL	Heartbeat interval, can override agent.json	empty
OPENFLARE_REQUEST_TIMEOUT	Request timeout, can override agent.json	empty
OPENFLARE_OPENRESTY_OBSERVABILITY_PORT	Local observability port, can override agent.json	empty
OPENFLARE_MMDB_PATH	WAF GeoIP mmdb path, can override agent.json	empty
OPENFLARE_MMDB_UPDATE_INTERVAL	WAF GeoIP mmdb update interval, can override agent.json	empty
OPENFLARE_MMDB_DOWNLOAD_URL	WAF GeoIP mmdb download URL, can override agent.json	empty

Agent CLI Flags

Flag	Purpose	Default
-config	Specify the path to the Agent configuration file	./agent.json

Agent Configuration Fields

Field	Purpose	Required	Default / Behavior
server_url	Control plane URL	yes	none
agent_token	Node-exclusive auth token	one of agent_token/discovery_token	empty
discovery_token	Global token for first registration	one of agent_token/discovery_token	empty
node_name	Node name	no	automatically uses host name
node_ip	Node IP	no	auto-detected; prioritizes obtaining the real public egress IP via third-party APIs, falling back to local interfaces on failure
openresty_path	OpenResty binary path	no	openresty
openresty_observability_port	Local observability and OpenResty health-check port	no	18081
data_dir	Agent data directory	no	data under the config file directory
main_config_path	OpenResty main config write path	no	data_dir/etc/nginx/nginx.conf
route_config_path	Route config write path	no	data_dir/etc/nginx/conf.d/openflare_routes.conf
access_log_path	OpenResty access log path	no	data_dir/var/log/openflare/access.log
cert_dir	Certificate write directory	no	data_dir/etc/nginx/certs
openresty_cert_dir	Certificate read directory in OpenResty config	no	same as cert_dir
lua_dir	Lua scripts and static resources write directory	no	data_dir/etc/nginx/lua
openresty_lua_dir	Lua read directory in OpenResty config	no	same as lua_dir
runtime_config_dir	Agent runtime config write directory, e.g., pow_config.json	no	data_dir/etc/openflare
mmdb_path	WAF GeoIP mmdb file path	no	data_dir/etc/openflare/GeoLite2-Country.mmdb
mmdb_update_interval	WAF GeoIP mmdb update interval	no	86400000 milliseconds
mmdb_download_url	WAF GeoIP mmdb download URL	no	built-in GeoLite2 Country download URL
observability_buffer_path	Observability buffering file path	no	data_dir/var/lib/openflare/observability-buffer.json
observability_replay_minutes	Minutes to automatically replay recent observability data	no	15
state_path	Agent local state file path	no	data_dir/var/lib/openflare/agent-state.json
heartbeat_interval	Heartbeat interval	no	10000 milliseconds
request_timeout	HTTP request timeout	no	10000 milliseconds

Description:

• agent_token and discovery_token cannot both be empty.
• heartbeat_interval and request_timeout support integer milliseconds or Go duration strings.
• When the Server runtime option AgentWebsocketUpgradeEnabled is enabled, the Agent will attempt to upgrade to a WebSocket after a successful HTTP heartbeat; it automatically falls back to HTTP heartbeats when connection fails or is disconnected.
• When openresty_path is not configured, openresty is called by default.
• The Agent's periodic health checks request http://127.0.0.1:<openresty_observability_port>/openflare/stub_status, no longer judging runtime health via high-frequency openresty -t; validation before configuration application, startup recovery, and reloads will still execute openresty -t -c <main_config_path>.
• The Agent initializes and periodically updates mmdb_path for OpenResty WAF Lua to execute country-level geographical rules; update failures only record warnings, and do not block sync or reloads.
• If agent.json does not exist but environment variables such as OPENFLARE_SERVER_URL and tokens are sufficient, the Agent can start directly; environment variables take precedence when both exist.
• When the Agent is not configured with node_ip, it first queries https://realip.cc for the real public egress IP, adapting to Docker/NAT scenarios; it falls back to local interface detection on failure, preferring a public IPv4 address.
• When the Agent automatically detects a private node_ip, the Server prioritizes retaining the public address of the Agent's direct connection during registration/heartbeat phases, avoiding misregistering internal interface addresses in NAT or multi-interface scenarios.
• When "Lock node IP" is enabled in the admin UI, the Server keeps the manually configured node IP and Agent registration, HTTP heartbeat, or WebSocket status reports will not overwrite that field; after unlocking, the next report can fill it again.

Common Configuration Combinations

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 Path

{
  "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
}

Maintenance Requirements

When the following contents change, this document must be updated in sync:

• Server command-line parameters.
• Server environment variables.
• Agent command-line parameters.
• Agent configuration fields.
• Default values, purposes, or examples of any configuration items.