Troubleshooting SSH Issues

Troubleshooting SSH Issues

SSH failures have a small set of well-defined root causes. The systematic approach: check connection refused (is SSH running, is the port open?), check authentication (correct key, correct permissions), check host key (server identity changed?), and use ssh -vvv to see exactly where the handshake fails. Most SSH problems are solvable within five minutes with the right diagnostic steps.

Connection refused

ssh user@192.168.1.10
# ssh: connect to host 192.168.1.10 port 22: Connection refused

# Diagnosis:

# 1. Is SSH running on the server? (need console access)
sudo systemctl status ssh

# 2. Is SSH listening on the expected port?
sudo ss -tlnp | grep sshd

# 3. Is a firewall blocking the port?
sudo ufw status verbose
sudo iptables -L INPUT -n | grep 22

# 4. Are you connecting to the right port?
ssh -p 2222 user@192.168.1.10    # If custom port

# 5. Is the server reachable at all?
ping -c 3 192.168.1.10

Permission denied (publickey)

ssh user@server
# Permission denied (publickey).

# Step-by-step diagnosis:

# 1. Verify the key is being offered
ssh -v user@server 2>&1 | grep "Offering\|Accepted\|denied"

# 2. Check permissions on SERVER (most common cause):
ssh user@server 'ls -la ~/.ssh'
# ~/.ssh must be 700, authorized_keys must be 600

# Fix permissions:
ssh user@server 'chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys'

# 3. Check public key is in authorized_keys:
ssh user@server 'cat ~/.ssh/authorized_keys'
# Compare with: cat ~/.ssh/id_ed25519.pub

# 4. Check server logs (on the server):
sudo journalctl -u ssh --since "5 min ago"
sudo tail -f /var/log/auth.log

Common auth.log entries

Authentication refused: bad ownership or modes for directory /home/user/.ssh
  → Fix: chmod 700 /home/user/.ssh

Authentication refused: bad ownership or modes for file /home/user/.ssh/authorized_keys
  → Fix: chmod 600 /home/user/.ssh/authorized_keys

userauth_pubkey: key type ssh-rsa not in PubkeyAcceptedAlgorithms
  → Old RSA key; use ed25519 or add ssh-rsa to PubkeyAcceptedAlgorithms

Host key verification failed

# This error means the server's host key changed since your last connection
# WARNING: This can indicate a MITM attack or simply a server rebuild
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

# Before removing the old key:
# 1. Verify through out-of-band method that the server was legitimately rebuilt
# 2. Get the current host key fingerprint from console/provider dashboard

# If confirmed legitimate rebuild: remove the old entry
ssh-keygen -R 192.168.1.10    # Remove by IP
ssh-keygen -R server.example.com  # Remove by hostname

# Then reconnect and accept the new key:
ssh user@server

⚠️ WARNING: Do NOT blindly remove the known_hosts entry and reconnect if you have not verified the server was rebuilt. Host key changes can indicate an active man-in-the-middle attack. Verify through a second channel (cloud console, Slack, phone) that the server was intentionally reinstalled.

SSH hanging at connection

# SSH hangs at "debug1: SSH2_MSG_KEXINIT sent" — usually DNS or MTU
# 1. Try connecting with DNS disabled:
ssh -o StrictHostKeyChecking=no -o AddressFamily=inet user@server

# 2. Bypass DNS lookup
ssh -o "GSSAPIAuthentication no" user@server

# 3. Test with UseDNS disabled on server:
# In sshd_config: UseDNS no

# SSH hangs after authentication (before prompt):
# Usually a slow MOTD or banner script
ssh -T user@server    # No pseudo-terminal, skips some startup scripts

Using debug mode with ssh -vvv

# -v, -vv, -vvv: increasing verbosity levels
# -vvv shows every authentication attempt in detail
ssh -vvv user@server 2>&1 | head -60

Key lines to look for in debug output

debug1: Connecting to server [192.168.1.10] port 22.   ← Connection attempt
debug1: Connection established.                          ← TCP connected
debug1: Offering public key: /home/irfan/.ssh/id_ed25519   ← Key offered
debug1: Server accepts key: ...                            ← Key accepted (auth success)
# OR
debug1: Authentications that can continue: publickey       ← Key rejected
debug1: Next authentication method: publickey
debug3: no such identity: /home/irfan/.ssh/id_rsa          ← Key not found locally

Conclusion

The SSH diagnostic toolkit: ssh -vvv to see exactly where authentication fails, sudo journalctl -u ssh or /var/log/auth.log on the server for the server-side error message, and chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys as the fix for 80% of key auth failures. Connection refused means SSH is not running or a firewall is blocking — check systemctl status ssh and ufw status first. Host key verification failures require out-of-band verification before removing the known_hosts entry.