obfs4 Bridge Troubleshooting: Diagnose and Fix Common Issues

After configuring a new bridge, it can take 48-72 hours to appear in the bridge authority database. Check relay search (metrics.torproject.org/rs.html) after this period. If still not appearing: verify BridgeRelay 1 is in torrc, verify ORPort and ExtORPort are configured correctly, verify ServerTransportPlugin line points to a valid obfs4proxy binary path. Common issue: ExtORPort is required when using pluggable transports - without it, obfs4proxy cannot communicate with Tor. Check Tor logs for 'Opening OR listener on' and 'Registered server transport obfs4' messages confirming successful initialization. If these messages are absent, review torrc for syntax errors.

Error in logs: 'obfs4proxy: Unable to bind to address: listen tcp 0.0.0.0:PORT: bind: address already in use'. Solution: another process is using the port. Find it: ss -tlnp | grep PORT. Options: kill the conflicting process, change the obfs4 port in torrc (ServerTransportListenAddr obfs4 0.0.0.0:NEWPORT), or if running multiple Tor instances, each needs a unique obfs4 port. Error: 'obfs4proxy: Unable to bind to address: permission denied' on ports below 1024. Solution: run obfs4proxy as root (not recommended) or use port 443 requires CAP_NET_BIND_SERVICE capability, or use ports above 1024 and redirect with iptables (iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 4443).

If your bridge is running but clients report connection failures: verify the client is using the correct bridge line (exact fingerprint and obfs4 certificate from /var/lib/tor/pt_state/obfs4_bridgeline.txt). Test the bridge port is reachable from outside: from an external server, nc -zv BRIDGE_IP BRIDGE_PORT. If nc fails: firewall is blocking the port. Check ufw status or iptables -L -n | grep PORT. Common mistake: allowing port in iptables but forgetting INPUT chain default is DROP and ACCEPT rule is positioned after a DROP. Verify correct iptables rule ordering. Test obfs4 connection specifically: obfs4proxy client mode test from another server verifies the obfuscation layer specifically.

Client error 'Fingerprint mismatch for bridge' occurs when the bridge's identity fingerprint changed (key regenerated). This happens if: /var/lib/tor/keys/ was deleted or permissions changed causing Tor to regenerate keys. Fix: share the new bridge line (from /var/lib/tor/pt_state/obfs4_bridgeline.txt) with affected clients. Prevention: backup /var/lib/tor/keys/ and never delete it. Ensure proper ownership and permissions: chown -R debian-tor:debian-tor /var/lib/tor/ and chmod 700 /var/lib/tor/. Tor will not start if permissions on the data directory are too permissive (readable by other users).

If your bridge is running but serving much less bandwidth than expected: check if BandwidthRate is set too low in torrc. Check system-level bandwidth limits (tc rules, provider-side throttling). Verify CPU is not saturating on encryption - obfs4 is computationally light but on very slow servers (shared VPS with throttled CPU), encryption can become a bottleneck. Check memory usage - Tor processes many circuits simultaneously, each requiring memory. On low-RAM servers (<512MB), consider reducing MaxCircuitDirtiness or PerConnBWRate to reduce concurrent circuit count. Network interface errors: ip -s link show shows dropped packets and errors on the interface - network hardware issues cause silent packet loss.