Troubleshooting EzTunnelSSH: Common Issues and Fixes

Troubleshooting EzTunnelSSH: Common Issues and Fixes

1. Connection refused / cannot reach remote host

• Cause: SSH server not running, wrong host/port, firewall blocking, or network outage.
• Fixes:
  1. Verify remote host and port (ssh user@host -p PORT).
  2. Ensure SSH server is running on the remote machine (systemctl status sshd).
  3. Check firewall rules on client and server (ufw/iptables/nftables) and allow the SSH port.
  4. Test network connectivity (ping, traceroute).

2. Authentication failures (password/key rejected)

• Cause: Wrong credentials, missing/incorrect private key permissions, or key not authorized.
• Fixes:
  1. Confirm username and password.
  2. Check private key permissions (chmod 600 /.ssh/id_rsa).
  3. Verify public key is in /.ssh/authorized_keys on server and has correct permissions (chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys).
  4. Use ssh -v to inspect authentication steps.

3. Port forwarding not working (local/remote/ dynamic)

• Cause: Incorrect port mapping, services not listening, or bind restrictions on server.
• Fixes:
  1. Confirm correct tunnel syntax (local forward: -L local_port:dest_host:dest_port; remote: -R remote_port:dest_host:dest_port; dynamic: -D socks_port).
  2. Ensure destination service is listening and reachable from the SSH server.
  3. For remote forwards, allow GatewayPorts or adjust sshd_config (AllowTcpForwarding yes, GatewayPorts yes) and restart sshd.
  4. Check for collisions with existing services using the same port.

4. Tunnel drops or disconnects frequently

• Cause: Unstable network, server-side timeouts, or keepalive not configured.
• Fixes:
  1. Enable keepalives: client-side (ServerAliveInterval 60) and server-side (ClientAliveInterval/ClientAliveCountMax).
  2. Use autossh to automatically restart dropped tunnels.
  3. Investigate network stability and latency; check logs (/var/log/auth.log or journalctl -u sshd).

5. High latency or slow performance through tunnel

• Cause: Bandwidth limits, encryption overhead, or intermediate network congestion.
• Fixes:
  1. Test raw latency/bandwidth (ping, iperf) to identify bottleneck.
  2. Use compression (-C) if CPU permits.
  3. Consider lighter ciphers in sshd_config/ssh (-c aes128-ctr) if compatible and secure.
  4. Offload heavy traffic outside the tunnel if possible.

6. Permission denied for binding privileged ports (<1024)

• Cause: Non-root user cannot bind low ports on remote host.
• Fixes:
  1. Use higher (>1024) ports for forwarding.
  2. If necessary and safe, run SSH as root or set CAP_NET_BIND_SERVICE on the sshd binary — weigh security implications.

7. DNS/name resolution issues over tunnel

• Cause: Client or server resolving names differently or DNS not routed through the tunnel.
• Fixes:
  1. Use IP addresses in forwarding rules or ensure DNS queries go through the tunnel (configure proxy/DNS settings for the application).
  2. For dynamic SOCKS proxies (-D), configure the app or system to use the SOCKS proxy and enable remote DNS if supported.

8. Permission or SELinux/AppArmor blocking connections

• Cause: Host security frameworks preventing sshd from forwarding/binding.
• Fixes:
  1. Check audit logs (`