Skip to Content
OpenFlare
GuidesDeploymentReferenceArchitectureChangelog

Configuration

You will learn: which config sources OpenFlare Server, frontend build, Agent, Relay, and OpenFlared support, what config fields and env vars exist, and their defaults and behavior.

This document summarizes all configuration items supported by the current OpenFlare version.


Config Sources

1. Server Config Sources

  • Config file: reads config.yaml in the same directory at startup by default (overridable via the CONFIG_PATH env var).
  • Env vars: every field in the config file can be overridden by an UPPER_SNAKE_CASE env var (env vars take precedence over config.yaml).
  • System runtime config: stored in the w_system_configs table in the relational DB. These can be hot-updated and take effect dynamically via the admin UI or system API.

2. Agent / Relay / OpenFlared Config Sources

  • CLI args: -config specifies the config file (JSON format).
  • Config file: e.g. relay.json, flared.json.
  • Override env vars: specific env vars can override connection addresses and Token credentials in the config file.

Config and State File Locations

ComponentDefault LocationNotes
Server config file./config.yamloverridable via CONFIG_PATH
Server SQLite DBopenflare.dboverridable via database.sqlite_path / SQLITE_PATH
Agent config file./agent.jsonoverridable via -config
One-click install Agent config/opt/openflare-agent/agent.jsondefault path generated by the install script
Agent data dirdata next to the config fileoverridable via data_dir
Relay config file./relay.jsonoverridable via -config
One-click install Relay config/opt/openflare-relay/relay.jsondefault path generated by the install script
Relay runtime state file<data_dir>/relay-state.jsonmaintained automatically at runtime in data directory to track node registration and state
Client config file./flared.jsonoverridable via -config
One-click install Client config/opt/openflared/flared.jsondefault path generated by the install script
Client runtime state file<data_dir>/flared-state.jsonmaintained automatically at runtime in data directory to track tunnel session state

Server CLI Args

# specify a config file when starting the Server
CONFIG_PATH=/path/to/custom-config.yaml ./bin/openflare-server all

Supported sub-service commands (fused/single-process mode):

  • all: starts all services in one process (API + Worker + Scheduler, default).
  • api: starts only the API service for the admin panel and node communication.
  • worker: starts only the background-task Asynq Worker service.
  • scheduler: starts only the scheduled-task Scheduler service.
  • reset-passwd: resets the password of a specified account (supports --user and --password flags).

Server Env Vars vs Config File

All Server core base config is defined in config.yaml, and every field supports env-var overrides (env vars take precedence over the YAML file).

1. App Basic Config (app:)

YAML pathOverride env varDescriptionDefault
app.app_nameAPP_NAMEapplication identifier nameopenflare
app.envAPP_ENVruntime env (development / testing / production)production
app.addrAPP_ADDRservice listen address and port:3000
app.node_idAPP_NODE_IDSnowflake node ID (0-1023); must be unique in multi-instance deploys1
app.api_prefixAPP_API_PREFIXroute prefix for admin panel and API/api
app.graceful_shutdown_timeoutAPP_GRACEFUL_SHUTDOWN_TIMEOUTgraceful shutdown wait timeout (seconds)30
app.session_cookie_nameAPP_SESSION_COOKIE_NAMEsession cookie nameopenflare_session_id
app.session_secretAPP_SESSION_SECRETsession signature secret; must be a random long string in productionnone (random)
app.session_domainAPP_SESSION_DOMAINshared-session cookie scope domainempty
app.session_ageAPP_SESSION_AGEbrowser session lifetime (seconds)86400 (24h)
app.session_http_onlyAPP_SESSION_HTTP_ONLYenable the cookie's HttpOnly attributefalse
app.session_secureAPP_SESSION_SECUREenable the cookie's Secure attribute (HTTPS)false

2. Relational DB Config (database:)

