Configuring SSM Agent on an Amazon Lightsail Instance
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.
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.- 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.
- In the navigation pane, expand Instances & Nodes and choose Hybrid Activations.
- 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)
- Activation description:
- 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.
- Log in to the Lightsail instance as
ec2-user
. - Update SSM Agent to the latest available version.
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 versionsudo yum update-to -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm
2.3.672.0
.
For further information about the installation options of SSM Agent and the used RPM package, refer to the AWS documentation. - Stop SSM agent and clear the previously saved SSM registration (if existed).
Then, register the Lightsail instance with the Systems Manager service.sudo stop amazon-ssm-agent sudo amazon-ssm-agent -register -clear
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
).
In the output of the above command, you find your Instance ID.sudo amazon-ssm-agent -register -y \ -id '<Activation ID>' -code '<Activation Code>' -region '<AWS Region>'
Instance ID is a string that for servers outside of Amazon EC2 starts with the prefixmi-
, for example,mi-123456789aabbccdd
. - Start SSM Agent.
sudo start amazon-ssm-agent
- You can find the SSM Agent logs in the
/var/log/amazon/ssm
directory.
- You can find the SSM Agent logs in the
- Log in to the Lightsail instance as
- 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 isOnline
.
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
, andid
), execute from your PC/system the following AWS CLI command:
In the output of the above command, you find your Command ID.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;'
- 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
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 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 port8080
, execute the following AWS CLI command to forward the local port4444
on your PC/system to the port8080
on the managed instance:
In the output of the above command, you find your Session ID.aws ssm start-session --target '<Instance ID>' --region '<AWS Region>' \ --document-name AWS-StartPortForwardingSession \ --parameters '{"portNumber": ["8080"], "localPortNumber": ["4444"]}'
- Test the connectivity.
For example, on your PC/system, open in a web browser the URLhttp://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.