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

Short description

SSM Agent is pre-installed on most Amazon Web Services (AWS) provided Amazon Machine Images (AMIs), including the following:

• Amazon Linux
• Amazon Linux 2
• Amazon Linux 2 ECS-optimized base AMIs
• Ubuntu Server 16.04, 18.04, and 20.04

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

Resolution

Verify the following to troubleshoot SSM Agent installation failures:

Unsupported operating system version

SSM Agent isn’t available for all operating system (OS) versions. SSM Agent installation fails if you run an unsupported version of an OS. Verify the list of supported operating systems to confirm whether SSM Agent is available for your OS version.

Package download failure

During the manual installation process for 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, 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 Enable internet access.
• If your instance is in a private or public subnet with an Amazon S3 virtual private cloud (VPC) endpoint, then see Endpoints for Amazon S3.

The package download can also fail under the following circumstances:

• The Domain Name System (DNS) servers configured within the OS can’t resolve the Amazon S3 endpoint URLs.
• DNS resolution is deactivated for the VPC.

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

$ cat /etc/resolv.conf

For more information, see Why can’t I connect to an S3 bucket using a gateway VPC endpoint?

Missing public key for SSM Agent package

SSM Agent package files are cryptographically signed. To verify that the agent package is original, you can use a public key to verify the installer package signature using either RPM or GPG. RPM packages already include the required signature for RPM verification. However, if you use GPG to verify the installer package, you must manually import the public key. Otherwise, installation fails with the error “Public key for amazon-ssm-agent.rpm is not installed”.

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

---

Related information

How do I install AWS Systems Manager Agent (SSM Agent) on an Amazon EC2 Linux instance at launch?

Automating updates to SSM Agent

Installing and configuring SSM Agent on EC2 instances for Linux