• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # Working with SSM Agent AWS Systems Manager Agent (SSM Agent) is Amazon software that runs on Amazon Elastic Compute Cloud (Amazon EC2) instances, edge devices, on-premises servers, and virtual machines (VMs). SSM Agent makes it possible for Systems Manager to update, manage, and configure these resources. The agent processes requests from the Systems Manager service in the AWS Cloud, and then runs them as specified in the request. SSM Agent then sends status and execution information back to the Systems Manager service by using the [https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmessagegatewayservice.html](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmessagegatewayservice.html) (`ssmmessages`). (In AWS Regions launched before 2024, status and execution information might also be sent back by the [https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmessagedeliveryservice.html](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmessagedeliveryservice.html) (service prefix: `ec2messages`).) If you monitor traffic, you will see that your managed nodes communicate with `ssmmessages.*` endpoints and possibly `ec2messages.*` endpoints. For more information, see [Reference: ec2messages, ssmmessages, and other API operations](systems-manager-setting-up-messageAPIs.md). For information about porting SSM Agent logs to Amazon CloudWatch Logs, see [Logging and monitoring in AWS Systems Manager](monitoring.md). **Topics** + [ # Learn technical details about the SSM Agent ](ssm-agent-technical-details.md) + [ # Find AMIs with the SSM Agent preinstalled ](ami-preinstalled-agent.md) + [ # Working with SSM Agent on EC2 instances for Linux ](ssm-agent-linux.md) + [ # Working with SSM Agent on EC2 instances for macOS ](ssm-agent-macos.md) + [ # Working with SSM Agent on EC2 instances for Windows Server ](ssm-agent-windows.md) + [ # Checking SSM Agent status and starting the agent ](ssm-agent-status-and-restart.md) + [ # Checking the SSM Agent version number ](ssm-agent-get-version.md) + [ # Viewing SSM Agent logs ](ssm-agent-logs.md) + [ # Restricting access to root-level commands through SSM Agent ](ssm-agent-restrict-root-level-commands.md) + [ # Automating updates to SSM Agent ](ssm-agent-automatic-updates.md) + [ # Subscribing to SSM Agent notifications ](ssm-agent-subscribe-notifications.md) + [ # Troubleshooting SSM Agent ](troubleshooting-ssm-agent.md) # Learn technical details about the SSM Agent Use the information in this topic to help you implement AWS Systems Manager Agent (SSM Agent) and understand how the agent works. **Topics** + [ ## SSM Agent version 3.2.x.x credential behavior ](#credentials-file) + [ ## SSM Agent credentials precedence ](#credentials-precedence) + [ ## Configuring SSM Agent for use with the Federal Information Processing Standard (FIPS) ](#fips-compliant-configurations) + [ ## About the local ssm-user account ](#ssm-user-account) + [ ## SSM Agent and the Instance Metadata Service (IMDS) ](#imds) + [ ## Keeping SSM Agent up-to-date ](#updating) + [ ## Ensuring that the SSM Agent installation directory is not modified, moved, or deleted ](#installation-directory) + [ ## SSM Agent rolling updates by AWS Regions ](#rolling-updates) + [ ## SSM Agent communications with AWS managed S3 buckets ](#ssm-agent-minimum-s3-permissions) + [ ## SSM Agent on GitHub ](#github) + [ ## Understanding SSM Agent hibernation ](#ssm-agent-hibernation) ## SSM Agent version 3.2.x.x credential behavior SSM Agent stores a set of temporary credentials at `/var/lib/amazon/ssm/credentials` (for Linux and macOS) or `%PROGRAMFILES%\Amazon\SSM\credentials` (for Windows Server) when an instance is onboarded using the Default Host Management Configuration in Quick Setup. The temporary credentials have the permissions you specify for the IAM role you chose for Default Host Management Configuration. On Linux, only the root account can access these credentials. On Windows Server, only the SYSTEM account and local Administrators can access these credentials. ## SSM Agent credentials precedence This topic describes important information about how SSM Agent is granted permission to perform actions on your resources. **Note** Support for edge devices differs slightly. You must configure your edge devices to use AWS IoT Greengrass Core software, configure an AWS Identity and Access Management (IAM) service role, and deploy SSM Agent to your devices by using AWS IoT Greengrass. For more information, see [Managing edge devices with Systems Manager](systems-manager-setting-up-edge-devices.md). When SSM Agent is installed on a machine, it requires permissions in order to communicate with the Systems Manager service. On Amazon Elastic Compute Cloud (Amazon EC2) instances, these permissions are provided in an instance profile that is attached to the instance. On a non-EC2 machine, SSM Agent normally gets the needed permissions from the shared credentials file, located at `/root/.aws/credentials` (Linux and macOS) or `%USERPROFILE%\.aws\credentials` (Windows Server). The needed permissions are added to this file during the [hybrid activation](activations.md) process. If a hybrid-activated node is deregistered, the agent may enter hibernation mode. For more information, see [Understanding SSM Agent hibernation](#ssm-agent-hibernation). In rare cases, however, a machine might end up with permissions added to more than one of the locations where SSM Agent checks for permissions to run its tasks. For example, say that you have configured an EC2 instance to be managed by Systems Manager. That configuration includes attaching an instance profile. But then you decide to also use that instance for developer or end-user tasks and install the AWS Command Line Interface (AWS CLI) on it. This installation results in additional permissions being added to a credentials file on the instance. When you run a Systems Manager command on the instance, SSM Agent might try to use credentials different from the ones you expect it to use, such as from a credentials file instead of an instance profile. This is because SSM Agent looks for credentials in the order prescribed for the *default credential provider chain*. **Note** On Linux and macOS, SSM Agent runs as the root user. Therefore, the environment variables and credentials file that SSM Agent looks for in this process are those of the root user only (`/root/.aws/credentials`). SSM Agent doesn't look at the environment variables or credentials file of any other users on the instance during the search for credentials. The default provider chain looks for credentials in the following order: 1. Environment variables, if configured (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`). 1. Shared credentials file (`$HOME/.aws/credentials` for Linux and macOS or `%USERPROFILE%\.aws\credentials` for Windows Server) with permissions provided by, for example, a hybrid activation or an AWS CLI installation. 1. An AWS Identity and Access Management (IAM) role for tasks if an application is present that uses an Amazon Elastic Container Service (Amazon ECS) task definition or **RunTask** API operation. 1. An instance profile attached to an Amazon EC2 instance. 1. The IAM role chosen for Default Host Management Configuration. For related information, see the following topics: + Instance profiles for EC2 instances – [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) + Hybrid activations – [Create a hybrid activation to register nodes with Systems Manager](hybrid-activation-managed-nodes.md) + AWS CLI credentials – [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) in the *AWS Command Line Interface User Guide* + Default credential provider chain – [Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/latest/developer-guide/configuring-sdk.html#specifying-credentials) in the *AWS SDK for Go Developer Guide* **Note** This topic in the *AWS SDK for Go Developer Guide* describes the default provider chain in terms of the SDK for Go; however, the same principles apply to evaluating credentials for SSM Agent. ## Configuring SSM Agent for use with the Federal Information Processing Standard (FIPS) If you need to use Systems Manager with Federal Information Processing Standard (FIPS) 140-3 validated cryptographic modules, you can configure AWS Systems Manager Agent (SSM Agent) to use the FIPS endpoints in supported Regions. **To configure SSM Agent to connect to FIPS 140-3 endpoints** 1. Connect to your managed node. 1. Navigate to the directory that contains the `amazon-ssm-agent.json` file: + Linux: `/etc/amazon/ssm/` + macOS: `/opt/aws/ssm/` + Windows Server: `C:\Program Files\Amazon\SSM\` 1. Open the file named `amazon-ssm-agent.json` for editing. **Tip** If no `amazon-ssm-agent.json` file exists yet, 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. Add the following content to the file. Replace the *region* placeholder values with the appropriate Region code for your partition: ``` { ---Existing file content, if any--- "Mds": { "Endpoint": "ec2messages-fips.region.amazonaws.com", }, "Ssm": { "Endpoint": "ssm-fips.region.amazonaws.com", }, "Mgs": { "Endpoint": "ssmmessages-fips.region.amazonaws.com", "Region": "region" }, "S3": { "Endpoint": "s3-fips.dualstack.region.amazonaws.com", "Region": region" }, "Kms": { "Endpoint": "kms-fips.region.amazonaws.com" } } ``` Supported Regions include the following: + `us-east-1` for the US East (N. Virginia) Region + `us-east-2` for the US East (Ohio) Region + `us-west-1` for the US West (N. California) Region + `us-west-2` for the US West (Oregon) Region + `ca-west-1` for the Canada West (Calgary) Region 1. Save the file and 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) in the `amazon-ssm-agent` repository in GitHub. For more information about AWS support for FIPS, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/). ## About the local ssm-user account Starting with version 2.3.50.0 of SSM Agent, the agent creates a local user account called `ssm-user` and adds it to the `/etc/sudoers.d` directory (Linux and macOS) or to the Administrators group (Windows Server). On agent versions before 2.3.612.0, the account is created the first time SSM Agent starts or restarts after installation. On version 2.3.612.0 and later, the `ssm-user` account is created the first time a session is started on an instance. This `ssm-user` is the default OS user when a session starts in Session Manager, a tool in AWS Systems Manager. You can change the permissions by moving `ssm-user` to a less-privileged group or by changing the `sudoers` file. The `ssm-user` account isn't removed from the system when SSM Agent is uninstalled. On Windows Server, SSM Agent handles setting a new password for the `ssm-user` account when each session starts. No passwords are set for `ssm-user` on Linux managed instances. Starting with SSM Agent version 2.3.612.0, the `ssm-user` account isn't created automatically on Windows Server machines that are being used as domain controllers. To use Session Manager on a Windows Server domain controller, create the `ssm-user` account manually if it isn't already present, and assign Domain Administrator permissions to the user. **Important** In order for the `ssm-user` account to be created, the instance profile attached to the instance must provide the necessary permissions. For information, see [Step 2: Verify or add instance permissions for Session Manager](session-manager-getting-started-instance-profile.md). ## SSM Agent and the Instance Metadata Service (IMDS) Systems Manager relies on EC2 instance metadata to function correctly. Systems Manager can access instance metadata using either version 1 or version 2 of the Instance Metadata Service (IMDSv1 and IMDSv2). Your instance must be able to access IPv4 address of the instance metadata service: 169.254.169.254. For more information, see [Instance metadata and user data](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) in the *Amazon EC2 User Guide*. ## Keeping SSM Agent up-to-date An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. **Note** An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. Amazon Machine Images (AMIs) that include SSM Agent by default can take up to two weeks to be updated with the newest version of SSM Agent. We recommend that you configure even more frequent automated updates to SSM Agent. ## Ensuring that the SSM Agent installation directory is not modified, moved, or deleted SSM Agent is installed at `/var/lib/amazon/ssm/` (Linux and macOS) and `%PROGRAMFILES%\Amazon\SSM\` (Windows Server). These installation directories contain critical files and folders used by SSM Agent, such as a credentials file, resources for inter-process communication (IPC), and orchestration folders. Nothing within the installation directory should be modified, moved, or deleted. Otherwise, SSM Agent might cease to function properly. ## SSM Agent rolling updates by AWS Regions After an SSM Agent update is made available in its GitHub repository, it can take up to two weeks until the updated version is rolled out to all AWS Regions at different times. For this reason, you might receive the "Unsupported on current platform" or "updating amazon-ssm-agent to an older version, please turn on allow downgrade to proceed" error when trying to deploy a new version of SSM Agent in a Region. To determine the version of SSM Agent available to you, you can run a `curl` command. To view the version of the agent available in the global download bucket, run the following command. ``` curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/VERSION ``` To view the version of the agent available in a specific Region, run the following command, substituting *region* with the Region you're working in, such as `us-east-2` for the US East (Ohio) Region. ``` curl https://s3.region.amazonaws.com/amazon-ssm-region/latest/VERSION ``` You can also open the `VERSION` file directly in your browser without a `curl` command. ## SSM Agent communications with AWS managed S3 buckets In the course of performing various Systems Manager operations, AWS Systems Manager Agent (SSM Agent) accesses a number of Amazon Simple Storage Service (Amazon S3) buckets. These S3 buckets are publicly accessible, and by default, SSM Agent connects to them using `HTTP` calls. However, if you're using a virtual private cloud (VPC) endpoint in your Systems Manager operations, you must provide explicit permission in an Amazon Elastic Compute Cloud (Amazon EC2) instance profile for Systems Manager, or in a service role for non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. Otherwise, your resources can't access these public buckets. To grant your managed nodes access to these buckets when you are using a VPC endpoint, you create a custom Amazon S3 permissions policy, and then attach it to your instance profile (for EC2 instances) or your service role (for non-EC2 managed nodes). For information about using a virtual private cloud (VPC) endpoint in your Systems Manager operations, see [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](setup-create-vpc.md). **Note** These permissions only provide access to the AWS managed buckets required by SSM Agent. They don't provide the permissions that are necessary for other Amazon S3 operations. They also don't provide permission to your own S3 buckets. For more information, see the following topics: + [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) + [Create the IAM service role required for Systems Manager in hybrid and multicloud environments](hybrid-multicloud-service-role.md) + [Reference: Amazon S3 buckets for patching operations](patch-operations-s3-buckets.md) **Topics** + [ ### Required bucket permissions ](#ssm-agent-minimum-s3-permissions-required) + [ ### Example ](#ssm-agent-minimum-s3-permissions-example) + [ ### Validating hybrid-activated machines using a hardware fingerprint ](#fingerprint-validation) ### Required bucket permissions The following table describes each of the S3 buckets that SSM Agent might need to access for Systems Manager operations. **Note** *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. Amazon S3 permissions required by SSM Agent | S3 bucket ARN | Description | | --- | --- | | `arn:aws:s3:::aws-windows-downloads-region/*` | Required for some SSM documents that support only Windows Server operating systems, plus some for cross-platform support, such as `AWSEC2-ConfigureSTIG`. | | `arn:aws:s3:::amazon-ssm-region/*` | Required for updating SSM Agent installations. These buckets contain the SSM Agent installation packages, and the installation manifests that are referenced by the AWS-UpdateSSMAgent document and plugin. If these permissions aren't provided, the SSM Agent makes an HTTP call to download the update. | | arn:aws:s3:::aws-ssm-region/\$1 | Provides access to the S3 bucket containing modules required for use with Systems Manager documents (SSM Command documents), including both non-patching and patching operations. For example: arn:aws:s3:::aws-ssm-us-east-2/\$1. The following are some commonly used SSM documents that use modules from these buckets. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) | | `arn:aws:s3:::patch-baseline-snapshot-region/*` -or-`arn:aws:s3:::patch-baseline-snapshot-region-unique-suffix/*` | Provides access to the S3 bucket containing patch baseline snapshots. This is required if you use any of the following SSM Command documents: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) The buckets for most supported AWS Regions use the following format: `arn:aws:s3:::patch-baseline-snapshot-region` For some Regions, an additional unique suffix is included in the bucket name. For example, the bucket name for the Middle East (Bahrain) Region (me-south-1) is as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) For a complete list of patch baseline snapshot bucket names, see [Buckets containing AWS managed patch baseline snapshots](patch-operations-s3-buckets.md#aws-patch-manager-buckets-baseline-snapshots). 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. | | For Linux and Windows Server managed nodes: `arn:aws:s3:::aws-patch-manager-region-unique-suffix/*` For Amazon EC2 instances for macOS: `arn:aws:s3:::aws-patchmanager-macos-region-unique-suffix/*` | Provides access to the S3 bucket containing modules used by SSM Command documents for patching operations in Patch Manager. Each bucket name includes a unique suffix, such as `552881074` for buckets in the US East (Ohio) (us-east-2) Region: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) SSM documents The following are some commonly used SSM documents that use modules from these buckets. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) For complete lists of AWS managed S3 buckets for patching operations, see the following topics: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html) | | `arn:aws:s3:::region-birdwatcher-prod/*` | Required for Distributor operations. This bucket contains package manifests used by the `aws:configurePackage` plugin when installing or updating Distributor packages using documents such as `AWS-ConfigureAWSPackage`. If you are using a VPC endpoint, your S3 VPC endpoint policy must include access to this bucket. | ### Example The following example illustrates how to provide access to the S3 buckets required for Systems Manager operations in the US East (Ohio) Region (us-east-2). In most cases, you need to provide these permissions explicitly in an instance profile or service role only when using a VPC endpoint. **Important** We recommend that you avoid using wildcard characters (\$1) in place of specific Regions in this policy. For example, use `arn:aws:s3:::aws-ssm-us-east-2/*` and don't use `arn:aws: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` block for each Region. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObject", "Resource": [ "arn:aws:s3:::aws-windows-downloads-us-east-2/*", "arn:aws:s3:::amazon-ssm-us-east-2/*", "arn:aws:s3:::aws-ssm-us-east-2/*", "arn:aws:s3:::us-east-2-birdwatcher-prod/*", "arn:aws:s3:::patch-baseline-snapshot-us-east-2/*", "arn:aws:s3:::aws-patch-manager-us-east-2-552881074/*", "arn:aws:s3:::aws-patchmanager-macos-us-east-2-552881074/*" ] } ] } ``` ------ ### Validating hybrid-activated machines using a hardware fingerprint When non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment, SSM Agent gathers a number of system attributes (referred to as the *hardware hash*) and uses these attributes to compute a *fingerprint*. The fingerprint is an opaque string that the agent passes to certain Systems Manager APIs. This unique fingerprint associates the caller with a particular hybrid-activated managed node. The agent stores the fingerprint and hardware hash on the local disk in a location called the *Vault*. The agent computes the hardware hash and fingerprint when the machine is registered for use with Systems Manager. Then, the fingerprint is passed back to the Systems Manager service when the agent sends a `RegisterManagedInstance` command. Later, when sending a `RequestManagedInstanceRoleToken` command, the agent checks the fingerprint and hardware hash in the Vault to make sure that the current machine attributes match with the stored hardware hash. If the current machine attributes do match the hardware hash stored in the Vault, the agent passes in the fingerprint from the Vault to `RegisterManagedInstance`, resulting in a successful call. If the current machine attributes don't match the stored hardware hash, SSM Agent computes a new fingerprint, stores the new hardware hash and fingerprint in the Vault, and passes the new fingerprint to `RequestManagedInstanceRoleToken`.* This causes `RequestManagedInstanceRoleToken` to fail, and the agent won't be able to obtain a role token to connect to the Systems Manager service.* This failure is by design and is used as a verification step to prevent multiple managed nodes from communicating with the Systems Manager service as the same managed node. When comparing the current machine attributes to the hardware hash stored in the Vault, the agent uses the following logic to determine whether the old and new hashes match: + If the SID (system/machine ID) is different, then no match. + Otherwise, if the IP address is the same, then match. + Otherwise, the percentage of machine attributes that match is computed and compared with the user-configured similarity threshold to determine whether there is a match. The similarity threshold is stored in the Vault, as part of the hardware hash. The similarity threshold can be set after an instance is registered using a command like the following. On Linux machines: ``` sudo amazon-ssm-agent -fingerprint -similarityThreshold 1 ``` On Windows Server machines using PowerShell: ``` cd "C:\Program Files\Amazon\SSM\" ` .\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1 ``` **Important** If one of the components used to calculate the fingerprint changes, this can cause the agent to hibernate. To help avoid this hibernation, set the similarity threshold to a low value, such as **1**. For more information about hibernation, see [Understanding SSM Agent hibernation](#ssm-agent-hibernation). ## SSM Agent on GitHub The source code for SSM Agent is available on [https://github.com/aws/amazon-ssm-agent](https://github.com/aws/amazon-ssm-agent) so that you can adapt the agent to meet your needs. We encourage you to submit [pull requests](https://github.com/aws/amazon-ssm-agent/blob/mainline/CONTRIBUTING.md) for changes that you would like to have included. However, Amazon Web Services doesn't provide support for running modified copies of this software. ## Understanding SSM Agent hibernation AWS Systems Manager Agent (SSM Agent) hibernation is an operational mode that occurs when the agent can't maintain proper communication with the Systems Manager service. During hibernation, the agent reduces its communication frequency and enters a standby state. **When SSM Agent hibernation occurs** SSM Agent hibernation can occur in the following scenarios: Deregistered hybrid nodes When you deregister a [hybrid-activated node](hybrid-activation-managed-nodes.md) from Systems Manager, the SSM Agent on that node can't refresh its authorization token. This causes the agent to enter hibernation mode because it can't authenticate with the service. Hardware fingerprint changes SSM Agent uses a hardware fingerprint to validate hybrid-activated machines. If one of the components used to calculate this fingerprint changes significantly, the agent might hibernate as a security measure. This is by design to prevent multiple managed nodes from communicating with Systems Manager as the same node. For more information, see [Validating hybrid-activated machines using a hardware fingerprint](#fingerprint-validation). SSM Agent hibernation on Amazon EC2 instances Hibernation can also occur on Amazon EC2 instances under certain conditions, such as when there are connectivity issues or authentication problems with the Systems Manager service. **Hibernation communication behavior** When SSM Agent enters hibernation mode, its communication pattern with the Systems Manager service changes: + **Normal operation**: The agent regularly communicates with Systems Manager (typically every few minutes) to check for new commands and report status. + **Hibernation mode**: The ping frequency starts at 5 minutes and gradually increases to once per hour by default (configurable up to 24 hours). This reduced communication frequency helps minimize unnecessary network traffic while still allowing the agent to potentially recover if conditions change. During hibernation, the agent continues to retry authentication and connection attempts at the reduced frequency, but it can't process new commands or report detailed status information until hibernation is resolved. **Configuration options to prevent hibernation in hybrid instances** The primary configuration option to help prevent hibernation caused by hardware fingerprint changes is adjusting the similarity threshold: On Linux machines: ``` sudo amazon-ssm-agent -fingerprint -similarityThreshold 1 ``` On Windows Server machines using PowerShell: ``` cd "C:\Program Files\Amazon\SSM\" ` .\amazon-ssm-agent.exe -fingerprint -similarityThreshold 1 ``` The similarity threshold determines how strictly the agent compares current machine attributes with the stored hardware hash: + Higher values require more matching attributes + Lower values (such as **1**) are more lenient and can help avoid hibernation caused by minor hardware changes **Hibernation logging and monitoring** When SSM Agent enters hibernation mode, it creates log entries that can help you identify and troubleshoot the hibernation state: + **Agent log files**: Hibernation events are logged in the standard SSM Agent log files. For more information about log file locations, see [Troubleshoot issues using SSM Agent log files](troubleshooting-ssm-agent.md#systems-manager-ssm-agent-log-files). + **Amazon EC2 console logging**: For EC2 instances, hibernation messages are now logged to the Amazon EC2 console system logs, providing additional visibility into agent status. To access the logs, select the instance in the EC2 console, and then choose **Actions**, **Monitor and troubleshoot**, **Get system log**. + **Specific log files**: When hibernation starts, particular log files are created that contain detailed information about the hibernation trigger and status. Monitor these log sources to detect hibernation events early and take corrective action to restore normal agent operation. **Recovering from hibernation** To recover from hibernation, address the underlying cause: + **For deregistered hybrid nodes**: Reregister the node with Systems Manager using a new activation code and ID, as described in [Deregister and reregister a managed node (Linux)](hybrid-multicloud-ssm-agent-install-linux.md#systems-manager-install-managed-linux-deregister-reregister) and [Deregister and reregister a managed node (Windows Server)](hybrid-multicloud-ssm-agent-install-windows.md#systems-manager-install-managed-win-deregister-reregister). + **For hardware fingerprint issues**: Adjust the similarity threshold as described above under **Configuration options to prevent hibernation in hybrid instances**, or re-register the node if hardware changes are significant. + **For connectivity issues**: Verify network connectivity and make sure that the required endpoints are accessible. For more information, see [Troubleshooting managed node availability using `ssm-cli`](troubleshooting-managed-nodes-using-ssm-cli.md). After you resolve the underlying issue, the agent should automatically exit hibernation mode and resume normal operation at the next communication attempt. # Find AMIs with the SSM Agent preinstalled AWS Systems Manager Agent (SSM Agent) is preinstalled on some Amazon Machine Images (AMIs) provided by AWS and trusted third-parties. For example, when you launch an Amazon Elastic Compute Cloud (Amazon EC2) instance created from an AMI with one of the following operating systems, you'll likely find that the SSM Agent is already installed: + AlmaLinux + Amazon Linux 2 + Amazon Linux 2 ECS-Optimized Base AMIs + Amazon Linux 2023 (AL2023) + Amazon EKS-Optimized Amazon Linux AMIs + macOS 13.x (Ventura), 14.x (Sonoma), and 15.x (Sequoia) + SUSE Linux Enterprise Server (SLES) 15.3 and later + Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 24.04 LTS, 24.0, and 25.04 + Windows Server 2012 R2 AMIs published in November 2016 or later + Windows Server 2016, 2019, 2022 (excluding Nano versions), and 2025 **Note** The version of SSM Agent preinstalled on an AMI might not be the latest available version. As a best practice, we recommend always using the latest available version of SSM Agent on your managed nodes. For more information about automating SSM Agent updates, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). SSM Agent might be preinstalled on AWS managed AMIs that aren’t on this list. This typically indicates that the operating system (OS) is not fully supported by all Systems Manager tools. SSM Agent might also be preinstalled on AMIs found in AWS Marketplace or in the Community AMIs repository, but AWS doesn’t support these AMIs. ## Verify the status of SSM Agent Depending on when it was initialized, an instance created from an AMI on the preceding list might not have SSM Agent preinstalled. It's also possible that an instance has the agent preinstalled, but the agent isn't running. Therefore, we recommend that you check the status of SSM Agent before you try to use Systems Manager on an instance for the first time. Use the following procedure to verify that SSM Agent is installed and running on an instance. If you find that the agent is not installed, you can manually install it on [Linux, ](manually-install-ssm-agent-linux.md) [macOS](manually-install-ssm-agent-macos.md), and [Windows Server](manually-install-ssm-agent-windows.md) instances. **To verify installation of SSM Agent on an instance** 1. After launching a new instance, wait a few minutes for it to initialize. 1. Connect to the instance using your preferred method. For example, you can use SSH to connect to Linux instances or use Remote Desktop to connect to Windows Server instances. 1. Check the status of SSM Agent by running the command for your instance's operating system type. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ami-preinstalled-agent.html) **Tip** To view the commands for checking SSM Agent status on all operating system types supported by Systems Manager, see [Checking SSM Agent status and starting the agent](ssm-agent-status-and-restart.md). 1. Evaluate the command output to learn the status of the SSM Agent. **Status: *Installed and running*** In most cases, the command output indicates that the agent is installed and running. The following example shows that SSM Agent is installed and running on an Amazon Linux 2 instance. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2021-10-20 19:09:29 UTC; 4min 6s ago --truncated-- ``` The following example shows that SSM Agent is installed and running on a Windows Server instance. ``` Status Name DisplayName ------ ---- ----------- Running AmazonSSMAgent Amazon SSM Agent ``` **Status: *Installed but not running*** In some cases, the command output indicates that the agent is installed but not running. The following example shows that SSM Agent is installed but not running on an Amazon Linux 2 instance. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: inactive (dead) since Wed 2021-10-20 22:16:41 UTC; 18s ago --truncated-- ``` The following example shows that SSM Agent is installed but not running on a Windows Server instance. ``` Status Name DisplayName ------ ---- ----------- Stopped AmazonSSMAgent Amazon SSM Agent ``` If the agent is installed but not running, you can activate it manually using the commands for your instance's operating system type. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/ami-preinstalled-agent.html) **Status: *Not installed*** In some cases, the command output indicates that the agent is not installed. The following example shows that SSM Agent is not installed on an Amazon Linux 2 instance. ``` Unit amazon-ssm-agent.service could not be found. ``` The following example shows that SSM Agent is not installed on a Windows Server instance. ``` Get-Service : Cannot find any service with service name 'AmazonSSMAgent'. --truncated-- ``` If the agent isn't installed, you can install it manually using the procedure for your operating system type: + [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md) + [Manually installing and uninstalling SSM Agent on EC2 instances for macOS](manually-install-ssm-agent-macos.md) + [Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server](manually-install-ssm-agent-windows.md) # Working with SSM Agent on EC2 instances for Linux AWS Systems Manager Agent (SSM Agent) processes Systems Manager requests and configures your machine as specified in the request. Use the procedures in following topics to install, configure, or uninstall SSM Agent on Linux operating systems. **Topics** + [ # Verifying the signature of SSM Agent ](verify-agent-signature.md) + [ # Manually installing and uninstalling SSM Agent on EC2 instances for Linux ](manually-install-ssm-agent-linux.md) + [ # Configuring SSM Agent to use a proxy on Linux nodes ](configure-proxy-ssm-agent.md) # Verifying the signature of SSM Agent The AWS Systems Manager Agent (SSM Agent) deb and rpm installer packages for Linux instances are cryptographically signed. You can use a public key to verify that the agent package is original and unmodified. If the files are damaged or have been altered, the verification fails. You can verify the signature of the installer package using either RPM or GPG. The following information is for SSM Agent versions 3.1.1141.0 or later. To find the correct signature file for your instance's architecture and operating system, see the following table. *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. | Architecture | Operating system | Signature file URL | Agent download file name | | --- | --- | --- | --- | | x86\$164 | AlmaLinux, Amazon Linux 2, Amazon Linux 2023, RHEL, Oracle Linux, Rocky Linux | `https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm.sig` `https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm.sig` | `amazon-ssm-agent.rpm` | | x86\$164 | Debian Server, Ubuntu Server | `https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-agent.deb.sig` `https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb.sig` | amazon-ssm-agent.deb | | ARM64 | Amazon Linux 2, Amazon Linux 2023, RHEL | `https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm.sig` `https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm.sig` | amazon-ssm-agent.rpm | ## Verifying the SSM Agent package on a Linux server (v3.3.1802.0 and later) **Before you begin** The procedures for **GPG** and **RPM** in this section apply to SSM Agent version 3.3.1802.0 and later. Before verifying the signature of SSM Agent using the following procedure, ensure that you have downloaded the latest agent package for your operating system. For example, `https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm`. For more information about downloading SSM Agent packages, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). If you have a reason to continue using agent version 3.3.1611.0 or earlier, follow the instructions in [Verifying the SSM Agent package on a Linux server (v3.3.1611.0 and earlier)](#verify-agent-signature-previous) instead. ------ #### [ GPG ] **To verify the SSM Agent package on a Linux server (v3.3.1802.0 and later)** 1. Copy one the following public key and save it to a file named `amazon-ssm-agent.gpg`. **Important** The following public key expires on 2026-07-15 (July 15, 2026). Systems Manager will publish a new public key in this topic before the old one expires. We encourage you to subscribe to the RSS feed for this topic to get a notification when the new key is available. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2.0.22 (GNU/Linux) mQINBGeRNq4BEACrlf5h6Pz+k+M+QCJJ2LfK7d2Tn9J8iJ9qBK2Vwvuxco1rpSO+ KEI3nTeysPuheximps8WOCADX4VlbsKxMZQLjQM4mA26m1Tiw9nAI4kod4bKjiuM BMUTCD1wfnjH3zQi4kDUdbpfAEMiPgNLVLH85Wf+lhK+Zm+V38DYzLyVj03kX4wK iG6RMoxzOBZa5gNsVq+j+oCUITGz/URxH713Rgo8WeoEegI0+7iCBLKg+PM0b7GV 2nzkwWJz796HdkqSg8BwXsYaLTrHxa2P1IpwPCisAkyO7gZaMd6Uj69dtMFO+V8a Qee6b57qGuFKZw7h1Vvc85PbF1Gy/wNIpary57kUHBFUg1vYep/roJuEbJCq97r5 I2liLl4NAyrWb9r/TAVxlXvqM4iZUhxm8GAp0FywMdBr9ZECClKa5HxuVmlm0Wgl TXoYTOZKeDg6ZoCvyhNxWneCNip74fohXymeFF5L/budhBwy5wuwSniOgTGLo/4C VgZHWCcN+d0Q3bx/sl2QNqPg5/xzsxEtymXLdVdwLIsLdEQUnIvy8KTs5jol3Dwi nnEEyhly6wdaw+qDOhkSOT/VnErrSMkYF8VJfa5GjhCBWKw9JVSkaP2CI/VHOgHM MKROnulq0hRQBR7RmLYt98xu38BHJWMmF8Ga/HJuIxzD1VmkZOPvDDESUwARAQAB tCdTU00gQWdlbnQgPHNzbS1hZ2VudC1zaWduZXJAYW1hem9uLmNvbT6JAj8EEwEC ACkFAmeRNq4CGy8FCQLGmIAHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIXgAAKCRBR qOBQ0AUuXTdND/9qldQ1E3dYjBVXOnbhiUQL594bkS5VoEX7D4fZ5UMVZa5pGiz+ husnoRUS9rH1cSeq7aHJu9hSCMuMdvRpuoo0CwLB+7HtzJvAO2M01hcEkUYa6Qdj njTzP0ZjnoenJmqF9SYmVqAI/VPa9mNQ1OJ+HQ3qh5i6w+FoWlVqEdXjZGrWijub TqyN33i1Y26t7Os/x8I9fUeNx37y/7Kama8LTdtv9GhWiMVBg2IuVf27HCMYofrQ m2uCGe61IhtsnhsYaYupmljl+6qgdiuCiS9BAsoIGtqTnu8lnKcGyGz6YnRszN+U 1bNE4w+UFpXWJF8ogpYcghJ06aW/LhjZnQSx3VliLdW8eOJzou41yWmiuL3ZY8eW KAlD+7eYKS6N6fEJCeNO2VX2lcKtDfaOX+lqGIVyexKayMfpi+0frNzt/92YCpF5 3jkeS77vMMVqKIUiIp1OCGv3XsFpIr6Bt2c2throYPDoQL3zvq6vvG40BKeRQ4tT Y+5vTc8MeNn3LdzTl9pusxTcKifrJq7f5FIsL2CpAX8uQ+Qz+XWsYQQ5PvyUDtOz nU/MRZaP6HnqY42bzI9ZlKgXi9IE3MXIwoET9YyzFjkIDvat7SlB4uJCpeIqp/KM OIrTMb7paGLYmBU6YqxNBkDWItNG7NeZzyhh/R/Qqb4vJaf4S+ZqD1RZXokCHAQQ AQIABgUCZ5E2rwAKCRB90Jej2tf1/CdnD/46It+RNoE00TesZK5n2bijH5Eljw0E 4/UpMi1SV6t2zY7lIm7TcKNn18tynJNFqB6YXXOwSbBG/fbN2E9RaoUCZw23TmAv amuHwrfsDqsHb7zzPF0bISYjqEDLQJj/gtEugUc6XY1dEpFSlWJIOvgryG04cFXI uD2KY87ya4s1R+sEVAJ14K4RlUCiMmzJdR0NJNYJOwBi1gkLEp6jG86ttiG2U7fY pE2ibV+c0GeIFq8PIzqqENsn9KBuRH5EcbdBwfnsj2XfM4aR3ZtRIdWXkKkdP9Rs yU5dTF/Y7XPId5h8/gp00+DMlXFBinQ1jE7A7eDYviEFd1ba8P7dIom3Q3gzKiWu KTGpnykShs5NvpQmvGUF6JqDHI4RK9s3kLqsNyZkhenJfRBrJ/45fQAuP4CRedkF 7PSfX0Xp7kDnKuyK6wEUEfXXrqmuLGDmigTXblO5qgdyMwkOLjiY9znBZbHoKs76 VplOoNgGnN19i3nuMcPf2npFICJv7kTIyn5Fh7pjWDCahl3U/PwoLjrrlEzpyStU oXSZrK3kiAADEdSODXJl8KYU0Pb27JbRr1ZbWnxb+O39TOhtssstulkR0v+IDGDQ rQE1b12sKgcNFSzInzWrNGu4S06WN8DYzlrTZ9aSHj+37ZqpXAevi8WOFXKPV3PA E6+O8RI2451Dcg== =aDkv -----END PGP PUBLIC KEY BLOCK----- ``` 1. Import the public key into your keyring, and note the returned key value. ``` gpg --import amazon-ssm-agent.gpg ``` 1. Verify the fingerprint. Be sure to replace *key-value* with the value from the preceding step. We recommend that you use GPG to verify the fingerprint even if you use RPM to verify the installer package. ``` gpg --fingerprint key-value ``` This command returns output similar to the following: ``` pub 4096R/D0052E5D 2025-01-22 [expires: 2026-07-15] Key fingerprint = 4855 A9E6 8332 16D6 A77D 8FE4 51A8 E050 D005 2E5D uid SSM Agent ``` The fingerprint should match the following. `4855 A9E6 8332 16D6 A77D 8FE4 51A8 E050 D005 2E5D` If the fingerprint doesn't match, don't install the agent. Contact AWS Support. 1. Download the signature file according to your instance's architecture and operating system if you haven't already done so. 1. Verify the installer package signature. Be sure to replace the *signature-filename* and *agent-download-filename* with the values you specified when downloading the signature file and agent, as listed in the table earlier in this topic. ``` gpg --verify signature-filename agent-download-filename ``` For example, for the x86\$164 architecture on Amazon Linux 2: ``` gpg --verify amazon-ssm-agent.rpm.sig amazon-ssm-agent.rpm ``` This command returns output similar to the following: ``` gpg: Signature made Sat 08 Feb 2025 12:05:08 AM UTC using RSA key ID D0052E5D gpg: Good signature from "SSM Agent " gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 4855 A9E6 8332 16D6 A77D 8FE4 51A8 E050 D005 2E5D ``` If the output includes the phrase `BAD signature`, check whether you performed the procedure correctly. If you continue to get this response, contact Support and don't install the agent. The warning message about the trust doesn't mean that the signature isn't valid, only that you haven't verified the public key. A key is trusted only if you or someone who you trust has signed it. If the output includes the phrase `Can't check signature: No public key`, verify you downloaded SSM Agent version 3.1.1141.0 or later. ------ #### [ RPM ] **To verify the SSM Agent package on a Linux server (v3.3.1802.0 and later)** 1. Copy the following public key and save it to a file named `amazon-ssm-agent.gpg`. **Important** The following public key expires on 2026-07-15 (July 15, 2026). Systems Manager will publish a new public key in this topic before the old one expires. We encourage you to subscribe to the RSS feed for this topic to get a notification when the new key is available. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2.0.22 (GNU/Linux) mQINBGeRNq4BEACrlf5h6Pz+k+M+QCJJ2LfK7d2Tn9J8iJ9qBK2Vwvuxco1rpSO+ KEI3nTeysPuheximps8WOCADX4VlbsKxMZQLjQM4mA26m1Tiw9nAI4kod4bKjiuM BMUTCD1wfnjH3zQi4kDUdbpfAEMiPgNLVLH85Wf+lhK+Zm+V38DYzLyVj03kX4wK iG6RMoxzOBZa5gNsVq+j+oCUITGz/URxH713Rgo8WeoEegI0+7iCBLKg+PM0b7GV 2nzkwWJz796HdkqSg8BwXsYaLTrHxa2P1IpwPCisAkyO7gZaMd6Uj69dtMFO+V8a Qee6b57qGuFKZw7h1Vvc85PbF1Gy/wNIpary57kUHBFUg1vYep/roJuEbJCq97r5 I2liLl4NAyrWb9r/TAVxlXvqM4iZUhxm8GAp0FywMdBr9ZECClKa5HxuVmlm0Wgl TXoYTOZKeDg6ZoCvyhNxWneCNip74fohXymeFF5L/budhBwy5wuwSniOgTGLo/4C VgZHWCcN+d0Q3bx/sl2QNqPg5/xzsxEtymXLdVdwLIsLdEQUnIvy8KTs5jol3Dwi nnEEyhly6wdaw+qDOhkSOT/VnErrSMkYF8VJfa5GjhCBWKw9JVSkaP2CI/VHOgHM MKROnulq0hRQBR7RmLYt98xu38BHJWMmF8Ga/HJuIxzD1VmkZOPvDDESUwARAQAB tCdTU00gQWdlbnQgPHNzbS1hZ2VudC1zaWduZXJAYW1hem9uLmNvbT6JAj8EEwEC ACkFAmeRNq4CGy8FCQLGmIAHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIXgAAKCRBR qOBQ0AUuXTdND/9qldQ1E3dYjBVXOnbhiUQL594bkS5VoEX7D4fZ5UMVZa5pGiz+ husnoRUS9rH1cSeq7aHJu9hSCMuMdvRpuoo0CwLB+7HtzJvAO2M01hcEkUYa6Qdj njTzP0ZjnoenJmqF9SYmVqAI/VPa9mNQ1OJ+HQ3qh5i6w+FoWlVqEdXjZGrWijub TqyN33i1Y26t7Os/x8I9fUeNx37y/7Kama8LTdtv9GhWiMVBg2IuVf27HCMYofrQ m2uCGe61IhtsnhsYaYupmljl+6qgdiuCiS9BAsoIGtqTnu8lnKcGyGz6YnRszN+U 1bNE4w+UFpXWJF8ogpYcghJ06aW/LhjZnQSx3VliLdW8eOJzou41yWmiuL3ZY8eW KAlD+7eYKS6N6fEJCeNO2VX2lcKtDfaOX+lqGIVyexKayMfpi+0frNzt/92YCpF5 3jkeS77vMMVqKIUiIp1OCGv3XsFpIr6Bt2c2throYPDoQL3zvq6vvG40BKeRQ4tT Y+5vTc8MeNn3LdzTl9pusxTcKifrJq7f5FIsL2CpAX8uQ+Qz+XWsYQQ5PvyUDtOz nU/MRZaP6HnqY42bzI9ZlKgXi9IE3MXIwoET9YyzFjkIDvat7SlB4uJCpeIqp/KM OIrTMb7paGLYmBU6YqxNBkDWItNG7NeZzyhh/R/Qqb4vJaf4S+ZqD1RZXokCHAQQ AQIABgUCZ5E2rwAKCRB90Jej2tf1/CdnD/46It+RNoE00TesZK5n2bijH5Eljw0E 4/UpMi1SV6t2zY7lIm7TcKNn18tynJNFqB6YXXOwSbBG/fbN2E9RaoUCZw23TmAv amuHwrfsDqsHb7zzPF0bISYjqEDLQJj/gtEugUc6XY1dEpFSlWJIOvgryG04cFXI uD2KY87ya4s1R+sEVAJ14K4RlUCiMmzJdR0NJNYJOwBi1gkLEp6jG86ttiG2U7fY pE2ibV+c0GeIFq8PIzqqENsn9KBuRH5EcbdBwfnsj2XfM4aR3ZtRIdWXkKkdP9Rs yU5dTF/Y7XPId5h8/gp00+DMlXFBinQ1jE7A7eDYviEFd1ba8P7dIom3Q3gzKiWu KTGpnykShs5NvpQmvGUF6JqDHI4RK9s3kLqsNyZkhenJfRBrJ/45fQAuP4CRedkF 7PSfX0Xp7kDnKuyK6wEUEfXXrqmuLGDmigTXblO5qgdyMwkOLjiY9znBZbHoKs76 VplOoNgGnN19i3nuMcPf2npFICJv7kTIyn5Fh7pjWDCahl3U/PwoLjrrlEzpyStU oXSZrK3kiAADEdSODXJl8KYU0Pb27JbRr1ZbWnxb+O39TOhtssstulkR0v+IDGDQ rQE1b12sKgcNFSzInzWrNGu4S06WN8DYzlrTZ9aSHj+37ZqpXAevi8WOFXKPV3PA E6+O8RI2451Dcg== =aDkv -----END PGP PUBLIC KEY BLOCK----- ``` 1. Import the public key into your keyring, and note the returned key value. ``` rpm --import amazon-ssm-agent.gpg ``` 1. Verify the fingerprint. We recommend that you use GPG to verify the fingerprint even if you use RPM to verify the installer package. ``` rpm -qa gpg-pubkey --qf '%{Description}' | gpg --with-fingerprint | grep -A 1 "ssm-agent-signer@amazon.com" ``` This command returns output similar to the following: ``` pub 4096R/D0052E5D 2025-01-22 SSM Agent Key fingerprint = 4855 A9E6 8332 16D6 A77D 8FE4 51A8 E050 D005 2E5D ``` The fingerprint should match the following. `4855 A9E6 8332 16D6 A77D 8FE4 51A8 E050 D005 2E5D` If the fingerprint doesn't match, don't install the agent. Contact AWS Support. 1. Verify the installer package signature. Be sure to replace the *agent-download-filename* with the values you specified when downloading the agent, as listed in the table earlier in this topic. ``` rpm --checksig agent-download-filename ``` For example, for the x86\$164 architecture on Amazon Linux 2: ``` rpm --checksig amazon-ssm-agent.rpm ``` This command returns output similar to the following. ``` amazon-ssm-agent.rpm: rsa sha1 md5 OK ``` If `pgp` is missing from the output and you have imported the public key, then the agent isn't signed. If the output contains the phrase `NOT OK (MISSING KEYS: (MD5) key-id)`, check whether you performed the procedure correctly and verify you downloaded SSM Agent version 3.1.1141.0 or later. If you continue to get this response, contact Support and don't install the agent. ------ ## Verifying the SSM Agent package on a Linux server (v3.3.1611.0 and earlier) **Before you begin** The procedures for **GPG** and **RPM** in this section apply to SSM Agent version 3.3.1611.0 and earlier versions. We recommend always using the latest version of the agent. For information, see [Verifying the SSM Agent package on a Linux server (v3.3.1802.0 and later)](#verify-agent-signature-current). However, if you have a specific reason to continue using agent version 3.3.1611.0 or earlier, follow the instructions in one of the following procedures. ------ #### [ GPG ] **To verify the SSM Agent package on a Linux server (v3.3.1611.0 and earlier)** 1. Copy the following public keys and save it to a file named `amazon-ssm-agent.gpg`. **Important** The public key shown below expired on 2025-02-17 (February 17, 2025) and works for Version 3.3.1611.0 and earlier versions up to 3.2.1542.0, and only if it was used previously to verify the agent's signature. Systems Manager will publish a new public key in this topic before the old one expires. We encourage you to subscribe to the RSS feed for this topic to get a notification when the new key is available. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2.0.22 (GNU/Linux) mQENBGTtIoIBCAD2M1aoGIE0FXynAHM/jtuvdAVVaX3Q4ZejTqrX+Jq8ElAMhxyO GzHu2CDtCYxtVxXK3unptLVt2kGgJwNbhYC393jDeZx5dCda4Nk2YXX1UK3P461i axuuXRzMYvfM4RZn+7bJTu635tA07q9Xm6MGD4TCTvsjBfViOxbrxOg5ozWbJdSw fSR8MwUrRfmFpAefRlYfCEuZ8FHywa9U6jLeWt2O/kqrZliJOAGjGzXtB7EZkqKb faCCxikjjvhF1awdEqSK4DQorC/OvQc4I5kP5y2CJbtXvXO73QH2yE75JMDIIx9x rOsIRUoSfK3UrWaOVuAnEEn5ueKzZNqGG1J1ABEBAAG0J1NTTSBBZ2VudCA8c3Nt LWFnZW50LXNpZ25lckBhbWF6b24uY29tPokBPwQTAQIAKQUCZO0iggIbLwUJAsaY gAcLCQgHAwIBBhUIAgkKCwQWAgMBAh4BAheAAAoJELwfSVyX3QTt+icH/A//tJsW I+7Ay8FGJh8dJPNy++HIBjVSFdGNJFWNbw1Z8uZcazHEcUCH3FhW4CLQLTZ3OVPz qvFwzDtRDVIN/Y9EGDhLMFvimrE+/z4olWsJ5DANf6BnX8I5UNIcRt5d8SWH1BEJ 2FWIBZFgKyTDI6XzRC5x4ahtgpOVAGeeKDehs+wh6Ga4W0/K4GsviP1Kyr+Ic2br NAIq0q0IHyN1q9zam3Y0+jKwEuNmTj+Bjyzshyv/X8S0JWWoXJhkexkOvWeBYNNt 5wI4QcSteyfIzp6KlQF8q11Hzz9D9WaPfcBEYyhq7vLEARobkbQMBzpkmaZua241 0RaWG50HRvrgm4aJAhwEEAECAAYFAmTtIoMACgkQfdCXo9rX9fwwqBAAzkTgYJ38 sWgxpn7Ux/81F2BWR1sVkmP79i++fXyJlKI8xtcJFQZhzeUos69KBUCy7mgx5bYU P7NA5o9DUbwz/QS0i1Cqm4+jtFlX0MXe4FikXcqfDPnnzN8mVB2H+fa43iHR1PuH GgUWuNdxzSoIYRmLZXWmeN5YXPcmixlhLzcE2TOQn1mOKcu2fKdLtBQ8KiEkmjiu naoLxnUcyk1zMhaha+LzEkQdOyasix0ggylN2ViWVnlmfy0niuXDxW0qZWPdLStF OODiX3iqGmkH3rDfy6nvxxBR4GIs+MGD72fpWzzrINDgkGI2i2t1+0AX/mps3aTy +ftlgrim8stYWB58XXDAb0vad06sNye5/zDzfr0I9HupJrTzFhaYJQjWPaSlINto LDJnBXohiUIPRYRcy/k012oFHDWZHT3H6CyjK9UD5UlxA9H7dsJurANs6FOVRe+7 34uJyxDZ/W7zLG4AVG0zxibrUSoaJxwcOjVPVsQAlrwG/GTs7tcAccsJqbJ1Py/w 9AgJl8VU2qc8POsHNXk348gjP7C8PDnGMpZFzr9f5INctRushpiv7onX+aWJVX7T n2uX/TP3LCyH/MsrNJrJOQnMYFRLQitciP0E+F+eA3v9CY6mDuyb8JSx5HuGGUsG S4bKBOcA8vimEpwPoT8CE7fdsZ3Qkwdu+pw= =zr5w -----END PGP PUBLIC KEY BLOCK----- ``` 1. Import the public key into your keyring, and note the returned key value. ``` gpg --import amazon-ssm-agent.gpg ``` 1. Verify the fingerprint. Be sure to replace *key-value* with the value from the preceding step. We recommend that you use GPG to verify the fingerprint even if you use RPM to verify the installer package. ``` gpg --fingerprint key-value ``` This command returns output similar to the following. ``` pub 2048R/97DD04ED 2023-08-28 [expired: 2025-02-17] Key fingerprint = DE92 C7DA 3E56 E923 31D6 2A36 BC1F 495C 97DD 04ED uid SSM Agent ``` The fingerprint should match the following. `DE92 C7DA 3E56 E923 31D6 2A36 BC1F 495C 97DD 04ED` If the fingerprint doesn't match, don't install the agent. Contact AWS Support. 1. Download the signature file according to your instance's architecture and operating system if you haven't already done so. 1. Verify the installer package signature. Be sure to replace the *signature-filename* and *agent-download-filename* with the values you specified when downloading the signature file and agent, as listed in the table earlier in this topic. ``` gpg --verify signature-filename agent-download-filename ``` For example, for the x86\$164 architecture on Amazon Linux 2: ``` gpg --verify amazon-ssm-agent.rpm.sig amazon-ssm-agent.rpm ``` This command returns output similar to the following: ``` gpg: Signature made Fri 10 Jan 2025 01:54:18 AM UTC using RSA key ID 97DD04ED gpg: Good signature from "SSM Agent " gpg: Note: This key has expired! Primary key fingerprint: DE92 C7DA 3E56 E923 31D6 2A36 BC1F 495C 97DD 04ED ``` If the output includes the phrase `BAD signature`, check whether you performed the procedure correctly. If you continue to get this response, contact Support and don't install the agent. The warning message about the trust doesn't mean that the signature isn't valid, only that you haven't verified the public key. A key is trusted only if you or someone who you trust has signed it. If the output includes the phrase `Can't check signature: No public key`, verify you downloaded SSM Agent version 3.1.1141.0 or later. ------ #### [ RPM ] **To verify the SSM Agent package on a Linux server (v3.3.1611.0 and earlier)** 1. Copy the following public key and save it to a file named `amazon-ssm-agent.gpg`. **Important** The public key shown below expired on 2025-02-17 (February 17, 2025) and works for Version 3.3.1611.0 and earlier versions up to 3.2.1542.0, and only if it was used previously to verify the agent's signature. Systems Manager will publish a new public key in this topic before the old one expires. We encourage you to subscribe to the RSS feed for this topic to get a notification when the new key is available. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v2.0.22 (GNU/Linux) mQENBGTtIoIBCAD2M1aoGIE0FXynAHM/jtuvdAVVaX3Q4ZejTqrX+Jq8ElAMhxyO GzHu2CDtCYxtVxXK3unptLVt2kGgJwNbhYC393jDeZx5dCda4Nk2YXX1UK3P461i axuuXRzMYvfM4RZn+7bJTu635tA07q9Xm6MGD4TCTvsjBfViOxbrxOg5ozWbJdSw fSR8MwUrRfmFpAefRlYfCEuZ8FHywa9U6jLeWt2O/kqrZliJOAGjGzXtB7EZkqKb faCCxikjjvhF1awdEqSK4DQorC/OvQc4I5kP5y2CJbtXvXO73QH2yE75JMDIIx9x rOsIRUoSfK3UrWaOVuAnEEn5ueKzZNqGG1J1ABEBAAG0J1NTTSBBZ2VudCA8c3Nt LWFnZW50LXNpZ25lckBhbWF6b24uY29tPokBPwQTAQIAKQUCZO0iggIbLwUJAsaY gAcLCQgHAwIBBhUIAgkKCwQWAgMBAh4BAheAAAoJELwfSVyX3QTt+icH/A//tJsW I+7Ay8FGJh8dJPNy++HIBjVSFdGNJFWNbw1Z8uZcazHEcUCH3FhW4CLQLTZ3OVPz qvFwzDtRDVIN/Y9EGDhLMFvimrE+/z4olWsJ5DANf6BnX8I5UNIcRt5d8SWH1BEJ 2FWIBZFgKyTDI6XzRC5x4ahtgpOVAGeeKDehs+wh6Ga4W0/K4GsviP1Kyr+Ic2br NAIq0q0IHyN1q9zam3Y0+jKwEuNmTj+Bjyzshyv/X8S0JWWoXJhkexkOvWeBYNNt 5wI4QcSteyfIzp6KlQF8q11Hzz9D9WaPfcBEYyhq7vLEARobkbQMBzpkmaZua241 0RaWG50HRvrgm4aJAhwEEAECAAYFAmTtIoMACgkQfdCXo9rX9fwwqBAAzkTgYJ38 sWgxpn7Ux/81F2BWR1sVkmP79i++fXyJlKI8xtcJFQZhzeUos69KBUCy7mgx5bYU P7NA5o9DUbwz/QS0i1Cqm4+jtFlX0MXe4FikXcqfDPnnzN8mVB2H+fa43iHR1PuH GgUWuNdxzSoIYRmLZXWmeN5YXPcmixlhLzcE2TOQn1mOKcu2fKdLtBQ8KiEkmjiu naoLxnUcyk1zMhaha+LzEkQdOyasix0ggylN2ViWVnlmfy0niuXDxW0qZWPdLStF OODiX3iqGmkH3rDfy6nvxxBR4GIs+MGD72fpWzzrINDgkGI2i2t1+0AX/mps3aTy +ftlgrim8stYWB58XXDAb0vad06sNye5/zDzfr0I9HupJrTzFhaYJQjWPaSlINto LDJnBXohiUIPRYRcy/k012oFHDWZHT3H6CyjK9UD5UlxA9H7dsJurANs6FOVRe+7 34uJyxDZ/W7zLG4AVG0zxibrUSoaJxwcOjVPVsQAlrwG/GTs7tcAccsJqbJ1Py/w 9AgJl8VU2qc8POsHNXk348gjP7C8PDnGMpZFzr9f5INctRushpiv7onX+aWJVX7T n2uX/TP3LCyH/MsrNJrJOQnMYFRLQitciP0E+F+eA3v9CY6mDuyb8JSx5HuGGUsG S4bKBOcA8vimEpwPoT8CE7fdsZ3Qkwdu+pw= =zr5w -----END PGP PUBLIC KEY BLOCK----- ``` 1. Import the public key into your keyring, and note the returned key value. ``` rpm --import amazon-ssm-agent.gpg ``` 1. Verify the fingerprint. We recommend that you use GPG to verify the fingerprint even if you use RPM to verify the installer package. ``` rpm -qa gpg-pubkey --qf '%{Description}' | gpg --with-fingerprint | grep -A 1 "ssm-agent-signer@amazon.com" ``` This command returns output similar to the following: ``` pub 2048R/97DD04ED 2023-08-28 SSM Agent Key fingerprint = DE92 C7DA 3E56 E923 31D6 2A36 BC1F 495C 97DD 04ED ``` The fingerprint should match the following. `DE92 C7DA 3E56 E923 31D6 2A36 BC1F 495C 97DD 04ED` If the fingerprint doesn't match, don't install the agent. Contact AWS Support. 1. Verify the installer package signature. Be sure to replace the *agent-download-filename* with the values you specified when downloading the agent, as listed in the table earlier in this topic. ``` rpm --checksig agent-download-filename ``` For example, for the x86\$164 architecture on Amazon Linux 2: ``` rpm --checksig amazon-ssm-agent.rpm ``` This command returns output similar to the following. ``` amazon-ssm-agent.rpm: rsa sha1 md5 OK ``` If `pgp` is missing from the output and you have imported the public key, then the agent isn't signed. If the output contains the phrase `NOT OK (MISSING KEYS: (MD5) key-id)`, check whether you performed the procedure correctly and verify you downloaded SSM Agent version 3.1.1141.0 or later. If you continue to get this response, contact Support and don't install the agent. ------ # Manually installing and uninstalling SSM Agent on EC2 instances for Linux Before you manually install AWS Systems Manager Agent (SSM Agent) on an Amazon Elastic Compute Cloud (Amazon EC2) Linux operating system, review the following information. **Installation on other machine types** The procedures in this section are designed specifically for Amazon EC2 instances. For on-premises servers, virtual machines, or other non-EC2 environments, use the `ssm-setup-cli` tool as described in [How to install the SSM Agent on hybrid Linux nodes](hybrid-multicloud-ssm-agent-install-linux.md). Using EC2 installation procedures on non-EC2 systems can potentially result in security vulnerabilities. The `ssm-setup-cli` tool provides additional security protections for non-EC2 machines. We strongly recommend that you avoid using OS versions that have reached End-of-Life (EOL). OS vendors including AWS typically don't provide security patches or other updates for versions that have reached EOL. Continuing to use an EOL system greatly increases the risk of not being able to apply upgrades, including security fixes, and other operational problems. AWS does not test Systems Manager functionality on OS versions that have reached EOL. **SSM Agent installation file URLs** You can access the installation files for SSM Agent that are stored in any commercial AWS Region. We also provide installation files in a globally available Amazon Simple Storage Service (Amazon S3) bucket that you can use as an alternative or backup source of files. If you're manually installing the agent on a instance or two, you can use the commands in the **Quick installation** procedures we provide to save time. The commands provided in these procedures can also be passed to Amazon EC2 instances as scripts through user data. If you're creating a script or template to use for installing the agent on multiple instances, we recommend that you use the installation files in or near an AWS Region where you're geographically located. For bulk installations, this can increase the speed of your downloads and reduce latency. In these cases, we recommend using the **Create custom installation commands** procedures in the installation topics. **Amazon Machine Images with the agent preinstalled** SSM Agent is preinstalled on some Amazon Machine Images (AMIs) provided by AWS. For information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). **Keeping the agent up to date** An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. **Choose your operating system** To view the procedure for manually installing SSM Agent on the specified operating system, choose a link from the following list: **Note** For a list of supported versions of each of the following operating systems, see [Supported operating systems for Systems Manager](operating-systems-and-machine-types.md#prereqs-operating-systems). + [AlmaLinux](agent-install-alma.md) + [Amazon Linux 2 and Amazon Linux 2023](agent-install-al2.md) + [Debian Server](agent-install-deb.md) + [Oracle Linux](agent-install-oracle.md) + [Red Hat Enterprise Linux](agent-install-rhel.md) + [Rocky Linux](agent-install-rocky.md) + [Ubuntu Server](agent-install-ubuntu.md) ## Uninstalling SSM Agent from Linux instances Use the package manager for your operating system to uninstall SSM Agent from Linux instances. Depending on the operating system, the uninstall command will be similar to the following example command: ``` sudo dpkg -r amazon-ssm-agent ``` # Manually install SSM Agent on AlmaLinux instances AlmaLinux Use the information in this section to help you manually install or reinstall SSM Agent on an AlmaLinux instance. **Before you begin** Before you install SSM Agent on an AlmaLinux instance, note the following: + Ensure that Python 3 is installed on your AlmaLinux instance. This is required in order for SSM Agent to work properly. + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ ## Quick installation commands for SSM Agent on AlmaLinux ](#quick-install-alma) + [ ## Create custom agent installation commands for AlmaLinux in your Region ](#custom-url-alma) ## Quick installation commands for SSM Agent on AlmaLinux Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **Before you begin** Before you install SSM Agent on a AlmaLinux instance, note the following: + Ensure that Python 3 is installed on your AlmaLinux instance. This is required in order for SSM Agent to work properly. **To install SSM Agent on AlmaLinux** 1. Connect to your AlmaLinux instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for AlmaLinux. x86\$164 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: active (running) since Tue 2025-04-19 16:40:41 UTC; 9s ago Main PID: 4898 (amazon-ssm-agen) Tasks: 14 (limit: 4821) Memory: 34.6M CGroup: /system.slice/amazon-ssm-agent.service ├─4898 /usr/bin/amazon-ssm-agent └─4954 /usr/bin/ssm-agent-worker --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: inactive (dead) since Tue 2025-04-19 16:42:05 UTC; 2s ago --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for AlmaLinux in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on AlmaLinux](#quick-install-alma) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Manually installing SSM Agent on Amazon Linux 2 and Amazon Linux 2023 instances Amazon Linux 2 and Amazon Linux 2023 In most cases, the Amazon Machine Images (AMIs) for Amazon Linux 2 and Amazon Linux 2023 that are provided by AWS come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). In the event that SSM Agent isn’t preinstalled on a new Amazon Linux 2 or Amazon Linux 2023 instance, or if you need to manually reinstall the agent, use the information on this page to help you. **Before you begin** Before you install SSM Agent on an Amazon Linux 2 or Amazon Linux 2023 instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). + If you use a `yum` command to update SSM Agent on a managed node after the agent has been installed or updated using the SSM document `AWS-UpdateSSMAgent`, you might see the following message: `"Warning: RPMDB altered outside of yum."` This message is expected and can be safely ignored. **Topics** + [ ## Quick installation commands for SSM Agent on Amazon Linux 2 or Amazon Linux 2023 ](#quick-install-al2) + [ ## Create custom agent installation commands for Amazon Linux 2 or Amazon Linux 2023 in your Region ](#custom-url-al2) ## Quick installation commands for SSM Agent on Amazon Linux 2 or Amazon Linux 2023 Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on Amazon Linux 2 or Amazon Linux 2023 using quick copy and paste commands** 1. Connect to your Amazon Linux 2 or Amazon Linux 2023 instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for Amazon Linux 2 and Amazon Linux 2023. **x86\$164** ``` sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2021-10-20 19:09:29 UTC; 4min 6s ago --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: inactive (dead) since Wed 2021-10-20 22:16:41 UTC; 18s ago --truncated-- ``` To activate the agent in these cases, run the following command. ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for Amazon Linux 2 or Amazon Linux 2023 in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Amazon Linux 2 or Amazon Linux 2023](#quick-install-al2) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo yum install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo yum install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo yum install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo yum install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Manually install SSM Agent on CentOS Stream instances CentOS Stream The Amazon Machine Images (AMIs) for CentOS Stream that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For a list of AWS managed AMIs on which the agent might be preinstalled, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). Use the information in this section to help you manually install or reinstall SSM Agent on a CentOS Stream instance. **Before you begin** Before you install SSM Agent on a CentOS Stream instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ ## Quick installation commands for SSM Agent on CentOS Stream ](#quick-install-centos-stream) + [ ## Create custom agent installation commands for CentOS Stream in your Region ](#custom-url-centos-stream) ## Quick installation commands for SSM Agent on CentOS Stream Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on CentOS Stream** 1. Connect to your CentOS Stream instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for CentOS Stream. x86\$164 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: active (running) since Tue 2025-04-19 16:40:41 UTC; 9s ago Main PID: 4898 (amazon-ssm-agen) Tasks: 14 (limit: 4821) Memory: 34.6M CGroup: /system.slice/amazon-ssm-agent.service ├─4898 /usr/bin/amazon-ssm-agent └─4954 /usr/bin/ssm-agent-worker ‐‐truncated‐‐ ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: inactive (dead) since Tue 2025-04-19 16:42:05 UTC; 2s ago ‐‐truncated ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for CentOS Stream in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on CentOS Stream](#quick-install-centos-stream) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Manually installing SSM Agent on Debian Server instances Debian Server The Amazon Machine Images (AMIs) for Debian Server that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For a list of AWS managed AMIs on which the agent might be preinstalled, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). Use the information in this section to help you manually install or reinstall SSM Agent on a Debian Server instance. **Before you begin** Before you install SSM Agent on a Debian Server instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ ## Quick installation commands for SSM Agent on Debian Server ](#quick-install-debian) + [ ## Create custom agent installation commands for Debian Server in your Region ](#custom-url-debian) ## Quick installation commands for SSM Agent on Debian Server Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on Debian Server** 1. Connect to your Debian Server instance using your preferred method, such as SSH. 1. Run the following command to create a temporary directory on the instance. ``` mkdir /tmp/ssm ``` 1. Run the following command to change to the temporary directory. ``` cd /tmp/ssm ``` 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for Debian Server. For Debian Server 8, only the x86\$164 architecture is supported. x86\$164 instances ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb ``` ARM64 instances ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_arm64/amazon-ssm-agent.deb ``` 1. Run the following command. ``` sudo dpkg -i amazon-ssm-agent.deb ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor Active: active (running) since Tue 2025-04-19 16:25:03 UTC; 4s ago Main PID: 628 (amazon-ssm-agen) CGroup: /system.slice/amazon-ssm-agent.service ├─628 /usr/bin/amazon-ssm-agent └─650 /usr/bin/ssm-agent-worker --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor Active: inactive (dead) since Tue 2025-04-19 16:26:30 UTC; 5s ago Main PID: 628 (code=exited, status=0/SUCCESS) --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for Debian Server in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Debian Server](#quick-install-debian) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. x86\$164 ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/debian_amd64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` ARM64 ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_arm64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/debian_arm64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` # Manually installing SSM Agent on Oracle Linux instances Oracle Linux The Amazon Machine Images (AMIs) for Oracle Linux that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For a list of AWS managed AMIs on which the agent might be preinstalled, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). Use the information in this section to help you manually install or reinstall SSM Agent on an Oracle Linux instance. **Before you begin** Before you install SSM Agent on an Oracle Linux instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). + If you use a `yum` command to update SSM Agent on a managed node after the agent has been installed or updated using the SSM document `AWS-UpdateSSMAgent`, you might see the following message: `"Warning: RPMDB altered outside of yum."` This message is expected and can be safely ignored. **Topics** + [ ## Quick installation commands for SSM Agent on Oracle Linux ](#quick-install-oracle) + [ ## Create custom agent installation commands for Oracle Linux in your Region ](#custom-url-oracle) ## Quick installation commands for SSM Agent on Oracle Linux Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on Oracle Linux using quick copy and paste commands** 1. Connect to your Oracle Linux instance using your preferred method, such as SSH. 1. Copy the following command and run it on the instance. **Note** Even though URL in the following command includes an `ec2-downloads-windows` directory, these are the correct global installation files for Oracle Linux. **x86\$164** ``` sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2021-10-20 19:09:29 UTC; 4min 6s ago --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled) Active: inactive (dead) since Wed 2021-10-20 22:16:41 UTC; 18s ago --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for Oracle Linux in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Oracle Linux](#quick-install-oracle) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo yum install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo yum install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` # Manually installing SSM Agent on Red Hat Enterprise Linux instances RHEL The Amazon Machine Images (AMIs) for Red Hat Enterprise Linux (RHEL) that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For a list of AWS managed AMIs on which the agent might be preinstalled, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). Use the information in this section to help you manually install or reinstall SSM Agent on a RHEL instance. **Before you begin** Before you install SSM Agent on a RHEL instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). + If you use a `yum` command to update SSM Agent on a managed node after the agent has been installed or updated using the SSM document `AWS-UpdateSSMAgent`, you might see the following message: `"Warning: RPMDB altered outside of yum."` This message is expected and can be safely ignored. **Topics** + [ # Install SSM Agent on RHEL 8.x, 9.x, and 10.x ](agent-install-rhel-8-9.md) + [ # Install SSM Agent on RHEL 7.x ](agent-install-rhel-7.md) # Install SSM Agent on RHEL 8.x, 9.x, and 10.x Versions 8.x, 9.x, and 10.x The Amazon Machine Images (AMIs) for RHEL 8 and 9 that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. Use the information on this page to help you install or reinstall the agent on RHEL 8 and 9 instances. **Before you begin** Before you install SSM Agent on a RHEL 8, 9, or 10 instance, note the following: + Ensure that either Python 2 or Python 3 is installed on your RHEL 8, 9, or 10 instance. This is required in order for SSM Agent to work properly. **Topics** + [ ## Quick installation commands for SSM Agent on RHEL 8, 9, and 10 ](#quick-install-rhel-8-9) + [ ## Create custom agent installation commands for RHEL 8, 9, and 10 in your Region ](#custom-url-rhel-8-9) ## Quick installation commands for SSM Agent on RHEL 8, 9, and 10 Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on RHEL 8.x, 9.x, or 10.x** 1. Connect to your RHEL 8, 9, or 10 instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for RHEL 8, 9, and 10. x86\$164 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: active (running) since Tue 2025-04-19 16:40:41 UTC; 9s ago Main PID: 4898 (amazon-ssm-agen) Tasks: 14 (limit: 4821) Memory: 34.6M CGroup: /system.slice/amazon-ssm-agent.service ├─4898 /usr/bin/amazon-ssm-agent └─4954 /usr/bin/ssm-agent-worker --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: inactive (dead) since Tue 2025-04-19 16:42:05 UTC; 2s ago --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for RHEL 8, 9, and 10 in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on RHEL 8, 9, and 10](#quick-install-rhel-8-9) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Install SSM Agent on RHEL 7.x Version 7.x The Amazon Machine Images (AMIs) for RHEL 7 that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. Use the information on this page to help you install or reinstall the agent on RHEL 7 instances. **Topics** + [ ## Quick installation commands for SSM Agent on RHEL 7 ](#quick-install-rhel-7) + [ ## Create custom agent installation commands for RHEL 7 in your Region ](#custom-url-rhel-7) ## Quick installation commands for SSM Agent on RHEL 7 Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on RHEL 7.x** 1. Connect to your RHEL 7 instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for RHEL 7. x86\$164 instances ``` sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances ``` sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: disabled) Active: active (running) since Tue 2025-04-19 16:47:36 UTC; 22s ago Main PID: 1342 (amazon-ssm-agen) CGroup: /system.slice/amazon-ssm-agent.service ├─1342 /usr/bin/amazon-ssm-agent └─1362 /usr/bin/ssm-agent-worker --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: disabled) Active: inactive (dead) since Tue 2025-04-19 16:48:56 UTC; 5s ago Process: 1342 ExecStart=/usr/bin/amazon-ssm-agent (code=exited, status=0/SUCCESS) Main PID: 1342 (code=exited, status=0/SUCCESS) --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for RHEL 7 in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on RHEL 7](#quick-install-rhel-7) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo yum install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo yum install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo yum install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo yum install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Manually install SSM Agent on Rocky Linux instances Rocky Linux The Amazon Machine Images (AMIs) for Rocky Linux that are provided by AWS do not come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For a list of AWS managed AMIs on which the agent might be preinstalled, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). Use the information in this section to help you manually install or reinstall SSM Agent on an Rocky Linux instance. **Before you begin** Before you install SSM Agent on a Rocky Linux instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ ## Quick installation commands for SSM Agent on Rocky Linux ](#quick-install-rocky) + [ ## Create custom agent installation commands for Rocky Linux in your Region ](#custom-url-rocky) ## Quick installation commands for SSM Agent on Rocky Linux Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **Before you begin** Before you install SSM Agent on a Rocky Linux instance, note the following: + Ensure that either Python 2 or Python 3 is installed on your Rocky Linux instance. This is required in order for SSM Agent to work properly. **To install SSM Agent on Rocky Linux** 1. Connect to your Rocky Linux instance using your preferred method, such as SSH. 1. Copy the command for your instance’s architecture and run it on the instance. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for Rocky Linux. x86\$164 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances ``` sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` 1. (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: active (running) since Tue 2025-04-19 16:40:41 UTC; 9s ago Main PID: 4898 (amazon-ssm-agen) Tasks: 14 (limit: 4821) Memory: 34.6M CGroup: /system.slice/amazon-ssm-agent.service ├─4898 /usr/bin/amazon-ssm-agent └─4954 /usr/bin/ssm-agent-worker --truncated-- ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendo> Active: inactive (dead) since Tue 2025-04-19 16:42:05 UTC; 2s ago --truncated-- ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for Rocky Linux in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Rocky Linux](#quick-install-rocky) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` **ARM64** ``` sudo dnf install -y https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` See the following example. ``` sudo dnf install -y https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` # Manually install SSM Agent on SUSE Linux Enterprise Server instances SUSE Linux Enterprise Server In most cases, the Amazon Machine Images (AMIs) for SUSE Linux Enterprise Server (SLES) that are provided by AWS come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). In the event that SSM Agent isn’t preinstalled on a new SLES instance, or if you need to manually reinstall the agent, use the information on this page to help you. **Before you begin** Before you install SSM Agent on a SLES instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ ## Quick installation commands for SSM Agent on SLES ](#quick-install-sles) + [ ## Create custom agent installation commands for SLES in your Region ](#custom-url-sles) ## Quick installation commands for SSM Agent on SLES Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on SLES using quick copy and paste commands** 1. Connect to your SLES instance using your preferred method, such as SSH. 1. **Option 1**: Use a `zypper` command: + Run the following command: ``` sudo zypper install amazon-ssm-agent ``` + Enter `y` in response to any prompts. **Option 2**: Use an `rpm` command. + Create a temporary directory on the instance. ``` mkdir /tmp/ssm ``` + Change to the temporary directory. ``` cd /tmp/ssm ``` + Run the following commands one at a time to download and run the SSM Agent installer. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for SLES. x86\$164 instances: ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm ``` ARM64 instances: ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_arm64/amazon-ssm-agent.rpm ``` + Run the following command. ``` sudo rpm ‐‐install amazon-ssm-agent.rpm ``` + (Recommended) Run the following command to verify that the agent is running. ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: disabled) Active: active (running) since Mon 2025-02-21 23:13:28 UTC; 7s ago Main PID: 2102 (amazon-ssm-agen) Tasks: 15 (limit: 512) CGroup: /system.slice/amazon-ssm-agent.service ├─2102 /usr/sbin/amazon-ssm-agent └─2107 /usr/sbin/ssm-agent-worker ‐‐truncated‐‐ ``` In rare cases, the command reports that the agent is installed but not running, as shown in the following example. ``` ● amazon-ssm-agent.service - amazon-ssm-agent Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; disabled; vendor preset: disabled) Active: inactive (dead) ‐‐truncated‐‐ ``` To activate the agent in these cases, run the following commands. ``` sudo systemctl enable amazon-ssm-agent ``` ``` sudo systemctl start amazon-ssm-agent ``` ## Create custom agent installation commands for SLES in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on SLES](#quick-install-sles) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **x86\$164** ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-agent.rpm ``` ``` sudo rpm ‐‐install amazon-ssm-agent.rpm ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_amd64/amazon-ssm-agent.rpm ``` ``` sudo rpm ‐‐install amazon-ssm-agent.rpm ``` **ARM64** ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_arm64/amazon-ssm-agent.rpm ``` ``` sudo rpm ‐‐install amazon-ssm-agent.rpm ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/linux_arm64/amazon-ssm-agent.rpm ``` ``` sudo rpm ‐‐install amazon-ssm-agent.rpm ``` # Manually installing SSM Agent on Ubuntu Server instances Ubuntu Server **Important** Before you install SSM Agent on a 64-bit version of Ubuntu Server, ensure that you are using the correct installation tools. Beginning with Amazon Machine Images (AMIs) that are identified with 20180627, SSM Agent is pre-installed on version 16.04 using Snap packages. On instances created from earlier AMIs, SSM Agent must be installed using deb installer packages. For more information, see [Determining the correct SSM Agent version to install on 64-bit Ubuntu Server 16.04 instances](agent-install-ubuntu-about-v16.md). In most cases, the Amazon Machine Images (AMIs) for Ubuntu Server that are provided by AWS come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). In the event that SSM Agent isn’t preinstalled on a new Ubuntu Server instance, or if you need to manually reinstall the agent, use the information in this section to help you. **Before you begin** Before you install SSM Agent on an Ubuntu Server instance, note the following: + For important information that applies to installation of SSM Agent on all Linux-based operating systems, see [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md). **Topics** + [ # Install SSM Agent on Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 ](agent-install-ubuntu-64-snap.md) + [ # Install SSM Agent on Ubuntu Server 16.04 64-bit (deb) ](agent-install-ubuntu-64-deb.md) + [ # Install SSM Agent on Ubuntu Server 16.04 32-bit ](agent-install-ubuntu-32.md) + [ # Determining the correct SSM Agent version to install on 64-bit Ubuntu Server 16.04 instances ](agent-install-ubuntu-about-v16.md) # Install SSM Agent on Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 Versions 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 **Before you begin** Before you install SSM Agent on an Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04, note the following: Version 16.04 installation by Snaps or deb installers On Ubuntu Server 16.04, SSM Agent is installed using either Snaps or deb installation packages, depending on the version of the 16.04 AMI. SSM Agent installer files locations On Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04, 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`). Using the Snap `candidate` channel The *candidate* channel in the Snap store contains the latest version of SSM Agent (including all of the latest bug fixes); not the stable channel. To learn more about the differences between the candidate and stable channels, see **Risk-levels** at [https://snapcraft.io/docs/channels](https://snapcraft.io/docs/channels). If you want to track SSM Agent version information on the candidate channel, run the following command on your Ubuntu Server 20.04, 18.04, and 16.04 LTS 64-bit instances. ``` sudo snap switch --channel=candidate amazon-ssm-agent ``` Snaps recommended on versions 18.04 and later On Ubuntu Server 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04, we recommend you only use Snaps. Also verify that only one instance of the agent is installed and running on your instances. If you want to use SSM Agent without Snaps, uninstall the SSM Agent. Then [install the SSM Agent as a debian package](agent-install-ubuntu-64-deb.md) using the instructions for installing SSM Agent on Ubuntu Server 16.04 (deb). Before installing, ensure you don't have any Snaps installed that overlap with the list of packages you want managed as debian packages. `Maximum timeout exceeded` error message Because of a known issue with Snap, you might see a `Maximum timeout exceeded` error with `snap` commands. If you get this error, run the following commands one at a time to start the agent, stop it, and check its status: ``` sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service ``` ``` sudo systemctl stop snap.amazon-ssm-agent.amazon-ssm-agent.service ``` ``` sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service ``` **To install SSM Agent on Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 (with Snap package)** 1. SSM Agent is installed, by default, on Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 AMIs with an identifier of `20180627` or later. You can use the following script if you need to install SSM Agent on an on-premises server or if you need to reinstall the agent. 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). ``` sudo snap install amazon-ssm-agent --classic ``` 1. Run the following command to determine if SSM Agent is running. ``` sudo snap list amazon-ssm-agent ``` 1. Run the following command to start the service if the previous command returned `amazon-ssm-agent is stopped`, `inactive`, or `disabled`. ``` sudo snap start amazon-ssm-agent ``` 1. Check the status of the agent. ``` sudo snap services amazon-ssm-agent ``` # Install SSM Agent on Ubuntu Server 16.04 64-bit (deb) Versions 16.04 and 14.04 64-bit (deb) **Important** Before you install SSM Agent on a 64-bit version of Ubuntu Server, ensure that you are using the correction installation tools. Beginning with Amazon Machine Images (AMIs) that are identified with 20180627, SSM Agent is pre-installed on version 16.04 using Snap packages. On instances created from earlier AMIs, SSM Agent must be installed using deb installer packages. For more information, see [Determining the correct SSM Agent version to install on 64-bit Ubuntu Server 16.04 instances](agent-install-ubuntu-about-v16.md).If SSM Agent is installed on your instance in conjunction with a Snap and you install or update SSM Agent using a deb installer package, the installation or SSM Agent operations might fail. In most cases, the Amazon Machine Images (AMIs) Ubuntu Server 16.04 that are provided by AWS come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). In the event that SSM Agent isn’t preinstalled on a new Ubuntu Server 16.04 instance prior to version 20180627 or you need to manually reinstall the agent, use the information on this page to help you. ## Quick installation commands for SSM Agent on Ubuntu Server 16.04 (deb) Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on Ubuntu Server 16.04 64-bit (deb) using quick copy and paste commands** 1. Connect to your Ubuntu Server instance using your preferred method, such as SSH. 1. Run the following command to create a temporary directory on the instance. ``` mkdir /tmp/ssm ``` 1. Change to the temporary directory. ``` cd /tmp/ssm ``` 1. Run the following commands. **Note** Even though URLs in the following commands include an `ec2-downloads-windows` directory, these are the correct global installation files for Ubuntu Server 16.04 64-bit. ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` 1. (Recommended) Run the following command to determine if SSM Agent is running. Ubuntu Server 16.04 ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running. In rare cases, the command reports that the agent is installed but not running, as shown in the following example. 1. Run the following command to start the service if the previous command returned `amazon-ssm-agent is stopped`, `inactive`, or `disabled`. Ubuntu Server 16.04: ``` sudo systemctl enable amazon-ssm-agent ``` ## Create custom installation commands for SSM Agent on Ubuntu Server 16.04 64-bit (deb) in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Ubuntu Server 16.04 (deb)](#quick-install-ub-16-14-64-bit) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/debian_amd64/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` # Install SSM Agent on Ubuntu Server 16.04 32-bit Versions 16.04 and 14.04 32-bit In most cases, the Amazon Machine Images (AMIs) Ubuntu Server 16.04 that are provided by AWS come with AWS Systems Manager Agent (SSM Agent) preinstalled by default. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md). In the event that SSM Agent isn’t preinstalled on a new Ubuntu Server 16.04 instance or you need to manually reinstall the agent, use the information on this page to help you. ## Quick installation commands for SSM Agent on Ubuntu Server 16.04 32-bit (deb) Use the following steps to manually install SSM Agent on a single instance. This procedure uses globally available installation files. **To install SSM Agent on Ubuntu Server 16.04 32-bit (deb) using quick copy and paste commands** 1. Connect to your Ubuntu Server instance using your preferred method, such as SSH. 1. Run the following command to create a temporary directory on the instance. ``` mkdir /tmp/ssm ``` 1. Change to the temporary directory. ``` cd /tmp/ssm ``` 1. Run the following commands. **Note** Even though URL in the following command include an `ec2-downloads-windows` directory, this is the correct global installation file for Ubuntu Server 16.04 32-bit. ``` wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` 1. (Recommended) Run the following command to determine if SSM Agent is running. Ubuntu Server 16.04 ``` sudo systemctl status amazon-ssm-agent ``` In most cases, the command reports that the agent is running. In rare cases, the command reports that the agent is installed but not running, as shown in the following example. 1. Run the following command to start the service if the previous command returned `amazon-ssm-agent is stopped`, `inactive`, or `disabled`. Ubuntu Server 16.04: ``` sudo systemctl enable amazon-ssm-agent ``` ## Create custom installation commands for SSM Agent on Ubuntu Server 16.04 32-bit (deb) in your Region When you install SSM Agent on multiple instances using a script or template, we recommend using installation files that are stored in the AWS Region you're working in. For the following commands, we provide examples that use a publicly accessible S3 bucket in the US East (Ohio) Region (`us-east-2`). **Tip** You can also replace a global URL in the procedure [Quick installation commands for SSM Agent on Ubuntu Server 16.04 32-bit (deb)](#quick-install-ub-16-14-32-bit) earlier in this topic with a custom Regional URL you construct. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. ``` wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` See the following example. ``` wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/debian_386/amazon-ssm-agent.deb ``` ``` sudo dpkg -i amazon-ssm-agent.deb ``` # Determining the correct SSM Agent version to install on 64-bit Ubuntu Server 16.04 instances **Important** Before you install SSM Agent on a 64-bit version of Ubuntu Server, ensure that you are using the correction installation tools. Beginning with Amazon Machine Images (AMIs) that are identified with 20180627, SSM Agent is pre-installed on version 16.04 using Snap packages. On instances created from earlier AMIs, SSM Agent must be installed using deb installer packages. For more information, see [Determining the correct SSM Agent version to install on 64-bit Ubuntu Server 16.04 instances](#agent-install-ubuntu-about-v16) Be aware that if an instance has more than one installation of the SSM Agent (for example, one installed using a Snap and one installed using a deb installer), your agent operations won't work correctly. You can verify the source AMI ID creation date for an instance using either of the following methods. These procedures apply only to AWS managed AMIs. **Verify a source AMI ID creation date (console)** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the left navigation pane, choose **Instances**. 1. Select an instance. 1. On the **Details** tab, check for a `YYYYMMDD` identifier in the value under **AMI name** field. For example: `ubuntu/images/hvm-ssd/ubuntu-xenial-16.04-amd64-server-20180627`. **Verify a source AMI ID creation date (AWS CLI)** + Run the following command. ``` aws ec2 describe-images --image-ids ami-id ``` *ami-id* represents the ID of an AMI provided by AWS, such as `ami-07c8bc5c1ce9598c3`. If successful, the command returns information like the following, in which you can check the `CreationDate` and `Name` fields for information. ``` { "Images": [ { "Architecture": "x86_64", "CreationDate": "2020-07-24T20:40:27.000Z", "ImageId": "ami-07c8bc5c1ce9598c3", -- truncated -- "ImageOwnerAlias": "amazon", "Name": "amzn2-ami-hvm-2.0.20200722.0-x86_64-gp2", "RootDeviceName": "/dev/xvda", "RootDeviceType": "ebs", "SriovNetSupport": "simple", "VirtualizationType": "hvm" } ] } ``` # Configuring SSM Agent to use a proxy on Linux nodes You can configure AWS Systems Manager Agent (SSM Agent) to communicate through an HTTP proxy by creating an override configuration file and adding `http_proxy`, `https_proxy`, and `no_proxy` settings to the file. An override file also preserves the proxy settings if you install newer or older versions of SSM Agent. This section includes procedures for creating an override file in both *upstart* and *systemd* environments. If you intend to use Session Manager, note that HTTPS proxy servers aren't supported. **Topics** + [ ## Configure SSM Agent to use a proxy (upstart) ](#ssm-agent-proxy-upstart) + [ ## Configure SSM Agent to use a proxy (systemd) ](#ssm-agent-proxy-systemd) ## Configure SSM Agent to use a proxy (upstart) Use the following procedure to create an override configuration file for an `upstart` environment. **To configure SSM Agent to use a proxy (upstart)** 1. Connect to the managed instance where you installed SSM Agent. 1. Open a simple editor like VIM, and depending on whether you're using an HTTP proxy server or HTTPS proxy server, add one of the following configurations. **For an HTTP proxy server:** ``` env http_proxy=http://hostname:port env https_proxy=http://hostname:port env no_proxy=IP address for instance metadata services (IMDS) ``` **For an HTTPS proxy server:** ``` env http_proxy=http://hostname:port env https_proxy=https://hostname:port env no_proxy=IP address for instance metadata services (IMDS) ``` **Important** Add the `no_proxy` setting to the file and specify the IP address. The IP address for `no_proxy` is the instance metadata services (IMDS) endpoint for Systems Manager. If you don't specify `no_proxy`, calls to Systems Manager take on the identity from the proxy service (if IMDSv1 fallback is enabled) or calls to Systems Manager fail (if IMDSv2 is enforced). For IPv4, specify `no_proxy=169.254.169.254`. For IPv6, specify `no_proxy=[fd00:ec2::254]`. The IPv6 address of the instance metadata service is compatible with IMDSv2 commands. The IPv6 address is only accessible on instances built on the [AWS Nitro System](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-nitro-instances.html). For more information, see [How Instance Metadata Service Version 2 works](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-v2-how-it-works.html) in the *Amazon EC2 User Guide*. 1. Save the file with the name `amazon-ssm-agent.override` in the following location: `/etc/init/` 1. Stop and restart SSM Agent using the following commands. ``` sudo service stop amazon-ssm-agent sudo service start amazon-ssm-agent ``` **Note** For more information about working with `.override` files in Upstart environments, see [init: Upstart init daemon job configuration](https://www.systutorials.com/docs/linux/man/5-init/). ## Configure SSM Agent to use a proxy (systemd) Use the following procedure to configure SSM Agent to use a proxy in a `systemd` environment. **Note** Some of the steps in this procedure contain explicit instructions for Ubuntu Server instances where SSM Agent was installed using Snap. 1. Connect to the instance where you installed SSM Agent. 1. Run one of the follow commands, depending on the operating system type. + On Ubuntu Server instances where SSM Agent is installed by using a snap: ``` sudo systemctl edit snap.amazon-ssm-agent.amazon-ssm-agent ``` On other operating systems: ``` sudo systemctl edit amazon-ssm-agent ``` 1. Open a simple editor like VIM, and depending on whether you're using an HTTP proxy server or HTTPS proxy server, add one of the following configurations. ![\[Enter new content above the line "### Lines below this comment will be discarded."\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/update-proxy-callout.png) **For an HTTP proxy server:** ``` [Service] Environment="http_proxy=http://hostname:port" Environment="https_proxy=http://hostname:port" Environment="no_proxy=IP address for instance metadata services (IMDS)" ``` **For an HTTPS proxy server:** ``` [Service] Environment="http_proxy=http://hostname:port" Environment="https_proxy=https://hostname:port" Environment="no_proxy=IP address for instance metadata services (IMDS)" ``` **Important** Add the `no_proxy` setting to the file and specify the IP address. The IP address for `no_proxy` is the instance metadata services (IMDS) endpoint for Systems Manager. If you don't specify `no_proxy`, calls to Systems Manager take on the identity from the proxy service (if IMDSv1 fallback is enabled) or calls to Systems Manager fail (if IMDSv2 is enforced). For IPv4, specify `no_proxy=169.254.169.254`. For IPv6, specify `no_proxy=[fd00:ec2::254]`. The IPv6 address of the instance metadata service is compatible with IMDSv2 commands. The IPv6 address is only accessible on instances built on the [AWS Nitro System](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-nitro-instances.html). For more information, see [How Instance Metadata Service Version 2 works](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-v2-how-it-works.html) in the *Amazon EC2 User Guide*. 1. Save your changes. The system automatically creates one of the following files, depending on the operating system type. + On Ubuntu Server instances where SSM Agent is installed by using a snap: `/etc/systemd/system/snap.amazon-ssm-agent.amazon-ssm-agent.service.d/override.conf` + On Amazon Linux 2, Amazon Linux 2023, and RHEL instances: `/etc/systemd/system/amazon-ssm-agent.service.d/override.conf` + On other operating systems: `/etc/systemd/system/amazon-ssm-agent.service.d/amazon-ssm-agent.override` 1. Restart SSM Agent by using one of the following commands, depending on the operating system type. + On Ubuntu Server instances installed by using a snap: ``` sudo systemctl daemon-reload && sudo systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent ``` + On other operating systems: ``` sudo systemctl daemon-reload && sudo systemctl restart amazon-ssm-agent ``` **Note** For more information about working with `.override` files in systemd environments, see [Modifying Existing Unit Files](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/chap-managing_services_with_systemd#sect-Managing_Services_with_systemd-Unit_File_Modify) in the *Red Hat Enterprise Linux 7 System Administrator's Guide*. # Working with SSM Agent on EC2 instances for macOS AWS Systems Manager (SSM Agent) processes Systems Manager requests and configures your machine as specified in the request. Use the following procedures to install, configure, or uninstall SSM Agent for macOS. **Note** SSM Agent is preinstalled, by default, on Amazon Machine Images (AMIs) for macOS. You don't need to install SSM Agent on an Amazon Elastic Compute Cloud (Amazon EC2) instance for macOS unless you have uninstalled it. The source code for SSM Agent is available on [https://github.com/aws/amazon-ssm-agent](https://github.com/aws/amazon-ssm-agent) so that you can adapt the agent to meet your needs. We encourage you to submit [pull requests](https://github.com/aws/amazon-ssm-agent/blob/mainline/CONTRIBUTING.md) for changes that you would like to have included. However, AWS doesn't provide support for running modified copies of this software. **Note** To view details about the different versions of SSM Agent, see the [release notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md). Before you manually install SSM Agent on a macOS operating system, review the following information. + SSM Agent is installed by default on the EC2 instances and Amazon Machine Images supported by Systems Manager. For more information, see the [list of supported operating systems for macOS](operating-systems-and-machine-types.md#prereqs-os-mac). SSM Agent doesn't need to be manually installed on macOS EC2 instances unless it has been uninstalled. + EC2 instances for macOS are not supported in all AWS Regions. For lists of Regions where x86-based and M1 EC2 instances for macOS are supported, see [macOS workloads](https://aws.amazon.com/ec2/faqs/#macos_workloads) in the Amazon EC2 FAQs. + An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. **Topics** + [ # Manually installing and uninstalling SSM Agent on EC2 instances for macOS ](manually-install-ssm-agent-macos.md) # Manually installing and uninstalling SSM Agent on EC2 instances for macOS Connect to your macOS instance and perform the following steps to install AWS Systems Manager Agent (SSM Agent). Perform these steps on each instance that will run commands using Systems Manager. The commands provided in this procedure can also be passed to Amazon EC2 instances as scripts through user data. **Important** We strongly recommend that you avoid using OS versions that have reached End-of-Life (EOL). OS vendors including AWS typically don't provide security patches or other updates for versions that have reached EOL. Continuing to use an EOL system greatly increases the risk of not being able to apply upgrades, including security fixes, and other operational problems. AWS does not test Systems Manager functionality on OS versions that have reached EOL. **Before you begin** Install `wget` using Homebrew. **To install SSM Agent on macOS** 1. Download the agent installer file for x86\$164 instances using the following command. In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. ``` sudo wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/darwin_amd64/amazon-ssm-agent.pkg ``` For Apple silicon instances use the following command. ``` sudo wget https://s3.region.amazonaws.com/amazon-ssm-region/latest/darwin_arm64/amazon-ssm-agent.pkg ``` Here is an example. ``` sudo wget https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/latest/darwin_amd64/amazon-ssm-agent.pkg ``` 1. Use the following command to run the SSM Agent installer. x86\$164: ``` sudo installer -pkg amazon-ssm-agent.pkg -target / ``` 1. Check the status of the agent. To determine if SSM Agent is running, check the agent log at `/var/log/amazon/ssm/amazon-ssm-agent.log` . 1. Run the following command to start the service if the the agent log indicates that "amazon-ssm-agent is stopped." ``` sudo launchctl load -w /Library/LaunchDaemons/com.amazon.aws.ssm.plist && sudo launchctl start com.amazon.aws.ssm ``` **Important** An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. # Uninstall SSM Agent from macOS instances macOS doesn't natively support uninstallation of `PKG` files. To uninstall AWS Systems Manager Agent (SSM Agent) from an Amazon Elastic Compute Cloud (Amazon EC2) instance for macOS, you can use the AWS managed script from the following location. [https://github.com/aws/amazon-ssm-agent/blob/mainline/Tools/src/update/darwin/uninstall.sh](https://github.com/aws/amazon-ssm-agent/blob/mainline/Tools/src/update/darwin/uninstall.sh) # Working with SSM Agent on EC2 instances for Windows Server AWS Systems Manager Agent (SSM Agent) is preinstalled, by default, on the Amazon Machine Images (AMIs) for Windows Server that are provided by AWS. Support is provided for the following operating system (OS) versions. + Windows Server 2012 R2 AMIs published in November 2016 or later + Windows Server 2016, 2019, 2022 (excluding Nano versions), and 2025 **Support notes for previous versions** Windows Server AMIs published *before* November 2016 use the EC2Config service to process requests and configure instances. Unless you have a specific reason for using the EC2Config service, or an earlier version of SSM Agent, to process Systems Manager requests, we recommend that you download and install the latest version of SSM Agent to each of your Amazon Elastic Compute Cloud (Amazon EC2) instances or non-EC2 machines that are configured for Systems Manager in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. **Keeping SSM Agent up to date** An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. To view details about the different versions of SSM Agent, see the [release notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md). **Topics** + [ # Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server ](manually-install-ssm-agent-windows.md) + [ # Configure SSM Agent to use a proxy for Windows Server instances ](configure-proxy-ssm-agent-windows.md) # Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server AWS Systems Manager Agent (SSM Agent) is preinstalled, by default, on the following Amazon Machine Images (AMIs) for Windows Server provided by Amazon: + Windows Server 2012 R2 AMIs published in November 2016 or later + Windows Server 2016, 2019, 2022 (excluding Nano versions), and 2025 **Important** We strongly recommend that you avoid using OS versions that have reached End-of-Life (EOL). OS vendors including AWS typically don't provide security patches or other updates for versions that have reached EOL. Continuing to use an EOL system greatly increases the risk of not being able to apply upgrades, including security fixes, and other operational problems. AWS does not test Systems Manager functionality on OS versions that have reached EOL. ## Install SSM Agent on EC2 instances for Windows Server If necessary, you can manually download and install the latest version of SSM Agent on your Amazon Elastic Compute Cloud (Amazon EC2) instance for Windows Server by using the following procedure. The commands provided in this procedure can also be passed to Amazon EC2 instances as scripts through user data. SSM Agent requires Windows PowerShell 3.0 or later to run certain AWS Systems Manager documents (SSM documents) on Windows Server instances (for example, the legacy `AWS-ApplyPatchBaseline` document). Verify that your Windows Server instances are running Windows Management Framework 3.0 or later. This framework includes Windows PowerShell. For more information, see [Windows Management Framework 3.0](https://www.microsoft.com/en-us/download/details.aspx?id=34595&751be11f-ede8-5a0c-058c-2ee190a24fa6=True). **Installation on other machine types** This procedure in this topic applies specifically to installing or reinstalling SSM Agent on an EC2 instance for Windows Server. For on-premises servers, virtual machines, or other non-EC2 environments, use the `ssm-setup-cli` tool as described in [Install SSM Agent on hybrid Windows Server nodes](hybrid-multicloud-ssm-agent-install-windows.md). Using EC2 installation procedures on non-EC2 systems can potentially result in security vulnerabilities. The `ssm-setup-cli` tool provides additional security protections for non-EC2 machines. **To manually install the latest version of SSM Agent on EC2 instances for Windows Server** 1. Connect to your instance by using Remote Desktop or Windows PowerShell. For more information, see [Connect to your instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/EC2_GetStarted.html#ec2-connect-to-instance-windows) in the *Amazon EC2 User Guide*. 1. Download the latest version of SSM Agent to your instance. You can download using either PowerShell commands or a direct download link. **Note** The URLs in this step let you download SSM Agent from *any* AWS Region. If you want to download the agent from a specific Region, use a Region-specific URL instead: `https://amazon-ssm-region.s3.region.amazonaws.com/latest/windows_amd64/AmazonSSMAgentSetup.exe` *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **PowerShell** Run the following three PowerShell commands in order. These commands allow you to download SSM Agent without adjusting Internet Explorer (IE) Enhanced Security settings, and then install the agent and remove the installation file. ``` [System.Net.ServicePointManager]::SecurityProtocol = 'TLS12' $progressPreference = 'silentlyContinue' Invoke-WebRequest ` https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows_amd64/AmazonSSMAgentSetup.exe ` -OutFile $env:USERPROFILE\Desktop\SSMAgent_latest.exe ``` ``` [System.Net.ServicePointManager]::SecurityProtocol = 'TLS12' $progressPreference = 'silentlyContinue' Invoke-WebRequest ` https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows_386/AmazonSSMAgentSetup.exe ` -OutFile $env:USERPROFILE\Desktop\SSMAgent_latest.exe ``` ``` Start-Process ` -FilePath $env:USERPROFILE\Desktop\SSMAgent_latest.exe ` -ArgumentList "/S" ` -Wait ``` ``` rm -Force $env:USERPROFILE\Desktop\SSMAgent_latest.exe ``` **Direct download** Download the latest version of SSM Agent to your instance by using the following link. If you want, update this URL with an AWS Region-specific URL. [https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows\$1amd64/AmazonSSMAgentSetup.exe](https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows_amd64/AmazonSSMAgentSetup.exe) Run the downloaded `AmazonSSMAgentSetup.exe` file to install SSM Agent. 1. Start or restart SSM Agent by sending the following command in PowerShell: ``` Restart-Service AmazonSSMAgent ``` **Note** To uninstall the SSM Agent from a Windows Server instance, open **Control Panel**, **Programs**. Choose the **Uninstall a program** option. Open the context (right-click) menu for **Amazon SSM Agent** and choose **Uninstall**. # Configure SSM Agent to use a proxy for Windows Server instances The information in this topic applies to Windows Server instances created on or after November 2016 that do *not* use the Nano installation option. If you intend to use Session Manager, note that HTTPS proxy servers aren't supported. **Before you begin** Before you configure SSM Agent to use a proxy, note the following important information. In the following procedure, you run a command to configure SSM Agent to use a proxy. The command includes a `no_proxy` setting with an IP address. The IP address is the instance metadata services (IMDS) endpoint for Systems Manager. If you don't specify `no_proxy`, calls to Systems Manager take on the identity from the proxy service (if IMDSv1 fallback is enabled) or calls to Systems Manager fail (if IMDSv2 is enforced). + For IPv4, specify `no_proxy=169.254.169.254`. + For IPv6, specify `no_proxy=[fd00:ec2::254]`. The IPv6 address of the instance metadata service is compatible with IMDSv2 commands. The IPv6 address is only accessible on instances built on the [AWS Nitro System](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-nitro-instances.html). For more information, see [How Instance Metadata Service Version 2 works](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-v2-how-it-works.html) in the *Amazon EC2 User Guide*. **To configure SSM Agent to use a proxy** 1. Using Remote Desktop or Windows PowerShell, connect to the instance that you would like to configure to use a proxy. 1. Run the following command block in PowerShell. Replace *hostname* and *port* with the information about your proxy. ``` $serviceKey = "HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent" $keyInfo = (Get-Item -Path $serviceKey).GetValue("Environment") $proxyVariables = @("http_proxy=hostname:port", "https_proxy=hostname:port", "no_proxy=IP address for instance metadata services (IMDS)") if ($keyInfo -eq $null) { New-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables -PropertyType MultiString -Force } else { Set-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables } Restart-Service AmazonSSMAgent ``` After running the preceding command, you can review the SSM Agent logs to confirm the proxy settings were applied. Entries in the logs look similar to the following. For more information about SSM Agent logs, see [Viewing SSM Agent logs](ssm-agent-logs.md). ``` 2020-02-24 15:31:54 INFO Getting IE proxy configuration for current user: The operation completed successfully. 2020-02-24 15:31:54 INFO Getting WinHTTP proxy default configuration: The operation completed successfully. 2020-02-24 15:31:54 INFO Proxy environment variables: 2020-02-24 15:31:54 INFO http_proxy: hostname:port 2020-02-24 15:31:54 INFO https_proxy: hostname:port 2020-02-24 15:31:54 INFO no_proxy: IP address for instance metadata services (IMDS) 2020-02-24 15:31:54 INFO Starting Agent: amazon-ssm-agent - v2.3.871.0 2020-02-24 15:31:54 INFO OS: windows, Arch: amd64 ``` **To reset SSM Agent proxy configuration** 1. Using Remote Desktop or Windows PowerShell, connect to the instance to configure. 1. If you connected using Remote Desktop, launch PowerShell as an administrator. 1. Run the following command block in PowerShell. ``` Remove-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent -Name Environment Restart-Service AmazonSSMAgent ``` ## SSM Agent proxy setting precedence When configuring proxy settings for the SSM Agent on Windows Server instances, it's important to understand these settings are evaluated and applied to the agent configuration when the SSM Agent is started. How you configure your proxy settings for a Windows Server instance can determine whether other settings might supersede your intended settings. The agent uses the first proxy settings it finds. **Important** SSM Agent communicates using the HTTPS protocol. For this reason, you must configure the `HTTPS proxy` parameter by using one of the following settings options. SSM Agent proxy settings are evaluated in the following order. 1. `AmazonSSMAgent` Registry settings (`HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent`) 1. `System` environment variables (`http_proxy`, `https_proxy`, `no_proxy`) 1. `LocalSystem` user account environment variables `http_proxy`, `https_proxy`, `no_proxy`) 1. Browser settings (`HTTP`, `secure`, `exceptions`) 1. `WinHTTP` proxy settings (`http=`, `https=`, `bypass-list=`) ## SSM Agent proxy settings and Systems Manager services If you configured the SSM Agent to use a proxy and are using AWS Systems Manager tools, such as Run Command and Patch Manager, that use PowerShell or the Windows Update client during their execution on Windows Server instances, configure additional proxy settings. Otherwise, the operation might fail because proxy settings used by PowerShell and the Windows Update client aren't inherited from the SSM Agent proxy configuration. For Run Command, configure `WinINet` proxy settings on your Windows Server instances. The `[System.Net.WebRequest]` commands provided are per-session. To apply these configurations to subsequent network commands that are run in Run Command, these commands must precede other PowerShell commands in the same `aws:runPowershellScript` plugin input. The following PowerShell commands return the current `WinINet` proxy settings, and apply your proxy settings to `WinINet`. ``` [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 ``` For Patch Manager, configure system-wide proxy settings so the Windows Update client can scan for and download updates. We recommend that you use Run Command to run the following commands because they run on the SYSTEM account, and the settings apply system-wide. The following `netsh` commands return the current proxy settings, and apply your proxy settings to the local system. ``` netsh winhttp show proxy netsh winhttp set proxy proxy-server="hostname:port" bypass-list="169.254.169.254" ``` For more information about using Run Command, see [AWS Systems Manager Run Command](run-command.md). # Checking SSM Agent status and starting the agent This topic lists the commands to check whether AWS Systems Manager Agent (SSM Agent) is running on each supported operating system. It also provides the commands to start the agent if it isn't running. | Operating system | Command to check SSM Agent status | Command to start SSM Agent | | --- | --- | --- | | Amazon Linux 2and Amazon Linux 2023 | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | Debian Server11 and 12 | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | macOS | Check the agent log file at /var/log/amazon/ssm/amazon-ssm-agent.log | `sudo launchctl load -w /Library/LaunchDaemons/com.amazon.aws.ssm.plist` `sudo launchctl start com.amazon.aws.ssm` | | Oracle Linux | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | Red Hat Enterprise Linux (RHEL) 7.x, 8.x, 9.x, and 10.x | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | SUSE Linux Enterprise Server (SLES) | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | Ubuntu Server 16.04 (32-bit) | `sudo status amazon-ssm-agent` | `sudo start amazon-ssm-agent` | | Ubuntu Server 16.04 64-bit instances (deb package installation) | `sudo systemctl status amazon-ssm-agent` | `sudo systemctl enable amazon-ssm-agent` `sudo systemctl start amazon-ssm-agent` | | Ubuntu Server 16.04 LTS, 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04 | `sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service` | `sudo snap start amazon-ssm-agent` | | Windows Server | *Run in PowerShell:* `Get-Service AmazonSSMAgent` | *Run in PowerShell Administrator mode:* `Start-Service AmazonSSMAgent` | **More info** + [Working with SSM Agent on EC2 instances for Linux](ssm-agent-linux.md) + [Working with SSM Agent on EC2 instances for Windows Server](ssm-agent-windows.md) + [Checking the SSM Agent version number](ssm-agent-get-version.md) # Checking the SSM Agent version number Certain AWS Systems Manager functionalities have prerequisites that include a minimum Systems Manager Agent (SSM Agent) version be installed on your managed nodes. You can get the currently installed SSM Agent version on your managed nodes using the Systems Manager console, or by logging in to your managed nodes. **Note** To view details about earlier versions, see the [SSM Agent release notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) on GitHub. The following procedures describe how to get the currently installed SSM Agent version on your managed nodes. **To check the version number of SSM Agent installed on a managed node** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Fleet Manager**. 1. In the **SSM Agent version** column, note the **Agent version** number. **To get the currently installed SSM Agent version from within the operating system** Choose from the following tabs to get the currently installed SSM Agent version from within an operating system. ------ #### [ Amazon Linux 2 and Amazon Linux 2023 ] **Note** This command varies depending on the package manager for your operating system. 1. Log in to your managed node. 1. Run the following command. ``` yum info amazon-ssm-agent ``` This command returns output similar to the following. ``` Loaded plugins: extras_suggestions, langpacks, priorities, update-motd Installed Packages Name : amazon-ssm-agent Arch : x86_64 Version : 3.0.655.0 ``` ------ #### [ Debian Server ] 1. Log in to your managed node. 1. Run the following command. ``` apt list amazon-ssm-agent ``` This command returns output similar to the following. ``` apt list amazon-ssm-agent Listing... Done amazon-ssm-agent/now 3.0.655.0-1 amd64 [installed,local] 3.0.655.0 is the version of SSM agent ``` ------ #### [ macOS ] 1. Log in to your managed node. 1. Run the following command. ``` pkgutil --pkg-info com.amazon.aws.ssm ``` ------ #### [ RHEL ] 1. Log in to your managed node. 1. Run the following command for RHEL 7, 8, 9, and 10. ``` yum info amazon-ssm-agent ``` This command returns output similar to the following. ``` Loaded plugins: extras_suggestions, langpacks, priorities, update-motd Installed Packages Name : amazon-ssm-agent Arch : x86_64 Version : 3.0.655.0 ``` Run the following command for the DNF package utility. ``` dnf info amazon-ssm-agent ``` ------ #### [ SLES ] 1. Log in to your managed node. 1. Run the following command for SLES 15.*x*. ``` zypper info amazon-ssm-agent ``` This command returns output similar to the following. ``` Loading repository data... Reading installed packages... Information for package amazon-ssm-agent: ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ Repository : @System Name : amazon-ssm-agent Version : 3.0.655.0-1 ``` ------ #### [ Ubuntu Server ] **Note** To check if your Ubuntu Server 16.04 instance uses deb or Snap packages, see [Manually installing SSM Agent on Ubuntu Server instances](agent-install-ubuntu.md). 1. Log in to your managed node. 1. Run the following command for Ubuntu Server 16.04 64-bit (with deb installer package). ``` apt list amazon-ssm-agent ``` This command returns output similar to the following. ``` apt list amazon-ssm-agent Listing... Done amazon-ssm-agent/now 3.0.655.0-1 amd64 [installed,local] 3.0.655.0 is the version of SSM agent ``` Run the following command for Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 23.10, 24.04 LTS, 24.0, and 25.04. ``` sudo snap list amazon-ssm-agent ``` This command returns output similar to the following. ``` snap list amazon-ssm-agent Name Version Rev Tracking Publisher Notes amazon-ssm-agent 3.0.529.0 3552 latest/stable/… aws✓ classic- 3.0.529.0 is the version of SSM agent ``` ------ #### [ Windows ] 1. Log in to your managed node. 1. Run the following PowerShell command. ``` & "C:\Program Files\Amazon\SSM\amazon-ssm-agent.exe" -version ``` This command returns output similar to the following. ``` SSM Agent version: 3.1.804.0 ``` ------ We recommend using the latest version of the SSM Agent so you can benefit from new or updated capabilities. To ensure your managed instances are always running the most up-to-date version of the SSM Agent, you can automate the process of updating the SSM Agent. For more information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). # Viewing SSM Agent logs AWS Systems Manager Agent (SSM Agent) writes information about executions, commands, scheduled actions, errors, and health statuses to log files on each managed node. You can view log files by manually connecting to a managed node, or you can automatically send logs to Amazon CloudWatch Logs. For more information about sending logs to CloudWatch Logs, see [Logging and monitoring in AWS Systems Manager](monitoring.md). You can view SSM Agent logs on managed nodes in the following locations. ------ #### [ Linux and macOS ] `/var/log/amazon/ssm/` ------ #### [ Windows ] `%PROGRAMDATA%\Amazon\SSM\Logs\` ------ For Linux managed nodes, the SSM Agent `stderr` and `stdout` files are written to the following directory: `/var/lib/amazon/ssm/`. For Windows managed nodes, the SSM Agent `stderr` and `stdout` files are written to the following directory: `%PROGRAMDATA%\Amazon\SSM\InstanceData\`. For information about allowing SSM Agent debug logging, see [Allowing SSM Agent debug logging](#ssm-agent-debug-log-files). For more information about `cihub/seelog` configuration, see the [Seelog Wiki](https://github.com/cihub/seelog/wiki) on GitHub. For examples of `cihub/seelog` configurations, see the [cihub/seelog examples](https://github.com/cihub/seelog-examples) repository on GitHub. ## Allowing SSM Agent debug logging Use the following procedure to allow SSM Agent debug logging on your managed nodes. ------ #### [ Linux and macOS ] **To allow SSM Agent debug logging on Linux and macOS managed nodes** 1. Either use Session Manager, a tool in AWS Systems Manager, to connect to the managed node where you want to allow debug logging, or log on to the managed node. For more information, see [Working with Session Manager](session-manager-working-with.md). 1. Locate the **seelog.xml.template** file. **Linux**: On most Linux managed node types, the file is located in the directory `/etc/amazon/ssm/seelog.xml.template`. On Ubuntu Server 20.04, 18.04, and 16.04 LTS, the file is located in the directory `/snap/amazon-ssm-agent/current/seelog.xml.template`. Copy this file from the `/snap/amazon-ssm-agent/current/` directory to the `/etc/amazon/ssm/` directory before making any changes. **macOS**: On macOS instance types, the file is located in the directory `/opt/aws/ssm/seelog.xml.template`. 1. Change the file name from `seelog.xml.template` to `seelog.xml`. **Note** On Ubuntu Server 20.04, 18.04, and 16.04 LTS, the file `seelog.xml` must be created in the directory `/etc/amazon/ssm/`. You can create this directory and file by running the following commands. ``` sudo mkdir -p /etc/amazon/ssm ``` ``` sudo cp -p /snap/amazon-ssm-agent/current/seelog.xml.template /etc/amazon/ssm/seelog.xml ``` 1. Edit the `seelog.xml` file to change the default logging behavior. Change the value of **minlevel** from **info** to **debug**, as shown in the following example. `` 1. (Optional) Restart SSM Agent using the following command. Linux: ``` sudo service amazon-ssm-agent restart ``` macOS: ``` sudo /opt/aws/ssm/bin/amazon-ssm-agent restart ``` ------ #### [ Windows ] **To allow SSM Agent debug logging on Windows Server managed nodes** 1. Either use Session Manager to connect to the managed node where you want to allow debug logging, or log on to the managed nodes. For more information, see [Working with Session Manager](session-manager-working-with.md). 1. Make a copy of the **seelog.xml.template** file. Change the name of the copy to **seelog.xml**. The file is located in the following directory. `%PROGRAMFILES%\Amazon\SSM\seelog.xml.template` 1. Edit the `seelog.xml` file to change the default logging behavior. Change the value of **minlevel** from **info** to **debug**, as shown in the following example. `` 1. Locate the following entry. `filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\{{EXECUTABLENAME}}.log"` Change this entry to use the following path. `filename="C:\ProgramData\Amazon\SSM\Logs\{{EXECUTABLENAME}}.log"` 1. Locate the following entry. `filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\errors.log"` Change this entry to use the following path. `filename="C:\ProgramData\Amazon\SSM\Logs\errors.log"` 1. Restart SSM Agent using the following PowerShell command in Administrator mode. ``` Restart-Service AmazonSSMAgent ``` ------ # Restricting access to root-level commands through SSM Agent AWS Systems Manager Agent (SSM Agent) runs on Amazon Elastic Compute Cloud (Amazon EC2) instances and other machine types in [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environments using root permissions (Linux) or SYSTEM permissions (Windows Server). Because these are the highest level of system access permissions, any trusted entity that has been granted permission to send commands to SSM Agent has root or SYSTEM permissions. (In AWS, a trusted entity that can perform actions and access resources in AWS is called a *principal*. A principal can be an AWS account root user, user, or a role.) This level of access is required for a principal to send authorized Systems Manager commands to SSM Agent, but also makes it possible for a principal to run malicious code by exploiting any potential vulnerabilities in SSM Agent. In particular, permissions to run the commands [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html) and [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartSession.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartSession.html) should be carefully restricted. A good first step is to grant permissions for each command only to select principals in your organization. However, we recommend tightening your security posture even further by restricting which managed nodes a principal can run these commands on. This can be done in the IAM policy assigned to the principal. In the IAM policy, you can include a condition that limits the user to running commands only on managed nodes that are tagged with specific tags or a combination of tags. For example, say you have two fleets of servers, one for testing, one for production. In the IAM policy applied to junior engineers, you specify that they can run commands only on instances tagged with `ssm:resourceTag/testServer`. But, for a smaller group of lead engineers, who should have access to all instances, you grant access to instances tagged with both `ssm:resourceTag/testServer` and `ssm:resourceTag/productionServer`. Using this approach, if junior engineers attempt to run a command on a production instance, they will be denied access because their assigned IAM policy doesn't provide explicit access to instances tagged with `ssm:resourceTag/productionServer`. For more information and examples, see the following topics: + [Restricting Run Command access based on tags](run-command-setting-up.md#tag-based-access) + [Restrict session access based on instance tags](getting-started-restrict-access-examples.md#restrict-access-example-instance-tags) # Automating updates to SSM Agent AWS releases a new version of AWS Systems Manager Agent (SSM Agent) when we add or update Systems Manager tools. If your managed nodes use an older version of the agent, then you can't use the new tools or benefit from the updated tools. For these reasons, we recommend that you automate the process of updating SSM Agent on your managed nodes using any of the following methods. **Agent updates on the Bottlerocket operating system** SSM Agent on the Bottlerocket operating system can't be updated using the Systems Manager Command document `AWS-UpdateSSMAgent`. Updates are managed within the Bottlerocket control container. For more information, see [Bottlerocket Control Container](https://github.com/bottlerocket-os/bottlerocket-control-container/blob/develop/README.md) and [Bottlerocket update operator](https://github.com/bottlerocket-os/bottlerocket-update-operator/blob/develop/README.md) on GitHub. **macOS version requirement** If an instance is running macOS version 11.0 (Big Sur) or later, the instance must have the SSM Agent version 3.1.941.0 or higher to run the AWS-UpdateSSMAgent document. If the instance is running a version of SSM Agent released before 3.1.941.0, update your SSM Agent to run the AWS-UpdateSSMAgent by running `brew update` and `brew upgrade amazon-ssm-agent` commands. **** | Method | Details | | --- | --- | | One-click automated update on all managed nodes (Recommended) | You can configure all managed nodes in your AWS account to automatically check for and download new versions of SSM Agent. To do this, choose **Auto update SSM Agent** on the **Settings** tab in Fleet Manager, as described later in this topic. | | Global or selective update | You can use State Manager, a tool in AWS Systems Manager, to create an association that automatically downloads and installs SSM Agent on your managed nodes. If you want to limit the disruption to your workloads, you can create a Systems Manager maintenance window to perform the installation during designated time periods. Both methods allow you to create either a global update configuration for all of your managed nodes or selectively choose which instances get updated. For information about creating a State Manager association, see [Walkthrough: Automatically update SSM Agent with the AWS CLI](state-manager-update-ssm-agent-cli.md). For information about creating a maintenance window, see [Tutorial: Create a maintenance window for patching using the console](maintenance-window-tutorial-patching.md). | | Global or selective update for new environments | If you're getting started with Systems Manager, we recommend that you use the **Update Systems Manager (SSM) Agent every two weeks** option in Quick Setup, a tool in AWS Systems Manager. Quick Setup allows you to create either a global update configuration for all of your managed nodes or selectively choose which managed nodes get updated. For more information, see [Set up Amazon EC2 host management using Quick Setup](quick-setup-host-management.md). | If you prefer to update SSM Agent on your managed nodes manually, you can subscribe to notifications that AWS publishes when a new version of the agent is released. For information, see [Subscribing to SSM Agent notifications](ssm-agent-subscribe-notifications.md). After you subscribe to notifications, you can use Run Command to manually update one or more managed nodes with the latest version. For more information, see [Updating the SSM Agent using Run Command](run-command-tutorial-update-software.md#rc-console-agentexample). ## Automatically updating SSM Agent You can configure Systems Manager to automatically update SSM Agent on all Linux-based and Windows-based managed nodes in your AWS account. If you turn on this option, then Systems Manager automatically checks every two weeks for a new version of the agent. If there is a new version, then Systems Manager automatically updates the agent to the latest released version using the SSM document `AWS-UpdateSSMAgent`. We encourage you to choose this option to ensure that your managed nodes are always running the most up-to-date version of SSM Agent. **Note** If you use a `yum` command to update SSM Agent on a managed node after the agent has been installed or updated using the SSM document `AWS-UpdateSSMAgent`, you might see the following message: `"Warning: RPMDB altered outside of yum."` This message is expected and can be safely ignored. **To automatically update SSM Agent** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Fleet Manager**. 1. Choose the **Settings** tab. 1. In the **Agent auto update** area, choose **Auto update SSM Agent**. To change the version of SSM Agent your fleet updates to, choose **Edit** under **Agent auto update** on the **Settings** tab. Then enter the version number of SSM Agent you want to update to in **Version** under **Parameters**. If not specified, the agent updates to the latest version. To stop automatically deploying updated versions of SSM Agent to all managed nodes in your account, choose **Delete** under **Agent auto update** on the **Settings** tab. This action deletes the State Manager association that automatically updates SSM Agent on your managed nodes. # Subscribing to SSM Agent notifications Amazon Simple Notification Service (Amazon SNS) can notify you when new versions of AWS Systems Manager Agent (SSM Agent) are released. Use the following procedure to subscribe to these notifications. **Tip** You can also subscribe to notifications by watching the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub. **To subscribe to SSM Agent notifications** 1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home). 1. From the Region selector in the navigation bar, choose **US East (N. Virginia)**, if it isn't selected already. You must select this AWS Region because the Amazon SNS notifications for SSM Agent that you're subscribing to are generated from this Region only. 1. In the navigation pane, choose **Subscriptions**. 1. Choose **Create subscription**. 1. For **Create subscription**, do the following: 1. For **Topic ARN**, use the following Amazon Resource Name (ARN): `arn:aws:sns:us-east-1:720620558202:SSM-Agent-Update` 1. For **Protocol**, choose `Email` or `SMS`. 1. For **Endpoint**, depending on whether you chose `Email` or `SMS` in the previous step, enter an email address or an area code and number to receive notifications. 1. Choose **Create subscription**. 1. If you chose `Email`, you will receive an email message asking you to confirm your subscription. Open the message, and follow the directions to complete your subscription. Whenever a new version of SSM Agent is released, we send notifications to subscribers. If you no longer want to receive these notifications, use the following procedure to unsubscribe. **To unsubscribe from SSM Agent notifications** 1. Open the Amazon SNS console. 1. In the navigation pane, choose **Subscriptions**. 1. Select the subscription, and then choose **Delete**. When prompted for confirmation, choose **Delete**. # Troubleshooting SSM Agent If you experience problems running operations on your managed nodes, there might be a problem with AWS Systems Manager Agent (SSM Agent). Use the following information to help you view SSM Agent log files and troubleshoot the agent. If your agent appears to be unresponsive or has reduced communication frequency, see [Understanding SSM Agent hibernation](ssm-agent-technical-details.md#ssm-agent-hibernation). **Topics** + [ ## SSM Agent is out of date ](#ssm-agent-out-of-date) + [ ## Troubleshoot issues using SSM Agent log files ](#systems-manager-ssm-agent-log-files) + [ ## Agent log files don't rotate (Windows) ](#systems-manager-ssm-agent-troubleshooting-log-rotation) + [ ## Unable to connect to SSM endpoints ](#systems-manager-ssm-agent-troubleshooting-endpoint-access) + [ ## Verify your VPC configuration ](#agent-ts-vpc-configuration) + [ ## Verify your VPC DNS-related attributes ](#agent-ts-dns-attributes) + [ ## Verify ingress rules on endpoint security groups ](#agent-ts-ingress-egress-rules) + [ ## Use `ssm-cli` to troubleshoot managed node availability ](#agent-ts-ssm-cli) ## SSM Agent is out of date An updated version of SSM Agent is released whenever new tools are added to Systems Manager or updates are made to existing tools. Failing to use the latest version of the agent can prevent your managed node from using various Systems Manager tools and features. For that reason, we recommend that you automate the process of keeping SSM Agent up to date on your machines. For information, see [Automating updates to SSM Agent](ssm-agent-automatic-updates.md). Subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) page on GitHub to get notifications about SSM Agent updates. ## Troubleshoot issues using SSM Agent log files SSM Agent logs information in the following files. The information in these files can also help you troubleshoot problems. For more information about SSM Agent log files, including how to turn on debug logging, see [Viewing SSM Agent logs](ssm-agent-logs.md). **Note** If you choose to view these logs by using Windows File Explorer, be sure to allow the viewing of hidden files and system files in Folder Options. **On Windows** + `%PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log` + `%PROGRAMDATA%\Amazon\SSM\Logs\errors.log` **On Linux and macOS** + `/var/log/amazon/ssm/amazon-ssm-agent.log` + `/var/log/amazon/ssm/errors.log` For Linux managed nodes, you might find more information in the `messages` file written to the following directory: `/var/log`. For additional information about troubleshooting using agent logs, see [How do I use SSM Agent logs to troubleshoot issues with SSM Agent in my managed instance?](https://repost.aws/knowledge-center/ssm-agent-logs) in the *AWS re:Post Knowledge Center*. ## Agent log files don't rotate (Windows) If you specify date-based log file rotation in the seelog.xml file (on Windows Server managed nodes) and the logs don't rotate, specify the `fullname=true` parameter. Here is an example of a seelog.xml configuration file with the `fullname=true` parameter specified. ``` ``` ## Unable to connect to SSM endpoints SSM Agent must allow HTTPS (port 443) outbound traffic to the following endpoints: + `ssm.region.amazonaws.com` + `ssmmessages.region.amazonaws.com` *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **Note** Prior to 2024, `ec2messages.region.amazonaws.com` was also required. For AWS Regions launched before 2024, allowing traffic to `ssmmessages.region.amazonaws.com` is still required but optional to `ec2messages.region.amazonaws.com`. For Regions launched in 2024 and later, allowing traffic to `ssmmessages.region.amazonaws.com` is required, but `ec2messages.region.amazonaws.com` endpoints are not supported for these Regions. SSM Agent won't work if it can't communicate with the preceding endpoints, as described, even if you use AWS provided Amazon Machine Images (AMIs) such as Amazon Linux 2 or Amazon Linux 2023. Your network configuration must have open internet access or you must have custom virtual private cloud (VPC) endpoints configured. If you don't plan on creating a custom VPC endpoint, check your internet gateways or NAT gateways. For more information about how to manage VPC endpoints, see [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](setup-create-vpc.md). ## Verify your VPC configuration If you are using a virtual private cloud (VPC), in order to manage EC2 instances with Systems Manager, your VPC endpoints must be configured properly for `ssm.region.amazonaws.com`, `ssmmessages.region.amazonaws.com`, and in some cases explained earlier in this topic in [Unable to connect to SSM endpoints](#systems-manager-ssm-agent-troubleshooting-endpoint-access), `ec2messages.region.amazonaws.com`. **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` `ssmmessages.region.amazonaws.com` `ec2messages.region.amazonaws.com` 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). To troubleshoot issues with your VPC endpoints, do the following: + Ensure that VPC endpoints are included at the VPC level. If the VPC endpoint with a specific service name is not found on the VPC, first verify that DNS support is enabled at the VPC level. Next, create a new VPC endpoint and associate it with one subnet in each Availability Zone. + Ensure that a private DNS name is enabled at the VPC endpoint level. Private DNS names are enabled by default but might have been manually disabled at some point. + Ensure that existing VPC endpoints are associated with the proper subnet. In addition, ensure that the VPCE is already associated with a subnet in that Availability Zone. For more information, see the following topics: + [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com//vpc/latest/privatelink/create-interface-endpoint.html) in the *AWS PrivateLink Guide* + [Associate a private DNS name](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#associate-private-dns-name) in the *AWS PrivateLink Guide* + [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](setup-create-vpc.md) ## Verify your VPC DNS-related attributes If you are using a virtual private cloud (VPC), as part of verifying your VPC configuration, ensure that the attributes `enableDnsSupport` and `enableDnsHostnames` are enabled. You can enable these attributes using the Amazon EC2 [ModifyVPCAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVpcAttribute.html) API action or the AWS CLI command [modify-vpc-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-vpc-attribute.html). For information about enabling these attributes in the Amazon VPC Console, see [View and update DNS attributes for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns-updating.html) in the *Amazon VPC User Guide*. **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` `ssmmessages.region.amazonaws.com` `ec2messages.region.amazonaws.com` 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). ## Verify ingress rules on endpoint security groups Ensure that any VPC endpoints you have configured (`ssm`, `ssmmessages`, and `ec2messages`) include an ingress rule on their security groups to allow traffic in on port 443. If necessary, you can create a new security group in the VPC with an ingress rule to allow traffic on port 443 for the Classless Inter-Domain Routing (CIDR) block for the VPC. After you create the security group, attach it to each VPC endpoint. For more information, see the following topics: + [How do I create VPC endpoints so that I can use Systems Manager to manage private EC2 instances without internet access?](https://repost.aws/knowledge-center/ec2-systems-manager-vpc-endpoints) on AWS re:Post + [VPC CIDR blocks](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-cidr-blocks.html) in the *Amazon VPC User Guide* ## Use `ssm-cli` to troubleshoot managed node availability Starting with SSM Agent version 3.1.501.0, you can use `ssm-cli` to determine whether a managed node meets the primary requirements to be managed by Systems Manager, and to appear in lists of managed nodes in Fleet Manager. The `ssm-cli` is a standalone command line tool included in the SSM Agent installation. Preconfigured commands are included that gather the required information to help you diagnose why an Amazon EC2 instance or non-EC2 machine that you have confirmed is running isn't included in your lists of managed nodes in Systems Manager. These commands are run when you specify the `get-diagnostics` option. For more information, see [Troubleshooting managed node availability using `ssm-cli`](troubleshooting-managed-nodes-using-ssm-cli.md).