Menu
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Tutorial: Remotely Manage Your Amazon EC2 Instances

This tutorial shows you how to remotely manage an Amazon EC2 instance using Amazon Elastic Compute Cloud (Amazon EC2) Run Command from your local machine. In this tutorial, you will learn how to do the following tasks:

  • Launch a new instance that is configured for Run Command.

  • Configure your user account for Run Command.

  • Use Run Command to send a command from your local machine and retrieve a list of services running on the instance.

This tutorial includes procedures for executing commands using either the Amazon EC2 console or AWS Command Line Interface.

Note

With Run Command, you can also manage your servers and virtual machines (VMs) in your on-premises environment or in an environment provided by other cloud providers. For more information, see Setting Up Systems Manager in Hybrid Environments.

Launch a New Instance

Instances require an AWS Identity and Access Management (IAM) role that enables the instance to communicate with Amazon EC2 Systems Manager (SSM). You can assign the IAM role when you create the new instance.

To create an instance that uses an SSM-supported role

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

  2. Select a supported region.

  3. Choose Launch Instance and select a Linux Amazon Machine Image (AMI).

  4. Choose your instance type and then choose Next: Configure Instance Details.

  5. In Auto-assign Public IP, choose Enable.

  6. Beside IAM role choose Create new IAM role. The IAM console opens in a new tab.

    1. Choose Create New Role.

    2. In Step 1: Set Role Name, enter a name that identifies this role as a Run Command role.

    3. In Step 2: Select Role Type, choose Amazon EC2 Role for Simple Systems Manager. The system skips Step 3: Establish Trust because this is a managed policy.

    4. In Step 4: Attach Policy, choose AmazonEC2RoleforSSM.

    5. Choose Next Step, and then choose Create Role.

    6. Close the tab with the IAM console.

  7. In the Amazon EC2 console, choose the Refresh button beside Create New IAM role.

  8. From IAM role, choose the role you just created.

  9. Complete the wizard to launch the new instance. Make a note of the instance ID. You will need to specify this ID later in this tutorial.

Important

You must install the SSM Agent on the instance you just created. For more information, see Installing the SSM Agent.

Grant Your User Account Access to SSM

Your user account must be configured to communicate with the SSM API. Use the following procedure to attach a managed IAM policy to your user account that grants you full access to SSM API actions.

To create the IAM policy for your user account

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)

  3. In the Filter field, type AmazonSSMFullAccess and press Enter.

  4. Select the check box next to AmazonSSMFullAccess and then choose Policy Actions, Attach.

  5. On the Attach Policy page, choose your user account and then choose Attach Policy.

Install the SSM Agent

The SSM agent processes Run Command requests and configures the instances that are specified in the request. You must manually install the agent using the procedure for your version of Linux. The following procedure describes how to install the agent on Red Hat Enterprise Linux (RHEL). For information about how to install the agent on Ubuntu, Amazon Linux or CentOS, see Installing the SSM Agent.

To install the SSM agent on Red Hat Enterprise Linux

  1. Connect to your RHEL instance and create a temporary directory on the instance.

    mkdir /tmp/ssm
  2. Use one of the following commands to download the SSM installer to the temporary directory. Replace region with one of the AWS Regions where SSM is available. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance.

    64-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

    32-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/linux_386/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
  3. Run the SSM installer.

    sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
  4. Run one of the following commands to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."

    RHEL 7.x

    sudo systemctl status amazon-ssm-agent

    RHEL 6.x

    sudo status amazon-ssm-agent
  5. Execute the following commands if the previous command returned "amazon-ssm-agent is stopped."

    1. Start the service.

      RHEL 7.x

      sudo systemctl start amazon-ssm-agent

      RHEL 6.x

      sudo start amazon-ssm-agent
    2. Check the status of the agent.

      RHEL 7.x

      sudo systemctl status amazon-ssm-agent

      RHEL 6.x

      sudo status amazon-ssm-agent

Send a Command Using the EC2 Console

Use the following procedure to list all services running on the instance by using Run Command from the Amazon EC2 console.

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

  2. In the navigation pane, choose Run Command.

  3. Choose Run a command.

  4. For Command document, choose AWS-RunShellScript.

  5. Choose Select instances, and then choose the instance you just created. If you do not see the instance, verify that you are currently in the same region as the instance you created. Also verify that you configured the IAM role and trust policies correctly as described earlier in this topic.

  6. For Commands, type service --status-all. You can specify a Working Directory and Execution Timeout, if you want. The Execution Timeout is the number of seconds the SSM agent will attempt to run the command before it is considered to have failed. We recommend entering a comment in the Comments field. A comment will help you identify the command in the list of pending commands and make it easier to view the output.

  7. In the Timeout (seconds) field, type the number of seconds Run Command should attempt to reach instances before an instance is considered unreachable and the command execution fails.

  8. Choose Run to execute the command simultaneously on the selected instances. Run Command displays a status screen.

  9. Choose View result.

  10. Choose the command invocation for the command you just ran.

  11. Choose the Output tab, and then choose View Output.

    List of commands executed using Run Command
  12. The system displays the output in your browser. If the output is longer than 2500 characters, only the first 2500 characters are shown and the rest is truncated. You could view the full output by specifying an Amazon S3 bucket before executing the command.

Send a Command Using the AWS CLI

Use the following procedure to list all services running on the instance by using Run Command in the AWS CLI.

To execute a command

  1. On your local computer, download the latest version of the AWS Command Line Interface (AWS CLI).

  2. Open the AWS CLI on your local computer and execute the following command to specify your credentials and the region.

    aws configure
  3. The system prompts you to specify the following.

    AWS Access Key ID [None]: key
    AWS Secret Access Key [None]: key
    Default region name [None]: region, for example us-east-1
    Default output format [None]: ENTER
  4. Execute the following command to retrieve the services running on the instance.

    aws ssm send-command --document-name "AWS-RunShellScript" --comment "listing services" --instance-ids "Instance-ID" --parameters commands="service --status-all" --region us-west-2 --output text

    The command returns a command ID, which you will use to view the results.

  5. The following command returns the output of the original Send-SSMCommand. The output is truncated after 2500 characters. To view the full list of services, you would need to specify an Amazon S3 bucket in the command using the --output-s3-bucket-name bucket_name parameter.

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

For more examples of how to execute commands using Run Command with the AWS CLI and the AWS Management Console, see Executing a Command Using Amazon EC2 Run Command. For more information about Run Command, see Remote Management (Run Command).