Tutorial: Remotely Manage Your Amazon EC2 Instances

This tutorial shows you how to remotely manage an Amazon EC2 instance using Systems Manager Run Command from your local machine. This tutorial includes procedures for executing commands using the Amazon EC2 console, AWS Tools for Windows PowerShell, and the 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.

Before you Begin

You must configure an AWS Identity and Access Management (IAM) instance profile role for Systems Manager. Attach the AmazonEC2RoleforSSM role to an Amazon EC2 instance. This role enables the instance to communicate with the Systems Manager API. For more information about how to attach the role to an existing instance, see Attaching an IAM Role to an Instance.

You must also configure your IAM user account for Systems Manager, as described in the next section.

Grant Your User Account Access to Systems Manager

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

To create the IAM policy for your user account

Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)
In the Filter field, type AmazonSSMFullAccess and press Enter.
Select the check box next to AmazonSSMFullAccess and then choose Policy Actions, Attach.
On the Attach Policy page, choose your user account and then choose Attach Policy.

Install the SSM Agent (Linux)

The SSM agent processes Run Command requests and configures the instances that are specified in the request. The agent is installed, by default, on Windows instance. However, you must manually install the agent on 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 SSM Agent On Linux.

To install the SSM agent on Red Hat Enterprise Linux

Connect to your RHEL instance and create a temporary directory on the instance.
```
Copy
mkdir /tmp/ssm
```

Use one of the following commands to download the SSM installer to the temporary directory.

64-Bit

Copy
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

32-Bit

Copy
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

Run the SSM installer.

Copy
sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm

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
```
Copy
sudo systemctl status amazon-ssm-agent
```
RHEL 6.x
```
Copy
sudo status amazon-ssm-agent
```
Execute the following commands if the previous command returned "amazon-ssm-agent is stopped."
1. Start the service.
  
  RHEL 7.x
```
Copy
sudo systemctl start amazon-ssm-agent
```
  RHEL 6.x
```
Copy
sudo start amazon-ssm-agent
```
2. Check the status of the agent.
  
  RHEL 7.x
```
Copy
sudo systemctl status amazon-ssm-agent
```
  RHEL 6.x
```
Copy
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.

To execute a command using Run Command from the console

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
In the navigation pane, choose Run Command.
Choose Run a command.
For Command document, choose AWS-RunPowerShellScript for Windows instances, and AWS-RunShellScript for Linux instances.
For Target instances, choose the instance you created. If you don't 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 as described earlier.
For Commands, type Get-Service for Windows, or ps -aux | less for Linux.
(Optional) For Working Directory, specify a path to the folder on your EC2 instances where you want to run the command.
(Optional) For Execution Timeout, specify the number of seconds the EC2Config service or SSM agent will attempt to run the command before it times out and fails.
For Comment, we recommend providing information that will help you identify this command in your list of commands.
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.
Choose Run to execute the command. Run Command displays a status screen. Choose View result.
To view the output, choose the command invocation for the command, choose the Output tab, and then choose View Output.

For more examples of how to execute commands using Run Command, see Executing Commands Using Systems Manager Run Command.

Send a Command Using AWS Tools for Windows PowerShell

Use the following procedure to list all services running on the instance by using Run Command from AWS Tools for Windows PowerShell.

To execute a command

On your local computer, download the latest version of AWS Tools for Windows PowerShell.
Open AWS Tools for Windows PowerShell on your local computer and execute the following command to specify your credentials.
```
Copy
Set-AWSCredentials –AccessKey key –SecretKey key
```
Execute the following command to set the region for your PowerShell session. Specify the region where you created the instance in the previous procedure. This example uses the us-west-2 region.
```
Copy
Set-DefaultAWSRegion -Region us-west-2
```
Execute the following command to retrieve the services running on the instance.
```
Copy
Send-SSMCommand -InstanceId 'Instance-ID' -DocumentName AWS-RunPowerShellScript -Comment 'listing services on the instance' -Parameter @{'commands'=@('Get-Service')}
```
The command returns a command ID, which you will use to view the results.
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, specify an Amazon S3 bucket in the command using the -OutputS3BucketName bucket_name parameter.
```
Copy
Get-SSMCommandInvocation -CommandId Command-ID -Details $true | select -ExpandProperty CommandPlugins
```

For more examples of how to execute commands using Run Command with Tools for Windows PowerShell, see Systems Manager Run Command Walkthough Using the AWS Tools for Windows PowerShell.

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.