50 lines
2.4 KiB
Markdown
50 lines
2.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.
|
|
|