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.yamlin the same directory at startup by default (overridable via theCONFIG_PATHenv var). - Env vars: every field in the config file can be overridden by an
UPPER_SNAKE_CASEenv var (env vars take precedence overconfig.yaml). - System runtime config: stored in the
w_system_configstable 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:
-configspecifies 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
| Component | Default Location | Notes |
|---|---|---|
| Server config file | ./config.yaml | overridable via CONFIG_PATH |
| Server SQLite DB | openflare.db | overridable via database.sqlite_path / SQLITE_PATH |
| Agent config file | ./agent.json | overridable via -config |
| One-click install Agent config | /opt/openflare-agent/agent.json | default path generated by the install script |
| Agent data dir | data next to the config file | overridable via data_dir |
| Relay config file | ./relay.json | overridable via -config |
| One-click install Relay config | /opt/openflare-relay/relay.json | default path generated by the install script |
| Relay runtime state file | <data_dir>/relay-state.json | maintained automatically at runtime in data directory to track node registration and state |
| Client config file | ./flared.json | overridable via -config |
| One-click install Client config | /opt/openflared/flared.json | default path generated by the install script |
| Client runtime state file | <data_dir>/flared-state.json | maintained 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 allSupported 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--userand--passwordflags).
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 path | Override env var | Description | Default |
|---|---|---|---|
app.app_name | APP_NAME | application identifier name | openflare |
app.env | APP_ENV | runtime env (development / testing / production) | production |
app.addr | APP_ADDR | service listen address and port | :3000 |
app.node_id | APP_NODE_ID | Snowflake node ID (0-1023); must be unique in multi-instance deploys | 1 |
app.api_prefix | APP_API_PREFIX | route prefix for admin panel and API | /api |
app.graceful_shutdown_timeout | APP_GRACEFUL_SHUTDOWN_TIMEOUT | graceful shutdown wait timeout (seconds) | 30 |
app.session_cookie_name | APP_SESSION_COOKIE_NAME | session cookie name | openflare_session_id |
app.session_secret | APP_SESSION_SECRET | session signature secret; must be a random long string in production | none (random) |
app.session_domain | APP_SESSION_DOMAIN | shared-session cookie scope domain | empty |
app.session_age | APP_SESSION_AGE | browser session lifetime (seconds) | 86400 (24h) |
app.session_http_only | APP_SESSION_HTTP_ONLY | enable the cookie's HttpOnly attribute | false |
app.session_secure | APP_SESSION_SECURE | enable the cookie's Secure attribute (HTTPS) | false |
2. Relational DB Config (database:)
| YAML path | Override env var | Description | Default |
|---|---|---|---|
database.enabled | DB_ENABLED | enable PostgreSQL; false falls back to SQLite | true |
database.sqlite_path | SQLITE_PATH | SQLite DB file path when PostgreSQL disabled | openflare.db |
database.host | DB_HOST | PostgreSQL host | 127.0.0.1 |
database.port | DB_PORT | PostgreSQL port | 5432 |
database.username | DB_USERNAME | PostgreSQL username | openflare |
database.password | DB_PASSWORD | PostgreSQL password | replace-with-strong-password |
database.database | DB_NAME | PostgreSQL database name | openflare |
database.max_idle_conn | DB_MAX_IDLE_CONN | connection pool max idle | 16 |
database.max_open_conn | DB_MAX_OPEN_CONN | connection pool max open | 128 |
database.conn_max_lifetime | - | max connection lifetime (seconds) | 1800 |
database.conn_max_idle_time | - | max connection idle time (seconds) | 600 |
database.log_level | DB_LOG_LEVEL | GORM SQL log level (info / warn / error / silent) | info |
database.ssl_mode | DB_SSL_MODE | PostgreSQL SSL mode | disable |
database.time_zone | DB_TIMEZONE | DB session timezone | UTC |
database.application_name | - | database connection application identifier name | openflare-server |
database.search_path | - | PostgreSQL schema search path | public |
database.prefer_simple_protocol | - | prefer simple query protocol | false |
database.statement_cache_capacity | - | prepared statement cache capacity | 256 |
database.default_query_exec_mode | - | default query execution mode | cache_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 path | Override env var | Description | Default |
|---|---|---|---|
redis.enabled | REDIS_ENABLED | enable Redis. The async queue and sync depend on it; must be on | true |
redis.addrs | REDIS_ADDR | Redis single/cluster address array (env var sets a single address) | ["127.0.0.1:6379"] |
redis.username | REDIS_USERNAME | Redis username (if any) | empty |
redis.password | REDIS_PASSWORD | Redis password | empty |
redis.db | REDIS_DB | Redis logical DB number | 0 |
redis.cluster_mode | - | enable Redis cluster mode | false |
redis.master_name | - | master name for Redis Sentinel mode (enables Sentinel when non-empty) | empty |
redis.key_prefix | REDIS_KEY_PREFIX | system key prefix in Redis | openflare: |
redis.pool_size | REDIS_POOL_SIZE | Redis connection pool size | 100 |
redis.min_idle_conn | - | minimum idle connections | 10 |
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 count | 3 |
redis.pool_timeout | - | pool timeout (seconds) | 4 |
redis.conn_max_idle_time | - | connection max idle time (seconds) | 300 |
redis.maint_notifications | REDIS_MAINT_NOTIFICATIONS | enable Redis maintenance-notifications negotiation at startup; keep off when compatibility is unclear; restart needed after change | false |
4. ClickHouse Config (clickhouse:)
Note: These are OpenFlare client connection parameters. For ClickHouse server small-host tuning: place
performance.xmlat./config/clickhouse/performance.xmland mount it as a single file to/etc/clickhouse-server/config.d/performance.xmlinside the container. See Start the Server.
| YAML path | Override env var | Description | Default |
|---|---|---|---|
clickhouse.enabled | CLICKHOUSE_ENABLED | enable 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 it | false |
clickhouse.hosts | CLICKHOUSE_HOST | ClickHouse cluster address array (env var sets a single address) | ["127.0.0.1:9000"] |
clickhouse.username | CLICKHOUSE_USERNAME | ClickHouse username | default |
clickhouse.password | CLICKHOUSE_PASSWORD | ClickHouse password | replace-with-clickhouse-password |
clickhouse.database | CLICKHOUSE_NAME | ClickHouse database name | openflare |
clickhouse.max_idle_conn | - | client idle connections (low by default for small hosts) | 8 |
clickhouse.max_open_conn | - | client max open connections | 16 |
clickhouse.conn_max_lifetime | - | connection max lifetime (seconds) | 3600 |
clickhouse.dial_timeout | - | dial timeout (seconds) | 5 |
clickhouse.block_buffer_size | - | native-protocol block buffer rows | 32 |
5. System Log Config (log:)
| YAML path | Override env var | Description | Default |
|---|---|---|---|
log.level | LOG_LEVEL | global log level (debug / info / warn / error / fatal) | info |
log.format | LOG_FORMAT | log format (console readable / json structured) | console |
log.output | LOG_OUTPUT | log 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 beyond | 100 |
log.max_age | - | max days to keep rotated log files | 30 |
log.max_backups | - | maximum number of old log files to retain | 10 |
log.compress | - | whether to compress rotated log files with gzip | true |
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 path | Override env var | Description | Default |
|---|---|---|---|
worker.concurrency | WORKER_CONCURRENCY | maximum number of concurrent task execution goroutines | 20 |
worker.strict_priority | WORKER_STRICT_PRIORITY | whether to enable strict priority processing across queues | false |
worker.queues | - | queue definitions and priority map | webhook: 10, whitelist_only: 5, default: 3 |
7. Tracing OpenTelemetry Config (otel:)
| YAML path | Override env var | Description | Default |
|---|---|---|---|
otel.export_protocol | OTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_EXPORTER_OTLP_PROTOCOL | OTLP exporter protocol (grpc or http/protobuf) | grpc |
otel.sampling_rate | OTEL_SAMPLING_RATE | OTel trace sampling rate (0.0 = disabled, 1.0 = 100%) | 0.0 |
otel.tracer_name | OTEL_TRACER_NAME | global OTel tracer instrumentation name | github.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
| Key | Type | Description | Default |
|---|---|---|---|
site_name | string | display name of the admin platform | OpenFlare |
server_address | string | public URL of the admin console, used for OAuth callbacks and download links | empty |
password_login_enabled | bool | allow admins to log in via username/password | true |
registration_enabled | bool | allow self-service user registration (default off; requires invitation/provisioning by root) | false |
password_register_enabled | bool | allow direct registration on the frontend with email/password | false |
oidc_login_enabled | bool | enable OIDC (SSO) third-party passwordless login | true |
max_api_keys_per_user | int | max API tokens per user | 5 |
login_session_ttl_hours | int | browser session lifetime (hours); 0 clears on browser close | 0 |
upload_allowed_extensions | string | allowed upload file extensions (comma-separated; empty = unlimited) | jpg,png,webp |
file_access_whitelist | json | business file types accessible without login (JSON array) | ["avatar"] |
disk_cache_max_size_mb | int | local disk cache max storage threshold (MB) | 100 |
disk_cache_ttl_minutes | int | default lifetime for local disk cache objects (minutes) | 60 |
disk_cache_lru_enabled | bool | evict oldest cache via LRU when disk cache exceeds threshold | true |
update_upstream_repository | string | GitHub repo for auto-update checks | Rain-kl/OpenFlare |
storage_config | json | structured storage config (JSON), supporting local disk and AWS S3-compatible backends | local storage |
relay_frps_web_ui_enabled | bool | enable embedded frps traffic monitor Web UI on relay nodes | false |
relay_frps_web_ui_port | int | host port for the frps monitor Web UI on relay nodes | 17500 |
search_engine_indexing_enabled | bool | allow search engines to crawl/index the site | false |
menu_display_config | string | structured menu display config (JSON string: {url: enabled}) | {} |
pages_max_package_size_mb | int | Pages deployment package upload size cap (MiB, 1-2048) | 100 |
pages_max_history_count | int | max deployment history retained per Pages project (0 = unlimited) | 20 |
2. Human Verification (PoW Captcha)
| Key | Type | Description | Default |
|---|---|---|---|
cap_login_enabled | bool | enforce local PoW compute challenge on login page to mitigate brute-force attacks | false |
cap_auto_solve | bool | automatically start background compute in the browser when page opens | true |
cap_challenge_count | int | number of PoW puzzles required (higher = longer compute time; recommended 1-5) | 1 |
cap_challenge_difficulty | int | PoW hash prefix matching difficulty (recommended 3-5) | 4 |
cap_challenge_size | int | captcha salt byte length | 32 |
cap_challenge_ttl_seconds | int | challenge validity window (seconds); expires if unanswered | 600 |
cap_token_ttl_seconds | int | login credential validity window after completing challenge (seconds) | 1200 |
3. SMTP Mail Config
| Key | Type | Description | Default |
|---|---|---|---|
smtp_host | string | outbound SMTP mail server address | empty |
smtp_port | int | outbound SMTP port (usually 465 SSL or 587 STARTTLS) | 465 |
smtp_username | string | SMTP sender mailbox address | empty |
smtp_password | string | SMTP account authorization password or credential (masked after saving) | empty |
email_login_verification_enabled | bool | send a one-time 6-digit verification code on email login for 2FA | false |
email_register_verification_enabled | bool | require email verification code on self-service registration | false |
4. Node & Agent Operations Runtime Config
| Key | Type | Description | Default |
|---|---|---|---|
agent_discovery_token | string | global auto-registration discovery token for first-time node access | none (auto-generated on first access) |
agent_heartbeat_interval | int | standard heartbeat interval pushed to connected Agents (ms) | 3000 (3s) |
agent_websocket_upgrade_enabled | bool | authorize Agent to upgrade to persistent WebSocket after successful HTTP handshake | true |
node_offline_threshold | int | unresponsive threshold before marking a node as offline in admin panel (ms) | 60000 (60s) |
agent_update_repo | string | GitHub release repo used by nodes to pull updates | Rain-kl/OpenFlare |
geoip_provider | string | GeoIP database provider, supporting maxmind etc., for WAF geographic rules | ipinfo |
5. Uptime Kuma Monitoring Sync
| Key | Type | Description | Default |
|---|---|---|---|
uptime_kuma_enabled | bool | automatically synchronize sites and create corresponding HTTP monitor targets in Uptime Kuma | false |
uptime_kuma_url | string | Uptime Kuma instance access URL (including port and path) | empty |
uptime_kuma_username | string | Uptime Kuma admin username for API authentication | empty |
uptime_kuma_password | string | Uptime Kuma admin password (masked after saving) | empty |
uptime_kuma_monitor_scope | string | scope of sites monitored (all for all sites, selected for partial list) | all |
uptime_kuma_selected_sites | string | comma-separated list of site names to monitor | empty |
uptime_kuma_sync_interval | int | differential scan and sync interval against Uptime Kuma (minutes) | 5 |
uptime_kuma_interval | int | HTTP probe request frequency (seconds) | 60 |
uptime_kuma_retry | int | retry attempts on connection failure | 0 |
uptime_kuma_retry_interval | int | interval between probe retries (seconds) | 60 |
uptime_kuma_timeout | int | HTTP 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":
| Key | Type | Description | Default |
|---|---|---|---|
edge_trusted_proxy_cidrs | string (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 trust | Cloudflare official ranges |
edge_default_limit_conn_per_server | int | default per-server concurrent connection limit when unconfigured; 0 disables | 0 |
edge_default_limit_conn_per_ip | int | default per-IP concurrent connection limit when unconfigured; 0 disables | 0 |
edge_default_limit_rate | string | default bandwidth limit per request when unconfigured (e.g. 512k); empty disables | empty |
edge_default_limit_req_per_ip | string | default per-IP request frequency limit when unconfigured (e.g. 10r/s, 100r/m); empty disables | empty |
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.
| Key | Type | Description | Default |
|---|---|---|---|
origin_error_page_enabled | bool | enable 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 untouched | true |
origin_error_page_get_only | bool | apply exclusively to GET requests. When enabled, only GET requests receive the custom error page; POST/PUT and other methods pass through raw origin responses | false |
origin_error_page_status_codes | json | status 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_html | string | custom HTML template. An empty string uses the built-in minimal white OpenFlare template; supports placeholders {{status}} and {{host}}. Max 256 KiB | empty |
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:
| Key | Type | Description | Default |
|---|---|---|---|
log_database | string | active log primary DB (postgres / sqlite / clickhouse). Internal protected key: modified exclusively by the migration task | follows relational DB (postgres when enabled, else sqlite; clickhouse preferred when ClickHouse enabled) |
log_db_migration | string | log migration freeze marker (migrating or empty). Internal protected key: while set, log write endpoints return 503 | empty |
log_retention_days_postgres | int | access log retention days in PostgreSQL log database | 30 |
log_retention_days_sqlite | int | access log retention days in SQLite log database | 30 |
log_retention_days_clickhouse | int | access log retention days in ClickHouse log database | 30 |
metric_retention_days | int | performance metrics (CPU/memory/disk/network) retention days across all three databases | 3 |
Frontend Build Env Vars
| Env var | Purpose | Default |
|---|---|---|
WAVELET_BACKEND_URL | backend address for server-side rendering and dev proxy | http://localhost:3000 |
NEXT_PUBLIC_WAVELET_BACKEND_URL | backend address for browser API requests; empty = same-origin | empty |
NEXT_PUBLIC_APP_VERSION | displayed frontend version | dev |
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, defaultinfo.- Supports
OPENFLARE_SERVER_URL,OPENFLARE_AGENT_TOKEN,OPENFLARE_DISCOVERY_TOKEN,OPENFLARE_NODE_NAME,OPENFLARE_NODE_IP,OPENFLARE_DATA_DIR,OPENFLARE_FRPS_PATHoverrides.
CLI Args
-config: Relay config file path, default./relay.json.
Config File Fields (relay.json)
| Field | Purpose | Required | Default/Behavior |
|---|---|---|---|
server_url | control-plane address | yes | none |
agent_token | relay node-specific auth Token | one of two with discovery_token | empty |
discovery_token | global Token for first-time auto-registration | one of two with agent_token | empty |
node_name | node name | no | hostname automatically |
node_ip | relay node IP for receiving tunnel traffic | no | auto-detected, prefers the public egress IP; falls back to NIC detection on failure |
frps_path | frps binary path | no | frps (found on system PATH) |
data_dir | Relay runtime data dir | no | data next to the config file |
state_path | Relay local state file path (auto-managed at runtime) | no | <data_dir>/relay-state.json |
heartbeat_interval | heartbeat interval | no | 10000 ms |
request_timeout | HTTP request timeout | no | 10000 ms |
OpenFlared (Client) Env Vars and Config Fields
Env Vars
LOG_LEVEL: Client log level, defaultinfo.- Supports
OPENFLARE_SERVER_URL,OPENFLARE_TUNNEL_TOKEN,OPENFLARE_DATA_DIR,OPENFLARE_FRPC_PATHoverrides.
CLI Args
-config: Client config file path, default./flared.json.
Config File Fields (flared.json)
| Field | Purpose | Required | Default/Behavior |
|---|---|---|---|
server_url | control-plane address | yes | none |
tunnel_token | tunnel-specific auth Token | yes | none |
frpc_path | frpc binary path | no | frpc (found on system PATH) |
data_dir | Client runtime data dir | no | data next to the config file |
state_path | Client local state file path (auto-managed at runtime) | no | <data_dir>/flared-state.json |
heartbeat_interval | heartbeat interval | no | 10000 ms |
sync_interval | config pull/sync interval | no | 30000 ms |
request_timeout | HTTP request timeout | no | 10000 ms |