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