Architecture Concepts
Purpose
Give operators a correct map of control plane vs data plane before they install.
Control plane: Manager
The Manager:
- exposes HTTP(S), primarily
/api/v1 - serves the React console
- authenticates administrators (username/password tokens, optional TOTP)
- registers Agents and issues/refreshes Agent credentials
- stores rules, blocked IPs, detection settings, and events in PostgreSQL
- can emit Prometheus metrics and WebSocket console updates
SQLite is not the Manager production database.
Data plane: Agents
The shared Agent:
- bootstraps durable identity
- registers with the Manager
- stores credentials locally
- synchronizes rules/settings
- uploads events
- optionally loads eBPF programs
Active packet enforcement requires root. The dedicated Hosting profile is intended to run unprivileged because it does not load enforcement eBPF; a separate privileged hosting-ebpf-loader owns pass-only attach.
Observation vs enforcement
Scroll sideways to see the full table. Use the arrow keys when focused.
| Profile | Kernel programs | Packet drop |
|---|---|---|
| Hosting Agent | hosting_observe XDP/TC | Prohibited (pass / OK only) |
| Virtualization Agent | firewall XDP + firewall_egress TC | Intended capability |
A config leaf protection_model of virtualization, hosting, or hybrid exists on the shared Agent. That leaf is not the same thing as the Enterprise Hosting Agent profile.
Communications
Operators and Agents reach the Manager over HTTPS. The customer protocol is HTTP/REST. Do not document gRPC as the customer control-plane protocol.
Example Manager listen settings from configs/manager.example.yml:
server.host:0.0.0.0server.port/server.api_port:8443server.tls.enabled:true
zwallctl defaults to http://localhost:8080 if unconfigured. Operators must point the CLI at the actual Manager URL.
eBPF program families that exist
Scroll sideways to see the full table. Use the arrow keys when focused.
| Program | Role | Enforcement? |
|---|---|---|
firewall.c / firewall_egress.c | Virtualization/network protection | Yes, intended |
hosting_observe.c | Hosting telemetry | Observe only |
uid_gid_filter*.c | UID/GID socket filtering | Intended; ABI/lifecycle not documented as complete |
smtp_dnat.c | SMTP mark/NAT companion | Specialized |
firewall_simple.c | Simplified/legacy variant | Not a separate customer product |