Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Run Command Walkthrough Using the AWS CLI

The following sample walkthrough shows you how to use the AWS CLI to view information about commands and command parameters, how to execute commands, and how to view the status of those commands.

Important

Only trusted administrators should be allowed to use Systems Manager pre-configured documents shown in this topic. The commands or scripts specified in Systems Manager documents run with administrative privilege on your instances. If a user has permission to execute any of the pre-defined Systems Manager documents (any document that begins with AWS), then that user also has administrator access to the instance. For all other users, you should create restrictive documents and share them with specific users. For more information about restricting access to Run Command, see Configuring Access to Systems Manager.

Step 1: Getting Started

You must either have administrator privileges on the instances you want to configure or you must have been granted the appropriate permission in IAM. Also note, this example uses the us-east-1 region. Run Command is currently available in the following Systems Manager regions. For more information, see Systems Manager Prerequisites.

To execute commands using the AWS CLI

  1. Run the following command to specify your credentials and the region.

    Copy
    aws configure
  2. The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: us-east-1 Default output format [None]: ENTER
  3. List all available documents

    This command lists all of the documents available for your account based on IAM permissions. The command returns a list of Linux and Windows documents.

    Copy
    aws ssm list-documents
  4. Verify that an instance is ready to receive commands

    The output of the following command shows if instances are online.

    Copy
    aws ssm describe-instance-information --output text --query "InstanceInformationList[*]"
  5. Use the following command to view details about a particular instance.

    Note

    To execute the commands in this walkthrough, you must replace the instance and command IDs. The command ID is returned as a response of the send-command. The instance ID is available from the Amazon EC2 console.

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

Step 2: Running Shell Scripts

Using Run Command and the AWS-RunShellScript document, you can execute any command or script on an EC2 instance as if you were logged on locally.

To view the description and available parameters

  • Use the following command to view a description of the Systems Manager JSON document.

    Copy
    aws ssm describe-document --name "AWS-RunShellScript" --query "[Document.Name,Document.Description]"
  • Use the following command to view the available parameters and details about those parameters.

    Copy
    aws ssm describe-document --name "AWS-RunShellScript" --query "Document.Parameters[*]"

Step 3: Send a Command Using the AWS-RunShellScript document - Example 1

Use the following command to get IP information for an instance.

Copy
aws ssm send-command --instance-ids "instance ID" --document-name "AWS-RunShellScript" --comment "IP config" --parameters commands=ifconfig --output text

Get command information with response data

The following command uses the Command ID that was returned from the previous command to get the details and response data of the command execution. The system returns the response data if the command completed. If the command execution shows "Pending" you will need to execute this command again to see the response data.

Copy
aws ssm list-command-invocations --command-id "command ID" --details

Step 4: Send a Command Using the AWS-RunShellScript document - Example 2

The following command displays the default user account running the commands.

Copy
sh_command_id=$(aws ssm send-command --instance-ids "instance ID" --document-name "AWS-RunShellScript" --comment "Demo run shell script on Linux Instance" --parameters commands=whoami --output text --query "Command.CommandId")

Get command status

The following command uses the Command ID to get the status of the command execution on the instance. This example uses the Command ID that was returned in the previous command.

Copy
aws ssm list-commands --command-id $sh_command_id

Get command details

The following command uses the Command ID from the previous command to get the status of the command execution on a per instance basis.

Copy
aws ssm list-command-invocations --command-id $sh_command_id --details

Get command information with response data for a specific instance

The following command returns the output of the original aws ssm send-command for a specific instance.

Copy
aws ssm list-command-invocations --instance-id instance ID --command-id $sh_command_id –-details

Step 5: Additional Examples

The following command returns the version of Python running on an instance.

Copy
sh_command_id=$(aws ssm send-command --instance-ids instance ID --document-name "AWS-RunShellScript" --comment "Demo run shell script on Linux Instances" --parameters commands='python' --version --output text --query "Command.CommandId")

The following command executes a Python script using Run Command.

Copy
aws ssm send-command --instance-ids instance ID --document-name "AWS-RunShellScript" --comment "Demo run shell script on Linux Instances" --parameters '{"commands":["#!/usr/bin/python","print \"Hello world from python\""]}' --output text --query "Command.CommandId"