docs: align documentation with nx9-wg implementation
This commit is contained in:
thakares committed
1 parent
fa676864be
commit
9678422187
5 files changed
+23
-16
No files matched your search
@@ -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]`).
|
||||
|
||||
+4
-1
@@ -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 <SESSION_ID>`: Invalidate specific session.
|
||||
- `nx9-wg admin sessions revoke-all`: Invalidate all active administrator sessions.
|
||||
- `nx9-wg admin tokens create --name <NAME> [--days <DAYS>]`: Generate a long-lived API token.
|
||||
- `nx9-wg admin tokens create --name <NAME> [--days <DAYS>] [--write-token-file <PATH>]`: 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 <TOKEN_ID>`: Revoke an API token.
|
||||
|
||||
|
||||
@@ -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 | `<data_dir>/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` |
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in new issue
Block a user