109 lines
5.7 KiB
Markdown
109 lines
5.7 KiB
Markdown
# Configuration Reference
|
|
|
|
`nx9-wg` configuration is loaded hierarchically with strict precedence:
|
|
1. **CLI Arguments** (Highest precedence)
|
|
2. **Environment Variables**
|
|
3. **TOML Configuration File**
|
|
4. **Compiled Defaults** (Lowest precedence)
|
|
|
|
---
|
|
|
|
## TOML Configuration Format
|
|
|
|
```toml
|
|
# Directory for SQLite database and state files
|
|
data_dir = "/var/lib/nx9-wg"
|
|
|
|
# Bind address and port for HTTP / WebSocket daemon
|
|
bind_address = "127.0.0.1:8080"
|
|
|
|
# Log level filter (trace, debug, info, warn, error)
|
|
log_level = "info"
|
|
|
|
# Session inactivity expiration in hours
|
|
session_expiry_hours = 24
|
|
|
|
# Interval between kernel reconciliation cycles in seconds
|
|
reconciliation_interval_secs = 60
|
|
|
|
[backup]
|
|
# Directory where backups are written
|
|
dir = "/var/lib/nx9-wg/backups"
|
|
# Maximum backup files retained
|
|
max_count = 5
|
|
# Optional cron schedule
|
|
# schedule = "0 2 * * *"
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variables (`NX9_WG_*`)
|
|
|
|
Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` namespace prefix:
|
|
|
|
| Environment Variable | TOML Key | CLI Equivalent | Description | Default |
|
|
| :--- | :--- | :--- | :--- | :--- |
|
|
| `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 | `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` |
|
|
| `NX9_WG_BACKUP_DIR` | `backup.dir` | N/A | Destination directory for database backups | `<data_dir>/backups` |
|
|
| `NX9_WG_BACKUP_MAX_COUNT` | `backup.max_count` | N/A | Maximum number of automated backup snapshots to retain | `5` |
|
|
| `NX9_WG_BACKUP_SCHEDULE` | `backup.schedule` | N/A | Cron schedule for automated snapshots | None |
|
|
| `NX9_WG_ADMIN_USERNAME` | `bootstrap.admin_username` | `--username` | Initial bootstrap administrator username | `admin` |
|
|
| `NX9_WG_ADMIN_PASSWORD` | `bootstrap.admin_password` | `--password` | Initial bootstrap administrator password (Secret) | None |
|
|
| `NX9_WG_ADMIN_PASSWORD_FILE` | N/A | `--password-file` | Path to administrator bootstrap password file (Secret) | None |
|
|
|
|
---
|
|
|
|
## 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`.
|