Manage the Default Host Management Configuration setting (console)Manage the Default Host Management Configuration setting (command line)Least privilege policy examples for Default Host Management Configuration

Default Host Management Configuration

The Default Host Management Configuration feature allows AWS Systems Manager to manage your Amazon EC2 instances automatically as managed instances. A managed instance is an EC2 instance that is configured for use with Systems Manager. The benefits of managing your instances with Systems Manager include the following:

Connect to your EC2 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 SSM Agent up to date automatically.

Fleet Manager, Inventory, Patch Manager, and Session Manager are capabilities of Systems Manager.

Default Host Management Configuration makes it possible to manage EC2 instances without your having to manually create an AWS Identity and Access Management (IAM) instance profile. Instead, Default Host Management Configuration creates and applies a default IAM role to ensure that Systems Manager has permissions to manage all instances in the Region and account where it's activated.

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 AWS managed policy: AmazonSSMManagedEC2InstanceDefaultPolicy.

Prerequisites

In order to use Default Host Management Configuration in the AWS Region and AWS account where you activate the feature, the following requirements must be met.

An instance to be managed must use Instance Metadata Service Version 2 (IMDSv2).

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 in the Amazon EC2 User Guide for Linux Instances
SSM Agent version 3.2.582.0 or later must be installed on the instance to be managed.

For information about checking the version of SSM Agent installed on your instance, see Checking the SSM Agent version number.

For information about updating SSM Agent, see Automatically updating SSM Agent.

You, as the administrator performing the tasks in this topic, must have permissions for the GetServiceSetting, ResetServiceSetting, and UpdateServiceSetting API operations. Additionally, you must have permissions for the iam:PassRole permission for the AWSSystemsManagerDefaultEC2InstanceManagementRole IAM role. The following is an example policy providing these permissions. Replace each example resource placeholder with your own information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetServiceSetting",
                "ssm:ResetServiceSetting",
                "ssm:UpdateServiceSetting"
            ],
            "Resource": "arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::account-id:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": [
                        "ssm.amazonaws.com"
                    ]
                }
            }
        }
    ]
}

If an IAM instance profile is already attached to an EC2 instance be be managed, you must remove any permissions from it that allow the ssm:UpdateInstanceInformation operation. 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 own IAM instance profile, the instance will not use the Default Host Management Configuration permissions.

Implement least privilege access

This procedures in this topic are intended to be performed only by administrators. Therefore, we recommend implementing least privilege access in order to prevent non-administrative users from configuring or modifying the Default Host Management Configuration. To view example policies that restrict access to the Default Host Management Configuration, see Least privilege policy examples for Default Host Management Configuration later in this topic.

Topics

Manage the Default Host Management Configuration setting (console)
Manage the Default Host Management Configuration setting (command line)
Least privilege policy examples for Default Host Management Configuration

Manage the Default Host Management Configuration setting (console)

You can activate and deactivate the Default Host Management Configuration from the Fleet Manager console.

To activate Default Host Management Configuration (console)

Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
In the navigation pane, choose Fleet Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the navigation pane, and then choose Fleet Manager in the navigation pane.
Choose Default Host Management Configuration under the Account management dropdown.
Turn on Enable Default Host Management Configuration.
Choose the AWS Identity and Access Management (IAM) role used to enable Systems Manager capabilities 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.
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.

To deactivate Default Host Management Configuration (console)

Note

If you deactivate Default Host Management Configuration, and you have not attached an instance profile to your Amazon EC2 instances that allows access to Systems Manager, they will no longer be managed by Systems Manager. You must turn off the Default Host Management Configuration setting in each Region where you no longer want your your Amazon EC2 instances managed automatically. Deactivating it in one Region doesn't deactivate it in all Regions.

Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
In the navigation pane, choose Fleet Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the navigation pane, and then choose Fleet Manager in the navigation pane.
Choose Default Host Management Configuration under the Account management dropdown.
Turn off Enable Default Host Management Configuration.
Choose Configure to disable Default Host Management Configuration.

