Menu
Amazon EC2 Systems Manager
User Guide

Setting Up Systems Manager in Hybrid Environments

Amazon EC2 Systems Manager lets you remotely and securely manage on-premises servers and virtual machines (VMs) in your hybrid environment. Configuring your hybrid environment for Systems Manager provides the following benefits.

  • Create a consistent and secure way to remotely manage your on-premises workloads from one location using the same tools or scripts.

  • Centralize access control for actions that can be performed on your servers and VMs by using AWS Identity and Access Management (IAM).

  • Centralize auditing and your view into the actions performed on your servers and VMs because all actions are recorded in AWS CloudTrail.

  • Centralize monitoring because you can configure CloudWatch Events and Amazon SNS to send notifications about service execution success.

Complete the procedures in this topic to configure your hybrid machines for Systems Manager.

Important

After you finish, your hybrid machines that are configured for Systems Manager are listed in the Amazon EC2 console and described as managed instances. Amazon EC2 instances configured for Systems Manager are also managed instances. In the Amazon EC2 console, however, your on-premise instances are distinguished from Amazon EC2 instances with the prefix "mi-".

Create an IAM Service Role

Servers and VMs in a hybrid environment require an IAM role to communicate with the Systems Manager SSM service. The role grants AssumeRole trust to the SSM service.

Note

You only need to create the service role once for each AWS account.

To create an IAM service role using AWS Tools for Windows PowerShell

  1. Create a text file (in this example it is named SSMService-Trust.json) with the following trust policy. Save the file with the .json file extension.

    Copy
    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"Service": "ssm.amazonaws.com"}, "Action": "sts:AssumeRole" } }
  2. Use New-IAMRole as follows to create a service role. This example creates a role named SSMServiceRole.

    Copy
    New-IAMRole -RoleName SSMServiceRole -AssumeRolePolicyDocument (Get-Content -raw SSMService-Trust.json)
  3. Use Register-IAMRolePolicy as follows to enable the SSMServiceRole to create a session token. The session token gives your managed instance permission to execute commands using Systems Manager.

    Copy
    Register-IAMRolePolicy -RoleName SSMServiceRole -PolicyArn arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM

To create an IAM service role using the AWS CLI

  1. Create a text file (in this example it is named SSMService-Trust.json) with the following trust policy. Save the file with the .json file extension.

    Copy
    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"Service": "ssm.amazonaws.com"}, "Action": "sts:AssumeRole" } }
  2. Use the create-role command to create the service role. This example creates a role named SSMServiceRole.

    Copy
    aws iam create-role --role-name SSMServiceRole --assume-role-policy-document file://SSMService-Trust.json
  3. Use attach-role-policy as follows to enable the SSMServiceRole to create a session token. The session token gives your managed instance permission to execute commands using Systems Manager.

    Copy
    aws iam attach-role-policy --role-name SSMServiceRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM

Note

Users in your company or organization who will use Systems Manager on your hybrid machines must be granted permission in IAM to call the SSM API. For more information, see Configuring Security Roles for Systems Manager.

Create a Managed-Instance Activation

To set up servers and VMs in your hybrid environment as managed instances, you need to create a managed-instance activation. After you complete the activation, you receive an activation code and ID. This code/ID combination functions like an Amazon EC2 access ID and secret key to provide secure access to the Systems Manager service from your managed instances.

To create a managed-instance activation using the console

  1. Open the Amazon EC2 console, expand Systems Manager Shared Resources in the navigation pane, and choose Activations.

  2. Choose Create an Activation.

  3. Fill out the form and choose Create Activation.

    Note that you can specify a date when the activation expires. If you want to register additional managed instances after the expiry date, you must create a new activation. The expiry date has no impact on registered and running instances.

  4. Store the managed-instance activation code and ID in a safe place. You specify this code and ID when you install the SSM agent on servers and VMs in your hybrid environment. If you lose the code and ID, you must create a new activation.

To create a managed-instance activation using the AWS Tools for Windows PowerShell

  1. On a machine with where you have installed AWS Tools for Windows PowerShell, execute the following command in AWS Tools for Windows PowerShell.

    Copy
    New-SSMActivation -DefaultInstanceName name -IamRole IAM service role -RegistrationLimit number of managed instances –Region region

    For example:

    Copy
    New-SSMActivation -DefaultInstanceName MyWebServers -IamRole RunCommandServiceRole -RegistrationLimit 10 –Region us-east-1
  2. Press Enter. If the activation is successful, the system returns an activation code and an ID. Store the activation code and ID in a safe place.

