AWS Systems Manager
User Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Troubleshooting Systems Manager Run Command

Run Command provides status details with each command execution. For more information about the details of command statuses, see Understanding Command Statuses. You can also use the information in this topic to help troubleshoot problems with Run Command.

Where Are My Instances?

In the Run a command page, after you choose an SSM document to run and select Manually selecting instances in the Targets section, a list is displayed of instances you can choose to run the command on. If an instance you expect to see is not listed, check the following requirements:

  • SSM Agent: Make sure the latest version of SSM Agent is installed on the instance. Only Amazon EC2 Windows Amazon Machine Images (AMIs) and some Linux AMIs are pre-configured with SSM Agent. For information about installing or reinstalling SSM Agent on an instance, see Installing and Configuring SSM Agent on Amazon EC2 Linux Instances or Installing and Configuring SSM Agent on Windows Instances.

  • IAM instance role: Verify that the 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 Create an IAM Instance Profile for Systems Manager.

  • Target operating system type: Double-check that you have selected an SSM document that supports the type of instance you want to update. Most SSM documents support both Windows and Linux instances, but some do not. For example, if you select the SSM document AWS-InstallPowerShellModule, which applies only to Windows instances, you will not see Linux instances in the target instances list.

Getting Status Information on Windows Instances

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

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:

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:

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:

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

  • 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 Create an IAM Instance Profile for Systems Manager.

Troubleshooting SSM Agent

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

View SSM Agent Log Files

SSM Agent logs information in the following files. The information in these files can help you troubleshoot problems.

Note

If you choose to view these logs by using Windows File Explorer, be sure to enable the viewing of hidden files and system files in Folder Options.

On Windows

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

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

On Linux

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

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

Enable SSM Agent Debug Logging

Use the follow procedure to enable SSM Agent debug logging on Windows Server and Linux managed instances.

  1. Either use Systems Manager Session Manager to connect to the instance where you want to enable debug logging, or log on to the managed instance. For more information, see Working with Session Manager.

  2. Make a copy of the seelog.xml.template file. Change the name of the copy to seelog.xml. The file is located in the following directory:

    1. Windows Server: %PROGRAMFILES%\Amazon\SSM\seelog.xml.template

    2. Linux: /etc/amazon/ssm/seelog.xml.template

  3. Edit the seelog.xml file to change the default logging behavior. Change the value of minlevel from info to debug, as shown in the following example.

    <seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="debug">
  4. Windows only: Locate the following entry:

    filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\amazon-ssm-agent.log"

    Change this entry to use the following path:

    filename="C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log"
  5. Windows only: Locate the following entry:

    filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\errors.log"

    Change this entry to use the following path:

    filename="C:\ProgramData\Amazon\SSM\Logs\errors.log"
  6. Restart SSM Agent.

    • Windows Server: Use Windows Services Manager to restart the Amazon SSM Agent.

    • Linux: Run the following command:

      sudo restart amazon-ssm-agent