Menu
Amazon EC2 Systems Manager
User Guide

Troubleshooting Systems Manager Run Command

Use the following information to help troubleshoot problems with Run Command.

Where Are My Instances?

If you do not see the expected list of instances when you choose Select Target instances then verify the following.

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 status of one or more instances

  • The last time the instance sent a heartbeat value

  • The version of the SSM Agent

  • The operating system

  • The version of the EC2Config service (Windows)

  • The status of the EC2Config service (Windows)

Getting Status Information on Windows Instances

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

Copy
Get-SSMInstanceInformation -InstanceInformationFilterList @{Key="InstanceIds";ValueSet="instance-ID","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:

Copy
Get-SSMInstanceInformation -InstanceInformationFilterList @{Key="PingStatus";ValueSet="Online"}

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

Copy
Get-SSMInstanceInformation -InstanceInformationFilterList @{Key="AgentVersion";ValueSet="LATEST"}

Getting Status Information on Linux Instances

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

Copy
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:

Copy
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:

Copy
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.

  • 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 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. The information in these files can help you troubleshoot problems.

On Windows

  • %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log

  • %PROGRAMDATA%\Amazon\SSM\Logs\error.log

On Linux

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

  • /var/log/amazon/ssm/errors.log

On Linux, you can enable extended logging by updating the seelog.xml file. By default, the configuration file is located here: /etc/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.