What is Simple Systems Manager
Amazon EC2 Simple Systems Manager (SSM) is an Amazon Web Services tool that allows us to automatically configure virtual servers in a cloud or in on-premises data center.
We can use scripts, commands or the Elastic Compute Cloud (EC2) console to manage EC2 instances, virtual machines (VMs) or servers hosted on other clouds, or within local environments such as Windows.
Granting user account access to Systems Manager
Our user account must be configured to communicate with the SSM API.
We need to use the following the procedure to attach a managed AWS Identity and Access Management (IAM) policy to our user account that grants us full access to SSM API actions.
To create the IAM policy for our user account:
- Open the IAM console at https://console.aws.amazon.com/iam/.
- In the navigation pane, choose Policies.
- 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 the user account and then choose Attach Policy.
AWS Identity and Access Management (IAM)
We must configure an AWS Identity and Access Management (IAM) instance profile role for Systems Manager.
The AmazonEC2RoleforSSM role should be attached to an Amazon EC2 instance. Let’s create it first:
Attach the role while the instance is being created:
This role enables the instance to communicate with the Systems Manager API.
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, we must manually install the agent on Linux. The following procedure describes how to install the agent on Ubuntu:
$ cd /tmp $ wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb $ sudo dpkg -i amazon-ssm-agent.deb $ sudo systemctl enable amazon-ssm-agent
We can use User data instead:
#!/bin/bash cd /tmp wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb sudo dpkg -i amazon-ssm-agent.deb sudo start amazon-ssm-agent
We can check if the agent is running on the instance:
$ ps -ef|grep agent | grep -v grep root 1723 1 0 01:13 ? 00:00:00 /usr/bin/amazon-ssm-agent
SSM Agent Installation
- Access the EC2 instance you have created with the SSH key for the one time SSM agent configuration.
- Execute the commands below after you login(sudo) as root.
# mkdir /tmp/ssm
# cd /tmp/ssm
# yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm
# systemctl enable amazon-ssm-agent
# systemctl start amazon-ssm-agent
Make sure that SSM agent version is 2.3.630 or above.
[root@ip-172-31-28-88 tmp]# rpm -qa | grep ssm
amazon-ssm-agent-2.3.634.0-1.x86_64
[root@ip-172-31-28-88 tmp]#
Sending a Command Using the EC2 Console
We can use the following steps 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 EC2 console:
- 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 we created. If we don’t see the instance, verify that we are currently in the same region as the instance we created. Also verify that we 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 our EC2 instances where we 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, providing information is recommended so that it will help us identify this command in our 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.
- Then choose View Output.
Sending a Command via AWS CLI
We must either have administrator privileges on the instances we want to configure or we must have been granted the appropriate permission in IAM.
The following command returns a list of Linux and Windows documents:
$ aws ssm list-documents DOCUMENTIDENTIFIERS Command 1 AWS-ApplyPatchBaseline Amazon 1.2 PLATFORMTYPES Windows PLATFORMTYPES Linux DOCUMENTIDENTIFIERS Command 1 AWS-ConfigureAWSPackage Amazon 2.0 PLATFORMTYPES Windows PLATFORMTYPES Linux ...
To check if an instance is ready to receive commands:
$ aws ssm describe-instance-information --output text --query "InstanceInformationList[*]" 2.0.796.0 ip-172-31-38-206 172.31.38.206 i-0698042a954420857 True 1496457091.34 Online Ubuntu Linux 16.04 EC2Instance
Using Run Command and the AWS-RunShellScript document, we can execute any command or script on an EC2 instance as if we were logged on locally.
To view the description and available parameters, we can use the following command to view a description of the Systems Manager JSON document:
$ aws ssm describe-document --name "AWS-RunShellScript" --query "[Document.Name,Document.Description]" AWS-RunShellScript Run a shell script or specify the commands to run.
We can use the following command to view the available parameters and details about those parameters:
$ aws ssm describe-document --name "AWS-RunShellScript" --query "Document.Parameters[*]" (Required) Specify a shell script or a command to run. commands StringList (Optional) The path to the working directory on your instance. workingDirectory String 3600 (Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours). executionTimeout String
We may want to use the following command to get IP information for an instance:
$ aws ssm send-command --instance-ids "i-0698042a954420857" --document-name "AWS-RunShellScript" --comment "IP config" --parameters commands=ifconfig --output text COMMAND e4d8a901-34b7-480d-9e47-f0a71179be64 IP config 0 AWS-RunShellScript 0 1496465253.78 50 0 1496458053.78 Pending Pending 1 INSTANCEIDS i-0698042a954420857 NOTIFICATIONCONFIG COMMANDS ifconfig
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” we will need to execute this command again to see the response data:
$ aws ssm list-command-invocations --command-id "e4d8a901-34b7-480d-9e47-f0a71179be64" --details
The following command displays the default user account running the commands:
$ sh_command_id=$(aws ssm send-command --instance-ids "i-0698042a954420857" --document-name "AWS-RunShellScript" --comment "Demo run shell script on Linux Instance" --parameters commands=whoami --output text --query "Command.CommandId")
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:
$ aws ssm list-commands --command-id $sh_command_id COMMANDS 136b1a05-6724-45f1-a23b-f98062fca64d Demo run shell script on Linux Instance 1 AWS-RunShellScript 0 1496465641.83 50 0 1496458441.83 Success Success 1 INSTANCEIDS i-0698042a954420857 NOTIFICATIONCONFIG COMMANDS whoami
The following command uses the Command ID from the previous command to get the status of the command execution on a per instance basis:
$ aws ssm list-command-invocations --command-id $sh_command_id --details
Recent Comments