checkpoint: integrate authenticated transports

docs/OPERATIONS.md

@@ -1,79 +1,91 @@
 # 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.
+This guide assumes a dedicated `wgcloak` service account and configuration
+under `/etc/wgcloak/`. Adjust paths to match the reviewed deployment.
 
-## First installation
+## Build and install
 
 ```bash
+cargo test --all-targets
+cargo build --release
 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:
+Store each client secret in a separate file readable only by the service
+account (normally owner `wgcloak`, mode `0600`). Protect the parent directory
+from untrusted writes. The server needs its TLS certificate and private key
+readable by its service account when QUIC, HTTP/3, or TLS/TCP is enabled.
+
+Validate configuration before starting a daemon:
 
 ```bash
 sudo -u wgcloak wgcloak check-config --config /etc/wgcloak/client.toml
+sudo -u wgcloak wgcloak check-config --config /etc/wgcloak/server.toml
 ```
 
-The command is a target v1 CLI and is delivered in the operational-polish
-milestone; confirm with `wgcloak --help`.
+## Start, stop, and reconnect
 
-## Starting and stopping
-
-Foreground operation is useful for first-run diagnostics:
+Foreground operation is useful during initial setup:
 
 ```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.
+On Linux, SIGINT, SIGTERM, or the control `shutdown` command initiates bounded
+shutdown. The server stops accepting sessions and gives listeners/sessions a
+bounded cleanup window before abort fallback. A client reconnects after
+transport failures using exponential backoff with jitter from 250 ms to 30 s;
+the sequence resets after a successful connection. Authentication rejection
+stops automatic probing rather than trying other transports.
 
-## Control socket (intended interface)
+Direct UDP keepalives are one-way and do not acknowledge peer liveness. A
+silent direct-UDP server restart may therefore not be detected immediately;
+use `wgcloak reconnect` on the client to force a fresh handshake. The tested
+restart path waits through normal reconnect backoff while the server is
+unavailable, then resumes when it returns.
 
-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.
+## Local control socket
 
-Target commands are:
+By default the socket is `$XDG_RUNTIME_DIR/wgcloak.sock` when that runtime
+directory is owned by the current user and has mode `0700`. Otherwise the
+daemon uses `/run/user/<uid>/wgcloak/wgcloak.sock` when that private user
+runtime directory exists, or `$HOME/.local/run/wgcloak/wgcloak.sock` as a
+per-user fallback. The socket's parent is created with mode `0700`; the socket
+itself is mode `0600`. An active socket path is never unlinked; a stale socket
+is removed only after its type and identity are checked. Use the same runtime
+directory for the CLI that is used by the daemon, or pass `--socket`
+explicitly (its parent directory must be owned by you and mode `0700`):
 
-```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
+```bash
+wgcloak status
+wgcloak stats
+wgcloak reconnect
+wgcloak reload
+wgcloak 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.
+`status` and `stats` report the running state. `reconnect` asks a client to
+leave its current session and reconnect; the server rejects this client-only
+command. `reload` currently returns “configuration reload is not supported”.
+Neither configuration hot reload nor certificate/key reload is implemented.
+`shutdown` requests graceful process shutdown. The control protocol is local
+newline-delimited JSON; do not send credentials or application payloads over
+it.
+
+For a non-default control path, set `XDG_RUNTIME_DIR` consistently for both
+daemon and CLI, or use the CLI's `--socket PATH` option.
 
 ## 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:
+Review and copy the units under `packaging/systemd/`. They assume binary
+`/usr/bin/wgcloak`, user/group `wgcloak`, and role configuration under
+`/etc/wgcloak/`. Each unit creates a private runtime directory and sets
+`XDG_RUNTIME_DIR` there.
 
 ```bash
-sudo install -Dm0644 packaging/systemd/wgcloak-client.service /etc/systemd/system/wgcloak-client.service
+sudo install -Dm0644 packaging/systemd/wgcloak-client.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now wgcloak-client.service
 systemctl status wgcloak-client.service
@@ -81,13 +93,15 @@ 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.
+and its matching bounding-set entry in the server unit only if required. Normal
+high-port operation needs no capability. Keep `CAP_NET_ADMIN` and
+`CAP_SYS_ADMIN` disabled.
 
 ## 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.
+Start with one enabled transport and one test client. Verify authentication,
+backend reachability, reply delivery, status/statistics, and clean shutdown.
+Add transports one at a time. Direct UDP, QUIC, and HTTP/3 are UDP listeners;
+QUIC and HTTP/3 cannot bind the same address/port in the current architecture.
+TLS/TCP may use the same numeric port because it uses TCP. Keep an independent
+management path available when changing public listener addresses.