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 the following.

  • You installed the SSM Agent on your instance. Amazon EC2 Windows Amazon Machine Images (AMIs) are pre-configured with the SSM Agent. Linux AMIs are not. For information about installing the SSM agent on an instance, see Installing the SSM Agent.

  • Your instance is configured with an AWS Identity and Access Management (IAM) role that enables the instance to communicate with the Systems Manager API. Also verify that your user account has an IAM user trust policy that enables your account to communicate with the Systems Manager API. For more information, see Configuring Access to Systems Manager.

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 Configuring Access to Systems Manager.

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.