151 lines
8.8 KiB
Markdown
151 lines
8.8 KiB
Markdown
# 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`](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`](../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.
|