63 lines
3.1 KiB
Markdown
63 lines
3.1 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.
|
|
|