How do I resolve SSH connection issues to my Amazon EC2 Linux instance?

12 minute read

I can't use SSH to connect to my Amazon Elastic Compute Cloud (Amazon EC2) Linux instance.

Short description

If there are SSH issues in your EC2 instance, then you might receive "Permission denied", "Connection refused", or "Resource temporarily unavailable" error messages.

To diagnose and automatically resolve configuration issues that cause SSH connection issues, run the AWSSupport-TroubleshootSSH automation.

Or, to manually resolve SSH issues, use one of the following methods to connect to your instance:

SSH with verbose messaging activated.
The EC2 Serial Console.
Session Manager, a capability of AWS Systems Manager.

Then, follow the resolution steps for the error message that you receive.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Prerequisites: Make sure that there's network connectivity to your instance. Also, make sure that you have the following information:

The .pem private key file that's associated with the instance
The correct username for your Linux distribution
The IP address or DNS name of your instance
Note: If you recently stopped and started your instance, then the public IPv4 address changed unless you associated an Elastic IP address with the instance. Check the Amazon EC2 console for the instance's current IP address or DNS name. Or, use the instance's public DNS host name that automatically resolves to the current IP address.

Run the AWSSupport-TroubleshootSSH runbook

Prerequisites:

Copy the instance ID of the unreachable instance.
Make sure that you have the required AWS Identity and Access Management (IAM) permissions. For more information, see Required IAM permissions on AWSSupport-TroubleshootSSH.
Make sure that you meet the EC2Rescue for Linux requirements.
Note: The runbook uses EC2Rescue to check for and resolve configuration issues.

To run AWSSupport-TroubleshootSSH, use the AWS CLI. Or, use the AWS Systems Manager console and configure the following settings:

For Automation document, choose AWSSupport-TroubleshootSSH.
Under Document details, choose Default version at runtime for Runbook version.
Under Input parameters, enter the unreachable instance's ID for InstanceID and FixAll for Action.

For more information, see Smart RDP and SSH remediation with AWS Systems Manager Automation API actions.

Connect with SSH with verbose messaging activated

Run the following command to connect to your Linux instance with verbose messaging activated:

ssh -vvv -i my_key.pem ec2-user@11.22.33.44

Note: Replace my_key.pem with your private key file, ec2-user with your username, and 11.22.33.44 with your IP address.

To determine the cause of your issue, check the error messages in the output of the SSH client. Then, proceed to Resolve SSH errors.

Connect with the EC2 Serial Console

Prerequisites:

Make sure that you meet the serial console prerequisites.
Configure access to the serial console.
Use an instance that's built on the AWS Nitro System or a supported bare metal instance.

Use the EC2 Serial Console to connect to the instance and diagnose the issue. For example, check the sshd service status, log files, and configuration files.

If you can't connect and receive a blank screen, then take the following actions:

Use the System Request (SysRq) key to troubleshoot.
Reboot your instance.
Use your own key and an SSH client to connect to your instance.

Use Session Manager

Prerequisites: Make sure that you meet the Session Manager prerequisites.

Use Session Manager to connect to your instance so that you can run bash commands on the instance.

If you lost SSH access because of a lost key, forgotten password, or SSH misconfiguration, then you can use Session Manager to regain instance access. Then, check the logs for errors, confirm that your configuration files are correct, or reset your credentials.

Note: SSH port 22 doesn't need to be open for you to use Session Manager. However, if you use port forwarding through Session Manager, then the instance's security groups and sshd configuration manage the forwarded SSH connection.

Resolve SSH errors

Troubleshoot "Connection timed out" or "Connection refused" errors

If the server doesn't respond to the client's request, then you receive the "Connection timed out" error message. If the instance reaches the host but rejects the connection because no service is listening on the SSH port, then you receive the "Connection refused" error message. To resolve these issues, see How do I troubleshoot "Connection refused" or "Connection timed out" errors when I use SSH to connect to my EC2 instance?

If sshd doesn't start, then you can't connect with SSH even if the instance is running and network connectivity is correct. As a result, you receive the "Connection refused" error. In this scenario, the sshd status is failed or activating (auto-restart), or SSH enters a restart loop with the 255 exit code.

