wireguard-scripts/README.md

wireguard-scripts

M1 runtime foundation

The current entry point provides dependency-free help and version commands. The planned operational commands are recognized but remain unavailable until later milestones.

Runtime locations default to the project directory and can be redirected for an isolated run with absolute paths using these environment variables:

WG_MANAGER_CONFIG, WG_MANAGER_BACKUP_DIR, WG_MANAGER_LOG_DIR, WG_MANAGER_METADATA_DIR, WG_MANAGER_ARCHIVE_DIR, and WG_MANAGER_LOCK_FILE.

WG_MANAGER_GUM selects an executable gum explicitly; otherwise the bundled bin/gum and then PATH are checked in that order. Configuration is parsed as restricted KEY=VALUE data and is never executed as shell code. Blank lines and full-line # comments are ignored; spaces around the key, =, and value are trimmed. Values are either one unquoted token or a double-quoted value without escapes, and only documented keys are accepted.

For deterministic read-only tests, WG_MANAGER_NOW may override the current epoch when set to decimal seconds; invalid values are rejected.

M2 adds read-only status and list. They parse the configured WireGuard file and, when available, wg show <interface> dump; a stopped or unavailable runtime is reported as unavailable and disk-only peers remain visible. list uses stable tab-separated output with English machine fields state and origin (managed, legacy, or unmanaged) and never prints private or preshared keys.

The explicit peer comment marker is # wg-manager-client: NAME; it is only a display candidate. A peer is considered managed only when its exact public key and configured addresses match a valid metadata record with MANAGED=1.

M3 transaction foundation

The internal run_transaction OPERATION TARGET BUILDER [METADATA_FILE...] primitive acquires WG_MANAGER_LOCK_FILE, then reloads and validates the live configuration before calling its builder. It creates a restrictive, timestamped backup, validates a same-filesystem staged configuration with wg-quick strip, replaces the live file atomically, applies it with wg syncconf, and verifies the active peer set. Apply or verification failures restore both disk and runtime; a failed restoration is reported as a critical rollback error. No M3 mutation command is exposed yet.

M3 tests use only isolated overrides and deny-by-default command mocks; they do not inspect or modify host WireGuard state.

M4 client creation

add NAME creates a client transactionally. The optional forms are --mode full-tunnel|split-tunnel and --endpoint HOST; unknown or extra arguments are rejected. Names are restricted to ASCII letters, digits, ., _, and - (without a leading -). Root is required for production use; tests enable only an isolated WG_MANAGER_TEST_MODE under TEST_ROOT.

Private/public/PSK files, client configuration, and metadata use restrictive permissions and are removed if the server transaction or rollback fails. Generated key material is supplied to wg through stdin or stdout and is not placed in command arguments or diagnostic output.

M5 inspection and export

show NAME displays only non-secret peer details and a config path after identity, ownership, mode, and path validation. config NAME prints only that validated path. Full client content requires the explicit noninteractive config NAME --show form; it never reads separate .key or .psk files.

qr NAME feeds the validated config to qrencode -t ansiutf8 through stdin. If the optional qrencode dependency is unavailable, it prints the safe config path and returns status 69; QR failures return the operation status. Routine show/export/path/error output is secret-free.

The inspection commands do not require gum or qrencode for show and config. qrencode is the only optional QR dependency; when it is absent, qr NAME writes the validated configuration path to stdout and an actionable warning to stderr, then returns status 69. A nonzero qrencode result returns status 70 without printing configuration content in the diagnostic.

Common command statuses are 64 for usage errors, 65 for invalid or unsafe client identity/path data, 69 for a missing optional dependency, and 70 for an operational read/export/QR failure. config NAME --show is the only inspection form that writes the complete client configuration to stdout; ordinary show, config, and qr output remains secret-safe.

M6 удаление клиента

remove NAME [--yes] удаляет только подтверждённый managed-peer после повторной проверки точного публичного ключа, адресов и блока под lock. В интерактивном терминале без --yes показываются имя, адреса и только последние 8 символов публичного ключа; ответ, отличный от y, отменяет операцию без изменений. В неинтерактивном режиме --yes обязателен.

Изменение серверной конфигурации выполняется внутри транзакции: сначала конфигурация заменяется и проверяется в WireGuard, а затем финализатор архивирует связанные .conf, .meta, .key, .pub и .psk (если существуют) в уникальный каталог ARCHIVE_DIR с режимами 0700/0600. Ошибка архивирования после применения приводит к откату и оставляет исходные файлы доступными для восстановления; архивы не удаляются автоматически и служат восстановительным материалом. Журнал содержит operation, target, UTC timestamp, outcome и короткий суффикс публичного ключа; ключи и содержимое конфигураций в него не записываются.

remove возвращает 64 для ошибки аргументов, 65 для неподтверждённой или небезопасной identity/path, 69 для отсутствующей обязательной зависимости и 70 для ошибки операции или архивации. Ошибка аудита после успешной мутации явно сообщается и возвращает операционный статус; отмена остаётся успешной без изменения состояния.