Cloud Techies
Published in

Cloud Techies

AWS Systems Manager Session Manager implementation

Session Manager Overview


Generic SSM Design
Detailed Network Design

How Session Manager works

Main benefits


SSM agent installation

SSM agent should be installed in every Ec2 instances or on-premise machine with Administrative access.

Internet Access

SSM agent needs communication with the AWS API, this communication uses standard HTTPS ports. Because the agent always starts the communication, allow any inbound rules is not necessary.

System Manager IAM setup

SSM requires an instance profile role that should be associated with each EC2 instances. In addition, an IAM service role is necessary for hybrid environment.


a) Transferring files is not possible by default with AWS Session Manager.

b) For Windows, RDP is not supported (port forwarding can be used instead) and “Run As” capability is not available.

c) Session manager is compatible with on premise system but requires the advanced on-premises instance tier (payment required).

d) Session manager is not a native ssh service, most of the tools that can work with ssh are not supported.

IAM policy example for Session Manager

"Version": "2012-10-17",
"Statement": [
"Effect": "Allow",
"Action": [
"Resource": "arn:aws:ec2:*:*:instance/*",
"Condition": {
"StringEquals": {
"tag_value" ]
"Effect": "Allow",
"Action": [
"Resource": "*"
{ "Effect": "Allow", "Action": [ "ssm:TerminateSession" ], "Resource": [ "arn:aws:ssm:*:*:session/${aws:username}-*" ] }

You can set IAM EndUser and Administrator policies for Session Manager.

You can also restrict access to specific instances individually or restrict based on tags, terminate only their specific sessions, allow full access to all sessions.

Recommended settings

Enable “Run As” support for Linux instances.

By default, sessions are launched using the credentials of a system-generated ssm-user account that is created on a managed instance.

You can instead launch sessions using the credentials of an operating system account. You can do this either by tagging an IAM user or role or by specifying an OS user name in Session Manager preferences.

This setting allows start sessions using the credentials of a specified operation system user, instead of the default credential generated by the System Manager agent (ssm-user).

When this option is enabled, Session Manager checks for access as follows:

Run As support always prevents sessions from being started using an ssm-user account on an instance.

Managing Account permissions

When a version of SSM Agent that supports Session Manager starts on an instance, it creates a user account with root or administrator privileges called ssm-user.

If you want to prevent Session Manager users from running administrative commands on an instance, you can update its ssm-user permissions. You can also restore these permissions after they have been removed.

You can disable or enable the ssm-user account sudo permissions on Linux or Windows instances.

Configure Session Manager to use AWS KMS key encryption

Provides additional protection to the data transmitted between client machines and managed instances.

Configure Session Manager to create and send session history logs.

Logs can be stored on Simple Storage Service (Amazon S3) bucket and/or an Amazon CloudWatch Log group. The stored log data can be used for logging and auditing purposes or even to create security alerts.

Session Manager Settings

Session manager allows several integrations with security services on AWS, the most relevant ones are listed below:


Any action performed over the session manager API is logged in CloudTrail. API actions such as StartSession can easily generate security alerts by SNS or trigger another action on AWS as the result of sessions activity (lambda functions or SSM run command are good examples).

Simple storage Service

As optional feature, Session Manager can store sessions outputs on S3 for further auditing. This option also allows run lambda functions that can be triggered every time when a session output is stored on a specific bucket. Lambda can analyses session outputs and perform any required action.

CloudWatch logs

Another service than can store session output logs for Session Manager is CloudWatch. This option is especially useful to create security alerts based on undesired behavior. By taking advantage of filters and metrics, CloudWatch logs can react and generate alerts if any user try to executes forbidden commands or performs any restricted action on the ssh/powershell sessions.

You can create Session Manager preferences for your account in the selected AWS Region via AWS Cli. Session manager preferences can be created using a JSON file and running a SSM document SSM-SessionManagerRunShell. Check out the steps in below.

To do the same via console -

Linux way of setting permission in instance.

Use the Run Command “UpdateSSMAgent” or send-command SSM action to execute the document to update your SSM agents -

aws ssm send-command — instance-ids i-1234a i-1234b — document-name “AWS-UpdateSSMAgent”

How to use Session Manager

Session Manager user requirements


You need to federate using your SAML role of your application for the required account. This role should have necessary policies attached for starting session using ssm.

SSM Agent

Version or later must be installed on the target instances.

AWS CLI (Optional)

Required to use the AWS CLI to start sessions (instead of using AWS Manager console), version 1.16.12 or later of the CLI must be installed on the local machine (Instructions to install AWS CLI for all supported systems).

In addition, the Session Manager plugin must be installed to start or terminate session over the EC2 instances. The plugin can be installed on supported versions of Microsoft Windows, macOS, Linux, and Ubuntu Server.

Session Manager Plugin

Install Session Manager Plugin on Linux

64-bit:curl “” -o “session-manager-plugin.rpm”32-bit:curl “” -o “session-manager-plugin.rpm”

2. Run the install command:

sudo yum install -y session-manager-plugin.rpm

3. Verify that the installation was successful running session-manager-plugin command. If the installation was successful, the following message is returned:

The Session Manager plugin is installed successfully. Use the AWS CLI to start a session.

Install Session Manager Plugin on macOS

curl "" -o ""

2.Unzip the package:


3. Run the install command:

sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

Install Session Manager Plugin on Windows

2. Run the downloaded installer and follow the on-screen the instructions.

3. Leave the install location box blank to install the plugin to the default directory:


4. Verify that the installation was successful.

Starting a Session (Console)

Users with the access right to use System Manager can start session directly in the AWS Management Console:

2. Select the target instance to start the connection, all the instances managed by SSM should be listed.

3. Choose Start session.

4. If the connection is successful, a bash commands (Linux) or PowerShell commands (Windows) will be opened.

Starting a Session (AWS CLI)

To start a session using the AWS CLI, run the following command:

aws ssm start-session — target instance-id

Instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its Session Manager capability. For example: i-02573cafcfEXAMPLE.

NOTE: To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on your local machine.

Starting a Session (Port Forwarding)

Linux example:

aws ssm start-session --target Instance-id --document-name AWS-StartPortForwardingSession --parameters ‘{“portNumber”:[“3389”],”localPortNumber”:[“12345”]}’

Windows example:

aws ssm start-session --target Instance-id --document-name AWSS-tartPortForwardingSession --parameters ‘“portNumber”=[“3389”], “localPortNumber”=[“12345”]’

Instance-id represents of the ID of an instance configured for use with AWS Systems Manager. For example: i-08dbf6bb51edqew34.

PortNumber represents the remote port on the instance where traffic should be redirected to. For example: 3389 to use RDP over windows.

LocalPortNumber represents the local port on the client where traffic should be redirected to. For example: 56789. This port can be reached over the local instances by any service/tool.

2. To reach RDP you can run:

mstsc /v localhost:LocalPortNumber

After credentials verifications, the RPD session should be opened.

Starting a Session (SSH)


To start a session using SSH, your target instance must be configured to support SSH connections.

Run the following command to start a session using SSH:

ssh -i /path/my-key-pair.pem username@instance-id


When you start a session using SSH, you can copy local files to the target instance using the following command format.

scp -i /path/my-key-pair.pem /path/SampleFile.txt username@instance-id:~scp -i /path/my-key-pair.pem /path/SampleFile.txt ec2-user@instance-id:SampleFile.txt

SSH via ProxyCommand

On the local machine from which you want to connect to a managed instance using SSH, do the following:


# SSH over Session Manager 
host i-* mi-*
ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"


# SSH over Session Manager 
host i-* mi-*
ProxyCommand C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p"


If you want to do ssh to your EC2 instances, remember you are trying to reach a private subnet through internet. So if you want to use SSM in your local environment(cli/ssh), you need to open firewall between your local subnet and SSM DNS for your required region.


You can check ssm agent logs in below path in your instances.


You can check session manager plugin logs in below path in your local.


For debugging purposes, you can enable logging as below.

Useful commands for reference

cli to ec2:
aws ssm start-session — target i-09b77018836663333
aws ssm start-session — target i-006d98bcda883e569
cli to ec2 using ssm port forwarding:
aws ssm start-session — target i-09b77013336667733 — document-name AWS-StartPortForwardingSession — parameters ‘{“portNumber”:[“22”],”localPortNumber”:[“9008”]}’
aws ssm start-session — target i-006d98b23a88c2569 — document-name AWS-StartPortForwardingSession — parameters ‘{“portNumber”:[“3389”],”localPortNumber”:[“9009”]}’
cli to rds using ssm port forwarding:
<Not Supported>
ssh to ec2 without keypair:
ssh ec2-user@i-09b770132336667733
ssh to ec2 with keypair:
ssh -i key ec2-user@i-09b77238836667733
ssh to ec2 using local port forwarding:
ssh -nNT -L 9000:localhost:80 ec2-user@i-09b77032836667733
ssh to rds via ec2 using local port forwarding:
ssh -nNT -L 9011:<db-host>:3306 ec2-user@i-09b770182116667733

User authentication

Technical Workflow

End to End automation

This approach will provide end to end automation to install System Manager agent in Linux EC2 and attach instance profile to both Windows and Linux machines using AWS Lambda.




Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Arun Kumar

Cloud Architect | AWS, GCP, Azure, Python, Kubernetes, Terraform, Ansible