RustProxy/docs/TROUBLESHOOTING.md

Troubleshooting and validation checklist

Start with a reproducible request, its hostname/path and the exact listener. Compare Vhost, Backend, Cache, Logs and the service journal before changing multiple settings at once.

Quick symptoms

Symptom	First checks
Domain returns the wrong site or local 404	DNS A/AAAA, selected listener ID, exact vs wildcard host precedence, Vhost enabled state, redirect/404 host ownership.
HTTP works, HTTPS does not	Trusted certificate, hostname/SAN coverage, TLS listener, port 443 firewall, certificate assignment and whether restart was needed.
HTTPS/H2 works but H3 fails	UDP firewall/NAT, H3 toggle on TLS listener, browser QUIC support and actual transport negotiation.
502 / 503 / 504 to origin	Backend IP/port, pool eligibility/health, private-address policy, upstream HTTPS verification, protocol auto/h2, timeout and container/PHP process availability.
WebSocket handshake fails or disconnects	Vhost WebSockets flag, backend Upgrade support, TLS/frontend protocol path, WebSocket idle limits and auth redirect.
403 / 405 / 429	Applicable IP/ACL/country policy, HTTP methods, rate limit, GeoIP availability, Basic/Tinyauth permissions.
Cache always BYPASS or MISS	Global + Vhost enablement, cookies/login, origin Cache-Control, Set-Cookie, Vary, TTL, size and exclusion rules.
Content remains stale	Cache Age/resident age, origin validator, policy changes, matching scheme/Host/query and selected purge scope.
Static file not found	Document root, process read permissions, index files, symlink policy, try_files and rewrite ordering.
PHP returns errors or another site's PHP settings	FPM endpoint/socket permission, distinct pool/INI settings, pool restart, PHP PATH_INFO, application logs.
Docker Vhost remains WAITING / 503	First agent poll, token/certificate pin, published host TCP binding, backend IP, container state and health.
Stream TCP/UDP unreachable	Actual listen address/port, protocol and firewall, backend IP, Stream health/session limits; HTTP Vhost settings do not apply.
Administration cannot be accessed remotely	Admin binds loopback by default. Use SSH tunnel or configure separate admin HTTPS and intentional bind address.
Prometheus exporter unavailable	Dedicated listener, CIDR and token, configured path, startup/restart state and monitoring server route.
Logs missing or search incomplete	Check sink enabled/path/permissions, Live vs Stored distinction, log rotation and bounded scan/truncation notices.
Certificate renewal fails	ACME runtime, HTTP-01 TCP 80, DNS-01 token/zone, expired credentials, Certbot files and external key ACL after rotation.

Useful commands

Local service status for installed Linux/systemd deployments:

systemctl status rustproxy
journalctl -u rustproxy -n 200 --no-pager

Inspect a specific HTTP frontend with the correct Host (adapt hostname, port and path):

curl -v -H 'Host: app.example.com' http://127.0.0.1:8080/health

For HTTPS certificate/routing testing use the real site DNS or a deliberate curl --resolve mapping; avoid permanently disabling certificate verification as a workaround. The local CLI can check configuration without saving:

rust-proxy --data-dir /var/lib/rustproxy config get
rust-proxy --data-dir /var/lib/rustproxy config validate config.json

Use Logs → Live Logs or the --livelogs CLI mode to correlate request IDs, Vhost/route/backend and status. Inspect Stored Logs for previously saved JSONL and selected low-level protocol failures.

Rollout gate for RustProxy 0.34.0

The latest source optimizations were not all compiled or performance-tested in the evidence supplied with this release. Before deploying:

1. Build using the declared Rust toolchain and run the project's available regression suite on the target platform.
2. Verify HTTP/1.1, HTTPS, HTTP/2, HTTP/3 (if enabled), WebSockets and multi-backend failover with a real origin.
3. Test private origin constraints, ACL/auth/CSRF, rate limits and protected cache content.
4. Test Web Server static files, PHP-FPM, cache revalidation/invalidation and optional sendfile=auto only if enabled.
5. Exercise certificate renewal/reload and backup restore on isolated staging.
6. Compare performance only under matched configurations with controlled repeatable traffic; do not label 0.34.0 as faster merely because its source reduces internal work.

For persistent problems, use the feature-specific guide in Documentation and preserve a redacted error example with environment/version and request ID.