The architecture enforces a strict boundary between policy intent (Manager) and policy execution (Agents).
SYSTEM ARCHITECTURE MAP
Operators
Console, API/REST, zwallctl CLI
TELEMETRY INWARD
POLICY OUTWARD
Architecture
A Manager you host. Agents that do one job well.
Operators reach the Manager over HTTPS. Agents register, heartbeat, synchronize policy, and upload events. PostgreSQL is the Manager’s system of record. Kernel programs inspect packets only on the node that owns the profile — pass-only on hosting observation, pass-or-drop on virtualization enforcement.
Topology
Control plane vs data plane
Lifecycle
Register, heartbeat, synchronize, upload
An Agent bootstraps local identity, registers with the Manager, stores credentials locally, heartbeats, synchronizes rules/settings, and uploads events. Policy assignment is Manager-owned. Hosting observation Agents cannot receive restart commands or firewall rules (HTTP 409); use systemd on the hosting unit.
Identity
Two identities, one Manager
Administrators authenticate with username and password; TOTP can be required. Login JSON returns token, expires_at, username, role — not a session_token. Browsers use an HttpOnly session cookie.
Agents present Manager-issued Agent credentials, not the administrator token. Most operator APIs require the administrator role. Named roles exist; this is not a generally advertised fine-grained RBAC product.
Communications
HTTPS and REST
All communications are over HTTPS and REST. The example Manager listen is TLS on 8443 in the sample config; unconfigured zwallctl defaults to http://localhost:8080.
Treat that mismatch as an operator configuration issue, not as two published ports of a SaaS service. CORS in the example config requires explicit origins.
eBPF
eBPF on the node that owns the profile
Zwall uses eBPF programs in the Linux kernel. Hosting observation uses a pass-only object loaded by a privileged loader; those programs are specified not to drop, redirect, or rewrite forwarding. Virtualization uses firewall XDP on ingress and firewall_egress TC on egress; those programs can pass or drop. Loaded programs can keep their last admitted maps if the userspace Agent exits; updates resume when userspace returns. XDP runs earlier than netfilter, so Zwall can sit in front of a conventional host firewall — validate that arrangement on the target distribution. UID/GID cgroup filtering exists in source and is not a stable customer contract.
Topology
Two topologies, one Manager
A typical estate is one Manager, Hosting Agents on panel/shared nodes, Virtualization Agents on hypervisors. Do not attach a drop-capable profile to a shared hosting node if you intend observation.
Do not expect Hosting Agents to enforce VM isolation. KVM/libvirt is the documented hypervisor path. Other hypervisors are not shipping integrations.
Availability
What operators should expect
If the Manager is down, Agents cannot sync new policy or upload; kernel programs on an enforcement node can keep last admitted maps. If PostgreSQL is unavailable, Manager readiness fails (ready checks include database).
If a Hosting collector path is unreadable, Hosting status reports permission_blocked or source_not_present rather than inventing events. Event delivery is not claimed as lossless. These are operational facts, not availability percentages.
Boundary
Admission is a separate story
Enterprise database schema admission is designed to consume a verified signed release before migrate. Community is a source build. Production secrets for JWT, database password, and default admin password are intended to stay out of ordinary YAML on Enterprise. A certified secret-custody claim is not currently published.
Read Security and Trust Workflow
Evaluation Workflow
- 01 Confirm REST
/api/v1+ PostgreSQL + two profiles (/platform). - 02 Walk register → heartbeat → sync → upload on this page.
- 03 Decide which nodes are observation vs enforcement.
- 04 Read deployment models; Community source vs Enterprise verified-release.
- 05 Read observation vs enforcement Docs before mixing profiles.
- 06 Talk to an Engineer for Enterprise admission; do not use curl-pipe installers.
Docs
Architecture Documentation
Frequently Asked Questions
Where are packets dropped?
Only on enforcement-capable Virtualization (and explicit block paths), not on Hosting observation programs.
What happens if the Agent process exits?
Loaded programs can keep last admitted maps; updates resume when userspace returns. Not an HA claim.
Is XDP a replacement for iptables?
XDP runs earlier than netfilter. Coexistence is a design property, not a certified distro matrix.
Is there gRPC or GraphQL?
Customer protocol is HTTP/REST.
Can I run this on Kubernetes as a shipping product?
Kubernetes is not a shipping integration.
Does Community use signed-release admission?
No. Community is a source build.
Ready to dive deeper?
Speak with an engineer or read the deployment documentation.