Administration

Manager administration

Purpose #

Operate the Manager after install: start and reload the service, use the console, manage administrator users, inspect settings and health, and keep secrets out of YAML on Enterprise.

This is the control plane. It does not attach eBPF and does not drop packets.

Audience #

Linux administrators who own zwall-manager.service (or the Community bin/manager process) and the PostgreSQL database it uses.

Edition #

Status #

SUPPORTED for single-Manager operation as documented here. Cluster and in-product updater remain non-customer products.

Prerequisites #

• PostgreSQL prepared (Database preparation)
• Schema admitted (-migrate or Enterprise database installer)
• TLS files if server.tls.enabled: true
• Enterprise: zwall-manager system user (nologin, home /nonexistent as established by the config installer)

Required permissions #

Host: root (or equivalent) to systemctl the unit. API: admin role for users, settings, maintenance, metrics, and almost all fleet/policy routes.

Dependencies #

PostgreSQL (example name zwall_centralized_security, port 5432). The Manager does not use SQLite as its production database.

Configuration #

Enterprise unit (zwall-manager.service):

Community README typically uses /etc/zcs/manager.yml and default -config configs/manager.yaml if the flag is omitted. Do not invent a third layout.

Example listen: server.host: 0.0.0.0, server.port / server.api_port / web.port: 8443 with TLS.

Binary flags #

Default -config on Enterprise is configs/manager.yml.

Choose only one of -migrate, -preflight-migrate, -check-schema, -migration-exec-preflight, -validate-runtime. Combining them fatals.

Database-only installer flags (-migration-config, -legacy-ledger-transition, and related proof inputs) are release-admission machinery, not daily operator commands. Do not run legacy-ledger transition as a customer procedure.

Community implements -config, -version, -verbose, -debug, -log-file, -migrate, -init-db, -preflight-migrate, -check-schema, -help. Community default -config is configs/manager.yaml.

Procedure — service control #

sudo systemctl enable --now zwall-manager
sudo systemctl status zwall-manager
sudo systemctl reload zwall-manager
sudo systemctl restart zwall-managerCopy

reload sends SIGHUP. Treat HUP as “request reload,” not a certified live-apply of every YAML key.

YAML secret fields in Enterprise production stay empty: database.password, auth.jwt_secret, auth.default_admin.password. Non-secret environment may live in /etc/zwall-manager/manager-nonsecret.env.

Secret custody:

sudo bash scripts/setup.sh --manager-secret-custody freshCopy

Actions are fresh|migrate|rotate. Enterprise zwallctl secret-rotate defers to this path. Secret custody is implemented but not certified.

Procedure — console and users #

Operators use the SPA at /login (Console).

Administrator users: GET/POST/DELETE /api/v1/users (admin). Roles admin, viewer, release_manager. Most operator APIs require admin. See Authentication.

Settings groups exist at /api/v1/settings (general/security/eBPF/notification-related configuration stored on the Manager). Change them from the console or API; do not assume every key is hot-reloaded.

Procedure — maintenance and backup #

/api/v1/maintenance exists. Example YAML maintenance.backup_dir: "/var/backups/zwall".

Verified production backup still uses the repo-managed scripts documented in Backup. Do not assume the admin backup API or zwallctl backup is a complete substitute. There is no published RPO/RTO.

Testing / non-enforcing mode for enforcement estates:

zwallctl test-flush
zwallctl test-flush-status
zwallctl test-flush-disableCopy

These call POST / GET / DELETE /api/v1/maintenance/testing-mode. Inspect before enforcing. This is not a benchmark. Do not enable testing-mode flush as a Hosting observation procedure.

Procedure — metrics #

When metrics.enabled is true (example default true), GET /metrics (or metrics.path) requires admin JWT/session and RoleAuth("admin"). Optional metrics.allowed_cidrs may further restrict source IPs. Treat scrape credentials as admin-equivalent.

Verification #

1. systemctl is-active zwall-manager → active
2. GET /health/live → {"status":"alive",...}
3. GET /health/ready → {"status":"ready","database":"ok",...}
4. /login authenticates
5. zwallctl login --manager-url https://manager.example.com:8443 --username admin then zwallctl list-agents
6. Enterprise optional: zwall-manager -config /etc/zwall-manager/manager.yml -validate-runtime then exit 0 without leaving a second long-running process

Expected result #

A single Manager process serving API and console, schema migrated, default admin bootstrapped through the secret contract, Agents able to register when pre-registered. Packet policy still happens only on Virtualization Agents.

Failure modes #

Troubleshooting #

See Manager unavailable and Health.

Logs: example YAML logging.file: /var/log/zcs/firewall-manager.log; Enterprise unit ReadWritePaths includes /var/log/zwall-manager. Use journalctl -u zwall-manager regardless.

Security considerations #

• Empty CapabilityBoundingSet, NoNewPrivileges, ProtectSystem=strict.
• Do not run the Manager as root.
• Do not put production JWT, database, or admin passwords in YAML on Enterprise.
• /metrics is admin-gated.
• Trusted client IP / proxy headers stay disabled unless the Manager is loopback-only behind an HTTP-aware edge that overwrites the canonical scheme header.

Limitations #

• No certified customer HA.
• No certified backup/restore SLA.
• Path prefix is not canonical across Manager, Hosting, and Virtualization units.
• Listen port example (8443) disagrees with zwallctl default (8080).
• Secret custody not final-accepted.
• zwallctl start / stop print that remote start/stop is not implemented; use systemd.

Related documentation #

• Manager concept
• Manager installation
• Manager configuration
• Authentication
• Console
• Health
• systemd units