72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# Troubleshooting
|
|
|
|
Check the simplest layer that can explain the symptom, then move outward.
|
|
|
|
## Process exits immediately
|
|
|
|
- Run the same command in the foreground and read the fatal configuration
|
|
error.
|
|
- Check that every secret/certificate path exists and is readable by the
|
|
service account, but not by unrelated users.
|
|
- Run `wgcloak --help` and `wgcloak check-config` to spot a command or schema
|
|
mismatch.
|
|
- Confirm listener addresses are valid and no other process owns the port.
|
|
|
|
## Client cannot connect
|
|
|
|
- Verify DNS resolution and the configured server name/port.
|
|
- Confirm the selected server listener is enabled and that the matching
|
|
transport/port appears in its `status` output. In auto mode, check the
|
|
configured client order and `retry_ms` status while it probes.
|
|
- For direct UDP, check both directions in the host firewall and allow the
|
|
server's UDP listener.
|
|
- For TLS transports, verify the hostname matches the certificate and do not
|
|
disable certificate verification.
|
|
- Authentication rejection means a bad/unknown client or secret and must not
|
|
be diagnosed as a firewall failure. Fix credentials before retrying.
|
|
|
|
## Authentication failures or repeated probing
|
|
|
|
Check client ID spelling, secret-file contents, ownership/mode, and system
|
|
clock skew. Direct HELLO timestamps have a target default 60-second window;
|
|
replayed client nonces are rejected. Repeated invalid credentials should stop
|
|
fallback probing rather than generate traffic across every transport.
|
|
|
|
## Connected but no application traffic
|
|
|
|
- Confirm the local application sends to the configured local UDP address.
|
|
- Confirm the server backend is listening at `[backend].target`.
|
|
- Check `status`/`stats` or structured logs for selected transport, maximum
|
|
datagram size, dropped/oversized datagrams, and backend errors.
|
|
- v1 remembers one most-recent local source peer per client tunnel. Concurrent
|
|
source peers can replace that return destination and produce a warning.
|
|
- No application-layer fragmentation exists: reduce payload size when the
|
|
configured transport limit is exceeded (starting target is 1200 bytes).
|
|
|
|
## Session disappears
|
|
|
|
The server's configured idle timeout applies per session. Check transport
|
|
keepalive behavior, NAT expiry, server resource limits, and whether the client
|
|
is reconnecting after a transport failure. A valid direct UDP packet can
|
|
update the peer address after NAT rebinding; a spoofed packet without a valid
|
|
MAC cannot.
|
|
|
|
## Control socket unavailable
|
|
|
|
Check the daemon and CLI use the same `XDG_RUNTIME_DIR`, and verify the
|
|
directory is private and the socket mode is `0600`. If `XDG_RUNTIME_DIR` is
|
|
unset or is not current-user-owned mode `0700`, the daemon uses
|
|
`/run/user/<uid>/wgcloak/` when available, or `$HOME/.local/run/wgcloak/`.
|
|
An active socket is never removed; a stale socket can be replaced only after
|
|
its type and identity are checked.
|
|
The `reload` command is present but currently returns an unsupported response;
|
|
neither configuration nor certificate hot reload is implemented.
|
|
|
|
## Host hardening prevents startup
|
|
|
|
Read the unit's journal output. Common causes are a secret/certificate path
|
|
outside the unit's read paths, a changed binary location, or an address family
|
|
not allowed by `RestrictAddressFamilies`. Correct the reviewed unit rather
|
|
than weakening all hardening directives. `CAP_NET_BIND_SERVICE` is only needed
|
|
for ports below 1024.
|