# Operations

This guide assumes a dedicated `wgcloak` service account and configuration
under `/etc/wgcloak/`. Adjust paths to match the reviewed deployment.

## 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
```

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
```

`network.max_datagram_size` defaults to 1200 bytes and may be raised for a
known jumbo/custom path up to the project-wide 16,384-byte safety ceiling.
The effective session maximum can be lower for a particular QUIC, HTTP/3, or
direct path after transport framing and negotiation; TLS/TCP still enforces
the configured cap at both endpoints.

## Start, stop, and reconnect

Foreground operation is useful during initial setup:

```bash
wgcloak client --config /etc/wgcloak/client.toml
wgcloak server --config /etc/wgcloak/server.toml
```

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.

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.

## Local control socket

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`):

```bash
wgcloak status
wgcloak stats
wgcloak reconnect
wgcloak reload
wgcloak shutdown
```

`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`, and role configuration under
`/etc/wgcloak/`. Each unit creates a private runtime directory and sets
`XDG_RUNTIME_DIR` there.

The resulting control paths are distinct and deterministic:

- client: `/run/wgcloak-client/wgcloak.sock`
- server: `/run/wgcloak-server/wgcloak.sock`

Use the explicit path when administering a unit from a shell outside its
service environment:

```bash
wgcloak status --socket /run/wgcloak-client/wgcloak.sock
wgcloak stats --socket /run/wgcloak-client/wgcloak.sock
wgcloak reconnect --socket /run/wgcloak-client/wgcloak.sock
wgcloak status --socket /run/wgcloak-server/wgcloak.sock
wgcloak stats --socket /run/wgcloak-server/wgcloak.sock
wgcloak shutdown --socket /run/wgcloak-server/wgcloak.sock
```

```bash
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
journalctl -u wgcloak-client.service -f
```

For a low port such as 443, uncomment `AmbientCapabilities=CAP_NET_BIND_SERVICE`
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 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.