100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# 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.
|