Manager Install

Manager installation

Purpose #

Install and start the Manager control plane after the edition-specific admission path (Community source build or Enterprise verified-release + database installer) has produced a binary and a schema.

This page does not replace Community source install or Database preparation. Detailed Enterprise verified-release admission is provided separately to Enterprise customers.

Audience #

Linux administrators who will run zwall-manager.service or bin/manager.

Edition #

Follow Community or Enterprise below. Do not mix path prefixes.

Status #

SUPPORTED for the unit/flags documented here. Secret custody is implemented but not certified. Cluster is not a public HA install.

Prerequisites #

• PostgreSQL reachable with the Manager database.* settings (example name zwall_centralized_security, port 5432, ssl_mode: require)
• Schema admitted (-migrate or Enterprise scripts/setup.sh --manager-database-only)
• TLS cert/key if server.tls.enabled: true (example /etc/ssl/certs/manager.crt, /etc/ssl/private/manager.key)
• Web artifacts at web.static_dir (example /opt/zcs/web) if the console will be served
• Enterprise: locked zwall-manager runtime identity (nologin, home /nonexistent) already established by the config installer

Required permissions #

Root to install units and credentials. The service itself runs as zwall-manager on Enterprise (not root).

Dependencies #

PostgreSQL. The Manager does not use SQLite as production storage.

Configuration #

Enterprise unit deploy/manager-systemd/zwall-manager.service:

Community README uses /etc/zcs/manager.yml and default -config configs/manager.yaml. The Enterprise database installer example also names --manager-config /etc/zcs/manager.yml while this unit uses /etc/zwall-manager/manager.yml. Treat that mismatch as a known path-prefix inconsistency; follow the unit you actually install.

YAML secrets on Enterprise production stay empty: database.password, auth.jwt_secret, auth.default_admin.password. Listen example: 8443 TLS. zwallctl unconfigured default is http://localhost:8080 — set --manager-url.

Procedure — Community #

1. Build per Community source install.
2. Create PostgreSQL role/database (Database preparation).
3. Copy configs/manager.example.yml to the runtime path.
4. Set database, TLS, CORS origins.
5. Migrate, then start:

./bin/manager -config /etc/zcs/manager.yml -migrate
./bin/manager -config /etc/zcs/manager.ymlCopy

Guided script sudo ./scripts/setup.sh can write systemd units zwall-manager and zwall-agent. Choose only one exclusive migrate flag at a time.

Procedure — Enterprise #

1. Complete verified-release schema admission (release verify → -preflight-migrate → -migrate → -check-schema). Those installer steps are provided separately to Enterprise customers.
2. Place production secrets via systemd credentials, not YAML. Customer path:

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

migrate and rotate are the other actions. Secret custody is implemented but a certified claim is not currently published. Do not call this certified. zwallctl secret-rotate on Enterprise defers here.

3. Optional runtime validation without starting listeners:

sudo -u zwall-manager /opt/zwall-manager/bin/zwall-manager \
  -config /etc/zwall-manager/manager.yml -validate-runtimeCopy

Do not combine -validate-runtime with -migrate.

4. Enable the Manager unit:

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

systemctl reload zwall-manager sends HUP (note: request reload, not certified live-apply of every key).

Procedure — flags you may run before start #

Choose only one exclusive mode.

Verification #

See First verification.

• systemctl is-active zwall-manager → active
• GET /health/live → alive
• GET /health/ready → ready and database: ok
• /login works with the initial admin credential from the secret contract
• zwallctl login --manager-url https://manager.example.com:8443 --username admin

Expected result #

Manager serving API and console, schema migrated, default admin present, no packet enforcement on this host.

Failure modes #

Troubleshooting #

Manager unavailable, Health, journalctl -u zwall-manager.

Security considerations #

Empty capabilities, non-root user, secrets not in YAML on Enterprise. Do not enable cluster as a customer HA install.

Limitations #

Unresolved: path prefixes, port mismatch, backup contract, cluster HA, secret custody.

Related documentation #

• Manager configuration
• systemd units
• Administration
• Authentication