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 Let's Encrypt 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 Let's Encrypt. 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, Flask 3.x for web management
• firewalld (nftables backend)
• nginx 1.26+
• dnsmasq
• WireGuard tools (wireguard-tools)
• acme.sh for ACME/Let's Encrypt certificate management
• 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 the required environment variables:

MGMT_DOMAIN=wall.lan MGMT_PASS=yourpassword ACME_EMAIL=admin@example.com \
    bash install.sh

After installation, access the management interface at https://wall.lan using the credentials you configured. The install.sh script provisions nginx, sets up authentication, obtains an initial Let's Encrypt certificate, and starts all services.

Project Structure

├── install.sh               # Deployment script
├── pyproject.toml           # Project metadata + dependencies
├── .venv/                   # Python virtual environment
├── system/                  # System file templates
│   ├── systemd/             # Service and timer unit files
│   │   ├── vacuum-wall.service        # Web UI service
│   │   ├── vacuum-wall-acme.service   # Certificate renewal service
│   │   └── vacuum-wall-acme.timer     # Renewal schedule
│   └── sudoers.d/           # Sudo whitelist for service account
├── lib/                     # Subsystem abstraction layer
│   ├── 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
│   ├── 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