Tools for AWS Systems Manager: ssm-session ssm-copy ssm-tunnel
Project description
aws-ssm-tools - AWS System Manager Tools
Helper tools for AWS Systems Manager.
Scripts included
-
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.
-
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 :)
-
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 systems.
Requires
ssm-tunnel-agent
installed on the instance - see below for instructions.
Usage
-
List instances available for connection
~ $ ssm-session --list i-07c189021bc56e042 test1.aws.nz test1 192.168.45.158 i-094df06d3633f3267 tunnel-test.aws.nz tunnel-test 192.168.44.95 i-02689d593e17f2b75 winbox.aws.nz winbox 192.168.45.5 13.11.22.33
-
Copy a file to an instance:
~ $ ssm-copy large-file test1: large-file - 1087kB, 27.6s, 39.4kB/s, [SHA1 OK]
-
Open SSM session to an instance:
~ $ ssm-session -v test1 Starting session with SessionId: botocore-session-1560983828-0d381153aca3ef740 sh-4.2$ hostname test1.aws.nz 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-1560983828-0d381153aca3ef740. ~ $
-
Create IP tunnel and SSH to another instance in the VPC through it.
We'll use
--route 192.168.44.0/23
that gives us access to the VPC CIDR.$ ssm-tunnel -v tunnel-test --route 192.168.44.0/23 [ssm-tunnel] INFO: Local IP: 100.64.160.100 / Remote IP: 100.64.160.101 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 an instance listed with
--list
above, for example totest1
that's got VPC IP192.168.45.158
:~ $ ssh ec2-user@192.168.45.158 Last login: Tue Jun 18 20:50:59 2019 from 100.64.142.232 ... [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 192.168.44.95 21:20 3.00s 0.02s 0.00s w -i [ec2-user@test1 ~]$ exit Connection to 192.168.45.158 closed. ~ $
Note the source IP
192.168.44.95
that belongs to thetunnel-test
instance - our connections will appear to 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.
Installation
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
1.1.17.0
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}.amazonaws.com
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 README-agent.md 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws_ssm_tools-0.9.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5130b230702558d100a6886a4930cd87f56970fa2b9774763662c4b6cc3a4b65 |
|
MD5 | db5002171663fe38f9b792428c145f39 |
|
BLAKE2b-256 | 412637c11a8fb88b5cc77b0b0dd85787d943611a7671ddea81e850d09d01f3c0 |