83 lines
6.8 KiB
Markdown
83 lines
6.8 KiB
Markdown
# NX9 WireGuard — Architectural & Design Principles
|
|
|
|
> **"Sovereign, self-hosted, Linux-native network infrastructure built from first principles."**
|
|
|
|
---
|
|
|
|
## 1. The NX9 Philosophy
|
|
|
|
`nx9-wg` was conceived as a clean, high-performance, single-binary WireGuard appliance and network management engine for sovereign infrastructure. It is built upon the following foundational principles:
|
|
|
|
### A. Self-Hosted First & Full Ownership
|
|
Network infrastructure is a critical sovereignty boundary. Administrators must have complete, unencumbered ownership of their cryptographic keys, network routing policies, and configuration data. `nx9-wg` operates entirely locally without phone-home telemetry, cloud dependencies, or external licensing servers.
|
|
|
|
### B. Linux-Native Architecture
|
|
Rather than treating the Linux kernel as an opaque black box accessed via shell utilities, `nx9-wg` communicates directly with kernel networking subsystems using native Netlink protocols (RTNETLINK and WireGuard Generic Netlink) and direct `/proc` interfaces.
|
|
|
|
### C. FOSS & No Vendor Lock-In
|
|
`nx9-wg` is free and open-source software dual-licensed under `MIT OR Apache-2.0`. All database schemas, configuration formats, cryptographic profiles, and backup archives use open, standard specifications (SQLite, TOML, JSON, Base64).
|
|
|
|
### D. Zero Scripting Runtime Dependencies
|
|
The entire application—from the HTTP/WebSocket API server and reactive SPA frontend to cryptographic key generation, QR rendering, database migrations, and kernel Netlink communication—is compiled into a single native Rust binary. There is zero runtime dependency on Node.js, npm, Electron, Python, or external shell scripts.
|
|
|
|
### E. CLI-First & Headless Operational Simplicity
|
|
Every capability exposed by the Web UI or REST API is first available as a first-class native CLI command supporting human-readable tables as well as machine-readable JSON, YAML, and CSV formats.
|
|
|
|
---
|
|
|
|
## 2. Why Not an Imperative Shell Wrapper?
|
|
|
|
Many existing WireGuard management tools act merely as thin Web UI wrappers around command-line utilities like `wg`, `wg-quick`, `iptables`, and `ip`. This model introduces severe architectural limitations:
|
|
|
|
1. **Fragile Process Spawning**: Shelling out to external executables (`std::process::Command`) incurs substantial overhead, introduces quoting/injection risks, and parses fragile string outputs that break across operating system versions.
|
|
2. **Lack of Authoritative State**: Relying on `/etc/wireguard/wg0.conf` text files makes atomic transactional updates, relational constraints, foreign keys, and audit logging difficult and error-prone.
|
|
3. **Configuration Drift**: Imperative changes applied directly to the kernel or configuration files easily drift out of sync with what the web management interface displays.
|
|
4. **Host Network Destruction**: Script-based firewall and routing flush commands (e.g., `iptables -F` or modifying default routing tables) often disrupt container engines (Docker, Podman), hypervisors (KVM, libvirt), or host networking.
|
|
|
|
---
|
|
|
|
## 3. Core Architectural Invariants
|
|
|
|
### 1. SQLite Desired-State Authority
|
|
The SQLite database is the single authoritative source of truth for all intended configuration state (interfaces, peers, networks, routes, firewall rules, and NAT policies). The kernel execution plane is a cache that is brought into alignment through continuous, deterministic reconciliation.
|
|
|
|
### 2. Zero Subprocess Execution Guarantee
|
|
Production Rust code in `nx9-wg` is strictly forbidden from invoking `std::process::Command` or `tokio::process`. All kernel mutations occur via in-process Netlink sockets or `libnftables` Netfilter bindings.
|
|
|
|
### 3. Strict Resource Ownership & Scoping
|
|
- **Firewall Rules**: Confined strictly to `table inet nx9_wg`. External tables created by Docker, Kubernetes, or host firewalls are never modified or flushed.
|
|
- **Routing**: `nx9-wg` manages only routes explicitly defined in its database or attached to its managed interfaces. Default gateway routes and unmanaged host routes are never altered.
|
|
|
|
### 4. Single Administrator Security Model
|
|
`nx9-wg` avoids complex RBAC frameworks in favor of a strictly enforced single-administrator model locked by database constraints (`CHECK (id = 1)`). This eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
|
|
|
|
### 5. Multi-Cycle Idempotent Reconciliation
|
|
State reconciliation follows a deterministic, read-only plan phase followed by a serialized apply phase and post-apply verification. Repeated executions against an already converged system produce zero mutations (NOOP).
|
|
|
|
---
|
|
|
|
## 4. Architectural Summary
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Single Administrator (Web UI / CLI) │
|
|
└───────────────────────────┬────────────────────────────┘
|
|
│
|
|
┌───────────────────────────▼────────────────────────────┐
|
|
│ Axum REST API & WebSockets │
|
|
└───────────────────────────┬────────────────────────────┘
|
|
│
|
|
┌───────────────────────────▼────────────────────────────┐
|
|
│ Authoritative SQLite Desired State (WAL) │
|
|
└───────────────────────────┬────────────────────────────┘
|
|
│ (Periodic / Triggered)
|
|
┌───────────────────────────▼────────────────────────────┐
|
|
│ Reconciliation Engine │
|
|
└───────┬───────────────────┼───────────────────┬────────┘
|
|
│ (RTNETLINK/Genl) │ (libnftables) │ (Procfs)
|
|
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
|
|
│ WireGuard Genl│ │ inet nx9_wg │ │ IP Forwarding │
|
|
│ Kernel Socket │ │ Table Filter │ │ /proc/sys │
|
|
└───────────────┘ └───────────────┘ └───────────────┘
|
|
```
|