AWS Systems Manager (SSM) Agent is an Amazon service that runs on EC2 instances and allows you to manage them remotely without opening SSH ports or managing key pairs. It handles command execution, patch management, configuration updates, and interactive shell sessions – all through the AWS console or CLI. SSM Agent communicates with the Systems Manager service over HTTPS, so your instances never need inbound SSH access from the internet.
This guide covers installing and configuring SSM Agent on EC2 instances running Amazon Linux, Ubuntu, Debian, RHEL, Rocky Linux, CentOS, and AlmaLinux. We walk through IAM role setup, agent installation, Session Manager connections, remote command execution, and patch management.
Prerequisites
Before you begin, make sure you have the following in place:
- One or more EC2 instances running a supported Linux distribution (Amazon Linux 2/2023, Ubuntu 20.04+, Debian 11+, RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, CentOS 7/8)
- An AWS account with permissions to create IAM roles and policies
- An IAM instance profile with
AmazonSSMManagedInstanceCorepolicy attached (we cover this in Step 4) - AWS CLI installed on your local machine for CLI-based operations
- Outbound HTTPS (port 443) access from the instance to AWS endpoints
Step 1: Check if SSM Agent is Pre-installed
Many AMIs come with SSM Agent already installed. Amazon Linux 2, Amazon Linux 2023, and Ubuntu 20.04+ AMIs published by AWS include SSM Agent by default. Check if the agent is already running before installing manually.
Connect to your instance and check the agent status:
sudo systemctl status amazon-ssm-agentIf the agent is installed and running, you will see output showing the service as active:
● amazon-ssm-agent.service - amazon-ssm-agent
Loaded: loaded (/usr/lib/systemd/system/amazon-ssm-agent.service; enabled; preset: enabled)
Active: active (running) since Sat 2026-03-22 10:15:32 UTC; 2h ago
Main PID: 1842 (amazon-ssm-agen)
CGroup: /system.slice/amazon-ssm-agent.service
└─1842 /usr/bin/amazon-ssm-agentIf the service is not found, the agent is not installed and you need to install it manually following the steps below for your distribution.
You can also check the installed version:
amazon-ssm-agent --versionThe version output confirms the installed release. The latest version at the time of writing is 3.3.3883.0:
SSM Agent version: 3.3.3883.0Step 2: Install SSM Agent on RHEL / Rocky Linux / CentOS / AlmaLinux
For RHEL-based distributions, AWS provides an RPM package hosted in their S3 bucket. This works on RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, and CentOS 7/8.
Install SSM Agent using the RPM package directly from AWS:
sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-ssm/latest/linux_amd64/amazon-ssm-agent.rpmFor ARM-based instances (Graviton), use the ARM64 package instead:
sudo dnf install -y https://s3.amazonaws.com/ec2-downloads-ssm/latest/linux_arm64/amazon-ssm-agent.rpmOn CentOS 7 or older systems that use yum instead of dnf, replace dnf with yum in the commands above.
Enable and start the SSM Agent service:
sudo systemctl enable amazon-ssm-agent
sudo systemctl start amazon-ssm-agentVerify the service is running:
sudo systemctl status amazon-ssm-agentThe output should show the service as active (running) with no errors in the log.
Step 3: Install SSM Agent on Ubuntu / Debian
Ubuntu 20.04+ and Debian 11+ AMIs from AWS typically include SSM Agent. If your instance does not have it, or you are using a custom AMI, install it with the deb package from AWS.
Download and install the agent for x86_64 systems:
wget https://s3.amazonaws.com/ec2-downloads-ssm/latest/debian_amd64/amazon-ssm-agent.deb
sudo dpkg -i amazon-ssm-agent.debFor ARM64 (Graviton) instances:
wget https://s3.amazonaws.com/ec2-downloads-ssm/latest/debian_arm64/amazon-ssm-agent.deb
sudo dpkg -i amazon-ssm-agent.debEnable and start the service:
sudo systemctl enable amazon-ssm-agent
sudo systemctl start amazon-ssm-agentConfirm the agent is running:
sudo systemctl status amazon-ssm-agentYou should see active (running) status confirming the agent started successfully.
Step 4: Attach IAM Instance Profile for SSM
SSM Agent needs IAM permissions to communicate with the Systems Manager service. Without the right IAM role attached to your EC2 instance, the agent cannot register as a managed instance. The recommended approach is to create an IAM role with the AmazonSSMManagedInstanceCore managed policy and attach it as an instance profile.
Create the IAM Role via AWS CLI
Create a trust policy file that allows EC2 to assume the role:
cat > /tmp/ec2-trust-policy.json << 'ENDOFPOLICY'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
ENDOFPOLICYCreate the IAM role with this trust policy:
aws iam create-role \
--role-name SSMInstanceRole \
--assume-role-policy-document file:///tmp/ec2-trust-policy.jsonAttach the SSM managed policy to the role:
aws iam attach-role-policy \
--role-name SSMInstanceRole \
--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCoreCreate an instance profile and add the role to it:
aws iam create-instance-profile --instance-profile-name SSMInstanceProfile
aws iam add-role-to-instance-profile \
--instance-profile-name SSMInstanceProfile \
--role-name SSMInstanceRoleAttach the Instance Profile to an EC2 Instance
Associate the instance profile with a running EC2 instance. Replace i-0abc123def456789 with your actual instance ID:
aws ec2 associate-iam-instance-profile \
--iam-instance-profile Name=SSMInstanceProfile \
--instance-id i-0abc123def456789If the instance already has an instance profile attached and you need to replace it, first disassociate the existing one:
aws ec2 describe-iam-instance-profile-associations \
--filters Name=instance-id,Values=i-0abc123def456789Note the AssociationId from the output, then replace it:
aws ec2 replace-iam-instance-profile-association \
--iam-instance-profile Name=SSMInstanceProfile \
--association-id iip-assoc-0123456789abcdef0After attaching the profile, the SSM Agent picks up the new credentials within a few minutes. You can restart the agent to speed this up:
sudo systemctl restart amazon-ssm-agentStep 5: Verify Managed Instance in Systems Manager
Once SSM Agent is installed and the IAM role is attached, the instance should register itself with AWS Systems Manager. This usually takes 1-2 minutes after the agent starts.
Check from the AWS CLI whether your instance appears as a managed instance:
aws ssm describe-instance-information \
--filters Key=InstanceIds,Values=i-0abc123def456789A successful registration returns instance details including the agent version and ping status:
{
"InstanceInformationList": [
{
"InstanceId": "i-0abc123def456789",
"PingStatus": "Online",
"LastPingDateTime": "2026-03-22T10:30:00.000Z",
"AgentVersion": "3.3.3883.0",
"IsLatestVersion": true,
"PlatformType": "Linux",
"PlatformName": "Rocky Linux",
"PlatformVersion": "10.0"
}
]
}The PingStatus should be Online. If it shows ConnectionLost or the instance does not appear at all, check these common issues:
- IAM instance profile is not attached or missing
AmazonSSMManagedInstanceCorepolicy - The instance has no outbound internet access (SSM Agent needs HTTPS to AWS endpoints)
- Security group or NACL blocks outbound port 443
- SSM Agent service is not running - check with
systemctl status amazon-ssm-agent
You can also verify from the AWS Console by navigating to Systems Manager > Fleet Manager. Your instance should appear in the managed instances list with an Online status.
Step 6: Connect to EC2 Instance via Session Manager
Session Manager provides a browser-based shell or CLI-based shell session to your instances without needing SSH keys, bastion hosts, or open inbound ports. All sessions are logged and auditable through CloudWatch or S3.
Connect from the AWS Console
Open the AWS Systems Manager console, go to Session Manager, and click Start session. Select your target instance from the list and click Start session. A browser-based terminal opens with a shell on the instance.
Connect from the AWS CLI
To start a session from your terminal, install the Session Manager plugin for the AWS CLI first. On Linux:
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o /tmp/session-manager-plugin.deb
sudo dpkg -i /tmp/session-manager-plugin.debFor RPM-based systems:
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm" -o /tmp/session-manager-plugin.rpm
sudo dnf install -y /tmp/session-manager-plugin.rpmStart a session to your instance:
aws ssm start-session --target i-0abc123def456789You get a shell session on the instance immediately, tunneled over HTTPS. No SSH key management needed:
Starting session with SessionId: user-0abc123def
sh-5.1$Type exit to end the session.
Step 7: Run Commands Remotely with Run Command
Systems Manager Run Command lets you execute commands on one or many instances without connecting to each one. This is useful for fleet-wide operations like checking disk space, restarting services, or running scripts across hundreds of servers.
Run a shell command on a single instance:
aws ssm send-command \
--instance-ids i-0abc123def456789 \
--document-name "AWS-RunShellScript" \
--parameters 'commands=["hostname","uptime","df -h /"]' \
--output jsonThe command returns a CommandId you can use to check the output:
aws ssm get-command-invocation \
--command-id "a1b2c3d4-5678-90ab-cdef-111222333444" \
--instance-id i-0abc123def456789 \
--query 'StandardOutputContent' \
--output textThis returns the actual command output from the instance:
ip-10-0-1-50.ec2.internal
10:45:12 up 3 days, 2:30, 0 users, load average: 0.02, 0.03, 0.00
Filesystem Size Used Avail Use% Mounted on
/dev/xvda1 20G 4.2G 16G 22% /To run a command on multiple instances, pass a list of instance IDs or use tags to target them:
aws ssm send-command \
--targets Key=tag:Environment,Values=production \
--document-name "AWS-RunShellScript" \
--parameters 'commands=["systemctl status nginx"]'This targets all instances tagged with Environment=production and checks the Nginx service status across the fleet.
Step 8: Patch Management with AWS SSM
Systems Manager Patch Manager automates patching across your EC2 fleet. You define a patch baseline (which patches to approve), a maintenance window (when to apply them), and a patch group (which instances to target). If you are managing EKS clusters or large fleets, Patch Manager keeps everything updated without manual SSH sessions.
Scan Instances for Missing Patches
Run a patch scan to see what patches are missing on an instance:
aws ssm send-command \
--instance-ids i-0abc123def456789 \
--document-name "AWS-RunPatchBaseline" \
--parameters 'Operation=Scan'After the scan completes, check the compliance status:
aws ssm describe-instance-patch-states \
--instance-ids i-0abc123def456789The output shows the number of installed, missing, and failed patches:
{
"InstancePatchStates": [
{
"InstanceId": "i-0abc123def456789",
"PatchGroup": "production",
"OperationType": "Scan",
"InstalledCount": 145,
"MissingCount": 3,
"FailedCount": 0,
"InstalledOtherCount": 12
}
]
}Install Missing Patches
To apply missing patches, run the same document with Install instead of Scan:
aws ssm send-command \
--instance-ids i-0abc123def456789 \
--document-name "AWS-RunPatchBaseline" \
--parameters 'Operation=Install'For production environments, schedule patching through a maintenance window rather than running ad-hoc commands. This ensures patches apply during approved change windows and instances reboot gracefully.
Step 9: SSM Agent vs SSH - When to Use Each
SSM Session Manager replaces SSH for most operational tasks. Here is a direct comparison to help you decide which to use.
| Feature | SSM Session Manager | SSH |
|---|---|---|
| Inbound ports required | None - outbound 443 only | Port 22 open to source IPs |
| Key management | IAM roles - no SSH keys | Key pairs per user/instance |
| Audit logging | Built-in (CloudWatch, S3) | Requires custom setup |
| Bastion host needed | No | Yes, for private subnets |
| File transfer | Limited (use S3) | SCP/SFTP built-in |
| Port forwarding | Supported | Supported |
| Multi-instance commands | Run Command (fleet-wide) | Requires Ansible/scripts |
| Works without internet | Yes, with VPC endpoints | Yes, within VPC |
| Cost | Free (SSM service) | Free |
Use SSM for day-to-day operations, fleet management, and environments where security compliance requires no open inbound ports. Use SSH when you need SCP/SFTP file transfers, run Packer and Ansible workflows that depend on SSH, or work with non-AWS infrastructure.
Troubleshooting SSM Agent
If your instance does not show up in Fleet Manager or Session Manager fails to connect, check the agent logs for errors:
sudo tail -50 /var/log/amazon/ssm/amazon-ssm-agent.logCommon issues and fixes:
- AccessDeniedException - the IAM instance profile is missing or does not have
AmazonSSMManagedInstanceCorepolicy. Attach the correct role and restart the agent - Unable to connect to endpoint - the instance cannot reach SSM endpoints on port 443. Check security groups, NACLs, and route tables. For private subnets without NAT, create VPC endpoints for
ssm,ssmmessages, andec2messages - Agent stuck in registration - restart the agent with
sudo systemctl restart amazon-ssm-agentand wait 2 minutes - Old agent version - update to the latest version by reinstalling the package from the S3 URL shown in Step 2 or Step 3
To set up automatic agent updates so you always run the latest version:
aws ssm create-association \
--name "AWS-UpdateSSMAgent" \
--targets Key=InstanceIds,Values=i-0abc123def456789 \
--schedule-expression "rate(14 days)"This creates a State Manager association that automatically updates SSM Agent every 14 days.
Conclusion
AWS Systems Manager Agent provides a secure, auditable way to manage EC2 instances without SSH. With SSM installed and an IAM role attached, you get Session Manager for interactive access, Run Command for fleet-wide operations, and Patch Manager for automated patching - all without opening port 22.
For production deployments, enable session logging to CloudWatch or S3 for compliance, set up automatic agent updates with State Manager, and use VPC endpoints if your instances run in private subnets without internet access. Refer to the SSM Agent GitHub repository for the latest releases and source code.
