Menu
AWS Systems Manager
User Guide

Executing Commands from the EC2 Console

You can use Run Command from the Amazon EC2 console to configure instances without having to login to each instance. This topic includes an example that shows how to update the SSM Agent on an instance by using Run Command.

Before You Begin

Before you send a command using Run Command, verify that your instances meet Systems Manager requirements.

The following procedure describes how to execute a command from the EC2 console.

Note

The following procedure describes steps that you perform in the Amazon EC2 console. You can also perform these steps in the new AWS Systems Manager console. The steps in the new console will differ from the steps below.

To send a command using Run Command

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, expand Systems Manager Services, and then choose Run Command.

  3. Choose Run a command.

  4. In the Command document section, choose a document.

  5. In the Select Targets by section, choose Manually Selecting Instances to chose individual instances. Or choose Specifying a Tag, choose a group of instances by specifying one or more Amazon EC2 tags.

  6. In the Execute on field, choose either Targets or Percent in the list. If you choose Targets, then you can specify the exact number of instances that should be allowed to run the command at one time, for example, 10. If you choose Percent, then you can choose a percentage of the instances that should be allowed to run the command at one time, for example 30. Percent is a helpful option when targeting EC2 tags and you are not certain of the total number of instances that will run the command.

    This feature allows you to limit the number of instances running the command at one time to avoid impacting instance performance and availability. For more information, see Sending Commands to a Fleet.

  7. In the Stop after __ errors field, specify the maximum number of errors allowed before the system stops sending the command to additional instances. For example, if you specify 1, then the systems stops sending the command to additional instances when the system receives the second error.

    Instances that are already running a command when this value is reached are allowed to complete, but some of these executions may fail as well. For more information, see Sending Commands to a Fleet.

  8. In the next section, specify the parameters or options for your SSM document. Parameters and options are different for each document.

  9. For Comment, we recommend providing information to will help you identify this command in your list of commands.

  10. For Timeout (seconds), type the number of seconds that Run Command should attempt to reach an instance before it is considered unreachable and the command execution fails. The minimum is 30 seconds, the maximum is 30 days, and the default is 10 minutes.

  11. (Optional) Choose Write output to an S3 bucket if you want to write the command output to an Amazon S3 bucket. If you chose this option, specify the S3 bucket and, optionally, an S3 key prefix. An S3 key prefix is a subfolder in the S3 bucket. A subfolder can help you organize Run Command output if you execute multiple commands against multiple instances.

    Important

    The Run Command Output page in the Amazon EC2 console truncates output after 2500 characters. Configure an Amazon S3 bucket before executing commands using Run Command. If your command output was longer than 2500 characters, you can view the full output in your Amazon S3 bucket. For more information, see Create a Bucket.

  12. (Optional) Choose Enable SNS notifications if you want to receive notifications about the status of the commands you execute with Run Command. For more information, see Configuring Amazon SNS Notifications for Run Command.

    Note

    After you specify parameters and options for your SSM document, expand the AWS Command Line Interface command section. This section includes a reusable command for different command-line platforms.

  13. Choose Run, and then choose View results.

  14. In the commands list, choose the command you just executed. If the command is still in progress, choose the refresh icon in the top right corner of the console.

  15. When the Status column shows Success or Failed, choose the Output tab.

  16. Choose View Output. The command output page shows the results of your command execution.

For information about canceling a command, see Canceling a Command.

Example: Update the SSM Agent

You can use the AWS-UpdateSSMAgent document to update the Amazon EC2 SSM Agent running on your Windows and Linux instances. You can update to either the latest version or downgrade to an older version. When you execute the command, the system downloads the version from AWS, installs it, and then uninstalls the version that existed before the command was run. If an error occurs during this process, the system rolls back to the version on the server before the command was run and the command status shows that the command failed.

Note

The following procedure describes steps that you perform in the Amazon EC2 console. You can also perform these steps in the new AWS Systems Manager console. The steps in the new console will differ from the steps below.

To update the SSM Agent using Run Command

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane under Systems Manager Services, choose Run Command.

  3. Choose Run a command.

  4. For Command document, choose AWS-UpdateSSMAgent.

  5. In the Select Targets by section, choose Manually Selecting Instances to chose individual instances. Or choose Specifying a Tag to choose a group of instances by specifying one or more Amazon EC2 tags.

  6. In the Execute on field, choose either Targets or Percent in the list. If you choose Targets, then you can specify the exact number of instances that should be allowed to run the command at one time, for example, 10. If you choose Percent, then you can choose a percentage of the instances that should be allowed to run the command at one time, for example 30. Percent is a helpful option when targeting EC2 tags and you are not certain of the total number of instances that will run the command.

    This feature allows you to limit the number of instances running the command at one time to avoid impacting instance performance and availability. For more information, see Sending Commands to a Fleet.

  7. In the Stop after __ errors field, specify the maximum number of errors allowed before the system stops sending the command to additional instances. For example, if you specify 1, then the systems stops sending the command to additional instances when the system receives the second error. For more information, see Sending Commands to a Fleet.

  8. (Optional) For Version, type the version of the SSM Agent to install. You can install older versions of the agent. If you do not specify a version, the service installs the latest version.

  9. (Optional) For Allow Downgrade, choose true to install an earlier version of the SSM agent. If you choose this option, you must specify the earlier version number. Choose false to install only the newest version of the service.

  10. For Comment, we recommend providing information that will help you identify this command in your list of commands.

  11. For Timeout (seconds), type the number of seconds that Run Command should attempt to reach an instance before it is considered unreachable and the command execution fails. The minimum is 30 seconds, the maximum is 30 days, and the default is 10 minutes.

  12. (Optional) Choose Write output to an S3 bucket if you want to write the command output to an Amazon S3 bucket. If you chose this option, specify the S3 bucket and, optionally, an S3 key prefix. An S3 key prefix is a subfolder in the S3 bucket. A subfolder can help you organize Run Command output if you execute multiple commands against multiple instances.

    Important

    The Run Command Output page in the Amazon EC2 console truncates output after 2500 characters. Configure an Amazon S3 bucket before executing commands using Run Command. If your command output was longer than 2500 characters, you can view the full output in your Amazon S3 bucket. For more information, see Create a Bucket.

  13. (Optional) Choose Enable SNS notifications if you want to receive notifications about the status of the commands you execute with Run Command. For more information, see Configuring Amazon SNS Notifications for Run Command.

    Note

    After you specify parameters and options for your SSM document, expand the AWS Command Line Interface command section. This section includes a reusable command for different command-line platforms.

  14. Choose Run, and then choose View results.

  15. In the commands list, choose the command you just executed. If the command is still in progress, choose the refresh icon in the top right corner of the console.

  16. When the Status column shows Success or Failed, choose the Output tab.

  17. Choose View Output. The command output page shows the results of your command execution.