Menu
Sign In to the Console
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Troubleshooting Amazon EC2 Run Command

Use the following information to help troubleshoot problems with Run Command. For information about troubleshooting Run Command for Windows, see Troubleshooting Run Command in the User Guide for Windows.

Where Are My Instances?

If you do not see the expected list of instances when you choose Select Target instances then verify that your instance is configured with an AWS Identity and Access Management (IAM) role that enables the instance to communicate with the SSM API. Also verify that your user account has an IAM user trust policy that enables your account to communicate with the SSM API. The following procedures describe how to configure the instance role and the user trust policy.

Note

You must assign the IAM instance role when you create a new instance. You can't assign a role to an instance that is already running. To configure an existing instance to use an SSM-supported role, you must create an image of the instance, launch an instance from that image, and assign the IAM role as you launch the instance. For more information, see Creating an Amazon EBS-Backed Linux AMI.

To create an instance that uses an SSM-supported role

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. Select a supported region.

  3. Choose Launch Instance and select a Linux instance.

  4. Choose your instance type and then choose Next: Configure Instance Details.

  5. Beside IAM role choose Create new IAM role. The IAM console opens in a new tab.

    1. Choose Create New Role.

    2. In Step 1: Set Role Name, enter a name that identifies this role as a Run Command role.

    3. In Step 2: Select Role Type, choose Amazon EC2 Role for Simple Systems Manager. The system skips Step 3: Establish Trust because this is a managed policy.

    4. In Step 4: Attach Policy, choose AmazonEC2RoleforSSM.

    5. Choose Next Step, and then choose Create Role.

    6. Close the tab with the IAM console.

  6. In the EC2 Management Console, choose the Refresh button beside Create New IAM role.

  7. In the IAM role drop-down list, choose the role you just created.

  8. Complete the wizard to create and launch the new instance.

Grant Your User Account Access to SSM

Use the following procedure to attach an the AmazonSSMFullAccess IAM policy to your user account. This policy grants you full access to SSM API actions.

To create an IAM policy for EC2 instances

  1. Open the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)

  3. In the Filter field, type AmazonSSMFullAccess and press Enter.

  4. Select the checkbox next to AmazonSSMFullAccess and then choose Policy Actions, Attach.

    Attaching the IAM policy

  5. On the Attach Policy page, choose your user account and then choose Attach Policy.

After you attach the policy, see if your instances are visible in the Select Target instances section of the EC2 console. If they are not visible, then one or more of the prerequisites have not been met. For more information, see Amazon EC2 Run Command Prerequisites.

Check Instance Status Using the Health API

You can use the Amazon EC2 Health API to quickly determine the following information about Amazon EC2 instances:

  • The version of the SSM agent

  • The status of one or more instances

  • The operating system

  • The status of the SSM agent

  • The last time the instance sent a heartbeat value

Use the following command to get status details about one or more instances:

aws ssm describe-instance-information --instance-information-filter-list key=InstanceIds,valueSet=instance-ID

Use the following command with no filters to see all instances registered to your account that are currently reporting an online status. Substitute the ValueSet="Online" with "ConnectionLost" or "Inactive" to view those statuses:

aws ssm describe-instance-information --instance-information-filter-list key=PingStatus,valueSet=Online

Use the following command to see which instances are running the latest version of the SSM agent. Substitute ValueSet="LATEST" with a specific version (for example, 1.0.145 or 1.0) to view those details:

aws ssm describe-instance-information --instance-information-filter-list key=AgentVersion,valueSet=LATEST

If the describe-instance-information API operation returns an AgentStatus of Online, then your instance is ready to be managed using Run Command. If the status is Inactive, the instance has one or more of the following problems.

  • The SSM agent is not installed. For more information, see Installing the SSM Agent.

  • The instance does not have outbound internet connectivity.

  • The instance was not launched with an IAM role that enables it to communicate with the SSM API, or the permissions for the IAM role are not correct for Run Command. For more information, see Delegating Access to Amazon EC2 Run Command.

Troubleshooting the Amazon SSM Agent

If you experience problems executing commands using Run Command, there might be a problem with the SSM agent. Use the following information to help you troubleshoot the agent.

View Agent Logs

The SSM agent logs information in the following files using cihub/seelog. The information in these files can help you troubleshoot problems.

  • /var/log/amazon/ssm/amazon-ssm-agent.log

  • /var/log/amazon/ssm/error.log

You can enable extended logging by updating the seelog.xml file. By default, the configuration file is located here: /opt/amazon/ssm/seelog.xml.

For more information about cihub/seelog configuration, go to the cihub/seelog Wiki. For examples of cihub/seelog configurations, go to cihub/seelog examples.