thakares/nx9-wg
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: complete nx9-wg v0.8.0 platform

Browse Source
This commit is contained in:
thakares committed 2026-08-17 14:25:45 +05:30
1 parent c75e5c4e71
commit c8a9b7cde6
52 files changed
+7751 -725
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/cli.md
+70 -91
View File
@@ -1,49 +1,48 @@
# Native CLI Command Reference (`nx9-wg`)
The `nx9-wg` binary provides 100% native CLI coverage for the entire NX9 WireGuard application stack.
The CLI directly executes native Rust application services (`Store`, `WireGuardEngine`, `NetworkEngine`, `ReconciliationEngine`, `BackupService`, `AuthService`) without calling external subprocesses.
The `nx9-wg` binary provides 100% native CLI coverage across all 17 application subcommands without spawning external subprocesses.
---
## Global Options
## 1. Global Options
- `-c, --config <PATH>`: Path to configuration file (env: `NX9_WG_CONFIG`, default: `/etc/nx9-wg/config.toml`)
- `-d, --data-dir <PATH>`: Path to data directory (env: `NX9_WG_DATA_DIR`, default: `/var/lib/nx9-wg`)
- `--database <PATH>`: Explicit SQLite database path or URL (env: `NX9_WG_DATABASE`)
- `--format <table|json|yaml|csv>`: Output formatting style (default: `table`)
- `--json`: Output strictly in formatted JSON
- `-q, --quiet`: Suppress status and conversational messages
- `-v, --verbose`: Enable debug trace output
- `--log-level <LEVEL>`: Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`, env: `NX9_WG_LOG_LEVEL`)
| Option | Environment Variable | Description |
| :--- | :--- | :--- |
| `-c, --config <PATH>` | `NX9_WG_CONFIG` | Path to configuration file (default: `/etc/nx9-wg/config.toml`) |
| `-d, --data-dir <PATH>` | `NX9_WG_DATA_DIR` | Path to data directory (default: `/var/lib/nx9-wg`) |
| `--database <PATH>` | `NX9_WG_DATABASE` | Specific SQLite database file path or URL |
| `--format <FORMAT>` | N/A | Output format (`table`, `json`, `yaml`, `csv`, default: `table`) |
| `--json` | N/A | Convenience flag for strict JSON output |
| `-q, --quiet` | N/A | Suppress status and conversational messages |
| `-v, --verbose` | N/A | Enable verbose trace logging |
| `--log-level <LEVEL>` | `NX9_WG_LOG_LEVEL` | Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`) |
---
## Command Groups
## 2. Command Groups Reference
### 1. `version`
Displays version, build metadata, target architecture, and feature capabilities.
Displays version, build edition, architecture, OS platform, and security flags.
```bash
nx9-wg version
nx9-wg version --format json
```
### 2. `serve`
Starts the Axum REST API, WebSocket event streamer, and background reconciliation daemon.
Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler.
```bash
nx9-wg serve
# To intentionally expose the management API on all interfaces:
nx9-wg serve --bind 0.0.0.0:8080
```
### 3. `init`
Initializes the single administrator account across 7 supported bootstrap sources.
Initializes the single administrator account across 7 bootstrap sources.
```bash
# Generated password:
nx9-wg init --generate-password --write-password-file /root/admin-pw.txt
# Generated secure password:
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
# Password from standard input:
echo "SecureSecret123!" | nx9-wg init --password-stdin
# Password via stdin:
echo "StrongPassword123!" | nx9-wg init --password-stdin
# Password from file:
nx9-wg init --password-file /run/secrets/admin_pw
@@ -51,103 +50,83 @@ nx9-wg init --password-file /run/secrets/admin_pw
### 4. `system`
- `nx9-wg system status`: System database statistics and object counts.
- `nx9-wg system health`: System and database connectivity health check.
- `nx9-wg system health`: System and SQLite connectivity health check.
- `nx9-wg system info`: System platform, architecture, and runtime paths.
- `nx9-wg system settings list`: List all configuration key-value settings.
- `nx9-wg system settings list`: List all key-value settings.
- `nx9-wg system settings get <KEY>`: Query setting value.
- `nx9-wg system settings set <KEY> <VALUE> [--secret]`: Save setting.
- `nx9-wg system settings delete <KEY>`: Delete setting.
### 5. `admin`
- `nx9-wg admin status`: View administrator profile and last login metrics.
- `nx9-wg admin create`: Provision administrator if not already initialized.
- `nx9-wg admin password --new-password <PW> | --stdin | --password-file <PATH> | --generate`: Update password and invalidate all sessions.
- `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>] [--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.
- `nx9-wg admin info`: Query administrator account metadata.
- `nx9-wg admin password`: Change administrator password.
- `nx9-wg admin token create <NAME> [--expires-in-days N] [--write-token-file PATH]`: Generate API token.
- `nx9-wg admin token list`: List active API tokens.
- `nx9-wg admin token revoke <TOKEN_ID>`: Revoke an API token.
- `nx9-wg admin session list`: List active browser sessions.
- `nx9-wg admin session revoke-all`: Invalidate all active sessions.
### 6. `interface`
- `nx9-wg interface list`: List all WireGuard interfaces.
- `nx9-wg interface show <NAME_OR_ID>`: Inspect interface details.
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--port <PORT>] [--address-v6 <CIDR>] [--mtu <MTU>] [--dns <DNS>]`: Create an interface.
- `nx9-wg interface update <NAME_OR_ID> [--port <PORT>] [--address-v4 <CIDR>] [--enabled <BOOL>]`: Update interface properties.
- `nx9-wg interface enable <NAME_OR_ID>` / `disable <NAME_OR_ID>`: Toggle administrative state.
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface and associated peers.
- `nx9-wg interface status <NAME>`: Query live interface telemetry.
- `nx9-wg interface reconcile <NAME>`: Reconcile interface state with the Linux kernel.
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--port PORT] [--mtu MTU]`: Create interface.
- `nx9-wg interface show <NAME_OR_ID>`: Show interface configuration.
- `nx9-wg interface enable <NAME_OR_ID>`: Enable interface (`IFF_UP`).
- `nx9-wg interface disable <NAME_OR_ID>`: Disable interface (`IFF_DOWN`).
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface.
### 7. `peer`
- `nx9-wg peer list [--interface <NAME_OR_ID>]`: List enrolled peers.
- `nx9-wg peer show <PEER_ID>`: Inspect peer configuration and metadata.
- `nx9-wg peer create --interface <NAME_OR_ID> --name <NAME> [--address-v4 <CIDR>] [--allowed-ips <CIDRS>] [--endpoint <IP:PORT>]`: Enroll peer.
- `nx9-wg peer update <PEER_ID> [--name <NAME>] [--allowed-ips <CIDRS>] [--enabled <BOOL>]`: Update peer parameters.
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>` / `revoke <PEER_ID>`: Peer lifecycle transitions.
- `nx9-wg peer delete <PEER_ID>`: Remove peer.
- `nx9-wg peer status <PEER_ID>`: Live handshake, endpoint, and bandwidth telemetry.
- `nx9-wg peer config <PEER_ID> [--output <PATH>]`: Generate standard client `.conf` file.
- `nx9-wg peer qr <PEER_ID> [--qr-format <terminal|svg|png>]`: Generate enrollment QR code.
- `nx9-wg peer list [--interface NAME]`: List enrolled peers.
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--profile PROFILE] [--mtu MTU]`: Enroll peer.
- `nx9-wg peer show <PEER_ID>`: Show peer configuration.
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>`: Toggle peer state.
- `nx9-wg peer delete <PEER_ID>`: Delete peer.
- `nx9-wg peer config <PEER_ID> [--device DEV] [--connection CONN]`: Output `.conf` client file.
- `nx9-wg peer qr <PEER_ID>`: Render ASCII QR code in terminal for mobile scanning.
### 8. `network`
- `nx9-wg network list`: List defined subnet networks.
- `nx9-wg network show <ID>`: Inspect network details.
- `nx9-wg network create <NAME> <CIDR> [--description <TEXT>]`: Create subnet network.
- `nx9-wg network update <ID> [--name <NAME>] [--cidr <CIDR>] [--enabled <BOOL>]`: Update network.
- `nx9-wg network delete <ID>`: Delete subnet network.
- `nx9-wg network list`: List subnet networks.
- `nx9-wg network create <NAME> --cidr <CIDR>`: Create network.
- `nx9-wg network delete <NAME_OR_ID>`: Delete network.
### 9. `route`
- `nx9-wg route list`: List configured kernel routing rules.
- `nx9-wg route show <ID>`: Inspect route rule.
- `nx9-wg route add --destination <CIDR> [--gateway <IP>] [--interface-name <IFACE>] [--metric <METRIC>]`: Add route.
- `nx9-wg route update <ID> [--destination <CIDR>] [--gateway <IP>] [--metric <METRIC>]`: Update route.
- `nx9-wg route delete <ID>`: Delete route.
- `nx9-wg route status`: Status of kernel routing table management.
- `nx9-wg route sync`: Synchronize desired routes to Linux kernel routing table.
- `nx9-wg route list`: List routing table entries.
- `nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]`: Add route.
- `nx9-wg route delete <ROUTE_ID>`: Delete route.
### 10. `firewall`
- `nx9-wg firewall list`: List nftables firewall rules.
- `nx9-wg firewall show <ID>`: Inspect firewall rule.
- `nx9-wg firewall add --name <NAME> [--direction <in|out|forward>] [--source <CIDR>] [--destination <CIDR>] [--protocol <tcp|udp|icmp|any>] [--port <PORT>] [--action <accept|drop|reject>] [--priority <INT>]`: Add rule.
- `nx9-wg firewall update <ID> [--action <ACTION>] [--priority <INT>] [--enabled <BOOL>]`: Update rule.
- `nx9-wg firewall delete <ID>` / `enable <ID>` / `disable <ID>`: Rule management.
- `nx9-wg firewall status`: Inspect active nftables ruleset and table.
- `nx9-wg firewall sync`: Synchronize firewall ruleset to nftables.
- `nx9-wg firewall add --name <NAME> [--protocol PROTO] [--port PORT] [--action ACTION] [--priority P]`: Add rule.
- `nx9-wg firewall enable <RULE_ID>` / `disable <RULE_ID>`: Toggle rule.
- `nx9-wg firewall delete <RULE_ID>`: Delete rule.
### 11. `nat`
- `nx9-wg nat status`: Inspect NAT masquerade status and managed subnets.
- `nx9-wg nat enable` / `disable`: Toggle NAT masquerade setting.
- `nx9-wg nat list`: List subnets configured for NAT masquerade.
- `nx9-wg nat sync`: Synchronize NAT rules to nftables postrouting chain.
- `nx9-wg nat status`: Query NAT masquerade state.
- `nx9-wg nat enable` / `disable`: Toggle outbound NAT masquerading.
### 12. `forwarding`
- `nx9-wg forwarding status`: Inspect IPv4 and IPv6 kernel packet forwarding state.
- `nx9-wg forwarding enable` / `disable`: Enable or disable kernel packet forwarding.
- `nx9-wg forwarding sync`: Synchronize sysctl forwarding parameters.
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP forwarding.
### 13. `reconcile`
- `nx9-wg reconcile status`: Summary of detected drift across all subsystems.
- `nx9-wg reconcile plan [--interface <NAME>]`: Dry-run drift analysis without state mutation.
- `nx9-wg reconcile apply [--interface <NAME>]`: Reconcile SQLite desired state to Linux kernel.
- `nx9-wg reconcile verify`: Assert zero drift exists between SQLite and kernel (returns exit code 1 if drift exists).
- `nx9-wg reconcile plan`: Calculate read-only drift between SQLite and kernel.
- `nx9-wg reconcile apply`: Apply mutations across all execution planes.
- `nx9-wg reconcile verify`: Post-apply verification check.
### 14. `backup`
- `nx9-wg backup create [--description <TEXT>]`: Generate consistent SQLite backup snapshot with SHA-256 manifest.
- `nx9-wg backup list`: List all backup snapshots.
- `nx9-wg backup show <ID>`: Inspect backup metadata and file size.
- `nx9-wg backup verify --path <PATH>`: Verify integrity and checksum of backup archive.
- `nx9-wg backup restore --path <PATH> --yes`: Safely restore database with pre-restore safety snapshot.
- `nx9-wg backup delete <ID>`: Delete backup record and archive.
- `nx9-wg backup list`: List backup snapshots.
- `nx9-wg backup create [--description DESC]`: Generate atomic SQLite online backup (`VACUUM INTO`).
- `nx9-wg backup verify <PATH>`: Verify SQLite 3 header and SHA-256 checksum.
- `nx9-wg backup restore <PATH_OR_ID>`: Restore database with automatic safety snapshot.
### 15. `audit`
- `nx9-wg audit list [--event-type <TYPE>] [--actor <ACTOR>] [--resource-type <RESOURCE>] [--limit <N>] [--offset <N>]`: Query security audit trail.
- `nx9-wg audit show <ID>`: Inspect complete audit event details.
- `nx9-wg audit list [--limit N] [--event-type TYPE]`: List append-only audit trail records.
### 16. `live`
- `nx9-wg live interface list` / `show <NAME>`: Query active WireGuard interfaces from kernel.
- `nx9-wg live peer list <IFACE>` / `show <KEY_OR_ID>`: Query active peers from kernel.
- `nx9-wg live routes`: Query live kernel routing status.
- `nx9-wg live firewall`: Query live nftables ruleset.
- `nx9-wg live forwarding`: Query live kernel forwarding sysctls.
- `nx9-wg live nat`: Query live NAT state.
- `nx9-wg live interfaces`: Query active Linux kernel WireGuard interfaces.
- `nx9-wg live peers <IFACE>`: Query live peers, transfer bytes, and handshakes.
- `nx9-wg live routes`: Query live kernel routing table.
- `nx9-wg live nftables`: Query active `table inet nx9_wg` ruleset.
### 17. `diagnostics`
- `nx9-wg diagnostics inspect all`: Inspect health across all 9 subsystems.
- `nx9-wg diagnostics inspect <SUBSYSTEM>`: Inspect specific subsystem (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`).