87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# 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.
|
|
|