5.3 KiB
Operations
This guide assumes a dedicated wgcloak service account and configuration
under /etc/wgcloak/. Adjust paths to match the reviewed deployment.
Build and install
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:
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:
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):
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:
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
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.