wireguard-admin/docs/SPEC.md

WireGuard Admin — Version 1 Specification

Status: approved by the user on 2026-10-18. This document records the discussion outcome; no new requirements have been added.

Purpose

A native Rust application with a terminal user interface (TUI), run as root directly on a Linux VPN server. It manages one existing WireGuard interface and supports existing clients. Initial VPN server setup is outside the scope of version 1.

Rust build dependencies are allowed. System utilities may be invoked only when necessary. The server uses systemd; the service name and operation timeout are configurable. The executable resides in a dedicated root-only directory and is not installed in PATH.

Data locations

• Application settings reside alongside the executable. Their location is resolved relative to the executable, not the current working directory.
• The data location is configurable; its default is a Backup directory alongside the executable.
• Within that directory, data contains current internal data and the encrypted vault, while archives contains backups.
• The directory containing existing client files is specified in the settings.
• VPN server paths are invariant for installation and restoration. Migration between servers with different paths is not supported.

Data sources

The server configuration is the source of truth for clients and their descriptive metadata. Clients are matched by public key. A client is an individual device with its own key pair. An alias is a convenient label; duplicate aliases are allowed.

The application may modify only client [Peer] sections and their associated managed comment blocks. The rest of the server configuration, including interface parameters, network setup commands, unknown parameters, and administrator comments, is preserved. These settings are changed manually by the administrator.

A versioned comment block immediately preceding [Peer] contains the alias and creation date in UTC. An unknown creation date for an existing client is not fabricated. The public key resides in [Peer] and is not duplicated in metadata. Passwords and client private keys are never included in comments.

Separate application metadata contains internal state only; an independent copy of aliases is not a source of truth.

New client parameters

The application settings file contains the server endpoint, IPv4 and IPv6 allocation ranges, and DNS addresses. A new client receives one address from each range. The first available address is selected by default, but the administrator may select an address manually. A deleted client's address is not reused until a successful restart.

All client traffic is routed through the VPN: 0.0.0.0/0 and ::/0. Existing IPv4-only clients are preserved without adding IPv6. Additional user settings for MTU, PersistentKeepalive, and preshared key generation are not introduced in version 1; existing connection parameters are preserved.

Operations and states

Supported operations are creation, deletion, viewing, and alias changes. IP changes and key replacement are not separate operations in version 1; deletion and creation are used instead.

There are three states:

1. Draft: prepared changes that have not been saved.
2. Saved state: files after Commit; these may differ from the running VPN.
3. Applied state: the running interface matches the saved clients.

Commit saves changes to files and the vault. Commit does not invoke reload, syncconf, or restart and does not change the running VPN. The TUI separately shows draft changes and saved but unapplied changes. A client deleted from the files may retain access until changes are applied.

Restart is a separate action using the configured systemd service. If a draft exists, the choices are “Discard draft and restart” and “Cancel.” Cancel preserves the draft in the current session. After systemd completes successfully, the application verifies that the expected interface exists and its clients match the saved configuration. Only after verification is the state marked applied and deleted clients' addresses released.

On normal exit, the application warns that the draft will be discarded. Drafts do not persist across launches. Restoration also warns that the draft will be discarded.

A single administrator is assumed. Optimistic locking, concurrent edit detection, and automatic merging are not required. Automatic rollback after a failed restart is not required: the error is displayed, and the administrator selects a backup to restore.

Encrypted vault

An asymmetric scheme is used: the public key allows new client secrets to be encrypted without a password. The vault's secret key is protected by a password set during initial creation. The password is needed only to decrypt a client's private key when reissuing connection details and is requested separately for each client.

Losing the password makes saved client private keys impossible to decrypt. Restoring a backup does not recover the password. A new key pair can be issued to a client through deletion and creation.

The password does not protect the entire archive, the server private key, the server-side copy of an existing preshared key, or retained original files. Access to secret data is restricted to root.

When a client is deleted, Commit removes its record and secrets from the current vault. Previously created backups are not rewritten and may still contain those secrets.

Connection delivery

Initial delivery is allowed after a successful Commit without a password during the client's creation session. Delivery after exiting the application requires a password.

Delivery must save a standard WireGuard connection file to the selected directory, without password encryption, accessible only to root. A terminal QR code is an additional option. An existing file is not overwritten without confirmation. Delivered files are not automatically deleted.

If saving the file fails, the administrator may resolve the issue, change the directory, and retry initial delivery without a password during the same creation session. Once initial delivery is complete, subsequent delivery requires a password. Until the configuration is applied, a warning states that access has not yet been activated.

Importing existing clients

During initial vault creation, existing client files from the configured directory are checked and encrypted at the earliest opportunity. Original files are neither modified nor deleted; the administrator handles any subsequent cleanup.

Validation results and anomalies are shown explicitly:

• a server entry exists without a client file;
• only a client file exists;
• both parts exist;
• the public key matches, but parameters such as the IP address differ;
• a file is invalid and cannot be imported.

Invalid files are skipped with an explanation. Anomalies are not automatically repaired. Explicit import of an existing file and deletion of a server entry are available.

The private key is checked against the public key before import. If parameters differ, the server configuration takes precedence; the secret may be imported after key verification, but reissuing is blocked until the administrator explicitly resolves the discrepancy.

Adding standard metadata blocks to existing clients goes through draft and Commit. Administrator comments are preserved. Until a standard alias exists, the client filename or shortened public key is displayed temporarily.

Backups and restoration

A backup includes application settings, the server configuration, internal metadata, and the complete encrypted vault. Drafts, original unencrypted client files, and previous archives are excluded. The server configuration may contain secrets, so archive access is restricted to root.

Backups are created manually and automatically before every Commit, restoration, and restart. If a mandatory backup cannot be created, further steps of the current operation stop. Automatic archive cleanup is not provided.

The TUI displays the backup list, creation date and reason, and identifies the last state whose restart was successfully verified. A pre-Commit backup contains the previous saved state, which may differ from the running VPN. A pre-restart backup is also not necessarily a working state.

Restoration requires a preview and confirmation. A precautionary backup is created first. The saved state is fully replaced with the selected archive contents; clients are not merged. The encrypted vault is restored as a whole without a password. Settings are also restored. The running VPN remains unchanged until a separate restart.

Client screen and statistics

The list displays the alias, shortened public key, IPv4/IPv6, change state, and anomalies. The last handshake and the current interface's received/transmitted byte counters are refreshed periodically.

The time of the last handshake is shown instead of an ambiguous “online” label. Counters are current WireGuard values, without daily or monthly history. Service logs and application action history are outside the scope of version 1.

Acceptance criteria

• Commit does not change the running interface or start the service.
• Client changes do not alter any server parameter outside managed records and blocks.
• Existing clients, keys, and original files are preserved during initial import.
• Creation, deletion, aliases, and restoration correctly follow draft, saved, and applied states.
• A new client receives valid IPv4/IPv6 addresses and a full-tunnel configuration file; the file and QR code represent the same configuration.
• A new secret is encrypted without a password; reissuing requires the correct password for the selected client.
• Failed file delivery can be retried during the current creation session.
• Failure of a mandatory backup prevents the protected operation from proceeding.
• Restoration without a password returns the archive's saved state without restarting the VPN.
• A deleted address is not reassigned until a successful restart has been verified.
• Restart and real server access are tested only in a dedicated environment.