# NX9 WireGuard (`nx9-wg`) ![Rust](https://img.shields.io/badge/Rust-Stable-orange) ![SQLite](https://img.shields.io/badge/SQLite-Embedded-blue) ![Platform](https://img.shields.io/badge/Platform-Linux-lightgrey) ![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-green) ![Version](https://img.shields.io/badge/Version-v0.8.0-purple) > **Sovereign, self-hosted, Linux-native VPN and network control plane built around the kernel's WireGuard implementation.** `nx9-wg` is no longer just a WireGuard management wrapper. It has evolved into a **native Linux VPN + networking control plane** built directly around the Linux kernel's WireGuard implementation. --- ## The Architectural Distinction ### Typical WireGuard Manager ``` UI ──► Configuration Files ──► wg / wg-quick / ip / nft ──► Linux Kernel ``` ### Whereas `nx9-wg` is: ``` nx9-wg │ ┌────────────┴────────────┐ │ │ Desired State Live State │ │ SQLite Linux Kernel │ ▲ ▼ │ Reconciliation ◄──────── Telemetry │ ├── WireGuard Generic Netlink ├── RTNETLINK ├── Netfilter / libnftables └── procfs │ ▼ Linux networking ``` --- ## Core Capabilities Beyond Interface Creation - 🔐 **WireGuard interface and peer lifecycle** (RTNETLINK + WireGuard Generic Netlink) - 🌐 **IPv4/IPv6 address management** (In-process `RTM_NEWADDR` / `RTM_DELADDR`) - 🛣️ **Route management & protected route reconciliation** (Zero default-route interference) - 🔥 **Firewall rule management** (In-process `libnftables.so.1` FFI in `table inet nx9_wg`) - 🛡️ **Scoped NAT/masquerading** (Strictly scoped to managed WireGuard client subnets) - ↔️ **IPv4/IPv6 forwarding** (Direct atomic `/proc/sys/net` sysctl control) - 📡 **Live WireGuard telemetry** (Handshake timestamps, authenticated roaming endpoints, byte counters) - 🔄 **Desired-state reconciliation** (Continuous closed-loop convergence) - 🧭 **Drift detection** (5-subsystem read-only deterministic planning) - ♻️ **Restart recovery** (Cold-boot reconstruction of live kernel networking from SQLite) - 🧪 **Simulation engine** (Full macOS/Windows local development fallback) - 🖥️ **CLI + REST API + WebSocket + SPA** (Zero-dependency embedded interface) - 📊 **Diagnostics** (Automated health inspection across 9 subsystems with remediation hints) - 💾 **Backup/restore** (Atomic online `VACUUM INTO` snapshots with SHA-256 manifests) - 🔑 **Administrator/authentication/API tokens** (Argon2id, SHA-256 tokens, single-admin `CHECK (id=1)`) - 📱 **Client profiles + generated configurations + QR** (Pure Rust SVG, PNG, and ASCII QR engine) - 📦 **Standalone Linux deployment** (Zero scripting runtime, self-contained distribution packages) - 🔒 **systemd capability isolation** (`CAP_NET_ADMIN`, `CAP_NET_BIND_SERVICE`, full sandbox directives) --- ## SQLite as the Single Authority The foundational architectural choice in `nx9-wg` is **SQLite as the authoritative desired state**. WireGuard is not the configuration database. The kernel is not the configuration database either. ``` SQLite │ │ desired state ▼ nx9-wg reconciler │ │ convergence ▼ Linux kernel ``` If the kernel state disappears after a reboot or network interface reset, the system deterministically reconstructs the entire network topology from the authoritative desired state in SQLite. --- ## The NX9 Philosophy in Implementation `nx9-wg` deliberately avoids building an application around a fragile pile of external utilities: - ❌ `wg` - ❌ `wg-quick` - ❌ `ip` - ❌ `iptables` - ❌ `nft` CLI - ❌ `sysctl` CLI - ❌ shell orchestration - ❌ Node.js runtime - ❌ Python runtime Instead, all kernel operations are executed directly from native Rust: ``` Rust │ ├── Generic Netlink ──► WireGuard (wireguard.ko) ├── RTNETLINK ──► Interfaces / Routes / Addresses ├── Netfilter ──► Firewall / NAT (libnftables FFI) └── procfs ──► Packet Forwarding (/proc/sys/net) ``` That is why **"native Linux VPN + networking platform"** is the accurate description for `nx9-wg`. --- ## Current Status | Subsystem | Status | Verification Evidence | | :--- | :---: | :--- | | **System Architecture** | **Complete** | Six-crate modular workspace with strict layer boundaries | | **Control Plane & REST API** | **Complete** | Axum HTTP server with session/bearer auth and WebSocket stream | | **Native WireGuard Engine** | **Implemented** | RTNETLINK link lifecycle & Generic Netlink cryptokey exchange | | **Native Linux Networking** | **Implemented** | RTNETLINK address/route management & direct procfs forwarding | | **Native nftables / NAT** | **Implemented** | In-process `libnftables` FFI scoped to `table inet nx9_wg` | | **Reconciliation Engine** | **Implemented** | Closed-loop drift detection, read-only plan, and serialized apply | | **Web User Interface** | **Verified** | Zero-dependency SPA with theme engine and 15 interactive routes | | **Release & Deployment** | **Implemented** | Standalone installer, uninstaller, packaging script, and systemd unit | | **SAFE Verification Suite** | **PASS** | 91 workspace tests, 203 CLI tests, 19 integration tests, 23 live tests | | **LIVE Kernel Verification** | **Framework Ready** | SAFE mode (`LIVE=0`) verified; dedicated host ready via `LIVE=1` | --- ## Six-Crate Workspace Architecture - [**`crates/nx9-wg-core`**](crates/nx9-wg-core): Typed domain models, validation, cryptography, and hierarchical configuration loader. - [**`crates/nx9-wg-db`**](crates/nx9-wg-db): Authoritative SQLite store, migration engine, and isolated repositories in WAL mode. - [**`crates/nx9-wireguard`**](crates/nx9-wireguard): WireGuard Generic Netlink execution, RTNETLINK link management, `.conf` builder, and pure Rust QR engine. - [**`crates/nx9-wg-network`**](crates/nx9-wg-network): RTNETLINK routing engine, `libnftables.so.1` Netfilter integration, and procfs forwarding. - [**`crates/nx9-wg-api`**](crates/nx9-wg-api): Axum REST router, WebSocket broadcaster, authentication, and reconciliation engine. - [**`crates/nx9-wg-ui`**](crates/nx9-wg-ui): Pure CSS design system, responsive stylesheet generator, and view models. --- ## Quick Start ### 1. Build and Run Workspace Tests ```bash # Build the release binary cargo build --release # Run the complete test suite (91/91 passed) cargo test --workspace ``` ### 2. Initialize Administrator Account ```bash # Generate a cryptographically secure random password written to a restricted file: ./target/release/nx9-wg init --generate-password --write-password-file /tmp/admin.pw ``` ### 3. Start the API Daemon & Web UI ```bash ./target/release/nx9-wg serve --bind 127.0.0.1:8080 ``` Open your browser at `http://127.0.0.1:8080/` to access the Web UI. ### 4. Interface Creation & Peer Enrollment via CLI ```bash # Create WireGuard interface wg0 ./target/release/nx9-wg interface create --address-v4 10.100.0.1/24 wg0 --port 51820 # Enroll peer Alice with automatic IP allocation and mobile MTU profile: ./target/release/nx9-wg peer create --interface wg0 --name alice --profile full_tunnel --mtu 1280 # Render ASCII QR code in terminal for mobile scanning: ./target/release/nx9-wg peer qr # Export WireGuard client configuration file: ./target/release/nx9-wg peer config # Apply reconciliation to synchronize kernel state: ./target/release/nx9-wg reconcile apply ``` --- ## Production Installation To install `nx9-wg` as a managed systemd service: ```bash # Download and extract release archive: tar -xzf nx9-wg-v0.8.0-linux-x86_64.tar.gz cd nx9-wg-v0.8.0-linux-x86_64 # Run production installer: sudo bash install.sh ``` See the [**Installation & Deployment Guide**](docs/installation.md) for step-by-step instructions. --- ## Complete Documentation Index | Topic | Documentation Link | | :--- | :--- | | **Philosophy & Intent** | [**NX9 Design Principles**](docs/design-principles.md) | | **System Architecture** | [**Architecture Reference**](docs/architecture.md) | | **Installation & Setup** | [**Installation Guide**](docs/installation.md) | | **Platform Requirements** | [**Linux Requirements**](docs/linux_requirements.md) | | **Native WireGuard** | [**Native WireGuard Engine**](docs/native-wireguard.md) | | **Native Networking** | [**Native Network & Routing Engine**](docs/native-network.md) | | **nftables & NAT** | [**Native nftables Engine**](docs/nftables.md) • [**Firewall/NAT Model**](docs/firewall_nat.md) | | **State Reconciliation** | [**Reconciliation & Convergence**](docs/reconciliation.md) | | **Web User Interface** | [**Web UI & SPA Routes**](docs/ui.md) | | **REST API & WebSockets** | [**API Reference**](docs/api.md) | | **CLI Commands** | [**CLI Command Reference**](docs/cli.md) | | **Security Architecture** | [**Security Model & Permissions**](docs/security.md) | | **Backup & Recovery** | [**Backup & Disaster Recovery**](docs/backup_restore.md) | | **Release Engineering** | [**Release Packaging & Systemd**](docs/release.md) | | **Quality Assurance** | [**Testing Strategy**](docs/testing.md) | | **Developer Guide** | [**Development Guide**](docs/development.md) | | **Configuration** | [**Configuration Reference**](docs/configuration.md) | | **Containerization** | [**Docker Deployment**](docs/docker.md) | | **Master Index** | [**Documentation Master Index**](docs/README.md) | --- ## License Dual-licensed under either: - **MIT License** ([`LICENSE-MIT`](LICENSE-MIT)) - **Apache License, Version 2.0** ([`LICENSE-APACHE`](LICENSE-APACHE)) at your option.