thakaresandCopilot
2ac6c81dfe
- Prevent 'nx9-wg version' from creating data directories by avoiding database initialization. - Create parent directories when an explicit --database path is provided. - Redact printed generated administrator passwords; announce file path or redact instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
67 lines
3.0 KiB
Markdown
67 lines
3.0 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 | `0.0.0.0: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 |
|
|
|
|
---
|
|
|
|
## 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`.
|
|
|