94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# 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.
|