Skip to content
Handy tools for AWS Systems Manager - ssm-session, ssm-copy and ssm-tunnel
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Only pylint python scripts. Jul 16, 2019
ssm_tools Only pylint python scripts. Jul 16, 2019
.gitignore Bump up version to 0.9.4 Jun 26, 2019
.pylintrc Added and helper files Jun 19, 2019 Bump up version to 0.9.4 Jun 26, 2019 Updated version to 0.9.3 Jun 19, 2019
requirements.txt Separate package for the agent. Jun 19, 2019 Added ssm-tunnel-updown.dns-example Jul 15, 2019
ssm-copy Re-add output flush Jun 19, 2019
ssm-session Reorganised files Jun 19, 2019
ssm-tunnel-agent Renamed ssm-tunnel-client to ssm-tunnel-agent Jun 19, 2019
ssm-tunnel-updown.dns-example Updated version to 0.9.3 Jun 19, 2019

aws-ssm-tools - AWS System Manager Tools

CircleCI PyPI Python Versions

Helper tools for AWS Systems Manager: ssm-session, ssm-copy and ssm-tunnel.

Scripts included

  • ssm-session

    Wrapper around aws ssm start-session that can open  SSM Session to an instance specified by Name or IP Address.

    Check out SSM Sessions the easy way for an example use.

    Works with any Linux or Windows EC2 instance registered in SSM.

  • ssm-copy

    Copy files to/from EC2 instances over SSM Session without the need to have a direct SSH access.

    Works with Linux instances only, however no remote agent is required. All that is needed is a shell and standard linux tools like base64 (yes, we are transferring the files base64-encoded as SSM Sessions won't pass through binary data).

    Only copy to instance is implemented at the moment. Copy from is on my todo list :)

  • ssm-tunnel

    Open IP tunnel to the SSM instance and to enable network access to the instance VPC. This requires ssm-tunnel-agent installed on the instance.

    Works with Amazon Linux 2 instances and probably other recent Linux systems.

    Requires ssm-tunnel-agent installed on the instance - see below for instructions.


  1. List instances available for connection

    ~ $ ssm-session --list
    i-07c189021bc56e042       test1
    i-094df06d3633f3267 tunnel-test
    i-02689d593e17f2b75      winbox
  2. Copy a file to an instance:

    ~ $ ssm-copy large-file test1:
    large-file - 1087kB, 27.6s, 39.4kB/s, [SHA1 OK]
  3. Open SSM session to an instance:

    ~ $ ssm-session -v test1
    Starting session with SessionId: botocore-session-0d381a3ef740153ac
    sh-4.2$ hostname
    sh-4.2$ cd
    sh-4.2$ ls -l
    total 1088
    -rw-r--r-- 1 ssm-user ssm-user 1113504 Jun 20 02:07 large-file
    sh-4.2$ exit
    Exiting session with sessionId: botocore-session-0d381a3ef740153ac.
    ~ $
  4. Create IP tunnel and SSH to another instance in the VPC through it.

    We'll use --route that gives us access to the VPC CIDR.

    $ ssm-tunnel -v tunnel-test --route
    [ssm-tunnel] INFO: Local IP: / Remote IP:
    00:00:15 | In:  156.0 B @    5.2 B/s | Out:  509.0 B @   40.4 B/s

    Leave it running and from another shell ssh to one of the instances listed with --list above. For example to test1 that's got VPC IP

    ~ $ ssh ec2-user@
    Last login: Tue Jun 18 20:50:59 2019 from
    [ec2-user@test1 ~]$ w -i
     21:20:43 up  1:43,  1 user,  load average: 0.00, 0.00, 0.00
    USER     TTY      FROM             LOGIN@   IDLE   JCPU   PCPU WHAT
    ec2-user pts/0    21:20    3.00s  0.02s  0.00s w -i
    [ec2-user@test1 ~]$ exit
    Connection to closed.
    ~ $

    Note the source IP that belongs to the tunnel-test instance - our connections will appear as if they come from this instance. Obviously the Security Groups of your other instances must allow SSH access from the IP or SG of your tunnelling instance.

All the tools support --help and a set of common parameters:

--profile PROFILE, -p PROFILE
                    Configuration profile from ~/.aws/{credentials,config}
--region REGION, -g REGION
                    Set / override AWS region.
--verbose, -v       Increase log level
--debug, -d         Increase log level

They also support the standard AWS environment variables like AWS_DEFAULT_PROFILE, AWS_DEFAULT_REGION, etc.


All the tools use AWS CLI to open SSM Session and then use that session to run commands on the target instance. The target instances must be registered in SSM.

Install AWS CLI and session-manager-plugin

Make sure you've got aws and session-manager-plugin installed locally on your laptop.

~ $ aws --version
aws-cli/1.16.175 Python/3.6.8 Linux/4.15.0-51-generic botocore/1.12.165

~ $ session-manager-plugin --version

Follow AWS CLI installation guide and session-manager-plugin installation guide to install them if needed.

Register your instances with Systems Manager

Amazon Linux 2 instances already have the amazon-ssm-agent installed and running. All they need to register with Systems Manager is AmazonEC2RoleforSSM managed role in their IAM Instance Role and network access to ssm.{region} either directly or through a https proxy.

Install SSM-Tools (finally! :)

The easiest way is to install the ssm-tools from PyPI repository:

sudo pip3 install aws-ssm-tools

NOTE: SSM Tools require Python 3.6 or newer. Only the ssm-tunnel-agent requires Python 2.7 or newer as that's what's available by default on Amazon Linux 2 instances.

Standalone ssm-tunnel-agent installation

Refer to for ssm-tunnel-agent installation details.

Alternatively it's also bundled with this package, you can take it from here and copy to /usr/local/bin/ssm-tunnel-agent on the instance. Make it executable and it should just work.

Other AWS Utilities

Check out AWS Utils repository for more useful AWS tools.

Author and License

All these scripts were written by Michael Ludvig and are released under Apache License 2.0.

You can’t perform that action at this time.