YAML pathOverride env varDescriptionDefault
database.enabledDB_ENABLEDenable PostgreSQL; false falls back to SQLitetrue
database.sqlite_pathSQLITE_PATHSQLite DB file path when PostgreSQL disabledopenflare.db
database.hostDB_HOSTPostgreSQL host127.0.0.1
database.portDB_PORTPostgreSQL port5432
database.usernameDB_USERNAMEPostgreSQL usernameopenflare
database.passwordDB_PASSWORDPostgreSQL passwordreplace-with-strong-password
database.databaseDB_NAMEPostgreSQL database nameopenflare
database.max_idle_connDB_MAX_IDLE_CONNconnection pool max idle16
database.max_open_connDB_MAX_OPEN_CONNconnection pool max open128
database.conn_max_lifetime-max connection lifetime (seconds)1800
database.conn_max_idle_time-max connection idle time (seconds)600
database.log_levelDB_LOG_LEVELGORM SQL log level (info / warn / error / silent)info
database.ssl_modeDB_SSL_MODEPostgreSQL SSL modedisable
database.time_zoneDB_TIMEZONEDB session timezoneUTC
database.application_name-database connection application identifier nameopenflare-server
database.search_path-PostgreSQL schema search pathpublic
database.prefer_simple_protocol-prefer simple query protocolfalse
database.statement_cache_capacity-prepared statement cache capacity256
database.default_query_exec_mode-default query execution modecache_statement
database.slow_threshold-slow query execution threshold (Duration)200ms

SQLite file databases enable WAL mode automatically on startup; in-memory databases retain memory mode. Ensure the database directory is writable to allow -wal and -shm creation. For online backups, use the admin database export endpoint (which generates an internally consistent snapshot), rather than copying raw active .db files.

3. Redis Config (redis:)

YAML pathOverride env varDescriptionDefault
redis.enabledREDIS_ENABLEDenable Redis. The async queue and sync depend on it; must be ontrue
redis.addrsREDIS_ADDRRedis single/cluster address array (env var sets a single address)["127.0.0.1:6379"]
redis.usernameREDIS_USERNAMERedis username (if any)empty
redis.passwordREDIS_PASSWORDRedis passwordempty
redis.dbREDIS_DBRedis logical DB number0
redis.cluster_mode-enable Redis cluster modefalse
redis.master_name-master name for Redis Sentinel mode (enables Sentinel when non-empty)empty
redis.key_prefixREDIS_KEY_PREFIXsystem key prefix in Redisopenflare:
redis.pool_sizeREDIS_POOL_SIZERedis connection pool size100
redis.min_idle_conn-minimum idle connections10
redis.dial_timeout-dial timeout (seconds)5
redis.read_timeout-read timeout (seconds)3
redis.write_timeout-write timeout (seconds)3
redis.max_retries-command retry count3
redis.pool_timeout-pool timeout (seconds)4
redis.conn_max_idle_time-connection max idle time (seconds)300
redis.maint_notificationsREDIS_MAINT_NOTIFICATIONSenable Redis maintenance-notifications negotiation at startup; keep off when compatibility is unclear; restart needed after changefalse

4. ClickHouse Config (clickhouse:)

Note: These are OpenFlare client connection parameters. For ClickHouse server small-host tuning: place performance.xml at ./config/clickhouse/performance.xml and mount it as a single file to /etc/clickhouse-server/config.d/performance.xml inside the container. See Start the Server.

YAML pathOverride env varDescriptionDefault
clickhouse.enabledCLICKHOUSE_ENABLEDenable ClickHouse. Node metrics and access logs are written here at scale. Off by default: missing config or false disables it and the primary DB handles logs/metrics; explicit true or setting CLICKHOUSE_HOST enables itfalse
clickhouse.hostsCLICKHOUSE_HOSTClickHouse cluster address array (env var sets a single address)["127.0.0.1:9000"]
clickhouse.usernameCLICKHOUSE_USERNAMEClickHouse usernamedefault
clickhouse.passwordCLICKHOUSE_PASSWORDClickHouse passwordreplace-with-clickhouse-password
clickhouse.databaseCLICKHOUSE_NAMEClickHouse database nameopenflare
clickhouse.max_idle_conn-client idle connections (low by default for small hosts)8
clickhouse.max_open_conn-client max open connections16
clickhouse.conn_max_lifetime-connection max lifetime (seconds)3600
clickhouse.dial_timeout-dial timeout (seconds)5
clickhouse.block_buffer_size-native-protocol block buffer rows32

5. System Log Config (log:)

YAML pathOverride env varDescriptionDefault
log.levelLOG_LEVELglobal log level (debug / info / warn / error / fatal)info
log.formatLOG_FORMATlog format (console readable / json structured)console
log.outputLOG_OUTPUTlog output (stdout / file)stdout
log.file_path-log file path when output is file./logs/app.log
log.max_size-max single log file size (MB); auto-rotates beyond100
log.max_age-max days to keep rotated log files30
log.max_backups-maximum number of old log files to retain10
log.compress-whether to compress rotated log files with gziptrue

