Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Troubleshooting › Enforcement

Enforcement

Enforcement not applying

SharedStatus: SUPPORTED for “rules sync to Virtualization Agents.” Not product-wide certified. No PPS claims.Audience: security engineer, virtualization operator

Symptom

A block or rule exists on the Manager, but traffic is not dropped (or not dropped on the node you expected). zwallctl deny printed success. Console shows the rule enabled.

Likely verified causes

  1. The target node is a Hosting Agent. Hosting never enforces.
    • Assign API: 409 Hosting observation Agents cannot receive rules
    • Validation: hosting observation Agent %d cannot receive rules
    • Hosting config must keep hosting.enforcement: false (with audit_only: true, log_only: true) or the Agent refuses to start.
  2. Rule was not assigned to that Virtualization Agent (POST /api/v1/rules/:id/assign).
  3. Testing mode is flushing or disabling enforcement (zwallctl test-flush-status; GET /api/v1/maintenance/testing-mode).
  4. Agent not syncing (zwallctl reload / Agent sync). Agent disconnected.
  5. eBPF not attached / maps empty. Enterprise: GET /api/v1/dashboard/ebpf-health. Community: that route is absent.
  6. zwallctl deny created BLOCK_IP_INBOUND on the Manager; that is not a Hosting action and is not a PPS guarantee.
  7. UID/GID filtering (enable_uid_gid_filtering, uid_gid_filter_v3.o) is not a supported customer contract. Non-application is not necessarily a bug.
  8. xdp_attach_mode failed (example auto tries native then generic).
  9. Agent not root / missing capabilities — eBPF.

Diagnostic commands/endpoints

Confirm profile first:

zwallctl list-agents

protection_model: hosting → stop. Hosting will not drop. Enforcement for hosting estates belongs on Virtualization Agents, not on the Hosting profile.

zwallctl list-rules
zwallctl test-flush-status
zwallctl reload
GET /api/v1/rules
POST /api/v1/rules/:id/assign   # body {"agent_id": <int>}
GET /api/v1/agents/:id
GET /api/v1/dashboard/ebpf-health          # Enterprise only
GET /api/v1/dashboard/ebpf-health?agent_id=<id>
GET /api/v1/maintenance/testing-mode

On a Virtualization node:

sudo systemctl status zwall-agent
sudo journalctl -u zwall-agent -n 200 --no-pager
zwallctl map ls

zwallctl deny posts:

{
  "rule_type": "BLOCK_IP_INBOUND",
  "action": "block",
  "direction": "INBOUND",
  "enabled": true
}

to POST /api/v1/rules. Success means the Manager accepted the object, not that XDP dropped a packet.

What each result means

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

ResultMeaning
409 Hosting observation Agents cannot receive rulesCorrect product behavior. Pick a Virtualization Agent.
Hosting Agent start error hosting profile must set audit_only=true, log_only=true, enforcement=falseEnforcement flag is forbidden on this profile.
Testing mode enabledRules may be temporarily applied and flushed (zwallctl test-flush; disable with test-flush-disable).
Rule exists, not in Agent assignment listNot synced to that Agent.
Enterprise ebpf-health overall_status unhealthy / unknown, ebpf_loaded: falsePrograms not loaded; maps/security-state summary only (redaction: summary_only_no_raw_map_keys).
Community ebpf-health 404 Endpoint not foundHandler not registered. Use Agent journal and map ls.
map ls empty on-nodeMaps not programmed or pin dir empty (ZWALL_PIN_DIR / default /sys/fs/bpf/fw).
UID/GID surprises with enable_uid_gid_filtering: true in example YAMLIncomplete ABI. Disable until a complete contract exists.
Agent not root (non-Hosting)The Agent exits if it is not root, unless Hosting is enabled.

Safe remediation

  1. Assign rules only to Virtualization Agents.
  2. Keep Hosting enforcement: false. Do not run zwall-agent.service (drop-capable) on the shared hosting node as a substitute for Hosting observation.
  3. If testing mode is on unintentionally: zwallctl test-flush-disable after confirming you intend to keep current rules. test-flush itself can flush — use with caution.
  4. Restore Agent connectivity; zwallctl reload to force rule sync.
  5. Fix eBPF attach (eBPF). Controlled fallback: ebpf.xdp_attach_mode: generic — not a performance claim.
  6. Set enable_uid_gid_filtering: false if UID/GID behavior is the incident.
  7. Verify with a lab flow on a Virtualization host, not on a production Hosting node.

Do-not-do warnings

  • Do not claim Hosting “silently firewalls.” Observation programs pass.
  • Do not claim PPS, latency, or certified drop rates.
  • Do not document UID/GID V3 as a supported customer feature.
  • Do not disable verify_artifact_integrity or set allow_unsigned_artifacts: true except break-glass.
  • Do not use testing-mode flush on production as a cleanup tool without intent.
  • Do not treat zwallctl deny success as dataplane proof.

Escalation condition

Escalate when:

  • Virtualization Agent is online, eBPF loaded, rule assigned and enabled, testing mode off, maps contain the object, and traffic still matches the rule’s IP/direction without drop
  • Hosting pass-only programs drop (defect)
  • Community needs a Manager eBPF health API — not present in Community router

Edition

SHARED Virtualization path. Hosting 409 and Hosting enforcement=false are ENTERPRISE Hosting profile. dashboard/ebpf-health ENTERPRISE_ONLY.

Status

SUPPORTED as implemented assignment/sync/attach diagnosis. Not a product-wide enforcement certification.