# 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`](docs/IMPLEMENTATION_CHECKLIST.md) for
acceptance evidence and remaining v1 work.

## Build and install

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

```bash
cargo test --all-targets
cargo build --release
```

For a local host installation:

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

The CLI supports:

```bash
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.toml`](examples/client.minimal.toml)
- [`examples/client.advanced.toml`](examples/client.advanced.toml)
- [`examples/server.minimal.toml`](examples/server.minimal.toml)
- [`examples/server.advanced.toml`](examples/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:

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

See [`docs/OPERATIONS.md`](docs/OPERATIONS.md) for control commands, systemd
deployment, shutdown behavior, and troubleshooting pointers.

## systemd

The units in [`packaging/systemd/`](packaging/systemd/) assume a dedicated
`wgcloak` user, `/usr/bin/wgcloak`, and configuration under `/etc/wgcloak/`.
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`](docs/ARCHITECTURE.md): runtime roles and ownership.
- [`docs/PROTOCOL.md`](docs/PROTOCOL.md): wire protocol and transport behavior.
- [`docs/OPERATIONS.md`](docs/OPERATIONS.md): setup, control, and systemd.
- [`docs/SECURITY.md`](docs/SECURITY.md): threat model and permissions.
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md): common failures.
- [`docs/IMPLEMENTATION_CHECKLIST.md`](docs/IMPLEMENTATION_CHECKLIST.md):
  milestones 1–6 and all 17 v1 criteria.