To resolve this issue, complete the following steps:

Use Session Manager, the EC2 Serial Console, or a rescue instance to connect to the instance.
Note: For information about how to launch a rescue instance, see How do I use EC2Rescue for Linux to troubleshoot OS-level issues?

Run the following command to check the sshd service status:

sudo systemctl status sshd
sudo journalctl -u sshd--no-pager -n 50

Run the following command to check the sshd configuration:
```
sudo sshd --t
```
If you find syntax errors, then update the /etc/ssh/sshd_config configuration file.
If the host keys are missing, then run the following command to regenerate them:
```
sudo ssh-keygen -A
```

Run the following command to update the configuration permissions to the required values:

sudo chmod 600 /etc/ssh/ssh_host_*_key
sudo chmod 644 /etc/ssh/ssh_host_*_key.pub
sudo chmod 600 /etc/ssh/sshd_config

Note: Private keys must be readable only by root (600). Public keys must be readable by all users (644). If these permissions are incorrect, then sshd doesn't start.

To check for a port conflict, run the following command to identify what's listening on port 22:
```
sudo ss -tlnp | grep :22
```
If another service is using port 22, then stop that service. Or, reconfigure sshd to use a different port in /etc/ssh/sshd_config.
If dependencies are missing after a package update, then run the following command to reinstall the OpenSSH server.
```
sudo dnf reinstall openssh-server
```
Note: For Amazon Linux 2 (AL2) replace dnf with yum.

Run the following command to restart the service:

sudo systemctl restart sshd

If you receive the "No journal files were found" error and sshd doesn't start, then run the following command to reboot the instance:
```
sudo reboot
```
Note: The preceding command reboots the EC2 instance, not your local machine. The reboot restores system logging so that sshd can start.

If you get a "Connection timed out" error on a virtual private cloud (VPC), then you might have a network configuration issue. Check your security group, network access control lists (network ACLs), VPC route tables, or local firewall. For more information, see How do I troubleshoot Amazon EC2 instance connection timeout errors from the internet?

Troubleshoot "Permission denied" or "Authentication failed" errors

If you can't authenticate through SSH to access your instance, then you receive "Permission denied" or "Authentication failed" errors to occur. This issue occurs if there are key or permission configuration issues. To resolve this issue, see How do I resolve the "Permission denied (publickey)" or "Authentication failed, permission denied" errors when I access my EC2 instance?

If the /etc/ssh/sshd_config file contains AllowGroups, AllowUsers, DenyGroups, or DenyUsers attributes, then only explicitly listed users or groups can connect. If your user isn't a member of the allowed group, then you receive "Permission denied" errors even if you have a valid key.

To resolve this issue, complete the following steps:

Use the EC2 Serial Console, Session Manager, or a rescue instance to access the instance.
Note: For information about how to launch a rescue instance, see How do I use EC2Rescue for Linux to troubleshoot OS-level issues?

Check /var/log/secure for Amazon Linux instances or /var/log/auth.log for Ubuntu instances for messages that show the user isn't in the allowed group.
Example entry:

sshd[12345]: User ec2-user from 10.0.0.1 not allowed because none of user's groups are listed in AllowGroups

To resolve the permissions issue, take one of the following actions in /etc/ssh/sshd_config:
Add your user to AllowUsers.
-or-
Add your user to the group that's specified in AllowGroups.
-or-
Remove the restrictive attribute.

Run the following command to restart the SSH service:

sudo systemctl restart sshd

Troubleshoot "Permission denied" or connection failures caused by a full disk

You might also receive "Permission denied" or "Connection reset by peer" errors if the root volume of your instance is full. If there's no free disk space, then sshd can't write to log files or create temporary authentication files.

To identify whether this issue is caused by disk space, connect to your instance through EC2 Serial Console or Session Manager. Then, run the following commands to check disk space and inode usage:

df -h
df -hi

If any filesystem shows 100% usage in the output, then disk space is the cause of the SSH failure.

