241 lines
9.8 KiB
Markdown
241 lines
9.8 KiB
Markdown
# 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** | 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 <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:
|
|
|
|
```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.
|