thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c8a9b7cde6132cde34c8fa61f77cee9f2491f6d9
nx9-wg/README.md
T

9.8 KiB
Raw Blame History

NX9 WireGuard (nx9-wg)

Rust SQLite Platform License Version

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: Typed domain models, validation, cryptography, and hierarchical configuration loader.
  • crates/nx9-wg-db: Authoritative SQLite store, migration engine, and isolated repositories in WAL mode.
  • crates/nx9-wireguard: WireGuard Generic Netlink execution, RTNETLINK link management, .conf builder, and pure Rust QR engine.
  • crates/nx9-wg-network: RTNETLINK routing engine, libnftables.so.1 Netfilter integration, and procfs forwarding.
  • crates/nx9-wg-api: Axum REST router, WebSocket broadcaster, authentication, and reconciliation engine.
  • crates/nx9-wg-ui: Pure CSS design system, responsive stylesheet generator, and view models.

Quick Start

1. Build and Run Workspace Tests

# Build the release binary
cargo build --release

# Run the complete test suite (91/91 passed)
cargo test --workspace

2. Initialize Administrator Account

# 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

./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

# 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 <PEER_UUID>

# Export WireGuard client configuration file:
./target/release/nx9-wg peer config <PEER_UUID>

# Apply reconciliation to synchronize kernel state:
./target/release/nx9-wg reconcile apply

Production Installation

To install nx9-wg as a managed systemd service:

# 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 for step-by-step instructions.

Complete Documentation Index

Topic Documentation Link
Philosophy & Intent NX9 Design Principles
System Architecture Architecture Reference
Installation & Setup Installation Guide
Platform Requirements Linux Requirements
Native WireGuard Native WireGuard Engine
Native Networking Native Network & Routing Engine
nftables & NAT Native nftables Engine • Firewall/NAT Model
State Reconciliation Reconciliation & Convergence
Web User Interface Web UI & SPA Routes
REST API & WebSockets API Reference
CLI Commands CLI Command Reference
Security Architecture Security Model & Permissions
Backup & Recovery Backup & Disaster Recovery
Release Engineering Release Packaging & Systemd
Quality Assurance Testing Strategy
Developer Guide Development Guide
Configuration Configuration Reference
Containerization Docker Deployment
Master Index Documentation Master Index

License

Dual-licensed under either:

at your option.

Reference in new issue View Git Blame Copy Permalink