Server, Agent, scheduler, task framework, and storage maintenance runtime logs use fixed English descriptions for consistent cross-language troubleshooting. Changing UI language does not alter terminal logs or OTel exceptions; API errors, task details, and built-in metadata are localized on display without rewriting history. User-supplied names and third-party errors keep their original strings. See Runtime Language & Internationalization.

6. Async Task Worker Config (worker:)

YAML pathOverride env varDescriptionDefault
worker.concurrencyWORKER_CONCURRENCYmaximum number of concurrent task execution goroutines20
worker.strict_priorityWORKER_STRICT_PRIORITYwhether to enable strict priority processing across queuesfalse
worker.queues-queue definitions and priority mapwebhook: 10, whitelist_only: 5, default: 3

7. Tracing OpenTelemetry Config (otel:)

YAML pathOverride env varDescriptionDefault
otel.export_protocolOTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_EXPORTER_OTLP_PROTOCOLOTLP exporter protocol (grpc or http/protobuf)grpc
otel.sampling_rateOTEL_SAMPLING_RATEOTel trace sampling rate (0.0 = disabled, 1.0 = 100%)0.0
otel.tracer_nameOTEL_TRACER_NAMEglobal OTel tracer instrumentation namegithub.com/Rain-kl/OpenFlare

System Runtime Config (SystemConfig)

These items are stored in the relational database's w_system_configs table. All items automatically invalidate the Redis cache on update to take effect dynamically, and administrators can manage them from the admin console.

1. Basic & Business Runtime Config

KeyTypeDescriptionDefault
site_namestringdisplay name of the admin platformOpenFlare
server_addressstringpublic URL of the admin console, used for OAuth callbacks and download linksempty
password_login_enabledboolallow admins to log in via username/passwordtrue
registration_enabledboolallow self-service user registration (default off; requires invitation/provisioning by root)false
password_register_enabledboolallow direct registration on the frontend with email/passwordfalse
oidc_login_enabledboolenable OIDC (SSO) third-party passwordless logintrue
max_api_keys_per_userintmax API tokens per user5
login_session_ttl_hoursintbrowser session lifetime (hours); 0 clears on browser close0
upload_allowed_extensionsstringallowed upload file extensions (comma-separated; empty = unlimited)jpg,png,webp
file_access_whitelistjsonbusiness file types accessible without login (JSON array)["avatar"]
disk_cache_max_size_mbintlocal disk cache max storage threshold (MB)100
disk_cache_ttl_minutesintdefault lifetime for local disk cache objects (minutes)60
disk_cache_lru_enabledboolevict oldest cache via LRU when disk cache exceeds thresholdtrue
update_upstream_repositorystringGitHub repo for auto-update checksRain-kl/OpenFlare
storage_configjsonstructured storage config (JSON), supporting local disk and AWS S3-compatible backendslocal storage
relay_frps_web_ui_enabledboolenable embedded frps traffic monitor Web UI on relay nodesfalse
relay_frps_web_ui_portinthost port for the frps monitor Web UI on relay nodes17500
search_engine_indexing_enabledboolallow search engines to crawl/index the sitefalse
menu_display_configstringstructured menu display config (JSON string: {url: enabled}){}
pages_max_package_size_mbintPages deployment package upload size cap (MiB, 1-2048)100
pages_max_history_countintmax deployment history retained per Pages project (0 = unlimited)20

2. Human Verification (PoW Captcha)

KeyTypeDescriptionDefault
cap_login_enabledboolenforce local PoW compute challenge on login page to mitigate brute-force attacksfalse
cap_auto_solveboolautomatically start background compute in the browser when page openstrue
cap_challenge_countintnumber of PoW puzzles required (higher = longer compute time; recommended 1-5)1
cap_challenge_difficultyintPoW hash prefix matching difficulty (recommended 3-5)4
cap_challenge_sizeintcaptcha salt byte length32
cap_challenge_ttl_secondsintchallenge validity window (seconds); expires if unanswered600
cap_token_ttl_secondsintlogin credential validity window after completing challenge (seconds)1200

3. SMTP Mail Config

KeyTypeDescriptionDefault
smtp_hoststringoutbound SMTP mail server addressempty
smtp_portintoutbound SMTP port (usually 465 SSL or 587 STARTTLS)465
smtp_usernamestringSMTP sender mailbox addressempty
smtp_passwordstringSMTP account authorization password or credential (masked after saving)empty
email_login_verification_enabledboolsend a one-time 6-digit verification code on email login for 2FAfalse
email_register_verification_enabledboolrequire email verification code on self-service registrationfalse

