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

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:

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:

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:

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:

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.

3.5 KiB Raw Blame History