Manage the Default Host Management Configuration setting (command line)

You can use the AWS Command Line Interface or AWS Tools for Windows PowerShell to activate and deactivate the Default Host Management Configuration.

To activate Default Host Management Configuration (command line)

Create a JSON file on your local machine containing the following trust relationship policy.


{
    "Version":"2012-10-17",
    "Statement":[
        {
            "Sid":"",
            "Effect":"Allow",
            "Principal":{
                "Service":"ssm.amazonaws.com"
            },
            "Action":"sts:AssumeRole"
        }
    ]
}

Open the AWS CLI or Tools for Windows PowerShell and run one of the following commands, depending on the operating system type of your local machine, to create a service role in your account. Replace each example resource placeholder with your own information.

Run the following command to attach the AmazonSSMManagedEC2InstanceDefaultPolicy managed policy to your newly created role. Replace each example resource placeholder with your own information.

Open the AWS CLI or Tools for Windows PowerShell and run the following command. Replace each example resource placeholder with your own information.

There is no output if the command succeeds.

Run the following command to view the current service settings for Default Host Management Configuration in the current AWS account and AWS Region.

The command returns information like the following.

{
    "ServiceSetting": {
        "SettingId": "/ssm/managed-instance/default-ec2-instance-management-role",
        "SettingValue": "service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
        "LastModifiedDate": "2022-11-28T08:21:03.576000-08:00",
        "LastModifiedUser": "System",
        "ARN": "arn:aws:ssm:us-east-2:-123456789012:servicesetting/ssm/managed-instance/default-ec2-instance-management-role",
        "Status": "Custom"
    }
}

To deactivate Default Host Management Configuration (command line)

Open the AWS CLI or Tools for Windows PowerShell and run the following command. Replace each example resource placeholder with your own information.

Least privilege policy examples for Default Host Management Configuration

The following sample policies demonstrate how to prevent members of your organization from making changes to the Default Host Management Configuration setting in your account.

Service control policy for AWS Organizations

The following policy demonstrates how to prevent non-administrative members in your AWS Organizations from updating your Default Host Management Configuration setting. Replace each example resource placeholder with your own information.


{
    "Version":"2012-10-17",
    "Statement":[
        {
            "Effect":"Deny",
            "Action":[
                "ssm:UpdateServiceSetting",
                "ssm:ResetServiceSetting"
            ],
            "Resource":"arn:aws:ssm:*:*:servicesetting/ssm/managed-instance/default-ec2-instance-management-role",
            "Condition":{
                "StringNotEqualsIgnoreCase":{
                "aws:PrincipalTag/job-function":[
                    "administrator"
                ]
                }
            }
        },
        {
            "Effect":"Deny",
            "Action":[
                "iam:PassRole"
            ],
            "Resource":"arn:aws:iam::*:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
            "Condition":{
                "StringEquals":{
                "iam:PassedToService":"ssm.amazonaws.com"
                },
                "StringNotEqualsIgnoreCase":{
                "aws:PrincipalTag/job-function":[
                    "administrator"
                ]
                }
            }
        },
        {
            "Effect":"Deny",
            "Resource":"arn:aws:iam::*:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
            "Action":[
                "iam:AttachRolePolicy",
                "iam:DeleteRole"
            ],
            "Condition":{
                "StringNotEqualsIgnoreCase":{
                "aws:PrincipalTag/job-function":[
                    "administrator"
                ]
                }
            }
        }
    ]
}

Policy for IAM principals

The following policy demonstrates how to prevent IAM groups, roles, or users in your AWS Organizations from updating your Default Host Management Configuration setting. Replace each example resource placeholder with your own information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": [
                "ssm:UpdateServiceSetting",
                "ssm:ResetServiceSetting"
            ],
            "Resource": "arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
        },
        {
            "Effect": "Deny",
            "Action": [
                "iam:AttachRolePolicy",
                "iam:DeleteRole",
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::account-id:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole"
        }
    ]
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Troubleshooting managed node availability using ssm-cli

Connect to a managed node using Remote Desktop