From 9678422187df4d515ddb6a21118da15c5303b6b7 Mon Sep 17 00:00:00 2001 From: Sunil Thakare Date: Sun, 16 Aug 2026 18:01:15 +0530 Subject: [PATCH] docs: align documentation with nx9-wg implementation --- README.md | 12 ++++++++---- docs/architecture.md | 16 ++++++++-------- docs/cli.md | 5 ++++- docs/configuration.md | 2 +- docs/installation.md | 4 ++-- 5 files changed, 23 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index dd00c63..fdf1d95 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ - **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. +- **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. @@ -27,14 +28,14 @@ # Build the workspace cargo build --release -# Run all 41 unit and integration tests +# Run the complete workspace test suite cargo test --workspace ``` ### 2. Initialize the Administrator ```bash # Initialize with a generated password: -cargo run -- init --generate-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!" @@ -42,6 +43,9 @@ cargo run -- init --username admin --password "YourStrongPassword123!" ### 3. Start the Daemon ```bash +cargo run -- serve + +# To intentionally expose the management API on all interfaces: cargo run -- serve --bind 0.0.0.0:8080 ``` @@ -51,7 +55,7 @@ cargo run -- serve --bind 0.0.0.0:8080 cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24 # Create peer Alice -cargo run -- peer create --interface-id --name alice --address-v4 10.0.0.2/32 +cargo run -- peer create --interface --name alice --address-v4 10.0.0.2/32 # Display terminal QR code for instant mobile scan: cargo run -- peer qr diff --git a/docs/architecture.md b/docs/architecture.md index 65e9fe0..e861346 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,23 +2,23 @@ ## System Overview -`nx9-wg` is structured as a modular Rust workspace consisting of seven specialized crates and a root binary. +`nx9-wg` is structured as a modular Rust workspace consisting of six specialized crates and a root binary. | Crate | Responsibility | Dependencies | | :--- | :--- | :--- | -| **`nx9-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` | -| **`nx9-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-core`, `sqlx` (sqlite) | -| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-core`, `qrcode`, `image`, `base64` | -| **`nx9-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-core`, `ipnet` | -| **`nx9-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-core`, `nx9-db`, `nx9-wireguard`, `nx9-network`, `axum`, `tower` | -| **`nx9-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-core` | +| **`nx9-wg-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` | +| **`nx9-wg-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-wg-core`, `sqlx` (sqlite) | +| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-wg-core`, `qrcode`, `image`, `base64` | +| **`nx9-wg-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-wg-core`, `ipnet` | +| **`nx9-wg-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-wg-core`, `nx9-wg-db`, `nx9-wireguard`, `nx9-wg-network`, `axum`, `tower` | +| **`nx9-wg-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-wg-core` | | **`nx9-wg`** | Primary application binary providing CLI operations and HTTP daemon server. | All workspace crates, `clap` | --- ## Architectural Invariants -1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-db/`. No other crate or handler interacts with SQLite directly. +1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-wg-db/`. No other crate or handler interacts with SQLite directly. 2. **Zero Shelling Out**: WireGuard, routing, and packet filtering interact with kernel abstractions and netlink without executing `wg`, `wg-quick`, or `iptables` subprocesses. 3. **Single Administrator Model**: The system maintains exactly one administrative identity with `CHECK (id = 1)`. No RBAC, multi-tenant, or organization complexity is introduced. 4. **Secret Redaction**: Passwords, private keys, preshared keys, and API tokens are never logged, persisted in plaintext, or exposed in error messages. All secret wrapper types implement custom `Debug` redactions (`[REDACTED]`). diff --git a/docs/cli.md b/docs/cli.md index df3aacd..6c20be9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -30,6 +30,9 @@ nx9-wg version --format json ### 2. `serve` Starts the Axum REST API, WebSocket event streamer, and background reconciliation daemon. ```bash +nx9-wg serve + +# To intentionally expose the management API on all interfaces: nx9-wg serve --bind 0.0.0.0:8080 ``` @@ -62,7 +65,7 @@ nx9-wg init --password-file /run/secrets/admin_pw - `nx9-wg admin sessions list`: List active sessions. - `nx9-wg admin sessions revoke `: Invalidate specific session. - `nx9-wg admin sessions revoke-all`: Invalidate all active administrator sessions. -- `nx9-wg admin tokens create --name [--days ]`: Generate a long-lived API token. +- `nx9-wg admin tokens create --name [--days ] [--write-token-file ]`: Generate a long-lived API token. The recommended secure workflow writes the one-time plaintext token to a file with restrictive permissions; token hashes are redacted from normal CLI output. - `nx9-wg admin tokens list`: List all API token metadata. - `nx9-wg admin tokens revoke `: Revoke an API token. diff --git a/docs/configuration.md b/docs/configuration.md index 3badb16..64ffdb9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -46,7 +46,7 @@ Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` n | `NX9_WG_CONFIG` | `config_file` | `--config, -c` | Path to TOML configuration file | `/etc/nx9-wg/config.toml` | | `NX9_WG_DATA_DIR` | `data_dir` | `--data-dir, -d` | Path to persistent data directory | `/var/lib/nx9-wg` | | `NX9_WG_DATABASE` | N/A | `--database` | Path to SQLite database file | `/nx9-wg.db` | -| `NX9_WG_LISTEN_ADDR` | `bind_address` | `--bind` | HTTP / WebSocket daemon bind address | `0.0.0.0:8080` | +| `NX9_WG_LISTEN_ADDR` | `bind_address` | `--bind` | HTTP / WebSocket daemon bind address | `127.0.0.1:8080` | | `NX9_WG_LOG_LEVEL` | `log_level` | `--log-level` | Log verbosity filter (`trace`, `debug`, `info`, `warn`, `error`) | `info` | | `NX9_WG_SESSION_TIMEOUT` | `session_expiry_hours` | N/A | Session inactivity timeout in hours | `24` | | `NX9_WG_RECONCILIATION_INTERVAL` | `reconciliation_interval_secs` | N/A | Background kernel reconciliation interval in seconds | `60` | diff --git a/docs/installation.md b/docs/installation.md index 2d53c35..105cd82 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -12,7 +12,7 @@ ### Building from Source ```bash -git clone https://github.com/nx9/nx9-wg.git +git clone ssh://git@git.nx9.in:6645/thakares/nx9-wg.git cd nx9-wg cargo build --release --bin nx9-wg @@ -28,7 +28,7 @@ sudo cp config.example.toml /etc/nx9-wg/config.toml ### Bootstrapping the Administrator Account ```bash -sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg init --generate-password +sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password ``` ---