DevOps Knowledge Hub
DevOps Knowledge Hub

Troubleshooting Common SSH Errors: Connection Refused and Denied

Resolve frustrating SSH connection issues by mastering the diagnosis of 'Connection Refused' and 'Permission Denied' errors. This practical guide details systematic troubleshooting steps, including verifying the sshd service status, debugging firewall rules (UFW), correcting key-based authentication permissions, and interpreting server authentication logs for swift resolution.

40 views

Troubleshooting Common SSH Errors: Connection Refused and Denied

Secure Shell (SSH) is the bedrock of remote system administration, providing encrypted communication for accessing servers. However, encountering connection errors can halt productivity immediately. The two most common and frustrating errors users face are "Connection Refused" and "Permission Denied".

This guide will walk you through a systematic approach to diagnosing and resolving these issues. By understanding the typical causes—ranging from network obstructions to incorrect authentication configurations—you can quickly restore secure access to your remote machines. We will cover essential checks, from verifying server status to debugging authentication mechanisms.

Understanding the Errors: Refused vs. Denied

It is crucial to differentiate between the two primary error messages, as they point to very different root causes:

  1. Connection Refused: This usually means the network connection reached the server, but nothing was listening on the specified port, or the operating system actively rejected the connection attempt.
  2. Permission Denied: This implies the SSH service (sshd) successfully received the connection request, but the authentication attempt (password or key) failed based on server configuration.

Part 1: Troubleshooting Connection Refused

"Connection Refused" (often seen as ssh: connect to host <hostname> port 22: Connection refused) typically points to an issue on the server side preventing the daemon from accepting incoming connections.

1. Verify the SSH Daemon (sshd) Status

The most common cause for refusal is that the SSH server process is not running or has crashed.

Actionable Steps (on the remote server):

Check the service status using systemctl (common on modern Linux distributions):

systemctl status sshd

If the status shows inactive or failed, start the service:

sudo systemctl start sshd
# Enable it to start automatically on boot
sudo systemctl enable sshd

2. Check the Listening Port and Configuration

By default, SSH runs on TCP port 22. If the port has been changed for security hardening, you must specify the correct port when connecting, or ensure the server is listening on the expected port.

A. Review sshd_config

Examine the SSH configuration file, typically located at /etc/ssh/sshd_config. Look for the Port directive:

# /etc/ssh/sshd_config example
Port 2222  # If this is not 22, you need to specify it client-side

If you change this file, you must restart the sshd service for changes to take effect.

B. Verify Listening Sockets

Use ss or netstat to confirm that sshd is actively listening on the expected interface and port. We check for port 22 here:

# Using ss (preferred on modern systems)
sudo ss -tuln | grep 22

# Expected output showing listening status:
# LISTEN 0      128    0.0.0.0:22               0.0.0.0:*

If nothing appears for port 22, the daemon is either not running or is configured to listen on a different address/port.

3. Firewall and Network Checks

A firewall blocking traffic before it reaches the sshd process will often result in a timeout, but sometimes it can present as a refusal. It is essential to confirm server-side firewall rules.

Common Firewall Commands (UFW on Ubuntu/Debian):

Ensure SSH traffic is allowed:

# Check current status
sudo ufw status

# Allow traffic on default port 22
sudo ufw allow ssh
# OR by port number
sudo ufw allow 22/tcp

# Reload firewall rules
sudo ufw reload

⚠️ Warning on External Firewalls: If you are connecting from a remote network, ensure that any intermediate network devices, cloud security groups (like AWS Security Groups or Azure NSGs), or hardware firewalls are explicitly permitting traffic on the SSH port.

Part 2: Troubleshooting Permission Denied

If you successfully connect to the server but immediately receive "Permission denied (publickey,password)", the issue lies strictly with authentication.

1. Check Username and Password

This is the simplest check, but often overlooked:

  • Username: Are you using the correct username for the target system? Root login might be disabled.
  • Password: If using password authentication, verify Caps Lock, typos, and ensure the account is not locked.

Client-Side Check: To see detailed debug output, run your client with verbose flags:

ssh -vvv user@hostname

This output will clearly show which authentication methods the client attempted and which the server rejected.

2. Key-Based Authentication Failures

Key-based authentication is superior, but configuration errors are frequent causes of denial.

A. Incorrect Permissions on .ssh Directory

SSH is extremely strict about file permissions for security. If the permissions are too open, the server will ignore the key file entirely.

On the Remote Server (Fixing Permissions):

# User's home directory permissions are usually fine, but check the .ssh folder
chmod 700 ~/.ssh

# The authorized_keys file must only be writable by the owner
chmod 600 ~/.ssh/authorized_keys

B. Key Not Present or Incorrectly Formatted

Ensure your public key (id_rsa.pub or similar) is correctly appended to the server's ~/.ssh/authorized_keys file for the target user. Each key must be on its own line, without line breaks inserted in the middle of the key string.

C. Server Configuration Disabling Keys

Check /etc/ssh/sshd_config on the server to ensure key authentication is permitted:

PubkeyAuthentication yes

# Ensure password authentication is not disabled if you rely on passwords
PasswordAuthentication yes

3. Server-Side Log Investigation

When authentication fails, the server logs are the ultimate source of truth. Look for messages related to the failed login attempt.

Common Log Locations:

  • Debian/Ubuntu: /var/log/auth.log
  • RHEL/CentOS/Fedora: /var/log/secure

Use grep to filter for recent connection attempts:

# On RHEL/CentOS systems
sudo grep 'Failed password' /var/log/secure

# Or look for general SSH activity
sudo tail -f /var/log/secure

Log messages often explicitly state why the key was rejected (e.g., bad options, no matching key found, or incorrect user context).

Best Practice Summary for Reliable SSH Access

  1. Use Key Pairs: Disable password authentication (PasswordAuthentication no) in sshd_config once key access is verified.
  2. Change Default Port: Moving SSH off port 22 reduces automated scan noise.
  3. Use PermitRootLogin no: Force administrative access through standard users, forcing use of sudo.
  4. Backup Configuration: Before making significant changes to /etc/ssh/sshd_config, always back up the original file:
    bash sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak.$(date +%F)
  5. Test Locally: After configuration changes, test connectivity locally on the server (if possible) before disconnecting your active session to avoid locking yourself out.

By systematically checking the service status, network path, and authentication configuration layers, you can swiftly resolve the frustrating Connection Refused and Permission Denied errors inherent in remote access management.