• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). 

# Managing nodes in hybrid and multicloud environments with Systems Manager


You can use AWS Systems Manager to manage both Amazon Elastic Compute Cloud (EC2) instances and a number of non-EC2 machine types. This section describes the setup tasks that account and system administrators perform to manage non-EC2 machines using Systems Manager in a *[hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment*. After these steps are complete, users who have been granted permissions by the AWS account administrator can use Systems Manager to configure and manage their organization's non-EC2 machines.

Any machine that has been configured for use with Systems Manager is called a *managed node*.

**Note**  
You can register edge devices as managed nodes using the same hybrid-activation steps used for other non-EC2 machines. These types of edge devices include both AWS IoT devices and devices other than AWS IoT devices. Use the process described in this section to set up these types of edge devices.  
Systems Manager also supports edge devices that use AWS IoT Greengrass Core software. The setup process and requirements for AWS IoT Greengrass core devices are different from those for AWS IoT and edge devices other than AWS edge devices. For information about registering AWS IoT Greengrass devices for use with Systems Manager, see [Managing edge devices with Systems Manager](systems-manager-setting-up-edge-devices.md).
Non-EC2 macOS machines aren't supported for Systems Manager hybrid and multicloud environments.

If you plan to use Systems Manager to manage Amazon Elastic Compute Cloud (Amazon EC2) instances, or to use both Amazon EC2 instances and non-EC2 machines in hybrid and multicloud environment, follow the steps in [Managing EC2 instances with Systems Manager](systems-manager-setting-up-ec2.md) first. 

After configuring your hybrid and multicloud environment for Systems Manager, you can do the following: 
+ Create a consistent and secure way to remotely manage your hybrid and multicloud workloads from one location using the same tools or scripts.
+ Centralize access control for actions that can be performed on your machines by using AWS Identity and Access Management (IAM).
+ Centralize auditing of the operations performed on your machines by viewing the API activity recorded in AWS CloudTrail.

  For information about using CloudTrail to monitor Systems Manager actions, see [Logging AWS Systems Manager API calls with AWS CloudTrail](monitoring-cloudtrail-logs.md).
+ Centralize monitoring by configuring Amazon EventBridge and Amazon Simple Notification Service (Amazon SNS) to send notifications about service execution success.

  For information about using EventBridge to monitor Systems Manager events, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md).

**About managed nodes**  
After you finish configuring your non-EC2 machines for Systems Manager as described in this section, your hybrid-activated machines are listed in the AWS Management Console and described as *managed nodes*. In the console, the IDs of your hybrid-activated managed nodes are distinguished from Amazon EC2 instances with the prefix "mi-". Amazon EC2 instance IDs use the prefix "i-".

