Secure Shell Access via SSM Without SSH Keys

Beginner8 min

Connect to EC2 instances securely using AWS Systems Manager Session Manager, eliminating the need for SSH keys, bastion hosts, or open inbound ports.

Prerequisites

-AWS CLI v2 installed and configured
-Session Manager plugin installed for the AWS CLI
-EC2 instance with SSM Agent running and IAM instance profile attached

Steps

Verify the instance is managed by SSM

Check that the target EC2 instance appears in the SSM managed instances list, confirming the agent is running and has connectivity.

$ aws ssm describe-instance-information --filters Key=InstanceIds,Values=i-0example --query 'InstanceInformationList[*].{InstanceId:InstanceId,PingStatus:PingStatus,AgentVersion:AgentVersion,Platform:PlatformName}' --output table

If the instance does not appear, verify the instance has an IAM role with AmazonSSMManagedInstanceCore policy and that the SSM Agent is running.

Start an interactive session

Open a shell session to the EC2 instance through SSM, tunneled over HTTPS without requiring any inbound ports.

$ aws ssm start-session --target i-0example

Session Manager sessions are logged in CloudTrail and can optionally stream session output to S3 or CloudWatch for auditing.

Run a command without an interactive session

Execute a one-off command across one or more instances using SSM Run Command without opening an interactive shell.

$ aws ssm send-command --instance-ids i-0example --document-name "AWS-RunShellScript" --parameters commands=["df -h","free -m","uptime"] --query Command.CommandId --output text

SSM Run Command can target multiple instances at once using instance IDs, tags, or resource groups.

Get command output

Retrieve the output of a previously executed Run Command by its command ID.

$ aws ssm get-command-invocation --command-id COMMAND_ID_HERE --instance-id i-0example --query '{Status:Status,Output:StandardOutputContent}' --output json

Start a port forwarding session

Forward a remote port from the EC2 instance to your local machine through SSM, useful for accessing databases or internal services without VPN.

$ aws ssm start-session --target i-0example --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["5432"],"localPortNumber":["15432"]}'

Port forwarding keeps running until you press Ctrl+C. Your local port 15432 will forward to port 5432 on the remote instance, so you can connect with tools like psql -h localhost -p 15432.

Full Script

full-script.sh

#!/bin/bash
# SSM Session Manager Operations
# Usage: ./ssm-connect.sh <action> <instance-id> [options]
# Actions: connect, run, forward, list

set -euo pipefail

ACTION="${1:?Usage: $0 <connect|run|forward|list> <instance-id> [options]}"

case "$ACTION" in
  connect)
    INSTANCE_ID="${2:?Provide instance ID}"
    echo "Checking SSM agent status..."
    STATUS=$(aws ssm describe-instance-information \
      --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
      --query 'InstanceInformationList[0].PingStatus' --output text 2>/dev/null || echo "NotFound")

    if [ "$STATUS" != "Online" ]; then
      echo "Instance $INSTANCE_ID is not online in SSM (status: $STATUS)"
      echo "Verify the instance has an IAM role with AmazonSSMManagedInstanceCore policy."
      exit 1
    fi

    echo "Connecting to $INSTANCE_ID via Session Manager..."
    aws ssm start-session --target "$INSTANCE_ID"
    ;;

  run)
    INSTANCE_ID="${2:?Provide instance ID}"
    COMMAND="${3:?Provide command to run (in quotes)}"
    echo "Running command on $INSTANCE_ID: $COMMAND"

    CMD_ID=$(aws ssm send-command \
      --instance-ids "$INSTANCE_ID" \
      --document-name "AWS-RunShellScript" \
      --parameters "commands=["$COMMAND"]" \
      --query 'Command.CommandId' --output text)

    echo "Command ID: $CMD_ID"
    echo "Waiting for completion..."
    sleep 3

    aws ssm get-command-invocation \
      --command-id "$CMD_ID" \
      --instance-id "$INSTANCE_ID" \
      --query '{Status:Status,Output:StandardOutputContent,Error:StandardErrorContent}' \
      --output json | jq .
    ;;

  forward)
    INSTANCE_ID="${2:?Provide instance ID}"
    REMOTE_PORT="${3:?Provide remote port}"
    LOCAL_PORT="${4:-$REMOTE_PORT}"
    echo "Forwarding localhost:$LOCAL_PORT -> $INSTANCE_ID:$REMOTE_PORT"
    echo "Press Ctrl+C to stop."
    aws ssm start-session \
      --target "$INSTANCE_ID" \
      --document-name AWS-StartPortForwardingSession \
      --parameters "portNumber=[$REMOTE_PORT],localPortNumber=[$LOCAL_PORT]"
    ;;

  list)
    echo "=== SSM Managed Instances ==="
    aws ssm describe-instance-information \
      --query 'InstanceInformationList[*].{InstanceId:InstanceId,Name:ComputerName,Status:PingStatus,Agent:AgentVersion,OS:PlatformName}' \
      --output table
    ;;

  *)
    echo "Unknown action: $ACTION (use connect, run, forward, or list)"
    exit 1
    ;;
