Configuring the SSM Agent

The Amazon EC2 Simple Systems Manager (SSM) agent processes Run Command requests and configures the instances that are 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.

Contents

Install the SSM Agent 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:

In these scripts, replace <region> with one of the SSM regions. To avoid cross-region data transfer costs for the download, specify the region of your EC2 instance.

SSM Regions

Location	Region
US East (N. Virginia)	us-east-1
US West (Oregon)	us-west-2
US West (N. California)	us-west-1
EU (Ireland)	eu-west-1
EU (Frankfurt)	eu-central-1
Asia Pacific (Singapore)	ap-southeast-1
Asia Pacific (Tokyo)	ap-northeast-1
Asia Pacific (Sydney)	ap-southeast-2
South America (Sao Paulo)	sa-east-1

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

Ubuntu Server 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

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 with SSM Run Command.

Manually Install the SSM Agent

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 one of the SSM regions.

SSM Regions

Location	Region
US East (N. Virginia)	us-east-1
US West (Oregon)	us-west-2
US West (N. California)	us-west-1
EU (Ireland)	eu-west-1
EU (Frankfurt)	eu-central-1
Asia Pacific (Singapore)	ap-southeast-1
Asia Pacific (Tokyo)	ap-northeast-1
Asia Pacific (Sydney)	ap-southeast-2
South America (Sao Paulo)	sa-east-1

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 Run Command.

To install the SSM agent on Amazon Linux

Create a temporary directory on the instance.
```
mkdir /tmp/ssm
```
Use one of the following commands to download the SSM installer to the temporary directory. Replace <region> with one of the SSM regions. 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
```

Run the SSM installer.

sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm

Run the following command to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."
```
status amazon-ssm-agent
```
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.
```
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 Run Command.

To install the SSM agent on Ubuntu

Create a temporary directory on the instance.
```
mkdir /tmp/ssm
```
Use one of the following commands to download the SSM installer to the temporary directory. Replace <region> with one of the SSM regions. 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
```

Run the SSM installer.

sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb

Run the following command to determine if the SSM agent is running. The command should return "amazon-ssm-agent is running."
```
status amazon-ssm-agent
```
Execute the following commands if the previous command returned, "amazon-ssm-agent is stopped."
1. Start the service.
```
sudo start amazon-ssm-agent
```
2. Check the status of the agent.
```
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 Run Command.

To install the SSM agent on Red Hat Enterprise Linux

Create a temporary directory on the instance.
```
mkdir /tmp/ssm
```
Use one of the following commands to download the SSM installer to the temporary directory. Replace <region> with one of the SSM regions. 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
```

Run the SSM installer.

sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm

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
```
status amazon-ssm-agent
```
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
```
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 Run Command.

To install the SSM agent on CentOS

Create a temporary directory on the instance.
```
mkdir /tmp/ssm
```
Use one of the following commands to download the SSM installer to the temporary directory. Replace <region> with one of the SSM regions. 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
```

Run the SSM installer.

sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm

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
```
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
```
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)

Connect to the instance where you installed the SSM agent.
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
Add the http_proxy setting to the file in the following format:
```
env http_proxy=http://hostname:port
```
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
```
Save your changes and close the editor.
Restart the SSM agent using the following command:
```
/sbin/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 /opt/amazon/ssm/
exec ./amazon-ssm-agent

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

Connect to the instance where you installed the SSM agent.
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
Add the http_proxy setting to the file in the following format:
```
Environment="HTTP_PROXY=http://hostname:port"
```
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"
```
Save your changes and close the editor.

Restart the SSM agent using the following commands:

systemctl stop amazon-ssm-agent
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=/opt/amazon/ssm/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

Document Conventions

« Previous Next »