AWS Systems Manager is a management service that enables you to automate tasks across your AWS resources, providing a unified interface for managing your infrastructure. One of the key features of Systems Manager is Run Command, which allows you to remotely execute commands on your EC2 instances and other resources without needing to SSH into them. This knowledge base will explore the features, setup, use cases, best practices, and troubleshooting of AWS Systems Manager Run Command.

Understanding AWS Systems Manager and Run Command

What is an AWS Systems Manager?

AWS Systems Manager provides a suite of tools to help automate operational tasks across AWS services and on-premises environments. It integrates various AWS services and offers capabilities such as:

• Automation: Automate operational tasks like patch management, software deployment, and instance configuration.
• Compliance Management: Check and maintain compliance with organizational policies.
• Resource Grouping: Organize resources into logical groups for easier management.
• Monitoring: Monitor operational metrics and logs to ensure the health of resources.

 What is Run Command?

Run Command is a capability within AWS Systems Manager that enables you to remotely and securely manage the configuration of your managed instances. With Run Command, you can execute scripts, install software, and make configuration changes across multiple instances simultaneously, without needing to log in to each instance.

 Key Features of Run Command

• Remote Execution: Execute commands or scripts on one or multiple managed instances.
• Parameter Store Integration: Use parameters from the AWS Systems Manager Parameter Store to pass values to commands.
• Logging: Capture and store command output in Amazon S3 or CloudWatch Logs for auditing and troubleshooting.
• Command Document: Utilize pre-defined documents (JSON or YAML) to specify commands and their execution parameters.

Setting Up AWS Systems Manager Run Command

Prerequisites

Before using Run Command, ensure that you have:

• An AWS account with appropriate permissions.
• EC2 instances are configured as managed instances (running the SSM agent).
• The required IAM roles and policies for Systems Manager.

Configuring IAM Roles and Policies

1. Create an IAM Role for EC2 Instances:

   • Go to the IAM console and select Roles.
   • Click on Create role.
   • Choose AWS service and select EC2.
   • Attach the policy named AmazonSSMManagedInstanceCore, which provides the necessary permissions for Systems Manager operations.
   • Name your role (e.g., SSM-EC2-Role) and create it.

2. Attach the IAM Role to Your EC2 Instances:

   • Navigate to the EC2 console.
   • Select the instances you want to manage with Systems Manager.
   • Choose Actions → Security → Modify IAM Role.
   • Select the role you just created and apply it to the instances.

3. Create an IAM User for Run Command:

   • Go back to the IAM console and create a new user.
   • Assign policies that allow access to Systems Manager, such as AmazonSSMFullAccess, or create a custom policy with specific permissions (e.g., ssm:SendCommand).

Using AWS Systems Manager Run Command

Executing Commands

To execute commands using Run Command, follow these steps:

1. Navigate to the Systems Manager Console:

   • Log in to the AWS Management Console and search for Systems Manager.

2. Access Run Command:

   • In the Systems Manager dashboard, find and select Run Command under the Instances & Nodes section.

3. Choose Command Document:

   • Click on the Run command.
   • Select a command document. You can use built-in documents like AWS-RunShellScript for Linux instances or AWS-RunPowerShellScript for Windows instances.

4. Configure Command Parameters:

   • Specify the command parameters. For example, if using, enter the shell commands you want to run.

5. Select Targets:

   • Choose the instances on which to run the command. You can target specific instances by instance IDs, tags, or resource groups.

6. Specify Output Options:

   • Optionally, specify the output options:
     • CloudWatch Logs: Choose to send logs to CloudWatch Logs.
     • S3 Bucket: Specify an S3 bucket to store command output.

7. Run the Command:

   • Review your configurations and click the Run button to execute the command.

Viewing Command Output

1. Access Command History:

   • Go back to the Run Command page in the Systems Manager console.
   • You can view a history of commands executed, along with their status.

2. Check Command Details:

   • Click on a specific command ID to see details, including the command output and any error messages.

3. Review Logs:

   • If you configured logging to CloudWatch or S3, you can access the logs for detailed information on the command execution.

Use Cases to Run Command

 Batch Software Installation

You can use Run Command to remotely install software on multiple instances simultaneously, ensuring consistency across your infrastructure. For example, you can run a shell script that installs necessary packages on all EC2 instances in a particular environment.

Configuration Management

Run Command allows you to manage and update configurations on your instances. You can execute scripts that modify configuration files or apply system settings without logging into each instance individually.

System Updates and Patching

Regularly applying patches and updates is critical for maintaining security. With Run Command, you can schedule commands to update software and operating systems across your managed instances efficiently.

Troubleshooting and Diagnostics

Run Command can be invaluable for troubleshooting issues across your EC2 instances. You can quickly execute diagnostic commands to gather system information, check service statuses, or retrieve log files for analysis.

 Environment Provisioning

When provisioning new environments, you can use Run Command to execute initialization scripts that configure instances based on specific requirements. This helps automate the setup process for development, testing, and production environments.

Best Practices for Using Run Command

 Use Parameter Store for Secure Configuration

Integrate AWS Systems Manager Parameter Store to manage sensitive data, such as API keys and passwords, securely. You can reference these parameters in your Run Command scripts without hardcoding sensitive information.

Limit Command Execution Scope

To minimize risk, limit command execution to only those instances that require the changes. Use tags or resource groups to specify which instances to target, reducing the potential impact of mistakes.

Monitor Command Execution

Regularly monitor command execution and outcomes to ensure that tasks are completed successfully. Use AWS CloudWatch to create alarms that alert you to failures or long-running commands.

Implement IAM Best Practices

Follow the principle of least privilege when configuring IAM roles and policies for users and instances. Ensure that only authorized users can execute commands through Run Command.

Regularly Review Logs

Periodically review command execution logs stored in CloudWatch or S3 to audit activities and identify any unauthorized changes or issues.

 Troubleshooting Common Issues

 Command Fails to Execute

If a command fails to execute:

• Check IAM Permissions: Ensure that the IAM role associated with the EC2 instances has the correct permissions to perform the actions specified in the command.
• Review Command Syntax: Verify that the command syntax and parameters are correct.

Slow Command Execution

If command execution is slow:

• Check Instance Performance: Monitor the CPU and memory usage of the instances to ensure they are not overloaded.
• Optimize Command Logic: Review the logic of your commands or scripts to identify any inefficiencies.

Missing Command Output

If you do not see the command output:

• Verify Output Configuration: Ensure you configured the output options correctly (e.g., CloudWatch Logs or S3).
• Check Execution Role Permissions: Confirm that the execution role has permission to write logs to CloudWatch or S3.

SSM Agent Issues

If you encounter problems with the SSM agent:

• Check Agent Status: Ensure that the SSM agent is running on your instances.
• Review Agent Logs: Look into the SSM agent logs for error messages that can help identify the problem. The logs are typically located  /var/log/amazon/ssm/amazon-ssm-agent.log on Linux and C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log Windows.

Advanced Features of Run Command

Document Management

You can create custom command documents that define your own commands and execution parameters. Custom documents enable reusable command configurations for consistent management tasks.