# 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`.