DevOps Knowledge Hub
DevOps Knowledge Hub

Troubleshooting Common SSH 'Permission Denied' Errors and Connection Issues

Master SSH connectivity by learning to conquer 'Permission denied' errors. This guide details how to use verbose mode (`-vvv`) to diagnose authentication failures, fix critical server-side file permissions (`700`/`600`) for `.ssh` directories, and verify necessary server configuration settings in `sshd_config` for reliable remote access.

37 views

Troubleshooting Common SSH 'Permission Denied' Errors and Connection Issues

Secure Shell (SSH) is the bedrock of remote server management, offering encrypted communication for accessing and controlling remote systems. While reliable, setting up SSH, especially with key-based authentication, can sometimes lead to frustrating connection failures. The most common culprit is the dreaded Permission denied error.

This comprehensive guide will walk you through diagnosing and resolving the most frequent SSH errors. We will focus specifically on understanding the root causes behind Permission denied (publickey) and address common pitfalls related to file permissions, incorrect configuration, and client/server setup mismatches. Mastering these troubleshooting steps ensures secure and reliable access to your remote infrastructure.

Understanding SSH Authentication Flow

Before troubleshooting, it’s crucial to understand how SSH authenticates users. When you attempt to connect, the server typically checks credentials in the following order (depending on configuration):

  1. Public Key Authentication: The client presents a public key, and the server checks if the corresponding private key is valid and matches an authorized key (authorized_keys file).
  2. Password Authentication: If key authentication fails or is disabled, the server prompts for a password.

When you receive Permission denied, it almost always means the server rejected your credentials during step 1 or 2.

Diagnosing Connection Issues: The Power of Verbose Mode

The single most effective tool for diagnosing SSH problems is running the client in verbose mode. By adding the -v, -vv, or -vvv flags, the client outputs detailed debugging information about the negotiation process.

Using Verbose Flags

Use the following command structure:

ssh -vvv user@remote_host

What to look for in the output:

  • Key Exchange: Look for lines indicating which authentication methods the client tried (e.g., Offering RSA key: /path/to/id_rsa).
  • Server Response: Pay close attention to the server's rejection messages. If the output shows the server is checking keys but fails to match, the issue is likely key configuration or permissions on the server side.
  • Password Prompt: If the output skips key checks and immediately asks for a password, key authentication may be disabled on the server.

Resolving Permission denied (publickey)

This error explicitly states that the server rejected the provided public key credential. The fix usually lies in permissions or key pairing.

1. Check Key File Permissions (Client Side)

For security, SSH clients are very strict about the permissions on your private key file (e.g., ~/.ssh/id_rsa). If these files are too open, the client will refuse to use them.

Actionable Fix (Client): Ensure your private key is only readable by you.

chmod 600 ~/.ssh/id_rsa

2. Verify Key Existence and Correct Key Use

Ensure you are connecting with the correct identity file, especially if you use non-standard keys or multiple key pairs.

Actionable Fix (Client): Specify the correct private key using the -i flag.

ssh -i /path/to/your/specific_private_key user@remote_host

3. Server-Side Permissions and Ownership

This is the most common source of failure. SSH enforces strict directory and file permissions on the server for the user you are trying to log in as.

Path on Server Required Permissions Owner
~/.ssh directory 700 (rwx------) User
~/.ssh/authorized_keys file 600 (rw-------) User

Actionable Fix (Server): Log in via console or password authentication (if enabled) and run these commands:

# Set directory permissions
chmod 700 ~/.ssh

# Set authorized_keys permissions
chmod 600 ~/.ssh/authorized_keys

# Verify ownership (replace 'myuser' with the actual username)
chown -R myuser:myuser ~/.ssh

Warning: If the permissions on the user's home directory (~/) are too broad (e.g., writable by group or others), SSH might also fail for security reasons. Aim for 755 or stricter on ~/ if problems persist.

4. Confirm Key is Actually Added

Ensure the public key string on the client matches exactly what is pasted into the server's ~/.ssh/authorized_keys file. A missing character or trailing whitespace will cause authentication failure.

Tip: When adding a key, use ssh-copy-id if available, as it handles permissions and formatting automatically:

ssh-copy-id user@remote_host

Troubleshooting Configuration File Issues (sshd_config)

If keys and permissions are correct, the issue often lies within the SSH daemon configuration file, typically located at /etc/ssh/sshd_config on the server.

1. Check Authentication Methods

Ensure that public key authentication is explicitly allowed.

Configuration Check: Look for the following lines and ensure they are uncommented (#) and set correctly:

PubkeyAuthentication yes
AuthorizedKeysFile  .ssh/authorized_keys

2. Password Authentication Status

If you are relying on password login temporarily, verify that it is enabled. If it is set to no, you must use keys.

PasswordAuthentication yes

3. PermitRootLogin

If you are attempting to log in as root, ensure this is permitted. Best practice is generally to log in as a standard user and use sudo, but for troubleshooting, you can check this setting:

PermitRootLogin yes

Crucial Step: After any changes to /etc/ssh/sshd_config, you must restart the SSH service for changes to take effect:
bash sudo systemctl restart sshd # Or service ssh restart

Other Common Connection Errors

While key issues are primary, other errors can block access:

A. Connection Timed Out

This usually means the client could not reach the server at all, indicating a networking issue, not an authentication issue.

Possible Causes:
* The server is down or unreachable.
* A firewall (local or network) is blocking the connection on port 22 (or custom SSH port).
* Incorrect IP address or hostname.

Troubleshooting: Use ping to check basic connectivity, and telnet or nc (netcat) to check if the port is open:

# Check if port 22 is reachable
telnet remote_host 22

B. No Route to Host

Similar to timeout, this is a network infrastructure problem. The client cannot find a path to the server's IP address. Check routing tables, VPN status, or ensure the remote server has a valid network interface active.

C. Server Refused Our Key

If the verbose output shows the server is actively rejecting keys but you've verified the authorized_keys file, check the SELinux or AppArmor security contexts on the server. These security modules can override file permissions and block SSH access if contexts are incorrect.

Summary of Best Practices

  1. Always use Verbose Mode (-vvv) for diagnosis.
  2. Client Key Security: Ensure private keys are set to 600 (chmod 600).
  3. Server File Integrity: Verify ~/.ssh is 700 and authorized_keys is 600.
  4. Restart Daemon: Always restart sshd after modifying /etc/ssh/sshd_config.
  5. Use ssh-copy-id whenever possible to automate key deployment.