Menu
Amazon EC2 Systems Manager
User Guide

Installing and Configuring SSM Agent on Linux Instances

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

Note

SSM Agent is installed, by default, on Amazon Linux AMIs dated 2017.09 and later. You must manually install SSM Agent on other versions of Linux, as described in this section. For backwards compatibility, this section still includes information about manually installing the agent on Amazon Linux.

The source code for 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.

Note

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

Install SSM Agent on Amazon EC2 Linux Instances at Launch

You can install SSM Agent when you launch an instance for the first time by using Amazon 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 SSM Agent at start-up

Note

  • The process for installing SSM Agent on Raspbian Jessie devices is different than other Linux versions. For more information, see Raspbian.

  • 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, copy the URL for your operating system, and then replace region with a region where SSM is available.

    For example, to download the SSM Agent for Amazon Linux, RHEL, CentOS, and SLES 64-bit from the US West 1 Region, use the following URL:

    Copy
    https://s3-us-west-1.amazonaws.com/amazon-ssm-us-west-1/latest/linux_amd64/amazon-ssm-agent.rpm

    If the download fails, try replacing https://s3-region with https://s3.region.

  • Amazon Linux, RHEL, CentOS, and SLES 64-bit:

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

  • Amazon Linux, RHEL, and CentOS 32-bit:

    https://s3-region.amazonaws.com/amazon-ssm-region/latest/linux_386/amazon-ssm-agent.rpm

  • Ubuntu Server 64-bit:

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

  • Ubuntu Server 32-bit:

    https://s3-region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb

  • Raspbian:

    https://s3-region.amazonaws.com/amazon-ssm-region/latest/debian_arm/amazon-ssm-agent.deb

RHEL 7.x and CentOS 7.x, 64-bit

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

RHEL 7.x and CentOS 7.x, 32-bit

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

Amazon Linux, RHEL 6.x, and CentOS 6.x, 64-bit

Note

SSM Agent is installed, by default, on Amazon Linux AMIs dated 2017.09 and later.

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

Amazon Linux, RHEL 6.x, and CentOS 6.x, 32-bit

Note

SSM Agent is installed, by default, on Amazon Linux AMIs dated 2017.09 and later.

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

Ubuntu Server 16 64-bit

Copy
#!/bin/bash cd /tmp wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb sudo dpkg -i amazon-ssm-agent.deb sudo systemctl enable amazon-ssm-agent

Ubuntu Server 16 32-bit

Copy
#!/bin/bash cd /tmp wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb sudo dpkg -i amazon-ssm-agent.deb sudo systemctl enable amazon-ssm-agent

SLES 64-bit

Copy
#!/bin/bash cd /tmp wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm sudo rpm --install amazon-ssm-agent.rpm sudo systemctl start amazon-ssm-agent

Ubuntu Server 14 64-bit

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

Ubuntu Server 14 32-bit

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

Save your changes, and complete the wizard. When the instance launches, the system copies 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 Commands Using Systems Manager Run Command.

Note

You can automatically update SSM Agent on your instances when new versions become available by using Systems Manager State Manager. For more informaiton, see Walkthrough: Automatically Update the SSM Agent.

Manually Install SSM Agent on Amazon EC2 Linux Instances

Use one of the following scripts to install SSM Agent on one of the following Linux instances.

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, copy the URL for your operating system, and then replace region with a region where SSM is available.

For example, to download the SSM Agent for Amazon Linux, RHEL, CentOS, and SLES 64-bit from the US West 1 Region, use the following URL:

Copy
https://s3-us-west-1.amazonaws.com/amazon-ssm-us-west-1/latest/linux_amd64/amazon-ssm-agent.rpm

If the download fails, try replacing https://s3-region with https://s3.region.

  • Amazon Linux, RHEL, CentOS, and SLES 64-bit:

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

  • Amazon Linux, RHEL, and CentOS 32-bit:

    https://s3-region.amazonaws.com/amazon-ssm-region/latest/linux_386/amazon-ssm-agent.rpm

  • Ubuntu Server 64-bit:

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

  • Ubuntu Server 32-bit:

    https://s3-region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb

After you manually install SSM Agent, you can automatically update SSM Agent on your instances when new versions become available by using Systems Manager State Manager. For more information, see Walkthrough: Automatically Update the SSM Agent.

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.

Note

SSM Agent is installed, by default, on Amazon Linux AMIs dated 2017.09 and later.

To install SSM Agent on Amazon Linux

  1. Create a temporary directory on the instance.

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

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

    64-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm

    32-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm
  4. Run the following command to determine if SSM Agent is running. The command should return "amazon-ssm-agent is running."

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

    1. Start the service.

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

      Copy
      sudo status amazon-ssm-agent

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 SSM Agent on Ubuntu

  1. Create a temporary directory on the instance.

    Copy
    mkdir /tmp/ssm
  2. Use one of the following commands to download and run the SSM installer.

    64-Bit

    Copy
    wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/amazon-ssm-agent.deb sudo dpkg -i amazon-ssm-agent.deb

    32-Bit

    Copy
    wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-ssm-agent.deb sudo dpkg -i amazon-ssm-agent.deb
  3. Run the following command to determine if SSM Agent is running.

    Ubuntu Server 14

    Copy
    sudo status amazon-ssm-agent

    Ubuntu Server 16

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

    1. Start the service.

      Ubuntu Server 14

      Copy
      sudo start amazon-ssm-agent

      Ubuntu Server 16

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

      Ubuntu Server 14

      Copy
      sudo status amazon-ssm-agent

      Ubuntu Server 16

      Copy
      sudo systemctl status amazon-ssm-agent

