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

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