• The Amazon 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.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Setting up managed nodes for Amazon Systems Manager
Complete the tasks in this section to set up and configure roles, user accounts, permissions, and initial resources for using Amazon Systems Manager tools. The tasks described in this section are typically performed by Amazon Web Services account and systems administrators. After these steps are complete, users in your organization can use Systems Manager to configure, manage, and access your *managed nodes*. A managed node is any machine configured for use with Systems Manager in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment.
**Note**
If you plan to use Amazon EC2 instances *and* your own computing resources in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment, follow the steps in [Managing EC2 instances with Systems Manager](systems-manager-setting-up-ec2.md). That topic presents steps in the best order for completing Systems Manager setup for EC2 instances and non-EC2 machines.
If you already use other Amazon Web Services services, you have completed some of these steps. However, other steps are specific to Systems Manager. Therefore, we recommend reviewing this entire section to ensure that you're ready to use all Systems Manager tools.
**Topics**
+ [
# Managing EC2 instances with Systems Manager
](systems-manager-setting-up-ec2.md)
+ [
# Managing nodes in hybrid and multicloud environments with Systems Manager
](systems-manager-hybrid-multicloud.md)
+ [
# Managing edge devices with Systems Manager
](systems-manager-setting-up-edge-devices.md)
+ [
# Creating an Amazon Organizations delegated administrator for Systems Manager
](setting_up_delegated_admin.md)
+ [
## General setup for Amazon Systems Manager
](#setting_up_prerequisites)
# Managing EC2 instances with Systems Manager
Complete the tasks in this section to set up and configure roles, permissions, and initial resources for Amazon Systems Manager. The tasks described in this section are typically performed by Amazon Web Services account and systems administrators. After these steps are complete, users in your organization can use Systems Manager to configure, manage, and access Amazon Elastic Compute Cloud (Amazon EC2) instances.
**Note**
If you plan to use Systems Manager to manage and configure on-premises machines, follow the setup steps in [Managing nodes in hybrid and multicloud environments with Systems Manager](systems-manager-hybrid-multicloud.md). If you plan to use both Amazon EC2 instances *and* non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment, follow the steps here first. This section presents steps in the recommended order for configuring the roles, users, permissions, and initial resources to use in your Systems Manager operations.
If you already use other Amazon Web Services services, you have completed some of these steps. However, other steps are specific to Systems Manager. Therefore, we recommend reviewing this entire section to ensure that you're ready to use all Systems Manager tools.
**Topics**
+ [
# Configure instance permissions required for Systems Manager
](setup-instance-permissions.md)
+ [
# Improve the security of EC2 instances by using VPC endpoints for Systems Manager
](setup-create-vpc.md)
# Configure instance permissions required for Systems Manager
By default, Amazon Systems Manager doesn't have permission to perform actions on your instances. You can provide instance permissions at the account level using an Amazon Identity and Access Management (IAM) role, or at the instance level using an instance profile. If your use case allows, we recommend granting access at the account level using the Default Host Management Configuration.
**Note**
You can skip this step and allow Systems Manager to apply the required permissions to your instances for you when setting up the unified console. For more information, see [Setting up Amazon Systems Manager](systems-manager-setting-up-console.md).
## Recommended configuration for EC2 instance permissions
Default Host Management Configuration allows Systems Manager to manage your Amazon EC2 instances automatically. After you've turned on this setting, all instances using Instance Metadata Service Version 2 (IMDSv2) in the Amazon Web Services Region and Amazon Web Services account with SSM Agent version 3.2.582.0 or later installed automatically become managed instances. Default Host Management Configuration doesn't support Instance Metadata Service Version 1. For information about transitioning to IMDSv2, see [Transition to using Instance Metadata Service Version 2](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.html) in the *Amazon EC2 User Guide*. For information about checking the version of the SSM Agent installed on your instance, see [Checking the SSM Agent version number](ssm-agent-get-version.md). For information about updating the SSM Agent, see [Automatically updating SSM Agent](ssm-agent-automatic-updates.md#ssm-agent-automatic-updates-console). Benefits of managed instances include the following:
+ Connect to your instances securely using Session Manager.
+ Perform automated patch scans using Patch Manager.
+ View detailed information about your instances using Systems Manager Inventory.
+ Track and manage instances using Fleet Manager.
+ Keep the SSM Agent up to date automatically.
Fleet Manager, Inventory, Patch Manager, and Session Manager are tools in Amazon Systems Manager.
Default Host Management Configuration allows instance management without the use of instance profiles and ensures that Systems Manager has permissions to manage all instances in the Region and account. If the permissions provided aren't sufficient for your use case, you can also add policies to the default IAM role created by the Default Host Management Configuration. Alternatively, if you don't need permissions for all of the capabilities provided by the default IAM role, you can create your own custom role and policies. Any changes made to the IAM role you choose for Default Host Management Configuration applies to all managed Amazon EC2 instances in the Region and account. For more information about the policy used by Default Host Management Configuration, see [Amazon managed policy: AmazonSSMManagedEC2InstanceDefaultPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSSMManagedEC2InstanceDefaultPolicy). For more information about the Default Host Management Configuration, see [Managing EC2 instances automatically with Default Host Management Configuration](fleet-manager-default-host-management-configuration.md).
**Important**
Instances registered using Default Host Management Configuration store registration information locally in the `/lib/amazon/ssm` or `C:\ProgramData\Amazon` directories. Removing these directories or their files will prevent the instance from acquiring the necessary credentials to connect to Systems Manager using Default Host Management Configuration. In these cases, you must use an instance profile to provide the required permissions to your instance, or recreate the instance.
**Note**
This procedure is intended to be performed only by administrators. Implement least privilege access when allowing individuals to configure or modify the Default Host Management Configuration. You must turn on the Default Host Management Configuration in each Amazon Web Services Region you wish to automatically manage your Amazon EC2 instances.
**To turn on the Default Host Management Configuration setting**
You can turn on the Default Host Management Configuration from the Fleet Manager console. To successfully complete this procedure using either the Amazon Web Services Management Console or your preferred command line tool, you must have permissions for the [GetServiceSetting](https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_GetServiceSetting.html), [ResetServiceSetting](https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_ResetServiceSetting.html), and [UpdateServiceSetting](https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_UpdateServiceSetting.html) API operations. Additionally, you must have permissions for the `iam:PassRole` permission for the `AWSSystemsManagerDefaultEC2InstanceManagementRole` IAM role. The following is an example policy. Replace each *example resource placeholder* with your own information.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting",
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws-cn:ssm:us-east-1:111122223333:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
},
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws-cn:iam::111122223333:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com.cn"
]
}
}
}
]
}
```
------
Before you begin, if you have instance profiles attached to your Amazon EC2 instances, remove any permissions that allow the `ssm:UpdateInstanceInformation` operation. The SSM Agent attempts to use instance profile permissions before using the Default Host Management Configuration permissions. If you allow the `ssm:UpdateInstanceInformation` operation in your instance profiles, the instance will not use the Default Host Management Configuration permissions.
1. Open the Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/systems-manager/).
1. In the navigation pane, choose **Fleet Manager**.
1. Choose **Configure Default Host Management Configuration** under the **Account management** dropdown.
1. Turn on **Enable Default Host Management Configuration**.
1. Choose the IAM role used to enable Systems Manager tools for your instances. We recommend using the default role provided by Default Host Management Configuration. It contains the minimum set of permissions necessary to manage your Amazon EC2 instances using Systems Manager. If you prefer to use a custom role, the role's trust policy must allow Systems Manager as a trusted entity.
1. Choose **Configure** to complete setup.
After turning on the Default Host Management Configuration, it might take up 30 minutes for your instances to use the credentials of the role you chose. You must turn on the Default Host Management Configuration in each Region you wish to automatically manage your Amazon EC2 instances.
## Alternative configuration for EC2 instance permissions
You can grant access at the individual instance level by using an Amazon Identity and Access Management (IAM) instance profile. An instance profile is a container that passes IAM role information to an Amazon Elastic Compute Cloud (Amazon EC2) instance at launch. You can create an instance profile for Systems Manager by attaching one or more IAM policies that define the necessary permissions to a new role or to a role you already created.
**Note**
You can use Quick Setup, a tool in Amazon Systems Manager, to quickly configure an instance profile on all instances in your Amazon Web Services account. Quick Setup also creates an IAM service role (or *assume* role), which allows Systems Manager to securely run commands on your instances on your behalf. By using Quick Setup, you can skip this step (Step 3) and Step 4. For more information, see [Amazon Systems Manager Quick Setup](systems-manager-quick-setup.md).
Note the following details about creating an IAM instance profile:
+ If you're configuring non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment for Systems Manager, you don't need to create an instance profile for them. Instead, configure your servers and VMs to use an IAM service role. For more information, see [Create the IAM service role required for Systems Manager in hybrid and multicloud environments](hybrid-multicloud-service-role.md).
+ If you change the IAM instance profile, it might take some time for the instance credentials to refresh. SSM Agent won't process requests until this happens. To speed up the refresh process, you can restart SSM Agent or restart the instance.
Depending on whether you're creating a new role for your instance profile or adding the necessary permissions to an existing role, use one of the following procedures.
**To create an instance profile for Systems Manager managed instances (console)**
1. Open the IAM console at [https://console.amazonaws.cn/iam/](https://console.amazonaws.cn/iam/).
1. In the navigation pane, choose **Roles**, and then choose **Create role**.
1. For **Trusted entity type**, choose **Amazon Web Services service**.
1. Immediately under **Use case**, choose **EC2**, and then 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.amazonaws.cn/en_us/systems-manager/latest/userguide/images/setup-instance-profile-2.png)
The console retains your selection even if you search for other policies.
+ If you created a custom S3 bucket policy in the previous procedure, [(Optional) Create a custom policy for S3 bucket access](#instance-profile-custom-s3-policy), search for it and select the check box next to its name.
+ If you plan to join instances to an Active Directory managed by Amazon 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 instance, 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 instance profile, such as **SSMInstanceProfile**.
**Note**
Make a note of the role name. You will choose this role when you create new instances that you want to manage by using Systems Manager.
1. (Optional) For **Description**, update the description for this instance profile.
1. (Optional) For **Tags**, add one or more tag-key value pairs to organize, track, or control access for this role, and then choose **Create role**. The system returns you to the **Roles** page.
**To add instance profile permissions for Systems Manager to an existing role (console)**
1. Open the IAM console at [https://console.amazonaws.cn/iam/](https://console.amazonaws.cn/iam/).
1. In the navigation pane, choose **Roles**, and then choose the existing role you want to associate with an instance profile for Systems Manager operations.
1. On the **Permissions** tab, choose **Add permissions, Attach policies**.
1. On the **Attach policy** page, do the following:
+ Use the **Search** field to locate the **AmazonSSMManagedInstanceCore** policy. Select the check box next to its name.
+ If you have created a custom S3 bucket policy, search for it and select the check box next to its name. For information about custom S3 bucket policies for an instance profile, see [(Optional) Create a custom policy for S3 bucket access](#instance-profile-custom-s3-policy).
+ If you plan to join instances to an Active Directory managed by Amazon 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 instance, search for **CloudWatchAgentServerPolicy** and select the check box next to its name.
1. Choose **Attach policies**.
For information about how to update a role to include a trusted entity or further restrict access, see [Modifying a role](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_manage_modify.html) in the *IAM User Guide*.
## (Optional) Create a custom policy for S3 bucket access
Creating a custom policy for Amazon S3 access is required only if you're using a VPC endpoint or using an S3 bucket of your own in your Systems Manager operations. You can attach this policy to the default IAM role created by the Default Host Management Configuration, or an instance profile you created in the previous procedure.
For information about the Amazon managed S3 buckets you provide access to in the following policy, see [SSM Agent communications with Amazon managed S3 buckets](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions).
1. Open the IAM console at [https://console.amazonaws.cn/iam/](https://console.amazonaws.cn/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. Choose the **JSON** tab, and replace the default text with the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": [
"arn:aws-cn:s3:::aws-ssm-us-west-2/*",
"arn:aws-cn:s3:::aws-windows-downloads-us-west-2/*",
"arn:aws-cn:s3:::amazon-ssm-us-west-2/*",
"arn:aws-cn:s3:::amazon-ssm-packages-us-west-2/*",
"arn:aws-cn:s3:::us-west-2-birdwatcher-prod/*",
"arn:aws-cn:s3:::aws-ssm-distributor-file-us-west-2/*",
"arn:aws-cn:s3:::aws-ssm-document-attachments-us-west-2/*",
"arn:aws-cn:s3:::patch-baseline-snapshot-us-west-2/*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:GetEncryptionConfiguration"
],
"Resource": [
"arn:aws-cn:s3:::amzn-s3-demo-bucket/*",
"arn:aws-cn:s3:::amzn-s3-demo-bucket"
]
}
]
}
```
------
**Note**
The first `Statement` element is required only if you're using a VPC endpoint.
The second `Statement` element is required only if you're using an S3 bucket that you created to use in your Systems Manager operations.
The `PutObjectAcl` access control list permission is required only if you plan to support cross-account access to S3 buckets in other accounts.
The `GetEncryptionConfiguration` element is required if your S3 bucket is configured to use encryption.
If your S3 bucket is configured to use encryption, then the S3 bucket root (for example, `arn:aws-cn:s3:::amzn-s3-demo-bucket`) must be listed in the **Resource** section. Your user, group, or role must be configured with access to the root bucket.
1. If you're using a VPC endpoint in your operations, do the following:
In the first `Statement` element, replace each *region* placeholder with the identifier of the Amazon Web Services Region this policy will be used in. For example, use `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.amazonaws.cn/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
**Important**
We recommend that you avoid using wildcard characters (\$1) in place of specific Regions in this policy. For example, use `arn:aws-cn:s3:::aws-ssm-us-east-2/*` and do not use `arn:aws-cn:s3:::aws-ssm-*/*`. Using wildcards could provide access to S3 buckets that you don’t intend to grant access to. If you want to use the instance profile for more than one Region, we recommend repeating the first `Statement` element for each Region.
-or-
If you aren't using a VPC endpoint in your operations, you can delete the first `Statement` element.
1. If you're using an S3 bucket of your own in your Systems Manager operations, do the following:
In the second `Statement` element, replace *amzn-s3-demo-bucket* with the name of an S3 bucket in your account. You will use this bucket for your Systems Manager operations. It provides permission for objects in the bucket, using `"arn:aws-cn:s3:::my-bucket-name/*"` as the resource. For more information about providing permissions for buckets or objects in buckets, see the topic [Amazon S3 actions](https://docs.amazonaws.cn/AmazonS3/latest/dev/using-with-s3-actions.html) in the *Amazon Simple Storage Service User Guide* and the Amazon blog post [IAM Policies and Bucket Policies and ACLs\$1 Oh, My\$1 (Controlling Access to S3 Resources)](https://amazonaws-china.com/blogs/security/iam-policies-and-bucket-policies-and-acls-oh-my-controlling-access-to-s3-resources/).
**Note**
If you use more than one bucket, provide the ARN for each one. See the following example for permissions on buckets.
```
"Resource": [
"arn:aws-cn:s3:::amzn-s3-demo-bucket1/*",
"arn:aws-cn:s3:::amzn-s3-demo-bucket2/*"
]
```
-or-
If you aren't using an S3 bucket of your own in your Systems Manager operations, you can delete the second `Statement` element.
1. Choose **Next: Tags**.
1. (Optional) Add tags by choosing **Add tag**, and entering the preferred tags for the policy.
1. Choose **Next: Review**.
1. For **Name**, enter a name to identify this policy, such as **SSMInstanceProfileS3Policy**.
1. Choose **Create policy**.
## Additional policy considerations for managed instances
This section describes some of the policies you can add to the default IAM role created by the Default Host Management Configuration, or your instance profiles for Amazon Systems Manager. To provide permissions for communication between instances and the Systems Manager API, we recommend creating custom policies that reflect your system needs and security requirements. Depending on your operations plan, you might need permissions represented in one or more of the other policies.
**Policy: `AmazonSSMDirectoryServiceAccess`**
Required only if you plan to join Amazon EC2 instances for Windows Server to a Microsoft AD directory.
This Amazon managed policy allows SSM Agent to access Amazon Directory Service on your behalf for requests to join the domain by the managed instance. For more information, see [Seamlessly join a Windows EC2 Instance](https://docs.amazonaws.cn/directoryservice/latest/admin-guide/launching_instance.html) in the *Amazon Directory Service Administration Guide*.
**Policy: `CloudWatchAgentServerPolicy`**
Required only if you plan to install and run the CloudWatch agent on your instances to read metric and log data on an instance and write it to Amazon CloudWatch. These help you monitor, analyze, and quickly respond to issues or changes to your Amazon resources.
Your default IAM role created by the Default Host Management Configuration or instance profile needs this policy only if you will use features such as Amazon EventBridge or Amazon CloudWatch Logs. (You can also create a more restrictive policy that, for example, limits writing access to a specific CloudWatch Logs log stream.)
Using EventBridge and CloudWatch Logs features is optional. However, we recommend setting them up at the beginning of your Systems Manager configuration process if you have decided to use them. For more information, see the *[Amazon EventBridge User Guide](https://docs.amazonaws.cn/eventbridge/latest/userguide/)* and the *[Amazon CloudWatch Logs User Guide](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/)*.
To create IAM policies with permissions for additional Systems Manager tools, see the following resources:
+ [Restricting access to Parameter Store parameters using IAM policies](sysman-paramstore-access.md)
+ [Setting up Automation](automation-setup.md)
+ [Step 2: Verify or add instance permissions for Session Manager](session-manager-getting-started-instance-profile.md)
## Attach the Systems Manager instance profile to an instance (console)
The following procedure describes how to attach an IAM instance profile to an Amazon EC2 instance using the Amazon EC2 console.
1. Sign in to the Amazon Web Services Management Console and open the Amazon EC2 console at [https://console.amazonaws.cn/ec2/](https://console.amazonaws.cn/ec2/).
1. In the navigation pane, under **Instances**, choose **Instances**.
1. Navigate to and choose your EC2 instance from the list.
1. In the **Actions** menu, choose **Security**, **Modify IAM role**.
1. For **IAM role**, select the instance profile you created using the procedure in [Alternative configuration for EC2 instance permissions](#instance-profile-add-permissions).
1. Choose **Update **IAM role****.
For more information about attaching IAM roles to instances, choose one of the following, depending on your selected operating system type:
+ [Attach an IAM role to an instance](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#attach-iam-role) in the *Amazon EC2 User Guide*
+ [Attach an IAM role to an instance](https://docs.amazonaws.cn/AWSEC2/latest/WindowsGuide/iam-roles-for-amazon-ec2.html#attach-iam-role) in the *Amazon EC2 User Guide*
Continue to [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](setup-create-vpc.md).
# Improve the security of EC2 instances by using VPC endpoints for Systems Manager
You can improve the security posture of your managed nodes (including non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment) by configuring Amazon Systems Manager to use an interface VPC endpoint in Amazon Virtual Private Cloud (Amazon VPC). By using an interface VPC endpoint (interface endpoint), you can connect to services powered by Amazon PrivateLink. Amazon PrivateLink is a technology that allows you to privately access Amazon Elastic Compute Cloud (Amazon EC2) and Systems Manager APIs by using private IP addresses.
Amazon PrivateLink restricts all network traffic between your managed instances, Systems Manager, and Amazon EC2 to the Amazon network. This means that your managed instances don't have access to the Internet. If you use Amazon PrivateLink, you don't need an internet gateway, a NAT device, or a virtual private gateway.
You aren't required to configure Amazon PrivateLink, but it's recommended. For more information about Amazon PrivateLink and VPC endpoints, see [Amazon PrivateLink and VPC endpoints](https://docs.amazonaws.cn/vpc/latest/userguide/endpoint-services-overview.html).
**Note**
The alternative to using a VPC endpoint is to allow outbound internet access on your managed instances. In this case, the managed instances must also allow HTTPS (port 443) outbound traffic to the following endpoints:
`ssm.region.amazonaws.com.cn`
`ssmmessages.region.amazonaws.com.cn`
`ec2messages.region.amazonaws.com.cn`
SSM Agent initiates all connections to the Systems Manager service in the cloud. For this reason, you don't need to configure your firewall to allow inbound traffic to your instances for Systems Manager.
For more information about calls to these endpoints, see [Reference: ec2messages, ssmmessages, and other API operations](systems-manager-setting-up-messageAPIs.md).
If you are using Systems Manager in an environment that supports *only* IPv6, you must also allow outbound traffic to the following endpoints:
`ssm.region.api.aws`
`ssmmessages.region.api.aws`
`ec2messages.region.api.aws`
For more information about dual-stack service endpoints, see [Dual stack endpoints ](https://docs.amazonaws.cn/general/latest/gr/rande.html#dual-stack-endpoints) in the *Amazon General Reference Guide*.
You must also ensure that the patch operation buckets are reachable from your nodes, as described in [Reference: Amazon S3 buckets for patching operations](https://docs.amazonaws.cn/systems-manager/latest/userguide/patch-operations-s3-buckets.html).
**About Amazon VPC**
You can use Amazon Virtual Private Cloud (Amazon VPC) to define a virtual network in your own logically isolated area within the Amazon Web Services Cloud, known as a *virtual private cloud (VPC)*. You can launch your Amazon resources, such as instances, into your VPC. Your VPC closely resembles a traditional network that you might operate in your own data center, with the benefits of using the scalable infrastructure of Amazon. You can configure your VPC; you can select its IP address range, create subnets, and configure route tables, network gateways, and security settings. You can connect instances in your VPC to the internet. You can connect your VPC to your own corporate data center, making the Amazon Web Services Cloud an extension of your data center. To protect the resources in each subnet, you can use multiple layers of security, including security groups and network access control lists. For more information, see the [Amazon VPC User Guide](https://docs.amazonaws.cn/vpc/latest/userguide/).
**Topics**
+ [
## VPC endpoint restrictions and limitations
](#vpc-requirements-and-limitations)
+ [
## Creating VPC endpoints for Systems Manager
](#create-vpc-endpoints)
+ [
## Create an interface VPC endpoint policy
](#create-vpc-interface-endpoint-policies)
## VPC endpoint restrictions and limitations
Before you configure VPC endpoints for Systems Manager, be aware of the following restrictions and limitations.
**VPC peering connections**
VPC interface endpoints can be accessed through both *intra-Region* and *inter-Region* VPC peering connections. For more information about VPC peering connection requests for VPC interface endpoints, see [VPC peering connections (Quotas)](https://docs.amazonaws.cn/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-peering) in the *Amazon Virtual Private Cloud User Guide*.
VPC gateway endpoint connections can't be extended out of a VPC. Resources on the other side of a VPC peering connection in your VPC can't use the gateway endpoint to communicate with resources in the gateway endpoint service. For more information about VPC peering connection requests for VPC gateway endpoints, see [VPC endpoints (Quotas)](https://docs.amazonaws.cn/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-endpoints) in the *Amazon Virtual Private Cloud User Guide*
**Incoming connections**
The security group attached to the VPC endpoint must allow incoming connections on port 443 from the private subnet of the managed instance. If incoming connections aren't allowed, then the managed instance can't connect to the SSM and EC2 endpoints.
**DNS resolution**
If you use a custom DNS server, you must add a conditional forwarder for any queries to the `amazonaws.com.cn` domain to the Amazon DNS server for your VPC.
**S3 buckets**
Your VPC endpoint policy must allow access to at least the Amazon S3 buckets listed in [SSM Agent communications with Amazon managed S3 buckets](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions).
**Note**
If you use an on-premises firewall and plan to use Patch Manager, that firewall must also allow access to the appropriate patch baseline endpoint.
**Amazon CloudWatch Logs**
If you don't allow your instances to access the internet, create a VPC endpoint for CloudWatch Logs to use features that send logs to CloudWatch Logs. For more information about creating an endpoint for CloudWatch Logs, see [Creating a VPC endpoint for CloudWatch Logs](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html#create-VPC-endpoint-for-CloudWatchLogs) in the *Amazon CloudWatch Logs User Guide*.
**DNS in hybrid and multicloud environment**
For information about configuring DNS to work with Amazon PrivateLink endpoints in [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environments, see [Private DNS for interface endpoints](https://docs.amazonaws.cn/vpc/latest/privatelink/vpce-interface.html#vpce-private-dns) in the *Amazon VPC User Guide*. If you want to use your own DNS, you can use Route 53 Resolver. For more information, see [Resolving DNS queries between VPCs and your network](https://docs.amazonaws.cn/Route53/latest/DeveloperGuide/resolver.html) in the *Amazon Route 53 Developer Guide*.
## Creating VPC endpoints for Systems Manager
Use the following information to create VPC interface endpoints for Amazon Systems Manager. This topic links to procedures in the *Amazon VPC User Guide*.
**Note**
*region* represents the identifier for an Amazon Web Services Region supported by Amazon 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.amazonaws.cn/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
Follow the steps in [Create an interface endpoint](https://docs.amazonaws.cn/vpc/latest/privatelink/vpce-interface.html#create-interface-endpoint) to create the following interface endpoints:
+ **`com.amazonaws.region.ssm`** – The endpoint for the Systems Manager service.
+ **`com.amazonaws.region.ec2messages`** – Systems Manager uses this endpoint to make calls from SSM Agent to the Systems Manager service. Beginning with version 3.3.40.0 of SSM Agent, Systems Manager began using the `ssmmessages:*` endpoint (Amazon Message Gateway Service) whenever available instead of the `ec2messages:*` endpoint (Amazon Message Delivery Service).
+ **`com.amazonaws.region.ec2`** – If you're using Systems Manager to create VSS-enabled snapshots, you need to ensure that you have an endpoint to the EC2 service. Without the EC2 endpoint defined, a call to enumerate attached Amazon EBS volumes fails, which causes the Systems Manager command to fail.
+ **`com.amazonaws.region.s3`** – Systems Manager uses this endpoint to update SSM Agent. Systems Manager also uses this endpoint if, optionally, you choose to retrieve scripts or other files stored in buckets or upload output logs to a bucket. If the security group associated with your instances restricts outbound traffic, you must add a rule to allow traffic to the prefix list for Amazon S3. For more information, see [Modify your security group](https://docs.amazonaws.cn/vpc/latest/privatelink/vpce-gateway.html#vpc-endpoints-security) in the *Amazon PrivateLink Guide*.
+ **`com.amazonaws.region.ssmmessages`** – This endpoint is required for SSM Agent to communicate with the Systems Manager service, for Run Command, and if you're connecting to your instances through a secure data channel using Session Manager. For more information, see [Amazon Systems Manager Session Manager](session-manager.md) and [Reference: ec2messages, ssmmessages, and other API operations](systems-manager-setting-up-messageAPIs.md).
+ (Optional) **`com.amazonaws.region.kms`** – Create this endpoint if you want to use Amazon Key Management Service (Amazon KMS) encryption for Session Manager or Parameter Store parameters.
+ (Optional) **`com.amazonaws.region.logs`** – Create this endpoint if you want to use Amazon CloudWatch Logs (CloudWatch Logs) for Session Manager, Run Command, or SSM Agent logs.
For information about the Amazon managed S3 buckets that SSM Agent must be able to access, see [SSM Agent communications with Amazon managed S3 buckets](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions). If you're using a virtual private cloud (VPC) endpoint in your Systems Manager operations, you must provide explicit permission in an EC2 instance profile for Systems Manager, or in a service role for non-EC2 managed nodes in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment.
## Create an interface VPC endpoint policy
You can create policies for VPC interface endpoints for Amazon Systems Manager in which you can specify:
+ The principal that can perform actions
+ The actions that can be performed
+ The resources that can have actions performed on them
For more information, see [Control access to services with VPC endpoints](https://docs.amazonaws.cn/vpc/latest/privatelink/vpc-endpoints-access.html) in the *Amazon VPC User Guide*.
# Managing nodes in hybrid and multicloud environments with Systems Manager
You can use Amazon 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 Amazon Web Services 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 Amazon IoT devices and devices other than Amazon 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 Amazon IoT Greengrass Core software. The setup process and requirements for Amazon IoT Greengrass core devices are different from those for Amazon IoT and edge devices other than Amazon edge devices. For information about registering Amazon 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 Amazon Identity and Access Management (IAM).
+ Centralize auditing of the operations performed on your machines by viewing the API activity recorded in Amazon CloudTrail.
For information about using CloudTrail to monitor Systems Manager actions, see [Logging Amazon Systems Manager API calls with Amazon 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 Amazon Web Services 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.amazonaws.cn/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 Amazon 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. Amazon 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 Amazon Web Services account per Amazon Web Services 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 Amazon 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 Amazon Identity and Access Management (IAM) service role to communicate with the Amazon Systems Manager service. The role grants Amazon Security Token Service (Amazon STS) [https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html](https://docs.amazonaws.cn/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 Amazon Web Services 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 Amazon Web Services 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 Amazon Web Services services. For example, without access to the required Amazon 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.amazonaws.cn/iam/](https://console.amazonaws.cn/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 **Amazon Web Services service**.
1. For **Use cases for other Amazon Web Services services**, choose **Systems Manager**.
1. Choose **Systems Manager**.
.
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.amazonaws.cn/en_us/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 Amazon 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 Amazon 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 Amazon Web Services 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 Amazon Web Services services and VPC endpoint services powered by Amazon 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.
------
#### [ Amazon CLI ]
**To create an IAM service role for a hybrid and multicloud environment (Amazon CLI)**
1. Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already.
For information, see [Installing or updating the latest version of the Amazon CLI](https://docs.amazonaws.cn/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 Amazon Web Services account and the Amazon Web Services 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.cn"
},
"Action":"sts:AssumeRole",
"Condition":{
"StringEquals":{
"aws:SourceAccount":"123456789012"
},
"ArnEquals":{
"aws:SourceArn":"arn:aws-cn:ssm:us-east-1:111122223333:*"
}
}
}
]
}
```
------
1. Open the Amazon CLI, and in the directory where you created the JSON file, run the [create-role](https://docs.amazonaws.cn/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.amazonaws.cn/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 Amazon 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 Amazon Systems Manager service core functionality.
------
#### [ Linux & macOS ]
```
aws iam attach-role-policy \
--role-name SSMServiceRole \
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore
```
------
#### [ Windows ]
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore
```
------
If you created a custom S3 bucket policy for your service role, run the following command to allow Amazon Systems Manager Agent (SSM Agent) to access the buckets you specified in the policy. Replace *account-id* and *amzn-s3-demo-bucket* with your Amazon Web Services account ID and your bucket name.
------
#### [ Linux & macOS ]
```
aws iam attach-role-policy \
--role-name SSMServiceRole \
--policy-arn arn:aws-cn:iam::account-id:policy/amzn-s3-demo-bucket
```
------
#### [ Windows ]
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn:iam::account-id:policy/amzn-s3-demo-bucket
```
------
(Optional) Run the following command to allow SSM Agent to access Amazon 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-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
------
#### [ Windows ]
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn: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-cn:iam::aws:policy/CloudWatchAgentServerPolicy
```
------
#### [ Tools for PowerShell ]
**To create an IAM service role for a hybrid and multicloud environment (Amazon Tools for Windows PowerShell)**
1. Install and configure the Amazon Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.
For information, see [Installing the Amazon Tools for PowerShell](https://docs.amazonaws.cn/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 Amazon Web Services account and the Amazon Web Services Region in the ARN where you created your hybrid activation.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com.cn"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws-cn: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.amazonaws.cn//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.amazonaws.cn/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 Amazon 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 Amazon Systems Manager service core functionality.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn: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 Amazon Web Services account ID and your bucket name.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn:iam::account-id:policy/my-bucket-policy-name
```
(Optional) Run the following command to allow SSM Agent to access Amazon 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-cn: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-cn: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 Amazon 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 Amazon CLI command [https://docs.amazonaws.cn/cli/latest/reference/ssm/deregister-managed-instance.html](https://docs.amazonaws.cn/cli/latest/reference/ssm/deregister-managed-instance.html)
+ Use the API action [https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html](https://docs.amazonaws.cn/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 Amazon Systems Manager. Amazon 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.amazonaws.cn/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 Amazon Command Line Interface (Amazon CLI) or Amazon 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 Amazon 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 Amazon 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 Amazon Web Services 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 Amazon Web Services Management Console to create an activation for registering managed nodes with Systems Manager
**To create a managed-node activation**
1. Open the Amazon Systems Manager console at [https://console.amazonaws.cn/systems-manager/](https://console.amazonaws.cn/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 Amazon Web Services 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 Amazon 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 Amazon 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 Amazon.
+ **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.cn"`. 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-cn:iam:::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 Amazon Command Line Interface (Amazon CLI) (on Linux or Windows Server) or Amazon Tools for PowerShell to create a managed node activation.
**To create an activation**
1. Install and configure the Amazon CLI or the Amazon Tools for PowerShell, if you haven't already.
For information, see [Installing or updating the latest version of the Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html) and [Installing the Amazon Tools for PowerShell](https://docs.amazonaws.cn/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.amazonaws.cn/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.cn"`. If your Amazon 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-cn:iam:::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 Amazon 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 Amazon Web Services 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 Amazon Web Services 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 Amazon Web Services Region supported by Amazon 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.amazonaws.cn/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://s3.cn-north-1.amazonaws.com.cn/amazon-ssm-cn-north-1/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://s3.cn-north-1.amazonaws.com.cn/amazon-ssm-cn-north-1/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
wget https://s3.cn-north-1.amazonaws.com.cn/amazon-ssm-cn-north-1/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://s3.cn-north-1.amazonaws.com.cn/amazon-ssm-cn-north-1/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 Amazon 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.amazonaws.cn/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html) API operation from either the Amazon 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.amazonaws.cn/cli/latest/reference/ssm/describe-activations.html) API using the Amazon 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 Amazon Web Services account as a managed node for a separate Amazon Web Services 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 Amazon 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 Amazon Web Services 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 Amazon Web Services Region supported by Amazon 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.amazonaws.cn/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 ]
```
$code = "activation-code"
$id = "activation-id"
$region = "region"
$dir = $env:TEMP + "\ssm"
New-Item -ItemType directory -Path $dir -Force
cd $dir
(New-Object System.Net.WebClient).DownloadFile("https://s3.cn-north-1.amazonaws.com.cn/amazon-ssm-cn-north-1/latest/windows_amd64/ssm-setup-cli.exe", $dir + "\ssm-setup-cli.exe")
Start-Process ./ssm-setup-cli.exe -ArgumentList @("-register", "-activation-code=$code", "-activation-id=$id", "-region=$region") -Wait
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 Amazon 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 Amazon CLI command [https://docs.amazonaws.cn/cli/latest/reference/ssm/describe-instance-information.html](https://docs.amazonaws.cn/cli/latest/reference/ssm/describe-instance-information.html), or by using the API command [https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_DescribeInstanceInformation.html](https://docs.amazonaws.cn/systems-manager/latest/APIReference/API_DescribeInstanceInformation.html).
## Setting up private key auto rotation
To strengthen your security posture, you can configure Amazon 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.amazonaws.cn/systems-manager/latest/APIReference/API_DeregisterManagedInstance.html) API operation from either the Amazon 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.amazonaws.cn/cli/latest/reference/ssm/describe-activations.html) API using the Amazon 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
```
# Managing edge devices with Systems Manager
This section describes the setup tasks that account and system administrators perform to enable configuration and management of Amazon IoT Greengrass core devices. After you complete these tasks, users who have been granted permissions by the Amazon Web Services account administrator can use Amazon Systems Manager to configure and manage their organization's Amazon IoT Greengrass core devices.
**Note**
SSM Agent for Amazon IoT Greengrass isn't supported on macOS and Windows 10. You can't use Systems Manager tools to manage and configure edge devices that use these operating systems.
Systems Manager also supports edge devices that aren't configured as Amazon IoT Greengrass core devices. To use Systems Manager to manage Amazon IoT Core devices and non-Amazon edge devices, you must configure them using a hybrid activation. For more information, see [Managing nodes in hybrid and multicloud environments with Systems Manager](systems-manager-hybrid-multicloud.md).
To use Session Manager and Microsoft application patching with your edge devices, you must enable the advanced-instances tier. For more information, see [Turning on the advanced-instances tier](fleet-manager-enable-advanced-instances-tier.md).
**Before you begin**
Verify that your edge devices meet the following requirements.
+ Your edge devices must meet the requirements to be configured as Amazon IoT Greengrass core devices. For more information, see [Setting up Amazon IoT Greengrass core devices](https://docs.amazonaws.cn/greengrass/v2/developerguide/setting-up.html) in the *Amazon IoT Greengrass Version 2 Developer Guide*.
+ Your edge devices must be compatible with Amazon Systems Manager Agent (SSM Agent). For more information, see [Supported operating systems for Systems Manager](operating-systems-and-machine-types.md#prereqs-operating-systems).
+ Your edge devices must be able to communicate with the Systems Manager service in the cloud. Systems Manager doesn't support disconnected edge devices.
**About setting up edge devices**
Setting up Amazon IoT Greengrass devices for Systems Manager involves the following processes.
**Note**
For information about uninstalling SSM Agent from an edge device, see [Uninstall the Amazon Systems Manager Agent](https://docs.amazonaws.cn/greengrass/v2/developerguide/uninstall-systems-manager-agent.html) in the *Amazon IoT Greengrass Version 2 Developer Guide*.
## Create an IAM service role for your edge devices
Amazon IoT Greengrass core devices require an Amazon Identity and Access Management (IAM) service role to communicate with Amazon Systems Manager. The role grants Amazon Security Token Service (Amazon STS) [https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html](https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html) trust to the Systems Manager service. You only need to create the service role once for each Amazon Web Services account. You will specify this role for the `RegistrationRole` parameter when you configure and deploy the SSM Agent component to your Amazon IoT Greengrass devices. If you already created this role while setting up non-EC2 nodes for a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment, you can skip this step.
**Note**
Users in your company or organization who will use Systems Manager on your edge devices must be granted permission in IAM to call the Systems Manager API.
**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 Amazon Web Services services and VPC endpoint services powered by Amazon PrivateLink.
+ **Case 2**: You plan to use an 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.
**Note**
If your devices are protected by a firewall and you plan to use Patch Manager, the firewall must allow access to the patch baseline endpoint `arn:aws-cn:s3:::patch-baseline-snapshot-region/*`.
*region* represents the identifier for an Amazon Web Services Region supported by Amazon 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.amazonaws.cn/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
------
#### [ Amazon CLI ]
**To create an IAM service role for an Amazon IoT Greengrass environment (Amazon CLI)**
1. Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already.
For information, see [Installing or updating the latest version of the Amazon CLI](https://docs.amazonaws.cn/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.
**Note**
Make a note of the name. You will specify it when you deploy SSM Agent to your Amazon IoT Greengrass core devices.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com.cn"
},
"Action": "sts:AssumeRole"
}
}
```
------
1. Open the Amazon CLI, and in the directory where you created the JSON file, run the [create-role](https://docs.amazonaws.cn/cli/latest/reference/iam/create-role.html) command to create the service role. Replace each *example resource placeholder* with your own information.
**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.amazonaws.cn/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 edge devices permission to run commands using Systems Manager.
**Note**
The policies you add for a service profile for edge devices are the same policies used to create an instance profile for Amazon Elastic Compute Cloud (Amazon EC2) instances. For more information about the IAM 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 an edge device to use Amazon Systems Manager service core functionality.
**Linux & macOS**
```
aws iam attach-role-policy \
--role-name SSMServiceRole \
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore
```
**Windows**
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore
```
If you created a custom S3 bucket policy for your service role, run the following command to allow Amazon Systems Manager Agent (SSM Agent) to access the buckets you specified in the policy. Replace *account\$1ID* and *my\$1bucket\$1policy\$1name* with your Amazon Web Services account ID and your bucket name.
**Linux & macOS**
```
aws iam attach-role-policy \
--role-name SSMServiceRole \
--policy-arn arn:aws-cn:iam::account_ID:policy/my_bucket_policy_name
```
**Windows**
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn:iam::account_id:policy/my_bucket_policy_name
```
(Optional) Run the following command to allow SSM Agent to access Amazon Directory Service on your behalf for requests to join the domain from edge devices. The service role needs this policy only if you join your edge devices to a Microsoft AD directory.
**Linux & macOS**
```
aws iam attach-role-policy \
--role-name SSMServiceRole \
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
**Windows**
```
aws iam attach-role-policy ^
--role-name SSMServiceRole ^
--policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
(Optional) Run the following command to allow the CloudWatch agent to run on your edge devices. This command makes it possible to read information on a device and write it to CloudWatch. Your service role 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-cn:iam::aws:policy/CloudWatchAgentServerPolicy
```
------
#### [ Tools for PowerShell ]
**To create an IAM service role for an Amazon IoT Greengrass environment (Amazon Tools for Windows PowerShell)**
1. Install and configure the Amazon Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.
For information, see [Installing the Amazon Tools for PowerShell](https://docs.amazonaws.cn/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.
**Note**
Make a note of the name. You will specify it when you deploy SSM Agent to your Amazon IoT Greengrass core devices.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com.cn"
},
"Action": "sts:AssumeRole"
}
}
```
------
1. Open PowerShell in administrative mode, and in the directory where you created the JSON file, run [New-IAMRole](https://docs.amazonaws.cn//powershell/latest/reference/items/Register-IAMRolePolicy.html) as follows to create a service role.
```
New-IAMRole `
-RoleName SSMServiceRole `
-AssumeRolePolicyDocument (Get-Content -raw SSMService-Trust.json)
```
1. Use [Register-IAMRolePolicy](https://docs.amazonaws.cn/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 edge devices permission to run commands using Systems Manager.
**Note**
The policies you add for a service role for edge devices in an Amazon IoT Greengrass environment are the same policies used to create an instance profile for EC2 instances. For more information about the Amazon 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 an edge device to use Amazon Systems Manager service core functionality.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn: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\$1ID* and *my\$1bucket\$1policy\$1name* with your Amazon Web Services account ID and your bucket name.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn:iam::account_ID:policy/my_bucket_policy_name
```
(Optional) Run the following command to allow SSM Agent to access Amazon Directory Service on your behalf for requests to join the domain from edge devices. The service role needs this policy only if you join your edge devices to a Microsoft AD directory.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
(Optional) Run the following command to allow the CloudWatch agent to run on your edge devices. This command makes it possible to read information on a device and write it to CloudWatch. Your service role needs this policy only if you will use services such as Amazon EventBridge or Amazon CloudWatch Logs.
```
Register-IAMRolePolicy `
-RoleName SSMServiceRole `
-PolicyArn arn:aws-cn:iam::aws:policy/CloudWatchAgentServerPolicy
```
------
## Configure your edge devices for Amazon IoT Greengrass
Set up your edge devices as Amazon IoT Greengrass core devices. The setup process involves verifying supported operating systems and system requirements, as well as installing and configuring the Amazon IoT Greengrass Core software on your devices. For more information, see [Setting up Amazon IoT Greengrass core devices](https://docs.amazonaws.cn/greengrass/v2/developerguide/setting-up.html) in the *Amazon IoT Greengrass Version 2 Developer Guide*.
## Update the Amazon IoT Greengrass token exchange role and install SSM Agent on your edge devices
The final step for setting up and configuring your Amazon IoT Greengrass core devices for Systems Manager requires you to update the Amazon IoT Greengrass Amazon Identity and Access Management (IAM) device service role, also called the *token exchange role*, and deploy Amazon Systems Manager Agent (SSM Agent) to your Amazon IoT Greengrass devices. For information about these processes, see [Install the Amazon Systems Manager Agent](https://docs.amazonaws.cn/greengrass/v2/developerguide/install-systems-manager-agent.html) in the *Amazon IoT Greengrass Version 2 Developer Guide*.
After you deploy SSM Agent to your devices, Amazon IoT Greengrass automatically registers your devices with Systems Manager. No additional registration is necessary. You can begin using Systems Manager tools to access, manage, and configure your Amazon IoT Greengrass devices.
**Note**
Your edge devices must be able to communicate with the Systems Manager service in the cloud. Systems Manager doesn't support disconnected edge devices.
# Creating an Amazon Organizations delegated administrator for Systems Manager
**Change Manager availability change**
Amazon Systems Manager Change Manager will no longer be open to new customers starting November 7, 2025. If you would like to use Change Manager, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [Amazon Systems Manager Change Manager availability change](https://docs.amazonaws.cn/systems-manager/latest/userguide/change-manager-availability-change.html).
When you set up an organization in Amazon Organizations, you assign a management account to perform all administrative tasks for all Amazon Web Services services. The management account user can assign a *delegated administrator account* only for Systems Manager to perform administrative tasks for Change Manager, Explorer, and OpsCenter. Amazon Organizations is an account management service that you can use to create an organization and assign Amazon Web Services accounts to manage these accounts centrally. For information about Amazon Organizations, see [Amazon Organizations](https://docs.amazonaws.cn/organizations/latest/userguide/orgs_introduction.html) in the *Amazon Organizations User Guide*.
Change Manager, Explorer, and OpsCenter, tools in Amazon Systems Manager, work with Amazon Organizations to perform tasks on all member accounts of your organization. You can assign only one delegated administrator for all Systems Manager tools. The delegated administrator account must be a member of the organization to which it's assigned.
**Topics**
+ [
## Using a delegated administrator with Change Manager
](#setting_up_delegated_administrator_change_manager)
+ [
## Using a delegated administrator with Explorer
](#setting_up_delegated_administrator_explorer)
+ [
## Using a delegated administrator with OpsCenter
](#setting_up_delegated_administrator_opscenter)
+ [
## Using a delegated administrator with Quick Setup
](#setting_up_delegated_administrator_quick_setup)
## Using a delegated administrator with Change Manager
Change Manager is an enterprise change management framework for requesting, approving, implementing, and reporting on operational changes to your application configuration and infrastructure.
If you use Change Manager across an organization, assign a delegated administrator account to manage change templates, approvals, and reporting for all member accounts. Using Quick Setup, you can set up Change Manager to use with an organization and select the delegated administrator account. If you use Change Manager with a single Amazon Web Services account, the delegated administrator account isn't required.
By default, Change Manager displays all change-related tasks in the delegated administrator account. For instructions on configuring a delegated administrator while setting up Change Manager for an organization, see [Setting up Change Manager for an organization (management account)](change-manager-organization-setup.md).
**Important**
If you use Change Manager across an organization, we recommend always making changes from the delegated administrator account. Although you can make changes from other accounts in the organization, those changes won't be reported in or viewable from the delegated administrator account.
## Using a delegated administrator with Explorer
Explorer is a customizable operations dashboard that reports aggregated view of operations data (OpsData) for your Amazon Web Services accounts, across Amazon Web Services Regions.
You can configure a delegated administrator account for Systems Manager to aggregate Explorer data from multiple Regions and accounts by using resource data sync with Amazon Organizations. A delegated administrator can search, filter, and aggregate Explorer data using the Amazon Web Services Management Console, the Amazon Command Line Interface (Amazon CLI), or Amazon Tools for Windows PowerShell.
When you use a delegated administrator account for Explorer, you limit the number of administrators who can create or delete multi-account and Region resource data syncs to an individual Amazon Web Services account.
You can synchronize operations data across all Amazon Web Services accounts in your organization by using Explorer. For information on how to assign a delegated administrator from Explorer, see [Configuring a delegated administrator for Explorer](Explorer-setup-delegated-administrator.md).
## Using a delegated administrator with OpsCenter
OpsCenter provides a central location where operations engineers and IT professionals can manage operational work items (OpsItems) related to Amazon resources. If you want to use OpsCenter to manage OpsItems centrally across accounts, you must set up the organization in Amazon Organizations.
Using Quick Setup for OpsCenter, you can assign a delegated administrator account and configure OpsCenter to manage OpsItems centrally. For more information, see [(Optional) Configure OpsCenter to manage OpsItems across accounts by using Quick Setup](OpsCenter-quick-setup-cross-account.md).
## Using a delegated administrator with Quick Setup
Quick Setup is a tool in Systems Manager that helps you to quickly configure frequently used Amazon services and features with recommended best practices. You can configure a delegated administrator account for Quick Setup to help you deploy and manage configurations across accounts and Regions using Amazon Organizations. A delegated administrator for Quick Setup can create, update, view, and delete configuration manager resources in your organization. Systems Manager registers a delegated administrator for Quick Setup as part of the setup process for the integrated console experience. For more information, see [Setting up Systems Manager unified console for an organization](systems-manager-setting-up-organizations.md).
## General setup for Amazon Systems Manager
If you haven't already done so, sign up for an Amazon Web Services account and create an administrative user.
### Sign up for an Amazon Web Services account
If you do not have an Amazon Web Services account, use the following procedure to create one.
**To sign up for Amazon Web Services**
1. Open [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choose **Sign Up**.
1. Follow the on-screen instructions.
Amazon sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [http://www.amazonaws.cn/](http://www.amazonaws.cn/) and choosing **My Account**.
### Secure IAM users
After you sign up for an Amazon Web Services account, safeguard your administrative user by turning on multi-factor authentication (MFA). For instructions, see [Enable a virtual MFA device for an IAM user (console)](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-iam-user) in the *IAM User Guide*.
To give other users access to your Amazon Web Services account resources, create IAM users. To secure your IAM users, turn on MFA and only give the IAM users the permissions needed to perform their tasks.
For more information about creating and securing IAM users, see the following topics in the *IAM User Guide*:
+ [Creating an IAM user in your Amazon Web Services account](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_create.html)
+ [Access management for Amazon resources](https://docs.amazonaws.cn/IAM/latest/UserGuide/access.html)
+ [Example IAM identity-based policies](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_examples.html)