Troubleshooting Common SSH Issues

Up to this point, I’ve focused on setting up SSH securely and exploring advanced techniques. But even the most seasoned pros run into connection problems. In this post, I’m going to show you how to diagnose and fix some of the most common SSH errors—from “Connection Refused” to “Host Key Verification Failed.” Whether you’re a beginner or a seasoned sysadmin, these tips will help you quickly pinpoint issues and get back online.

Top 5 SSH Errors and Quick Fixes

“Connection Refused”

This message usually looks something like:

$ ssh user@server-ip
ssh: connect to host server-ip port 22: Connection refused

Common Causes

1. SSH Server Isn’t Running
   • On Linux, run sudo systemctl status sshd (or systemctl status ssh on some distros).
   • If it’s inactive, start it with sudo systemctl start sshd.
2. Firewall Blocking the Port
   • Check your firewall rules with sudo ufw status (Ubuntu) or sudo iptables -L -n.
   • Ensure port 22 (or your custom SSH port) is allowed.
3. Wrong Port
   • If you changed SSH to a non-default port, specify it explicitly:

     ssh -p 2222 user@server-ip
     

4. Server Is Down
   • Try ping server-ip to ensure it’s reachable.
   • If it doesn’t respond, the server might be offline or behind another firewall.
5. Network-Level Issues (NAT, VPN)
   • If your server is behind a NAT or requires a VPN, verify your connection to that network.

Quick Fix Verify the SSH service is running and the firewall is configured. Also confirm you’re using the correct port.

“Host Key Verification Failed”

This usually means the server’s host key stored on your client doesn’t match what the server is presenting now. You might see:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @ 
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
....
_some-messages_
....
Host key verification failed.

Why This Happens

1. Server Reinstalled or Host Key Regenerated
   • The server’s fingerprint has changed since your first connection.
2. Possible Man-in-the-Middle Attack
   • If you aren’t expecting a key change, proceed cautiously—someone might be impersonating your server.

How to Fix

1. Remove the Old Key
   • Open ~/.ssh/known_hosts and delete the line for that server’s IP or hostname.
   • Or run:

     ssh-keygen -R <server-ip-or-hostname>
     

2. Reconnect
   • SSH will prompt you to accept the new key. Double-check the server’s authenticity before confirming.

Best Practice
If you’re sure it’s just a reinstallation, removing the old key is fine. But if you suspect malicious activity, verify the server’s fingerprint out-of-band (e.g., phone call, official documentation).

“Permission Denied”

When you see:

Permission denied (publickey,password).

or something similar, it indicates you’re not allowed to log in with your provided credentials.

Possible Causes

1. Wrong Username/Password
   • Always verify you have the correct username and password.
2. Key File Permissions
   • SSH is picky about file permissions. Ensure the private key file is chmod 600 and the .ssh directory is chmod 700.
3. Server-side Issues
   • The authorized_keys file on the server might be incorrectly set (chmod 600).
   • If you’re using key-based authentication, confirm your public key is in ~/.ssh/authorized_keys.
4. Account Restrictions
   • SSH settings like AllowUsers or DenyUsers can block your user. Check /etc/ssh/sshd_config.

Quick Fix

• Double-check your credentials and file permissions.
• Use -v for extra verbosity; SSH will often hint at which step failed.

Firewall or Network-Level Issues

Even if SSH is running, network firewalls could still block traffic. Or your server might be behind NAT without a proper port-forward rule.

What to Check

1. Local Firewall
   • On your own machine, ensure outgoing connections on the SSH port are allowed.
2. Server Firewall
   • sudo ufw allow 22/tcp (Ubuntu) or relevant iptables/firewalld rules on RHEL/CentOS.
3. Router/NAT
   • If the server is behind a router, forward port 22 (or a custom SSH port) to the server’s local IP.
4. VPN
   • Confirm you’re connected to the VPN if the server requires it.

Quick Fix
Confirm both local and remote firewalls. Verify port-forwarding if on a private network.

“Network is Unreachable” or Timeout Errors

This might show up as:

ssh: connect to host 10.0.0.5 port 22: Network is unreachable

Likely Causes

1. Incorrect IP Address
   • Double-check you’re using the right address.
2. Network Connectivity
   • Is your Wi-Fi or Ethernet up? Are you on the correct VLAN or subnet?
3. Routing or DNS
   • If you’re using a hostname, verify DNS resolution.

Quick Fix
Check your network connection, correct IP/host, and ensure no router issues are preventing traffic.

Systematic Debugging Using Verbose Mode and Logs

Leveraging Verbose Mode

SSH has built-in verbosity levels: -v, -vv, and -vvv. These reveal where in the connection process things might be failing.

ssh -v user@server

You’ll see lines about key exchange, authentication, host key checks, etc. If one stage fails, you can narrow down your fix.

What Each Flag Shows

• -v
  • Basic debugging info.
• -vv
  • More detailed debugging, including which keys are tried for authentication.
• -vvv
  • Very detailed debugging (spams your console but can be invaluable).

Checking System Logs

On the server side

• Ubuntu/Debian
  • /var/log/auth.log
• CentOS/RHEL
  • /var/log/secure
• Generic
  • journalctl -u sshd (if you’re using systemd)

Look for sshd entries. Common messages include:

sshd[1234]: Failed password for user from 203.0.113.5 port 52524 ssh2
sshd[1234]: Accepted publickey for user from 203.0.113.5 port 52524 ssh2

These lines tell you if authentication succeeded or failed—and why.

Client Logs

• If you can’t figure it out from the server, you can also check your client’s syslog (on Linux) or use the verbose SSH output.

Best Practices for Smooth SSH Operations

1. Test After Each Change
   If you update sshd_config, always keep one session open while testing a new session in case something breaks.
2. Document Your Environment
   Note custom ports, allowed users, firewall rules, etc. This makes troubleshooting easier in the future.
3. Use a Bastion Host
   If you have multiple internal servers, a bastion can centralize logs and reduce your external attack surface.
4. Automate Where Possible
   Tools like Ansible or scripts can help keep configurations consistent across many servers.

Conclusion

Troubleshooting SSH doesn’t have to be stressful once you know where to look and what to look for. Using these tips—fixing common errors, running SSH in verbose mode, and checking logs—you’ll be able to resolve the majority of SSH connection issues quickly.

Whether you’re a newcomer or a seasoned admin, these troubleshooting steps are essential skills to have in your arsenal. If you still run into issues, feel free to leave a comment or explore further resources. In our next series instillment, I’ll keep digging into SSH’s capabilities and how you can ensure secure, reliable remote connections in any environment.

Stay tuned for more on harnessing the full power of SSH, and drop any questions or tips in the comments below!

Have questions or want to share your own SSH hardening tips? Leave a comment below, and let’s keep the conversation going.

• ← Previous Post
• Next Post →