thakaresandCopilot
2ac6c81dfe
- Prevent 'nx9-wg version' from creating data directories by avoiding database initialization. - Create parent directories when an explicit --database path is provided. - Redact printed generated administrator passwords; announce file path or redact instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
# 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, and ASCII terminal QR output.
|
|
- **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
|
|
```bash
|
|
# Build the workspace
|
|
cargo build --release
|
|
|
|
# Run all 41 unit and integration tests
|
|
cargo test --workspace
|
|
```
|
|
|
|
### 2. Initialize the Administrator
|
|
```bash
|
|
# Initialize with a generated password:
|
|
cargo run -- init --generate-password
|
|
|
|
# Or initialize with a specific password:
|
|
cargo run -- init --username admin --password "YourStrongPassword123!"
|
|
```
|
|
|
|
### 3. Start the Daemon
|
|
```bash
|
|
cargo run -- serve --bind 0.0.0.0:8080
|
|
```
|
|
|
|
### 4. Create an Interface and Enroll a Peer via CLI
|
|
```bash
|
|
# 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-id <INTERFACE_UUID> --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](docs/architecture.md).
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Copyright (c) NX9 Systems. All rights reserved.
|