Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Manager

Manager

Manager (concept)

SharedStatus: SUPPORTED as component descriptionAudience: Manager administrator, deployment engineer

Purpose

Define the Manager as the control plane you host. Operators talk to the Manager. The Manager talks to Agents. The Manager does not attach eBPF and does not drop packets.

Concept

From current Manager source:

  • HTTP(S) API at /api/v1
  • Web console (React SPA; / and /ui redirect to /login)
  • Administrator authentication (username/password, optional TOTP, JWT + HttpOnly session cookie)
  • Agent registration, heartbeat, token refresh, policy/rule sync
  • PostgreSQL persistence (not SQLite)
  • Security log ingest and listing
  • Background detection services (brute-force, blocklists, GeoIP, RBL, temp-to-perm, login rate limit, and related handlers)
  • Optional Prometheus /metrics (admin-authenticated when metrics.enabled)
  • Health probes /health, /health/live, /health/ready, plus GET /api/v1/health

Example combined listen: API and web on 8443 with TLS. Optional server.split_mode_enabled runs API and web on different ports; web.enabled must be true and web.port must differ from api_port. web.static_dir example /opt/zcs/web.

Graceful HTTP shutdown timeout in code: 30s. systemd TimeoutStopSec=30.

Enterprise unit: User=zwall-manager, ExecStart=/opt/zwall-manager/bin/zwall-manager -config /etc/zwall-manager/manager.yml, EnvironmentFile=-/etc/zwall-manager/manager-nonsecret.env, ExecReload=/bin/kill -HUP $MAINPID, After postgresql.service, ReadWritePaths=/var/lib/zwall-manager /var/log/zwall-manager /run/zwall-manager, empty CapabilityBoundingSet, NoNewPrivileges, ProtectSystem=strict.

Path prefixes /etc/zcs vs /etc/zwall-manager vs /opt/zcs vs /opt/zwall-manager are not unified. zwallctl default URL http://localhost:8080 vs example listen 8443 is a known mismatch.

Data/control flow

Operators (browser/CLI) → Manager API → PostgreSQL.
Agents → register/heartbeat/sync/logs.
Manager → assigned Virtualization Agents (policy). Hosting Agents send telemetry only.

Exclusive flags (Enterprise): choose only one of -migrate, -preflight-migrate, -check-schema, -migration-exec-preflight, -validate-runtime. -init-db is a deprecated alias for -migrate. Default -config is configs/manager.yml. Also -version, -build-info-json, -verbose, -debug, -log-file, -help.

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

Default admin may be created from auth.default_admin if no row exists. Production secrets via systemd credentials; YAML empty for jwt_secret, database.password, default_admin.password. Secret custody scripts/setup.sh --manager-secret-custody is implemented, but a certified secret-custody claim is not currently published.

Boundaries

  • Cluster is implemented, license-gated, not a public HA product.
  • In-product updater is not the supported production upgrade path.
  • Backup API is not a certified backup contract.
  • No OIDC.
  • AI Preview is Preview; dedicated private Zwall AI is not this component’s GA claim.
  • Live probes do not mean the database is healthy — use /health/ready.

Edition differences

Enterprise: licensing, Hosting APIs, AI Preview, -validate-runtime, systemd credential strictness, release verifier admission.
Community: source install, operator-managed secrets, 3-Agent cap.

Common misconceptions

  • “Manager is the firewall.” Agents enforce.
  • “/health/live 200 means PostgreSQL is up.” It does not.
  • “Cluster YAML makes HA.” Not a customer HA product.
  • “curl-pipe installer.” Not a shipping feature.