wgcloak

wgcloak relays opaque UDP datagrams between a local UDP application and a remote UDP backend. It does not inspect WireGuard or other application protocols and does not configure interfaces, routes, or firewalls.

The current runtime implements authenticated direct UDP, QUIC DATAGRAM, HTTP/3 CONNECT-UDP, and TLS/TCP framed fallback. Client mode = "auto" probes the configured transport order; authentication rejection stops fallback. See docs/IMPLEMENTATION_CHECKLIST.md for acceptance evidence and remaining v1 work.

Build and install

Install Rust and Cargo, then run from the repository root:

cargo test --all-targets
cargo build --release

cargo test --all-targets also runs the harness = false Criterion target as its smoke check; use cargo bench --bench protocol_transports for measured benchmark results.

For a local host installation:

sudo install -Dm755 target/release/wgcloak /usr/bin/wgcloak
sudo install -d -o root -g wgcloak -m0750 /etc/wgcloak/clients

The CLI supports:

wgcloak client --config /etc/wgcloak/client.toml
wgcloak server --config /etc/wgcloak/server.toml
wgcloak check-config --config /etc/wgcloak/client.toml
wgcloak generate-secret
wgcloak status
wgcloak stats
wgcloak reconnect
wgcloak reload
wgcloak shutdown

reload is retained as a CLI/control command but currently returns an explicit unsupported response. Configuration and certificate hot reload are not implemented. reconnect applies to the client; the server rejects it.

Configure and run

Copy a placeholder-only example and adjust it for the selected transport:

Store each secret in a separate file owned by the service account with mode 0600. Keep configuration and key files out of version control. TLS-capable transports require a certificate and private key on the server; clients use normal certificate-chain and hostname verification.

Run in the foreground first:

wgcloak check-config --config /etc/wgcloak/client.toml
wgcloak client --config /etc/wgcloak/client.toml

See docs/OPERATIONS.md for control commands, systemd deployment, shutdown behavior, and troubleshooting pointers.

Fuzzing setup and parser invariants are documented in docs/FUZZING.md.

systemd

The units in packaging/systemd/ assume a dedicated wgcloak user, /usr/bin/wgcloak, and configuration under /etc/wgcloak/. With the supplied units, use /run/wgcloak-client/wgcloak.sock for client commands and /run/wgcloak-server/wgcloak.sock for server commands, for example wgcloak stats --socket /run/wgcloak-client/wgcloak.sock. Review the paths and enabled listeners before installing. The server unit contains an optional, commented CAP_NET_BIND_SERVICE setting for ports below 1024. Normal operation needs neither CAP_NET_ADMIN nor CAP_SYS_ADMIN.

Security boundaries

TLS transports authenticate the server with normal X.509 verification and authenticate clients with the configured shared secret. Direct UDP provides message integrity and replay protection but no outer confidentiality. The control socket is local, stored in a private runtime directory, and mode 0600.

wgcloak does not configure WireGuard, create TUN/TAP devices, change routes or firewalls, fragment application datagrams, spoof browser fingerprints, cluster servers, or provide multiple simultaneous local client tunnels.

Documentation

docs/ARCHITECTURE.md: runtime roles and ownership.
docs/PROTOCOL.md: wire protocol and transport behavior.
docs/OPERATIONS.md: setup, control, and systemd.
docs/BENCHMARKS.md: deterministic benchmark commands, environment reporting, and datagram-size guidance.
docs/SECURITY.md: threat model and permissions.
docs/TROUBLESHOOTING.md: common failures.
docs/IMPLEMENTATION_CHECKLIST.md: milestones 1–6 and all 17 v1 criteria.

4.3 KiB Raw Blame History Unescape Escape