Metadata-Version: 2.1
Name: aws-ssm-tools
Version: 1.1.1
Summary: Tools for AWS Systems Manager: ssm-session ssm-copy ssm-tunnel
Home-page: https://github.com/mludvig/aws-ssm-tools
Author: Michael Ludvig
Author-email: mludvig@logix.net.nz
License: Apache License 2.0
Project-URL: Bug Tracker, https://github.com/mludvig/aws-ssm-tools/issues
Project-URL: Documentation, https://github.com/mludvig/aws-ssm-tools/blob/master/README.md
Project-URL: Source Code, https://github.com/mludvig/aws-ssm-tools
Keywords: aws ssm ssm-session ssm-copy ssm-tunnel
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Networking
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pexpect
Requires-Dist: botocore
Requires-Dist: boto3

# aws-ssm-tools - AWS System Manager Tools

[![CircleCI](https://circleci.com/gh/mludvig/aws-ssm-tools.svg?style=shield)](https://circleci.com/gh/mludvig/aws-ssm-tools)
[![PyPI](https://img.shields.io/pypi/v/aws-ssm-tools.svg)](https://pypi.org/project/aws-ssm-tools/)
[![Python Versions](https://img.shields.io/pypi/pyversions/aws-ssm-tools.svg)](https://pypi.org/project/aws-ssm-tools/)

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](https://aws.nz/projects/ssm-session/)* 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](README-agent.md)
  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.

## Usage

1. **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
    ```

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
    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-0d381a3ef740153ac.
    ~ $
    ```

4. **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 one of the instances listed
    with `--list` above. For example to `test1` that's got VPC IP `192.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 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.

## 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
and [session-manager-plugin
installation guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) 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](https://pypi.org/)* 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](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](https://github.com/mludvig/aws-utils)**
repository for more useful AWS tools.

## Author and License

All these scripts were written by [Michael Ludvig](https://aws.nz/)
and are released under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).