4. Node & Agent Operations Runtime Config

KeyTypeDescriptionDefault
agent_discovery_tokenstringglobal auto-registration discovery token for first-time node accessnone (auto-generated on first access)
agent_heartbeat_intervalintstandard heartbeat interval pushed to connected Agents (ms)3000 (3s)
agent_websocket_upgrade_enabledboolauthorize Agent to upgrade to persistent WebSocket after successful HTTP handshaketrue
node_offline_thresholdintunresponsive threshold before marking a node as offline in admin panel (ms)60000 (60s)
agent_update_repostringGitHub release repo used by nodes to pull updatesRain-kl/OpenFlare
geoip_providerstringGeoIP database provider, supporting maxmind etc., for WAF geographic rulesipinfo

5. Uptime Kuma Monitoring Sync

KeyTypeDescriptionDefault
uptime_kuma_enabledboolautomatically synchronize sites and create corresponding HTTP monitor targets in Uptime Kumafalse
uptime_kuma_urlstringUptime Kuma instance access URL (including port and path)empty
uptime_kuma_usernamestringUptime Kuma admin username for API authenticationempty
uptime_kuma_passwordstringUptime Kuma admin password (masked after saving)empty
uptime_kuma_monitor_scopestringscope of sites monitored (all for all sites, selected for partial list)all
uptime_kuma_selected_sitesstringcomma-separated list of site names to monitorempty
uptime_kuma_sync_intervalintdifferential scan and sync interval against Uptime Kuma (minutes)5
uptime_kuma_intervalintHTTP probe request frequency (seconds)60
uptime_kuma_retryintretry attempts on connection failure0
uptime_kuma_retry_intervalintinterval between probe retries (seconds)60
uptime_kuma_timeoutintHTTP probe timeout threshold (seconds)48

6. Edge Security and Rate Limiting Options

OpenFlare edge proxies operate exclusively on the Pingora architecture. Obsolete OpenResty / Nginx configuration directives (such as worker_processes, worker_connections, worker_rlimit_nofile, and keepalive_timeout) have been removed. Edge runtime parameters, upstream connection pools, HTTP/2, TLS listeners, and proxy caching policies are managed via the console under "Performance Policies" and distributed to edge nodes (see Pingora Performance Policies).

The system retains generalized edge security and traffic limit settings (edge_*), configurable under "System Management → System Configuration → Business Configuration":

KeyTypeDescriptionDefault
edge_trusted_proxy_cidrsstring (JSON array)IPv4/IPv6 CIDR list authorized to pass CF-Connecting-IP; defaults to Cloudflare's 22 official IPv4/IPv6 ranges; setting explicitly to [] disables trustCloudflare official ranges
edge_default_limit_conn_per_serverintdefault per-server concurrent connection limit when unconfigured; 0 disables0
edge_default_limit_conn_per_ipintdefault per-IP concurrent connection limit when unconfigured; 0 disables0
edge_default_limit_ratestringdefault bandwidth limit per request when unconfigured (e.g. 512k); empty disablesempty
edge_default_limit_req_per_ipstringdefault per-IP request frequency limit when unconfigured (e.g. 10r/s, 100r/m); empty disablesempty

In the admin panel, edit edge_trusted_proxy_cidrs under "System Management → System Configuration → Business Configuration". The default value contains Cloudflare's official 22 IPv4 and IPv6 CIDRs. To trust additional reverse proxy hops, append their CIDRs to the array (e.g. 10.2.0.227/32). Explicit [] disables trusted proxy header handling. Pingora extracts CF-Connecting-IP only from trusted origins, applying the recovered client address to access logs, WAF rules, and upstream X-Real-IP.

7. Origin Error Page

Global origin error page configuration. Automatically synced to edge nodes via site snapshots. Affects only reverse proxy routes; Pages static site routes remain unaffected. Admin entry: "Website Management → Error Pages". See Origin Error Page Design.

