docs: add comprehensive project wiki for v1.0

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2026-06-04 14:07:55 -06:00
parent a758e8e0bc
commit 0166fb6511
32 changed files with 1483 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Debugging
+
+## Logs
+
+rustunnel uses `tracing` with an `EnvFilter` defaulting to `info`. Set `RUST_LOG=debug` or `RUST_LOG=trace` for more detail.
+
+```sh
+RUST_LOG=debug ./target/release/rustunnel listen --listen 127.0.0.1:4180 ...
+```
+
+All logged secrets are redacted. The `Redacted` wrapper shows `[REDACTED(len=N)]` instead of the raw value. If you see raw secrets in logs, that is a bug.
+
+## Common errors
+
+### TLS handshake failures
+
+If the connector fails with a TLS error, check:
+
+- Do the listener and connector share the same CA certificate?
+- Does the server certificate's SAN match the target hostname? Use `generate` with the correct `--advertise` address, or pass `--insecure-skip-tls-verify` (lab only).
+- Are the certificate files readable and valid PEM?
+
+rustunnel prints TLS hint messages for common failures:
+
+- `BadSignature` — the listener certificate is not signed by the CA trusted by the connector.
+- `NotValidForName` — the listener certificate does not match the target host.
+
+### Auth failures
+
+- Verify the token file is not empty and has no trailing whitespace.
+- The listener and connector must use the same token value.
+- Auth failures are terminal for the connector's reconnect loop (it will not retry with a bad token).
+
+### Port conflicts
+
+If binding fails with "address already in use":
+
+- Check for orphaned processes from previous test runs.
+- The E2E tests use random free ports; manual testing may need explicit port management.
+
+### SOCKS5 connection refused
+
+If curl fails through the SOCKS5 proxy:
+
+- Is the connector running and the tunnel established?
+- Is the SOCKS5 proxy port correct?
+- Is the target address reachable from the listener side (for default mode) or connector side (when using `--socks` on the listener)?
+
+## Tracing
+
+The connector logs effective config at startup, including the target, SOCKS5 address, and redacted auth token. The listener logs its bind address, TLS fingerprints, and auth token (redacted).
+
+State transitions are logged at `info` level: "Tunnel session established", "Tunnel disconnected", "Reconnecting in Ns".