Metadata-Version: 2.1
Name: ssh-aws
Version: 2.4.5
Summary: SSH into your EC2 instances.
Home-page: https://gitlab.com/franciscogd/awssh
Author: Francisco Duran
Author-email: franciscogd@gatech.edu
License: UNKNOWN
Download-URL: https://gitlab.com/franciscogd/awssh/archive/2.4.5.tar.gz
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: awscli (>=1.10.14)
Requires-Dist: boto3 (>=1.3.1)

awssh
----------------

SSH boto3 utility for AWS
```
➜  ~ awssh --profile dyna
Querying AWS for EC2 instances in region: default ...

     Name           Instance ID   Public IP       Private IP       Zone          Key Name
 0 - JumpHost-1     i-06755dff7   3.13.18.215     10.120.1.119     us-east-2a    project-100715
 1 - WinStack       i-088fbe001   None            10.120.1.40      us-east-2a    project-100715
 2 - JumpHost-2     i-00498e224   48.14.28.186    10.120.0.8       us-east-2a    project-101018
 3 - PCoIP          i-0b79c1a8f   None            10.120.1.46      us-east-2a    project-101018
 4 - Dyna-dyna      i-03ed2e9df   None            10.120.1.7       us-east-2a    project-101018
 5 - ECS Instance   i-01b2877c1   None            10.120.1.55      us-east-2a    project-101018
 6 - MySQL-PROD     i-01b2877c1   None            10.120.1.55      us-east-2a    project-100715
 7 - codeCommit     i-06755dff7   None            10.120.1.119     us-east-2a    project-100715

Enter server number: 7

ProxyJump configuration directive.
Connecting to PROD-Core-1 via PROD-Chef:

Trying with user "centos".
Command: ssh-add /Users/fduran/project-100715.pem; ssh -A -o ConnectTimeout=5 -J centos@3.13.18.215 centos@10.120.1.119
Identity added: /Users/fduran/project-100715.pem (/Users/fduran/project-100715.pem)

[centos@code-commit ~]$
```

Installation
----------------
First, install the aws-cli and boto3 libraries: 
```
pip install awscli --upgrade --user
pip install boto3
```
Next, set up credentials and default region:
```bash
aws configure
```
Finally, install the `awssh` utility:
```bash
pip install --user ssh-aws # or pip install ssh-aws
```

**Note**: The `awssh` utility is installed in `$HOME/Library/Python/2.7/bin` which may not be on PATH.
Consider adding this directory to PATH.

Version update
----------------
```bash
echo y | pip uninstall ssh-aws
pip install --no-cache --user ssh-aws
awssh --version
```


Requirements
----------------

- Python 2.7
- boto3
- aws-cli

Features
----------------

The `awssh` utility gives you a list of aws instances and preconfigures `ssh` with the proper key and user.
You can filter by instance name. If it matches only one instance you will be logged into it. If an instance 
without an external IP is selected, the utility attempts to find its jump server and ssh with the ProxyJump 
configuration directive (e.g. `ssh -A -J user@<jump.host> user@<target.host>`). Agent forwarding should be 
used with caution. `awssh` also allows local and remote port forwarding for ssh tunneling 
(e.g. `ssh -L 9000:imgur.com:80 user@<ip_address>`). 

Usage
-----

```
usage: awssh [-h] [--users USERS [USERS ...]] [--profile PROFILE]
                   [--region REGION] [-i KEY_PATH] [-c COMMAND]
                   [-r REMOTE_HOST] [-p REMOTE_PORT] [-l LOCAL_PORT]
                   [--keys KEYS] [--timeout TIMEOUT] [--console-output]
                   [--version] [-v]
                   [filter]

SSH into AWS instances. "awssh --profile prod-acc-2 --users fduran --region
us-east-2 instance-name". The default user list is centos, ubuntu, and
ec2-user. "awssh --profile prod-acc-2" will attempt ssh with default users.
Due to the nature of nargs, "awssh --users user1 user2 instance-name" will not
be parsed properly. Instead try "awssh instance-name --users user1 user2". If
available, JumpHost will be automatically selected when the instance has no
external IP.

positional arguments:
  filter                Optional instance name or key word as a filter. If
                        only one instance is found, it will connect to it
                        directly.

optional arguments:
  -h, --help            show this help message and exit
  --users USERS [USERS ...]
                        Users to try (centos, ubuntu, and ec2-user are
                        defaults).
  --profile PROFILE     Use a specific profile from your credentials file.
  --region REGION       AWS region (User default if none is provided).
  -i KEY_PATH, --key-path KEY_PATH
                        Specific key path, overrides, --keys
  -c COMMAND, --command COMMAND
                        Translates to ssh -t <COMMAND>
  -r REMOTE_HOST, --remote-host REMOTE_HOST
                        Open a tunnel. Equivalent to ssh -L <local-port
                        >:<remote-host>:<remote-port> <selected-aws-host>
  -p REMOTE_PORT, --remote-port REMOTE_PORT
                        Port to use on the remote host (default is 5432).
  -l LOCAL_PORT, --local-port LOCAL_PORT
                        Port to use on the local host. Get overwritten by
                        remote port if not defined.
  --keys KEYS           Directory of the private keys (~/.ssh by default).
  --timeout TIMEOUT     SSH connection timeout.
  --console-output, -co
                        Display the instance console out before logging in.
  --version             Returns awssh's version.
  -v                    Verbose, prints instance details.


  Examples:
    awssh
    awssh --profile prod-acc-2
    awssh --users fduran --profile prod-acc-2 --region us-east-2 -c top
    awssh --users user1 user2 --region us-east-2 --keys '~/.ssh' instance-name
    awssh instance-name --users user1 user2 -c 'df -h'

```


