131 lines
5.3 KiB
Markdown
131 lines
5.3 KiB
Markdown
# 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.
|