Why can't I install SSM Agent on my Amazon EC2 Linux instance?

Short description

SSM Agent is preinstalled on instances that you create from Amazon Machine Images (AMIs) with the following versionS of the Linux operating system (OS):

• AlmaLinux
• Amazon Linux 2
• Amazon Linux 2 ECS-Optimized Base AMIs
• Amazon Linux 2023 (AL2023)
• Ubuntu Server 16.04 LTS 64-bit (Snap), 18.04, 20.04, 22.04 LTS, 24.04 LTS, 24.0, and 25.04

For more information, see Find AMIs with the SSM Agent preinstalled.

You must manually install SSM Agent on instances that are based on RedHat, SUSE, or CentOS AMIs.

Resolution

Prerequisite: Before you install SSM Agent, verify that your OS supports Systems Manager and that you set up Systems Manager correctly.

Manually Install SSM Agent

For instructions on how to manually install SSM Agent on a Linux instance, see How do I install SSM Agent on an Amazon EC2 Linux instance at launch?

For Windows, see How do I install SSM Agent on an Amazon EC2 Windows instance at launch?

Note: It's a best practice to check the status of SSM Agent before you use Systems Manager on an instance for the first time. For instructions, see Verify the status of SSM Agent.

Troubleshoot package download failures

When you manually install SSM Agent, the SSM Agent package downloads and installs from an Amazon Simple Storage Service (Amazon S3) repository. If the instance can't connect to the S3 bucket to download the package, then the SSM Agent installation fails.

Verify that your instance has access to the S3 repository to download the SSM Agent package based on your configuration:

• If your instance is in a private subnet with a network address translation (NAT) gateway, then see NAT gateways.
• If your instance is in a private subnet with a NAT instance, then see NAT instances.
• If your EC2 instance is in a public subnet with an internet gateway, then see Internet gateway basics.
• If your instance is in a private or public subnet with an Amazon Virtual Private Cloud (Amazon VPC) endpoint, then see Gateway endpoints for Amazon S3.

Verify that your /etc/resolv.conf file includes the correct IP address for your DNS server

The following issues cause your package download to fail:

• The DNS servers in the OS can't resolve the Amazon S3 endpoint URLs.
• You deactivated DNS resolution for Amazon VPC.

To troubleshoot the previous errors, run the following command:

cat /etc/resolv.conf

Review the output and confirm that the nameserver IP address matches the IP address for your DNS server.

For more information, see How do I troubleshoot connectivity issues with my gateway Amazon VPC endpoints?

Verify your SSM Agent package

SSM Agent package files have cryptographic signatures. To make sure that your SSM Agent package is original, use either RPM Package Manager or GNU Privacy Guard to verify the installer package's signature.

RPM Package Manager

RPM Package Manager packages include the required verification signature. When you use RPM Package Manager to install SSM Agent, run the following command to import the public key into your keyring:

rpm --import amazon-ssm-agent.gpg

The following error indicates that you use an RHEL Linux 8.x and 9.x instances with a deprecated SHA1 algorithm:

"Transaction test error: package amazon-ssm-agent-VERSION_NO does not verify: Header V4 RSA/SHA1 Signature"

To resolve this issue, use GNU Privacy Guard to manually import the public key.

GNU Privacy Guard

If you use GNU Privacy Guard to verify the installer package, then you must manually import the public key. The following error appears when you you don't manually import the public key and you use GNU Privacy Guard:

"Public key for amazon-ssm-agent.rpm is not installed"

To use GNU Privacy Guard to verify your SSM Agent package, run the following command to manually import the public key:

gpg --import amazon-ssm-agent.gpg

Then, verify the SSM Agent installer package's signature, and then install SSM agent.