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:
examples/client.minimal.tomlexamples/client.advanced.tomlexamples/server.minimal.tomlexamples/server.advanced.toml
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.