How do I troubleshoot "Connection refused" or "Connection timed out" errors when I use SSH to connect to my Amazon EC2 instance?

Resolution

Troubleshoot the "Connection refused" error

If a host remotely refuses your connection, then you receive the following error message:

"ssh: connect to host ec2-X-X-X-X.compute-1.amazonaws.com port 22: Connection refused"

To troubleshoot this issue, make sure that there isn't a firewall on the EC2 instance that blocks the SSH connection. Also, make sure that the SSH daemon (sshd) is running and listens on port 22.

Note: To check the preceding configurations, you must have operating system (OS) access to the instance.

Troubleshoot the "Connection timed out" error

If the server doesn't respond to the client, then the client program times out and you receive the following error message:

"ssh: connect to host ec2-X-X-X-X.compute-1.amazonaws.com port 22: Connection timed out"

To troubleshoot this issue, check the following settings:

• Make sure that the instance's IP address or hostname is correct.
• Make sure that the instance passes its status checks.
• Confirm that the instance's security group allows inbound traffic on TCP port 22.
• Confirm that the instance subnet's network access control lists (network ACLs) allow inbound traffic on TCP port 22 and outbound traffic on the ephemeral ports.
• Make sure that the instance subnet's route table provides connectivity between the instance and the SSH client.
• Check whether there's a firewall that blocks the connection between the SSH client and the instance.
• Make sure that the instance's TCP Wrappers don't block SSH. For more information, see TCP Wrappers configuration files on the Red Hat website.
  Note: To check for issues with the firewall or TCP Wrappers, you must have OS-level access to the instance.

For more troubleshooting steps, see Error connecting to your instance: Connection timed out.

Troubleshoot issues with instances that pass their status checks

Run the AWSSupport-TroubleshootSSH runbook to automatically resolve issues

To automatically identify and resolve SSH issues, run the AWSSupport-TroubleshootSSH runbook. The runbook installs the EC2Rescue tool on your instance to identify and fix issues that block a remote SSH connection to a Linux host.

Manually troubleshoot OS-level issues

Use the EC2 Serial Console or Session Manager, a capability of AWS Systems Manager, to connect to your instance. Then, troubleshoot SSH configuration issues.

To use the EC2 Serial Console, you must use a supported instance type and configure access to the serial console. Also, make sure that each instance that uses the serial console has at least one password-based Linux user with sudo access. To reset the password for an AWS account with sudo access, run ssm-user. You can also use the EC2 Serial Console to troubleshoot OS-level issues such as boot issues and network configuration issues.

To use Session Manager, your instance must be a managed node and must meet the Session Manager prerequisites. The instance's AWS Systems Manager Agent (SSM Agent) ping status must be Online. Also, the attached AWS Identity and Access Management (IAM) role must have AmazonSSMManagedInstanceCore permissions.

To update your configuration so that it doesn't block SSH access, complete the following steps:

1. Use the EC2 Serial Console to connect to the instance as a password-configured Linux user. Or, use Session Manager to start a session.

2. If you configured iptables rules, then run the following command to add a rule in iptables that accepts all SSH connections on port 22:

   sudo iptables -I INPUT 1 -p tcp --dport 22 -j ACCEPT

3. If you use an OS-based firewall, then deactivate it. It's a best practice to use security groups instead of a firewall. To deactivate your OS-based firewall, run the following commands based on your OS.
   Important: The following commands clear all main iptables rules and delete existing rules. The commands also add a rule that allows inbound SSH connections and change the default policy of the main chain to ACCEPT. With this configuration, you don't affect instance network connectivity when you clear the iptables rule.
   Distributions that use Uncomplicated Firewall (UFW) such as Ubuntu and Debian:

   sudo iptables -F
   sudo iptables -P INPUT ACCEPT
   sudo ufw disable

   Distributions that use firewalld such as Red Hat Enterprise Linux (RHEL) and CentOS:

   sudo iptables -F
   sudo iptables -P INPUT ACCEPT
   sudo systemctl disable firewalld

   Note: After you regain access to your instance, check your firewall configuration.