KeyTypeDescriptionDefault
origin_error_page_enabledboolenable the global origin error page. When enabled, matching status codes from the origin or gateway are replaced with custom/default HTML while the HTTP status code is preserved; when disabled, origin responses pass through untouchedtrue
origin_error_page_get_onlyboolapply exclusively to GET requests. When enabled, only GET requests receive the custom error page; POST/PUT and other methods pass through raw origin responsesfalse
origin_error_page_status_codesjsonstatus code selector JSON array. Supports individual codes (e.g. 522) and closed ranges (e.g. 500-599); range limits must be in 400–599 with lo ≤ hi["500-599"]
origin_error_page_htmlstringcustom HTML template. An empty string uses the built-in minimal white OpenFlare template; supports placeholders {{status}} and {{host}}. Max 256 KiBempty

8. Log Database

Runtime configuration for log storage decoupling. The active log database is managed by the "Switch Log Database" background task (internal protected keys, forbidden for manual editing). Retention periods are configured per storage engine in business configuration:

KeyTypeDescriptionDefault
log_databasestringactive log primary DB (postgres / sqlite / clickhouse). Internal protected key: modified exclusively by the migration taskfollows relational DB (postgres when enabled, else sqlite; clickhouse preferred when ClickHouse enabled)
log_db_migrationstringlog migration freeze marker (migrating or empty). Internal protected key: while set, log write endpoints return 503empty
log_retention_days_postgresintaccess log retention days in PostgreSQL log database30
log_retention_days_sqliteintaccess log retention days in SQLite log database30
log_retention_days_clickhouseintaccess log retention days in ClickHouse log database30
metric_retention_daysintperformance metrics (CPU/memory/disk/network) retention days across all three databases3

Frontend Build Env Vars

Env varPurposeDefault
WAVELET_BACKEND_URLbackend address for server-side rendering and dev proxyhttp://localhost:3000
NEXT_PUBLIC_WAVELET_BACKEND_URLbackend address for browser API requests; empty = same-originempty
NEXT_PUBLIC_APP_VERSIONdisplayed frontend versiondev

Pingora Edge Startup Arguments

openflare-edge run connects to the control plane using --server-url, --token-type discovery|node, --token-file, and --state-dir. Listening sockets are specified via --http-listen and optionally --tls-listen. Installer-managed services default to ports 80 and 443 with state stored in /var/lib/openflare-edge. Pass --upgrade when upgrading active configurations.


Relay Env Vars and Config Fields

Env Vars

  • LOG_LEVEL: Relay log level, default info.
  • Supports OPENFLARE_SERVER_URL, OPENFLARE_AGENT_TOKEN, OPENFLARE_DISCOVERY_TOKEN, OPENFLARE_NODE_NAME, OPENFLARE_NODE_IP, OPENFLARE_DATA_DIR, OPENFLARE_FRPS_PATH overrides.

CLI Args

  • -config: Relay config file path, default ./relay.json.

Config File Fields (relay.json)

FieldPurposeRequiredDefault/Behavior
server_urlcontrol-plane addressyesnone
agent_tokenrelay node-specific auth Tokenone of two with discovery_tokenempty
discovery_tokenglobal Token for first-time auto-registrationone of two with agent_tokenempty
node_namenode namenohostname automatically
node_iprelay node IP for receiving tunnel trafficnoauto-detected, prefers the public egress IP; falls back to NIC detection on failure
frps_pathfrps binary pathnofrps (found on system PATH)
data_dirRelay runtime data dirnodata next to the config file
state_pathRelay local state file path (auto-managed at runtime)no<data_dir>/relay-state.json
heartbeat_intervalheartbeat intervalno10000 ms
request_timeoutHTTP request timeoutno10000 ms

OpenFlared (Client) Env Vars and Config Fields

Env Vars

  • LOG_LEVEL: Client log level, default info.
  • Supports OPENFLARE_SERVER_URL, OPENFLARE_TUNNEL_TOKEN, OPENFLARE_DATA_DIR, OPENFLARE_FRPC_PATH overrides.

CLI Args

  • -config: Client config file path, default ./flared.json.

Config File Fields (flared.json)

FieldPurposeRequiredDefault/Behavior
server_urlcontrol-plane addressyesnone
tunnel_tokentunnel-specific auth Tokenyesnone
frpc_pathfrpc binary pathnofrpc (found on system PATH)
data_dirClient runtime data dirnodata next to the config file
state_pathClient local state file path (auto-managed at runtime)no<data_dir>/flared-state.json
heartbeat_intervalheartbeat intervalno10000 ms
sync_intervalconfig pull/sync intervalno30000 ms
request_timeoutHTTP request timeoutno10000 ms

On this page