To resolve full disk space issues, see How do I troubleshoot an EC2 Linux instance that fails a status check because of resource over-usage?

If you persistently run out of disk space, then increase your Amazon Elastic Block Store (Amazon EBS) volume size.

Troubleshoot "Server refused our key" errors

If you use the incorrect private key, username, or permissions when you connect with SSH, then you receive the "Server refused our key" error message. SSH server configuration issues can also cause this error. To resolve this error, see Why do I receive the "Server refused our key" error message when I try to connect to my EC2 instance through SSH?

Troubleshoot "imported-openssh-key" or "Putty Fatal Error" errors

If you use an incorrect username to connect, then you receive "imported-openssh-key" or "Putty Fatal Error" error messages. This issue also occurs if you use the wrong private key during a SSH session negotiation. To resolve these issues, see Why do I receive the "imported-openssh-key" or "PuTTY Fatal Error" when I connect to my Amazon EC2 Linux instance through a PuTTY client?

Troubleshoot "Enter passphrase for key 'my_key.pem'" errors

If you created a password for your key file, but didn't manually enter the password, then you receive the "Enter passphrase for key 'my_key.pem'" error message. To resolve this issue, manually enter the password. Or, use ssh-agent to automatically load the key.

Troubleshoot "no hostkey alg", "no matching host key type found", or "no matching key type found" errors

If the SSH client and server can't agree on the cryptographic algorithms for the connection, then you receive one of the following error messages:

"no hostkey alg"
"no matching host key type found. Their offer: ssh-rsa"
"Unable to negotiate with port 22: no matching host key type found"

This issue typically occurs if you use Amazon Linux 2023 (AL2023) with an earlier client that supports only ssh-rsa. By default, AL2023 uses OpenSSH 8.7+ that deactivates the ssh-rsa (SHA-1) host key algorithm. To resolve this issue, upgrade your clients to versions that support rsa-sha2-256 or rsa-sha2-512.

As a temporary workaround, complete the following steps to activate ssh-rsa on your server:

Use Session Manager or EC2 Serial Console to connect to the instance.

Run the following command to generate an RSA host key:

sudo ssh-keygen -b 4096 -t rsa -f /etc/ssh/ssh_host_rsa_key

Run the following command to create a drop-in configuration file that activates ssh-rsa:

sudo bash -c 'cat > /etc/ssh/sshd_config.d/51-host-key.conf << EOF
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa
EOF'

Run the following command to restart SSH:

sudo systemctl restart sshd

Key errors might also occur if you use an outdated SSH client. PuTTY 0.65 and earlier, early versions of WinSCP, and legacy systems such as Sun OS might not support the required key exchange algorithms. Or, the instance's openssh-client might be an earlier version that can't connect to the remote server that has the latest algorithms. To resolve this issue, update your openssh-clients package.

Troubleshoot slow or unresponsive SSH connections

If you can establish SSH connections but commands are slow or the session hangs, then your Amazon EBS volumes might be throttled. To troubleshoot this issue, see How do I troubleshoot Amazon EBS performance issues with my Amazon EC2 instance?

Troubleshoot kernel panic or "No bootable device found" error messages

If your instance is unreachable after a kernel or operating system (OS) update, then the instance has boot issues. In this scenario, SSH connection times out with no response or the instance fails its status checks. The EC2 Serial Console might show kernel panic or "No bootable device" errors. To troubleshoot this issue, see How do I resolve the "Kernel panic - not syncing" error in my EC2 instance? and How do I troubleshoot an EC2 Linux instance that failed the instance status check because of OS issues?

Make sure that you follow best practice to update your instance's kernel.

Troubleshoot third-party application issues

If SSH works but a third-party management panel, such as Baota, cPanel, Plesk, or Webmin, is inaccessible, then check for panel software configuration issues.

Run the following command to check whether the panel service is running:

systemctl status panel-service

Note: Replace panel-service with the service name.

Also, make sure that the security group allows traffic on the panel's port. If you still encounter issues, then check the panel vendor's documentation to make sure that your configuration is correct.