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¶
- Confirm the application is using the configured SOCKS/CONNECT listener or that diversion rules count matching packets.
- Confirm the relevant
accept_*switch and worker count. - Check that Smithproxy's own upstream traffic is exempt from diversion.
- Test IPv4 and IPv6 separately.
- 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 reloador 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, globalcaptures.local.enabledand directory permissions; - inspect
diag writer statsand disk space; - trigger
execute pcap rolloverbefore 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.