wireguard-admin/docs/OPERATIONS.md

Operator setup, backup and recovery

This guide describes the supported single-interface installation and recovery boundaries. Use it only after qualifying the application for the target host; the current evidence and gaps are listed in RELEASE_READINESS.md. Do not trial the application on a production service as a substitute for the pending disposable systemd VM qualification.

Installation prerequisites and placement

The application manages one already-configured Linux WireGuard interface and its existing systemd service. The host must provide working WireGuard kernel support, systemd and its system D-Bus, plus the required service setup (such as wg-quick when the selected unit uses it). Version 1 does not provision a server, install a service, or manage multiple interfaces. Do not mount the development host's D-Bus into a test environment.

Build with the pinned Rust 1.97.1 toolchain and locked dependencies. Before installing an artifact, verify its target and dynamic library requirements against the chosen Linux distribution. The current x86-64 GNU release candidate is host-assessed only; it has not been started in a guest. Keep the executable and wireguard-admin.toml together in a dedicated root-owned directory that ordinary users cannot modify. Keep the executable outside PATH; no installer, service unit, or automatic privilege wrapper is supplied.

Copy ../config/wireguard-admin.example.toml to wireguard-admin.toml beside the executable and edit it for the existing interface, server configuration, client source directory, address pools, endpoint, DNS, systemd unit, and timeout. The server config path and interface name are installation invariants. Relative paths resolve beside the executable, not from the shell's working directory. By default working data is Backup/data and archives are Backup/archives, also beside the executable. Test the resolved paths before running management. Preserve the existing configuration and imported client files; import is read-only and anomaly reports require operator decisions.

Restrict the settings file, server configuration, vault, internal state, and backup tree to root. Existing server configuration and vault files must already be mode 0600 or stricter when opened. Keep private directories at 0700 and secret-bearing files at 0600; the application creates new owned outputs with these modes but does not silently chmod an unsafe existing server/vault file. Do not make the executable or settings writable by unprivileged users. The application requires root for management; --help and --version are unprivileged.

Initial vault, import and delivery

At initial setup, import scans the configured source directory without changing or deleting its original files. Review every reported match, mismatch, invalid file, or server-only/client-only anomaly. The server peer set remains authoritative; do not treat an imported file as permission to rewrite server settings.

Choose and protect the vault password during initial vault creation. The password protects the separate vault secret key; it does not encrypt the server configuration, original client files, or backup archives. Losing it prevents future reissue of stored client private keys. A backup restores the encrypted vault but cannot recover a lost password. Store credentials under your organization's separate secret-custody process; never place the password in settings, a command line, logs, or evidence.

For a new client, Commit first, then complete first file delivery in the same application session. The initial file is mandatory and can be retried at a different destination after a publication failure while that creation session is still active. Optional QR output represents the same configuration and is available only after file publication. The delivered file is plaintext WireGuard configuration, mode 0600; treat terminal QR output as a disclosure. If publication reports uncertain output or cleanup is required, follow the exact manual-cleanup instruction before retrying; do not assume an error means no plaintext file was created. Until the saved peer set has been explicitly applied and verified, treat the new client's access as inactive. After that session ends, each reissue requires the vault password for that client and reads installed saved state. The application does not use retained original plaintext files as a password-free fallback. Overwriting a selected output file requires confirmation.

Commit, backups, restore and restart

Keep the three states distinct:

1. Draft is the current session's proposed edit. Cancel preserves it in that session; exiting does not save it.
2. Saved is what Commit installed on disk. Commit creates a mandatory pre-Commit backup, then saves settings, server configuration, internal state and encrypted vault. Commit never reloads, syncs, or restarts WireGuard.
3. Applied is saved state verified against the running interface after an explicit restart. A historical verification marker after reopen is not a live observation.

Every Commit, restore and restart first creates a complete mandatory backup. If that backup fails, the protected operation stops before changing saved files or submitting a restart. Backups are uncompressed archives, not encrypted archives. They can contain the server's private configuration and encrypted vault records. Restrict them to root, include them in the site's protected backup custody, and remember that a backup beside the executable is lost with that disk. The application has no automatic retention or remote-copy feature. Deleting a client from the current vault does not erase old backups.

Restore is a previewed, confirmed full replacement of saved state. It restores the settings and opaque vault without a vault password, and it does not change the running interface. A restored archive's old verification marker is historical; runtime state becomes unknown. To apply the restored state, start a separate explicit restart and inspect its result. Never describe restore or Commit as a VPN rollback.

Before confirming restart, review the configured interface/service and the saved-versus-applied differences. The application creates a pre-restart backup, submits the configured systemd job, waits for its terminal result, compares the complete observed peer and route sets, then journals verification state. A successful systemd job alone does not establish that the expected peers are active. A pre-restart backup captures saved files and is not necessarily a known-good working VPN state. Deleted-client addresses remain reserved until verification and its saved-state write both succeed.

If restart reports failure, timeout, a runtime mismatch, or a persistence failure, read the stage and whether submission occurred or may still complete. A timeout does not cancel a submitted job. Do not immediately issue repeated restarts while a submitted job may still be running. No automatic restart, retry, VPN rollback, or reservation release occurs on these failure paths. Preserve the pre-restart backup and inspect the service and configured interface through the host's normal, independently controlled administration path. Do not infer success from log text alone. When the application remains usable, select a known-good archive through its preview/confirmation flow to restore saved files, then decide separately whether to restart and verify them.

Saved-file journal recovery

The persistence journal recovers interrupted file replacement; it is not runtime rollback. On reopen, an uncommitted prepared journal rolls saved files back to the recorded prior bytes, while a committed journal is cleaned up. If recovery or cleanup fails, the application returns RecoveryRequired and rejects mutations. Correct the underlying storage problem (for example, available space or directory access), preserve the journal, and retry opening the application so its recovery can run. Do not delete, hand-edit, or rename journal files to force startup.

If a journal remains invalid or recovery continues to fail, stop making changes. Preserve the complete data directory and operation backups for a careful, separately reviewed recovery. A known-good archive is the documented saved-state recovery source when the application can safely preview and restore it; it does not repair the runtime automatically. After saved state is recovered, inspect the live interface and use a separate explicit restart only when its target is understood. If the application cannot open to perform a safe previewed restore, do not improvise by copying partial archive members over installation paths.

Never remove old archives or original client files as an automatic response to an error. Keep secret-bearing files and working backups out of source control, support tickets, screenshots, logs, and evidence reports.