4. To verify that SSH is running and that TCP port 22 is in the listening state, run the following commands:

   sudo systemctl restart sshd
   sudo ss -tpln | grep -iE '22|ssh'
   LISTEN 0 128 0.0.0.0:22 0.0.0.0:* users:(("sshd",pid=1901,fd=3))LISTEN 0 128 [::]:22 [::]:* users:(("sshd",pid=1901,fd=4))

   Note: If your system doesn't have the ss command, then replace ss with the legacy netstat command. Make sure to use the same syntax as the preceding command.

5. To make sure that the TCP Wrapper doesn't block an SSH connection, run the following command:

   if [[ $( cat /etc/hosts.[ad]* | grep -vE '^#' | awk 'NF' | wc -l) -ne 0 ]];\
   then sudo sed -i '1i sshd2 sshd : ALL: allow' /etc/hosts.allow; fi

6. Use SSH to connect to the instance.

7. Disconnect from the serial console session. Or, end the session in Session Manager.

Use a user data script to troubleshoot your instance

If you can't use the runbook, serial console, or Session Manager to connect to your instance, then use a user data script to troubleshoot issues. In the user data script, deactivate the OS-level firewall and the TCP Wrapper. Then, restart the sshd service.

Configure your instance for a stop and start

Note: When you stop and start an instance, the instance's public IP address changes. It's a best practice to use an Elastic IP address to route external traffic to your instance instead of a public IP address. If you use Amazon Route 53, then you might need to update the Route 53 DNS records when the public IP address changes. A stop and start is different from an instance reboot. For more information, see How EC2 instance stop and start works.

Before you stop and start your instance, take the following actions:

• If your instance uses an instance store, then save the volume data on the instance store to persistent storage. For example, you can save the data to Amazon Elastic Block Store (Amazon EBS) volumes or Amazon Simple Storage Service (Amazon S3) buckets.
  Important: Amazon EC2 deletes instance store data when you stop the instance.
• Create a snapshot of your Amazon EBS volume. If you experience issues, then you can use the snapshot to restore your instance.
• Temporarily remove the instance from its Amazon EC2 Auto Scaling group so that you don't accidentally terminate the instance when you stop it.
  Note: EC2 Auto Scaling might terminate stopped instances in an Auto Scaling group based on your scale-in protection settings. Instances that you launch with Amazon EMR, AWS CloudFormation, or AWS Elastic Beanstalk might be in an Auto Scaling group.
• Set the instance shutdown behavior to Stop to make sure that the instance doesn't terminate when you stop it.

Configure user data for the instance

Complete the following steps:

1. Stop the instance.
2. Choose the instance, and then choose Actions.
3. Select Instance settings.
4. Choose Edit user data, and then enter the following user data script:

   Content-Type: multipart/mixed; boundary="//"
   MIME-Version: 1.0
   
   --//
   Content-Type: text/cloud-config; charset="us-ascii"
   MIME-Version: 1.0
   Content-Transfer-Encoding: 7bit
   Content-Disposition: attachment; filename="cloud-config.txt"
   
   #cloud-config
   cloud_final_modules:
   - [scripts-user, always]
   
   --//
   Content-Type: text/x-shellscript; charset="us-ascii"
   MIME-Version: 1.0
   Content-Transfer-Encoding: 7bit
   Content-Disposition: attachment; filename="userdata.txt"
   
   #!/bin/bash
   iptables -P INPUT ACCEPT
   iptables -F
   systemctl restart sshd.service || service sshd restart
   if [[ $( cat /etc/hosts.[ad]* | grep -vE '^#' | awk 'NF' | wc -l) -ne 0 ]];\
   then sudo sed -i '1i sshd2 sshd : ALL: allow' /etc/hosts.allow; fi
   --//

   Note: The preceding user data script runs at each instance reboot. This method removes all main iptables rules.
5. Choose Save.
6. Use SSH to connect to the instance.
7. Remove the user data script, and then confirm that your firewall configuration is accurate.

Related information

How do I troubleshoot Amazon EC2 instance connection timeout errors from the internet?

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