ssm-connect.sh

A small helper to quickly connect to an EC2 instance either via SSH over AWS Systems Manager (using your SSH ProxyCommand) or via a direct SSM interactive shell.

Purpose

• Default behavior: SSH to an instance ID like i-xxxxxxxxxxxxxxxxx using your ~/.ssh/config SSM ProxyCommand.
• Optional: run an interactive SSM shell instead with --ssm.

This script auto-selects a suitable SSH username (e.g., ubuntu for Ubuntu, ec2-user for Amazon Linux) using the instance platform/AMI metadata. If the platform is generic (e.g., "Linux/UNIX"), it inspects the instance AMI name (e.g., detects ubuntu, amazon linux, amzn, al2023, al2). If it still cannot determine the user, it will ask you to pass --user.

If --region is not provided and no default is configured, the script will prompt you to select a region interactively (fzf if available, otherwise a numbered menu).

It also exports AWS_PROFILE, AWS_REGION, and AWS_DEFAULT_REGION so the ProxyCommand inherits them.

Dependencies

• AWS CLI v2 (configured with SSO/credentials)
• ssh
• fzf (recommended; used for interactive selection)

SSH ProxyCommand setup

Configure your SSH to route i-* hosts via AWS SSM. One common approach is from qoomon’s aws-ssm-ssh-proxy-command.

Example ~/.ssh/config snippet:

Host i-*
  User ec2-user
  ProxyCommand aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=22'
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null

Reference: qoomon aws-ssm-ssh-proxy-command link

Note: You can still let the script pick the right user at runtime; the User in the SSH config above is just a fallback.

Usage

./ssm-connect.sh [options]

Options:
  -p, --profile  AWS profile (defaults to $AWS_PROFILE if set)
  -r, --region   AWS region. If not provided, you will be prompted to select one
  -a             List all instances (do not filter by state=running)
  --ssm          Force SSM shell (default is SSH via ~/.ssh/config ProxyCommand)
  -u, --user     SSH username override (defaults: ubuntu for Ubuntu, ec2-user otherwise)
  -h, --help     Show help

Examples

# Interactive picker, then SSH via ProxyCommand
./ssm-connect.sh

# Force SSM interactive shell
./ssm-connect.sh --ssm

# Use a specific profile and region
./ssm-connect.sh -p prod -r eu-west-1

# Override user explicitly
./ssm-connect.sh -u ubuntu

Notes

• The script exports AWS_PROFILE, AWS_REGION, and AWS_DEFAULT_REGION before invoking SSH, so your ProxyCommand runs in the correct account/region.
• If SSM cannot connect (TargetNotConnected), ensure the instance has the SSM agent running, IAM role with AmazonSSMManagedInstanceCore, and network access to the SSM endpoints (or VPC interface endpoints for ssm, ssmmessages, ec2messages).