wgcloak/README.md

wgcloak

wgcloak is a Linux userspace relay for opaque UDP datagrams. It is intended to carry WireGuard traffic, but does not configure, inspect, or depend on WireGuard: the same relay can carry any UDP application.

The design keeps four concerns separate:

local UDP application -> tunnel core -> selected transport -> tunnel core
                                                     -> backend UDP application

The server gives each authenticated client its own backend UDP socket. The application payload is not decoded or rewritten.

Status

This checkout is specification-first and under active implementation. The milestone and v1 acceptance checklist is in docs/IMPLEMENTATION_CHECKLIST.md. A transport is available only when its code, tests, and integration criteria are verified; the documentation intentionally does not imply that all four transports are already present.

Target v1 transport order:

1. direct UDP (Milestone 1)
2. QUIC DATAGRAM (Milestone 2)
3. HTTP/3 CONNECT-UDP (Milestone 4)
4. TLS/TCP framed fallback (Milestone 5)

Build and install

Rust and Cargo are required. From the repository root:

cargo test
cargo build --release

For a host installation (choose a reviewed release artifact):

sudo install -Dm755 target/release/wgcloak /usr/local/bin/wgcloak
sudo install -d -m0750 /etc/wgcloak

The binary name and subcommands are the intended interface from spec.md:

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

Run wgcloak --help against the built binary to confirm the commands in the current build. QUIC, HTTP/3, control commands, and certificate reload are milestone-gated; see the checklist before deploying them.

Configuration

Copy and edit one of the safe, placeholder-only examples:

• examples/client.minimal.toml
• examples/client.advanced.toml
• examples/server.minimal.toml
• examples/server.advanced.toml

Put real secrets in separate files, owned by the service account, mode 0600. Do not commit them. See docs/OPERATIONS.md and docs/SECURITY.md.

Run with systemd

The templates in packaging/systemd/ assume a dedicated wgcloak user, /usr/bin/wgcloak, and configuration under /etc/wgcloak/. Review paths and transport support before installing them. The server template includes hardening and a commented optional CAP_NET_BIND_SERVICE setting for ports below 1024; normal operation does not require CAP_NET_ADMIN or CAP_SYS_ADMIN.

Documentation

• docs/ARCHITECTURE.md: process, data path, and ownership boundaries.
• docs/PROTOCOL.md: direct packet model and transport contracts.
• docs/OPERATIONS.md: files, control socket, lifecycle, and deployment.
• docs/SECURITY.md: threat model, secrets, privileges, and non-goals.
• docs/TROUBLESHOOTING.md: checks for common startup and connectivity failures.
• docs/IMPLEMENTATION_CHECKLIST.md: milestones 1–6 and all 17 v1 criteria.

Explicit non-goals

wgcloak does not configure WireGuard, create TUN/TAP devices, change routes or firewalls, fragment application datagrams, spoof browser/TLS fingerprints, or provide clustering, roaming, a GUI, Windows/macOS support, or multiple client tunnels in v1.