178 lines
10 KiB
Markdown
178 lines
10 KiB
Markdown
# Native CLI Command Reference (`nx9-wg`)
|
|
|
|
The `nx9-wg` binary provides native CLI coverage across all 18 application command groups without spawning external subprocesses.
|
|
|
|
---
|
|
|
|
## 1. Global Options
|
|
|
|
| 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`) |
|
|
|
|
---
|
|
|
|
## 2. Command Groups Reference
|
|
|
|
### 1. `version`
|
|
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 daemon, WebSocket streamer, and background reconciliation scheduler.
|
|
```bash
|
|
nx9-wg serve
|
|
nx9-wg serve --bind 0.0.0.0:8080
|
|
```
|
|
|
|
### 3. `init`
|
|
Initializes the single administrator account across bootstrap sources.
|
|
```bash
|
|
# Generate secure random password written to a restricted file:
|
|
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
|
|
|
# Password via stdin:
|
|
echo "StrongPassword123!" | nx9-wg init --password-stdin
|
|
|
|
# Password from file:
|
|
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 SQLite connectivity health check.
|
|
- `nx9-wg system info`: System platform, architecture, and runtime paths.
|
|
- `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 (validates `wireguard.server_host`, `wireguard.server_port`, `wireguard.server_endpoint_enabled`).
|
|
- `nx9-wg system settings delete <KEY>`: Delete setting.
|
|
|
|
```bash
|
|
# Configure persistent WireGuard server endpoint:
|
|
nx9-wg system settings set wireguard.server_host vpn.thakares.com
|
|
nx9-wg system settings set wireguard.server_port 51820
|
|
nx9-wg system settings set wireguard.server_endpoint_enabled true
|
|
```
|
|
|
|
### 5. `admin`
|
|
- `nx9-wg admin status`: Query administrator account metadata.
|
|
- `nx9-wg admin create [--username U] [--password P | --password-stdin | --generate-password]`: Bootstrap admin if uninitialized.
|
|
- `nx9-wg admin password [--new-password P | --stdin | --password-file F | --generate]`: Change administrator password.
|
|
- `nx9-wg admin tokens create --name <NAME> [--days N] [--write-token-file PATH]`: Generate API token.
|
|
- `nx9-wg admin tokens list`: List active API tokens.
|
|
- `nx9-wg admin tokens revoke <TOKEN_ID>`: Revoke an API token.
|
|
- `nx9-wg admin sessions list`: List active browser sessions.
|
|
- `nx9-wg admin sessions revoke <SESSION_ID>`: Revoke an active session.
|
|
- `nx9-wg admin sessions revoke-all`: Invalidate all active sessions.
|
|
|
|
### 6. `interface`
|
|
- `nx9-wg interface list`: List all WireGuard interfaces.
|
|
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--address-v6 <CIDR>] [--port PORT] [--mtu MTU] [--dns DNS]`: Create interface.
|
|
- `nx9-wg interface show <NAME_OR_ID>`: Show interface details.
|
|
- `nx9-wg interface update <NAME_OR_ID> [--port P] [--address-v4 A] [--address-v6 A] [--mtu M] [--dns D] [--enabled BOOL]`: Update interface.
|
|
- `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 (cascades to peers).
|
|
- `nx9-wg interface status <NAME_OR_ID>`: Show live interface status and peer metrics.
|
|
- `nx9-wg interface reconcile <NAME_OR_ID>`: Reconcile specific interface with kernel.
|
|
|
|
### 7. `peer`
|
|
- `nx9-wg peer list [--interface NAME_OR_ID]`: List enrolled peers.
|
|
- `nx9-wg peer show <PEER_ID>`: Show peer configuration.
|
|
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--peer-type TYPE] [--profile PROFILE] [--network NET] [--address-v4 CIDR] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu MTU] [--expires-at RFC3339]`: Enroll peer.
|
|
- `nx9-wg peer update <PEER_ID> [--name N] [--allowed-ips IPS] [--endpoint EP] [--persistent-keepalive SECS] [--mtu M] [--enabled BOOL]`: Update peer.
|
|
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>`: Toggle peer state.
|
|
- `nx9-wg peer revoke <PEER_ID>`: Revoke peer.
|
|
- `nx9-wg peer expire <PEER_ID>`: Mark peer as expired.
|
|
- `nx9-wg peer lifecycle <PEER_ID>`: Show peer lifecycle metadata.
|
|
- `nx9-wg peer status <PEER_ID>`: Show live peer status and telemetry.
|
|
- `nx9-wg peer delete <PEER_ID>`: Delete peer.
|
|
- `nx9-wg peer config <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--output PATH]`: Export `.conf` client file (uses persistent `wireguard.server_*` settings or `--endpoint` override).
|
|
- `nx9-wg peer qr <PEER_ID> [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF] [--endpoint EP] [--qr-format terminal|svg|png]`: Render QR code in terminal, SVG, or PNG format.
|
|
|
|
### 8. `profile`
|
|
- `nx9-wg profile list [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT]`: List client configuration profiles.
|
|
- `nx9-wg profile show <PROFILE_ID>`: Show details of a client profile (e.g. `default-mobile`, `android-mobile`).
|
|
- `nx9-wg profile validate <MTU>`: Validate MTU against safe operational limits.
|
|
- `nx9-wg profile resolve [--provider PROV] [--device DEV] [--connection CONN] [--nat NAT] [--mtu MTU] [--profile PROF]`: Resolve optimal client profile and MTU.
|
|
|
|
### 9. `network`
|
|
- `nx9-wg network list`: List subnet networks.
|
|
- `nx9-wg network show <ID>`: Show network details.
|
|
- `nx9-wg network create <NAME> --cidr <CIDR> [--description DESC]`: Create network.
|
|
- `nx9-wg network available <ID> [--limit N] [--interface IFACE]`: Show available unallocated IP addresses.
|
|
- `nx9-wg network allocations <ID>`: Show allocated IP addresses and peer mappings.
|
|
- `nx9-wg network update <ID> [--name N] [--cidr C] [--description D] [--enabled BOOL]`: Update network.
|
|
- `nx9-wg network delete <ID>`: Delete subnet network.
|
|
|
|
### 10. `route`
|
|
- `nx9-wg route list`: List configured routing rules.
|
|
- `nx9-wg route show <ID>`: Show route details.
|
|
- `nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]`: Add kernel routing rule.
|
|
- `nx9-wg route update <ID> [--destination C] [--gateway IP] [--interface-name IFACE] [--metric M] [--enabled BOOL]`: Update route.
|
|
- `nx9-wg route delete <ID>`: Delete routing rule.
|
|
- `nx9-wg route status`: Show current kernel routing status.
|
|
- `nx9-wg route sync`: Synchronize routes with kernel routing table.
|
|
|
|
### 11. `firewall`
|
|
- `nx9-wg firewall list [--peer PEER]`: List configured nftables rules.
|
|
- `nx9-wg firewall show <ID>`: Show firewall rule details.
|
|
- `nx9-wg firewall add --name <NAME> [--direction in|out|forward] [--source CIDR] [--destination CIDR] [--peer PEER] [--protocol tcp|udp|tcp_udp|icmp|any] [--port P] [--port-range R] [--action accept|drop|reject] [--priority P]`: Add rule.
|
|
- `nx9-wg firewall update <ID> [--name N] [--action A] [--priority P] [--enabled BOOL]`: Update rule.
|
|
- `nx9-wg firewall enable <ID>` / `disable <ID>`: Toggle rule.
|
|
- `nx9-wg firewall delete <ID>`: Delete rule.
|
|
- `nx9-wg firewall sync`: Synchronize nftables ruleset in `table inet nx9_wg`.
|
|
- `nx9-wg firewall status`: Show active nftables status.
|
|
|
|
### 12. `nat`
|
|
- `nx9-wg nat status`: Query NAT masquerade state.
|
|
- `nx9-wg nat enable` / `disable`: Toggle outbound NAT masquerading.
|
|
- `nx9-wg nat list`: List subnets configured for NAT masquerade.
|
|
- `nx9-wg nat sync`: Synchronize NAT rules with kernel.
|
|
|
|
### 13. `forwarding`
|
|
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
|
|
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP packet forwarding.
|
|
- `nx9-wg forwarding sync`: Synchronize IP forwarding setting with kernel.
|
|
|
|
### 14. `reconcile`
|
|
- `nx9-wg reconcile status`: Inspect reconciliation status and statistics.
|
|
- `nx9-wg reconcile plan [--interface IFACE]`: Calculate read-only drift plan between SQLite and Linux kernel.
|
|
- `nx9-wg reconcile apply [--interface IFACE]`: Apply reconciliation mutations to live kernel state.
|
|
- `nx9-wg reconcile verify`: Verify zero drift between SQLite and kernel.
|
|
|
|
### 15. `backup`
|
|
- `nx9-wg backup list`: List backup snapshots.
|
|
- `nx9-wg backup create [--description DESC]`: Generate atomic SQLite online backup (`VACUUM INTO`).
|
|
- `nx9-wg backup show <ID>`: Show backup details and manifest.
|
|
- `nx9-wg backup verify <PATH>`: Verify SQLite 3 header and SHA-256 checksum.
|
|
- `nx9-wg backup restore <PATH> [-y, --yes]`: Restore database with automatic safety snapshot.
|
|
- `nx9-wg backup delete <ID>`: Delete backup record and snapshot archive.
|
|
|
|
### 16. `audit`
|
|
- `nx9-wg audit list [--event-type TYPE] [--actor ACTOR] [--resource-type TYPE] [--limit N] [--offset N]`: List append-only audit trail records.
|
|
- `nx9-wg audit show <ID>`: Show full details for an audit event.
|
|
|
|
### 17. `live`
|
|
- `nx9-wg live interface list`: List live WireGuard interface names in kernel.
|
|
- `nx9-wg live interface show <NAME>`: Show live interface statistics.
|
|
- `nx9-wg live peer <IFACE>`: Query live peers, transfer bytes, and handshakes.
|
|
- `nx9-wg live routes`: Query live Linux kernel routing table.
|
|
- `nx9-wg live firewall`: Query live active `table inet nx9_wg` nftables ruleset.
|
|
- `nx9-wg live forwarding`: Query live IP packet forwarding status.
|
|
- `nx9-wg live nat`: Query live NAT masquerade status.
|
|
|
|
### 18. `diagnostics`
|
|
- `nx9-wg diagnostics all`: Inspect health across all subsystems.
|
|
- `nx9-wg diagnostics <SUBSYSTEM> [--peer PEER_UUID]`: Inspect specific subsystem (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`).
|