Troubleshooting

Start with observation, not configuration changes. Capture the version, deployment mode, policy index and the smallest reproducible flow.

Baseline checklist

sudo smithproxy --config-check-only
sudo sx_ctl status
show status
show event list
diag workers proxy list
diag proxy session list active ips
diag writer stats

No session appears

  1. Confirm the application is using the configured SOCKS/CONNECT listener or that diversion rules count matching packets.
  2. Confirm the relevant accept_* switch and worker count.
  3. Check that Smithproxy's own upstream traffic is exempt from diversion.
  4. Test IPv4 and IPv6 separately.
  5. For TPROXY, verify packet marks, policy routing and local routes.

Session appears but the connection fails

Use higher verbosity:

diag proxy session list 7 tls io ips
show event list
show event detail <id>

Check the matched policy, original destination, upstream DNS result, TLS verification error and queue state. A CONNECT 403 indicates policy rejection; 431 means oversized request headers; 502 indicates resolution or upstream connection failure.

TLS certificate errors

  • confirm the client trusts the correct current ca-cert.pem;
  • verify hostname/SAN and client clock;
  • inspect diag tls verify stats, CRL and OCSP events;
  • reload after custom-certificate changes with diag tls ca reload or cache clear as appropriate;
  • never solve a broad validation problem by globally allowing invalid certificates.

Capture is empty or missing

  • confirm the matched policy selects the intended content profile;
  • verify write_payload, global captures.local.enabled and directory permissions;
  • inspect diag writer stats and disk space;
  • trigger execute pcap rollover before reading an aggregate file still open for writing;
  • confirm configured byte limits are not zero in the sense used by the selected release.

High CPU or memory pressure

diag workers proxy list
diag workers pool list
diag mem buffers stats
diag mem udp stats
diag writer stats

Reduce unnecessary capture, fingerprinting and debug verbosity. Check webhook latency before increasing worker counts. Synchronous content webhooks can stall traffic and accumulate buffers.

API failures

diag api info
show event list

Confirm HTTPS, port, access key/session token, source-address restrictions and build support for PAM login. Release builds protect /api/status/ping; do not rely on unauthenticated health checks observed in a debug build.

Reporting an issue

Include:

  • exact commit/tag and distribution;
  • OpenSSL version and whether QUIC is involved;
  • sanitized configuration sections and matched policy;
  • minimal CLI diagnostics and relevant events;
  • reproduction using a non-sensitive test endpoint.

Remove access keys, cookies, private keys, captured payloads and internal addresses unless they are essential and safe to disclose.