esac

FAQ

Discussion

Loading comments...

#!/bin/bash # SSM Session Manager Operations # Usage: ./ssm-connect.sh <action> <instance-id> [options] # Actions: connect, run, forward, list set -euo pipefail ACTION="${1:?Usage: $0 <connect|run|forward|list> <instance-id> [options]}" case "$ACTION" in connect) INSTANCE_ID="${2:?Provide instance ID}" echo "Checking SSM agent status..." STATUS=$(aws ssm describe-instance-information \ --filters "Key=InstanceIds,Values=$INSTANCE_ID" \ --query 'InstanceInformationList[0].PingStatus' --output text 2>/dev/null || echo "NotFound") if [ "$STATUS" != "Online" ]; then echo "Instance $INSTANCE_ID is not online in SSM (status: $STATUS)" echo "Verify the instance has an IAM role with AmazonSSMManagedInstanceCore policy." exit 1 fi echo "Connecting to $INSTANCE_ID via Session Manager..." aws ssm start-session --target "$INSTANCE_ID" ;; run) INSTANCE_ID="${2:?Provide instance ID}" COMMAND="${3:?Provide command to run (in quotes)}" echo "Running command on $INSTANCE_ID: $COMMAND" CMD_ID=$(aws ssm send-command \ --instance-ids "$INSTANCE_ID" \ --document-name "AWS-RunShellScript" \ --parameters "commands=["$COMMAND"]" \ --query 'Command.CommandId' --output text) echo "Command ID: $CMD_ID" echo "Waiting for completion..." sleep 3 aws ssm get-command-invocation \ --command-id "$CMD_ID" \ --instance-id "$INSTANCE_ID" \ --query '{Status:Status,Output:StandardOutputContent,Error:StandardErrorContent}' \ --output json | jq . ;; forward) INSTANCE_ID="${2:?Provide instance ID}" REMOTE_PORT="${3:?Provide remote port}" LOCAL_PORT="${4:-$REMOTE_PORT}" echo "Forwarding localhost:$LOCAL_PORT -> $INSTANCE_ID:$REMOTE_PORT" echo "Press Ctrl+C to stop." aws ssm start-session \ --target "$INSTANCE_ID" \ --document-name AWS-StartPortForwardingSession \ --parameters "portNumber=[$REMOTE_PORT],localPortNumber=[$LOCAL_PORT]" ;; list) echo "=== SSM Managed Instances ===" aws ssm describe-instance-information \ --query 'InstanceInformationList[*].{InstanceId:InstanceId,Name:ComputerName,Status:PingStatus,Agent:AgentVersion,OS:PlatformName}' \ --output table ;; *) echo "Unknown action: $ACTION (use connect, run, forward, or list)" exit 1 ;; esac