Configuring SSM Agent on an Amazon Lightsail Instance

October 3, 2019

Figure showing a Lightsail instance with running SSM Agent that connects to the Systems Manager service.

AWS Systems Manager Agent (SSM Agent) is lightweight Amazon software that can be installed and configured on an Amazon EC2 instance, an on-premises server, or a virtual machine. SSM Agent securely communicates with the Systems Manager service and gives this AWS service visibility and control of the managed servers.

Systems Manager has different capabilities that allow you, for example, to run a command (Unix shell or PowerShell) on a managed instance, open an interactive session to an instance, or forward a local network port on a client machine to any port inside a managed instance.

This blog post describes how to configure SSM Agent on a Lightsail instance running the Amazon Machine Image (AMI) Amazon Linux 2018.03.0. Similarly, you can configure SSM Agent on other systems. For detailed information and installation instructions that apply to other use cases, see Setting Up AWS Systems Manager (for Amazon EC2) and Setting Up AWS Systems Manager for Hybrid Environments.

How to Configure SSM Agent on a Lightsail Instance

Using the Systems Manager service and SSM Agent running on your server, you can keep on your server all inbound network ports closed while still can be able, for example, to remotely run shell commands on this server, open an interactive session and even start a port forwarding session to the server. These capabilities make Systems Manager applicable to a wide range of use cases.

Flow diagram showing a Lightsail instance with installed SSM Agent. Internet users and even administrators can not connect to the instance directly because all inbound network ports are closed. An administrator can use the AWS CLI and Management console to execute commands on the instance or create a port forwarding session.

To configure SSM Agent on a Lightsail instance running Amazon Linux 2018.03.0, perform the following steps:

Create a managed-instance activation for a hybrid environment.
To register any server outside of Amazon EC2, you must create a Systems Manager activation. Thus, that applies not only to on-premises servers but also to Lightsail instances.
1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/home and switch to the same AWS region where you are running your Lightsail instance.
2. In the navigation pane, expand Instances & Nodes and choose Hybrid Activations.
3. Click Create activation and use the following parameters for the new hybrid activation:
  - Activation description: Amazon Lightsail instances
  - Instance limit: 5
    Specify the total number of servers that you want to register as a part of this activation.
    - In this procedure, you register only one Lightsail instance, but you may want to do additional tests or register more instances later.
  - IAM role: Choose Use the default role created by the system (AmazonEC2RunCommandRoleForManagedInstances)
4. Click Create activation on the bottom of the page.
  Systems Manager returns the Activation Code and Activation ID to the console. Store them securely to use in the following steps.
Configure SSM Agent on your Lightsail instance.
1. Log in to the Lightsail instance as ec2-user.
2. Update SSM Agent to the latest available version.
```
sudo yum update-to -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm
```
  SSM Agent is pre-installed, by default, on Amazon Linux. The update is required to make available new capabilities. For example, the port forwarding capability (plugin) is first available only in version 2.3.672.0.
  For further information about the installation options of SSM Agent and the used RPM package, refer to the AWS documentation.
3. Stop SSM agent and clear the previously saved SSM registration (if existed).
```
sudo stop amazon-ssm-agent
sudo amazon-ssm-agent -register -clear
```
  Then, register the Lightsail instance with the Systems Manager service.
  In the following command, replace <Activation ID> and <Activation Code> with your values from the previous step. Also, replace <AWS Region> with the AWS region where you created the Systems Manager activation (for example, us-east-1).
```
sudo amazon-ssm-agent -register -y \
-id '<Activation ID>' -code '<Activation Code>' -region '<AWS Region>'
```
  In the output of the above command, you find your Instance ID.
  Instance ID is a string that for servers outside of Amazon EC2 starts with the prefix mi-, for example, mi-123456789aabbccdd.
4. Start SSM Agent.
```
sudo start amazon-ssm-agent
```
  - You can find the SSM Agent logs in the /var/log/amazon/ssm directory.
In the navigation pane of the AWS Systems Manager console, expand Instances & Nodes and choose Managed Instances.
The SSM agent setup on your Lightsail instance is successful if the ping status next to your Instance ID is Online.

Now you can perform various tasks on your Lightsail instance using different Systems Manager capabilities. For example, perform the following tasks:

Run shell commands on your Lightsail instance
Start a port forwarding session to your Lightsail instance
Open an interactive shell session to your Lightsail instance and run individual commands (running SSH daemon is not needed)

