Menu
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Installing the SSM Agent

The Amazon EC2 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 the SSM agent.

The source code for the SSM agent is available on GitHub so that you can adapt the agent to meet your needs. We encourage you to submit pull requests for changes that you would like to have included. However, AWS does not currently provide support for running modified copies of this software.

To view details about the different versions of SSM Agent, see the release notes.

Information for Windows Users

See Installing and Updating SSM Agent in the Amazon EC2 User Guide for Windows Instances.

Install the SSM Agent on EC2 Instances at Start-Up

You can install the SSM agent when you launch an instance for the first time by using EC2 User Data. On the Configure Instance Details page of the launch wizard, expand Advanced Details and then copy and paste one of the following scripts into the User data field. For example:

Install the SSM agent at start-up

Note

The URLs in the following scripts let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, replace https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/ with https://amazon-ssm-region.s3.amazonaws.com/. And then replace region with a region where SSM is available.

Amazon Linux, RHEL, and CentOS 64-bit

#!/bin/bash
cd /tmp
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm
yum install -y amazon-ssm-agent.rpm

Amazon Linux, RHEL, and CentOS 32-bit

#!/bin/bash
cd /tmp
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm
yum install -y amazon-ssm-agent.rpm

Ubuntu Server 16 64-bit

#!/bin/bash
cd /tmp			
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb -o amazon-ssm-agent.deb
dpkg -i amazon-ssm-agent.deb
systemctl start amazon-ssm-agent

Ubuntu Server 16 32-bit

#!/bin/bash
cd /tmp			
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb -o amazon-ssm-agent.deb
dpkg -i amazon-ssm-agent.deb
systemctl start amazon-ssm-agent

Ubuntu Server 14 64-bit

#!/bin/bash
cd /tmp			
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb -o amazon-ssm-agent.deb
dpkg -i amazon-ssm-agent.deb
start amazon-ssm-agent

Ubuntu Server 14 32-bit

#!/bin/bash
cd /tmp			
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb -o amazon-ssm-agent.deb
dpkg -i amazon-ssm-agent.deb
start amazon-ssm-agent

Save your changes, and complete the wizard. When the instance launches, the system copies the SSM agent to the instance and starts it. When the instance is online, you can configure it using Run Command. For more information, see Executing a Command Using Amazon EC2 Run Command.

Manually Install the SSM Agent on EC2 Instances

Use one of the following scripts to install the SSM agent on Amazon Linux, Ubuntu, CentOS, or Red Hat Enterprise Linux.

Install the SSM Agent on Amazon Linux

Connect to your Amazon Linux instance and perform the following steps to install the SSM agent. Perform these steps on each instance that will execute commands using Systems Manager.

To install the SSM agent on Amazon Linux

  1. Create a temporary directory on the instance.

    mkdir /tmp/ssm
  2. Change to the temporary directory.

    cd /tmp/ssm
  3. Use one of the following commands to download the SSM installer.

    Note

    The URLs in this section let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, replace https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/ with https://amazon-ssm-region.s3.amazonaws.com/. And then replace region with a region where SSM is available.

    64-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm

    32-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm
  4. Run the SSM installer.

    sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
  5. Run the following command to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."

    sudo status amazon-ssm-agent
  6. Execute the following commands if the previous command returns, "amazon-ssm-agent is stopped."

    1. Start the service.

      sudo start amazon-ssm-agent
    2. Check the status of the agent.

      sudo status amazon-ssm-agent

Install the SSM Agent on Ubuntu

Connect to your Ubuntu instance and perform the following steps to install the SSM agent. Perform these steps on each instance that will execute commands using Systems Manager.

To install the SSM agent on Ubuntu

  1. Create a temporary directory on the instance.

    mkdir /tmp/ssm
  2. Use one of the following commands to download the SSM installer to the temporary directory.

    Note

    The URLs in this section let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, replace https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/ with https://amazon-ssm-region.s3.amazonaws.com/. And then replace region with a region where SSM is available.

    64-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb

    32-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb
  3. Run the SSM installer.

    sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb
  4. Run the following command to determine if the SSM agent is running.

    Ubuntu Server 14

    sudo status amazon-ssm-agent

    Ubuntu Server 16

    sudo systemctl status amazon-ssm-agent
  5. Execute the following commands if the previous command returned "amazon-ssm-agent is stopped" or "inactive".

    1. Start the service.

      Ubuntu Server 14

      sudo start amazon-ssm-agent

      Ubuntu Server 16

      sudo systemctl start amazon-ssm-agent
    2. Check the status of the agent.

      Ubuntu Server 14

      sudo status amazon-ssm-agent

      Ubuntu Server 16

      sudo systemctl status amazon-ssm-agent

Install the SSM Agent on Red Hat Enterprise Linux

Connect to your Red Hat Enterprise Linux (RHEL) instance and perform the following steps to install the SSM agent. Perform these steps on each instance that will execute commands using Systems Manager.

