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

Short description

SSM Agent comes preinstalled on most AWS provided Amazon Machine Images (AMIs):

• Amazon Linux
• Amazon Linux 2
• Amazon Elastic Container Service (Amazon ECS) optimized base AMIs on Amazon Linux 2
• Ubuntu Server 16.04, 18.04, and 20.04

However, to manage instances that are based on RedHat, SUSE, or CentOS AMIs, you must manually install SSM Agent.

Resolution

To troubleshoot SSM Agent installation failures, check the following common issues:

Unsupported operating system version

SSM Agent isn't available for all operating system (OS) versions. If you run an unsupported version of an OS, then SSM Agent installation fails. To confirm if SSM Agent is available for your OS, see Supported operating systems for Systems Manager.

Package download failure

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 SSM Agent installation fails.

Verify that your Amazon EC2 instance has access to the S3 repository to download the SSM Agent package:

• 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 instance is in a public subnet with an internet gateway, then see Activate internet access.
• If your instance is in a private or public subnet with an Amazon S3 virtual private cloud (VPC) endpoint, then see Gateway endpoints for Amazon S3.

The package download can also fail in the following scenarios:

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

To verify that the /etc/resolv.conf file includes the correct IP address for your DNS server, run the following command. Then, review the output and confirm that the nameserver IP address matches the IP address for your DNS server:

$ cat /etc/resolv.conf

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

Missing public key for SSM Agent package

SSM Agent package files have cryptographic signatures. To make sure that the agent package is original, use a public key to verify the installer package signature. You can use either RPM Package Manager (RPM) or GNU Privacy Guard (GPG). RPM packages already include the required signature for RPM verification. If you use GPG to verify the installer package, then you must manually import the public key. Otherwise, installation fails with the following error:

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

For more information, see Verifying the signature of SSM Agent.

Transaction test error

When you use RPM to install SSM Agent, run the following command to import the public key into your keyring:

rpm --import amazon-ssm-agent.gpg 

After you run this command and try to install SSM Agent, you might see the following error:

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

This error might occur in RHEL Linux 8.x and 9.x instances with a deprecated SHA1 algorithm. To resolve this issue, follow these steps:

1. Use GPG to manually import the public key:

   gpg --import amazon-ssm-agent.gpg

2. Verify the signature of SSM Agent, and then install the SSM agent.