Set up AWS Session Manager

Session Manager needs four things: an SSM Agent on the instance, an instance profile that lets the agent talk to Systems Manager, network reachability to three regional endpoints (or VPC endpoints), and an IAM policy for the people who connect. For CLI use, add the Session Manager plugin on your laptop.

1. Instance side

1.1 SSM Agent version

FeatureMinimum SSM Agent
Basic shell sessions2.3.68.0
KMS encryption of session data2.3.539.0
Shell profiles3.0.161.0
Port forwarding and SSH sessions3.0.222.0
Port forwarding to a remote host3.1.1374.0
Streaming session data to CloudWatch Logs3.0.284.0

The agent is preinstalled on most AWS-provided AMIs. AWS recommends automating updates (AWS-UpdateSSMAgent via State Manager or a maintenance window).

1.2 Instance profile

Attach an IAM role (via an instance profile) that includes the AWS managed policy AmazonSSMManagedInstanceCore. If you already use Run Command or Parameter Store, this is probably in place. Two alternatives:

  • Default Host Management Configuration — grants the permission at the account level with AmazonSSMManagedEC2InstanceDefaultPolicy, so you don't need per-instance profiles.
  • Quick Setup → Host Management — creates the profile and attaches it for you; the EC2 console's Session Manager tab prompts for this when it's missing.

If SSM Agent was already running when you attached the profile, restart the agent (or the instance) so it registers.

1.3 Network reachability

Instances must allow HTTPS (443) outbound to:

ec2messages.<region>.amazonaws.com
ssm.<region>.amazonaws.com
ssmmessages.<region>.amazonaws.com

ssmmessages is the one Session Manager itself uses. Add kms.<region>, logs.<region> and s3.<region> if you enable KMS encryption, CloudWatch streaming or S3 logging.

No internet access? Create VPC interface endpoints (AWS PrivateLink) for ssm, ssmmessages and ec2messages — plus logs/kms interface endpoints and an s3 gateway endpoint if you log. Then the instance needs no internet gateway, NAT or public IP at all.

2. User side

2.1 IAM policy for people who connect

The minimum for CLI users, from AWS's quickstart samples (replace the placeholders):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ssm:StartSession"],
      "Resource": [
        "arn:aws:ec2:REGION:ACCOUNT_ID:instance/INSTANCE_ID",
        "arn:aws:ssm:REGION:ACCOUNT_ID:document/SSM-SessionManagerRunShell"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["ssmmessages:OpenDataChannel"],
      "Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
    },
    {
      "Effect": "Allow",
      "Action": ["ssm:TerminateSession", "ssm:ResumeSession"],
      "Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
    }
  ]
}
  • For port forwarding, add the document ARN arn:aws:ssm:REGION::document/AWS-StartPortForwardingSession (and AWS-StartPortForwardingSessionToRemoteHost if you use it) to the ssm:StartSession resources.
  • For SSH over Session Manager, add AWS-StartSSHSession.
  • To grant by tag instead of instance ID, use a Condition with "ssm:resourceTag/<Key>": ["<Value>"] on arn:aws:ec2:*:ACCOUNT_ID:instance/*.
  • If you encrypt session data with a KMS key, also allow kms:GenerateDataKey on that key.
  • Add ssm:DescribeSessions, ssm:GetConnectionStatus, ssm:DescribeInstanceProperties and ec2:DescribeInstances for console users who need to list targets.

2.2 AWS CLI and the Session Manager plugin

  • AWS CLI 1.16.12 or later (v2 recommended).
  • The Session Manager plugin, version 1.2.764.0 or later — AWS says older versions will stop being supported. Check with:
session-manager-plugin --version

Installers exist for Windows, macOS and Linux (Debian/Ubuntu and RPM). On Windows the installer should add C:\Program Files\Amazon\SessionManagerPlugin\bin\ to PATH; if aws ssm start-session can't find the plugin, add it manually.

3. First session

aws ssm start-session --target i-0123456789abcdef0

From the console: EC2 → Instances → Connect → Session Manager, or Systems Manager → Session Manager → Start session. If the instance isn't listed, or the tab says it isn't configured, work through Session Manager troubleshooting.

4. Optional hardening

  • Session preferences (SSM-SessionManagerRunShell document): idle timeout, shell profile, KMS key, and where transcripts go.
  • Restrict ssm-user administrative permissions if you don't want every session to be root/Administrator.
  • Logging: enable CloudWatch Logs streaming or S3 delivery for interactive sessions (port-forwarding and SSH sessions are not transcribed).

Common questions

Do I need the instance profile if I use Default Host Management Configuration?

No — DHMC grants the permission at the account level with AmazonSSMManagedEC2InstanceDefaultPolicy, so per-instance profiles aren't required.

Which VPC endpoints are strictly required?

ssm, ssmmessages and ec2messages interface endpoints. kms, logs and the s3 gateway endpoint are only needed for the optional encryption and logging features.

Why can't the plugin be found after installing on Windows?

The installer normally adds the plugin to PATH. If it didn't, add C:\Program Files\Amazon\SessionManagerPlugin\bin\ to your user PATH and reopen the command prompt.

Sources