feat: complete nx9-wg v0.8.0 platform
This commit is contained in:
thakares committed
1 parent
c75e5c4e71
commit
c8a9b7cde6
52 files changed
+7751
-725
No files matched your search
@@ -1,123 +1,240 @@
|
||||
# NX9 WireGuard (`nx9-wg`)
|
||||
|
||||
> **A native Rust, self-hosted WireGuard appliance and network management engine for the NX9 ecosystem.**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
`nx9-wg` is designed from first principles as a clean, high-performance replacement for Node.js-based WireGuard managers (such as `wg-easy`). Built entirely in native Rust with zero external scripting runtime dependencies, `nx9-wg` provides authoritative SQLite persistence, robust administrative authentication, native Linux kernel networking, automated reconciliation, and pure Rust QR code and client configuration generation.
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
## The Architectural Distinction
|
||||
|
||||
- **Native Rust Systems Architecture**: Zero Node.js, npm, Python, Electron, or external daemon runners.
|
||||
- **Authoritative SQLite State**: Fully migration-driven schema with WAL mode, foreign key integrity, and isolated repository operations.
|
||||
- **Single Administrator Security Model**: Strictly 1 administrator identity (`CHECK (id = 1)`), Argon2id password hashing, SHA-256 API token authentication, and sliding-window brute force lockout.
|
||||
- **Native Linux WireGuard Engine**: Direct interaction with Linux networking and kernel interfaces without shelling out to `wg` or `wg-quick`.
|
||||
- **nftables Isolation**: Dedicated `table inet nx9_wg` with input, forward, and NAT postrouting masquerade chains.
|
||||
- **Continuous Reconciliation**: Automated drift detection and idempotent convergence between desired database state and live Linux kernel state.
|
||||
- **Pure Rust Client Enrollment**: Full-tunnel and split-tunnel `.conf` builder, high-resolution SVG/PNG QR generator, ASCII terminal QR output, and client-aware environment/MTU profiles.
|
||||
- **Deterministic IP Allocation**: Automatic IPv4/IPv6 peer address allocation with collision and reserved-address protection.
|
||||
- **Consistent Backups**: Atomic SQLite snapshots (`VACUUM INTO`), manifest hashing with SHA-256, verification, and safety snapshots before restore.
|
||||
- **Complete CLI & Axum REST API**: Multi-format CLI (`table`, `json`, `yaml`, `csv`) and RESTful API with real-time WebSocket telemetry.
|
||||
### 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 Tests
|
||||
### 1. Build and Run Workspace Tests
|
||||
```bash
|
||||
# Build the workspace
|
||||
# Build the release binary
|
||||
cargo build --release
|
||||
|
||||
# Run the complete workspace test suite
|
||||
# Run the complete test suite (91/91 passed)
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
### 2. Initialize the Administrator
|
||||
### 2. Initialize Administrator Account
|
||||
```bash
|
||||
# Initialize with a generated password:
|
||||
cargo run -- init --generate-password --write-password-file /tmp/nx9-wg-admin-password
|
||||
|
||||
# Or initialize with a specific password:
|
||||
cargo run -- init --username admin --password "YourStrongPassword123!"
|
||||
# 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 Daemon
|
||||
### 3. Start the API Daemon & Web UI
|
||||
```bash
|
||||
cargo run -- serve
|
||||
|
||||
# To intentionally expose the management API on all interfaces:
|
||||
cargo run -- serve --bind 0.0.0.0:8080
|
||||
./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. Create an Interface and Enroll a Peer via CLI
|
||||
### 4. Interface Creation & Peer Enrollment via CLI
|
||||
```bash
|
||||
# Create WireGuard interface wg0
|
||||
cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24
|
||||
./target/release/nx9-wg interface create --address-v4 10.100.0.1/24 wg0 --port 51820
|
||||
|
||||
# Create peer Alice
|
||||
cargo run -- peer create --interface <INTERFACE_NAME_OR_ID> --name alice --address-v4 10.0.0.2/32
|
||||
# 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
|
||||
|
||||
# Display terminal QR code for instant mobile scan:
|
||||
cargo run -- peer qr <PEER_UUID>
|
||||
# Render ASCII QR code in terminal for mobile scanning:
|
||||
./target/release/nx9-wg peer qr <PEER_UUID>
|
||||
|
||||
# Print client .conf file:
|
||||
cargo run -- peer config <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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
## Production Installation
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ nx9-wg CLI │
|
||||
└───────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼────────────────────────────┐
|
||||
│ Axum REST API & WebSockets │
|
||||
└───────┬───────────────────┬───────────────────┬────────┘
|
||||
│ │ │
|
||||
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
|
||||
│ nx9-db │ │ nx9-wireguard │ │ nx9-network │
|
||||
│ (SQLite+WAL) │ │ (Kernel WG) │ │(Routes+nftables)│
|
||||
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
||||
│ │ │
|
||||
└───────────────────┼───────────────────┘
|
||||
│
|
||||
┌───────────────▼───────────────┐
|
||||
│ Reconciliation Engine │
|
||||
│ (Desired vs Live Kernel) │
|
||||
└───────────────────────────────┘
|
||||
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
|
||||
```
|
||||
|
||||
For complete architectural details, see [Architecture Documentation](docs/architecture.md).
|
||||
See the [**Installation & Deployment Guide**](docs/installation.md) for step-by-step instructions.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Index
|
||||
## Complete Documentation Index
|
||||
|
||||
- [Architecture & Crate Design](docs/architecture.md)
|
||||
- [Installation & Systemd Setup](docs/installation.md)
|
||||
- [Configuration Reference](docs/configuration.md)
|
||||
- [CLI Command Guide](docs/cli.md)
|
||||
- [REST API & WebSocket Reference](docs/api.md)
|
||||
- [Security Model & Auditing](docs/security.md)
|
||||
- [Docker & Container Deployment](docs/docker.md)
|
||||
- [Backup & Restore Procedures](docs/backup_restore.md)
|
||||
- [Development & Testing Guide](docs/development.md)
|
||||
- [Linux Kernel Requirements](docs/linux_requirements.md)
|
||||
| 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
|
||||
|
||||
Copyright (c) NX9 Systems.
|
||||
Dual-licensed under either:
|
||||
- **MIT License** ([`LICENSE-MIT`](LICENSE-MIT))
|
||||
- **Apache License, Version 2.0** ([`LICENSE-APACHE`](LICENSE-APACHE))
|
||||
|
||||
Licensed under either of the following, at your option:
|
||||
|
||||
- [MIT License](LICENSE-MIT)
|
||||
- [Apache License 2.0](LICENSE-APACHE)
|
||||
|
||||
Unless you explicitly state otherwise, any contribution intentionally submitted
|
||||
for inclusion in this project shall be dual-licensed under the MIT License and
|
||||
the Apache License, Version 2.0, without any additional terms or conditions.
|
||||
at your option.
|
||||
Reference in new issue
Block a user