Package: aws-ssm-tools
aws-ssm-tools - AWS System Manager ToolsHelper tools for AWS Systems Manager:ec2-session,ec2-sshandssm-tunnel,
and for ECS Docker Exec:ecs-sessionScripts includedec2-session(formerlyssm-session)Wrapper aroundaws ssm start-sessionthat can open
 SSM Session to an instance specified byNameorIP Address.It doesn't need user credentials or evensshdrunning on the instance.Check outSSM Sessions the easy
wayfor an example use.Works with any Linux or Windows EC2 instance registered in SSM.ecs-sessionWrapper aroundaws ecs execute-commandthat can run a command
or open an interactive session to an Exec-enabled ECS container
specified by the service, name, IP address, etc.It doesn't need user credentials orsshdrunning on the container,
however the containers must be configured to allow this access.Check outInteractive shell in ECS Containersfor an example use.ec2-ssh(formerlyssm-ssh)Open an SSH connection to the remote server throughSystems Managerwithout the need for open firewall or direct internet access. SSH can
then be used to forward ports, copy files, etc.Unlikessm-tunnelit doesn't create a full VPN link, however it's in
some aspects more versatile as it can be used withrsync,scp,sftp, etc.It works with any client that can run SSH (including Mac OS-X) and
doesn't require a special agent on the instance, other than the standard
AWS SSM agent.Also supports pushing your SSH key to the instance with--send-key(akaEC2 Instance Connect, although that's an odd name for this function).ssm-tunnelOpenIP tunnelto the SSM instance and to enablenetwork accessto the instance VPC. This requiresssm-tunnel-agentinstalled on the instance.Works withAmazon Linux 2instances and probably other recent Linux
EC2 instances. RequiresLinuxon the client side - if you are on Mac
or Windows you can install a Linux VM in aVirtualBox.Requiresssm-tunnel-agentinstalled on the instance - see below for
instructions.UsageList instancesavailable for connection~ $ ec2-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.33If you're like me and have access to many different AWS accounts you
can select the right one with--profileand / or change the--region:~ $ ec2-session --profile aws-sandpit --region us-west-2 --list
i-0beb42b1e6b60ac10   uswest2.aws.nz     uswest2      172.31.0.92Alternatively use the standard AWSenvironment variables:~ $ export AWS_DEFAULT_PROFILE=aws-sandpit
~ $ export AWS_DEFAULT_REGION=us-west-2
~ $ ec2-session --list
i-0beb42b1e6b60ac10   uswest2.aws.nz     uswest2      172.31.0.92Open SSM sessionto an instance:This opens an interactive shell session over SSM without the need for
a password or SSH key. Note that by default the login user isssm-user.
You can specify most a different user with e.g.--user ec2-useror
even--user root.~ $ ec2-session -v test1 --user ec2-user
Starting session with SessionId: botocore-session-0d381a3ef740153ac
[ec2-user@ip-192-168-45-158] ~ $ hostname
test1.aws.nz

[ec2-user@ip-192-168-45-158] ~ $ id
uid=1000(ec2-user) gid=1000(ec2-user) groups=1000(ec2-user),...

[ec2-user@ip-192-168-45-158] ~ $ ^D
Exiting session with sessionId: botocore-session-0d381a3ef740153ac.
~ $You can specify other SSM documents to run with--document-name AWS-...to customise your session. Refer to AWS docs for details.Open SSH sessionover SSM withport forwarding.Theec2-sshtool provides a connection and authentication mechanism
for running SSH over Systems Manager.The target instancedoes not needa public IP address, it also doesnotneed an open SSH port in the Security Group. All it needs is to be
registered in the Systems Manager.Allsshoptions are supported, go wild. In this example we will
forward port 3306 to our MySQL RDS database using the standard-L 3306:mysql-rds.aws.nz:3306SSH port forwarding method.~ $ ec2-ssh ec2-user@test1 -L 3306:mysql-rds.aws.nz:3306 -i ~/.ssh/aws-nz.pem
[ec2-ssh] INFO: Resolved instance name 'test1' to 'i-07c189021bc56e042'
[ec2-ssh] INFO: Running: ssh -o ProxyCommand='aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p' i-07c189021bc56e042 -l ec2-user -L 3306:mysql-rds.aws.nz:3306 -i ~/.ssh/aws-nz.pem
OpenSSH_7.6p1 Ubuntu-4ubuntu0.3, OpenSSL 1.0.2n  7 Dec 2017
...
Last login: Sun Apr 12 20:05:09 2020 from localhost

   __|  __|_  )
   _|  (     /   Amazon Linux 2 AMI
  ___|\___|___|

[ec2-user@ip-192-168-45-158] ~ $From another terminal we can now connect to the MySQL RDS. Since the
port 3306 is forwarded fromlocalhostthrough the tunnel we will
instructmysqlclient to connect to127.0.0.1(localhost).~ $ mysql -h 127.0.0.1 -u {RdsMasterUser} -p
Enter password: {RdsMasterPassword}
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Server version: 5.6.10 MySQL Community Server (GPL)

MySQL [(none)]> show processlist;
+-----+------------+-----------------------+
| Id  | User       | Host                  |
+-----+------------+-----------------------+
|  52 | rdsadmin   | localhost             |
| 289 | masteruser | 192.168.45.158:52182  | <<< Connection from test1 IP
+-----+------------+-----------------------+
2 rows in set (0.04 sec)Usersyncwithec2-sshto copy files to/from EC2 instance.Since in the end we run a standardsshclient we can use it withrsyncto copy files to/from the
EC2 instance.~ $ rsync -e ec2-ssh -Prv ec2-user@test1:some-file.tar.gz .
some-file.tar.gz
     31,337,841 100%  889.58kB/s    0:00:34 (xfr#1, to-chk=0/1)
sent 43 bytes  received 31,345,607 bytes  814,172.73 bytes/sec
total size is 31,337,841  speedup is 1.00We can also select a different AWS profile and/or region:~ $ rsync -e "ec2-ssh --profile aws-sandpit --region us-west-2" -Prv ...Alternatively set the profile and region through standard AWSenvironment variablesAWS_DEFAULT_PROFILEandAWS_DEFAULT_REGION.`Create IP tunneland SSH to another instance in the VPC through it.We will use--route 192.168.44.0/23that 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/sLeave it running and from another shellsshto one of the instances listed
with--listabove. For example totest1that'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 IP192.168.44.95that belongs to thetunnel-testinstance - our connections willappearas if they come from this instance.
Obviously theSecurity Groupsof your other instances must allow SSH
access from the IP or SG of your tunnelling instance.All these tools support--helpand 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 even more.ec2-sshonly supports the long options to prevent conflict withssh's
own short options that are being passed through.Standard AWS environment variables likeAWS_DEFAULT_PROFILE,AWS_DEFAULT_REGION, etc, are also supported.InstallationAll the tools useAWS CLIto openSSM Sessionand then use that
session to run commands on the target instance. The target instancesmust be
registered in SSM, which means they need:connectivity to SSM endpoint, e.g. through public IP, NAT Gateway, or
SSM VPC endpoint.EC2 instance IAM Rolewith permissions to connect to Systems Manager.Follow the detailed instructions atUsing SSM Session Manager for
interactive instance accessfor more informations.InstallAWS CLIandsession-manager-pluginMake sure you've gotawsandsession-manager-plugininstalled locally
on your laptop.~ $ aws --version
aws-cli/1.18.31 Python/3.6.9 Linux/5.3.0-42-generic botocore/1.15.31

~ $ session-manager-plugin --version
1.1.56.0FollowAWS CLI installation
guideandsession-manager-plugin
installation guideto install them if needed.Note thatec2-sshneedssession-manager-pluginversion1.1.23or
newer. Upgrade if your version is older.Register your instances with Systems ManagerAmazon Linux 2instances already have theamazon-ssm-agentinstalled and
running. All they need to register withSystems ManagerisAmazonEC2RoleforSSMmanaged role in theirIAM Instance Roleand network
access tossm.{region}.amazonaws.comeither directly or through ahttps proxy.Check out thedetailed instructionsfor more info.Install SSM-Tools(finally! :)The easiest way is to install the ssm-tools fromPyPIrepository:sudo pip3 install aws-ssm-toolsNOTE:SSM Tools requirePython 3.6 or newer. Only thessm-tunnel-agentrequiresPython 2.7 or neweras that's what's available by default
onAmazon Linux 2instances.Standalonessm-tunnel-agentinstallationRefer toREADME-agent.mdforssm-tunnel-agentinstallation details.Alternatively it's also bundled with this package, you can take it from here and
copy to/usr/local/bin/ssm-tunnel-agenton the instance. Make it executable
and it should just work.Other AWS UtilitiesCheck outAWS Utilsrepository for more useful AWS tools.Author and LicenseAll these scripts were written byMichael Ludvigand are released underApache License 2.0.