ZWall Community

Open-source Linux firewalling and threat response built on eBPF/XDP, with centralized management, real-time visibility, and operator-controlled deployment.

Why ZWall Community

ZWall Community is the open-source edition of the ZWall platform. It gives security teams and infrastructure operators a centrally managed Linux firewall and threat-control layer that runs close to the kernel using eBPF/XDP, with a web dashboard, API, CLI, metrics, and agent-based policy enforcement.

It is designed for:

• labs and test environments
• SMB and smaller production fleets
• security teams evaluating the ZWall platform
• operators who want transparent, self-managed deployment on Linux

ZWall Community supports up to 3 registered agents per manager.

Core Capabilities

Kernel-Level Firewalling

• eBPF/XDP-based ingress enforcement with low-overhead packet filtering
• IP, CIDR, port, protocol, and MAC-based controls
• UID/GID-aware network filtering for process-level policy scenarios
• whitelisting and blocklisting workflows
• interface-level bandwidth controls and SMTP traffic controls where supported

Threat Detection and Response

• SYN, ICMP, and UDP flood protection
• port-scan detection and automated response paths
• brute-force detection for monitored services
• DHCP guard, BPDU blocking, and MAC spoofing protections
• temporary-to-permanent block workflows and correlated event handling

Centralized Operations

• manager and agent architecture with centralized policy distribution
• React-based web dashboard for rules, agents, health, and event visibility
• zwallctl CLI for operational workflows
• REST API for automation and integration
• Prometheus metrics and included Grafana dashboards

Infrastructure Support

• KVM/libvirt-aware virtualization visibility
• GeoIP-based controls and external blocklist ingestion
• RBL checks and notification workflows
• ModSecurity integration paths for web protection use cases
• centralized audit and security event visibility

Architecture Overview

flowchart LR
    subgraph Manager["ZWall Community Manager"]
        API["REST API"]
        UI["Web UI"]
        DB[(PostgreSQL)]
        METRICS["Prometheus Metrics"]
        API --- UI
        API --- DB
        API --- METRICS
    end

    subgraph AgentA["Agent Node A"]
        RUNTIMEA["Agent Runtime"]
        XDPA["XDP / eBPF"]
    end

    subgraph AgentB["Agent Node B"]
        RUNTIMEB["Agent Runtime"]
        XDPB["XDP / eBPF"]
    end

    API <-->|"JWT / mTLS-capable sync"| RUNTIMEA
    API <-->|"JWT / mTLS-capable sync"| RUNTIMEB
    RUNTIMEA --- XDPA
    RUNTIMEB --- XDPB

Loading

At a high level:

1. The manager stores policies, security settings, and fleet state in PostgreSQL.
2. Agents register with the manager and synchronize policy on a heartbeat loop.
3. Enforcement happens on the agent using eBPF/XDP and related kernel hooks.
4. Metrics, events, and health data flow back to the manager for visibility and operations.

Community Edition Boundaries

ZWall Community is intentionally scoped for open-source self-hosting.

• Fleet limit: up to 3 registered agents per manager
• TLS model: operator-managed certificates and passive certificate visibility
• Deployment model: self-managed source build and installation
• Edition scope: Community does not include Enterprise-only scale limits, commercial support, or private-edition governance features

Community does not ship product-managed ACME or certificate-center automation. If you enable manager TLS, provide and rotate certificate files operationally.

Quick Start

Prerequisites

• Linux kernel 4.15+ (5.4+ recommended)
• Go 1.25+
• Node.js 18+
• PostgreSQL 15+
• clang, llvm, and libbpf-dev or equivalent toolchain packages

Clone and Build

git clone https://github.com/zwall-net/zwall-community.git
cd zwall-community

go build -o bin/manager ./cmd/manager
go build -o bin/agent ./cmd/agent
go build -o bin/zwallctl ./cmd/zwallctl

cd ebpf && make && cd ..
cd web && npm install && npm run build && cd ..

Automated Setup

For a guided installation on a supported Linux host:

sudo ./scripts/setup.sh

Manual Setup

1. Create a PostgreSQL database and user.
2. Copy configs/manager.example.yml to /etc/zcs/manager.yml and set database, networking, and TLS paths.
3. Run the manager migration before first startup:

./bin/manager -config /etc/zcs/manager.yml -migrate

4. Start the manager:

./bin/manager -config /etc/zcs/manager.yml

5. Copy configs/agent.example.yml to /etc/zcs/agent.yml, point it at the manager, then start the agent.

Deployment Best Practices

• Run the manager behind TLS with operator-managed certificates.
• Back up PostgreSQL regularly and test restore procedures before production use.
• Limit manager exposure to trusted networks, VPNs, or controlled administrative access paths.
• Validate kernel, BTF, and libbpf prerequisites before agent rollout.
• Monitor /metrics, manager logs, and agent health after installation and upgrades.
• Treat Community as a self-managed security platform: validate policies in a safe environment before broad rollout.

Documentation Map

• Architecture
• Installation Guide
• Operations Guide
• API Reference
• Zwallctl CLI Reference
• Manager Internals
• Agent Internals
• Frontend Architecture

Community vs Enterprise

Area	ZWall Community	ZWall Enterprise
Agent capacity	Up to 3 agents per manager	Larger fleet scale
Support model	Self-managed, community-driven	Commercial support and guidance
Governance depth	Core operational controls	Advanced enterprise governance and private-edition capabilities
Adoption fit	Labs, SMB, evaluation, small fleets	Larger fleets, regulated environments, commercial deployments

Need larger fleet limits, enterprise support, or advanced governance features? Explore ZWall Enterprise at zwall.net.

Contributing and License

ZWall Community is licensed under AGPL-3.0-only.

• Contribution guidelines: CONTRIBUTING.md
• Security reporting: SECURITY.md
• Release history: CHANGELOG.md