nx9-wg/docs/configuration.md

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

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