I'm receiving errors when trying to connect to my EC2 instance using SSH. How can I use the AWSSupport-TroubleshootSSH automation workflow to troubleshoot SSH connection issues?

Last updated: 2020-03-19

When I log in to my Amazon Elastic Compute Cloud (Amazon EC2) instance over SSH with verbose messaging on I receive errors, such as "Permission denied" or "Connection refused". How can I use the AWSSupport-TroubleshootSSH automation document to troubleshoot SSH connection issues?

Short Description

AWSSupport-TroubleshootSSH installs the Amazon EC2Rescue tool and then checks for and corrects some issues that cause remote connection errors when connecting to a Linux machine through SSH. Run the AWSSupport-TroubleshootSSH automation to automatically repair issues by subnet, S3 buckets, or IAM role.

System requirements to use EC2Rescue for Linux

EC2Rescue for Linux requires an Amazon EC2 Linux instance that meets the following prerequisites:

Supported operating systems

  • Amazon Linux 2
  • Amazon Linux 2016.09+
  • SLES 12+
  • RHEL 7+
  • Ubuntu 16.04+

Software requirements

  • Python 2.7.9+ or 3.2+

Note: To learn more about verbose messaging or troubleshooting other types of error messages, see How do I troubleshoot problems connecting to my Amazon EC2 Linux instance using SSH?

Resolution

Before you begin:

  • Copy the instance ID of the Amazon EC2 instance you want to troubleshoot. You need the instance ID to run the automation document.
  • (Optional) Copy the ID of a subnet in the same Availability Zone as your unreachable Amazon EC2 instance. The EC2Rescue instance installs in this subnet. If you don’t specify a subnet, then the automation document creates a new temporary VPC in your AWS account. Verify that your AWS account has at least one available VPC. By default, you can create five VPCs in a Region. If you've already created five VPCs in the Region, the automation fails without changing your Amazon EC2 instance. For more information, see VPC and Subnets.
  • (Optional) Create and specify an AWS Identity and Access Management (IAM) role for automation. If you don't specify this role, AWS Systems Manager Automation uses the permissions of the user who executes this document. For more information about creating roles for automation, see Running an Automation Workflow by Using an IAM Service Role.

Run the AWSSupport-TroubleshootSSH automation from the AWS Systems Manager console

  1. Open the AWS Systems Manager console.
  2. In the navigation pane, choose Automation.
    Note: If the AWS Systems Manager home page opens first, choose the menu icon to open the navigation pane, and then choose Automation.
  3. Choose Execute automation.
  4. Enter AWSSupport-TroubleshootSSH in the search field, and then press Enter.
  5. Select AWSSupport-TroubleshootSSH in the search results.
  6. In the documents list, choose AWSSupport-TroubleshootSSH. The document owner is Amazon.
  7. In the Description section, verify that Document version is set to Default version at runtime.
  8. Choose Next.
  9. In the Execute automation document section, choose Simple execution.
  10. In the Input parameters section, specify the following parameters:
    For InstanceID, specify the ID of the unreachable instance. For Action, select FixAll.
    For AllowOffline, select True.
    (Optional) For SubnetId, specify a subnet in an existing VPC in the same Availability Zone as the Amazon EC2 instance that you specified. By default, Systems Manager creates a new VPC, but you can specify a subnet in an existing VPC.
    (Optional) For S3BucketName, enter the name of a bucket that you have write permissions to. The troubleshooting logs are uploaded to this bucket, if provided.
    (Optional) For AutomationAssumeRole, specify the IAM role for this execution. If no role is specified, AWS Systems Manager Automation uses the permissions of the user who executes this document.
  11. Choose Execute.
  12. To monitor the execution progress, choose the running Automation, and then choose the Steps tab. When the execution is finished, choose the Descriptions tab, and then choose View output to view the results. To view the output of individual steps, choose the Steps tab, and then choose View Outputs beside a step.

Run the AWSSupport-TroubleshootSSH automation from the AWS Command Line Interface (AWS CLI)

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootSSH" --document-version "\$DEFAULT" --parameters '{"InstanceId":["i-0a241ed9caf16f01e"],"Action":["FixAll"],"AllowOffline":["True"],"SubnetId":["SelectedInstanceSubnet"]}' --region us-east-1

For more information about the AWSSupport-TroubleshootSSH Automation, see Smart RDP and SSH remediation with AWS Systems Manager Automation API actions.


Did this article help you?

Anything we could improve?


Need more help?