nx9-wg/README.md

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.

---

Key Features

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

---

Quick Start

1. Build and Run Tests

# Build the workspace
cargo build --release

# Run the complete workspace test suite
cargo test --workspace

2. Initialize the Administrator

# 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!"

3. Start the Daemon

cargo run -- serve

# To intentionally expose the management API on all interfaces:
cargo run -- serve --bind 0.0.0.0:8080

4. Create an Interface and Enroll a Peer via CLI

# Create WireGuard interface wg0
cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24

# Create peer Alice
cargo run -- peer create --interface <INTERFACE_NAME_OR_ID> --name alice --address-v4 10.0.0.2/32

# Display terminal QR code for instant mobile scan:
cargo run -- peer qr <PEER_UUID>

# Print client .conf file:
cargo run -- peer config <PEER_UUID>

---

Architecture Overview

 ┌────────────────────────────────────────────────────────┐
 │                      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)    │
             └───────────────────────────────┘

For complete architectural details, see Architecture Documentation.

---

Documentation Index

• Architecture & Crate Design
• Installation & Systemd Setup
• Configuration Reference
• CLI Command Guide
• REST API & WebSocket Reference
• Security Model & Auditing
• Docker & Container Deployment
• Backup & Restore Procedures
• Development & Testing Guide
• Linux Kernel Requirements

---

License

Copyright (c) NX9 Systems. All rights reserved.