Manager Configuration
Manager configuration reference
Restart. YAML changes require Manager restart unless a specific key documents otherwise. Enterprise unit supports systemctl reload (HUP); treat HUP as “request reload,” not a certified live-apply of every key.
Source authority. configs/manager.example.yml plus Manager configuration load behavior.
Secrets in Enterprise production stay in systemd credentials; keep YAML empty for database.password, auth.jwt_secret, auth.default_admin.password.
Cluster YAML (cluster.*) and updater YAML (updater.*) exist in source. They are not public products. Do not enable internal AI development configuration blocks as AI Preview setup.
Column meanings: Restart/reload = process restart unless noted. Interactions = other keys or subsystems.
server
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
server.host | Manager | API listen address | string | no | 0.0.0.0 | IP or 0.0.0.0 | 0.0.0.0 | no | restart | Shared | with server.api_port | manager.example.yml |
server.port | Manager | Legacy single port | int | no | 8443 | 1–65535 | 8443 | no | restart | Shared | used if api_port unset | manager.example.yml |
server.api_port | Manager | API listen port | int | no | 8443 | 1–65535 | 8443 | no | restart | Shared | zwallctl defaults to :8080; pass --manager-url | manager.example.yml |
server.split_mode_enabled | Manager | Separate API and web ports | bool | no | false | true/false | false | no | restart | Shared | requires web.enabled and distinct web.port | manager.example.yml |
server.timeout | Manager | Request timeout | duration | no | 30s | Go duration | 30s | no | restart | Shared | manager.example.yml | |
server.tls.enabled | Manager | TLS on the API listener | bool | no | true (example) | true/false | true | no | restart | Shared | cookie issuance needs HTTPS | manager.example.yml |
server.tls.cert_file | Manager | TLS certificate | path | if TLS | /etc/ssl/certs/manager.crt | path | /etc/ssl/certs/manager.crt | no | restart | Shared | manager.example.yml | |
server.tls.key_file | Manager | TLS private key | path | if TLS | /etc/ssl/private/manager.key | path | /etc/ssl/private/manager.key | yes | restart | Shared | systemd credentials preferred | manager.example.yml |
server.cors.enabled | Manager | CORS | bool | no | true | true/false | true | no | restart | Shared | manager.example.yml | |
server.cors.allowed_origins | Manager | Browser origins | list | production | https://manager.example.com | absolute origins | https://manager.example.com | no | restart | Shared | wildcard blocked in TLS/production | manager.example.yml |
server.cors.allow_credentials | Manager | CORS credentials | bool | no | true | true/false | true | no | restart | Shared | cookies | manager.example.yml |
server.trusted_client_ip.enabled | Manager | One-hop proxy trust for registration IP | bool | no | false | true/false | false | no | restart | Shared | keep off unless loopback-behind-edge | manager.example.yml |
server.trusted_client_ip.trusted_proxy_cidrs | Manager | Trusted immediate peers | CIDR list | if enabled | [] | /32 or /128 | no | restart | Shared | max_hops=1 | manager.example.yml |
database
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
database.host | Manager | PostgreSQL host | string | yes | localhost | hostname/IP | localhost | no | restart | Shared | manager.example.yml | |
database.port | Manager | PostgreSQL port | int | yes | 5432 | 1–65535 | 5432 | no | restart | Shared | manager.example.yml | |
database.name | Manager | Database name | string | yes | zwall_centralized_security | ident | zwall_centralized_security | no | restart | Shared | manager.example.yml | |
database.user | Manager | Database user | string | yes | zwall_user | ident | zwall_user | no | restart | Shared | manager.example.yml | |
database.password | Manager | Database password | string | yes (via secret) | empty YAML | yes | restart | Shared | systemd database_password | manager.example.yml | ||
database.ssl_mode | Manager | libpq SSL mode | enum | yes | require | disable | require | verify-ca | verify-full | require | no | restart | Shared | production: not disable | manager.example.yml + DatabaseConfig |
database.max_connections | Manager | Pool max | int | no | 25 | >0 | 25 | no | restart | Shared | manager.example.yml | |
database.max_idle_connections | Manager | Pool idle | int | no | 5 | ≥0 | 5 | no | restart | Shared | manager.example.yml |
auth / agents
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
auth.jwt_secret | Manager | Admin JWT HMAC secret | string | yes | empty YAML | high entropy | yes | restart | Shared | systemd jwt_secret | manager.example.yml | |
auth.token_expiry | Manager | Admin JWT TTL | duration | no | example 8h | Go duration | 8h | no | restart | Shared | login expires_at | manager.example.yml |
auth.agent_token_ttl | Manager | Agent JWT TTL | duration | no | 8h | comment 4h–8h | 8h | no | restart | Shared | Agent refresh | manager.example.yml |
auth.agent_refresh_before | Manager | Rotate when remaining < this | duration | no | 20m | 20m | no | restart | Shared | heartbeat refresh | manager.example.yml | |
auth.agent_expired_grace | Manager | Heartbeat-only grace | duration | no | 2m | 2m | no | restart | Shared | manager.example.yml | ||
auth.default_admin.username | Manager | First-install admin | string | no | admin | admin | no | first-install | Shared | login recreates if missing | manager.example.yml | |
auth.default_admin.password | Manager | First-install password | string | first-install | empty YAML | strength-checked | yes | first-install | Shared | detached after readiness | manager.example.yml | |
agents.auto_register | Manager | Open registration | bool | no | false | true/false | false | no | restart | Shared | keep false; use pre-register | manager.example.yml |
agents.timeout | Manager | Offline after silence | duration | no | 2m | 2m | no | restart | Shared | dashboard online flag | manager.example.yml |
logging / web / maintenance / health / metrics
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
logging.level | Manager | Log verbosity | string | no | info | debug/info/warn/error | info | no | restart | Shared | manager.example.yml | |
logging.file | Manager | Log file | path | no | /var/log/zcs/firewall-manager.log | path or empty stdout | no | restart | Shared | unit may use /var/log/zwall-manager | manager.example.yml | |
web.enabled | Manager | Serve console | bool | no | true | true/false | true | no | restart | Shared | split mode | manager.example.yml |
web.port | Manager | Web listen port | int | no | 8443 | 1–65535 | 8443 | no | restart | Shared | must differ from API in split mode | manager.example.yml |
web.static_dir | Manager | SPA files | path | no | /opt/zcs/web | path | /opt/zcs/web | no | restart | Shared | /opt/zwall-manager vs /opt/zcs | manager.example.yml |
maintenance.backup_dir | Manager | API backup helper dir | path | no | /var/backups/zwall | path | /var/backups/zwall | no | n/a | Shared | not backup_db.sh | manager.example.yml |
health.readiness_timeout | Manager | /health/ready timeout | duration | no | 5s when unset | Go duration | 5s | no | restart | Shared | cluster checks if cluster enabled | HealthConfig.ApplyDefaults |
metrics.enabled | Manager | Prometheus scrape | bool | no | example true | true/false | true | no | restart | Shared | skipped if false | MetricsConfig |
metrics.path | Manager | Scrape path | string | no | /metrics | path | /metrics | no | restart | Shared | admin JWT + RoleAuth admin | MetricsConfig.ApplyDefaults |
notifications
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
notifications.email.enabled | Manager | SMTP notifications | bool | no | false | true/false | false | no | restart | Shared | NotificationConfig | |
notifications.email.smtp_host | Manager | SMTP host | string | if enabled | smtp.example.com | no | restart | Shared | EmailConfig | |||
notifications.email.smtp_port | Manager | SMTP port | int | if enabled | 587 | no | restart | Shared | EmailConfig | |||
notifications.email.username | Manager | SMTP user | string | if auth | no | restart | Shared | EmailConfig | ||||
notifications.email.password | Manager | SMTP password | string | if auth | empty | yes | restart | Shared | systemd slot | EmailConfig | ||
notifications.email.from | Manager | From address | string | if enabled | zwall@example.com | no | restart | Shared | EmailConfig | |||
notifications.email.recipients | Manager | Default recipients | list | if enabled | emails | no | restart | Shared | EmailConfig | |||
notifications.webhook.enabled | Manager | Webhook notifications | bool | no | false | true/false | false | no | restart | Shared | WebhookConfig | |
notifications.webhook.url | Manager | Webhook URL | URL | if enabled | https URL | https://hooks.example.com/zwall | yes | restart | Shared | WebhookConfig | ||
notifications.webhook.timeout | Manager | HTTP timeout | duration | no | 10s | 10s | no | restart | Shared | ApplyManagerDefaults | WebhookConfig |
security integrations (group, not every nested threshold)
Brute-force, login-rate-limit, UDP flood, SMTP, SSH/sudo alerts, temp-to-perm, subnet escalation, and distributed-attack each have enabled + numeric thresholds. Operators should copy the example YAML block for a service rather than inventing PPS/SLA numbers. Nested failure_threshold / time_window / block_duration are ints (often seconds). Restart required. Edition SHARED unless Cloudflare/messenger (Enterprise HTTP).
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
security.geoip.enabled | Manager | GeoIP blocking | bool | no | false | true/false | false | no | restart | Shared | needs database | GeoIPConfig |
security.geoip.database_type | Manager | DB vendor | string | no | maxmind | maxmind / db-ip | maxmind | no | restart | Shared | GeoIPConfig | |
security.geoip.database_path | Manager | MMDB path | path | if enabled | no | restart | Shared | GeoIPConfig | ||||
security.geoip.maxmind_account_id | Manager | MaxMind account | string | if auto-update | no | restart | Shared | GeoIPConfig | ||||
security.geoip.maxmind_license_key | Manager | MaxMind license | string | if auto-update | yes | restart | Shared | systemd | GeoIPConfig | |||
security.geoip.allow_on_lookup_failure | Manager | Fail-open lookup | bool | no | true/false | no | restart | Shared | GeoIPConfig | |||
security.blocklists.enabled | Manager | External blocklists | bool | no | false | true/false | false | no | restart | Shared | sources[] | BlocklistsConfig |
security.blocklists.sources | Manager | HTTP/file sources | list | if enabled | [] | {name,url,enabled,format} | no | restart | Shared | BlocklistSourceConfig | ||
security.rbl.enabled | Manager | DNS RBL | bool | no | false | true/false | false | no | restart | Shared | sources[].zone | RBLConfig |
security.cloudflare.enabled | Manager | Cloudflare sync | bool | no | false | true/false | false | no | restart | ENTERPRISE | Connect API still required | CloudFlareConfig |
security.cloudflare.api_token | Manager | CF API token | string | if enabled | empty | yes | restart | ENTERPRISE | prefer API connect + credentials | CloudFlareConfig | ||
security.cloudflare.zone_id | Manager | Zone ID | string | if enabled | no | restart | ENTERPRISE | CloudFlareConfig | ||||
security.cloudflare.account_id | Manager | Account ID | string | no | no | restart | ENTERPRISE | optional | CloudFlareConfig | |||
security.modsecurity.enabled | Manager | ModSecurity ingest | bool | no | false | true/false | false | no | restart | Shared | ModSecurityConfig | |
security.modsecurity.webhook_secret | Manager | Webhook HMAC | string | if webhook | yes | restart | Shared | ModSecurityConfig | ||||
security.messenger.enabled | Manager | Unblock portal | bool | no | false | true/false | false | no | restart | ENTERPRISE | captcha keys | MessengerConfig |
security.messenger.captcha_provider | Manager | Captcha vendor | string | if enabled | recaptcha | hcaptcha | recaptcha | no | restart | ENTERPRISE | MessengerConfig | ||
security.messenger.recaptcha_secret_key / hcaptcha_secret_key | Manager | Captcha secrets | string | if enabled | yes | restart | ENTERPRISE | site keys may be public | MessengerConfig | |||
security.brute_force.* | Manager | Per-service BF | grouped | no | disabled | see YAML | no | restart | Shared | ssh/ftp/smtp/http/pop3/imap each: enabled, failure_threshold, time_window, block_duration | BruteForceConfig |
Do not document security.uid_gid_filtering as V3 enablement.
ai (Enterprise Preview)
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ai.enabled | Manager | Master switch | bool | no | false | true/false | false | no | restart | ENTERPRISE | forces human approval | manager.example.yml |
ai.provider | Manager | Provider class | string | no | openai_compatible | openai_compatible | openai_compatible | no | restart | ENTERPRISE | only supported class | manager.example.yml |
ai.base_url | Manager | Chat-completions base | URL | if enabled | http://127.0.0.1:8000/v1 | URL | no | restart | ENTERPRISE | offline loopback | manager.example.yml | |
ai.require_human_approval | Manager | Human gate | bool | no | true | must stay true when enabled | true | no | restart | ENTERPRISE | manager.example.yml | |
ai.offline_mode | Manager | Loopback validation | bool | no | true | true/false | true | no | restart | ENTERPRISE | private-network override | manager.example.yml |
ai.training_export.enabled | Manager | Training export | bool | no | false | must false | false | no | restart | ENTERPRISE | customer custody | AITrainingExportConfig |
Public Preview operator keys: AI Preview operator control. Do not enable internal AI development configuration blocks as Preview setup.