Finalize nx9-wg production release
This commit is contained in:
thakares committed
1 parent
4dfe42fe68
commit
d704c1e131
30 files changed
+2502
-370
No files matched your search
+17
-13
@@ -6,10 +6,10 @@ The `nx9-wg` API daemon serves JSON REST endpoints and a real-time WebSocket eve
|
||||
|
||||
## 1. Authentication & Session Model
|
||||
|
||||
Authentication is supported via two mechanisms:
|
||||
Authentication is supported via two secure mechanisms:
|
||||
|
||||
### A. HTTP Session Cookie (`nx9_session`)
|
||||
Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header and automatically attached by web browsers.
|
||||
Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header with `HttpOnly; SameSite=Strict; Path=/` and automatically attached by web browsers for both REST API requests and WebSocket upgrade handshakes.
|
||||
|
||||
### B. Bearer API Token
|
||||
Passed in the `Authorization` header:
|
||||
@@ -36,8 +36,8 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `401 Unauthorized`: Missing, invalid, or expired session/token.
|
||||
- `404 Not Found`: Resource ID does not exist in SQLite.
|
||||
- `409 Conflict`: Unique constraint violation (e.g. duplicate interface name or IP).
|
||||
- `422 Unprocessable Entity`: Semantic constraint failure.
|
||||
- `429 Too Many Requests`: Brute-force rate limiting triggered.
|
||||
- `422 Unprocessable Entity`: Semantic constraint failure (e.g. invalid server host with embedded port, invalid port bounds).
|
||||
- `429 Too Many Requests`: Brute-force rate limiting triggered (5 failed logins in 15 minutes).
|
||||
- `500 Internal Server Error`: Native Linux execution plane or storage failure.
|
||||
|
||||
---
|
||||
@@ -58,20 +58,20 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `GET /api/v1/system/version`: Public version and build information.
|
||||
- `GET /api/v1/system`: System operational overview and interface/peer counts.
|
||||
- `GET /api/v1/system/settings`: List all key-value settings.
|
||||
- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "...", "value": "...", "description": "..." }`.
|
||||
- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "wireguard.server_host", "value": "vpn.thakares.com", "is_secret": false, "description": "..." }`. Supports `wireguard.server_host`, `wireguard.server_port`, and `wireguard.server_endpoint_enabled`.
|
||||
|
||||
### WireGuard Interfaces
|
||||
- `GET /api/v1/interfaces`: List all WireGuard interfaces.
|
||||
- `POST /api/v1/interfaces`: Create interface `{ "name": "wg0", "address_v4": "10.100.0.1/24", "listen_port": 51820, "mtu": 1420 }`.
|
||||
- `GET /api/v1/interfaces/{id}`: Get interface details.
|
||||
- `PUT /api/v1/interfaces/{id}`: Update interface configuration.
|
||||
- `PUT /api/v1/interfaces/{id}`: Update interface configuration (preserves private/public cryptographic identity).
|
||||
- `DELETE /api/v1/interfaces/{id}`: Delete interface (cascades to peers).
|
||||
- `POST /api/v1/interfaces/{id}/enable`: Set interface `IFF_UP`.
|
||||
- `POST /api/v1/interfaces/{id}/disable`: Set interface `IFF_DOWN`.
|
||||
- `GET /api/v1/interfaces/{id}/status`: Query live kernel netlink telemetry.
|
||||
|
||||
### Peers & Client Configs
|
||||
- `GET /api/v1/peers`: List all peers across all interfaces.
|
||||
- `GET /api/v1/peers`: List all peers across all interfaces (enriched with live kernel telemetry).
|
||||
- `GET /api/v1/interfaces/{id}/peers`: List peers for specific interface.
|
||||
- `POST /api/v1/interfaces/{id}/peers`: Enroll peer `{ "name": "alice", "profile": "full_tunnel", "mtu": 1280, ... }`.
|
||||
- `GET /api/v1/peers/{id}`: Get peer details.
|
||||
@@ -79,8 +79,12 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `DELETE /api/v1/peers/{id}`: Delete peer.
|
||||
- `POST /api/v1/peers/{id}/enable`: Enable peer.
|
||||
- `POST /api/v1/peers/{id}/disable`: Disable peer.
|
||||
- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...`).
|
||||
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg`).
|
||||
- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...&endpoint=...`). Uses persistent `wireguard.server_*` settings if `endpoint` query parameter is omitted.
|
||||
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg&endpoint=...`). Returns `{ "svg": "<svg...", "data_url": "data:image/png;base64,..." }`.
|
||||
|
||||
### Client Profiles & MTU Resolution
|
||||
- `GET /api/v1/client-profiles`: List client transport profiles.
|
||||
- `GET /api/v1/client-profiles/resolve`: Resolve optimal MTU and keepalive parameters for device and connection environment.
|
||||
|
||||
### Networks & Subnets
|
||||
- `GET /api/v1/networks`: List subnet networks.
|
||||
@@ -95,8 +99,8 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `DELETE /api/v1/routes/{id}`: Delete route.
|
||||
|
||||
### Firewall & NAT
|
||||
- `GET /api/v1/firewall/rules`: List nftables rules.
|
||||
- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": "22", "action": "accept" }`.
|
||||
- `GET /api/v1/firewall/rules`: List nftables rules in `table inet nx9_wg`.
|
||||
- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": 22, "action": "accept" }`.
|
||||
- `DELETE /api/v1/firewall/rules/{id}`: Delete rule.
|
||||
- `POST /api/v1/firewall/rules/{id}/enable`: Enable rule.
|
||||
- `POST /api/v1/firewall/rules/{id}/disable`: Disable rule.
|
||||
@@ -106,7 +110,7 @@ All non-2xx responses return a structured JSON error body:
|
||||
- `POST /api/v1/reconcile/apply`: Execute native mutations and verify convergence.
|
||||
|
||||
### Diagnostics
|
||||
- `GET /api/v1/diagnostics/all`: Run automated checks across all 9 subsystems.
|
||||
- `GET /api/v1/diagnostics/all`: Run automated checks across all subsystems.
|
||||
- `GET /api/v1/diagnostics/{subsystem}`: Run checks for a single subsystem.
|
||||
|
||||
### Backups
|
||||
@@ -123,7 +127,7 @@ All non-2xx responses return a structured JSON error body:
|
||||
|
||||
## 4. Real-Time WebSocket Protocol (`/api/v1/ws`)
|
||||
|
||||
Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events:
|
||||
Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events. Authentication is handled automatically using the browser's `nx9_session` cookie or `Authorization: Bearer <token>` header:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
+94
-49
@@ -1,6 +1,6 @@
|
||||
# Native CLI Command Reference (`nx9-wg`)
|
||||
|
||||
The `nx9-wg` binary provides 100% native CLI coverage across all 17 application subcommands without spawning external subprocesses.
|
||||
The `nx9-wg` binary provides native CLI coverage across all 18 application command groups without spawning external subprocesses.
|
||||
|
||||
---
|
||||
|
||||
@@ -36,9 +36,9 @@ nx9-wg serve --bind 0.0.0.0:8080
|
||||
```
|
||||
|
||||
### 3. `init`
|
||||
Initializes the single administrator account across 7 bootstrap sources.
|
||||
Initializes the single administrator account across bootstrap sources.
|
||||
```bash
|
||||
# Generated secure password:
|
||||
# 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:
|
||||
@@ -54,79 +54,124 @@ nx9-wg init --password-file /run/secrets/admin_pw
|
||||
- `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.
|
||||
- `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 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.
|
||||
- `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> [--port PORT] [--mtu MTU]`: Create interface.
|
||||
- `nx9-wg interface show <NAME_OR_ID>`: Show interface configuration.
|
||||
- `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.
|
||||
- `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]`: List enrolled peers.
|
||||
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--profile PROFILE] [--mtu MTU]`: Enroll 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> [--device DEV] [--connection CONN]`: Output `.conf` client file.
|
||||
- `nx9-wg peer qr <PEER_ID>`: Render ASCII QR code in terminal for mobile scanning.
|
||||
- `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. `network`
|
||||
### 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 create <NAME> --cidr <CIDR>`: Create network.
|
||||
- `nx9-wg network delete <NAME_OR_ID>`: Delete network.
|
||||
- `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.
|
||||
|
||||
### 9. `route`
|
||||
- `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. `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.
|
||||
|
||||
### 10. `firewall`
|
||||
- `nx9-wg firewall list`: List nftables firewall rules.
|
||||
- `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. `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.
|
||||
|
||||
### 11. `nat`
|
||||
### 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.
|
||||
|
||||
### 12. `forwarding`
|
||||
### 13. `forwarding`
|
||||
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
|
||||
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP forwarding.
|
||||
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP packet forwarding.
|
||||
- `nx9-wg forwarding sync`: Synchronize IP forwarding setting with kernel.
|
||||
|
||||
### 13. `reconcile`
|
||||
- `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. `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.
|
||||
|
||||
### 14. `backup`
|
||||
### 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_OR_ID>`: Restore database with automatic safety snapshot.
|
||||
- `nx9-wg backup restore <PATH> [-y, --yes]`: Restore database with automatic safety snapshot.
|
||||
- `nx9-wg backup delete <ID>`: Delete backup record and snapshot archive.
|
||||
|
||||
### 15. `audit`
|
||||
- `nx9-wg audit list [--limit N] [--event-type TYPE]`: List append-only audit trail records.
|
||||
### 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.
|
||||
|
||||
### 16. `live`
|
||||
- `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. `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.
|
||||
|
||||
### 17. `diagnostics`
|
||||
- `nx9-wg diagnostics all`: Inspect health across all 9 subsystems.
|
||||
- `nx9-wg diagnostics <SUBSYSTEM>`: Inspect specific subsystem (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`).
|
||||
### 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`).
|
||||
+43
-1
@@ -59,8 +59,50 @@ Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` n
|
||||
|
||||
---
|
||||
|
||||
## Persistent WireGuard Server Endpoint Configuration
|
||||
|
||||
When generating client `.conf` configurations and QR codes, `nx9-wg` embeds the public or reachable server endpoint address so client devices can reach the server. This is managed through persistent settings in SQLite.
|
||||
|
||||
### Settings Keys
|
||||
|
||||
| Key | Type | Description | Default | Example |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| `wireguard.server_host` | String | Public/reachable server hostname or IP address (DNS hostname, IPv4, or IPv6). Must not contain a port. | Empty | `vpn.thakares.com` or `203.0.113.10` or `2001:db8::10` |
|
||||
| `wireguard.server_port` | u16 | Public reachable UDP port where clients connect. | `51820` | `51820` |
|
||||
| `wireguard.server_endpoint_enabled` | Boolean | Whether the persistent server endpoint is used as the default for client exports. | `true` | `true` |
|
||||
| `server_endpoint` | String | Legacy formatted endpoint fallback (`host:port` or `[ipv6]:port`). | Empty | `vpn.thakares.com:51820` |
|
||||
| `public_endpoint` | String | Legacy secondary fallback. | Empty | `vpn.thakares.com:51820` |
|
||||
|
||||
### Important Architectural Invariants
|
||||
|
||||
- **Public Endpoint vs. Interface Listen Port**: The public server endpoint (`wireguard.server_host` and `wireguard.server_port`) is the external address that clients use to connect across the Internet or WAN. It is conceptually separate from the WireGuard interface's local kernel UDP `listen_port` (which may sit behind NAT, port-forwarding, or a reverse proxy).
|
||||
- **Authoritative Resolution Precedence**:
|
||||
1. **Explicit per-request / per-export override**: Passed via `--endpoint <ENDPOINT>` in the CLI or `?endpoint=<ENDPOINT>` in the REST API.
|
||||
2. **Persistent structured settings**: `wireguard.server_host` + `wireguard.server_port` when `wireguard.server_endpoint_enabled` is `true` and host is non-empty.
|
||||
3. **Legacy `server_endpoint` setting**: If present and non-empty.
|
||||
4. **Legacy `public_endpoint` setting**: If present and non-empty.
|
||||
5. **Actionable configuration error**: If no endpoint is configured, generation fails with an actionable error directing the administrator to configure the server endpoint in Settings or provide an explicit override.
|
||||
|
||||
### Configuring via CLI
|
||||
|
||||
```bash
|
||||
# Configure the persistent 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
|
||||
|
||||
# Export a client configuration using the persistent default:
|
||||
nx9-wg peer config <PEER_UUID>
|
||||
# Generated output contains: Endpoint = vpn.thakares.com:51820
|
||||
|
||||
# Export with a temporary one-off override (does not modify persistent settings):
|
||||
nx9-wg peer config <PEER_UUID> --endpoint custom.backup-vpn.com:51820
|
||||
# Generated output contains: Endpoint = custom.backup-vpn.com:51820
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Secret Handling & Docker Secrets
|
||||
|
||||
- **Never Persisted in Cleartext**: `NX9_WG_ADMIN_PASSWORD` is hashed into SQLite using Argon2id during initialization and is never written to disk, config files, or logs.
|
||||
- **Docker Secrets**: In container environments, mount Docker secrets to `/run/secrets/nx9_wg_admin_password` and specify `NX9_WG_ADMIN_PASSWORD_FILE=/run/secrets/nx9_wg_admin_password`.
|
||||
|
||||
+12
-7
@@ -10,7 +10,7 @@
|
||||
- **Embedded Static Assets**: HTML, CSS, and JavaScript are bundled into the binary at compile time via `include_str!()` and served from memory.
|
||||
- **Unified Design Tokens**: Custom CSS variable design system (`nx9-wg-ui/src/css.rs`) providing Dark and Light themes with persistent `localStorage` preference.
|
||||
- **Responsive Layout**: Mobile-first responsive layout with side-drawer navigation and `@media (max-width: 768px)` breakpoints.
|
||||
- **Live WebSocket Event Stream**: Connects to `ws://<host>/api/v1/ws` for reactive dashboard, peer handshake, and reconciliation updates without polling.
|
||||
- **Live WebSocket Event Stream**: Connects to `ws://<host>/api/v1/ws` authenticated via the browser's `nx9_session` HttpOnly cookie for reactive dashboard, peer handshake, and reconciliation updates without polling.
|
||||
- **Presentation-Only Separation**: The UI contains presentation and client routing logic only; all business validation, allocation, and state authority reside in the backend REST API and SQLite.
|
||||
|
||||
---
|
||||
@@ -20,7 +20,7 @@
|
||||
| Hash Route | Navigation Label | Purpose & Operational Features |
|
||||
| :--- | :--- | :--- |
|
||||
| `#dashboard` | **Dashboard** | System status, uptime, interface/peer counts, diagnostics health, and reconciliation status cards. |
|
||||
| `#interfaces` | **Interfaces** | List WireGuard interfaces, "+ Create Interface" modal, enable/disable toggle, and delete interface. |
|
||||
| `#interfaces` | **Interfaces** | List WireGuard interfaces, "+ Create Interface" modal, interface "Edit" action (with cryptographic key preservation), enable/disable toggle, and delete interface. |
|
||||
| `#peers` | **Peers** | Enrolled peer table with real-time handshakes, status filter, "+ Add Peer" modal with MTU profile resolution, client configuration export, and live SVG QR rendering. |
|
||||
| `#networks` | **Networks** | Subnet network ranges, CIDR masks, "+ Create Network" modal, and deletion. |
|
||||
| `#routes` | **Routes** | Routing table entries, gateway assignments, "+ Create Route" modal, and deletion. |
|
||||
@@ -28,9 +28,9 @@
|
||||
| `#nat` | **NAT & Masquerade** | Outbound NAT masquerade status card, active masqueraded subnet list, and instant toggle. |
|
||||
| `#forwarding` | **IP Forwarding** | Kernel sysctl `/proc/sys/net/ipv4/ip_forward` packet forwarding status and toggle. |
|
||||
| `#reconciliation` | **Reconciliation** | Real-time kernel drift overview, planned execution actions table, and interactive "Run Reconcile (Apply)" button. |
|
||||
| `#diagnostics` | **Diagnostics** | Automated health inspection across all 9 subsystems (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`) with remediation hints. |
|
||||
| `#diagnostics` | **Diagnostics** | Automated health inspection across all subsystems (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`) with remediation hints. |
|
||||
| `#live-state` | **Live State** | Live Linux Netlink kernel telemetry, active WireGuard interfaces, and live routing table entries. |
|
||||
| `#settings` | **Settings** | Appliance key-value parameters table and danger zone reset controls. |
|
||||
| `#settings` | **Settings** | Dedicated **WireGuard Server Endpoint** configuration card (Host, Port, Enabled toggle, live preview, save), appliance parameters table, and danger zone reset controls. |
|
||||
| `#backups` | **Backups** | Atomic SQLite database backup snapshots list, "+ Create Backup Snapshot" button, and direct `.db` download. |
|
||||
| `#audit` | **Audit Log** | Append-only security and administrative audit trail with actor, IP, timestamp, and metadata. |
|
||||
| `#administrator` | **Administrator** | Admin account verification, "Change Password" modal, and "+ Generate API Token" modal with one-time raw secret copy. |
|
||||
@@ -43,9 +43,14 @@
|
||||
When enrolling a new peer (`#peers`), the modal automatically queries `/api/v1/client-profiles/resolve` based on selected Device (Android, iOS, Linux, Windows, macOS) and Connection (Mobile Cellular 4G/5G, Wi-Fi, Wired Ethernet) to determine optimal MTU (1280 vs 1360 vs 1420) and persistent keepalive (25s).
|
||||
|
||||
### B. Client Export & QR Code Modal
|
||||
Displays both:
|
||||
1. **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
|
||||
2. **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
|
||||
When opening the export modal for a peer, the UI automatically:
|
||||
1. Pre-populates the **Server Endpoint** field using the persistent settings (`wireguard.server_host` and `wireguard.server_port`) configured under Settings.
|
||||
2. Displays a `"Default from Server Settings"` badge indicating persistent configuration source.
|
||||
3. Automatically triggers client `.conf` and QR code generation on modal open without requiring manual typing.
|
||||
4. Allows the administrator to enter a temporary one-off endpoint override directly in the modal for specialized network requirements without mutating global server settings.
|
||||
5. Displays both:
|
||||
- **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
|
||||
- **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
|
||||
|
||||
### C. One-Time API Token Delivery Modal
|
||||
Generates a new API token, calculates its SHA-256 digest for SQLite storage, and presents the raw token string once in an interactive modal with a copy button.
|
||||
|
||||
Reference in new issue
Block a user