0 Fork 0

Files

T

thakares 4dfe42fe68 release: NX9-WG v1.0.0

2026-08-18 17:32:56 +05:30

9.8 KiB

Raw Blame History

NX9 WireGuard (`nx9-wg`)

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	162 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 (162/162 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-v1.0.0-linux-x86_64.tar.gz
cd nx9-wg-v1.0.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	Comprehensive Testing Specification
Developer Guide	Development Guide
Configuration	Configuration Reference
Containerization	Docker Deployment
Master Index	Documentation Master Index

License

Dual-licensed under either:

MIT License (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

at your option.

9.8 KiB Raw Blame History

NX9 WireGuard (nx9-wg)