AWS Systems Manager
User Guide

Installing and Configuring SSM Agent

AWS Systems Manager Agent (SSM Agent) is Amazon software that runs on your Amazon EC2 instances and your hybrid instances that are configured for Systems Manager (hybrid instances). SSM Agent processes requests from the Systems Manager service in the cloud and configures your machine as specified in the request. SSM Agent sends status and execution information back to the Systems Manager service by using the EC2 Messaging service. If you monitor traffic, you will see your instances communicating with ec2messages.* endpoints. For more information, see Reference: ec2messages, ssmmessages, and Other API Calls.

Starting with version of SSM Agent, the agent creates a local user account called ssm-user and adds it to /etc/sudoers (Linux) or to the Administrators group (Windows) every time the agent starts. This ssm-user is the default OS user when a Session Manager session is started, and the password for this user is reset on every session. You can change the permissions by moving ssm-user to a less-privileged group or by changing the sudoers file. The ssm-user account is not removed from the system when SSM Agent is uninstalled.

SSM Agent is installed, by default, on the following Amazon EC2 Amazon Machine Images (AMIs):

  • Windows Server (all SKUs)

  • Amazon Linux

  • Amazon Linux 2

  • Ubuntu Server 16.04

  • Ubuntu Server 18.04

You must manually install SSM Agent on Amazon EC2 instances created from other Linux AMIs. You must also manually install SSM Agent on servers or virtual machines in your on-premises environment. For more information, see Setting Up AWS Systems Manager in Hybrid Environments.


  1. SSM Agent is updated whenever changes are made to Systems Manager and when new capabilities are added. AMIs that include SSM Agent by default can take up to two weeks to publish an updated AMI with the newest version of SSM Agent. To ensure that your instances are running the newest version of SSM Agent, we recommend that you create a State Manager association that automatically updates SSM Agent when a new version is available. You can also use Run Command to quickly update one or more instances with the latest version. For more information, see Automatically Update SSM Agent (CLI) (State Manager) and Update SSM Agent by using Run Command.

  2. Updated versions of SSM Agent are rolled out to new AWS Regions at different times. For this reason, you might receive the "Unsupported on current platform" error when trying to deploy a new version of SSM Agent in a Region.

For information about porting SSM Agent logs to Amazon CloudWatch Logs, see Monitoring Instances with AWS Systems Manager.

Use the following procedures to install, configure, or uninstall SSM Agent. This section also includes information about configuring SSM Agent to use a proxy.