Skip to content ↓ | Skip to navigation ↓

Last year, Amazon Web Services announced new capabilities in the AWS Systems Manager Session Manager. Users are now capable of tunneling SSH (Secure Shell) and SCP (Secure Copy) connections directly from a local client without the need for the AWS management console.

For years, users have relied on firewalls and bastion hosts in order to securely access cloud assets, but these options have security and management overhead tradeoffs. The Session Manager allows for secure, audited console access to cloud resources without the need for additional ingress points.

The addition of secure copy (SCP) capability removes one of the obstacles encountered by users adopting the AWS Session Manager. Cloud asset console access was provided within the AWS management console, but until now, there was no simple way to move files onto the remote systems. In many scenarios, development or administration of a live system may require copying patches or other data onto your live instances, and now Session Manager allows this without the need for additional solutions such as firewalls, bastions or intermediate S3 usage.

How to Setup

In order to perform SCP and SSH operations from your local host to the remote cloud asset, you will need to perform the following setup steps:

  1. Install or Update Systems Manager Agent on your EC2 instance– Most importantly, these new capabilities require the newest SSM agents to be running on your cloud assets. If you were already running the Systems Manager agent, you must upgrade.
  2. Create IAM Instance Profile– You must grant IAM permissions to allow Systems Manager to perform actions on your systems.
  3. Update to the latest AWS CLI– An updated command line interface is required on your local host in order to use these new Session Manager features.
  4. Install the Session Manager Plugin– This plugin allows the AWS cli to launch Session Manager sessions with your local SSH client.
  5. Update local host SSH config– The tricky portion of this setup involves altering your local host SSH configuration in order to proxy commands through the AWS session manager for any aws ec2 instance-id.

For Linux:

You will typically find your SSH config file at ~/.ssh/config

Add the following to the SSH config file:

# SSH over Session Manager

host i-* mi-*

ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

For Windows:

The OpenSSH Client is available as an installable component in newer versions of Windows, see this link for further information on installation.

You will typically find your SSH config file at C:\Users\username\.ssh\config though the .ssh directory will not exist until ssh has been used.

Add the following to the SSH config file:

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

How to Use

Once these steps are complete, you will be ready to initiate SSH and SCP connections to your cloud assets directly from your local machine.

Obtain the instance-id of the cloud asset. This can be done via the AWS management console or with the AWS cli command “aws ec2 describe-instances,” and will have a format similar to “i-0ba3d05e2b6c0fb36”

SSH can be performed as normal using the instance-id as the hostname and many SSH command line switches can be used.

For example providing a key with the -i switch can be performed like so:

$ ssh -i dev.key ec2-user@i-0ba3d05e2b6c0fb36

Last login: Thu Jul 13 14:45:21 2019 from ::1

[ec2-user@ip-10-1-5-19 ~]$

SCP may now be used as well for copying files onto the remote system without the need for an intermediate step.

$ scp /Users/blayer/bugfix.tar.gz ec2-user@i-0ba3d05e2b6c0fb36:/dir/fix.tar.gz

bugfix.tar.gz                                                                                             100%   18KB 106.2KB/s   00:00


Best of all, these connections are secured by IAM access and generate cloudtrail events for logging and monitoring.

While immutable infrastructure is a desired goal for multiple reasons, many will find themselves with a need to access or alter systems running live. The AWS Systems Manager Session Manager allows this capability without the need for additional firewall ingress or bastion hosts.