First Verification

Purpose #

Prove a freshly installed system is actually running — process, database, console, Agent heartbeat, and the correct observation vs enforcement profile — not merely that a unit is enabled.

Audience #

The engineer who just finished Manager and Agent install.

Edition #

SHARED probes. Hosting checks are ENTERPRISE_ONLY. GET /api/v1/dashboard/ebpf-health is Enterprise.

Status #

SUPPORTED.

Prerequisites #

Manager unit or bin/manager started. At least one Agent if you intend to verify fleet. Admin credential from the supported secret contract.

Required permissions #

Root for systemctl. Admin JWT for APIs. zwallctl --manager-url set to the real origin (example https://manager.example.com:8443).

Procedure — Manager #

1. systemctl is-active zwall-manager (or confirm the Community process).
2. GET /health/live — {"status":"alive","timestamp":...} unless draining/updating (503). Not a database check.
3. GET /health/ready — status: ready, database: ok. 503 lists checks (listener_admission_incomplete, database: timeout / unavailable / not_configured, optional cluster/blocking keys).
4. GET /health and GET /api/v1/health — compatibility only; prefer live/ready.
5. Open /login and authenticate (username/password, optional TOTP). JSON login returns token, expires_at, username, role — not session_token.
6. Optional: GET /api/v1/auth/status with the session cookie.
7. If metrics.enabled: GET /metrics as admin. Unauthenticated scrape must fail.

curl -k https://manager.example.com:8443/health/live
curl -k https://manager.example.com:8443/health/ready
zwallctl login --manager-url https://manager.example.com:8443 --username admin
zwallctl pingCopy

Procedure — Agent (any profile) #

1. Unit active: zwall-agent or Hosting loader + Hosting Agent. Do not expect both jobs on one shared hosting node.
2. zwallctl list-agents after login. GET /api/v1/agents shows the Agent. Community: fourth Agent rejected.
3. Heartbeat continuing (console status / last_heartbeat; offline after agents.timeout example 2m).

Procedure — Virtualization Agent #

1. Unit zwall-agent active as root.
2. GET /api/v1/virtualization/vms and /interfaces — non-empty on a libvirt host with workloads.
3. GET /api/v1/dashboard/ebpf-health (Enterprise).
4. Optional zwallctl status --agent ID.
5. Policy path: create a rule or block; confirm sync. Use testing mode before first drop (zwallctl test-flush-status). Do not test first-drop on a Hosting profile.

Procedure — Hosting Agent (Enterprise) #

1. systemctl is-active zwall-hosting-ebpf-loader
2. systemctl is-active zwall-hosting-agent or zwall-hosting-agent-v2
3. Socket /run/zwall-hosting-ebpf/observer.sock
4. GET /api/v1/agents/:id/hosting/status — sources explained (permission_blocked / source_not_present / active); observation_only
5. GET /api/v1/agents/:id/hosting/events — category-safe projection
6. Drops remain zero for observation programs
7. Negative: restart API and rule assign return 409

Verification #

All applicable rows in the tables above pass. CLI default port 8080 is not a pass if the Manager listens on 8443.

Expected result #

Control plane ready, Agents listed, Hosting observing or Virtualization able to enforce — not both jobs silently mixed.

Failure modes #

Troubleshooting #

Diagnostics, Troubleshooting index.

Security considerations #

-k is for untrusted lab certs only. Do not disable Agent verify_tls to pass this checklist.

Limitations #

Does not certify OS/kernel matrix, secret custody, or backup.

Related documentation #

• Health
• Manager install
• Hosting install
• Virtualization install