vacuum-wall/docs/overview.md

Vacuum Wall

What is Vacuum Wall?

Vacuum Wall is a zone-based firewall appliance with a built-in SSL reverse proxy, providing a unified platform for network security and traffic management. It combines firewalld policy control, DHCP/DNS services, WireGuard VPN tunnels, and automated certificate provisioning into a single device. A single web UI controls everything, making enterprise-grade network infrastructure manageable from one place.

Architecture Overview

Vacuum Wall is built around four integrated subsystems managed through a central Flask web interface. The traffic plane uses firewalld with its nftables backend, supporting zone-based policies, source NAT, and destination NAT for port forwarding. The DNS/DHCP plane serves private subnets via dnsmasq, providing address allocation and local name resolution. The proxy plane runs nginx with automatic ACME certificates through acme.sh, handling SSL termination and reverse proxying for backend services. The VPN plane uses WireGuard (wg-quick) for encrypted tunnel management. All subsystems are configured and monitored through the Flask web UI, which is itself proxied through nginx with basic HTTP authentication.

Subsystems

Firewall

The firewall uses firewalld's zone model for traffic control. Network interfaces are assigned to zones such as external, internal, VPN, and trusted. Rules and services define which traffic is allowed between zones. Source NAT (masquerade) enables RFC 1918 networks to reach the internet through the external interface. Destination NAT rules provide port forwarding, exposing internal services to external networks on configurable ports.

DHCP/DNS

dnsmasq serves as both the DHCP server and local DNS resolver. It is configured to serve address pools on specified LAN interfaces, with support for dynamic allocation ranges and static MAC-based reservations. Custom DNS records can be defined for local name resolution, and upstream DNS forwarding passes external queries to configurable resolvers.

SSL Proxy

The nginx reverse proxy handles HTTPS termination for user-defined domains, with certificates automatically provisioned and renewed via acme.sh and an ACME provider (ZeroSSL by default). Each proxy domain is configured with an HTTP-to-HTTPS redirect, modern TLS settings, and a configurable backend target. New proxy domains are added through the web UI, and the configuration is applied without manual intervention.

WireGuard

WireGuard support provides server-side VPN tunnel management. Peers are added through the web UI, with the system generating client configuration files that can be downloaded and applied on remote devices. The dashboard displays active connections and transfer statistics for each peer, allowing operators to monitor tunnel health and usage.

Tech Stack

• Debian 13 (trixie) target platform
• Python 3.13+, Flask 3.x for web management
• firewalld (nftables backend)
• nginx 1.26+
• dnsmasq
• WireGuard tools (wireguard-tools)
• acme.sh for ACME certificate management (ZeroSSL by default)
• HTMX for dynamic UI updates
• Jinja2 for server-side templating

Quick Start

To install Vacuum Wall on a Debian 13 system, run install.sh as root with required settings (CLI flags or environment variables):

# Production
./install.sh --mgmt-pass yourpassword --acme-email "admin@example.com"

# Development (auto-detects your user)
./install.sh --dev --mgmt-pass yourpassword --acme-email "admin@example.com"

After installation, access the management interface at https://<hostname>.local using the credentials you configured. The install.sh script auto-detects the system hostname, network interfaces, and provisions nginx, authentication, an initial self-signed certificate, and all services. Run ./install.sh --help for all options.

Project Structure

├── install.sh               # Deployment script (renders Jinja2 templates)
├── pyproject.toml           # Project metadata + dependencies
├── .venv/                   # Python virtual environment
├── config/                  # Declarative JSON configuration (source of truth)
│   ├── dnsmasq/             # DHCP/DNS config
│   ├── nginx/               # Proxy domain & SSL config
│   └── wireguard/           # VPN interface & peer config
├── data/                    # Runtime artifacts & generated files
│   ├── nginx/sites-enabled/ # Generated server blocks
│   ├── dnsmasq/fragments/   # User config fragments
│   ├── acme/                # ACME certificates
│   └── firewall/            # Firewall rule backup
├── system/                  # System file templates (all Jinja2)
│   ├── systemd/             # Service and timer unit files
│   │   ├── vacuum-wall.service        # Web UI service (rendered at install)
│   │   ├── vacuum-wall-acme.service   # Certificate renewal (rendered at install)
│   │   └── vacuum-wall-acme.timer     # Renewal schedule
│   ├── sudoers.d/           # Sudo whitelist (rendered at install)
│   ├── nginx/               # Nginx config templates (rendered at runtime)
│   ├── dnsmasq.conf         # Dnsmasq template (rendered at runtime)
│   └── wireguard*.conf      # WireGuard templates (rendered at runtime)
├── lib/                     # Subsystem abstraction layer
│   ├── common.py            # Shared utilities (run, run_proc, load_json, save_json, deep_merge, ensure_dirs)
│   ├── logging.py           # Logging setup
│   ├── firewall.py          # firewalld bindings
│   ├── dnsmasq.py           # DHCP/DNS configuration
│   ├── nginx.py             # Reverse proxy configuration
│   ├── acme.py              # Certificate management
│   └── wireguard.py         # VPN tunnel management
├── webui/                   # Flask web application
│   ├── server.py            # Application entry point
│   ├── api/                 # REST API route modules
│   │   └── common.py        # Shared API response helpers (_ok, _error)
│   ├── templates/           # Jinja2/HTMX templates
│   └── static/              # CSS and client-side JS
└── docs/                    # Documentation
    ├── overview.md          # This file
    ├── deployment.md
    ├── api.md
    ├── security.md
    ├── architecture.md
    └── config.md

Documentation

• Deployment Guide - Full installation and configuration
• API Reference - REST API endpoints
• Security Model - Privilege model and sudo whitelist
• Architecture - Detailed subsystem design
• Configuration - Config file formats and locations