rustunnel/droid-wiki/how-to-contribute/debugging.md

Debugging

Logs

rustunnel uses tracing with an EnvFilter defaulting to info. Set RUST_LOG=debug or RUST_LOG=trace for more detail.

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".