To create a managed-instance activation using the AWS CLI

  1. On a machine where you have installed the AWS Command Line Interface (AWS CLI), execute the following command in the CLI.

    Copy
    aws ssm create-activation --default-instance-name name --iam-role IAM service role --registration-limit number of managed instances --region region

    For example:

    Copy
    aws ssm create-activation --default-instance-name MyWebServers --iam-role RunCommandServiceRole --registration-limit 10 --region us-east-1
  2. Press Enter. If the activation is successful, the system returns an activation code and an ID. Store the activation code and ID in a safe place.

Install the SSM Agent on Servers and VMs in Your Windows Hybrid Environment

Before you begin, locate the activation code and ID that was sent to you after you completed the managed-instance activation in the previous section. You will specify the code and ID in the following procedure.

Important

This procedure is for servers and VMs in an on-premises or hybrid environment. To download and install the SSM Agent on an Amazon EC2 Windows instance, see Installing SSM Agent on Windows.

To install the SSM agent on servers and VMs in your hybrid environment

  1. Log on to a server or VM in your hybrid environment.

  2. Open Windows PowerShell.

  3. Copy and paste the following command block into AWS Tools for Windows PowerShell. Specify your activation code, activation ID, and the region where you want to download the SSM agent from. For region, choose a region where SSM is available. For example, us-west-2.

    Copy
    $dir = $env:TEMP + "\ssm" New-Item -ItemType directory -Path $dir cd $dir (New-Object System.Net.WebClient).DownloadFile("https://amazon-ssm-region.s3.amazonaws.com/latest/windows_amd64/AmazonSSMAgentSetup.exe", $dir + "\AmazonSSMAgentSetup.exe") Start-Process .\AmazonSSMAgentSetup.exe -ArgumentList @("/q", "/log", "install.log", "CODE=code", "ID=id", "REGION=region") -Wait Get-Content ($env:ProgramData + "\Amazon\SSM\InstanceData\registration") Get-Service -Name "AmazonSSMAgent"
  4. Press Enter.

The command downloads and installs the SSM agent onto the server or VM. The command also registers the server or VM with the SSM service. The server or VM is now a managed instance. In the console, these instances are listed with the prefix "mi-". You can view all instances using a List command. For more information, see the Amazon EC2 Systems Manager API Reference.

Install the SSM Agent on Servers and VMs in Your Linux Hybrid Environment

Before you begin, locate the activation code and ID that was sent to you after you completed the managed-instance activation. You will specify the code and ID in the following procedure.

Important

This procedure is for servers and VMs in an on-premises or hybrid environment. To download and install the SSM Agent on an Amazon EC2 Linux instance, see Installing SSM Agent on Linux.

The URLs in the following scripts let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, choose one of the following URLs.

  • Amazon Linux, RHEL, CentOS, and SLES 64-bit

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

  • Amazon Linux, RHEL, and CentOS 32-bit

    https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_386/amazon-ssm-agent.rpm

  • Ubuntu Server 64-bit

    https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-agent.deb

  • Ubuntu Server 32-bit

    https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb

And then replace region with a region where SSM is available.

To install the SSM agent on servers and VMs in your hybrid environment

  1. Log on to a server or VM in your hybrid environment.

  2. Copy and paste one of the following command blocks into SSH. Specify your activation code, activation ID, and the region where you want to download the SSM agent from. Note that sudo is not necessary if you are a root user.

    On Amazon Linux, RHEL 6.x, and CentOS 6.x

    Copy
    mkdir /tmp/ssm sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm sudo stop amazon-ssm-agent sudo amazon-ssm-agent -register -code "code" -id "id" -region "region" sudo start amazon-ssm-agent

    On RHEL 7.x and CentOS 7.x

    Copy
    mkdir /tmp/ssm sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm sudo systemctl stop amazon-ssm-agent sudo amazon-ssm-agent -register -code "code" -id "id" -region "region" sudo systemctl start amazon-ssm-agent

    On SLES

    Copy
    mkdir /tmp/ssm sudo wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm sudo rpm --install amazon-ssm-agent.rpm sudo systemctl stop amazon-ssm-agent sudo amazon-ssm-agent -register -code "code" -id "id" -region "region" sudo systemctl enable amazon-ssm-agent sudo systemctl start amazon-ssm-agent

    On Ubuntu

    Copy
    mkdir /tmp/ssm sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb sudo service amazon-ssm-agent stop sudo amazon-ssm-agent -register -code "code" -id "id" -region "region" sudo service amazon-ssm-agent start
  3. Press Enter.

The command downloads and installs the SSM agent onto the server or VM in your hybrid environment. The command stops the SSM agent and then registers the server or VM with the SSM service. The server or VM is now a managed instance. Amazon EC2 instances configured for Systems Manager are also managed instances. In the Amazon EC2 console, however, your on-premise instances are distinguished from Amazon EC2 instances with the prefix "mi-".