ssh2ec2

A little helper script to simplify connecting to an EC2 instance via SSH.

Specify some tags and metadata to filter your instances, and you'll be connected to an instance in the matching set.

See the blog post for more details.

Usage Examples

Open an SSH connection to a random instance that matches the given filters:

ssh2ec2 --tag Name=nginx

ssh2ec2 --tag role=web --tag environment=production

ssh2ec2 --availability-zone us-east-1a --instance-type t2.micro

ssh2ec2 --tag role=web --ssh-user ubuntu

Pass commands to SSH for execution on the remote host:

ssh2ec2 --tag role=web uname -a

SSH arguments can be specified by including them in a quoted string at the end of the command, or explicitly specified with --ssh-args. The following commands are functionally identical:

ssh2ec2 --tag role=web "-i /path/to/key echo hello"
ssh2ec2 --tag role=web --ssh-args "-i /path/to/key" echo hello

Execute the same command on all instances matching the filters:

ssh2ec2 --all-matching-instances --tag role=web hostname

Installation and Configuration

pip install ssh2ec2

This script does not require any specific configuration. However, it does assume that your AWS credentials and default region are available in a config file or environment variables. See the AWS documentation for more details.

If you have multiple sets of credentials in your ~/.aws/credentials file you can select which one will be used with the --profile argument:

ssh2ec2 --profile profile_name ...

Multi-Factor Authentication devices are supported, but you must use the mfa_serial directive in your ~/.aws/config:

$ ssh2ec2 --profile prod --tag role=web
Enter MFA code:

Supported Filters