Red Hat Enterprise Linux

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

To install SSM Agent on Red Hat Enterprise Linux

  1. Create a temporary directory on the instance.

    Copy
    mkdir /tmp/ssm
  2. Use one of the following commands to download and run the SSM installer.

    64-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm

    32-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm
  3. Run one of the following commands to determine if SSM Agent is running. The command should return "amazon-ssm-agent is running."

    RHEL 7.x

    Copy
    sudo systemctl status amazon-ssm-agent

    RHEL 6.x

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

    1. Start the service.

      RHEL 7.x

      Copy
      sudo systemctl enable amazon-ssm-agent
      Copy
      sudo systemctl start amazon-ssm-agent

      RHEL 6.x

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

      RHEL 7.x

      Copy
      sudo systemctl status amazon-ssm-agent

      RHEL 6.x

      Copy
      sudo status amazon-ssm-agent

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 SSM Agent on CentOS

  1. Create a temporary directory on the instance.

    Copy
    mkdir /tmp/ssm
  2. Use one of the following commands to download and run the SSM installer.

    64-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm

    32-Bit

    Copy
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_386/amazon-ssm-agent.rpm
  3. Run one of the following commands to determine if SSM Agent is running. The command should return "amazon-ssm-agent is running."

    CentOS 7.x

    Copy
    sudo systemctl status amazon-ssm-agent

    CentOS 6.x

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

    1. Start the service.

      CentOS 7.x

      Copy
      sudo systemctl enable amazon-ssm-agent
      Copy
      sudo systemctl start amazon-ssm-agent

      CentOS 6.x

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

      CentOS 7.x

      Copy
      sudo systemctl status amazon-ssm-agent

      CentOS 6.x

      Copy
      sudo status amazon-ssm-agent

SLES

Connect to your SLES 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 SSM Agent on SLES

  1. Create a temporary directory on the instance.

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

    Copy
    cd /tmp/ssm
  3. Use the following command to download and run the SSM installer.

    64-Bit

    Copy
    wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm sudo rpm --install amazon-ssm-agent.rpm
  4. Run the following command to determine if SSM Agent is running. The command should return "amazon-ssm-agent is running."

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

    1. Start the service.

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

      Copy
      sudo systemctl status amazon-ssm-agent

Raspbian

This section includes information about how to install SSM Agent on Raspbian Jessie and Raspbian Stretch, including Raspberry Pi (32-bit) devices.

Before You Begin

To set up your Raspbian devices as Systems Manager managed instances, you need to create a managed-instance activation. After you complete the activation, you receive an activation code and ID. This code/ID combination functions like an Amazon EC2 access ID and secret key to provide secure access to the Systems Manager service from your managed instances. Store the activation code and ID in a safe place. For more information about the activation process, see Setting Up Systems Manager in Hybrid Environments.

Connect to your Raspbian device 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 SSM Agent on Raspbian devices

  1. Create a temporary directory on the instance.

    Copy
    mkdir /tmp/ssm
  2. Use the following command to download and run the SSM installer.

    Copy
    sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_arm/amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb
  3. Execute the following command to install SSM Agent.

    Copy
    sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb
  4. Execute the following command to stop SSM Agent.

    Copy
    sudo service amazon-ssm-agent stop
  5. Execute the following command to register the agent using the managed-instance activation code and ID you received when you completed the managed-instance activation process.

    Copy
    sudo amazon-ssm-agent -register -code "code" -id "ID" -region "Region"
  6. Execute the following command to start SSM Agent.

    Copy
    sudo service amazon-ssm-agent start

Configure SSM Agent to Use a Proxy

You can configure 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 SSM Agent to use a proxy (Upstart)

  1. Connect to the instance where you installed 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 following settings to the file in the following format:

    Copy
    env http_proxy=http://hostname:port env https_proxy=http://hostname:port env HTTP_PROXY=http://hostname:port env HTTPS_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:

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

  6. Stop and restart SSM Agent using the following commands:

    Copy
    sudo stop amazon-ssm-agent sudo start amazon-ssm-agent

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

Copy
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 SSM Agent to use a proxy (systemd)

  1. Connect to the instance where you installed 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 following settings to the file:

    Copy
    Environment="http_proxy=http://hostname:port" Environment="https_proxy=http://hostname:port" Environment="HTTP_PROXY=http://hostname:port" Environment="HTTPS_PROXYy=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:

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

  6. Restart SSM Agent using the following commands:

    Copy
    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:

Copy
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

View SSM Agent Logs

SSM Agent writes information about executions, scheduled actions, errors, and health statuses to log files on each instance. You can view log files by manually connecting to an instance, or you can automatically send logs to Amazon CloudWatch Logs. For more information about sending logs to CloudWatch, see Sending SSM Agent Log Files to Amazon CloudWatch Logs.

You can view SSM Agent logs on Linux instances in the following locations.

  • /var/log/amazon/ssm/amazon-ssm-agent.log

  • /var/log/amazon/ssm/errors.log

You can enable extended logging by updating the seelog.xml file. By default, the configuration file is located here: /etc/amazon/ssm/seelog.xml.

For more information about cihub/seelog configuration, go to the cihub/seelog Wiki. For examples of cihub/seelog configurations, go to cihub/seelog examples.

Uninstall SSM Agent from Linux Instances

Use the following commands to uninstall SSM Agent.

Amazon Linux, RHEL, or Cent OS

Copy
sudo yum erase amazon-ssm-agent –y

Ubuntu

Copy
sudo dpkg -r amazon-ssm-agent

SLES

Copy
sudo rpm --erase amazon-ssm-agent