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

Console

Manager console

Purpose

Give operators a browser UI for fleet, firewall, detection, logs, and settings on the Manager you host. The console is the React SPA served by the Manager. It is not a separate SaaS.

Audience

Administrators who operate Zwall from a browser rather than only zwallctl or raw /api/v1.

Edition

SHARED core: login, dashboard, agents, firewall, logs, settings.

Enterprise additionally includes Hosting views, AI Preview, license, and certificate-related screens when those features are present in the admitted release.

Do not invent screens that are not in the product (no “single pane of glass,” no public streaming console, no OIDC login page).

Status

SUPPORTED. Live updates use an authenticated WebSocket hub. That hub is not a public streaming product API.

Prerequisites

  • Manager ready (GET /health/ready)
  • web.enabled: true
  • TLS certificate the browser will accept (example server.tls.enabled: true on port 8443)
  • server.cors.allowed_origins lists the actual origin the browser uses (hostname and IP variants if operators use both)
  • Administrator credentials (Authentication)

Required permissions

Console XHR uses the administrator JWT. Session bootstrap and WebSocket upgrades use the HttpOnly session_token cookie. Most operator APIs behind the UI require admin. A viewer login will not drive mutating fleet/firewall workflows.

Dependencies

  • Static assets from web.static_dir (example /opt/zcs/web)
  • PostgreSQL (same as the API)
  • Optional: Hosting Agents before Hosting pages show collector evidence; Virtualization Agents before VM/interface pages populate

Configuration

Scroll sideways to see the full table. Use the arrow keys when focused.

KeyExampleNotes
web.enabledtruerequired for the SPA
web.port8443must differ from server.api_port when split mode is on
web.static_dir/opt/zcs/webthis prefix is /opt/zcs even when the Manager binary is /opt/zwall-manager
server.port / server.api_port8443combined-mode example
server.split_mode_enabledfalseoptional split of API and web ports
server.cors.allowed_originshttps://manager.example.comno wildcard in TLS/production
server.cors.allow_credentialstruerequired for cookie sessions

Path prefixes are not unified. Follow the admitted unit: Manager config /etc/zwall-manager/manager.yml on Enterprise zwall-manager.service; Community README often uses /etc/zcs/manager.yml.

Procedure

  1. Confirm web.enabled: true and that web.static_dir contains the built SPA.
  2. Open https://manager.example.com:8443/login (replace host and port with yours). / and /ui redirect to /login.
  3. Authenticate with username/password and optional TOTP. The browser keeps session_token as HttpOnly; API calls use the JWT.
  4. Set CORS origins to the URL you actually typed, including the port if it is not 443.
  5. For live dashboard widgets, allow WebSocket to GET /api/v1/dashboard/ws (session cookie or Bearer inside the upgrader).

Split mode: browsers load the UI from web.port. Put that origin in allowed_origins, not only the API port.

Verification

Scroll sideways to see the full table. Use the arrow keys when focused.

CheckPass
/login returns the login pageSPA present
Successful login leaves /loginJWT + cookie issued
Dashboard loads agent counts / health widgets/api/v1/dashboard/* reachable as admin
WebSocket connectsconsole updates without claiming a public stream
Hosting pages (Enterprise)only after a Hosting Agent heartbeats; events are category-safe

GET /api/v1/auth/status confirms the session cookie for the browser.

Expected result

An authenticated operations console on the Manager origin. Operators can inspect Agents, rules, logs, and settings. Enterprise operators can open Hosting observation views and AI Preview without those features becoming enforcement or autonomous SOC.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomCauseAction
Blank page / 404 on /loginweb.enabled false or empty static_dirinstall web artifacts to /opt/zcs/web; enable web
Login form never submitsCORS origin mismatchadd the exact https://host:port
400 Secure HTTPS session requiredcookie policyterminate TLS at the Manager or a reviewed HTTPS front
UI loads, APIs 401JWT expired (auth.token_expiry example 8h)log in again
Hosting UI emptyno Hosting Agent, or collectors permission_blockedHosting troubleshooting
“Live stream” expectedWebSocket is console-onlyuse log APIs; this is not a SIEM tap

Troubleshooting

  • Confirm /health/ready before debugging the SPA.
  • journalctl -u zwall-manager for static dir / TLS errors.
  • Browser devtools: cookie HttpOnly, Authorization on XHR, WS to /api/v1/dashboard/ws.
  • Do not disable verify_tls on Agents to “fix” the console.

Security considerations

  • Serve the console on HTTPS. Example Manager TLS files: /etc/ssl/certs/manager.crt, /etc/ssl/private/manager.key.
  • Restrict allowed_origins. Wildcard CORS is a development warning, not a production setting.
  • Treat the WebSocket as admin-equivalent.
  • AI Preview screens must not be described as applying live rules. Approval records review intent only.

Limitations

  • Not a public event streaming product.
  • Viewer role cannot replace administrator workflows.
  • Cluster dashboards that may exist in Grafana templates are not a certified HA console.
  • In-product updater UI, if present, is not the supported production upgrade path.