Menu
Amazon EC2 Systems Manager
User Guide

Installing SSM Agent

The Amazon EC2 Systems Manager (SSM) agent processes Systems Manager requests and configures your machine as specified in the request.

SSM communicates with the SSM Agent on your instance by using the EC2 Messaging service. If you monitor traffic, you will see your instances communicating with ec2messages.* endpoints.

Use the following procedures to install, configure, or uninstall the SSM agent.

Installing SSM Agent on Windows

An agent running on your instances processes Systems Manager requests and configures your instances as specified in the request. The SSM Agent is installed by default on Windows Server 2016 instances and instances created from Windows Server 2003-2012 R2 AMIs published in November 2016 or later.

Windows AMIs published before November 2016 use the EC2Config service to process requests and configure instances.

Unless you have a specific reason for using the EC2Config service or an earlier version of the SSM Agent to process Systems Manager requests, we recommend that you download and install the latest version of the SSM Agent to each of your Amazon EC2 instances or managed instances (servers and VMs in a hybrid environment).

Note

The SSM Agent download and installation process for managed instances is different than Amazon EC2 instances. For more information, see Install the SSM Agent on Servers and VMs in Your Windows Hybrid Environment.

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

Installing SSM Agent

If your instance is a Windows Server 2003-2012 R2 instance created before November 2016, then EC2Config processes Systems Manager requests on your instance. We recommend that you upgrade your existing instances to use the latest version of EC2Config. By upgrading, you install SSM Agent side-by-side with EC2Config. This version of SSM Agent is compatible with your instances created from earlier Windows AMIs and enables you to use SSM features published after November 2016. You can remotely update EC2Config and install SSM Agent on one or more instances by using Run Command. For more information, see Executing Commands from the EC2 Console.

Alternatively, you can manually download and install the latest version of SSM Agent using the following procedure.

To manually download and install the latest version of SSM Agent

  1. Login to your instance.

  2. Download the latest version of the SSM Agent to your instance.

    https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows_amd64/AmazonSSMAgentSetup.exe.

    This URL lets you download the SSM agent from any AWS region. If you want to download the agent from a specific region, use a region-specific URL instead:

    https://amazon-ssm-region.s3.amazonaws.com/latest/windows_amd64/AmazonSSMAgentSetup.exe

  3. Start or restart the SSM agent (AmazonSSMAgent.exe) using the Windows Services control panel or by sending the following command in PowerShell:

    Copy
    Restart-Service AmazonSSMAgent

SSM Agent Logs

On Windows, SSM Agent stores log files in the following locations.

  • %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log

  • %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

Configuring SSM Agent to Use a Proxy

For information about configuring EC2Config to use a proxy, see Configure Proxy Settings for the EC2Config Service.

To configure SSM Agent to use a proxy

  1. Using Remote Desktop or Windows PowerShell, connect to the instance that you would like to configure to use a proxy. For Windows Server 2016 instances that use the Nano installation option (Nano Server), you must connect using PowerShell. For more information, see Connect to a Windows Server 2016 Nano Server Instance.

  2. If you connected using Remote Desktop, then launch PowerShell as an administrator.

  3. Run the following command block in PowerShell:

    Copy
    $serviceKey = "HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent" $keyInfo = (Get-Item -Path $serviceKey).GetValue("Environment") $proxyVariables = @("http_proxy=hostname:port", "no_proxy=169.254.169.254") If($keyInfo -eq $null) { New-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables -PropertyType MultiString -Force } else { Set-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables } Restart-Service AmazonSSMAgent

To reset the SSM agent proxy configuration

  1. Using Remote Desktop or Windows PowerShell, connect to the instance that you would like to configure.

  2. If you connected using Remote Desktop, then launch PowerShell as an administrator.

  3. Run the following command block in PowerShell:

    Copy
    Remove-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent -Name Environment Restart-Service AmazonSSMAgent

Installing SSM Agent on Linux

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.

Note

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

Install SSM Agent on EC2 Instances at Launch

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 the URL below with one of the following region-specific URLs. You must specify a region where Systems Manager is available.

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

Amazon Linux, RHEL, and CentOS 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

Amazon Linux, RHEL, and CentOS 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

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

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 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 Commands Using Systems Manager Run Command.

Manually Install the SSM Agent on EC2 Instances

Use one of the following scripts to install the 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, replace the URL below with one of the following region-specific URLs. You must specify a region where Systems Manager is available.

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

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.

    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 the 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 the 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 the 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 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.

    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 the 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 the 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 the 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 the 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 the 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

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 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_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
    env no_proxy=169.254.169.254
  5. Save your changes and close the editor.

  6. Stop and restart the 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 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 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 the 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

SSM Agent Logs

The SSM agent logs information in the following files. The information in these files can help you troubleshoot problems.

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

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

On Linux, 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 the SSM Agent on Linux

Use the following commands to uninstall the 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