To install the SSM agent on Red Hat Enterprise Linux

  1. Create a temporary directory on the instance.

    mkdir /tmp/ssm
  2. Use one of the following commands to download the SSM installer to the temporary directory.

    Note

    The URLs in this section let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, replace https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/ with https://amazon-ssm-region.s3.amazonaws.com/. And then replace region with a region where SSM is available.

    64-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

    32-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
  3. Run the SSM installer.

    sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
  4. Run one of the following commands to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."

    RHEL 7.x

    sudo systemctl status amazon-ssm-agent

    RHEL 6.x

    sudo status amazon-ssm-agent
  5. Execute the following commands if the previous command returned "amazon-ssm-agent is stopped."

    1. Start the service.

      RHEL 7.x

      sudo systemctl start amazon-ssm-agent

      RHEL 6.x

      sudo start amazon-ssm-agent
    2. Check the status of the agent.

      RHEL 7.x

      sudo systemctl status amazon-ssm-agent

      RHEL 6.x

      sudo status amazon-ssm-agent

Install the SSM Agent on CentOS

Connect to your CentOS instance and perform the following steps to install the SSM agent. Perform these steps on each instance that will execute commands using Systems Manager.

To install the SSM agent on CentOS

  1. Create a temporary directory on the instance.

    mkdir /tmp/ssm
  2. Use one of the following commands to download the SSM installer to the temporary directory.

    Note

    The URLs in this section let you download the SSM agent from any AWS region. If you want to download the agent from a specific region, replace https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/ with https://amazon-ssm-region.s3.amazonaws.com/. And then replace region with a region where SSM is available.

    64-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

    32-Bit

    curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
  3. Run the SSM installer.

    sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
  4. Run one of the following commands to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."

    CentOS 7.x

    sudo systemctl status amazon-ssm-agent

    CentOS 6.x

    status amazon-ssm-agent
  5. Execute the following commands if the previous command returned "amazon-ssm-agent is stopped."

    1. Start the service.

      CentOS 7.x

      sudo systemctl start amazon-ssm-agent

      CentOS 6.x

      sudo start amazon-ssm-agent
    2. Check the status of the agent.

      CentOS 7.x

      sudo systemctl status amazon-ssm-agent

      CentOS 6.x

      sudo status amazon-ssm-agent

Configure the SSM Agent to Use a Proxy

You can configure the SSM agent to communicate through an HTTP proxy by adding the http_proxy and no_proxy settings to the SSM agent configuration file. This section includes procedures for upstart and systemd environments.

To configure the SSM agent to use a proxy (Upstart)

  1. Connect to the instance where you installed the SSM agent.

  2. Open the amazon-ssm-agent.conf file in an editor such as VIM. By default, the file is located here:

    /etc/init/amazon-ssm-agent.conf

  3. Add the http_proxy setting to the file in the following format:

    env http_proxy=http://hostname:port
  4. Add the no_proxy setting to the file in the following format. You must specify the IP address listed here. It is the instance metadata endpoint for SSM and without this IP address calls to SSM fail:

    env no_proxy=169.254.169.254
  5. Save your changes and close the editor.

  6. Restart the SSM agent using the following command:

    sudo restart amazon-ssm-agent

The following Upstart example includes the http_proxy and no_proxy settings in the amazon-ssm-agent.conf file:

description "Amazon SSM Agent"
author "Amazon.com"

start on (runlevel [345] and started network)
stop on (runlevel [!345] or stopping network)

respawn

env http_proxy=http://i-1234567890abcdef0:443
env no_proxy=169.254.169.254

chdir /usr/bin/
exec ./amazon-ssm-agent

To configure the SSM agent to use a proxy (systemd)

  1. Connect to the instance where you installed the SSM agent.

  2. Open the amazon-ssm-agent.service file in an editor such as VIM. By default, the file is located here:

    /etc/systemd/system/amazon-ssm-agent.service

  3. Add the http_proxy setting to the file in the following format:

    Environment="HTTP_PROXY=http://hostname:port"
  4. Add the no_proxy setting to the file in the following format. You must specify the IP address listed here. It is the instance metadata endpoint for SSM and without this IP address calls to SSM fail:

    Environment="no_proxy=169.254.169.254"
  5. Save your changes and close the editor.

  6. Restart the SSM agent using the following commands:

    sudo systemctl stop amazon-ssm-agent
    sudo systemctl daemon-reload

The following systemd example includes the http_proxy and no_proxy settings in the amazon-ssm-agent.service file:

Type=simple
Environment="HTTP_PROXY=http://i-1234567890abcdef0:443"
Environment="no_proxy=169.254.169.254"
WorkingDirectory=/opt/amazon/ssm/
ExecStart=/usr/bin/amazon-ssm-agent
KillMode=process
Restart=on-failure
RestartSec=15min

Uninstall the SSM Agent

Use the following commands to uninstall the SSM agent.

To uninstall the SSM agent on Amazon Linux, RHEL, or Cent OS

sudo yum erase amazon-ssm-agent –y

To uninstall the SSM agent on Ubuntu

sudo dpkg -r amazon-ssm-agent