How to Run Shell Commands on a Managed Instance

In the following commands, replace <Instance ID> with your Instance ID (for example, mi-123456789aabbccdd), and <AWS Region> with the AWS region where your managed instance is registered (for example, us-east-1).

To send one or several shell commands from a client machine to a Systems Manager managed instance, perform the following steps:

Make sure that your PC/system is set up as described in Appendix A, How to Set Up a Client Machine for Communicating with Systems Manager.
Send one or a sequence of shell commands.
For example, to run on a managed instance three shell commands (hostname, uptime, and id), execute from your PC/system the following AWS CLI command:
```
aws ssm send-command --instance-ids '<Instance ID>' --region '<AWS Region>' \
--document-name AWS-RunShellScript --comment 'Test run of shell commands' \
--parameters commands='hostname; uptime; id;' 
```
In the output of the above command, you find your Command ID.

Use your Command ID to fetch the output of the executed shell commands.

aws ssm list-command-invocations --command-id '<Command ID>' \
--instance-id '<Instance ID>' --region '<AWS Region>' \
--details --query CommandInvocations[].CommandPlugins[].Output --output text

How to Start a Port Forwarding Session to a Managed Instance

To start a port forwarding session from a client machine to a Systems Manager managed instance, perform the following steps:

Make sure that your PC/system is set up as described in Appendix A, How to Set Up a Client Machine for Communicating with Systems Manager.
Enable the advanced-instances tier for the AWS account and AWS region where you registered your managed instance.
- Additional charges apply to advanced instances.
- If you enabled the advanced-instances tier and want to change back to the standard-instances tier, you must contact AWS Support.
On your PC/system, start a new port forwarding session.
For example, assuming that on your managed instance you are running a private HTTP web server that listens to port 8080, execute the following AWS CLI command to forward the local port 4444 on your PC/system to the port 8080 on the managed instance:
```
aws ssm start-session --target '<Instance ID>' --region '<AWS Region>' \
--document-name AWS-StartPortForwardingSession \
--parameters '{"portNumber": ["8080"], "localPortNumber": ["4444"]}'
```
In the output of the above command, you find your Session ID.
Test the connectivity.
For example, on your PC/system, open in a web browser the URL http://localhost:4444 to connect to the private web server running on your managed instance.
Alternatively, query the URL from the console:
```
curl http://localhost:4444
```

To terminate a session, you can use the AWS Systems Manager console or execute on your PC/system the following AWS CLI command:

aws ssm terminate-session --session-id '<Session ID>' --region '<AWS Region>'

In some cases, you might also need to kill the process of the Session Manager Plugin for the AWS CLI on the client machine.

Appendix A, How to Set Up a Client Machine for Communicating with Systems Manager

A client machine can be your PC or a remote system (server). From this machine, you can connect to the Systems Manager service and execute managements tasks or open port forwarding sessions to your managed instances.

To set up the client machine, perform the following steps:

Install on your PC/system the latest version of the AWS CLI.
Install on your PC/system the Session Manager plugin for the AWS CLI.
The Session Manager plugin is required to use the AWS CLI to start and terminate sessions that connect you to your managed instances.

Configure the AWS CLI.
For the IAM user or role used by the AWS CLI, add, for example, the following permissions that are needed to start/stop a port forwarding session or run shell commands and fetch the output of these commands:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "ssm:SendCommand", "ssm:StartSession"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:ssm:*:*:managed-instance/mi-*",
        "arn:aws:ssm:*::document/AWS-RunShellScript",
        "arn:aws:ssm:*::document/AWS-StartPortForwardingSession"
      ]
    },
    {
      "Action": "ssm:ListCommandInvocations",
      "Effect": "Allow",
      "Resource": "arn:aws:ssm:*:*:*"
    },
    {
      "Action": "ssm:TerminateSession",
      "Effect": "Allow",
      "Resource": "arn:aws:ssm:*:*:session/*"
    }
  ]
}

Depending on the tasks that you plan to perform using Sessions Manager, you may want to add additional permission or adjust the above permissions to follow the standard security advice of granting the least privilege.

Lightsail, Systems Manager

Configuring SSM Agent on an Amazon Lightsail Instance

How to Configure SSM Agent on a Lightsail Instance

How to Run Shell Commands on a Managed Instance

How to Start a Port Forwarding Session to a Managed Instance

Appendix A, How to Set Up a Client Machine for Communicating with Systems Manager

Table of Contents