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