Walkthrough: Use the AWS CLI with Run Command
The following sample walkthrough shows you how to use the AWS CLI to view information about commands and command parameters, how to run commands, and how to view the status of those commands.
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 run 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 Create non-Admin IAM users and groups for Systems Manager.
Topics
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 (Ohio) Region (us-east-2). Run Command is currently available in the AWS Regions listed in Systems Manager service endpoints in the Amazon Web Services General Reference. For more information, see Systems Manager prerequisites.
To run commands using the AWS CLI
-
Install and configure the AWS CLI, if you have not already.
For information, see Install or upgrade AWS command line tools.
-
List all available documents.
This command lists all of the documents available for your account based on IAM permissions.
aws ssm list-documents
-
Verify that an instance is ready to receive commands.
The output of the following command shows if instances are online.
-
Use the following command to view details about a particular instance.
Note To run the commands in this walkthrough, you must replace the instance and command IDs. The command ID is returned as a response to send-command. The instance ID is available from the Amazon EC2 console.
Step 2: Run shell scripts to view resource details
Using Run Command and the AWS-RunShellScript document, you can run any command or script on an EC2 instance as if you were logged on locally.
View the description and available parameters
Use the following command to view a description of the Systems Manager JSON document.
Use the following command to view the available parameters and details about those parameters.
Step 3: Send simple commands using the AWS-RunShellScript document
Use the following command to get IP information for an instance.
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"
or
"InProgress"
you run this command again to see the response
data.
Identify user account
The following command displays the default user account running the commands.
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.
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.
Get command information with response data for a specific instance
The following command returns the output of the original aws ssm
send-command
request for a specific instance.
Display Python version
The following command returns the version of Python running on an instance.
Step 4: Run a simple Python script using Run Command
The following command runs a simple Python "Hello World" script using Run Command.
Step 5: Run a Bash script using Run Command
The examples in this section demonstrate how to run the following bash script using Run Command.
For examples of using Run Command to run scripts stored in remote locations, see Running scripts from Amazon S3 and Running scripts from GitHub.
#!/bin/bash yum -y update yum install -y ruby cd /home/ec2-user curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install chmod +x ./install ./install auto
This script installs the AWS CodeDeploy agent on Amazon Linux and Red Hat Enterprise Linux (RHEL) instances, as described in Create an Amazon EC2 instance for CodeDeploy in the AWS CodeDeploy User Guide.
The script installs the CodeDeploy agent from an AWS managed Amazon S3 bucket in the
US East (Ohio) Region (us-east-2),
aws-codedeploy-us-east-2
.
Run a bash script in an AWS CLI command
The following sample demonstrates how to include the bash script in a CLI
command using the --parameters
option.
Run a bash script in a JSON file
In the following example, the content of the bash script is stored in a JSON
file, and the file is included in the command using the
--cli-input-json
option.
The command:
The contents of the referenced
installCodeDeployAgent.json
file:
{ "Parameters": { "commands": [ "#!/bin/bash", "yum -y update", "yum install -y ruby", "cd /home/ec2-user", "curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install", "chmod +x ./install", "./install auto" ] } }