checkpoint: implement wgcloak v1 foundations

docs/OPERATIONS.md

@@ -0,0 +1,93 @@
+# Operations
+
+This guide assumes a dedicated `wgcloak` system user and `/etc/wgcloak/` for
+configuration. Adjust paths for a user service or a different packaging
+layout.
+
+## First installation
+
+```bash
+sudo install -Dm755 target/release/wgcloak /usr/bin/wgcloak
+sudo install -d -o wgcloak -g wgcloak -m0750 /etc/wgcloak/clients
+sudo install -o wgcloak -g wgcloak -m0600 client.secret /etc/wgcloak/client.secret
+```
+
+Create server client secrets separately and transfer them through a protected
+channel. Do not put real secret contents in the repository. Validate a config
+before starting a service when `check-config` is available in the current
+build:
+
+```bash
+sudo -u wgcloak wgcloak check-config --config /etc/wgcloak/client.toml
+```
+
+The command is a target v1 CLI and is delivered in the operational-polish
+milestone; confirm with `wgcloak --help`.
+
+## Starting and stopping
+
+Foreground operation is useful for first-run diagnostics:
+
+```bash
+wgcloak client --config /etc/wgcloak/client.toml
+wgcloak server --config /etc/wgcloak/server.toml
+```
+
+SIGTERM and SIGINT should stop accepting new sessions, stop local ingestion,
+close backend sockets, flush useful metrics, and exit within a bounded timeout.
+A transport failure should reconnect with jitter; it should not terminate the
+daemon. The systemd templates set restart-on-failure for this reason.
+
+## Control socket (intended interface)
+
+The daemon should expose a Unix-domain control socket at
+`$XDG_RUNTIME_DIR/wgcloak.sock` (for a system service, the template maps this
+to its private runtime directory). Filesystem permissions, not a TCP port,
+authorize access. The initial control protocol may be newline-delimited JSON.
+
+Target commands are:
+
+```text
+status     current role/state, selected transport, endpoint, MTU and uptime
+stats      counters for traffic, drops, auth failures, reconnects and sessions
+reconnect ask the client to leave the current transport and probe again
+reload     re-read supported configuration (not full hot reload in early builds)
+shutdown   request graceful process shutdown
+```
+
+The exact request/response field names are implementation-owned until the
+control protocol lands. A client should never send credentials or payloads
+through this socket. `status` and `stats` are read-only; `reconnect`, `reload`,
+and `shutdown` are state-changing and must remain local-admin operations.
+
+## systemd deployment
+
+Review and copy the units under `packaging/systemd/`. They assume:
+
+- binary `/usr/bin/wgcloak`;
+- user/group `wgcloak`;
+- configuration `/etc/wgcloak/client.toml` or `server.toml`;
+- runtime socket under a private `/run` directory;
+- secret and certificate paths readable by the service user.
+
+After review:
+
+```bash
+sudo install -Dm0644 packaging/systemd/wgcloak-client.service /etc/systemd/system/wgcloak-client.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now wgcloak-client.service
+systemctl status wgcloak-client.service
+journalctl -u wgcloak-client.service -f
+```
+
+For a low port such as 443, uncomment `AmbientCapabilities=CAP_NET_BIND_SERVICE`
+and its bounding-set companion in the server unit only after confirming the
+unit still starts. Direct UDP examples use an unprivileged port.
+
+## Safe rollout
+
+Start with direct UDP and one test client. Check local listener binding,
+server authentication, backend reachability, return-peer behavior, counters,
+and clean shutdown. Add one transport milestone at a time. Keep an independent
+path to the host while changing a public listener and retain the previous
+configuration until a restart test succeeds.