Menu
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Installing the SSM Agent

The Amazon EC2 Simple 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.

Note

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, Amazon Web Services does not currently provide support for running modified copies of this software.

The commands in this section require you to replace region with a region where SSM is available. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance. For servers and VMs in your hybrid environment, there is no cross-region data transfer cost, but we recommend that you specify the region closest to your data center or computing environment.

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

Amazon Linux, RHEL, and CentOS 64-bit

#!/bin/bash
cd /tmp
curl https://amazon-ssm-region.s3.amazonaws.com/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://amazon-ssm-region.s3.amazonaws.com/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://amazon-ssm-region.s3.amazonaws.com/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://amazon-ssm-region.s3.amazonaws.com/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://amazon-ssm-region.s3.amazonaws.com/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://amazon-ssm-region.s3.amazonaws.com/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. In these scripts, replace region with a region where SSM is available.

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. Replace region with the AWS region of your EC2 instance to avoid cross-region data transfer costs for the download.

    64-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/linux_amd64/amazon-ssm-agent.rpm -o amazon-ssm-agent.rpm

    32-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/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. Replace region with one of the AWS Regions where SSM is available. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance.

    64-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/debian_amd64/amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb

    32-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/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. Replace region with one of the AWS Regions where SSM is available. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance.

    64-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

    32-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/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. Replace region with one of the AWS Regions where SSM is available. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance.

    64-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm

    32-Bit

    curl https://amazon-ssm-region.s3.amazonaws.com/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