A managed node is any machine configured for Systems Manager. Previously, managed nodes were all referred to as managed instances. The term *instance* now refers to EC2 instances only. The [deregister-managed-instance](https://docs.aws.amazon.com/cli/latest/reference/ssm/deregister-managed-instance.html) command was named before this terminology change.

For more information, see [Working with managed nodes](fleet-manager-managed-nodes.md).

**Important**  
We strongly recommend that you avoid using OS versions that have reached End-of-Life (EOL). OS vendors including AWS typically don't provide security patches or other updates for versions that have reached EOL. Continuing to use an EOL system greatly increases the risk of not being able to apply upgrades, including security fixes, and other operational problems. AWS does not test Systems Manager functionality on OS versions that have reached EOL.

**About instance tiers**  
Systems Manager offers a standard-instances tier and an advanced-instances tier for non-EC2 managed nodes in your hybrid and multicloud environment. The standard-instances tier allows you to register a maximum of 1,000 hybrid-activated machines per AWS account per AWS Region. If you need to register more than 1,000 non-EC2 machines in a single account and Region, then use the advanced-instances tier. Advanced instances also allow you to connect to your non-EC2 machines by using AWS Systems Manager Session Manager. Session Manager provides interactive shell access to your managed nodes.

For more information, see [Configuring instance tiers](fleet-manager-configure-instance-tiers.md).

**Topics**
+ [

# Create the IAM service role required for Systems Manager in hybrid and multicloud environments
](hybrid-multicloud-service-role.md)
+ [

# Create a hybrid activation to register nodes with Systems Manager
](hybrid-activation-managed-nodes.md)
+ [

# Install SSM Agent on hybrid Linux nodes
](hybrid-multicloud-ssm-agent-install-linux.md)
+ [

# Install SSM Agent on hybrid Windows Server nodes
](hybrid-multicloud-ssm-agent-install-windows.md)

# Create the IAM service role required for Systems Manager in hybrid and multicloud environments


Non-EC2 (Amazon Elastic Compute Cloud) machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment require an AWS Identity and Access Management (IAM) service role to communicate with the AWS Systems Manager service. The role grants AWS Security Token Service (AWS STS) [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) trust to the Systems Manager service. You only need to create a service role for a hybrid and multicloud environment once for each AWS account. However, you might choose to create multiple service roles for different hybrid activations if machines in your hybrid and multicloud environment require different permissions.

The following procedures describe how to create the required service role using the Systems Manager console or your preferred command line tool.

## Using the AWS Management Console to create an IAM service role for Systems Manager hybrid activations


Use the following procedure to create a service role for hybrid activation. This procedure uses the `AmazonSSMManagedInstanceCore` policy for Systems Manager core functionality. Depending on your use case, you might need to add additional policies to your service role for your on-premises machines to be able to access other Systems Manager tools or AWS services. For example, without access to the required AWS managed Amazon Simple Storage Service (Amazon S3) buckets, Patch Manager patching operations fail.

**To create a service role (console)**

1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **Roles**, and then choose **Create role**.

1. For **Select trusted entity**, make the following choices:

   1. For **Trusted entity type**, choose **AWS service**.

   1. For **Use cases for other AWS services**, choose **Systems Manager**.

   1. Choose **Systems Manager**.

      The following image highlights the location of the Systems Manager option.  
![\[Systems Manager is one of the options for Use case.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/iam_use_cases_for_MWs.png)

1. Choose **Next**. 

1. On the **Add permissions** page, do the following: 
   + Use the **Search** field to locate the **AmazonSSMManagedInstanceCore** policy. Select the check box next to its name, as shown in the following illustration.   
![\[The check box is selected in the AmazonSSMManagedInstanceCore row.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/setup-instance-profile-2.png)
**Note**  
The console retains your selection even if you search for other policies.
   + If you created a custom S3 bucket policy in the procedure [(Optional) Create a custom policy for S3 bucket access](setup-instance-permissions.md#instance-profile-custom-s3-policy), search for it and select the check box next to its name.
   + If you plan to join non-EC2 machines to an Active Directory managed by Directory Service, search for **AmazonSSMDirectoryServiceAccess** and select the check box next to its name.
   + If you plan to use EventBridge or CloudWatch Logs to manage or monitor your managed node, search for **CloudWatchAgentServerPolicy** and select the check box next to its name.

1. Choose **Next**.

1. For **Role name**, enter a name for your new IAM server role, such as **SSMServerRole**.
**Note**  
Make a note of the role name. You will choose this role when you register new machines that you want to manage by using Systems Manager.

1. (Optional) For **Description**, update the description for this IAM server role.

1. (Optional) For **Tags**, add one or more tag-key value pairs to organize, track, or control access for this role. 

1. Choose **Create role**. The system returns you to the **Roles** page.

## Using the AWS CLI to create an IAM service role for Systems Manager hybrid activations


Use the following procedure to create a service role for hybrid activation. This procedure uses the `AmazonSSMManagedInstanceCore` policy Systems Manager core functionality. Depending on your use case, you might need to add additional policies to your service role for your non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment to be able to access other tools or AWS services.

**S3 bucket policy requirement**  
If either of the following cases are true, you must create a custom IAM permission policy for Amazon Simple Storage Service (Amazon S3) buckets before completing this procedure:
+ **Case 1** – You're using a VPC endpoint to privately connect your VPC to supported AWS services and VPC endpoint services powered by AWS PrivateLink. 
+ **Case 2** – You plan to use an Amazon S3 bucket that you create as part of your Systems Manager operations, such as for storing output for Run Command commands or Session Manager sessions to an S3 bucket. Before proceeding, follow the steps in [Create a custom S3 bucket policy for an instance profile](setup-instance-permissions.md#instance-profile-custom-s3-policy). The information about S3 bucket policies in that topic also applies to your service role.

------
#### [ AWS CLI ]

**To create an IAM service role for a hybrid and multicloud environment (AWS CLI)**

1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.

   For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).

1. On your local machine, create a text file with a name such as `SSMService-Trust.json` with the following trust policy. Make sure to save the file with the `.json` file extension. Be sure to specify your AWS account and the AWS Region in the ARN where you created your hybrid activation. Replace the *placeholder values* for account ID and Region with your own information.

------
#### [ JSON ]

****  

   ```
   {
      "Version":"2012-10-17",		 	 	 
      "Statement":[
         {
            "Sid":"",
            "Effect":"Allow",
            "Principal":{
               "Service":"ssm.amazonaws.com"
            },
            "Action":"sts:AssumeRole",
            "Condition":{
               "StringEquals":{
                  "aws:SourceAccount":"123456789012"
               },
               "ArnEquals":{
                  "aws:SourceArn":"arn:aws:ssm:us-east-1:111122223333:*"
               }
            }
         }
      ]
   }
   ```

------

1. Open the AWS CLI, and in the directory where you created the JSON file, run the [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create the service role. This example creates a role named `SSMServiceRole`. You can choose another name if you prefer.

------
#### [ Linux & macOS ]

   ```
   aws iam create-role \
       --role-name SSMServiceRole \
       --assume-role-policy-document file://SSMService-Trust.json
   ```

------
#### [ Windows ]

   ```
   aws iam create-role ^
       --role-name SSMServiceRole ^
       --assume-role-policy-document file://SSMService-Trust.json
   ```

------

1. Run the [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) command as follows to allow the service role you just created to create a session token. The session token gives your managed node permission to run commands using Systems Manager.
**Note**  
The policies you add for a service profile for managed nodes in a hybrid and multicloud environment are the same policies used to create an instance profile for Amazon Elastic Compute Cloud (Amazon EC2) instances. For more information about the AWS policies used in the following commands, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).

   (Required) Run the following command to allow a managed node to use AWS Systems Manager service core functionality.

------
#### [ Linux & macOS ]

   ```
   aws iam attach-role-policy \
       --role-name SSMServiceRole \
       --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
   ```

------
#### [ Windows ]

   ```
   aws iam attach-role-policy ^
       --role-name SSMServiceRole ^
       --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
   ```

------

   If you created a custom S3 bucket policy for your service role, run the following command to allow AWS Systems Manager Agent (SSM Agent) to access the buckets you specified in the policy. Replace *account-id* and *amzn-s3-demo-bucket* with your AWS account ID and your bucket name. 

------
#### [ Linux & macOS ]

   ```
   aws iam attach-role-policy \
       --role-name SSMServiceRole \
       --policy-arn arn:aws:iam::account-id:policy/amzn-s3-demo-bucket
   ```

------
#### [ Windows ]

   ```
   aws iam attach-role-policy ^
       --role-name SSMServiceRole ^
       --policy-arn arn:aws:iam::account-id:policy/amzn-s3-demo-bucket
   ```

------

   (Optional) Run the following command to allow SSM Agent to access Directory Service on your behalf for requests to join the domain by the managed node. Your service role needs this policy only if you join your nodes to a Microsoft AD directory.

------
#### [ Linux & macOS ]

   ```
   aws iam attach-role-policy \
       --role-name SSMServiceRole \
       --policy-arn arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess
   ```

------
#### [ Windows ]

   ```
   aws iam attach-role-policy ^
       --role-name SSMServiceRole ^
       --policy-arn arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess
   ```

------

   (Optional) Run the following command to allow the CloudWatch agent to run on your managed nodes. This command makes it possible to read information on a node and write it to CloudWatch. Your service profile needs this policy only if you will use services such as Amazon EventBridge or Amazon CloudWatch Logs.

   ```
   aws iam attach-role-policy \
       --role-name SSMServiceRole \
       --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
   ```

------
#### [ Tools for PowerShell ]

**To create an IAM service role for a hybrid and multicloud environment (AWS Tools for Windows PowerShell)**

1. Install and configure the AWS Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.

   For information, see [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).

1. On your local machine, create a text file with a name such as `SSMService-Trust.json` with the following trust policy. Make sure to save the file with the `.json` file extension. Be sure to specify your AWS account and the AWS Region in the ARN where you created your hybrid activation.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "",
               "Effect": "Allow",
               "Principal": {
                   "Service": "ssm.amazonaws.com"
               },
               "Action": "sts:AssumeRole",
               "Condition": {
                   "StringEquals": {
                       "aws:SourceAccount": "123456789012"
                   },
                   "ArnEquals": {
                       "aws:SourceArn": "arn:aws:ssm:us-east-1:123456789012:*"
                   }
               }
           }
       ]
   }
   ```

------

1. Open PowerShell in administrative mode, and in the directory where you created the JSON file, run [New-IAMRole](https://docs.aws.amazon.com//powershell/latest/reference/items/Register-IAMRolePolicy.html) as follows to create a service role. This example creates a role named `SSMServiceRole`. You can choose another name if you prefer.

   ```
   New-IAMRole `
       -RoleName SSMServiceRole `
       -AssumeRolePolicyDocument (Get-Content -raw SSMService-Trust.json)
   ```

1. Use [Register-IAMRolePolicy](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-IAMRolePolicy.html) as follows to allow the service role you created to create a session token. The session token gives your managed node permission to run commands using Systems Manager.
**Note**  
The policies you add for a service profile for managed nodes in a hybrid and multicloud environment are the same policies used to create an instance profile for EC2 instances. For more information about the AWS policies used in the following commands, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).

   (Required) Run the following command to allow a managed node to use AWS Systems Manager service core functionality.

   ```
   Register-IAMRolePolicy `
       -RoleName SSMServiceRole `
       -PolicyArn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
   ```

   If you created a custom S3 bucket policy for your service role, run the following command to allow SSM Agent to access the buckets you specified in the policy. Replace *account-id* and *my-bucket-policy-name* with your AWS account ID and your bucket name. 

   ```
   Register-IAMRolePolicy `
       -RoleName SSMServiceRole `
       -PolicyArn arn:aws:iam::account-id:policy/my-bucket-policy-name
   ```

   (Optional) Run the following command to allow SSM Agent to access Directory Service on your behalf for requests to join the domain by the managed node. Your server role needs this policy only if you join your nodes to a Microsoft AD directory.

   ```
   Register-IAMRolePolicy `
       -RoleName SSMServiceRole `
       -PolicyArn arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess
   ```

   (Optional) Run the following command to allow the CloudWatch agent to run on your managed nodes. This command makes it possible to read information on a node and write it to CloudWatch. Your service profile needs this policy only if you will use services such as Amazon EventBridge or Amazon CloudWatch Logs.

   ```
   Register-IAMRolePolicy `
       -RoleName SSMServiceRole `
       -PolicyArn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
   ```

------

Continue to [Create a hybrid activation to register nodes with Systems Manager](hybrid-activation-managed-nodes.md).

# Create a hybrid activation to register nodes with Systems Manager


To set up machines other than Amazon Elastic Compute Cloud (EC2) instances as managed nodes for a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment, you create and apply a *hybrid activation*. After you successfully complete the activation, you *immediately* receive an Activation Code and Activation ID at the top of the console page. You specify this Code and ID combination when you install AWS Systems Manager SSM Agent on non-EC2 machines for your hybrid and multicloud environment. The Code and ID provide secure access to the Systems Manager service from your managed nodes.

**Important**  
Systems Manager immediately returns the Activation Code and ID to the console or the command window, depending on how you created the activation. Copy this information and store it in a safe place. If you navigate away from the console or close the command window, you might lose this information. If you lose it, you must create a new activation. 

**About activation expirations**  
An *activation expiration* is a window of time when you can register on-premises machines with Systems Manager. An expired activation has no impact on your servers or VMs that you previously registered with Systems Manager. If an activation expires then you can’t register more servers or VMs with Systems Manager by using that specific activation. You simply need to create a new one.

Every on-premises server and VM you previously registered remains registered as a Systems Manager managed node until you explicitly deregister it. You can deregister a non-EC2 managed node in the following ways:
+ Use the **Managed nodes** tab in Fleet Manager in the Systems Manager console
+ Use the AWS CLI command [https://docs.aws.amazon.com/cli/latest/reference/ssm/deregister-managed-instance.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/deregister-managed-instance.html)
+ Use the API action [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html).

For more information, see the following topics
+ [Deregister and reregister a managed node (Linux)](hybrid-multicloud-ssm-agent-install-linux.md#systems-manager-install-managed-linux-deregister-reregister)
+ [Deregister and reregister a managed node (Windows Server)](hybrid-multicloud-ssm-agent-install-windows.md#systems-manager-install-managed-win-deregister-reregister)

**About managed nodes**  
A managed node is any machine configured for AWS Systems Manager. AWS Systems Manager supports Amazon Elastic Compute Cloud (Amazon EC2) instances, edge devices, and on-premises servers or VMs, including VMs in other cloud environments. Previously, managed nodes were all referred to as managed instances. The term *instance* now refers to EC2 instances only. The [deregister-managed-instance](https://docs.aws.amazon.com/cli/latest/reference/ssm/deregister-managed-instance.html) command was named before this terminology change.

**About activation tags**  
If you create an activation by using either the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell, you can specify tags. Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment. Here is an AWS CLI sample command to run in the US East (Ohio) Region on a local Linux machine that includes optional tags.

```
aws ssm create-activation \
  --default-instance-name MyWebServers \
  --description "Activation for Finance department webservers" \
  --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances \
  --registration-limit 10 \
  --region us-east-2 \
  --tags "Key=Department,Value=Finance"
```

If you specify tags when you create an activation, then those tags are automatically assigned to your managed nodes when you activate them.

You can't add tags to or delete tags from an existing activation. If you don't want to automatically assign tags to your on-premises servers and VMs using an activation, then you can add tags to them later. More specifically, you can tag your on-premises servers and VMs after they connect to Systems Manager for the first time. After they connect, they're assigned a managed node ID and listed in the Systems Manager console with an ID that is prefixed with "mi-".

**Note**  
You can't assign tags to an activation if you create it by using the Systems Manager console. You must create it by using either the AWS CLI or Tools for Windows PowerShell.

If you no longer want to manage an on-premises server or virtual machine (VM) by using Systems Manager, you can deregister it. For information, see [Deregistering managed nodes in a hybrid and multicloud environment](fleet-manager-deregister-hybrid-nodes.md).

**Topics**
+ [

## Using the AWS Management Console to create an activation for registering managed nodes with Systems Manager
](#create-managed-node-activation-console)
+ [

## Using the command line to create an activation for registering managed nodes with Systems Manager
](#create-managed-node-activation-command-line)

## Using the AWS Management Console to create an activation for registering managed nodes with Systems Manager


**To create a managed-node activation**

1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).

1. In the navigation pane, choose **Hybrid Activations**.

1. Choose **Create activation**.

   -or-

   If you are accessing **Hybrid Activations** for the first time in the current AWS Region, choose **Create an Activation**. 

1. (Optional) For **Activation description**, enter a description for this activation. We recommend entering a description if you plan to activate large numbers of servers and VMs.

1. For **Instance limit**, specify the total number of nodes that you want to register with AWS as part of this activation. The default value is 1 instance.

1. For ** IAM role**, choose a service role option that allows your servers and VMs to communicate with AWS Systems Manager in the cloud:
   + **Option 1**: Choose **Use the default role created by the system** to use a role and managed policy provided by AWS. 
   + **Option 2**: Choose **Select an existing custom IAM role that has the required permissions** to use the optional custom role you created earlier. This role must have a trust relationship policy that specifies `"Service": "ssm.amazonaws.com"`. If your IAM role doesn't specify this principle in a trust relationship policy, you receive the following error:

     ```
     An error occurred (ValidationException) when calling the CreateActivation
                                         operation: Not existing role: arn:aws:iam::<accountid>:role/SSMRole
     ```

     For more information about creating this role, see [Create the IAM service role required for Systems Manager in hybrid and multicloud environments](hybrid-multicloud-service-role.md). 

1. For **Activation expiry date**, specify an expiration date for the activation. The expiry date must be in the future, and not more than 30 days into the future. The default value is 24 hours.
**Note**  
If you want to register additional managed nodes after the expiry date, you must create a new activation. The expiry date has no impact on registered and running nodes.

1. (Optional) For **Default instance name** field, specify an identifying name value to be displayed for all managed nodes associated with this activation. 

1. Choose **Create activation**. Systems Manager immediately returns the Activation Code and ID to the console. 

## Using the command line to create an activation for registering managed nodes with Systems Manager


The following procedure describes how to use the AWS Command Line Interface (AWS CLI) (on Linux or Windows Server) or AWS Tools for PowerShell to create a managed node activation.

**To create an activation**

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you haven't already.

   For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).

1. Run the following command to create an activation.
**Note**  
In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
The role you specify for the *iam-role* parameter must have a trust relationship policy that specifies `"Service": "ssm.amazonaws.com"`. If your AWS Identity and Access Management (IAM) role doesn't specify this principle in a trust relationship policy, you receive the following error:  

     ```
     An error occurred (ValidationException) when calling the CreateActivation
                                             operation: Not existing role: arn:aws:iam::<accountid>:role/SSMRole
     ```
For more information about creating this role, see [Create the IAM service role required for Systems Manager in hybrid and multicloud environments](hybrid-multicloud-service-role.md). 
For `--expiration-date`, provide a date in timestamp format, such as `"2021-07-07T00:00:00"`, for when the activation code expires. You can specify a date up to 30 days in advance. If you don't provide an expiration date, the activation code expires in 24 hours.

------
#### [ Linux & macOS ]

   ```
   aws ssm create-activation \
       --default-instance-name name \
       --iam-role iam-service-role-name \
       --registration-limit number-of-managed-instances \
       --region region \
       --expiration-date "timestamp" \\  
       --tags "Key=key-name-1,Value=key-value-1" "Key=key-name-2,Value=key-value-2"
   ```

------
#### [ Windows ]

   ```
   aws ssm create-activation ^
       --default-instance-name name ^
       --iam-role iam-service-role-name ^
       --registration-limit number-of-managed-instances ^
       --region region ^
       --expiration-date "timestamp" ^
       --tags "Key=key-name-1,Value=key-value-1" "Key=key-name-2,Value=key-value-2"
   ```

------
#### [ PowerShell ]

   ```
   New-SSMActivation -DefaultInstanceName name `
       -IamRole iam-service-role-name `
       -RegistrationLimit number-of-managed-instances `
       –Region region `
       -ExpirationDate "timestamp" `
       -Tag @{"Key"="key-name-1";"Value"="key-value-1"},@{"Key"="key-name-2";"Value"="key-value-2"}
   ```

------

   Here is an example.

------
#### [ Linux & macOS ]

   ```
   aws ssm create-activation \
       --default-instance-name MyWebServers \
       --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances \
       --registration-limit 10 \
       --region us-east-2 \
       --expiration-date "2021-07-07T00:00:00" \
       --tags "Key=Environment,Value=Production" "Key=Department,Value=Finance"
   ```

------
#### [ Windows ]

   ```
   aws ssm create-activation ^
       --default-instance-name MyWebServers ^
       --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances ^
       --registration-limit 10 ^
       --region us-east-2 ^
       --expiration-date "2021-07-07T00:00:00" ^
       --tags "Key=Environment,Value=Production" "Key=Department,Value=Finance"
   ```

------
#### [ PowerShell ]

   ```
   New-SSMActivation -DefaultInstanceName MyWebServers `
       -IamRole service-role/AmazonEC2RunCommandRoleForManagedInstances `
       -RegistrationLimit 10 `
       –Region us-east-2 `
       -ExpirationDate "2021-07-07T00:00:00" `
       -Tag @{"Key"="Environment";"Value"="Production"},@{"Key"="Department";"Value"="Finance"}
   ```

------

   If the activation is created successfully, the system immediately returns an Activation Code and ID.

# Install SSM Agent on hybrid Linux nodes


This topic describes how to install AWS Systems Manager SSM Agent on non-EC2 (Amazon Elastic Compute Cloud) Linux machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. For information about installing SSM Agent on EC2 instances for Linux, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md).

Before you begin, locate the Activation Code and Activation ID that were generated during the hybrid activation process, as described in [Create a hybrid activation to register nodes with Systems Manager](hybrid-activation-managed-nodes.md). You specify the Code and ID in the following procedure.

**To install SSM Agent on non-EC2 machines in a hybrid and multicloud environment**

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

1. If you use an HTTP or HTTPS proxy, you must set the `http_proxy` or `https_proxy` environment variables in the current shell session. If you aren't using a proxy, you can skip this step.

   For an HTTP proxy server, enter the following commands at the command line:

   ```
   export http_proxy=http://hostname:port
   export https_proxy=http://hostname:port
   ```

   For an HTTPS proxy server, enter the following commands at the command line:

   ```
   export http_proxy=http://hostname:port
   export https_proxy=https://hostname:port
   ```

1. Copy and paste one of the following command blocks into SSH. Replace the placeholder values with the Activation Code and Activation ID generated during the hybrid activation process and with the identifier of the AWS Region you want to download SSM Agent from, then press `Enter`.
**Important**  
Note the following important details:  
Using `ssm-setup-cli` for non-EC2 installations maximizes the security of your Systems Manager installation and configuration.
`sudo` isn't necessary if you're a root user.
Download `ssm-setup-cli` from the same AWS Region as where your hybrid activation was created.
`ssm-setup-cli` supports a `manifest-url` option that determines the source where the agent is downloaded from. Don't specify a value for this option unless required by your organization.
When registering instances, only use the provided download link provided for `ssm-setup-cli`. `ssm-setup-cli` shouldn’t be stored separately for future use.
You can use the script provided [here](https://github.com/aws/amazon-ssm-agent/blob/mainline/Tools/src/setupcli_data_integrity_linux.sh) to validate the signature of `ssm-setup-cli`.

   *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.

   Additionally, `ssm-setup-cli` includes the following options:
   + `version` - Valid values are `latest` and `stable`.
   + `downgrade` - Allows the SSM Agent to be downgraded to an earlier version. Specify `true` to install an earlier version of the agent.
   + `skip-signature-validation` - Skips the signature validation during the download and installation of the agent.

## Amazon Linux 2, RHEL 7.x, and Oracle Linux


```
mkdir /tmp/ssm
curl https://amazon-ssm-region.s3.region.amazonaws.com/latest/linux_amd64/ssm-setup-cli -o /tmp/ssm/ssm-setup-cli
sudo chmod +x /tmp/ssm/ssm-setup-cli
sudo /tmp/ssm/ssm-setup-cli -register -activation-code "activation-code" -activation-id "activation-id" -region "region"
```

## RHEL 8.x


```
mkdir /tmp/ssm
curl https://amazon-ssm-region.s3.region.amazonaws.com/latest/linux_amd64/ssm-setup-cli -o /tmp/ssm/ssm-setup-cli
sudo chmod +x /tmp/ssm/ssm-setup-cli
sudo /tmp/ssm/ssm-setup-cli -register -activation-code "activation-code" -activation-id "activation-id" -region "region"
```

## Debian Server


```
mkdir /tmp/ssm
curl https://amazon-ssm-region.s3.region.amazonaws.com/latest/debian_amd64/ssm-setup-cli -o /tmp/ssm/ssm-setup-cli
sudo chmod +x /tmp/ssm/ssm-setup-cli
sudo /tmp/ssm/ssm-setup-cli -register -activation-code "activation-code" -activation-id "activation-id" -region "region"
```

## Ubuntu Server

+ **Using .deb packages**

  ```
  mkdir /tmp/ssm
  curl https://amazon-ssm-region.s3.region.amazonaws.com/latest/debian_amd64/ssm-setup-cli -o /tmp/ssm/ssm-setup-cli
  sudo chmod +x /tmp/ssm/ssm-setup-cli
  sudo /tmp/ssm/ssm-setup-cli -register -activation-code "activation-code" -activation-id "activation-id" -region "region"
  ```
+ **Using Snap packages**

  You don't need to specify a URL for the download, because the `snap` command automatically downloads the agent from the [Snap app store](https://snapcraft.io/amazon-ssm-agent) at [https://snapcraft.io](https://snapcraft.io).

  On Ubuntu Server 20.04, 18.04, and 16.04 LTS, SSM Agent installer files, including agent binaries and config files, are stored in the following directory: `/snap/amazon-ssm-agent/current/`. If you make changes to any configuration files in this directory, then you must copy these files from the `/snap` directory to the `/etc/amazon/ssm/` directory. Log and library files haven't changed (`/var/lib/amazon/ssm`, `/var/log/amazon/ssm`).

  ```
  sudo snap install amazon-ssm-agent --classic
  sudo systemctl stop snap.amazon-ssm-agent.amazon-ssm-agent.service
  sudo /snap/amazon-ssm-agent/current/amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region "region" 
  sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service
  ```
**Important**  
The *candidate* channel in the Snap store contains the latest version of SSM Agent; not the stable channel. If you want to track SSM Agent version information on the candidate channel, run the following command on your Ubuntu Server 18.04 and 16.04 LTS 64-bit managed nodes.  

  ```
  sudo snap switch --channel=candidate amazon-ssm-agent
  ```

The command downloads and installs SSM Agent onto the hybrid-activated machine in your hybrid and multicloud environment. The command stops SSM Agent, and then registers the machine with the Systems Manager service. The machine is now a managed node. Amazon EC2 instances configured for Systems Manager are also managed nodes. In the Systems Manager console, however, your hybrid-activated nodes are distinguished from Amazon EC2 instances with the prefix "mi-".

Continue to [Install SSM Agent on hybrid Windows Server nodes](hybrid-multicloud-ssm-agent-install-windows.md).

## Setting up private key auto rotation


To strengthen your security posture, you can configure AWS Systems Manager Agent (SSM Agent) to automatically rotate the private key for your hybrid and multicloud environment. You can access this feature using SSM Agent version 3.0.1031.0 or later. Turn on this feature using the following procedure.

**To configure SSM Agent to rotate the private key for a hybrid and multicloud environment**

1. Navigate to `/etc/amazon/ssm/` on a Linux machine or `C:\Program Files\Amazon\SSM` for a Windows machine.

1. Copy the contents of `amazon-ssm-agent.json.template` to a new file named `amazon-ssm-agent.json`. Save `amazon-ssm-agent.json` in the same directory where `amazon-ssm-agent.json.template` is located.

1. Find `Profile`, `KeyAutoRotateDays`. Enter the number of days that you want between automatic private key rotations. 

1. Restart SSM Agent.

Every time you change the configuration, restart SSM Agent.

You can customize other features of SSM Agent using the same procedure. For an up-to-date list of the available configuration properties and their default values, see [Config Property Definitions](https://github.com/aws/amazon-ssm-agent#config-property-definitions). 

## Deregister and reregister a managed node (Linux)


You can deregister a hybrid-activated managed node by calling the [DeregisterManagedInstance](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html) API operation from either the AWS CLI or Tools for Windows PowerShell. Here's an example CLI command:

`aws ssm deregister-managed-instance --instance-id "mi-1234567890"`

To remove the remaining registration information for the agent, remove the `IdentityConsumptionOrder` key in the `amazon-ssm-agent.json` file. Then, depending on your installation type, run one of the following commands.

On Ubuntu Server nodes where SSM Agent was installed using Snap packages:

```
sudo /snap/amazon-ssm-agent/current/amazon-ssm-agent -register -clear
```

On all other Linux installations:

```
amazon-ssm-agent -register -clear
```

**Note**  
You can reregister an on-premises server, edge device, or VM using the same activation code and ID as long as you haven't reached the instance limit for the designated activation code and ID. You can verify the instance limit for an activation code and ID by calling the [describe-activations](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-activations.html) API using the AWS CLI. After you run the command, verify that the value of `RegistrationCount` doesn't exceed `RegistrationLimit`. If it does, you must use a different activation code and ID.

**To reregister a managed node on a non-EC2 Linux machine**

1. Connect to your machine.

1. Run the following command. Be sure to replace the placeholder values with the Activation Code and Activation ID generated when you created a managed-node activation, and with the identifier of the Region you want to download the SSM Agent from.

   ```
   echo "yes" | sudo /tmp/ssm/ssm-setup-cli -register -activation-code "activation-code" -activation-id "activation-id" -region "region
   ```

## Troubleshooting SSM Agent installation on non-EC2 Linux machines


Use the following information to help you troubleshoot problems installing SSM Agent on hybrid-activated Linux machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment.

### You receive DeliveryTimedOut error


**Problem**: While configuring a machine in one AWS account as a managed node for a separate AWS account, you receive `DeliveryTimedOut` after running the commands to install SSM Agent on the target machine.

**Solution**: `DeliveryTimedOut` is the expected response code for this scenario. The command to install SSM Agent on the target node changes the node ID of the source node. Because the node ID has changed, the source node isn't able to reply to the target node that the command failed, completed, or timed out while executing.

### Unable to load node associations


**Problem**: After running the install commands, you see the following error in the SSM Agent error logs:

`Unable to load instance associations, unable to retrieve associations unable to retrieve associations error occurred in RequestManagedInstanceRoleToken: MachineFingerprintDoesNotMatch: Fingerprint doesn't match`

You see this error when the machine ID doesn't persist after a reboot.

**Solution**: To solve this problem, run the following command. This command forces the machine ID to persist after a reboot.

```
umount /etc/machine-id
systemd-machine-id-setup
```

# Install SSM Agent on hybrid Windows Server nodes


This topic describes how to install AWS Systems Manager SSM Agent on Windows Server machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. For information about installing SSM Agent on EC2 instances for Windows Server, see [Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server](manually-install-ssm-agent-windows.md).

Before you begin, locate the Activation Code and Activation ID that were generated during the hybrid activation process, as described in [Create a hybrid activation to register nodes with Systems Manager](hybrid-activation-managed-nodes.md). You specify the Code and ID in the following procedure.

**To install SSM Agent on non-EC2 Windows Server machines in a hybrid and multicloud environment**

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

1. If you use an HTTP or HTTPS proxy, you must set the `http_proxy` or `https_proxy` environment variables in the current shell session. If you aren't using a proxy, you can skip this step.

   For an HTTP proxy server, set this variable:

   ```
   http_proxy=http://hostname:port
   https_proxy=http://hostname:port
   ```

   For an HTTPS proxy server, set this variable:

   ```
   http_proxy=http://hostname:port
   https_proxy=https://hostname:port
   ```

   For PowerShell, configure the WinINet proxy settings:

   ```
   [System.Net.WebRequest]::DefaultWebProxy
   
   $proxyServer = "http://hostname:port"
   $proxyBypass = "169.254.169.254"
   $WebProxy = New-Object System.Net.WebProxy($proxyServer,$true,$proxyBypass)
   
   [System.Net.WebRequest]::DefaultWebProxy = $WebProxy
   ```
**Note**  
WinINet proxy configuration is required for PowerShell operations. For more information, see [SSM Agent proxy settings and Systems Manager services](configure-proxy-ssm-agent-windows.md#ssm-agent-proxy-services).

1. Open Windows PowerShell in elevated (administrative) mode.

1. Copy and paste the following command block into Windows PowerShell. Replace each *example resource placeholder* with your own information. For example, the Activation Code and Activation ID generated when you create a hybrid activation, and with the identifier of the AWS Region you want to download SSM Agent from.
**Important**  
Note the following important details:  
Using `ssm-setup-cli` for non-EC2 installations maximizes the security of your Systems Manager installation and configuration.
`ssm-setup-cli` supports a `manifest-url` option that determines the source where the agent is downloaded from. Don't specify a value for this option unless required by your organization.
You can use the script provided [here](https://github.com/aws/amazon-ssm-agent/blob/mainline/Tools/src/setupcli_data_integrity_windows.ps1) to validate the signature of `ssm-setup-cli`.
When registering instances, only use the provided download link provided for `ssm-setup-cli`. `ssm-setup-cli` shouldn’t be stored separately for future use.

   *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.

   Additionally, `ssm-setup-cli` includes the following options:
   + `version` - Valid values are `latest` and `stable`.
   + `downgrade` - Reverts the agent to an earlier version.
   + `skip-signature-validation` - Skips the signature validation during the download and installation of the agent.

------
#### [ 64-bit ]

   ```
   [System.Net.ServicePointManager]::SecurityProtocol = 'TLS12'
   $code = "activation-code"
   $id = "activation-id"
   $region = "us-east-1"
   $dir = $env:TEMP + "\ssm"
   New-Item -ItemType directory -Path $dir -Force
   cd $dir
   (New-Object System.Net.WebClient).DownloadFile("https://amazon-ssm-$region.s3.$region.amazonaws.com/latest/windows_amd64/ssm-setup-cli.exe", $dir + "\ssm-setup-cli.exe")
   ./ssm-setup-cli.exe -register -activation-code="$code" -activation-id="$id" -region="$region"
   Get-Content ($env:ProgramData + "\Amazon\SSM\InstanceData\registration")
   Get-Service -Name "AmazonSSMAgent"
   ```

------

1. Press `Enter`.

**Note**  
If the command fails, verify that you are running the latest version of AWS Tools for PowerShell.

The command does the following: 
+ Downloads and installs SSM Agent onto the machine.
+ Registers the machine with the Systems Manager service.
+ Returns a response to the request similar to the following:

  ```
      Directory: C:\Users\ADMINI~1\AppData\Local\Temp\2
  
  
  Mode                LastWriteTime         Length Name
  ----                -------------         ------ ----
  d-----       07/07/2018   8:07 PM                ssm
  {"ManagedInstanceID":"mi-008d36be46EXAMPLE","Region":"us-east-2"}
  
  Status      : Running
  Name        : AmazonSSMAgent
  DisplayName : Amazon SSM Agent
  ```

The machine is now a *managed node*. These managed nodes are now identified with the prefix "mi-". You can view managed nodes on the **Managed node** page in Fleet Manager, by using the AWS CLI command [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-information.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-information.html), or by using the API command [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstanceInformation.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstanceInformation.html).

## Setting up private key auto rotation


To strengthen your security posture, you can configure AWS Systems Manager Agent (SSM Agent) to automatically rotate the private key for a hybrid and multicloud environment. You can access this feature using SSM Agent version 3.0.1031.0 or later. Turn on this feature using the following procedure.

**To configure SSM Agent to rotate the private key for a hybrid and multicloud environment**

1. Navigate to `/etc/amazon/ssm/` on a Linux machine or `C:\Program Files\Amazon\SSM` for a Windows Server machine.

1. Copy the contents of `amazon-ssm-agent.json.template` to a new file named `amazon-ssm-agent.json`. Save `amazon-ssm-agent.json` in the same directory where `amazon-ssm-agent.json.template` is located.

1. Find `Profile`, `KeyAutoRotateDays`. Enter the number of days that you want between automatic private key rotations. 

1. Restart SSM Agent.

Every time you change the configuration, restart SSM Agent.

You can customize other features of SSM Agent using the same procedure. For an up-to-date list of the available configuration properties and their default values, see [Config Property Definitions](https://github.com/aws/amazon-ssm-agent#config-property-definitions). 

## Deregister and reregister a managed node (Windows Server)


You can deregister a managed node by calling the [DeregisterManagedInstance](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html) API operation from either the AWS CLI or Tools for Windows PowerShell. Here's an example CLI command:

`aws ssm deregister-managed-instance --instance-id "mi-1234567890"`

To remove the remaining registration information for the agent, remove the `IdentityConsumptionOrder` key in the `amazon-ssm-agent.json` file. Then run the following command:

`amazon-ssm-agent -register -clear`

**Note**  
You can reregister an on-premises server, edge device, or VM using the same activation code and ID as long as you haven't reached the instance limit for the designated activation code and ID. You can verify the instance limit for an activation code and ID by calling the [describe-activations](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-activations.html) API using the AWS CLI. After you run the command, verify that the value of `RegistrationCount` doesn't exceed `RegistrationLimit`. If it does, you must use a different activation code and ID.

**To reregister a managed node on a Windows Server hybrid machine**

1. Connect to your machine.

1. Run the following command. Be sure to replace the placeholder values with the Activation Code and Activation ID generated when you created a hybrid activation, and with the identifier of the Region you want to download the SSM Agent from.

   ```
   $dir = $env:TEMP + "\ssm"
   cd $dir
   Start-Process ./ssm-setup-cli.exe -ArgumentList @(
       "-register",
       "-activation-code=$code",
       "-activation-id=$id",
       "-region=$region"
   ) -Wait -NoNewWindow
   ```