Skip to content

AWS Systems Manager Session Manager

Jump to bottom
Richard T. Miles edited this page Jun 21, 2024 · 1 revision

Overview

Benefits of using Session Manager: https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html

Setting up an Instance with Session Manager

Two Key Points

  1. An IAM role must be associated with an EC2 instance to give it permissions to access the SSM APIs. Ensure the IAM role that will be assigned to the instance has the AmazonSSMManagedInstanceCore managed policy attached (or an inline policy with the same permissions set)
  2. The Amazon SSM Agent is installed and running on the instance (Amazon Linux AMIs have it installed by default, other AMIs will need to have the agent installed or via UserData/cfn-init). The role must be attached before the agent starts, otherwise the agent will need to be restarted before anyone can connect.

Connecting to an Instance

The Amazon SSM Agent must be running and an IAM role properly configured before you can connect. There are a couple of ways to connect: 1) with CLI access and 2) Port Forwarding

CLI access

This method gives you CLI access into the machine. This will be sh, bash, etc for Linux instances, and PowerShell for Windows instances.

Connect via Web Browser

  1. Go to the AWS Systems Manager service and select Session Manager in the side bar.
  2. Ensure you’re in the correct region.
  3. Click “Start session” and choose your instance

Connect via Local Terminal (AWS CLI)

Prerequisites

  1. Have a recent version of the AWS CLI installed and configured
  2. Install the Session Manager Plugin (works on both macOS and Windows) Once the prerequisites have been met, you can connect to your instance by running the following command in the terminal (use --profile with your CLI profile name, if applicable):
aws ssm start-session --target <ec2 instance id>

Connect via SSH (AWS CLI + SSH)

Prerequisites

  1. Install the AWS CLI and Session Manager Plugin
  2. Configure your local SSH client to use the AWS CLI as a proxy to the EC2 instance. Only clients that support proxy with SSH will work. Make sure to add the ProxyCommand section to your ~/.ssh/config file as outlined in the AWS docs.
  3. (Optional) If you have an AWS CLI profile setup, you will need to set an environment variable (AWS_PROFILE) with the CLI profile name you want to use for the proxy SSH command
export AWS_PROFILE=<myprofile>
ssh ec2-user@<ec2-instance-id>

You can optionally set the environment variable and run the ssh command in one line:

AWS_PROFILE=<myprofile> ssh ec2-user@<ec2-instance-id>

Port Forwarding

You can connect to any TCP port on your remote instance by forwarding it through a tunnel. There are two ways to port forward: 1) Through the SSM agent (recommended) and 2) through SSH tunneling.

Forwarding Ports with SSM

Choose an unused port on your machine to use for the port forward. Generally it's best to use an ephemeral port between 1025 and 65535. Personally I usually choose a port somewhere in the 8000-9999 range. Once you have decided on a port, you'll also need to know the port number for the service you are trying to reach (e.g., 3389 for RDP, 80/443 for HTTP/HTTPS, etc.). Once ports have been decided, obtain the EC2 instance ID (either in the console or via the CLI). We can then run the AWS CLI command to forward the port (don't forget to add --profile <your profile name> if you configured the AWS CLI with a profile):

aws ssm start-session --target <instance-id> --document-name AWS-StartPortForwardingSession --parameters "localPortNumber=<chosen local port number to bind the connection>,portNumber=<remote port on the instance>"

If the command is successful, you will see output similar to the following in your terminal (in my example, I used local port 8000 and remote port 3389 to forward RDP from the instance to my local machine):

$ aws ssm start-session --target i-01234567890abcdef --document-name AWS-StartPortForwardingSession --parameters "localPortNumber=8000,portNumber=3389"

Starting session with SessionId: <session id name>
Port 8000 opened for sessionId <session id name>.

Congratulations! You've just forwarded a port from your remote EC2 instance to your local machine! As long as you keep the terminal window open with the command running, the port will continue to be forwarded. You can access the port by accessing localhost:<local port number>. In the example above, you could use an RDP client to connect to localhost:8000 to access RDP on the remote instance.

Forwarding Ports with SSH

With this method, you can use native SSH commands to forward a remote port to your local machine. This method works with direct SSH access to a machine, as well as using the Proxy SSM + SSH method above.

You'll need to follow nearly the same beginning instructions as the above method (finding local and remote ports). You'll also need to ensure your target machine has an OpenSSH server installed and running. Once you have those items ready, you can forward the port using the following command:

ssh ec2-user@<host or instance id> -L <local port bind>:<remote ip>:<remote port>

This will log you in to SSH like normal, but the remote port will now be bound to the local port you specified. If you don't want to drop into a shell, include the -N flag on the ssh command.

Other Items

Clone this wiki locally