AWS Systems Manager

User Guide
 AWS Systems Manager User Guide

AWS Systems Manager: User Guide

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.

The AWS Documentation website is getting a new look!

Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.
 AWS Systems Manager User Guide

Table of Contents
What Is AWS Systems Manager? .......................................................................................................... 1
Capabilities ................................................................................................................................ 3
Operations Management ..................................................................................................... 4
Actions & Change .............................................................................................................. 4
Instances & Nodes .............................................................................................................. 5
Shared Resources ............................................................................................................... 6
How It Works ............................................................................................................................ 6
About SSM Agent ....................................................................................................................... 9
Supported Operating Systems ................................................................................................... 10
Windows Server ............................................................................................................... 10
Linux .............................................................................................................................. 10
Raspbian ......................................................................................................................... 12
Accessing Systems Manager ....................................................................................................... 12
Prerequisites ............................................................................................................................ 12
Quick Setup ..................................................................................................................................... 14
Permissions Roles ..................................................................................................................... 14
Details about the Default Instance Profile ........................................................................... 15
Details about the Service Role ........................................................................................... 16
Update Systems Manager (SSM) Agent ........................................................................................ 17
Collect Inventory from Your Instances ......................................................................................... 17
Scan Instances for Missing Patches Daily ..................................................................................... 18
Install and Configure the CloudWatch Agent ................................................................................ 18
Update the CloudWatch Agent Once Every Four Weeks ................................................................. 18
Working with Quick Setup Results .............................................................................................. 18
Troubleshooting Quick Setup Results .......................................................................................... 20
Running Quick Setup Again ....................................................................................................... 21
Setting Up Systems Manager ............................................................................................................. 23
Step 1: Sign Up for AWS ........................................................................................................... 23
Step 2: Create an Admin IAM User for AWS ................................................................................. 24
Step 3: Create Non-Admin IAM Users and Groups for Systems Manager ........................................... 25
Task 1: Create Policies for Tag Editor and Resource Groups .................................................... 25
Task 2: Create User Groups ................................................................................................ 26
Task 3: Create Users and Assign Permissions ........................................................................ 27
Step 4: Create an IAM Instance Profile for Systems Manager .......................................................... 29
About Policies for a Systems Manager Instance Profile .......................................................... 29
Task 1: (Optional) Create a Custom S3 Bucket Policy for an Instance Profile .............................. 30
Task 2: Add Permissions to a Systems Manager Instance Profile (Console) ................................ 32
Step 5: Attach an IAM Instance Profile to an Amazon EC2 Instance ................................................. 34
Launch an Instance that Uses the Systems Manager Instance Profile (Console) .......................... 35
Attach the Systems Manager Instance Profile to an Existing Instance (Console) ......................... 35
Step 6: (Optional) Create a Virtual Private Cloud Endpoint ............................................................. 36
VPC Endpoint Restrictions and Limitations .......................................................................... 36
Creating VPC Endpoints for Systems Manager ...................................................................... 37
Step 7: (Optional) Create Systems Manager Service Roles .............................................................. 38
Create a Service Role ........................................................................................................ 38
Step 8: (Optional) Set Up Integrations with Other AWS Services ..................................................... 40
Setting Up Hybrid Environments ........................................................................................................ 41
Step 1: Complete General Systems Manager Setup Steps .............................................................. 42
Step 2: Create an IAM Service Role for a Hybrid Environment ......................................................... 42
Step 3: Install a TLS certificate on On-Premises Servers and VMs .................................................... 45
Step 4: Create a Managed-Instance Activation for a Hybrid Environment .......................................... 45
Create an Activation (Console) ........................................................................................... 46
Create a Managed Instance Activation (Command Line) ......................................................... 47
Step 5: Install SSM Agent for a Hybrid Environment (Windows) ...................................................... 48

iii
 AWS Systems Manager User Guide

Step 6: Install SSM Agent for a Hybrid Environment (Linux) ........................................................... 50

Step 7: (Optional) Enable the Advanced-Instances Tier .................................................................. 53
Configuring Permissions to Enable the Advanced-Instances Tier .............................................. 53
Enabling the Advanced-Instances Tier (Console) ................................................................... 55
Enabling the Advanced-Instances Tier (AWS CLI) .................................................................. 55
Enabling the Advanced-Instances Tier (PowerShell) ............................................................... 56
Getting Started ................................................................................................................................ 58
Step 1: Install or Upgrade the AWS CLI ....................................................................................... 58
Step 2: Install or Upgrade the AWS Tools for PowerShell ............................................................... 59
Step 3: Practice Installing or Updating SSM Agent on an Instance ................................................... 60
Step 4: Try Systems Manager Tutorials and Walkthroughs ............................................................. 61
Working with SSM Agent .................................................................................................................. 64
Installing and Configuring SSM Agent on Windows Instances ......................................................... 65
Install and Configure SSM Agent on Amazon EC2 Windows Instances ...................................... 66
View SSM Agent Logs on Windows Instances ....................................................................... 67
Configure SSM Agent to Use a Proxy for Windows Instances .................................................. 67
Installing and Configuring SSM Agent on Amazon EC2 Linux Instances ............................................ 68
Manually Install SSM Agent on Amazon EC2 Linux Instances .................................................. 68
Configure SSM Agent to Use a Proxy .................................................................................. 82
View SSM Agent Logs ....................................................................................................... 84
Uninstall SSM Agent from Linux Instances ........................................................................... 85
Restrict Access to Root-Level Commands Through SSM Agent ........................................................ 85
Automate Updates to SSM Agent ............................................................................................... 86
Subscribe to SSM Agent Notifications ......................................................................................... 86
About Minimum S3 Bucket Permissions for SSM Agent ................................................................. 87
Required Permissions ........................................................................................................ 87
Example .......................................................................................................................... 88
Partner and Product Integration ......................................................................................................... 90
Referencing AWS Secrets Manager Secrets from Parameter Store Parameters ................................... 90
Restrictions ...................................................................................................................... 90
How to Reference a Secrets Manager Secret by Using Parameter Store .................................... 91
Running Scripts from GitHub and Amazon S3 .............................................................................. 93
Running Scripts from GitHub ............................................................................................. 94
Running Scripts from Amazon S3 ....................................................................................... 98
Using Chef InSpec Profiles with Systems Manager Compliance ..................................................... 105
How It Works ................................................................................................................. 105
Running an InSpec Compliance Scan ................................................................................. 106
Operations Management ................................................................................................................. 109
CloudWatch Dashboards .......................................................................................................... 109
OpsCenter ............................................................................................................................. 109
How Can OpsCenter Benefit My Organization? ................................................................... 110
What Are the Features of OpsCenter? ............................................................................... 110
How Does OpsCenter Work with Amazon CloudWatch Events? Which Service Should I Use? ....... 112
Does OpsCenter Integrate with My Existing Case Management System? ................................. 112
Is There a Charge to Use OpsCenter? ................................................................................ 112
Does OpsCenter Work with My On-Premises and Hybrid Managed Instances? .......................... 113
What are the resource limits for OpsCenter? ...................................................................... 113
Getting Started with OpsCenter ....................................................................................... 113
Creating OpsItems .......................................................................................................... 119
Working with OpsItems ................................................................................................... 125
Remediating OpsItem Issues ............................................................................................ 133
Viewing OpsCenter Summary Reports ............................................................................... 136
Supported Resources Reference ........................................................................................ 136
Auditing and Logging OpsCenter Activity .......................................................................... 140
Resource Groups ..................................................................................................................... 140
Trusted Advisor and PHD ......................................................................................................... 140
Actions & Change ........................................................................................................................... 142

iv
 AWS Systems Manager User Guide

Automation ............................................................................................................................ 142

Automation Use Cases .................................................................................................... 142
Getting Started with Automation ..................................................................................... 144
Working with Automation Executions ................................................................................ 150
Working with Automation Documents ............................................................................... 217
Automation Walkthroughs ............................................................................................... 400
Troubleshooting Systems Manager Automation .................................................................. 433
Maintenance Windows ............................................................................................................. 444
Controlling Access .......................................................................................................... 445
Working with Maintenance Windows (Console) ................................................................... 455
Maintenance Windows Tutorials (AWS CLI) ......................................................................... 461
Maintenance Windows Walkthroughs ................................................................................ 496
Instances & Nodes .......................................................................................................................... 504
Compliance ............................................................................................................................ 504
Getting Started with Configuration Compliance .................................................................. 505
Creating a Resource Data Sync for Configuration Compliance ............................................... 505
Working With Configuration Compliance ........................................................................... 507
Remediating Compliance Issues ........................................................................................ 510
Configuration Compliance Walkthrough (AWS CLI) .............................................................. 511
Inventory ............................................................................................................................... 512
Learn More About Inventory ............................................................................................ 515
Configuring Resource Data Sync for Inventory .................................................................... 520
Configuring Inventory Collection ...................................................................................... 523
Working with Inventory Data ........................................................................................... 527
Working with Custom Inventory ....................................................................................... 541
Viewing Inventory History and Change Tracking ................................................................. 551
Inventory Walkthroughs .................................................................................................. 552
Troubleshooting Inventory ............................................................................................... 562
Managed Instances ................................................................................................................. 563
Resetting Passwords on Managed Instances ....................................................................... 564
Activations ............................................................................................................................. 567
Session Manager .................................................................................................................... 567
How can Session Manager benefit my organization? ............................................................ 568
Who Should Use Session Manager? ................................................................................... 569
What Are the Main Features of Session Manager? ............................................................... 569
What Is a Session? .......................................................................................................... 570
Getting Started with Session Manager .............................................................................. 571
Working with Session Manager ......................................................................................... 598
Auditing and Logging Session Activity ............................................................................... 608
Troubleshooting Session Manager ..................................................................................... 611
Run Command ....................................................................................................................... 613
Setting Up Run Command ............................................................................................... 613
Running Commands ........................................................................................................ 619
Understanding Command Statuses ................................................................................... 627
Run Command Walkthroughs ........................................................................................... 631
Troubleshooting Run Command ....................................................................................... 642
State Manager ....................................................................................................................... 645
About State Manager ...................................................................................................... 646
Working with Associations ............................................................................................... 647
State Manager Walkthroughs ........................................................................................... 667
Patch Manager ....................................................................................................................... 683
Patch Manager Prerequisites ............................................................................................ 684
How It Works ................................................................................................................. 685
About Patching Operations .............................................................................................. 699
About Patch Baselines ..................................................................................................... 709
Working with Patch Manager (Console) ............................................................................. 720
Tutorial: Patch a Server Environment (AWS CLI) .................................................................. 732

v
 AWS Systems Manager User Guide

AWS CLI Commands for Patch Manager ............................................................................ 737

Distributor ............................................................................................................................. 749
How Can Distributor Benefit my Organization? ................................................................... 750
Who Should Use Distributor? ........................................................................................... 750
What Are the Features of Distributor? ............................................................................... 750
What Is a Package? ......................................................................................................... 751
Getting Started with Distributor ....................................................................................... 752
Working with Distributor ................................................................................................. 754
Auditing and Logging Distributor Activity .......................................................................... 773
Troubleshooting Distributor ............................................................................................. 773
Shared Resources ........................................................................................................................... 775
SSM Documents ..................................................................................................................... 775
Systems Manager Pre-Defined Documents ......................................................................... 777
SSM Document Schemas and Features .............................................................................. 778
SSM Document Syntax .................................................................................................... 779
Creating Systems Manager Documents .............................................................................. 784
Tagging Documents ........................................................................................................ 787
Sharing Systems Manager Documents ............................................................................... 790
Creating Composite Documents ........................................................................................ 796
Running Documents from Remote Locations ...................................................................... 797
SSM Document Plugin Reference ...................................................................................... 800
Parameter Store ..................................................................................................................... 825
Getting Started with Parameter Store ............................................................................... 826
Learn More About Parameters .......................................................................................... 827
Setting Up Parameter Store ............................................................................................. 832
Working with Parameters ................................................................................................ 839
Working with Public Parameters ....................................................................................... 861
Increasing Parameter Store Throughput ............................................................................ 866
Specifying a Default Parameter Tier .................................................................................. 869
Parameter Store Walkthroughs ......................................................................................... 875
Monitoring ..................................................................................................................................... 882
Sending Logs to CloudWatch Logs (SSM Agent) .......................................................................... 882
Sending Logs to CloudWatch Logs (CloudWatch agent) ............................................................... 884
Migrate Windows Server Instance Log Collection to the CloudWatch agent ............................. 884
Store CloudWatch agent Configuration Settings in Parameter Store ...................................... 888
Rolling Back to Log Collection with SSM Agent .................................................................. 888
Logging AWS Systems Manager API Calls with AWS CloudTrail ..................................................... 889
Systems Manager Information in CloudTrail ....................................................................... 889
Understanding Systems Manager Log File Entries ............................................................... 890
Monitoring with Amazon CloudWatch Events ............................................................................. 891
Configuring CloudWatch Events for Automation ................................................................. 892
Amazon SNS Notifications ....................................................................................................... 893
Configure Amazon SNS Notifications for AWS Systems Manager ........................................... 893
Example Amazon SNS Notifications for AWS Systems Manager ............................................. 899
Use Run Command to Send a Command that Returns Status Notifications ............................. 900
Use a Maintenance Window to Send a Command that Returns Status Notifications .................. 902
Authentication and Access Control .................................................................................................... 906
Authentication ....................................................................................................................... 906
Access Control ........................................................................................................................ 907
Overview of Managing Access .................................................................................................. 907
Resources and Operations ............................................................................................... 908
Understanding Resource Ownership .................................................................................. 910
Managing Access to Resources ......................................................................................... 911
Specifying Policy Elements: Resources, Actions, Effects, and Principals ................................... 913
Specifying Conditions in a Policy ...................................................................................... 913
Using Identity-Based Policies (IAM Policies) ................................................................................ 914
Permissions Required to Use the AWS Systems Manager Console .......................................... 914

vi
 AWS Systems Manager User Guide

AWS Managed Policies for AWS Systems Manager .............................................................. 915

Customer Managed Policy Examples ................................................................................. 916
Using Service-Linked Roles ...................................................................................................... 919
Service-Linked Role Permissions for Systems Manager ......................................................... 919
Creating a Service-Linked Role for Systems Manager ........................................................... 920
Editing a Service-Linked Role for Systems Manager ............................................................. 920
Deleting a Service-Linked Role for Systems Manager ........................................................... 920
Supported Regions for Systems Manager Service-Linked Roles ............................................. 921
AWS Systems Manager Permissions Reference ............................................................................ 921
AWS Systems Manager Reference ..................................................................................................... 933
Cron and Rate Expressions ....................................................................................................... 933
General Information About Cron and Rate Expressions ........................................................ 934
Cron and Rate Expressions for Associations ........................................................................ 937
Cron and Rate Expressions for Maintenance Windows .......................................................... 938
Maintenance Windows Scheduling and Active Period Options ....................................................... 939
Example 1: Specify a maintenance window start date ......................................................... 939
Example 2: Specify a maintenance window start date and end date ...................................... 940
Example 3: Create a maintenance window that runs only once ............................................. 940
ec2messages, ssmmessages, and Other API Calls ........................................................................ 941
Use Cases and Best Practices ........................................................................................................... 942
Document History .......................................................................................................................... 944
Earlier Updates ....................................................................................................................... 968
AWS Glossary ................................................................................................................................. 980

vii
 AWS Systems Manager User Guide

What Is AWS Systems Manager?

AWS Systems Manager is an AWS service that you can use to view and control your infrastructure on
AWS. Using the Systems Manager console, you can view operational data from multiple AWS services and
automate operational tasks across your AWS resources. Systems Manager helps you maintain security
and compliance by scanning your managed instances and reporting on (or taking corrective action on)
any policy violations it detects.

A managed instance is a machine that has been configured for use with Systems Manager. Systems
Manager also helps you configure and maintain your managed instances. Supported machine types
include Amazon EC2 instances, on-premises servers, and virtual machines (VMs), including VMs in other
cloud environments. Supported operating system types include Windows Server, multiple distributions
of Linux, and Raspbian.

Using Systems Manager, you can associate AWS resources together by applying the same identifying
resource tag to each of them. You can then view operational data for these resources as a resource group,
to help monitor and troubleshoot.

For example, you can assign a resource tag of "Operation=North Region OS Patching" to all of the
following resources:

• A group of Amazon EC2 instances

• A group of on-premises servers in your own facility
• A Systems Manager patch baseline that specifies which patches to apply to your managed instances
• An Amazon S3 bucket to store patching operation log output
• A Systems Manager maintenance window that specifies the schedule for the patching operation

After tagging the resources, you can view a consolidated dashboard in Systems Manager that reports
the status of all the resources that are part of the patching operation in your North region. If a problem
arises with any of these resources, you can take corrective action immediately.

Capabilities in Systems Manager

Systems Manager is comprised of individual capabilities (p. 3), which are grouped into four
categories: Operations Management, Actions & Change, Instances & Nodes, and Shared Resources.

This collection of capabilities is a powerful set of tools and features that you can use to perform many
operational tasks. For example:

• Group AWS resources together by any purpose or activity you choose, such as application,
environment, region, project, campaign, business unit, or software lifecycle.
• Centrally define the configuration options and policies for your managed instances.
• Centrally view, investigate, and resolve operational work items related to AWS resources.
• Automate or schedule a variety of maintenance and deployment tasks.
• Use and create runbook-style SSM documents that define the actions to perform on your managed
instances.
• Run a command, with rate and error controls, that targets an entire fleet of managed instances.
• Securely connect to a managed instance with a single click, without having to open an inbound port or
manage SSH keys.

1
 AWS Systems Manager User Guide

• Separate your secrets and configuration data from your code by using parameters, with or without
encryption, and then reference those parameters from a number of other AWS services.
• Perform automated inventory by collecting metadata about your Amazon EC2 and on-premises
managed instances. Metadata can include information about applications, network configurations, and
more.
• View consolidated inventory data from multiple AWS Regions and accounts that you manage.
• Quickly see which resources in your account are out of compliance and take corrective action from a
centralized dashboard.
• View active summaries of metrics and alarms for your AWS resources.

Systems Manager simplifies resource and application management, shortens the time to detect and
resolve operational problems, and helps you operate and manage your AWS infrastructure securely at
scale.
Note
AWS Systems Manager was formerly known as Amazon Simple Systems Manager (SSM) and
Amazon EC2 Systems Manager (SSM). For more information, see Systems Manager Service Name
History (p. 2).

What is AWS Systems Manager? (Video)

View more AWS videos on the Amazon Web Services YouTube Channel.

Systems Manager Supported Regions

AWS Systems Manager is available in the AWS Regions listed in the AWS Systems Manager
Supported Regions table in the AWS General Reference. Before starting your Systems Manager
configuration process, we recommend that you ensure the service is available in each of the AWS
Regions you want to use it in.

For on-premises servers and VMs in your hybrid environment, we recommend that you choose the
Region closest to your data center or computing environment.
Systems Manager Pricing

Some Systems Manager capabilities charge a fee. For more information, see AWS Systems Manager
Pricing.
Systems Manager Service Name History

AWS Systems Manager (Systems Manager) was formerly known as "Amazon Simple Systems
Manager (SSM)" and "Amazon EC2 Systems Manager (SSM)". The original abbreviated name of the
service, "SSM", is still reflected in various AWS resources, including a few other service consoles.
Some examples:
• Systems Manager Agent: SSM Agent
• Systems Manager parameters: SSM parameters
• Systems Manager service endpoints: ssm.us-east-2.amazonaws.com
• AWS CloudFormation resource types: AWS::SSM::Document
• AWS Config rule identifier: EC2_INSTANCE_MANAGED_BY_SSM
• AWS CLI commands: aws ssm describe-patch-baselines
• AWS Identity and Access Management (IAM) managed policy names:
AmazonSSMReadOnlyAccess
• Systems Manager resource ARNs: arn:aws:ssm:us-
east-2:111222333444:patchbaseline/pb-07d8884178EXAMPLE

2
 AWS Systems Manager User Guide
Capabilities

Related Content

The following resources can help you work directly with Systems Manager.
• AWS Blog & Podcast – Read blog posts about Systems Manager in the AWS Management Tools
Category, as well as other posts that are tagged with #Systems Manager.
• Systems Manager Developer Forum – Follow announcements, or post or answer a question in the
AWS Systems Manager Forum.
• AWS Systems Manager API Reference – Provides descriptions, syntax, and usage examples for
each of the Systems Manager actions and data types.
• AWS Systems Manager section of the AWS CLI Command Reference – Manage Systems Manager
from a command line tool. Available to use on Windows, Mac, and Linux/UNIX systems.
• AWS Systems Manager section of the AWS Tools for PowerShell Cmdlet Reference – Manage
Systems Manager with the same PowerShell tools that you use to manage your Windows, Linux, or
Mac environments.
• AWS Systems Manager Limits in the Amazon Web Services General Reference – Provides the
default limits for Systems Manager for an AWS account. Unless otherwise noted, each limit is
Region-specific.

The following related resources can help you as you work with this service.
• Classes & Workshops – Links to role-based and specialty courses as well as self-paced labs to help
sharpen your AWS skills and gain practical experience.
• AWS Developer Tools – Links to developer tools, SDKs, IDE toolkits, and command line tools for
developing and managing AWS applications.
• AWS Whitepapers – Links to a comprehensive list of technical AWS whitepapers, covering topics
such as architecture, security, and economics and authored by AWS Solutions Architects or other
technical experts.
• AWS Support Center – The hub for creating and managing your AWS Support cases. Also includes
links to other helpful resources, such as forums, technical FAQs, service health status, and AWS
Trusted Advisor.
• AWS Support – The primary web page for information about AWS Support, a one-on-one, fast-
response support channel to help you build and run applications in the cloud.
• Contact Us – A central contact point for inquiries concerning AWS billing, account, events, abuse,
and other issues.
• AWS Site Terms – Detailed information about our copyright and trademark; your account, license,
and site access; and other topics.

Learn More About Systems Manager

• Systems Manager Capabilities (p. 3)
• How Systems Manager Works (p. 6)
• About SSM Agent (p. 9)
• Supported Operating Systems (p. 10)
• Accessing Systems Manager (p. 12)
• Systems Manager Prerequisites (p. 12)

Systems Manager Capabilities

Systems Manager capabilities are grouped into the following capability types:

3
 AWS Systems Manager User Guide
Operations Management

Topics
• Operations Management (p. 4)
• Actions & Change (p. 4)
• Instances & Nodes (p. 5)
• Shared Resources (p. 6)

Operations Management
Operations Management is a suite of capabilities that help you manage your AWS resources.

CloudWatch Dashboards

Amazon CloudWatch Dashboards are customizable home pages in the CloudWatch console that
you can use to monitor your resources in a single view, even those resources that are spread across
different regions. You can use CloudWatch dashboards to create customized views of the metrics and
alarms for your AWS resources.
OpsCenter

OpsCenter (p. 109) provides a central location where operations engineers and IT professionals
can view, investigate, and resolve operational work items (OpsItems) related to AWS resources.
OpsCenter is designed to reduce mean time to resolution for issues impacting AWS resources. This
Systems Manager capability aggregates and standardizes OpsItems across services while providing
contextual investigation data about each OpsItem, related OpsItems, and related resources.
OpsCenter also provides Systems Manager Automation documents (runbooks) that you can use to
quickly resolve issues. You can specify searchable, custom data for each OpsItem. You can also view
automatically-generated summary reports about OpsItems by status and source.
Resource Groups

AWS Resource Groups: An AWS resource is an entity you can work with in AWS, such as Systems
Manager SSM documents, patch baselines, maintenance windows, parameters, and managed
instances; an Amazon Elastic Compute Cloud (Amazon EC2) instance; an Amazon Elastic Block
Store (Amazon EBS) volume; a security group; or an Amazon Virtual Private Cloud (VPC). A resource
group is a collection of AWS resources that are all in the same AWS Region, and that match criteria
provided in a query. You build queries in the Resource Groups console, or pass them as arguments to
Resource Groups commands in the AWS CLI. With Resource Groups, you can create a custom console
that organizes and consolidates information based on criteria that you specify in tags. You can also
use groups as the basis for viewing monitoring and configuration insights in AWS Systems Manager.
Trusted Advisor & Personal Health Dashboard (PHD)

Systems Manager hosts two online tools to help you provision your resources and monitor your
account for health events. Trusted Advisor is an online tool that provides you real time guidance to
help you provision your resources following AWS best practices. For more information, see Trusted
Advisor.

The AWS Personal Health Dashboard provides information about AWS Health events that can
affect your account. The information is presented in two ways: a dashboard that shows recent and
upcoming events organized by category, and a full event log that shows all events from the past 90
days. For more information, see Getting Started with the AWS Personal Health Dashboard.

Actions & Change

Systems Manager provides the following capabilities for taking action against or changing your AWS
resources.

4
 AWS Systems Manager User Guide
Instances & Nodes

Automation

Use Systems Manager Automation (p. 142) to automate common maintenance and deployment
tasks. You can use Automation to create and update Amazon Machine Images, apply driver and
agent updates, reset passwords on Windows instance, reset SSH keys on Linux instances, and apply
OS patches or application updates.
Maintenance Windows

Use Maintenance Windows (p. 444) to set up recurring schedules for managed instances to run
administrative tasks like installing patches and updates without interrupting business-critical
operations.

Instances & Nodes

Systems Manager provides capabilities for managing your Amazon EC2 instances, your on-premises
servers and virtual machines (VMs) in your hybrid environment, and other types of AWS resources
(nodes).

Configuration Compliance

Use Systems Manager Configuration Compliance (p. 504) to scan your fleet of managed instances
for patch compliance and configuration inconsistencies. You can collect and aggregate data
from multiple AWS accounts and Regions, and then drill down into specific resources that aren’t
compliant. By default, Configuration Compliance displays compliance data about Patch Manager
patching and State Manager associations. You can also customize the service and create your own
compliance types based on your IT or business requirements.
Inventory Management

Inventory Manager (p. 512) automates the process of collecting software inventory from managed
instances. You can use Inventory Manager to gather metadata about applications, files, components,
patches, and more on your managed instances.
Managed Instances

A managed instance (p. 23) is any Amazon EC2 instance or on-premises machine–a server or a
virtual machine (VM)–in your hybrid environment that is configured for Systems Manager. To set
up managed instances, you need to install SSM Agent on your machines (if not installed by default)
and configure AWS Identity and Access Management (IAM) permissions. On-premises machines also
require an activation code.
Activations

To set up servers and VMs in your hybrid environment as managed instances, you need to create a
managed-instance activation (p. 41). After you complete the activation, you receive an activation
code and ID. This code/ID combination functions like an Amazon EC2 access ID and secret key to
provide secure access to the Systems Manager service from your managed instances.
Session Manager

Use Session Manager (p. 567) to manage your Amazon EC2 instances through an interactive one-
click browser-based shell or through the AWS CLI. Session Manager provides secure and auditable
instance management without the need to open inbound ports, maintain bastion hosts, or manage
SSH keys. Session Manager also makes it easy to comply with corporate policies that require
controlled access to instances, strict security practices, and fully auditable logs with instance access
details, while still providing end users with simple one-click cross-platform access to your Amazon
EC2 instances.
Run Command

Use Systems Manager Run Command (p. 613) to remotely and securely manage the configuration
of your managed instances at scale. Use Run Command to perform on-demand changes like

5
 AWS Systems Manager User Guide
Shared Resources

updating applications or running Linux shell scripts and Windows PowerShell commands on a target
set of dozens or hundreds of instances.
State Management

Use Systems Manager State Manager (p. 645) to automate the process of keeping your managed
instances in a defined state. You can use State Manager to ensure that your instances are
bootstrapped with specific software at startup, joined to a Windows domain (Windows instances
only), or patched with specific software updates.
Patch Management

Use Patch Manager (p. 683) to automate the process of patching your managed instances with
both security related and other types of updates. You can use Patch Manager to apply patches for
both operating systems and applications. (On Windows Server, application support is limited to
updates for Microsoft applications.) This capability enables you to scan instances for missing patches
and apply missing patches individually or to large groups of instances by using Amazon EC2 instance
tags. Patch Manager uses patch baselines, which can include rules for auto-approving patches within
days of their release, as well as a list of approved and rejected patches. You can install security
patches on a regular basis by scheduling patching to run as a Systems Manager maintenance window
task. For Linux operating systems, you can define the repositories that should be used for patching
operations as part of your patch baseline. This allows you to ensure that updates are installed only
from trusted repositories regardless of what repositories are configured on the instance. For Linux,
you also have the ability to update any package on the instance, not just those that are classified as
operating system security updates. For Windows Server, you can also use Patch Manager to update
supported Microsoft applications.
Distributor

Use Distributor (p. 749) to create and deploy packages to managed instances. Distributor
lets you package your own software—or find AWS-provided agent software packages, such as
AmazonCloudWatchAgent—to install on AWS Systems Manager managed instances. Distributor
publishes resources, such as software packages, to AWS Systems Manager managed instances.

Shared Resources
Systems Manager uses the following shared resources for managing and configuring your AWS resources.

Systems Manager Documents

A Systems Manager document (p. 775) (SSM document) defines the actions that Systems Manager
performs. SSM document types include Command documents, which are used by State Manager
and Run Command, and Automation documents, which are used by Systems Manager Automation.
Systems Manager includes more dozens of pre-configured documents that you can use by specifying
parameters at runtime. Documents can be expressed in JSON or YAML, and include steps and
parameters that you specify.
Parameter Store

Parameter Store (p. 825) provides secure, hierarchical storage for configuration data and secrets
management. You can store data such as passwords, database strings, and license codes as
parameter values. You can store values as plain text or encrypted data. You can then reference
values by using the unique name you specified when you created the parameter.

How Systems Manager Works

Diagram 1 below shows a general example of the different processes that Systems Manager performs
when executing an action like sending a command to your fleet of servers or performing an inventory

6
 AWS Systems Manager User Guide
How It Works

of the applications running on your on-premises servers. Each Systems Manager capability, for example
Run Command and Maintenance Windows, uses a similar process of set up, execution, processing, and
reporting.

1. Configure Systems Manager: Use the Systems Manager console, SDK, AWS CLI, or AWS Tools for
Windows PowerShell to configure, schedule, automate, and run actions that you want to perform on
your AWS resources.
2. Verification and processing: Systems Manager verifies the configurations, including permissions, and
sends requests to the SSM Agent running on your instances or servers in your hybrid environment.
SSM Agent performs the specified configuration changes.
3. Reporting: SSM Agent reports the status of the configuration changes and actions to Systems
Manager in the AWS cloud. Systems Manager then sends the status to the user and various AWS
services, if configured.

Diagram 1: General Example of Systems Manager Process Flow

7
AWS Systems Manager User Guide
How It Works

8
 AWS Systems Manager User Guide
About SSM Agent

About SSM Agent

AWS Systems Manager Agent (SSM Agent) is Amazon software that can be installed and configured on
an Amazon EC2 instance, an on-premises server, or a virtual machine (VM). SSM Agent makes it possible
for Systems Manager to update, manage, and configure these resources. The agent processes requests
from the Systems Manager service in the AWS Cloud, and then runs them as specified in the request.
SSM Agent then sends status and execution information back to the Systems Manager service by using
the Amazon Message Delivery Service (service prefix: ec2messages).

SSM Agent must be installed on each instance you want to use with Systems Manager. SSM Agent is
preinstalled, by default, on instances created from the following Amazon Machine Images (AMIs):

• Windows Server 2003-2012 R2 AMIs published in November 2016 or later

• Windows Server 2016 and 2019
• Amazon Linux
• Amazon Linux 2
• Ubuntu Server 16.04
• Ubuntu Server 18.04

On other AMIs, and on on-premises servers and virtual machines for your hybrid environment, you must
install the agent manually, as described in the table below.
Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Operating System Type SSM Agent Installation

Windows Windows AMIs published before November 2016

use the EC2Config service to process requests and
configure instances.

Unless you have a specific reason for using the

EC2Config service or an earlier version of SSM
Agent to process Systems Manager requests, we
recommend that you download and install the
latest version of the SSM Agent to each of your
Amazon EC2 instances and managed instances in
your hybrid environment. For more information,
see Installing and Configuring SSM Agent on
Windows Instances (p. 65).

Linux SSM Agent is installed by default on Amazon

Linux, Amazon Linux 2, Ubuntu Server 16.04, and
Ubuntu Server 18.04 LTS base EC2 AMIs. You must
manually install SSM Agent on other versions of
Amazon EC2 for Linux, including non-base images
like Amazon ECS-Optimized AMIs. For more
information, see Installing and Configuring SSM
Agent on Amazon EC2 Linux Instances (p. 68).

9
 AWS Systems Manager User Guide
Supported Operating Systems

Operating System Type SSM Agent Installation

On-premises servers and VMs SSM Agent must be installed manually on on-
premises servers and virtual machines (VMs) you
want to use in a hybrid environment. The SSM
Agent download and installation process for these
machines is different than the process used for
Amazon EC2 instances. For more information, see
the following topics:

• Install SSM Agent for a Hybrid Environment

(Windows) (p. 48)
• Install SSM Agent for a Hybrid Environment
(Linux) (p. 50)

Supported Operating Systems

Your Amazon EC2 instances, on-premises servers, and virtual machines (VMs) must be running one of the
following operating systems in order to be used with AWS Systems Manager.

Operating System Types

• Windows Server (p. 10)
• Linux (p. 10)
• Raspbian (p. 12)

Windows Server
Version Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

2003 and 2003 R2 ✓ ✓  

2008 ✓ ✓  

2008 R2   ✓  

2012 and 2012 R2   ✓  

2016   ✓  

2019   ✓  

Linux
Amazon Linux

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

2012.03 – 2018.03 ✓ ✓  

Note
Beginning with version 2015.03, Amazon Linux is released in Intel 64-bit (x86_64) versions only.

10
 AWS Systems Manager User Guide
Linux

Amazon Linux 2

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

2.0 and all later   ✓ ✓

versions

Ubuntu Server

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

12.04 LTS and 14.04 ✓ ✓  

LTS

16.04 LTS and 18.04   ✓ ✓

LTS

Debian Server

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

Jessie (8)   ✓  

Stretch (9)   ✓  

Red Hat Enterprise Linux (RHEL)

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

6.0   ✓  

6.5 ✓ ✓  

6.9 ✓ ✓  

7.0   ✓  

7.4   ✓  

7.5   ✓  

7.6   ✓ ✓

CentOS

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

6.0 ✓    

6.3 and later 6.x ✓ ✓  

versions

7.1 and later 7.x   ✓ ✓

versions

11
 AWS Systems Manager User Guide
Raspbian

SUSE Linux Enterprise Server (SLES)

Versions Intel 32-bit (x86) Intel 64-bit (x86_64) ARM 64-bit (arm64)

12 and later 12.x   ✓  

versions

Raspbian
Version ARM 32-bit (arm)

Jessie ✓

Stretch ✓

Accessing Systems Manager

You can work with Systems Manager in any of the following ways:

Systems Manager Console

The AWS Systems Manager console is a browser-based interface to access and use Systems Manager.
AWS Command Line Tools

The AWS command line tools let you issue commands at your system's command line to perform
Systems Manager and other AWS tasks, and is supported on Windows, Linux, and macOS. Using
the CLI can be faster and more convenient than using the console. The command line tools also are
useful if you want to build scripts that perform AWS tasks.

AWS provides two sets of command line tools: the AWS Command Line Interface (AWS CLI) and the
AWS Tools for Windows PowerShell. For information about installing and using the AWS CLI, see the
AWS Command Line Interface User Guide. For information about installing and using the Tools for
Windows PowerShell, see the AWS Tools for Windows PowerShell User Guide.
Note
On your Windows Server instances, Windows PowerShell 3.0 or later is required to run
certain SSM documents (for example, the AWS-ApplyPatchBaseline document). Verify
that your Windows instances are running Windows Management Framework 3.0 or later.
The framework includes PowerShell.
AWS SDKs

AWS provides software development kits (SDKs) that consist of libraries and sample code for various
programming languages and platforms (for example, Java, Python, Ruby, .NET, iOS and Android,
and others). The SDKs provide a convenient way to create programmatic access to Systems Manager.
For information about the AWS SDKs, including how to download and install them, see Tools for
Amazon Web Services.

Systems Manager Prerequisites

The prerequisites for using AWS Systems Manager to manage your Amazon EC2 instances, on-premises
servers, and virtual machines (VMs) are covered step by step in the Setting Up chapters of this user guide:

12
 AWS Systems Manager User Guide
Prerequisites

• Setting Up AWS Systems Manager (p. 23)

• Setting Up AWS Systems Manager for Hybrid Environments (p. 41)

This topic provides an overview of these prerequisites.

To complete prerequisites for using Systems Manager

1. Create an AWS account and configure the required IAM roles.

2. Verify that Systems Manager is supported in the AWS Regions where you want to use the service.
3. Verify that you are using supported machine types that run a supported operating system.
4. For EC2 instances, create an IAM instance profile and attach it to your machines.
5. For on-premises servers and VMs, create an IAM service role for a hybrid environment.
6. Verify that you are allowing HTTPS (port 443) outbound traffic to the Systems Manager endpoints.
7. (Recommended) Create a VPC endpoint in Amazon Virtual Private Cloud to use with Systems
Manager.
8. On on-premises servers, VMs, and EC2 instances created from AMIs that are not supplied by AWS,
install a Transport Layer Security (TLS) certificate.
9. For on-premises servers and VMs, register the machines with Systems Manager through the
managed instance activation process.
10. Install or verify installation of SSM Agent on each of your managed instances.

Integration with IAM and Amazon EC2

User access to Systems Manager, its capabilities, and its resources are controlled through policies
that you use or create in AWS Identity and Access Management (IAM). If you plan to use computing
resources provided by AWS, and not only on-premises servers and virtual machines (VMs), you also need
to understand Amazon Elastic Compute Cloud (Amazon EC2) before you set up Systems Manager for
your organization. Understanding how these services work is essential to successfully set up Systems
Manager.

For more information about Amazon EC2, see the following:

• Amazon Elastic Compute Cloud (Amazon EC2)

• Getting Started with Amazon EC2 Linux Instances
• Getting Started with Amazon EC2 Windows Instances
• What is Amazon EC2? (Linux)
• What is Amazon EC2? (Windows)

For more information about IAM, see the following:

• AWS Identity and Access Management (IAM)

• Getting Started with IAM
• What is IAM?

13
 AWS Systems Manager User Guide
Permissions Roles

AWS Systems Manager Quick Setup

Use AWS Systems Manager Quick Setup to quickly configure required security roles and commonly used
Systems Manager capabilities on your Amazon EC2 instances. These capabilities help you manage and
monitor the health of your instances while providing the minimum required permissions to get started.
Specifically, Quick Setup helps you configure the following components on the instances you choose or
target by using tags:

• AWS Identity and Access Management (IAM) instance profile roles for Systems Manager.
• A scheduled, bi-weekly update of SSM Agent.
• A scheduled collection of Inventory metadata every 30 minutes.
• A daily scan of your instances to identify missing patches.
• A one-time installation and configuration of the Amazon CloudWatch agent.
• A scheduled, monthly update of the CloudWatch agent.

To access Quick Setup, choose Quick Setup in the navigation pane of the Systems Manager console. You
can also access Quick Setup by choosing AWS Systems Manager at the top of the navigation pane, and
then choosing Get Started with Systems Manager as shown.

Note
You can change Quick Setup configurations at any time. Before you do, we recommend that
you learn how to change configurations by using the Quick Setup Results page. For more
information, see Working with Quick Setup Results (p. 18).

Permissions Roles
By default, Systems Manager doesn't have permission to communicate with or perform actions on your
instances. You must grant access by using an AWS Identity and Access Management (IAM) instance
profile and an IAM service role (or assume role). An instance profile is a container that passes IAM
role information to an Amazon EC2 instance at launch. A service role enables Systems Manager to
run commands on your instances. For more information about instance profiles, see Using Instance
Profiles in the IAM User Guide. For more information about service roles, see Creating a Role to Delegate
Permissions to an AWS Service.

You can choose to have Quick Setup create and configure these roles for you by choosing Use the
default role. If you select an existing role, then that role must include IAM policies with, at minimum,

14
 AWS Systems Manager User Guide
Details about the Default Instance Profile

the permissions described in this topic. If you select existing roles and they don't have these permissions,
then Quick Setup may fail to configure one or more selected components, or those components may fail
to run correctly.
Note
Quick Setup doesn't override instance profiles that already exist on your instances.

Details about the Default Instance Profile

In the Instance profile role section, if you choose Use the default role, then Quick Setup creates a new
IAM instance profile that uses the AmazonSSMManagedInstanceCore policy and one additional policy.
The AmazonSSMManagedInstanceCore policy enables Systems Manager to perform the following
actions on your instances.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeAssociation",
"ssm:GetDeployablePatchSnapshotForInstance",
"ssm:GetDocument",
"ssm:DescribeDocument",
"ssm:GetManifest",
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:ListAssociations",
"ssm:ListInstanceAssociations",
"ssm:PutInventory",
"ssm:PutComplianceItems",
"ssm:PutConfigurePackageResult",
"ssm:UpdateAssociationStatus",
"ssm:UpdateInstanceAssociationStatus",
"ssm:UpdateInstanceInformation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2messages:AcknowledgeMessage",
"ec2messages:DeleteMessage",
"ec2messages:FailMessage",
"ec2messages:GetEndpoint",
"ec2messages:GetMessages",
"ec2messages:SendReply"
],
"Resource": "*"
}
]
}

15
 AWS Systems Manager User Guide
Details about the Service Role

Note
For information about the ssmmessages* and ec2messages* actions, see Reference:
ec2messages, ssmmessages, and Other API Calls (p. 941).

Quick Setup also adds the following policy to the instance profile. This policy enables trusted
communications between the Systems Manager service in the cloud and your Amazon EC2 instances.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":"ec2.amazonaws.com"
},
"Action":"sts:AssumeRole"
}
]
}

Details about the Service Role

In the Systems Manager service role section, if you choose Use the default role, then Quick Setup
creates a new IAM service role that includes the following policies. The first policy enables Systems
Manager to perform the following actions on your instances.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:CreateInstanceProfile",
"iam:ListInstanceProfilesForRole",
"iam:PassRole",
"ec2:DescribeIamInstanceProfileAssociations",
"iam:GetInstanceProfile",
"ec2:DisassociateIamInstanceProfile",
"ec2:AssociateIamInstanceProfile",
"iam:AddRoleToInstanceProfile"
],
"Resource": "*"
}
]
}

The following policy enables Systems Manager to perform the actions in the previous policy on your
behalf. Systems Manager assumes your role to perform the actions.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Action":"sts:AssumeRole"
}
]
}

16
 AWS Systems Manager User Guide
Update Systems Manager (SSM) Agent

Note
Configuring an instance with an instance profile for Systems Manager does not give a user
access to run commands or use Systems Manager capabilities on that instance. Your IAM user,
group, or role must be configured with a separate permissions policy that enables you to
perform actions on your instances by using Systems Manager. For more information, see Setting
Up AWS Systems Manager (p. 23).

Update Systems Manager (SSM) Agent

SSM Agent is Amazon software that processes requests from the Systems Manager service in the AWS
Cloud, and then runs them on your instance as specified in the request. SSM Agent is preinstalled, by
default, on the following Amazon Machine Images (AMIs):

• Windows Server 2003-2012 R2 AMIs published in November 2016 or later

• Windows Server 2016 and 2019
• Amazon Linux
• Amazon Linux 2
• Ubuntu Server 16.04
• Ubuntu Server 18.04

If you enable this option, then Systems Manager automatically checks every two weeks for a new version
of the agent. If there is a new version, then Systems Manager automatically updates the agent on your
instance to the latest released version. We encourage you to choose this option to ensure that your
instances are always running the most up-to-date version of SSM Agent. For more information about
SSM Agent, including information about how to manually install the agent, see Working with SSM
Agent (p. 64).

Collect Inventory from Your Instances

AWS Systems Manager Inventory provides visibility into your computing environment. You can use
Inventory to collect metadata from your managed instances. You can store this metadata in a central
Amazon Simple Storage Service (Amazon S3) bucket. Then use built-in tools to query the data and
quickly determine which instances are running the software and configurations required by your
software policy, and which instances need to be updated. Quick Setup configures collection of the
following types of metadata:

• AWS components: EC2 driver, agents, versions, and more.

• Applications: Application names, publishers, versions, and more.
• Instance details: System name, operating system (OS) name, OS version, last boot, DNS, domain, work
group, OS architecture, and more.
• Network configuration: IP address, MAC address, DNS, gateway, subnet mask, and more.
• Services: Name, display name, status, dependent services, service type, start type, and more (Windows
instances only).
• Windows roles: Name, display name, path, feature type, installed state, and more (Windows instances
only).
• Windows updates: Hotfix ID, installed by, installed date, and more (Windows instances only).

You can configure Systems Manager Inventory to collect the following additional types of metadata from
your instances. For more information, see AWS Systems Manager Inventory (p. 512).

17
 AWS Systems Manager User Guide
Scan Instances for Missing Patches Daily

• Custom inventory: Metadata that was assigned to a managed instance as described in Working with
Custom Inventory (p. 541).
• Files: Name, size, version, installed date, modification time, last accessed time, and more.
• Tags: Tags assigned to your instances.
• Windows Registry: Registry key path, value name, value type, and value.

Important
A global Inventory configuration is created from the one-click configuration option on the
Inventory page and targets all instances in your AWS account. If you already have a global
Inventory configuration enabled on your instances, then enabling Inventory collection in Quick
Setup creates another schedule to collect Inventory data for the specified or targeted instances.
There is no conflict. However, if you already have a non-global Inventory configuration enabled
on some of your instances, then the configuration you created earlier will fail. Inventory
collection does not support more than one specific configuration per instance. To resolve this
issue, either deploy a global inventory configuration or delete the conflict configuration.

Scan Instances for Missing Patches Daily

If you enable this option in Quick Setup, then Systems Manager uses Patch Manager to scan your
instances each day and generate a simple report in the Compliance page. The report shows how many
instances are patch-compliant according to the default patch baseline. The report includes a list of each
instance and its compliance status. You can navigate this list to see details about noncompliant instances.
For more information about patching operations and patch baselines, see AWS Systems Manager Patch
Manager (p. 683). To view compliance information, see the Systems Manager Compliance page.

Install and Configure the CloudWatch Agent

Amazon CloudWatch provides data and actionable insights to monitor your applications, understand
and respond to system-wide performance changes, optimize resource utilization, and get a unified
view of operational health. The CloudWatch agent collects metrics and log files from your instances
and consolidates this information so that you can quickly determine the health of your instances. For
more information, see Collecting Metrics and Logs from Amazon EC2 Instances and On-Premises Servers
with the CloudWatch Agent. There may be added cost. For more information, see Amazon CloudWatch
pricing.

Update the CloudWatch Agent Once Every Four

Weeks
If you enable this option, then Systems Manager automatically checks every four weeks for a new version
of the CloudWatch agent. If there is a new version, then Systems Manager automatically updates the
agent on your instance to the latest released version. We encourage you to choose this option to ensure
that your instances are always running the most up-to-date version of the CloudWatch agent.

Working with Quick Setup Results

Systems Manager displays the results of Quick Setup in a separate card for each option you selected.

18
 AWS Systems Manager User Guide
Working with Quick Setup Results

For each option you selected, Systems Manager creates and immediately runs a State Manager
association. The Configuration status field shows Success when the association successfully runs on
all selected or targeted instances. If one association fails to run, Configuration status is Failed. If an
association is processing, Configuration status is Pending. To update Configuration status for Pending
items, refresh your browser.
Note
The Inventory collection option can take up to 10 minutes to complete, even if you only
selected a few instances.

A Configuration status of Not configured, means you didn't choose the option in Quick Setup. If you see
this status for Managed instances, it means that you didn't choose a role in the Role selection list. You
can run Quick Setup again, as described in this topic, and choose a role.

To edit the association for a Quick Setup option, choose the Edit button in the option card. If you
edit the association, don't choose a different SSM Document in the Edit Association page. If you
choose a different SSM Document, the option becomes unavailable in Quick Setup. Change only the
parameters and targets of the association. When you save your changes to the association, State
Manager automatically runs the association.

19
 AWS Systems Manager User Guide
Troubleshooting Quick Setup Results

Troubleshooting Quick Setup Results

If a Quick Setup card shows Not configured, you might have missed a selection on the Quick Setup
page. As a first step in troubleshooting this problem, choose the Edit all button at the top of the Quick
Setup results page and review your selections. If you missed one or more, you can choose them and then
choose Reset to configure those options.

If you still see a problem with one or more Quick Setup results cards, then use the following procedure to
troubleshoot the issue.

To troubleshoot a failed Quick Setup configuration

1. In the Quick Setup results page, choose View Details in the card with a Configuration status of
Failed.

2. In the Association ID page, choose the Execution history tab.

3. Under Execution ID, choose the association execution that failed.

4. The Association execution targets page lists all of the instances where the association ran. Choose
the Output button for an execution that failed to run.

20
 AWS Systems Manager User Guide
Running Quick Setup Again

5. In the Output page, choose Step - Output to view the error message for that step in the command
execution. Each step can display a different error message. Review the error messages for all steps to
help troubleshoot the issue.

If viewing the step output doesn't help troubleshoot the problem, then you can recreate the association
to see if the problem persists. To recreate the association, you must first delete all associations that
already exist for the Quick Setup option. You can delete an association by using the Delete button in
the Quick Setup results card. You can also delete the association by choosing State Manager in the
navigation pane. After you delete the association, run Quick Setup again to see if the problem persists.

Running Quick Setup Again

You can run Quick Setup again by choosing the Edit all button on the Quick Setup results page. You
can choose or clear options. If you clear an option, Systems Manager doesn't delete the association. For
example, if you previously selected the Collect inventory from your instances every 30 minutes option,
and you clear the option when you run Quick Setup again, the original association still exists. You must
either delete the association from the Quick Setup results page or from the State Manager page.

21
 AWS Systems Manager User Guide
Running Quick Setup Again

Important
If you want to run Quick Setup on new instances, we recommend that you choose the new
instances and also choose all of the instances on which you previously ran Quick Setup.
By choosing all of the instances on which you previously ran Quick Setup, you synchronize
the association executions for all of the instances. This synchronizes status and compliance
reporting. We also recommend that you target instances by using tags. New instances with
the specified tags are automatically added to Quick Setup associations. This means that they
automatically display status in the Quick Setup results and in the Compliance page.

22
 AWS Systems Manager User Guide
Step 1: Sign Up for AWS

Setting Up AWS Systems Manager

This section describes the tasks that account and system administrators perform to set up AWS Systems
Manager for their organizations. After these steps are complete, users in the organization can use
Systems Manager to configure and manage the Amazon Elastic Compute Cloud (Amazon EC2) instances
in their account.

If you plan to use Systems Manager to manage and configure your own on-premises servers and virtual
machines (VMs) in what is called a hybrid environment, follow the setup steps in Setting Up AWS Systems
Manager for Hybrid Environments (p. 41). If you plan to use both Amazon EC2 instances and your own
computing resources in a hybrid environment, follow the steps here first. This section presents steps in
the best order for configuring the roles, users, permissions, and initial resources to use in your Systems
Manager operations.

If you already use other AWS services, you have completed some of these steps. However, other steps are
specific to Systems Manager. Therefore, we recommend reviewing this entire section to ensure that you
are ready to use all Systems Manager capabilities.
Note
You can use Systems Manager Quick Setup to quickly configure an AWS Identity and Access
Management (IAM) instance profile on all instances in your AWS account. Quick Setup can also
create an assume role, which enables Systems Manager to securely run commands on your
instances on your behalf. By using Quick Setup, you can skip step 4 and 5 in this section. For
more information, see AWS Systems Manager Quick Setup (p. 14).

Contents
• Step 1: Sign Up for AWS (p. 23)
• Step 2: Create an Admin IAM User for AWS (p. 24)
• Step 3: Create Non-Admin IAM Users and Groups for Systems Manager (p. 25)
• Step 4: Create an IAM Instance Profile for Systems Manager (p. 29)
• Step 5: Attach an IAM Instance Profile to an Amazon EC2 Instance (p. 34)
• Step 6: (Optional) Create a Virtual Private Cloud Endpoint (p. 36)
• Step 7: (Optional) Create Systems Manager Service Roles (p. 38)
• Step 8: (Optional) Set Up Integrations with Other AWS Services (p. 40)

Step 1: Sign Up for AWS

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.
2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a verification code on the
phone keypad.

Continue to Step 2: Create an Admin IAM User for AWS (p. 24).

23
 AWS Systems Manager User Guide
Step 2: Create an Admin IAM User for AWS

Step 2: Create an Admin IAM User for AWS

When you first create an AWS account, you begin with a single sign-in identity that has complete access
to all AWS services and resources in the account. This identity is called the AWS account root user and
is accessed by signing in with the email address and password that you used to create the account. We
strongly recommend that you do not use the root user for your everyday tasks, even the administrative
ones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Then
securely lock away the root user credentials and use them to perform only a few account and service
management tasks.

In this procedure, you use the AWS account root user to create your first user in AWS Identity and Access
Management (IAM). You add this IAM user to an Administrators group, to ensure that you have access
to all services and their resources in your account. The next time that you access your AWS account, you
should sign in with the credentials for this IAM user.

To create an IAM user with limited permissions, see Step 3: Create Non-Admin IAM Users and Groups for
Systems Manager (p. 25).

To create an administrator user for yourself and add the user to an administrators group
(console)

1. Use your AWS account email address and password to sign in as the AWS account root user to the
IAM console at https://console.aws.amazon.com/iam/.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user below and securely lock away the root user credentials. Sign in as the root user
only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user.
3. For User name, enter Administrator.
4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box.
5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new
user to reset their password after they sign in.
6. Choose Next: Permissions.
7. Under Set permissions, choose Add user to group.
8. Choose Create group.
9. In the Create group dialog box, for Group name enter Administrators.
10. Choose Filter policies, and then select AWS managed -job function to filter the table contents.
11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note
You must activate IAM user and role access to Billing before you can use the
AdministratorAccess permissions to access the AWS Billing and Cost Management
console. To do this, follow the instructions in step 1 of the tutorial about delegating access
to the billing console.
12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
13. Choose Next: Tags.
14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information
about using tags in IAM, see Tagging IAM Entities in the IAM User Guide.
15. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.

24
 AWS Systems Manager User Guide
Step 3: Create Non-Admin IAM Users
and Groups for Systems Manager

You can use this same process to create more groups and users and to give your users access to your AWS
account resources. To learn about using policies that restrict user permissions to specific AWS resources,
see Access Management and Example Policies.

Continue to Step 3: Create Non-Admin IAM Users and Groups for Systems Manager (p. 25).

Step 3: Create Non-Admin IAM Users and Groups

for Systems Manager
Users in the administrators group for an account have access to all AWS services and resources in that
account. This section describes how to create users with permissions that are limited to AWS Systems
Manager.

The following Systems Manager capabilities may have additional or alternative procedures for granting
user access:

• Session Manager - See Control User Session Access to Instances (p. 579).
• Distributor - See Control User Access to Packages (p. 753).
• Maintenance Windows - See Controlling Access to Maintenance Windows (p. 445) (see the
instructions for assigning the IAM PassRole policy to an IAM user or group).

For more information about using IAM policies to control user access to Systems Manager capabilities
and resources, see Using Identity-based Policies (IAM Policies) for AWS Systems Manager (p. 914).

For information about how to change permissions for an IAM user account, group, or role, see Changing
Permissions for an IAM User in the IAM User Guide.

Topics
• Task 1: Create Policies for Tag Editor and Resource Groups (p. 25)
• Task 2: Create User Groups (p. 26)
• Task 3: Create Users and Assign Permissions (p. 27)

Task 1: Create Policies for Tag Editor and Resource

Groups
You can use resource groups to organize your AWS resources. Resource groups make it easier to manage
and automate tasks on large numbers of resources across AWS at one time.

Tags are properties of a resource, so they are shared across your entire account. Users in a department
or specialized group can draw from a common vocabulary (tags) to create resource groups that are
meaningful to their roles and responsibilities. Having a common pool of tags also means that when users
share a resource group, they don't have to worry about missing or conflicting tag information.

AWS resource groups are managed in the AWS Resource Groups service. It is optional to provide the users
and user groups in your account access to this service and its Tag Editor, but we recommend it for more
effective management operations.

For more information about the AWS Resource Groups service and Tag Editor, see the AWS Resource
Groups User Guide.

The following procedure shows how to create a custom policy that allows your account's users to access
Resource Groups and Tag Editor. You need to complete this procedure only one time. In later topics, you
grant these permissions by attaching the policy to users and user groups in your account.

25
 AWS Systems Manager User Guide
Task 2: Create User Groups

To create a policy for Tag Editor and Resource Groups

1. Use your AWS account ID or account alias, and the credentials for your admin IAM user, to sign in to
the IAM console.
2. In the navigation pane of the console, choose Policies, and then choose Create policy.
3. Choose the JSON tab and paste the following policy:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"resource-groups:*",
"cloudformation:DescribeStackResources",
"cloudformation:ListStackResources",
"tag:GetResources",
"tag:TagResources",
"tag:UntagResources",
"tag:getTagKeys",
"tag:getTagValues"
],
"Resource": "*"
}
]
}

This policy allows all actions for Tag Editor and Resource Groups.
4. Choose Review policy.
5. On the Review policy page, for Name, enter SSMTagEditorAndResourceGroupAccess or
another name that you prefer, and then choose Create policy.

Continue to Task 2: Create User Groups (p. 26).

Task 2: Create User Groups

You can create a user group for each policy and assign users to a group rather than attaching individual
policies to each user.

You can create multiple user groups with different permission sets by omitting recommended or optional
policies. You can also create custom IAM policies to grant any combination of permissions for a user. For
example, you can grant a user group permission to use only the Session Manager capability in Systems
Manager, as described in Control User Session Access to Instances (p. 579).

For additional examples of custom IAM policies for Systems Manager, see Customer Managed Policy
Examples (p. 916).

For comprehensive information about using IAM policies for Systems Manager access, see Authentication
and Access Control for AWS Systems Manager (p. 906).

To create a user group

Use the following procedure to create a user group for your Systems Manager users. You can repeat this
procedure to create additional user groups with different sets of permissions.

1. In the navigation pane of the IAM console, choose Groups, and then choose Create New Group.
2. On the Set Group Name page, enter a name for the group, such as SSMUserGroup or another name
that you prefer.

26
 AWS Systems Manager User Guide
Task 3: Create Users and Assign Permissions

3. Choose Next Step.

4. On the Attach Policy page, for Filter, enter SSM.
5. In the policy list, do the following:

• If you want to provide users with permission to use Resource Groups and the Tag Editor, choose
the SSMTagEditorAndResourceGroupAccess policy that you created in the procedure Task 1:
Create Policies for Tag Editor and Resource Groups (p. 25). If you gave the policy a different
name, choose that name instead.
• To provide users in this group with full access to the Systems Manager console, select the box next
to AmazonSSMFullAccess.

-or-

If you want users in this group only to view Systems Manager data, and not create or update
resources, select the box beside AmazonSSMReadOnlyAccess.
• To provide users with access to the Built-In Insights and Dashboard by CloudWatch pages in the
Systems Manager console, select the boxes next to these managed policies:
• AWSHealthFullAccess

This policy grants full access to the AWS Health APIs and Notifications and the Personal Health
Dashboard. It also provides access to portions of the Built-In Insights Dashboard in the Systems
Manager console.
• AWSConfigUserAccess

This policy provides read-only access to use AWS Config, including searching by tags on
resources, and reading all tags> It also provides access to portions of the Built-In Insights
Dashboard in the Systems Manager console.
• CloudWatchReadOnlyAccess

This policy provides read-only access to CloudWatch, which is needed to view information on
the Dashboard by CloudWatch in the Systems Manager console.
• Add any other policies that provide permissions you want to grant to this user group.
6. Choose Next Step.
7. On the Review page, verify that the correct policies are added to this group, and then choose Create
Group.

Continue to Task 3: Create Users and Assign Permissions (p. 27).

Task 3: Create Users and Assign Permissions

Create IAM users for the individuals who require access to AWS Systems Manager, and add each user to
the appropriate user group to ensure that they have the right level of permissions.
Note
If your organization has an existing identity system, you might want to create a single sign-on
(SSO) option. SSO gives users access to the AWS Management Console for your account without
requiring them to have an IAM user identity. SSO also eliminates the need for users to sign in
to your organization's site and to AWS separately. For more information, see Enabling Custom
Identity Broker Access to the AWS Console.

Depending on whether the user accounts for this group were already created, use one of the following
procedures:

To create users and add permissions

1. In the navigation pane of the IAM console, choose Users, and then choose Add user.

27
 AWS Systems Manager User Guide
Task 3: Create Users and Assign Permissions

2. For User name, enter the name that the user will use to sign in to AWS Systems Manager.
3. To allow the user access to the AWS API, AWS CLI, AWS SDK, and other development tools, select the
check box next to Programmatic access.

This creates an access key for the new user. You can view or download the access keys when you get
to the Final page.
4. To allow the user access to the AWS Management Console, select the check box next to AWS
Management Console access.

The AWS Management Console provides a web interface where you can manage your compute,
storage, and other cloud resources. Within the AWS Management Console, individual services have
their own console. For example, you can manage your compute resources using the Amazon EC2
console and storage through the Amazon S3 console.

If you choose Custom password, enter an initial password for the user. You can optionally select
Require password reset to force the user to create a new password the next time the user signs in.
5. Choose Next: Permissions.
6. On the Set permissions for user page, choose Add user to group.
7. In the group list, choose the user group to add the user to, and then choose Next: Tags.
8. (Optional) Add one or more tag key-value pairs to organize, track, or control access for this user, and
then choose Next: Review to see the list of group memberships that the new user is joining.
9. Choose Create user.
10. To view the users' access keys (access key IDs and secret access keys), choose Show next to each
password and access key that you want to see. To save the access keys, choose Download .csv and
then save the file to a safe location.
Important
This is your only opportunity to view or download the secret access keys, and you must
provide this information to your users before they can use the AWS API or AWS CLI. Save
the user's new access key ID and secret access key in a safe and secure place. You will not
have access to the secret keys again after this step.
11. Provide each user with his or her credentials. On the final page you can choose Send email next
to each user. Your local mail client opens with a draft that you can customize and send. The email
template includes the following details for each user:

• User name
• URL of the account sign-in page. Use the following example, substituting the correct account ID
number or account alias:

https://AWS-account-ID or alias.signin.aws.amazon.com/console

For more information, see How IAM Users Sign In to AWS in the IAM User Guide.
Important
The user's password is not included in the generated email. You must provide them to the
user in a way that complies with your organization's security guidelines.

To add permissions for an existing user

1. In the IAM console navigation pane, choose Users.

2. Choose the name of the user to add to a group, and then choose Add permission.
3. For Add user to group, select the box next to the group to add the user to, such as SSMUserGroup,
or the name of a different user group that you created.

28
 AWS Systems Manager User Guide
Step 4: Create an IAM Instance Profile for Systems Manager

4. Add any other available permission policies to assign to the user.

5. Choose Next: Review to see the list of group memberships that will be added to the new user.
6. Choose Add permissions.

Continue to Step 4: Create an IAM Instance Profile for Systems Manager (p. 29).

Step 4: Create an IAM Instance Profile for Systems

Manager
By default, AWS Systems Manager doesn't have permission to perform actions on your instances. You
must grant access by using an AWS Identity and Access Management (IAM) instance profile. An instance
profile is a container that passes IAM role information to an Amazon Elastic Compute Cloud (Amazon
EC2) instance at launch. You can create an instance profile for Systems Manager by attaching one or
more IAM policies that define the necessary permissions to a new role or to a role you already created.
Note
You can use Systems Manager Quick Setup to quickly configure an instance profile on all
instances in your AWS account. Quick Setup can also create an assume role, which enables
Systems Manager to securely run commands on your instances on your behalf. By using Quick
Setup, you can skip this step (Step 4) and Step 5. For more information, see AWS Systems
Manager Quick Setup (p. 14).

Note the following details about creating an IAM instance profile:

• If you are configuring servers or virtual machines (VMs) in a hybrid environment for Systems Manager,
you don't need to create an instance profile for them. Instead, you must configure your servers and
VMs to use an IAM service role. For more information, see Create an IAM Service Role for a Hybrid
Environment (p. 42).
• If you change the IAM instance profile, it might take some time for the instance credentials to refresh.
SSM Agent will not process requests until this happens. To speed up the refresh process, you can
restart SSM Agent or restart the instance.

About Policies for a Systems Manager Instance Profile

This section describes the policies you can add to your EC2 instance profile for Systems Manager.
To provide permissions for communication between instances and the Systems Manager API,
we recommend creating custom policies that take into account your system needs and security
requirements. However, as a starting point, you can use one or more of the following policies
to grant permission for Systems Manager to interact with your instances. The first policy,
AmazonSSMManagedInstanceCore, enables an instance to use AWS Systems Manager service core
functionality. Depending on your operations plan, you might need permissions represented in one or
more of the other three policies.

Policy: AmazonSSMManagedInstanceCore

Required permissions.

This AWS managed policy enables an instance to use Systems Manager service core functionality.
Policy: A custom policy for Amazon S3 bucket access

Required permissions in either of the following cases:

• Case 1: You are using a VPC endpoint to privately connect your VPC to supported AWS services
and VPC endpoint services powered by PrivateLink.

29
 AWS Systems Manager User Guide
Task 1: (Optional) Create a Custom S3
Bucket Policy for an Instance Profile

SSM Agent is Amazon software that is installed on your instances and performs Systems Manager
tasks. This agent requires access to specific Amazon-owned S3 buckets. These buckets are publicly
accessible.

In a private VPC endpoint environment, however, you must explicitly provide access to these
buckets:

arn:aws:s3:::patch-baseline-snapshot-region/*
arn:aws:s3:::aws-ssm-region/*

For more information, see Step 6: (Optional) Create a Virtual Private Cloud Endpoint (p. 36),
About Minimum S3 Bucket Permissions for SSM Agent (p. 87), and VPC Endpoints in the
Amazon VPC User Guide.
• Case 2: You plan to use an Amazon S3 bucket that you create as part of your Systems Manager
operations.

Your EC2 instance profile for Systems Manager must grant access to an S3 bucket that you own for
tasks like the following:
• To access scripts you store in the S3 bucket to use in commands you run.
• To store the full output of Run Command commands or Session Manager sessions.
• To access custom patch lists for use when patching your instances.
Note
Saving output log data in an S3 bucket is optional, but we recommend setting it up at the
beginning of your Systems Manager configuration process if you have decided to do so. For
more information, see Create a Bucket in the Amazon Simple Storage Service Getting Started
Guide.
Policy: AmazonSSMDirectoryServiceAccess

Required only if you plan to join EC2 instance for Windows Server to a Microsoft AD directory.

This AWS managed policy allows SSM Agent to access AWS Directory Service on your behalf for
requests to join the domain by the managed instance. For more information, see Seamlessly Join a
Windows EC2 Instance in the AWS Directory Service Administration Guide.
Policy: CloudWatchAgentServerPolicy

Required only if you plan to install and run the CloudWatch agent on your instances to read metric
and log data on an instance and write it to Amazon CloudWatch. These help you monitor, analyze,
and quickly respond to issues or changes to your AWS resources.

Your instance profile needs this policy only if you will use CloudWatch features, such as CloudWatch
Events or CloudWatch Logs. (You can also create a more restrictive policy that, for example, limits
writing access to a specific CloudWatch Logs log stream.)
Note
Using CloudWatch features is optional, but we recommend setting them up at the
beginning of your Systems Manager configuration process if you have decided to use them.
For more information, see the Amazon CloudWatch Events User Guide and the Amazon
CloudWatch Logs User Guide.

Task 1: (Optional) Create a Custom S3 Bucket Policy

for an Instance Profile
Creating a custom S3 bucket policy for your instance profile is required only if you are using a VPC
endpoint or using an S3 bucket of your own in your Systems Manager operations.

30
 AWS Systems Manager User Guide
Task 1: (Optional) Create a Custom S3
Bucket Policy for an Instance Profile

For information about the AWS managed S3 buckets you provide access to in the policy below, see About
Minimum S3 Bucket Permissions for SSM Agent (p. 87).

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Policies, and then choose Create policy.
3. Choose the JSON tab, and replace the default text with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": [
"arn:aws:s3:::aws-ssm-region/*",
"arn:aws:s3:::aws-windows-downloads-region/*",
"arn:aws:s3:::amazon-ssm-region/*",
"arn:aws:s3:::amazon-ssm-packages-region/*",
"arn:aws:s3:::region-birdwatcher-prod/*",
"arn:aws:s3:::patch-baseline-snapshot-region/*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:GetEncryptionConfiguration"
],
"Resource": [
"arn:aws:s3:::my-bucket-name/*",
"arn:aws:s3:::my-bucket-name"
]
}
]
}

1
The first Statement element is required only if you are using a VPC endpoint.

2
The second Statement element is required only if you are using an S3 bucket that you created to
use in your Systems Manager operations.

3
The PutObjectAcl access control list permission is required only if you plan to support cross-
account access to S3 buckets in other accounts.

4
The GetEncryptionConfiguration element is required if your S3 bucket is configured to use
encryption.

5
If your S3 bucket is configured to use encryption, then the S3 bucket root (for example,
arn:aws:s3:::my-bucket-name) must be listed in the Resource section. Your IAM user, group, or role
must be configured with access to the root bucket.
4. If you are using a VPC endpoint in your operations, do the following:

In the first Statement element, replace each region placeholder with the identifier of the AWS
Region this policy will be used in. For example, use us-east-2 for the US East (Ohio) Region. For

31
 AWS Systems Manager User Guide
Task 2: Add Permissions to a Systems
Manager Instance Profile (Console)

a list of supported region values, see the Region column in the AWS Systems Manager Table of
Regions and Endpoints topic in the AWS General Reference.
Important
We recommend that you avoid using wildcard characters (*) in place of specific Regions
in this policy. For example, use arn:aws:s3:::aws-ssm-us-east-2/* and do not
use arn:aws:s3:::aws-ssm-*/*. Using wildcards could provide access to Amazon S3
buckets that you don’t intend to grant access to. If you want to use the instance profile for
more than one Region, we recommend repeating the first Statement element for each
Region.

-or-

If you are not using a VPC endpoint in your operations, you can delete the first Statement element.
5. If you are using an S3 bucket of your own in your Systems Manager operations, do the following:

In the second Statement element, replace my-bucket-name with the name of an S3 bucket in
your account. You will use this bucket for your Systems Manager operations. It provides permission
for objects in the bucket, using "arn:aws:s3:::my-bucket-name/*" as the resource. For more
information about providing permissions for buckets or objects in buckets, see the topic Specifying
Permissions in a Policy in the Amazon Simple Storage Service Developer Guide and the AWS blog post
IAM Policies and Bucket Policies and ACLs! Oh, My! (Controlling Access to S3 Resources).
Note
If you use more than one bucket, provide the ARN for each one. For example, for
permissions on buckets:

"Resource": [
"arn:aws:s3:::my-first-bucket-name/*",
"arn:aws:s3:::my-second-bucket-name/*"
]

-or-

If you are not using an S3 bucket of your own in your Systems Manager operations, you can delete
the second Statement element.
6. Choose Review policy.
7. For Name, enter a name to identify this policy, such as SSMInstanceProfileS3Policy or another
name that you prefer.
8. Choose Create policy.

Task 2: Add Permissions to a Systems Manager

Instance Profile (Console)
Depending on whether you are creating a new role for your instance profile or adding the necessary
permissions to an existing role, use one of the following procedures.

To create an instance profile for Systems Manager managed instances (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create role.
3. Under Select type of trusted entity, choose AWS service.
4. Immediately under Choose the service that will use this role, choose EC2, and then choose Next:
Permissions.

32
 AWS Systems Manager User Guide
Task 2: Add Permissions to a Systems
Manager Instance Profile (Console)

5. On the Attached permissions policy page, do the following:

• Use the Search field to locate the AmazonSSMManagedInstanceCore. Select the box next to its
name.

The console retains your selection even if you search for other policies.
• If you created a custom S3 bucket policy in the previous procedure, Task 1: (Optional) Create a
Custom S3 Bucket Policy for an Instance Profile (p. 30), search for it and select the box next to
its name.
• If you plan to join instances to an Active Directory managed by AWS Directory Service, search for
AmazonSSMDirectoryServiceAccess and select the box next to its name.
• If you plan to use CloudWatch Events or CloudWatch Logs to manage or monitor your instance,
search for CloudWatchAgentServerPolicy and select the box next to its name.
6. Choose Next: Tags.
7. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this role, and
then choose Next: Review.
8. For Role name, enter a name for your new instance profile, such as SSMInstanceProfile or
another name that you prefer.
Note
Make a note of the role name. You will choose this role when you create new instances that
you want to manage by using Systems Manager.
9. (Optional) For Role description, enter a description for this instance profile.
10. Choose Create role. The system returns you to the Roles page.

To add instance profile permissions for Systems Manager to an existing role (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose the existing role you want to associate with
an instance profile for Systems Manager operations.
3. On the Permissions tab, choose Attach policies.
4. On the Attach permission policies page, do the following:

33
 AWS Systems Manager User Guide
Step 5: Attach an IAM Instance
Profile to an Amazon EC2 Instance

• Select the box next to the required AmazonSSMManagedInstanceCore managed policy.

• If you have created a custom S3 bucket policy, select the box next to its name. For information
about custom S3 bucket policies for an instance profile, see Task 1: (Optional) Create a Custom S3
Bucket Policy for an Instance Profile (p. 30).
• If you plan to join instances to an Active Directory managed by AWS Directory Service, select the
box next to AmazonSSMDirectoryServiceAccess.
• If you plan to use CloudWatch Events or CloudWatch Logs to manage or monitor your instance,
select the box next to CloudWatchAgentServerPolicy.
5. Choose Attach policy.

For information about how to update a role to include a trusted entity or further restrict access, see
Modifying a Role in the IAM User Guide.

Continue to Step 5: Attach an IAM Instance Profile to an Amazon EC2 Instance (p. 34).

Step 5: Attach an IAM Instance Profile to an

Amazon EC2 Instance
The procedures in this topic describe how to attach the IAM instance profile for Systems Manager that
you created in the previous topic, Step 4: Create an IAM Instance Profile for Systems Manager (p. 29),
to Amazon EC2 instances. You can attach the instance profile to new Amazon EC2 instances when you
launch them, or to existing Amazon EC2 instances.

SSM Agent requirements for instances

AWS Systems Manager Agent (SSM Agent) is Amazon software that can be installed and configured on
an Amazon EC2 instance, an on-premises server, or a virtual machine (VM). SSM Agent makes it possible
for Systems Manager to update, manage, and configure these resources.

If the Amazon Machine Image (AMI) type you choose in the first procedure doesn't come with SSM Agent
preinstalled, you must manually install the agent on the new instance before it can be used with Systems
Manager. If SSM Agent isn't installed on the existing EC2 instance you choose in the second procedure,
you must manually install the agent on the instance before it can be used with Systems Manager.

SSM Agent is installed by default on the following AMIs:

• Windows Server 2003-2012 R2 AMIs published in November 2016 or later

• Windows Server 2016 and 2019
• Amazon Linux
• Amazon Linux 2
• Ubuntu Server 16.04
• Ubuntu Server 18.04

For information about manually installing SSM Agent on other Linux operating systems, see Installing
and Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68).

TLS certificate requirement for instances

A Transport Layer Security (TLS) certificate must be installed on each managed instance you use with
Systems Manager. These certificates are used to encrypt calls to other AWS services. A TLS certificate
is already installed on each Amazon EC2 instance created from any Amazon Machine Image (AMI).
On instances created from AMIs not supplied by Amazon, and on your own on-premises servers and

34
 AWS Systems Manager User Guide
Launch an Instance that Uses the Systems
Manager Instance Profile (Console)

VMs, you must install the certificate yourself. For more information, see Install a TLS certificate on On-
Premises Servers and VMs (p. 45).

Topics
• Launch an Instance that Uses the Systems Manager Instance Profile (Console) (p. 35)
• Attach the Systems Manager Instance Profile to an Existing Instance (Console) (p. 35)

Launch an Instance that Uses the Systems Manager

Instance Profile (Console)
To launch an instance that uses the Systems Manager instance profile (console)

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. On the navigation bar at the top of the screen, select the AWS Region for the instance.
3. Choose Launch Instance.
4. On the Choose an Amazon Machine Image (AMI) page, locate the AMI for the instance type you
want to create, and then choose Select.
5. Choose the type of instance to launch, such as t2.micro, and then choose Next: Configure Instance
Details.
6. On the Configure Instance Details page, in the IAM role drop-down list, select the instance
profile you created using the procedure in Step 4: Create an IAM Instance Profile for Systems
Manager (p. 29).
7. For other options on the page, make selections that meet your requirements for the instance. For
more information, choose one of the following, depending on your selected operating system type:

• Linux: Launching an Instance Using the Launch Instance Wizard in the Amazon EC2 User Guide for
Linux Instances
• Windows Server: Launching an Instance Using the Launch Instance Wizard in the Amazon EC2
User Guide for Windows Instances
8. Complete the wizard.

If you create other instances that you want to configure using Systems Manager, you must specify the
instance profile for each instance.

Attach the Systems Manager Instance Profile to an

Existing Instance (Console)
1. Sign in to the AWS Management Console and open the Amazon EC2 console at https://
console.aws.amazon.com/ec2/.
2. In the navigation pane, under Instances, choose Instances.
3. Browse to and choose your Amazon EC2 instance from the list.
4. In the Actions menu, choose Instance Settings, Attach/Replace IAM Role.
5. For IAM role, select the instance profile you created using the procedure in Step 4: Create an IAM
Instance Profile for Systems Manager (p. 29).
6. Choose Apply.

For more information about attaching IAM roles to instances, see Attaching an IAM Role to an Instance in
the Amazon EC2 User Guide for Linux Instances.

35
 AWS Systems Manager User Guide
Step 6: (Optional) Create a Virtual Private Cloud Endpoint

Continue to Step 6: (Optional) Create a Virtual Private Cloud Endpoint (p. 36).

Step 6: (Optional) Create a Virtual Private Cloud

Endpoint
You can improve the security posture of your managed instances (including managed instances in your
hybrid environment) by configuring AWS Systems Manager to use an interface VPC endpoint in Amazon
Virtual Private Cloud (Amazon VPC). An interface VPC endpoint (interface endpoint) enables you to
connect to services powered by AWS PrivateLink, a technology that enables you to privately access
Amazon EC2 and Systems Manager APIs by using private IP addresses. PrivateLink restricts all network
traffic between your managed instances, Systems Manager, and Amazon EC2 to the Amazon network.
(Managed instances don't have access to the Internet.) Also, you don't need an Internet gateway, a NAT
device, or a virtual private gateway.

You are not required to configure PrivateLink, but it's recommended. For more information about
PrivateLink and VPC endpoints, see Accessing AWS Services Through PrivateLink.
Note
The alternative to using a VPC endpoint is to enable outbound internet access on your managed
instances.

About Amazon VPC

Amazon Virtual Private Cloud (Amazon VPC) enables you to define a virtual network in your own
logically isolated area within the AWS cloud, known as a virtual private cloud (VPC). You can launch your
AWS resources, such as instances, into your VPC. Your VPC closely resembles a traditional network that
you might operate in your own data center, with the benefits of using AWS's scalable infrastructure. You
can configure your VPC; you can select its IP address range, create subnets, and configure route tables,
network gateways, and security settings. You can connect instances in your VPC to the internet. You can
connect your VPC to your own corporate data center, making the AWS cloud an extension of your data
center. To protect the resources in each subnet, you can use multiple layers of security, including security
groups and network access control lists. For more information, see the Amazon VPC User Guide.

Topics
• VPC Endpoint Restrictions and Limitations (p. 36)
• Creating VPC Endpoints for Systems Manager (p. 37)

VPC Endpoint Restrictions and Limitations

Before you configure VPC endpoints for Systems Manager, be aware of the following restrictions and
limitations.

aws:domainJoin plugin

If you choose to create VPC endpoints, then be aware that requests to join a Windows instance to a
domain from SSM documents that use the aws:domainJoin plugin will fail. This plugin requires the AWS
Directory Service, and AWS Directory Service does not have PrivateLink endpoint support. Support
for joining a Windows instance to a domain from other domain join methods depend only on Active
Directory requirements (for example, ensuring that domain controllers are reachable and discoverable
by using DNS and other related requirements). You can use Amazon EC2 User Data scripts to join an
instance to a domain.

Cross-region requests

VPC endpoints currently do not support cross-region requests—ensure that you create your endpoint
in the same region as your bucket. You can find the location of your bucket by using the Amazon S3

36
 AWS Systems Manager User Guide
Creating VPC Endpoints for Systems Manager

console, or by using the get-bucket-location command. Use a region-specific Amazon S3 endpoint to

access your bucket; for example, mybucket.s3-us-west-2.amazonaws.com. For more information
about region-specific endpoints for Amazon S3, see Amazon Simple Storage Service (S3) in Amazon
Web Services General Reference. If you use the AWS CLI to make requests to Amazon S3, set your default
region to the same region as your bucket, or use the --region parameter in your requests.

Incoming connections

The security group attached to the VPC endpoint must allow incoming connections on port 443 from
the private subnet of the managed instance. If incoming connections are not allowed, then the managed
instance cannot connect to the SSM and EC2 endpoints.

Amazon S3 buckets

Your VPC endpoint policy must allow at least access to the following Amazon S3 buckets:

• The S3 buckets used by Patch Manager for patch baseline operations in your AWS Region. These
buckets contain the code that is retrieved and run on instances by the patch baseline service. Each
AWS Region has its own patch baseline operations buckets for the code to be retrieved when a patch
baseline document is run. If the code can't be downloaded, the patch baseline command will fail.

To provide access to the buckets in your AWS Region, include the following permission in your
endpoint policy:

arn:aws:s3:::patch-baseline-snapshot-region/*
arn:aws:s3:::aws-ssm-region/*

region represents the Region identifier for an AWS Region supported by AWS Systems Manager, such
as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region
column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General Reference.

For example:

arn:aws:s3:::patch-baseline-snapshot-us-east-2/*
arn:aws:s3:::aws-ssm-us-east-2/*

• The S3 buckets listed in About Minimum S3 Bucket Permissions for SSM Agent (p. 87).

DNS in hybrid environment

For information about configuring DNS to work with PrivateLink endpoints in hybrid environments, see
Private DNS. If you want to use your own DNS, you can use Route 53 Resolver. For more information, see
Resolving DNS Queries Between VPCs and Your Network in the Amazon Route 53 Developer Guide.

Creating VPC Endpoints for Systems Manager

Use the following procedure to create three required and one optional separate VPC endpoints for
Systems Manager. All three endpoints are required for Systems Manager to work in a VPC. The fourth is
required only if you are using Session Manager capabilities. This procedure links to related procedures in
the Amazon VPC User Guide.

To create VPC endpoints for Systems Manager

1. Follow the steps in Creating an Interface Endpoint to create the following endpoints:

• com.amazonaws.region.ssm: The endpoint for the Systems Manager service.

• com.amazonaws.region.ec2messages: Systems Manager uses this endpoint to make calls from
SSM Agent to the Systems Manager service.

37
 AWS Systems Manager User Guide
Step 7: (Optional) Create Systems Manager Service Roles

• com.amazonaws.region.ec2: If you're using Systems Manager to create VSS-enabled snapshots,

you need to ensure that you have an endpoint to the EC2 service. Without the EC2 endpoint
defined, a call to enumerate attached EBS volumes fails, which causes the Systems Manager
command to fail.
• com.amazonaws.region.ssmmessages: This endpoint is required only if you are connecting to
your instances through a secure data channel using Session Manager. For more information, see
AWS Systems Manager Session Manager (p. 567).

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
2. Follow the steps in Creating a Gateway Endpoint to create an endpoint for Amazon S3. Systems
Manager uses this endpoint to upload Amazon S3 output logs, and to update SSM Agent.

Continue to Step 7: (Optional) Create Systems Manager Service Roles (p. 38).

Step 7: (Optional) Create Systems Manager Service

Roles
This topic explains the difference between a service role and a service-linked role for Systems Manager. It
also explains when you need to create or use either type of role.

Service role: A service role is an AWS Identity and Access Management (IAM) that grants permissions
to an AWS service so that the service can access AWS resources. Only a few Systems Manager scenarios
require a service role. When you create a service role for Systems Manager, you choose the permissions
to grant in order for it to access or interact with other AWS resources.

Service-linked role: A service-linked role is predefined by Systems Manager and includes all the
permissions that the service requires to call other AWS services on your behalf.

Currently, the Systems Manager service-linked role can be used for the following:

• The Systems Manager Inventory capability uses the service-linked role to collect inventory metadata
from tags and resource groups.
• The Maintenance Windows capability can use the service-linked role in some situations. Other
situations require a custom service role that you create, as described below.

For more information about the service-linked role, see Using Service-Linked Roles for Systems
Manager (p. 919).

Create a Service Role

You can create the following service roles as part of Systems Manager setup, or you can create them
later.

Service Role for Automation

Automation previously required that you specify a service role so that the service had permission
to perform actions on your behalf. Automation no longer requires this role because the service now
operates by using the context of the user who invoked the execution.

38
 AWS Systems Manager User Guide
Create a Service Role

However, the following situations still require that you specify a service role for Automation:

• When you want to restrict a user's privileges on a resource, but you want the user to run an
Automation workflow that requires elevated privileges. In this scenario, you can create a service role
with elevated privileges and allow the user to run the workflow.
• Operations that you expect to run longer than 12 hours require a service role.

If you need to create a service role and an instance profile role for Automation, you can use one of the
following methods.

• Method 1: Use AWS CloudFormation to Configure a Service Role for Automation (p. 145)
• Method 2: Use IAM to Configure Roles for Automation (p. 146)

Service Role for Maintenance Windows Tasks

To run tasks on your managed instances, the Maintenance Windows service must have permission to
access those resources. This permission can be granted using either a service-linked role for Systems
Manager or a custom service role that you create.

You create a custom service role in the following cases:

• If you want to use Amazon Simple Notification Service (Amazon SNS) to send notifications related to
maintenance window tasks run through Run Command.
• If you want to use a more restrictive set of permissions than those provided by the service-linked role.

For more information, see the following topics in the Maintenance Windows section of this user guide:

• Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance Window
Tasks? (p. 445)
• (Optional) Create a Custom Service Role for Maintenance Windows (Console) (p. 446).

Service Role for Amazon Simple Notification Service

Notifications
Amazon Simple Notification Service (Amazon SNS) is a web service that coordinates and manages
the delivery or sending of messages to subscribing endpoints or clients. In Systems Manager, you can
configure Amazon SNS to send notifications about the status of commands that you send using the Run
Command capability, or the status of tasks run in maintenance windows.

You create a service role for Amazon SNS as part of the process of configuring the service for use with
Systems Manager. After you complete this configuration, you choose whether to receive notifications for
particular Run Command commands or maintenance windows tasks at the time you create each one.

For more information, see Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).

Service Role for a Systems Manager Hybrid Environment

If you plan to use Systems Manager to manage on-premises servers and virtual machines (VMs) in what
is called a hybrid environment, you must create an IAM role for those resources to communicate with the
Systems Manager service.

For more information, see Create an IAM Service Role for a Hybrid Environment (p. 42).

Continue to Step 8: (Optional) Set Up Integrations with Other AWS Services (p. 40).

39
 AWS Systems Manager User Guide
Step 8: (Optional) Set Up
Integrations with Other AWS Services

Step 8: (Optional) Set Up Integrations with Other

AWS Services
AWS Systems Manager integrates with a number of other AWS services. In most cases, you set up an
integration after you decide to incorporate the service into your Systems Manager operations. For
example:

• Referencing AWS Secrets Manager Secrets from Parameter Store Parameters (p. 90)
• Using Chef InSpec Profiles with Systems Manager Compliance (p. 105)

You can use some AWS services immediately to compile log data for later troubleshooting and analysis.
You can also use AWS services to monitor and quickly respond to changes in your Systems Manager
environment. Therefore, we recommend that you set up the following resources as part of your initial
Systems Manager setup process.

Amazon CloudWatch Events and Amazon Simple Notification Service – CloudWatch Events lets you
set up rules to detect when changes happen to AWS resources that you specify. You can configure
CloudWatch Events to log status execution changes of the commands users in your account send using
Systems Manager. You can create a rule to detect when a user in your organization starts or stops a
session in Session Manager. You can also configure a CloudWatch event to trigger other actions in your
AWS environment. For more information, see the following topics:

• Understanding Command Statuses (p. 627)

• Configuring CloudWatch Events for Run Command (p. 615)
• Monitoring Session Activity Using Amazon CloudWatch Events (Console) (p. 610)

Amazon Simple Storage Service (Amazon S3)

Run Command command output in the Systems Manager console is truncated after 2,500 characters.
In order to access complete command output logs, you can store Systems Manager output in an
Amazon Simple Storage Service (Amazon S3) bucket, and then use this output later for auditing or
troubleshooting. You specify whether to save command output to an S3 bucket each time you run
a command. You can also create an Amazon S3 key prefix (a subfolder) to help you organize the log
output. For more information, see Create a Bucket in the Amazon Simple Storage Service Getting Started
Guide.

Amazon CloudWatch Logs (CloudWatch Logs)

As an alternative to storing command output in an Amazon S3 bucket, you can send output to an
Amazon CloudWatch Logs log group. If you specify CloudWatch Logs as the output target, Run
Command periodically sends all command output and error logs to CloudWatch Logs. You can
monitor output logs in near real-time, search for specific phrases, values, or patterns, and create
alarms based on the search. For more information, see Configuring Amazon CloudWatch Logs for Run
Command (p. 614).

40
 AWS Systems Manager User Guide

Setting Up AWS Systems Manager

for Hybrid Environments
This section describes the setup tasks that account and system administrators perform for a hybrid
environment. A hybrid environment includes on-premises servers and virtual machines (VMs) that have
been configured for use with Systems Manager, including VMs in other cloud environments. After these
steps are complete, users who have been granted permissions by the AWS account administrator can
use AWS Systems Manager to configure and manage their organization's on-premises servers and virtual
machines (VMs).

If you plan to use Systems Manager to manage Amazon Elastic Compute Cloud (Amazon EC2) instances,
or to use both Amazon EC2 instances and your own resources in a hybrid environment, follow the steps
in Setting Up AWS Systems Manager (p. 23) first.

Configuring your hybrid environment for Systems Manager enables you to do the following:

• Create a consistent and secure way to remotely manage your hybrid workloads from one location
using the same tools or scripts.
• Centralize access control for actions that can be performed on your servers and VMs by using AWS
Identity and Access Management (IAM).
• Centralize auditing and your view into the actions performed on your servers and VMs by recording all
actions in AWS CloudTrail.

For information about using CloudTrail to monitor Systems Manager actions, see Logging AWS
Systems Manager API Calls with AWS CloudTrail (p. 889).
• Centralize monitoring by configuring CloudWatch Events and Amazon SNS to send notifications about
service execution success.

For information about using CloudWatch Events to monitor Systems Manager events, see Monitoring
Systems Manager Events with Amazon CloudWatch Events (p. 891).

About managed instances

After you finish configuring your servers and VMs for Systems Manager as described in this section,
your hybrid machines are listed in the AWS Management Console and described as managed instances.
Amazon EC2 instances configured for Systems Manager are also described as managed instances. In the
console, however, the IDs of your hybrid instances are distinguished from Amazon EC2 instances with the
prefix "mi-". Amazon EC2 instance IDs use the prefix "i-".

About instance tiers

AWS Systems Manager offers a standard-instances tier and an advanced-instances tier for servers and
VMs in your hybrid environment. The standard-instances tier enables you to register a maximum of
1,000 on-premises servers or VMs per AWS account per AWS Region. If you need to register more than
1,000 on-premises servers or VMs in a single account and Region, then use the advanced-instances
tier. Advanced instances also enable you to connect to your hybrid machines by using AWS Systems
Manager Session Manager. Session Manager provides interactive shell access to your instances. For more
information, see Step 7: (Optional) Enable the Advanced-Instances Tier (p. 53) below.

Complete the procedures in this section to configure your hybrid servers and VMs for Systems Manager.

Topics

41
 AWS Systems Manager User Guide
Step 1: Complete General Systems Manager Setup Steps

• Step 1: Complete General Systems Manager Setup Steps (p. 42)

• Step 2: Create an IAM Service Role for a Hybrid Environment (p. 42)
• Step 3: Install a TLS certificate on On-Premises Servers and VMs (p. 45)
• Step 4: Create a Managed-Instance Activation for a Hybrid Environment (p. 45)
• Step 5: Install SSM Agent for a Hybrid Environment (Windows) (p. 48)
• Step 6: Install SSM Agent for a Hybrid Environment (Linux) (p. 50)
• Step 7: (Optional) Enable the Advanced-Instances Tier (p. 53)

Step 1: Complete General Systems Manager Setup

Steps
If you haven't already done so, complete the following general setup steps for Systems Manager in the
Setting Up AWS Systems Manager (p. 23) section of this user guide. The other steps in that section are
required only if you plan to manage Amazon EC2 instances.

• Sign Up for AWS (p. 23)

• Create an Admin IAM User for AWS (p. 24)
• Create Non-Admin IAM Users and Groups for Systems Manager (p. 25)
• (Optional) Create a Virtual Private Cloud Endpoint (p. 36)
• (Optional) Create Systems Manager Service Roles (p. 38)
• (Optional) Set Up Integrations with Other AWS Services (p. 40)

After ensuring that you have completed those steps, continue to Step 2: Create an IAM Service Role for a
Hybrid Environment (p. 42).

Step 2: Create an IAM Service Role for a Hybrid

Environment
Servers and virtual machines (VMs) in a hybrid environment require an IAM role to communicate with the
Systems Manager service. The role grants AssumeRole trust to the Systems Manager service. You only
need to create the service role for a hybrid environment once for each AWS account.
Note
Users in your company or organization who will use Systems Manager on your hybrid machines
must be granted permission in IAM to call the SSM API. For more information, see Create Non-
Admin IAM Users and Groups for Systems Manager (p. 25).

S3 bucket policy requirement

If either of the following cases are true, you must create a custom IAM permission policy for Amazon S3
buckets before completing this procedure:

• Case 1: You are using a VPC endpoint to privately connect your VPC to supported AWS services and
VPC endpoint services powered by PrivateLink.
• Case 2: You plan to use an Amazon S3 bucket that you create as part of your Systems Manager
operations, such as for storing output for Run Command commands or Session Manager sessions to
an S3 bucket. Before proceeding, follow the steps in Create a Custom S3 Bucket Policy for an Instance
Profile (p. 30). The information about S3 bucket policies in that topic also applies to your service role.

42
 AWS Systems Manager User Guide
Step 2: Create an IAM Service
Role for a Hybrid Environment

To create an IAM service role for a hybrid environment (Tools for Windows PowerShell)

1. Create a text file with a name such as SSMService-Trust.json with the following trust policy.
Make sure to save the file with the .json file extension.

{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"Service": "ssm.amazonaws.com"},
"Action": "sts:AssumeRole"
}
}

2. Use New-IAMRole as follows to create a service role. This example creates a role named
SSMServiceRole. You can choose another name if you prefer.

New-IAMRole -RoleName SSMServiceRole -AssumeRolePolicyDocument (Get-Content -

raw SSMService-Trust.json)

3. Use Register-IAMRolePolicy as follows to enable the service role you created to create a session
token. The session token gives your managed instance permission to run commands using Systems
Manager.
Note
The policies you add for a service profile for managed instances in a hybrid environment are
the same policies used to create an instance profile for EC2 instances. For more information
about the AWS policies used in the following commands, see Create an IAM Instance Profile
for Systems Manager (p. 29).

(Required) Run the following command to enable a managed instance to use AWS Systems Manager
service core functionality.

Register-IAMRolePolicy -RoleName SSMServiceRole -PolicyArn arn:aws:iam::aws:policy/

AmazonSSMManagedInstanceCore

If you created a custom S3 bucket policy for your service role, run the following command to enable
SSM Agent to access the buckets you specified in the policy. Replace account-id and my-bucket-
policy-name with your AWS account ID and your bucket name.

Register-IAMRolePolicy -RoleName SSMServiceRole -PolicyArn arn:aws:iam::account-

id:policy/my-bucket-policy-name

(Optional) Run the following command to allow SSM Agent to access AWS Directory Service on your
behalf for requests to join the domain by the managed instance. Your instance profile needs this
policy only if you join your instances to a Microsoft AD directory.

Register-IAMRolePolicy -RoleName SSMServiceRole -PolicyArn arn:aws:iam::aws:policy/

AmazonSSMDirectoryServiceAccess

(Optional) Run the following command to allow the CloudWatch agent to run on your managed
instances. This command makes it possible to read information on an instance and write it to
CloudWatch. Your service profile needs this policy only if you will use CloudWatch features, such as
Amazon CloudWatch Events or Amazon CloudWatch Logs.

Register-IAMRolePolicy -RoleName SSMServiceRole -PolicyArn arn:aws:iam::aws:policy/

CloudWatchAgentServerPolicy

43
 AWS Systems Manager User Guide
Step 2: Create an IAM Service
Role for a Hybrid Environment

To create an IAM service role for a hybrid environment (AWS CLI)

1. Create a text file with a name such as SSMService-Trust.json with the following trust policy.
Make sure to save the file with the .json file extension.

{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Principal": {"Service": "ssm.amazonaws.com"},
"Action": "sts:AssumeRole"
}
}

2. Use the create-role command to create the service role. This example creates a role named
SSMServiceRole. You can choose another name if you prefer.

aws iam create-role --role-name SSMServiceRole --assume-role-policy-document

file://SSMService-Trust.json

3. Use attach-role-policy as follows to enable the service role you just created to create a session
token. The session token gives your managed instance permission to run commands using Systems
Manager.
Note
The policies you add for a service profile for managed instances in a hybrid environment are
the same policies used to create an instance profile for EC2 instances. For more information
about the AWS policies used in the following commands, see Create an IAM Instance Profile
for Systems Manager (p. 29).

(Required) Run the following command to enable a managed instance to use AWS Systems Manager
service core functionality.

aws iam attach-role-policy --role-name SSMServiceRole --policy-arn

arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

If you created a custom S3 bucket policy for your service role, run the following command to enable
SSM Agent to access the buckets you specified in the policy. Replace account-id and my-bucket-
policy-name with your AWS account ID and your bucket name.

aws iam attach-role-policy --role-name SSMServiceRole --policy-arn

arn:aws:iam::account-id:policy/my-bucket-policy-name

(Optional) Run the following command to allow SSM Agent to access AWS Directory Service on your
behalf for requests to join the domain by the managed instance. Your instance profile needs this
policy only if you join your instances to a Microsoft AD directory.

aws iam attach-role-policy --role-name SSMServiceRole --policy-arn

arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess

(Optional) Run the following command to allow the CloudWatch agent to run on your managed
instances. This command makes it possible to read information on an instance and write it to
CloudWatch. Your service profile needs this policy only if you will use CloudWatch features, such as
Amazon CloudWatch Events or Amazon CloudWatch Logs.

aws iam attach-role-policy --role-name SSMServiceRole --policy-arn

arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

44
 AWS Systems Manager User Guide
Step 3: Install a TLS certificate
on On-Premises Servers and VMs

Note
Users in your company or organization who are to use Systems Manager on your hybrid
machines must be granted permission in IAM to call the SSM API. For more information, see
Create Users and Assign Permissions (p. 27).

Continue to Step 3: Install a TLS certificate on On-Premises Servers and VMs (p. 45).

Step 3: Install a TLS certificate on On-Premises

Servers and VMs
A Transport Layer Security (TLS) certificate must be installed on each managed instance you use with
Systems Manager. AWS services use these certificates to encrypt calls to other AWS services.

A TLS certificate is already installed by default on each Amazon EC2 instance created from any Amazon
Machine Image (AMI).

On base operating systems, on instances created from AMIs that are not supplied by Amazon, and on
your own on-premises servers and VMs, you must install and enable a certificate from Amazon Trust
Services using AWS Certificate Manager (ACM).

Each of your managed instances must have one of the following Transport Layer Security (TLS)
certificates installed.

• Amazon Root CA 1
• Starfield Services Root Certificate Authority - G2
• Starfield Class 2 Certificate Authority

For information about using Amazon Trust Services certificates or ACM, see the AWS Certificate Manager
User Guide.

If certificates in your computing environment are managed by a Group Policy Object (GPO), then you
might need to configure Group Policy to include one of these certificates.

For more information about the Amazon Root and Starfield certificates, see the blog post How to
Prepare for AWS’s Move to Its Own Certificate Authority.

Continue to Step 4: Create a Managed-Instance Activation for a Hybrid Environment (p. 45).

Step 4: Create a Managed-Instance Activation for a

Hybrid Environment
To set up servers and virtual machines (VMs) in your hybrid environment as managed instances, you need
to create a managed-instance activation. After you successfully complete the activation, you immediately
receive an Activation Code and Activation ID. You specify this Code/ID combination when you install
SSM Agent on servers and VMs in your hybrid environment. The Code/ID provides secure access to the
Systems Manager service from your managed instances.
Important
Systems Manager immediately returns the Activation Code and ID to the console or the
command window, depending on how you created the activation. Copy this information and
store it in a safe place. If you navigate away from the console or close the command window,
you might lose this information. If you lose it, you must create a new activation.

45
 AWS Systems Manager User Guide
Create an Activation (Console)

About activation expirations

An activation expiration is a window of time when you can register on-premises machines with Systems
Manager. An expired activation has no impact on your servers or virtual machines (VMs) that you
previously registered with Systems Manager. If an activation expires then you can’t register more servers
or VMs with Systems Manager by using that specific activation. You simply need to create a new one.

Every on-premises server and VM you previously registered remains registered as a Systems Manager
managed instance until you explicity deregister it. You can deregister a managed instance on the
Managed Instances page of the Systems Manager console, by using the AWS CLI command deregister-
managed-instance, or by using the API action DeregisterManagedInstance.

About activation tags

If you create an activation by using either the AWS CLI or AWS Tools for Windows PowerShell, you can
specify tags. Tags are optional metadata that you assign to a resource. Tags enable you to categorize a
resource in different ways, such as by purpose, owner, or environment. Here is a Linux CLI example that
includes tags.

aws ssm create-activation \

--default-instance-name MyWebServers \
--iam-role SSMServiceRole \
--registration-limit 10 \
--region us-east-2 \
--tags "Key=Department,Value=Finance"

If you specify tags when you create an activation, then those tags are automatically assigned to your on-
premises servers and VMs when you activate them.

You can't add tags to or delete tags from an existing activation. If you don't want to automatically assign
tags to your on-premises servers and VMs using an activation, then you can add tags to them later. More
specifically, you can tag your on-premises servers and VMs after they connect to Systems Manager for
the first time. After they connect, they are assigned a managed instance ID and listed in the Systems
Manager console with an ID that is prefixed with "mi-". For information about how to add tags to your
managed instances without using the activation process, see AddTagsToResource.
Note
You can't assign tags to an activation if you create it by using the Systems Manager console. You
must create it by using either the AWS CLI or Tools for Windows PowerShell.

Topics
• Create an Activation (Console) (p. 46)
• Create a Managed Instance Activation (Command Line) (p. 47)

Create an Activation (Console)

To create a managed-instance activation

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Hybrid Activations.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Hybrid Activations.
3. Choose Create activation.

46
 AWS Systems Manager User Guide
Create a Managed Instance Activation (Command Line)

4. (Optional) In the Activation description field, enter a description for this activation. The description
is optional, be we recommend that you enter a description if you plan to activate large numbers of
servers and VMs.
5. In the Instance limit field, specify the total number of on-premises servers or VMs that you want to
register with AWS as part of this activation.
6. In the IAM role name section, choose a service role option that enables your servers and VMs to
communicate with AWS Systems Manager in the cloud:

a. Choose Use the system created default command execution role to use a role and managed
policy created by AWS.
b. Choose Select an existing custom IAM role that has the required permissions to use the
optional custom role you created earlier.
7. In the Activation expiry date field, specify an expiration date for the activation.
Note
If you want to register additional managed instances after the expiry date, you must create
a new activation. The expiry date has no impact on registered and running instances.
8. (Optional) In the Default instance name field, specify a name.
9. Choose Create activation. Systems Manager immediately returns the Activation Code and ID to the
console.

Create a Managed Instance Activation (Command

Line)
The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to create a managed instance activation.

To create an activation

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools
for PowerShell (p. 59).
2. Run the following command to create an activation.
Note
region represents the Region identifier for an AWS Region supported by AWS Systems
Manager, such as us-east-2 for the US East (Ohio) Region. For a list of supported
region values, see the Region column in the AWS Systems Manager Table of Regions and
Endpoints in the AWS General Reference.

Linux CLI

aws ssm create-activation \

--default-instance-name name \
--iam-role iam-service-role-name \
--registration-limit number_of_managed_instances \
--region region \
--tags "Key=a_key,Value=a_value","Key=a_2nd_key,Value=a_2nd_value"

Windows CLI

aws ssm create-activation ^

--default-instance-name name ^
--iam-role iam-service-role-name ^

47
 AWS Systems Manager User Guide
Step 5: Install SSM Agent for a
Hybrid Environment (Windows)

--registration-limit number_of_managed_instances ^
--region region ^
--tags "Key=a_key,Value=a_value","Key=a_2nd_key,Value=a_2nd_value"

PowerShell

New-SSMActivation -DefaultInstanceName name `

-IamRole iam-service-role-name `
-RegistrationLimit number-of-managed-instances `
–Region region `
-Tag
@{"Key"="a_key";"Value"="a_value"},@{"Key"="a_2nd_key";"Value"="a_2nd_value"}

Here is an example.

Linux CLI

aws ssm create-activation \

--default-instance-name MyWebServers \
--iam-role SSMServiceRole \
--registration-limit 10 \
--region us-east-2 \
--tags "Key=Environment,Value=Production","Key=Department,Value=Finance"

Windows CLI

aws ssm create-activation ^

--default-instance-name MyWebServers ^
--iam-role SSMServiceRole ^
--registration-limit 10 ^
--region us-east-2 ^
--tags "Key=Environment,Value=Production","Key=Department,Value=Finance"

PowerShell

New-SSMActivation -DefaultInstanceName MyWebServers `

-IamRole SSMServiceRole `
-RegistrationLimit 10 `
–Region us-east-2 `
-Tag
@{"Key"="Environment";"Value"="Production"},@{"Key"="Department";"Value"="Finance"}

If the activation is created successfully, the system immediately returns an Activation Code and ID.

Continue to Step 5: Install SSM Agent for a Hybrid Environment (Windows) (p. 48).

Step 5: Install SSM Agent for a Hybrid

Environment (Windows)
This topic describes how to install SSM Agent on Windows Server machines in a hybrid environment. If
you plan to use Linux machines in a hybrid environment, see the next step, Step 6: Install SSM Agent for
a Hybrid Environment (Linux) (p. 50).

48
 AWS Systems Manager User Guide
Step 5: Install SSM Agent for a
Hybrid Environment (Windows)

Important
This procedure is for servers and virtual machines (VMs) in an on-premises or hybrid
environment. To download and install SSM Agent on an Amazon EC2 Windows instance, see
Installing and Configuring SSM Agent on Windows Instances (p. 65).

Before you begin, locate the Activation Code and Activation ID that were sent to you after you completed
the managed-instance activation earlier in Step 4: Create a Managed-Instance Activation for a Hybrid
Environment (p. 45). You specify the Code and ID in the following procedure.

To install SSM Agent on servers and VMs in your hybrid environment

1. Log on to a server or VM in your hybrid environment.

2. Open Windows PowerShell in elevated (administrative) mode.
3. Copy and paste the following command block into AWS Tools for Windows PowerShell. Replace
the placeholder values with the Activation Code and Activation ID generated when you create a
managed-instance activation, and with the identifier of the AWS Region you want to download SSM
Agent from.

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

$code = "activation-code"
$id = "activation-id"
$region = "region"
$dir = $env:TEMP + "\ssm"
New-Item -ItemType directory -Path $dir -Force
cd $dir
(New-Object System.Net.WebClient).DownloadFile("https://amazon-ssm-
$region.s3.amazonaws.com/latest/windows_amd64/AmazonSSMAgentSetup.exe", $dir +
"\AmazonSSMAgentSetup.exe")
Start-Process .\AmazonSSMAgentSetup.exe -ArgumentList @("/q", "/log", "install.log",
"CODE=$code", "ID=$id", "REGION=$region") -Wait
Get-Content ($env:ProgramData + "\Amazon\SSM\InstanceData\registration")
Get-Service -Name "AmazonSSMAgent"

4. Press Enter.

The command does the following:

• Downloads and installs SSM Agent onto the server or VM.

• Registers the server or VM with the SSM service.
• Returns a response to the request similar to the following:

Directory: C:\Users\ADMINI~1\AppData\Local\Temp\2

Mode LastWriteTime Length Name

---- ------------- ------ ----
d----- 07/07/2018 8:07 PM ssm
{"ManagedInstanceID":"mi-008d36be46EXAMPLE","Region":"us-east-2"}

Status : Running
Name : AmazonSSMAgent
DisplayName : Amazon SSM Agent

49
 AWS Systems Manager User Guide
Step 6: Install SSM Agent for a Hybrid Environment (Linux)

The server or VM is now a managed instance. These instances are now identified with the prefix
"mi-". You can view managed instances on the Managed Instances page in the Systems Manager
console, by using the AWS CLI command describe-instance-information, or by using the API command
DescribeInstanceInformation.
Note
You can deregister a managed instance by calling the DeregisterManagedInstance API action
from either the AWS CLI or Tools for Windows PowerShell. Here's an example CLI command:

aws ssm deregister-managed-instance --instance-id "mi-1234567890"

Continue to Step 6: Install SSM Agent for a Hybrid Environment (Linux) (p. 50).

Step 6: Install SSM Agent for a Hybrid

Environment (Linux)
This topic describes how to install SSM Agent on Linux machines in a hybrid environment. If you plan to
use Windows Server machines in a hybrid environment, see the previous step, Step 5: Install SSM Agent
for a Hybrid Environment (Windows) (p. 48).
Important
This procedure is for servers and virtual machines (VMs) in an on-premises or hybrid
environment. To download and install SSM Agent on an Amazon EC2 Linux instance, see
Installing and Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68).

Before you begin, locate the Activation Code and Activation ID that were sent to you after you completed
the managed-instance activation earlier in Step 4: Create a Managed-Instance Activation for a Hybrid
Environment (p. 45). You specify the Code and ID in the following procedure.

The URLs in the following scripts let you download SSM Agent from any AWS region. If you want to
download the agent from a specific region, copy the URL for your operating system, and then replace
region with an appropriate value.

region represents the Region identifier for an AWS Region supported by AWS Systems Manager, such as
us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region column
in the AWS Systems Manager Table of Regions and Endpoints in the AWS General Reference.

For example, to download SSM Agent for Amazon Linux, RHEL, CentOS, and SLES 64-bit from the US
West (N. California) Region (us-west-1), use the following URL:

https://s3.us-west-1.amazonaws.com/amazon-ssm-us-west-1/latest/linux_amd64/amazon-ssm-
agent.rpm

• Amazon Linux 2, Amazon Linux, RHEL, CentOS, and SLES 64-bit

https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-
agent.rpm
• Amazon Linux, RHEL, and CentOS 32-bit

https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_386/amazon-ssm-agent.rpm
• Ubuntu Server 64-bit

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-
agent.deb
• Ubuntu Server 32-bit

50
 AWS Systems Manager User Guide
Step 6: Install SSM Agent for a Hybrid Environment (Linux)

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb
• Debian Server 64-bit

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-
agent.deb
• Raspbian

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_arm/amazon-ssm-agent.deb

To install SSM Agent on servers and VMs in your hybrid environment

1. Log on to a server or VM in your hybrid environment.

2. Copy and paste one of the following command blocks into SSH. Replace the placeholder values with
the Activation Code and Activation ID generated when you create a managed-instance activation,
and with the identifier of the AWS Region you want to download SSM Agent from.

Note that sudo is not necessary if you are a root user.

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

On Amazon Linux, RHEL 6.x, and CentOS 6.x

mkdir /tmp/ssm
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-
ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
sudo stop amazon-ssm-agent
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo start amazon-ssm-agent

On Amazon Linux 2, RHEL 7.x, and CentOS 7.x

mkdir /tmp/ssm
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-
ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
sudo systemctl stop amazon-ssm-agent
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo systemctl start amazon-ssm-agent

On SLES

mkdir /tmp/ssm
sudo wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/
amazon-ssm-agent.rpm
sudo rpm --install amazon-ssm-agent.rpm
sudo systemctl stop amazon-ssm-agent
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo systemctl enable amazon-ssm-agent
sudo systemctl start amazon-ssm-agent

51
 AWS Systems Manager User Guide
Step 6: Install SSM Agent for a Hybrid Environment (Linux)

On Ubuntu

mkdir /tmp/ssm
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/
amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb
sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb
sudo service amazon-ssm-agent stop
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo service amazon-ssm-agent start

On Debian

mkdir /tmp/ssm
wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/
amazon-ssm-agent.deb -O /tmp/ssm/amazon-ssm-agent.deb
sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb
sudo service amazon-ssm-agent stop
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo service amazon-ssm-agent start

On Raspbian

mkdir /tmp/ssm
sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_arm/
amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb
sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb
sudo service amazon-ssm-agent stop
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region
"region"
sudo service amazon-ssm-agent start

Note
If you see the following error in the SSM Agent error logs, then the machine ID did not
persist after a reboot:
Unable to load instance associations, unable to retrieve
associations unable to retrieve associations error occurred in
RequestManagedInstanceRoleToken: MachineFingerprintDoesNotMatch:
Fingerprint does not match
Run the following command to make the machine ID persist after a reboot.

umount /etc/machine-id
systemd-machine-id-setup

3. Press Enter.

The command downloads and installs SSM Agent onto the server or VM in your hybrid environment. The
command stops SSM Agent, and then registers the server or VM with the SSM service. The server or VM
is now a managed instance. Amazon EC2 instances configured for Systems Manager are also managed
instances. In the Amazon EC2 console, however, your on-premises instances are distinguished from
Amazon EC2 instances with the prefix "mi-".
Note
You can deregister a managed instance by calling the DeregisterManagedInstance API action
from either the AWS CLI or Tools for Windows PowerShell. Here's an example CLI command:

52
 AWS Systems Manager User Guide
Step 7: (Optional) Enable the Advanced-Instances Tier

aws ssm deregister-managed-instance --instance-id "mi-1234567890"

Continue to Step 7: (Optional) Enable the Advanced-Instances Tier (p. 53).

Step 7: (Optional) Enable the Advanced-Instances

Tier
AWS Systems Manager offers a standard-instances tier and an advanced-instances tier for servers and
VMs in your hybrid environment. The standard-instances tier enables you to register a maximum of 1,000
on-premises servers or VMs per AWS account per AWS Region. If you need to register more than 1,000
on-premises servers or VMs in a single account and Region, then use the advanced-instances tier. You can
activate as many managed instances in a hybrid environment as you like in the advanced-instances tier.
However, all instances configured for Systems Manager using the managed-instance activation process
described earlier in Step 4: Create a Managed-Instance Activation for a Hybrid Environment (p. 45)
are made available on a pay-per-use basis. This also applies to Amazon EC2 instances that use a Systems
Manager on-premises activation (which is not a common scenario).
Note

• Advanced instances also enable you to connect to your hybrid machines by using AWS
Systems Manager Session Manager. Session Manager provides interactive shell access to your
instances. For more information, see AWS Systems Manager Session Manager (p. 567).
• The standard-instances limit also applies to Amazon EC2 instances that use a Systems
Manager on-premises activation (which is not a common scenario).
• Microsoft application patching is only available on Amazon EC2 instances and in the
advanced-instances tier. To patch Microsoft applications on on-premises servers and VMs,
you must enable the advanced-instances tier. For more information, see About Patching
Applications on Windows Server (p. 719).

This section describes how to configure your hybrid environment to use the advanced-instances tier.

Before You Begin

Review pricing details for advanced instances. Advanced instances are an account-level feature and all
on-premises servers and VMs in the account and AWS Region that were added using managed-instance
activation are made available on a per-use-basis. For more information see, AWS Systems Manager
Pricing.

Configuring Permissions to Enable the Advanced-

Instances Tier
Verify that you have permission in AWS Identity and Access Management (IAM) to change your
environment from the standard-instances tier to the advanced-instances tier. You must either have the
AdministratorAccess policy attached to your IAM user, group, or role. Or, you must have permission to
change the Systems Manager activation-tier service setting. The activation-tier setting uses the following
API actions:

• GetServiceSetting
• UpdateServiceSetting
• ResetServiceSetting

53
 AWS Systems Manager User Guide
Configuring Permissions to Enable
the Advanced-Instances Tier

Use the following procedure to add an inline IAM policy to a user account. This policy enables a user to
view the current managed-instance tier setting. This policy also enables the user to change or reset the
current setting in the specified AWS account and Region.

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users.
3. In the list, choose the name of the user to embed a policy in.
4. Choose the Permissions tab.
5. On the right side of the page, under Permission policies, choose Add inline policy.
6. Choose the JSON tab.
7. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting",

],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:AWS_Region:AWS_account_ID:servicesetting/ssm/
managed-instance/activation-tier"
}
]
}

8. Choose Review policy.

9. On the Review policy page, for Name, enter a name for the inline policy. For example: Managed-
Instances-Tier.
10. Choose Create policy.

Administrators can specify read-only permission by assigning the following inline policy to the user's
account.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"

54
 AWS Systems Manager User Guide
Enabling the Advanced-Instances Tier (Console)

],
"Resource": "*"
}
]
}

For more information about creating and editing IAM policies, see Creating IAM Policies in the IAM User
Guide.

Enabling the Advanced-Instances Tier (Console)

The following procedure shows you how to use the Systems Manager console to change all on-premises
servers and VMs that were added using managed-instance activation, in the specified AWS account and
Region, to use the advanced-instances tier.
Important
The following procedure describes how to change an account-level setting. This change results
in charges being billed to your account. If you want to change back to the standard-instances
tier, then you must contact AWS Support.

To enable the advanced-instances tier (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Managed instances.
3. Choose the Settings tab.

If you don't see the Settings tab, then do the following:

1. Verify that the console is open in the AWS Region where you created your managed instances.
You can switch Regions by using the list in the top, right corner of the console.
2. Verify that your instances meet Systems Manager requirements. For information, see Systems
Manager Prerequisites (p. 12).
3. For servers and VMs in a hybrid environment, verify that you completed the activation process.
For more information, see Setting Up AWS Systems Manager for Hybrid Environments (p. 41).
4. Choose Change account settings.
5. Review the information in the pop-up about changing account settings, and then, if you approve,
choose the option to accept and continue.

The system can take several minutes to complete the process of moving all instances from the standard-
instances tier to the advanced-instances tier.

Enabling the Advanced-Instances Tier (AWS CLI)

The following procedure shows you how to use the AWS CLI to change all on-premises servers and VMs
that were added using managed-instance activation, in the specified AWS account and Region, to use the
advanced-instances tier.
Important
The following procedure describes how to change an account-level setting. This change results
in charges being billed to your account. If you want to change back to the standard-instances
tier, then you must contact AWS Support.

To enable the advanced-instances tier using the AWS CLI

1. Open the AWS CLI and run the following command to change all managed instances in the current
AWS account and Region to use the advanced-instances tier.

55
 AWS Systems Manager User Guide
Enabling the Advanced-Instances Tier (PowerShell)

aws ssm update-service-setting --setting-id arn:aws:ssm:us-

east-1:123456789012:servicesetting/ssm/managed-instance/activation-tier --setting-value
advanced

There is no output if the command succeeds.

2. Run the following command to view the current service settings for managed instances in the
current AWS account and Region.

aws ssm get-service-setting --setting-id arn:aws:ssm:us-

east-1:123456789012:servicesetting/ssm/managed-instance/activation-tier

{
"ServiceSetting": {
"SettingId": "/ssm/managed-instance/activation-tier",
"SettingValue": "advanced",
"LastModifiedDate": 1555603376.138,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/
Jasper",
"ARN": "arn:aws:ssm:us-east-1:123456789012:servicesetting/ssm/managed-instance/
activation-tier",
"Status": "PendingUpdate"
}
}

The system can take several minutes to complete the process of moving all instances from the standard-
instances tier to the advanced-instances tier.

Enabling the Advanced-Instances Tier (PowerShell)

The following procedure shows you how to use the AWS Tools for Windows PowerShell to change all
on-premises servers and VMs that were added using managed-instance activation, in the specified AWS
account and Region, to use the advanced-instances tier.
Important
The following procedure describes how to change an account-level setting. This change results
in charges being billed to your account. If you want to change back to the standard-instances
tier, then you must contact AWS Support.

To enable the advanced-instances tier using PowerShell

1. Change all managed instances in the current AWS account and Region to use the advanced-instances
tier using the AWS Tools for Windows PowerShell.

Update-SSMServiceSetting -SettingId "arn:aws:ssm:us-east-1:123456789012:servicesetting/

ssm/managed-instance/activation-tier" -SettingValue "advanced"

There is no output if the command succeeds.

2. Run the following command to view the current service settings for managed instances in the
current AWS account and Region.

Get-SSMServiceSetting -SettingId "arn:aws:ssm:us-east-1:123456789012:servicesetting/

ssm/managed-instance/activation-tier"

56
 AWS Systems Manager User Guide
Enabling the Advanced-Instances Tier (PowerShell)

ARN : arn:aws:ssm:us-east-1:123456789012:servicesetting/ssm/managed-
instance/activation-tier
LastModifiedDate : 4/18/2019 4:02:56 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/Jasper
SettingId : /ssm/managed-instance/activation-tier
SettingValue : advanced
Status : PendingUpdate

The system can take several minutes to complete the process of moving all instances from the standard-
instances tier to the advanced-instances tier.

57
 AWS Systems Manager User Guide
Step 1: Install or Upgrade the AWS CLI

Getting Started with AWS Systems

Manager
This section helps you learn about and use AWS Systems Manager after your organization completes the
setup steps in Setting Up AWS Systems Manager (p. 23) or Setting Up AWS Systems Manager for Hybrid
Environments (p. 41).

Before You Begin

The following is useful background information to help you get started:

• The topic What Is AWS Systems Manager? (p. 1)

• The Amazon EC2 Getting Started Guide (if you are managing Amazon Elastic Compute Cloud (Amazon
EC2) instances in your account).
• Understanding the Systems Manager setup requirements helps you troubleshoot problems you
encounter while you use Systems Manager, such as with permissions or resource availability:
• Setting Up AWS Systems Manager (p. 23)
• Setting Up AWS Systems Manager for Hybrid Environments (p. 41)

When you are ready, continue with the following steps.

Topics
• Step 1: Install or Upgrade the AWS CLI (p. 58)
• Step 2: Install or Upgrade the AWS Tools for PowerShell (p. 59)
• Step 3: Practice Installing or Updating SSM Agent on an Instance (p. 60)
• Step 4: Try Systems Manager Tutorials and Walkthroughs (p. 61)

Step 1: Install or Upgrade the AWS CLI

This topic is for users who have programmatic access to use Systems Manager (or any other AWS service),
and who want to run AWS CLI commands from their local machines.
Note
Programmatic access and console access are different permissions that can be granted to a user
account by an AWS account administrator. A user can be granted one or both access types. For
information, see Create Non-Admin IAM Users and Groups for Systems Manager (p. 25).

For information about the AWS CLI, see the AWS Command Line Interface User Guide.

For information about all Systems Manager commands you can run using the AWS CLI, see the Systems
Manager section of the AWS CLI Command Reference.

To install or upgrade and then configure the AWS CLI

1. Follow the instructions in Installing the AWS Command Line Interface in the AWS Command Line
Interface User Guide to install or upgrade the AWS CLI on your local machine.

58
 AWS Systems Manager User Guide
Step 2: Install or Upgrade the AWS Tools for PowerShell

Tip
The AWS CLI is frequently updated with new functionality. Upgrade (reinstall) the CLI
periodically to ensure that you have access to all the latest functionality.
2. To configure the AWS CLI, see Configuring the AWS Command Line Interface in the AWS Command
Line Interface User Guide.

In this step, you specify credentials that an AWS administrator in your organization has given you, in
the following format:

AWS Access Key ID: AKIAIOSFODNN7EXAMPLE

AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Important
When you configure the AWS CLI, you are prompted to specify an AWS Region. Choose one
of the supported Regions listed for Systems Manager in the Region and Endpoints topic
in the AWS General Reference. If necessary, first verify with an administrator for your AWS
account which Region you should choose.

For more information about access keys, see Managing Access Keys for IAM Users in the IAM User
Guide
3. To verify the installation or upgrade, run the following command from the AWS CLI:

aws ssm help

If successful, this command displays a list of available Systems Manager commands.

Step 2: Install or Upgrade the AWS Tools for

PowerShell
This topic is for users who have programmatic access to use Systems Manager (or any other AWS service),
and who want to run AWS Tools for PowerShell commands from their local machines.
Note
Programmatic access and console access require different permissions that can be granted to a
user account by an AWS account administrator. A user can be granted one or both access types.
For information, see Create Non-Admin IAM Users and Groups for Systems Manager (p. 25).

For information about the AWS Tools for Windows PowerShell, see the AWS Tools for Windows
PowerShell User Guide.

For information about all Systems Manager commands you can run using the AWS Tools for PowerShell,
see the Systems Manager section of the AWS Tools for PowerShell Cmdlet Reference.

To install or upgrade and then configure the AWS Tools for Windows PowerShell

1. Follow the instructions in Setting up the AWS Tools for Windows PowerShell or AWS Tools for
PowerShell Core in the AWS Tools for Windows PowerShell User Guide to install or upgrade AWS
Tools for PowerShell on your local machine.
Tip
AWS Tools for PowerShell is frequently updated with new functionality. Upgrade (reinstall)
the AWS Tools for PowerShell periodically to ensure that you have access to all the latest
functionality.

59
 AWS Systems Manager User Guide
Step 3: Practice Installing or
Updating SSM Agent on an Instance

2. To configure AWS Tools for PowerShell, see Using AWS Credentials in the AWS Tools for Windows
PowerShell User Guide.

In this step, you specify credentials that an AWS administrator in your organization has given you,
using the following command.

Set-AWSCredential -AccessKey AKIAIOSFODNN7EXAMPLE -SecretKey wJalrXUtnFEMI/K7MDENG/

bPxRfiCYEXAMPLEKEY -StoreAs MyProfileName

Important
When you configure AWS Tools for PowerShell, you can run Set-DefaultAWSRegion to
specify an AWS Region. Choose one of the supported Regions listed for Systems Manager in
the Region and Endpoints topic in the AWS General Reference. If necessary, first verify with
an administrator for your AWS account which Region you should choose.

For more information about access keys, see Managing Access Keys for IAM Users in the IAM User
Guide.
3. To verify the installation or upgrade, run the following command from AWS Tools for PowerShell.

Get-AWSCmdletName -Service SSM

If successful, this command displays a list of available Systems Manager cmdlets.

Step 3: Practice Installing or Updating SSM Agent

on an Instance
AWS Systems Manager Agent (SSM Agent) is Amazon software that can be installed and configured on
an Amazon EC2 instance, an on-premises server, or a virtual machine (VM). SSM Agent makes it possible
for Systems Manager to update, manage, and configure these resources. The agent processes requests
from the Systems Manager service in the AWS Cloud, and then runs them as specified in the request.
SSM Agent then sends status and execution information back to the Systems Manager service by using
the Amazon Message Delivery Service (service prefix: ec2messages).

In this task, you install or update the SSM Agent on an Amazon EC2 instance.
Note
If you are working with your own on-premises servers or VMs, see the following topics:

• Install SSM Agent for a Hybrid Environment (Windows) (p. 48)

• Install SSM Agent for a Hybrid Environment (Linux) (p. 50)

Prerequisites

An instance profile for Systems Manager must already be attached to the Amazon EC2 instance that you
update. Refer to the following topics as needed to meet this requirement:

• Create an EC2 instance profile for Systems Manager: Create an IAM Instance Profile for Systems
Manager (p. 29)
• Attach the instance profile to an EC2 instance when you create the instance: Attach an IAM Instance
Profile to an Amazon EC2 Instance (p. 34)
• Attach the instance profile to an existing EC2 instance: Attaching an IAM Role to an Instance in the
Amazon EC2 User Guide

60
 AWS Systems Manager User Guide
Step 4: Try Systems Manager Tutorials and Walkthroughs

Windows Server instance

To practice installing or updating SSM Agent on an Amazon EC2 instance running Windows
Server instance, follow the steps in Install and Configure SSM Agent on Amazon EC2 Windows
Instances (p. 66).

Linux instance

To practice installing or updating SSM Agent on an Amazon EC2 instance running Linux, follow the
steps for your Linux operating system type in Manually Install SSM Agent on Amazon EC2 Linux
Instances (p. 68).

Step 4: Try Systems Manager Tutorials and

Walkthroughs
This topic guides you to tutorials, walkthroughs, and basic tasks to help you learn how to use Systems
Manager.

Because Systems Manager is a collection of several capabilities, no single walkthrough or tutorial can
introduce the entire service. Therefore, we've provided links to resources according to the capability for
which they provide practice.

In most cases, you do not need to complete additional setup or configuration tasks before you start.
You can complete all of the tasks if you have necessary permissions and, where needed, access to one or
more managed instances.

In some cases, additional configuration, setup, or experience with Systems Manager are required before
you try a tutorial or walkthrough. We have identify those tutorials and walkthroughs as "Advanced".

Compliance

The AWS Systems Manager Configuration Compliance (p. 504) capability scans your fleet of managed
instances for patch compliance and configuration inconsistencies.

• Configuration Compliance Walkthrough (AWS CLI) (p. 511)

Run Command

The AWS Systems Manager Run Command (p. 613) capability provides you safe, secure remote
management of your instances at scale without logging into your servers, replacing the need for bastion
hosts, SSH, or remote PowerShell. It provides a simple way of automating common administrative tasks
across groups of instances such as registry edits, user management, and software and patch installations.

• Walkthrough: Use the AWS CLI with Run Command (p. 631)
• Walkthrough: Use the AWS Tools for Windows PowerShell with Run Command (p. 634)

Session Manager

The AWS Systems Manager Session Manager (p. 567) capability lets you manage your Amazon EC2
instances through an interactive one-click browser-based shell or through the AWS CLI without the need
to open inbound ports, maintain bastion hosts, or manage SSH keys.

• Working with Session Manager (p. 598)

Distributor

61
 AWS Systems Manager User Guide
Step 4: Try Systems Manager Tutorials and Walkthroughs

The AWS Systems Manager Distributor (p. 749) capability lets you package your own software—or
find AWS-provided agent software packages, such as AmazonCloudWatchAgent—to install on Systems
Manager managed instances.

• Create a Package (p. 754)

• Step 4: Add a Package to Distributor (p. 763)

Patch Manager

The AWS Systems Manager Patch Manager (p. 683) capability helps you select and deploy operating
system and software patches automatically across large groups of Amazon EC2 instances or on-premises
servers and VMs.

• Create a Custom Patch Baseline (p. 721)

• Create a Patch Group (p. 725)
• Tutorial: Patch a Server Environment (AWS CLI) (p. 732)

Maintenance Windows

The AWS Systems Manager Maintenance Windows (p. 444) capability lets you define a schedule for
performing potentially disruptive actions on your managed instances, such as patching an operating
system, updating drivers, or installing software or patches.

• Tutorial: Create and Configure a Maintenance Window (AWS CLI) (p. 463)
• Tutorial: Update a Maintenance Window (AWS CLI) (p. 490)
• Tutorial: View Information About a Maintenance Windows (AWS CLI) (p. 479)
• Tutorial: View Information About Tasks and Task Executions (AWS CLI) (p. 488)

State Manager

The AWS Systems Manager State Manager (p. 645) capability helps you maintain consistent
configuration of your Amazon EC2 instances or on-premises servers and VMs, in a state that you define.
Using State Manager, you can control configuration details such as server configurations, anti-virus
definitions, firewall settings, and more.

• Creating Associations that Run MOF Files (p. 667)

• Automatically Update SSM Agent (CLI) (p. 681)
• Walkthrough: Automatically Update PV Drivers on EC2 Windows Instances (Console) (p. 682)

Documents

The AWS Systems Manager Documents (p. 775) capability lets you create and manage SSM documents.
An SSM document defines the actions that Systems Manager performs on your managed instances.
Systems Manager includes more than a dozen pre-configured documents that you can use by specifying
parameters at runtime. Documents use JavaScript Object Notation (JSON) or YAML, and they include
steps and parameters that you specify.

• Copy a Document (p. 785)

• Add a Systems Manager Document (Console) (p. 786)
• Create an SSM Document (AWS CLI) (p. 786)
• Create an SSM Document (Tools for Windows PowerShell) (p. 786)

Parameter Store

62
 AWS Systems Manager User Guide
Step 4: Try Systems Manager Tutorials and Walkthroughs

The AWS Systems Manager Parameter Store (p. 825) capability provides a centralized store to manage
your configuration data, whether plain-text data such as database strings or secrets such as passwords.
This allows you to separate your secrets and configuration data from your code. Parameters can be
tagged and organized into hierarchies, helping you manage parameters more easily.

• Walkthrough: Create and Use a Parameter in a Command (Console) (p. 875)

• Walkthrough: Create and Use a Parameter in a Command (AWS CLI) (p. 876)
• Walkthrough: Manage Parameters Using Hierarchies (AWS CLI) (p. 880)
• Advanced: Walkthrough: Create a Secure String Parameter and Join an Instance to a Domain
(PowerShell) (p. 878)

Inventory

The AWS Systems Manager Inventory (p. 512) capability collects information about your instances and
the software installed on them, helping you to understand your system configurations and installed
applications.

• Advanced: Walkthrough: Assign Custom Inventory Metadata to an Instance (p. 553)

• Advanced: Walkthrough: Configure Your Managed Instances for Inventory by Using the CLI (p. 554)
• Advanced: Walkthrough: Use Resource Data Sync to Aggregate Inventory Data (p. 556)

Automation

The AWS Systems Manager Automation (p. 142) capability allows you to safely automate operations
and management tasks across AWS resources. You can automate common IT tasks, safely perform
disruptive tasks in bulk, simplify complex tasks, enhance operations security, and used stored
configuration scripts share best practices with the rest of your organization.

• Advanced: Patch a Linux AMI (Console) (p. 400)

• Advanced: Patch a Linux AMI (AWS CLI) (p. 403)
• Advanced: Patch a Windows AMI (p. 408)
• Advanced: Simplify AMI Patching Using Automation, Lambda, and Parameter Store (p. 412)
• Advanced: Patch an AMI and Update an Auto Scaling Group (p. 417)
• Advanced: Run the EC2Rescue Tool on Unreachable Instances (p. 422)
• Advanced: Reset Passwords and SSH Keys on Amazon EC2 Instances (p. 426)
• Advanced: Using Automation with Jenkins (p. 431)

63
 AWS Systems Manager User Guide

Working with SSM Agent

AWS Systems Manager Agent (SSM Agent) is Amazon software that can be installed and configured on
an Amazon EC2 instance, an on-premises server, or a virtual machine (VM). SSM Agent makes it possible
for Systems Manager to update, manage, and configure these resources. The agent processes requests
from the Systems Manager service in the AWS Cloud, and then runs them as specified in the request.
SSM Agent then sends status and execution information back to the Systems Manager service by using
the Amazon Message Delivery Service (service prefix: ec2messages).

If you monitor traffic, you will see your Amazon EC2 instances, and any on-premises servers or VMs in
your hybrid environment, communicating with ec2messages.* endpoints. For more information, see
Reference: ec2messages, ssmmessages, and Other API Calls (p. 941). For information about porting
SSM Agent logs to Amazon CloudWatch Logs, see Monitoring AWS Systems Manager (p. 882).

Keeping SSM Agent up-to-date

An updated version of SSM Agent is released whenever new capabilities are added to Systems Manager
or updates are made to existing capabilities. If an older version of the agent is running on an instance,
some SSM Agent processes can fail. For that reason, we recommend that you automate the process
of keeping SSM Agent up-to-date on your instances. For information, see Automate Updates to SSM
Agent (p. 86). To be notified about SSM Agent updates, subscribe to the SSM Agent Release Notes
page on GitHub.
Note
AMIs that include SSM Agent by default can take up to two weeks to be updated with
the newest version of SSM Agent. We recommend that you configure even more frequent
automated updates to SSM Agent.
Updated versions of SSM Agent are rolled out to new AWS Regions at different times. For this
reason, you might receive the "Unsupported on current platform" error when trying to deploy a
new version of SSM Agent in a Region.

About the local ssm-user account

Starting with version 2.3.50.0 of SSM Agent, the agent creates a local user account called ssm-user and
adds it to /etc/sudoers (Linux) or to the Administrators group (Windows). On agent versions before
2.3.612.0, the account is created the first time SSM Agent starts or restarts after installation. On version
2.3.612.0 and later, the ssm-user account is created the first time a session is started on an instance.
This ssm-user is the default OS user when a Session Manager session is started. You can change the
permissions by moving ssm-user to a less-privileged group or by changing the sudoers file. The ssm-
user account is not removed from the system when SSM Agent is uninstalled.

On Windows Server, SSM Agent handles setting a new password for the ssm-user account when each
session starts. No passwords are set for ssm-user on Linux managed instances.

Starting with SSM Agent version 2.3.612.0, the ssm-user account is not created automatically on
Windows Server machines that are being used as domain controllers. To use Session Manager on a
Windows Server domain controller, you must create the ssm-user account manually if it isn't already
present.
Important
In order for the ssm-user account to be created, the instance profile attached to the instance
must provide the necessary permissions. For information, see Verify or Create an IAM Instance
Profile with Session Manager Permissions (p. 573).

AMIs with SSM Agent preinstalled

64
 AWS Systems Manager User Guide
Installing and Configuring SSM
Agent on Windows Instances

SSM Agent is preinstalled, by default, on the following Amazon Machine Images (AMIs):

• Windows Server 2003-2012 R2 AMIs published in November 2016 or later

• Windows Server 2016 and 2019
• Amazon Linux
• Amazon Linux 2
• Ubuntu Server 16.04
• Ubuntu Server 18.04

You must manually install SSM Agent on Amazon EC2 instances created from other Linux AMIs, including
non-base images like Amazon ECS-Optimized AMIs. You must also manually install SSM Agent on on-
premises servers or VMs in your hybrid environment. For more information, see Setting Up AWS Systems
Manager for Hybrid Environments (p. 41).

SSM Agent on GitHub

The source code for SSM Agent is available on GitHub so that you can adapt the agent to meet your
needs. We encourage you to submit pull requests for changes that you would like to have included.
However, Amazon Web Services does not currently provide support for running modified copies of this
software.

Contents
• Installing and Configuring SSM Agent on Windows Instances (p. 65)
• Installing and Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68)
• Restrict Access to Root-Level Commands Through SSM Agent (p. 85)
• Automate Updates to SSM Agent (p. 86)
• Subscribe to SSM Agent Notifications (p. 86)
• About Minimum S3 Bucket Permissions for SSM Agent (p. 87)

Installing and Configuring SSM Agent on Windows

Instances
SSM Agent is installed by default on instances created from Windows Server 2016 and Windows Server
2019 Amazon Machine Images (AMIs), and on instances created from Windows Server 2003-2012 R2
AMIs published in November 2016 or later.

Windows AMIs published before November 2016 use the EC2Config service to process requests and
configure instances.

Unless you have a specific reason for using the EC2Config service, or an earlier version of SSM Agent, to
process Systems Manager requests, we recommend that you download and install the latest version of
SSM Agent to each of your Amazon EC2 instances or hybrid instances that are configured for Systems
Manager.
Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

65
 AWS Systems Manager User Guide
Install and Configure SSM Agent
on Amazon EC2 Windows Instances

To view details about the different versions of SSM Agent, see the release notes.

Topics
• Install and Configure SSM Agent on Amazon EC2 Windows Instances (p. 66)
• View SSM Agent Logs on Windows Instances (p. 67)
• Configure SSM Agent to Use a Proxy for Windows Instances (p. 67)

Install and Configure SSM Agent on Amazon EC2

Windows Instances
SSM Agent is installed by default on instances created from Windows Server 2016 and Windows Server
2019 Amazon Machine Images (AMIs), and on instances created from Windows Server 2003-2012 R2
AMIs published in November 2016 or later.

If your instance is a Windows Server 2003-2012 R2 instance created before November 2016, then
EC2Config processes Systems Manager requests on your instance. We recommend that you upgrade your
existing instances to use the latest version of EC2Config. By using the latest EC2Config installer, you
install SSM Agent side-by-side with EC2Config. This side-by-side version of SSM Agent is compatible with
your instances created from earlier Windows AMIs and enables you to use SSM features published after
November 2016. For information about how to install the latest version of the EC2Config service, see
Installing the Latest Version of EC2Config in the Amazon EC2 User Guide for Windows Instances.
Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

If necessary, you can manually download and install the latest version of SSM Agent on your Amazon
EC2 Windows instance by using the following procedure.
Important
This procedure applies to installing or reinstalling SSM Agent on an Amazon EC2 Windows
instance. If you need to install the agent on an on-premises server or a virtual machine (VM)
so it can be used with Systems Manager, see Install SSM Agent for a Hybrid Environment
(Windows) (p. 48).

To manually download and install the latest version of SSM Agent

1. Log in to your instance by using, for example, Remote Desktop or Windows PowerShell.
2. Download the latest version of SSM Agent to your instance:

https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/windows_amd64/
AmazonSSMAgentSetup.exe

This URL lets you download SSM Agent from any AWS region. If you want to download the agent
from a specific region, use a region-specific URL instead:

https://amazon-ssm-region.s3.amazonaws.com/latest/windows_amd64/
AmazonSSMAgentSetup.exe

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

66
 AWS Systems Manager User Guide
View SSM Agent Logs on Windows Instances

3. Run the downloaded AmazonSSMAgentSetup.exe file to install SSM Agent.

4. Start or restart SSM Agent by sending the following command in PowerShell:

Restart-Service AmazonSSMAgent

Important
SSM Agent requires Windows PowerShell 3.0 or later to run certain SSM Documents on Windows
instances (for example, the AWS-ApplyPatchBaseline document). Verify that your Windows
instances are running Windows Management Framework 3.0 or later. This framework includes
Windows PowerShell. For more information, see Windows Management Framework 3.0.

View SSM Agent Logs on Windows Instances

SSM Agent writes information about executions, scheduled actions, errors, and health statuses to
log files on each instance. You can view log files by manually connecting to an instance, or you can
automatically send logs to Amazon CloudWatch Logs. For more information about sending logs to
CloudWatch, see Monitoring AWS Systems Manager (p. 882).

You can view SSM Agent log files on Windows instances in the following locations.

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

For information about enabling SSM Agent debug logging, see Enable SSM Agent Debug
Logging (p. 644).

Configure SSM Agent to Use a Proxy for Windows

Instances
The information in this topic applies to Windows Server instances created in or after November 2016
that do not use the Nano installation option.

If your instance is a Windows Server 2003-2012 R2 instance created before November 2016, then
EC2Config processes Systems Manager requests on your instance. For information about configuring
EC2Config to use a proxy, see Configure Proxy Settings for the EC2Config Service.

For Windows Server 2016 instances that use the Nano installation option (Nano Server), you must
connect using PowerShell. For more information, see Connect to a Windows Server 2016 Nano Server
Instance.

To configure SSM Agent to use a proxy

1. Using Remote Desktop or Windows PowerShell, connect to the instance that you would like to
configure to use a proxy.
2. Run the following command block in PowerShell. Replace hostname and port with the information
about your proxy:

$serviceKey = "HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent"
$keyInfo = (Get-Item -Path $serviceKey).GetValue("Environment")
$proxyVariables = @("http_proxy=hostname:port", "no_proxy=169.254.169.254")

If($keyInfo -eq $null)

{

67
 AWS Systems Manager User Guide
Installing and Configuring SSM Agent
on Amazon EC2 Linux Instances

New-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables -

PropertyType MultiString -Force
} else {
Set-ItemProperty -Path $serviceKey -Name Environment -Value $proxyVariables
}
Restart-Service AmazonSSMAgent

To reset SSM Agent proxy configuration

1. Using Remote Desktop or Windows PowerShell, connect to the instance to configure.

2. If you connected using Remote Desktop, launch PowerShell as an administrator.
3. Run the following command block in PowerShell:

Remove-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Services\AmazonSSMAgent -Name

Environment
Restart-Service AmazonSSMAgent

Installing and Configuring SSM Agent on Amazon

EC2 Linux Instances
SSM Agent processes Systems Manager requests and configures your machine as specified in the request.
Use the following procedures to install, configure, or uninstall SSM Agent.
Important

• SSM Agent is installed, by default, on Amazon Linux base AMIs dated 2017.09 and later. SSM
Agent is also installed, by default, on Amazon Linux 2, Ubuntu Server 16.04, and Ubuntu
Server 18.04 LTS AMIs.
• You must manually install SSM Agent on other versions of Linux, including non-base images
like Amazon ECS-Optimized AMIs.

The source code for SSM Agent is available on GitHub so that you can adapt the agent to meet your
needs. We encourage you to submit pull requests for changes that you would like to have included.
However, AWS does not currently provide support for running modified copies of this software.
Note
To view details about the different versions of SSM Agent, see the release notes.

Topics
• Manually Install SSM Agent on Amazon EC2 Linux Instances (p. 68)
• Configure SSM Agent to Use a Proxy (p. 82)
• View SSM Agent Logs (p. 84)
• Uninstall SSM Agent from Linux Instances (p. 85)

Manually Install SSM Agent on Amazon EC2 Linux

Instances
Use one of the following scripts to install SSM Agent on one of the following Linux instances.

• Amazon Linux and Amazon Linux 2 (p. 69)

68
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

• Ubuntu Server (p. 70)

• Debian Server (p. 75)
• Red Hat Enterprise Linux (RHEL) (p. 76)
• CentOS (p. 78)
• SUSE Linux Enterprise Server (SLES) 12 (p. 79)
• Raspbian (p. 80)

The URLs in the following scripts let you download SSM Agent from any AWS region. If you want to
download the agent from a specific region, see Download SSM Agent from a Specific Region (p. 81).

After you manually install SSM Agent, you can automatically update SSM Agent on your instances when
new versions become available by using Systems Manager State Manager. For more information, see
Automatically Update SSM Agent (CLI) (p. 681).
Important
These procedures apply to installing or reinstalling SSM Agent on Amazon EC2 Linux instances.
If you need to install the agent on an on-premises server or a virtual machine (VM) so it can be
used with Systems Manager, see Install SSM Agent for a Hybrid Environment (Linux) (p. 50).

Amazon Linux and Amazon Linux 2

Connect to your Amazon Linux or Amazon Linux 2 instance and perform the following steps to install
SSM Agent. Perform these steps on each instance that will run commands using Systems Manager.
Important

• SSM Agent is installed, by default, on Amazon Linux base AMIs dated 2017.09 and later. SSM
Agent is also installed, by default, on Amazon Linux 2 AMIs.
• You must manually install SSM Agent on other versions of Linux, including non-base images
like Amazon ECS-Optimized AMIs.
• Instances created from an Amazon Linux AMI that are using a proxy must be running a current
version of the Python requests module in order to support Patch Manager operations. For
more information, see Upgrade the Python Requests Module on Amazon Linux Instances That
Use a Proxy Server (p. 84).

To install SSM Agent on Amazon Linux or Amazon Linux 2

1. Use one of the following commands to download and run the SSM Agent installer.
Note
Even though the following download URLs show 'ec2-downloads-windows', these are the
correct URLs for downloading Amazon Linux and Amazon Linux 2.

Intel (x86_64) 64-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_amd64/amazon-ssm-agent.rpm

ARM (arm64) 64-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_arm64/amazon-ssm-agent.rpm

Intel (x86) 32-bit instances:

69
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_386/amazon-ssm-agent.rpm

2. Run the following command to determine if SSM Agent is running. The command should return the
message "amazon-ssm-agent is running."

Amazon Linux

sudo status amazon-ssm-agent

Amazon Linux 2

sudo systemctl status amazon-ssm-agent

3. Run the following commands if the previous command returns the message "amazon-ssm-agent is
stopped."

a. Start the service.

Amazon Linux

sudo start amazon-ssm-agent

Amazon Linux 2

sudo systemctl enable amazon-ssm-agent

sudo systemctl start amazon-ssm-agent

b. Check the status of the agent.

Amazon Linux

sudo status amazon-ssm-agent

Amazon Linux 2

sudo systemctl status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Ubuntu Server
Connect to your Ubuntu Server instance and perform the steps in one of following procedures to install
SSM Agent on each instance that will run commands using Systems Manager.

Topics

70
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

• About SSM Agent installations on 64-bit Ubuntu Server 16.04 instances (p. 71)
• Install SSM Agent on Ubuntu Server 18.04 and 16.04 LTS 64-bit instances (with Snap
package) (p. 71)
• Install SSM Agent on Ubuntu Server 16.04 and 14.04 64-bit instances (with deb installer
package) (p. 72)
• Install SSM Agent on Ubuntu Server 16.04 and 14.04 32-bit instances (p. 74)

About SSM Agent installations on 64-bit Ubuntu Server 16.04 instances

Beginning with instances created from Ubuntu Server 16.04 AMIs identified with 20180627, SSM
Agent is pre-installed using Snap packages. For example: ubuntu/images/hvm-ssd/ubuntu-
xenial-16.04-amd64-server-20180627. On instances created from earlier AMIs, you should
continue using deb installer packages.
Important
Be aware that if an instance has more than one installation of the SSM Agent (for example, one
installed using a Snap, one installed using a deb installer), your agent operations will not work
correctly.

You can check the source AMI ID for an instance following these steps:

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the left navigation, choose Instances.
3. Select an instance.
4. On the Description tab, locate the value in the AMI ID field.

For instances created from a 64-bit Ubuntu Server 16.04 AMI, be sure to follow the correct procedure for
your SSM Agent installation type:

• Instances created from AMIs with identifier 20180627 or later: Install SSM Agent on Ubuntu Server
18.04 and 16.04 LTS 64-bit instances (with Snap package) (p. 71)
• Instances created from AMIs earlier than 20180627: Install SSM Agent on Ubuntu Server 16.04 and
14.04 64-bit instances (with deb installer package) (p. 72)

Install SSM Agent on Ubuntu Server 18.04 and 16.04 LTS 64-bit instances (with
Snap package)

1. SSM Agent is installed, by default, on Ubuntu Server 18.04 and on 16.04 LTS 64-bit AMIs with an
identifier of 20180627 or later. For more information about version 16.04 AMIs, see About SSM
Agent installations on 64-bit Ubuntu Server 16.04 instances (p. 71).

You can use the following script if you need to install SSM Agent on an on-premises server or if you
need to reinstall the agent. You don't need to specify a URL for the download, because the snap
command automatically downloads the agent from the Snap app store at https://snapcraft.io.

sudo snap install amazon-ssm-agent --classic

Note
Note the following details about SSM Agent on Ubuntu Server 18.04 and 16.04:

• Because of a known issue with Snap, you might see a Maximum timeout exceeded
error with snap commands. If you get this error, run the following commands one at a
time to start the agent, stop it, and check its status:

71
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

sudo systemctl start snap.amazon-ssm-agent.amazon-ssm-agent.service

sudo systemctl stop snap.amazon-ssm-agent.amazon-ssm-agent.service

sudo systemctl status snap.amazon-ssm-agent.amazon-ssm-agent.service

• On Ubuntu Server 18.04 and 16.04, SSM Agent installer files, including agent
binaries and config files, are stored in the following directory: /snap/amazon-
ssm-agent/current/. If you make changes to the config files (amazon-ssm-
agent.json.template and seelog.xml.template) then you must copy these files
from the /snap folder to the /etc/amazon/ssm/ folder. Log and library files have not
changed (/var/lib/amazon/ssm, /var/log/amazon/ssm).
• On Ubuntu Server 18.04, use Snaps only. Don't install deb packages. Also verify that only
one instance of the agent is installed and running on your instances.
• On Ubuntu Server 18.04 and 16.04, SSM Agent provides support for the arm64 processor
architecture.
• On Ubuntu Server 16.04, SSM Agent is installed using either Snaps or deb installation
packages, depending on the version of the 16.04 AMI. For more information, see About
SSM Agent installations on 64-bit Ubuntu Server 16.04 instances (p. 71).
2. Run the following command to determine if SSM Agent is running.

sudo snap list amazon-ssm-agent

3. Run the following command to start the service if the previous command returned amazon-ssm-
agent is stopped, inactive, or disabled.

sudo snap start amazon-ssm-agent

4. Check the status of the agent.

sudo snap services amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Install SSM Agent on Ubuntu Server 16.04 and 14.04 64-bit instances (with deb
installer package)
1. You can use the following script if you need to install SSM Agent on an on-premises server or if you
need to reinstall the agent.
Important
SSM Agent is installed by default on instances created from Ubuntu Server 16.04 LTS 64-
bit AMIs with an identifier of 20180627 or later. Instances created from AMIs with earlier
identifiers, for example 20171121.1 and 20180522, should continue to use deb installers.
If SSM Agent is installed on your instance in conjunction with a Snap and you install or
update SSM Agent using a deb installer package, the installation or SSM Agent operations

72
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

may fail. For more information, see About SSM Agent installations on 64-bit Ubuntu Server
16.04 instances (p. 71)

Create a temporary directory on the instance.

mkdir /tmp/ssm

Change to the temporary directory.

cd /tmp/ssm

Run the following commands.

Note
Even though the following download URL shows 'ec2-downloads-windows', this is the
correct URL.

wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/
amazon-ssm-agent.deb

sudo dpkg -i amazon-ssm-agent.deb

2. Run one of the following commands to determine if SSM Agent is running.

Ubuntu Server 16.04:

sudo systemctl status amazon-ssm-agent

Ubuntu Server 14.04:

sudo status amazon-ssm-agent

3. Run one of the following commands to start the service if the previous command returned amazon-
ssm-agent is stopped, inactive, or disabled.

Ubuntu Server 16.04:

sudo systemctl enable amazon-ssm-agent

Ubuntu Server 14.04:

sudo start amazon-ssm-agent

4. Run one of the following commands to check the status of the agent.

Ubuntu Server 16.04:

sudo systemctl status amazon-ssm-agent

Ubuntu Server 14.04:

sudo status amazon-ssm-agent

73
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Install SSM Agent on Ubuntu Server 16.04 and 14.04 32-bit instances
1. Create a temporary directory on the instance.

mkdir /tmp/ssm

Change to the temporary directory.

cd /tmp/ssm

Run the following commands.

Note
Even though the following download URL shows 'ec2-downloads-windows', this is the
correct URL.

wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_386/amazon-
ssm-agent.deb

sudo dpkg -i amazon-ssm-agent.deb

2. Run the following command to determine if SSM Agent is running:

sudo status amazon-ssm-agent

3. Run the following commands if the previous command returned amazon-ssm-agent is

stopped, inactive, or disabled.

a. Start the agent:

sudo start amazon-ssm-agent

b. Check the status of the agent:

sudo status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

74
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

Debian Server
Connect to your Debian Server instance and perform the steps in one of following procedures to install
SSM Agent on each instance that will run commands using Systems Manager.

Topics
• Install SSM Agent on Debian Server 9 64-bit instances (with deb installer package) (p. 75)
• Install SSM Agent on Debian Server 8 64-bit instances (with deb installer package) (p. 76)

Install SSM Agent on Debian Server 9 64-bit instances (with deb installer
package)
1. Connect to your Debian Server instance and perform the following steps to install SSM Agent.
Perform these steps on each instance that will run commands using Systems Manager.

Create a temporary directory on the instance.

mkdir /tmp/ssm

Change to the temporary directory.

cd /tmp/ssm

Run the following commands.

Note
Even though the following download URL shows 'ec2-downloads-windows', this is the
correct URL.

wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/
amazon-ssm-agent.deb

sudo dpkg -i amazon-ssm-agent.deb

2. Run following command to determine if SSM Agent is running.

sudo systemctl status amazon-ssm-agent

3. Run the following command to start the service if the previous command returned amazon-ssm-
agent is stopped, inactive, or disabled.

sudo systemctl enable amazon-ssm-agent

4. Run the following command to check the status of the agent.

sudo systemctl status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see

75
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Install SSM Agent on Debian Server 8 64-bit instances (with deb installer
package)
1. Connect to your Debian Server instance and perform the following steps to install SSM Agent.
Perform these steps on each instance that will run commands using Systems Manager.

Create a temporary directory on the instance.

mkdir /tmp/ssm

Change to the temporary directory.

cd /tmp/ssm

Run the following commands.

Note
Even though the following download URL shows 'ec2-downloads-windows', this is the
correct URL.

wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_amd64/
amazon-ssm-agent.deb

sudo dpkg -i amazon-ssm-agent.deb

2. Run following command to determine if SSM Agent is running.

sudo systemctl status amazon-ssm-agent

3. Run the following command to start the service if the previous command returned amazon-ssm-
agent is stopped, inactive, or disabled.

sudo systemctl enable amazon-ssm-agent

4. Run the following command to check the status of the agent.

sudo systemctl status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Red Hat Enterprise Linux (RHEL)

Connect to your RHEL instance and perform the following steps to install SSM Agent. Perform these
steps on each instance that will run commands using Systems Manager.
76
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

To install SSM Agent on Red Hat Enterprise Linux

1. Use one of the following commands to download and run the SSM Agent installer.
Note
Even though the following download URLs show 'ec2-downloads-windows', these are the
correct URLs.

Intel (x86_64) 64-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_amd64/amazon-ssm-agent.rpm

ARM (arm64) 64-bit instances::

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_arm64/amazon-ssm-agent.rpm

Intel (x86) 32-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_386/amazon-ssm-agent.rpm

2. Run one of the following commands to determine if SSM Agent is running. The command should
return the message amazon-ssm-agent is running.

RHEL 7.x:

sudo systemctl status amazon-ssm-agent

RHEL 6.x:

sudo status amazon-ssm-agent

3. Run the following commands if the previous command returned amazon-ssm-agent is

stopped.

a. Start the service.

RHEL 7.x:

sudo systemctl enable amazon-ssm-agent

sudo systemctl start amazon-ssm-agent

RHEL 6.x:

sudo start amazon-ssm-agent

b. Check the status of the agent.

RHEL 7.x:

sudo systemctl status amazon-ssm-agent

77
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

RHEL 6.x:

sudo status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

CentOS
Connect to your CentOS instance and perform the following steps to install the SSM Agent. Perform
these steps on each instance that will run commands using Systems Manager.

To install SSM Agent on CentOS

1. Use one of the following commands to download and run the SSM Agent installer.
Note
Even though the following download URLs show 'ec2-downloads-windows', these are the
correct URLs.

64-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_amd64/amazon-ssm-agent.rpm

32-bit instances:

sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/

linux_386/amazon-ssm-agent.rpm

2. Run one of the following commands to determine if SSM Agent is running. The command should
return the message amazon-ssm-agent is running.

CentOS 7.x:

sudo systemctl status amazon-ssm-agent

CentOS 6.x:

sudo status amazon-ssm-agent

3. Run the following commands if the previous command returned amazon-ssm-agent is

stopped.

a. Start the service.

CentOS 7.x:

sudo systemctl enable amazon-ssm-agent

78
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

sudo systemctl start amazon-ssm-agent

CentOS 6.x:

sudo start amazon-ssm-agent

b. Check the status of the agent.

CentOS 7.x:

sudo systemctl status amazon-ssm-agent

CentOS 6.x:

sudo status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

SUSE Linux Enterprise Server (SLES) 12

Connect to your SLES instance and perform the following steps to install the SSM Agent. Perform these
steps on each instance that will run commands using Systems Manager.

To install SSM Agent on SUSE Linux Enterprise Server

1. Create a temporary directory on the instance.

mkdir /tmp/ssm

2. Change to the temporary directory.

cd /tmp/ssm

3. Run the following commands one at a time to download and run the SSM Agent installer.
Note
Even though the following download URL shows 'ec2-downloads-windows', this is the
correct URL.

64-bit instances:

wget https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-
ssm-agent.rpm

sudo rpm --install amazon-ssm-agent.rpm

4. Run the following command to determine if SSM Agent is running. The command should return the
message amazon-ssm-agent is running.

79
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

sudo systemctl status amazon-ssm-agent

5. Run the following commands if the previous command returns the message amazon-ssm-agent
is stopped.

a. Start the service.

sudo systemctl enable amazon-ssm-agent

sudo systemctl start amazon-ssm-agent

b. Check the status of the agent.

sudo systemctl status amazon-ssm-agent

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Raspbian
This section includes information about how to install SSM Agent on Raspbian Jessie and Raspbian
Stretch, including Raspberry Pi (32-bit) devices.

Before You Begin

To set up your Raspbian devices as Systems Manager managed instances, you need to create a managed-
instance activation. After you complete the activation, you receive an activation code and ID. This code/
ID combination functions like an Amazon EC2 access ID and secret key to provide secure access to the
Systems Manager service from your managed instances. Store the activation code and ID in a safe place.
For more information about the activation process, see Setting Up AWS Systems Manager for Hybrid
Environments (p. 41).

Connect to your Raspbian device and perform the following steps to install the SSM Agent. Perform
these steps on each instance that will run commands using Systems Manager.

To install SSM Agent on Raspbian devices

1. Create a temporary directory on the instance.

mkdir /tmp/ssm

2. Use the following command to download and run the SSM Agent installer.

sudo curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/debian_arm/

amazon-ssm-agent.deb -o /tmp/ssm/amazon-ssm-agent.deb

3. Run the following command to install SSM Agent.

sudo dpkg -i /tmp/ssm/amazon-ssm-agent.deb

80
 AWS Systems Manager User Guide
Manually Install SSM Agent on Amazon EC2 Linux Instances

4. Run the following command to stop SSM Agent.

sudo service amazon-ssm-agent stop

5. Run the following command to register the agent using the managed-instance activation code and
ID you received when you completed the managed-instance activation process.

sudo amazon-ssm-agent -register -code "code" -id "ID" -region "region"

6. Run the following command to start SSM Agent.

sudo service amazon-ssm-agent start

Note

• If you see the following error in the SSM Agent error logs, then the machine ID did not persist
after a reboot:

Unable to load instance associations, unable to retrieve

associations unable to retrieve associations error occurred in
RequestManagedInstanceRoleToken: MachineFingerprintDoesNotMatch:
Fingerprint does not match

Run the following command to make the machine ID persist after a reboot.

umount /etc/machine-id
systemd-machine-id-setup

• An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is
running on an instance, some SSM Agent processes can fail. For that reason, we recommend
that you automate the process of keeping SSM Agent up-to-date on your instances. For
information, see Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent
updates, subscribe to the SSM Agent Release Notes page on GitHub.

Download SSM Agent from a Specific Region

If you want to download the agent from a specific region, copy the URL for your operating system, and
then replace region with an appropriate value.

region represents the Region identifier for an AWS Region supported by AWS Systems Manager, such as
us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region column
in the AWS Systems Manager Table of Regions and Endpoints in the AWS General Reference.

For example, to download SSM Agent for Amazon Linux, RHEL, CentOS, and SLES 64-bit from the US
West 1 Region, use the following URL:

https://s3.us-west-1.amazonaws.com/amazon-ssm-us-west-1/latest/linux_amd64/amazon-ssm-
agent.rpm

• Amazon Linux, RHEL, CentOS, and SLES 64-bit:

https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_amd64/amazon-ssm-
agent.rpm
• Amazon Linux, RHEL, and CentOS 32-bit:

81
 AWS Systems Manager User Guide
Configure SSM Agent to Use a Proxy

https://s3.region.amazonaws.com/amazon-ssm-region/latest/linux_386/amazon-ssm-agent.rpm
• Ubuntu Server 64-bit:

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_amd64/amazon-ssm-
agent.deb
• Ubuntu Server 32-bit:

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_386/amazon-ssm-agent.deb
• Raspbian:

https://s3.region.amazonaws.com/amazon-ssm-region/latest/debian_arm/amazon-ssm-agent.deb

Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe
to the SSM Agent Release Notes page on GitHub.

Configure SSM Agent to Use a Proxy

You can configure SSM Agent to communicate through an HTTP proxy by adding the http_proxy,
https_proxy, and no_proxy settings to an amazon-ssm-agent.override configuration file. An override
file also preserves the proxy settings if you install newer or older versions of SSM Agent. This section
includes procedures for upstart and systemd environments.
Note
Instances created from an Amazon Linux AMI that are using a proxy must be running a current
version of the Python requests module in order to support Patch Manager operations. For
more information, see Upgrade the Python Requests Module on Amazon Linux Instances That
Use a Proxy Server (p. 84).

Topics
• Configure SSM Agent to Use a Proxy (Upstart) (p. 82)
• Configure SSM Agent to Use a Proxy (systemd) (p. 83)
• Upgrade the Python Requests Module on Amazon Linux Instances That Use a Proxy Server (p. 84)

Configure SSM Agent to Use a Proxy (Upstart)

1. Connect to the instance where you installed SSM Agent.
2. Open a simple editor like VIM, and specify the following settings:

env http_proxy=http://hostname:port
env https_proxy=http(s)://hostname:port
env no_proxy=169.254.169.254

Note
You must add the no_proxy setting to the file and specify the IP address listed here. It
is the instance metadata endpoint for Systems Manager. Without this IP address, calls to
Systems Manager fail.
3. Save the file as amazon-ssm-agent.override in the following location: /etc/init/

82
 AWS Systems Manager User Guide
Configure SSM Agent to Use a Proxy

4. Stop and restart SSM Agent using the following commands:

sudo stop amazon-ssm-agent

sudo start amazon-ssm-agent

Note
For more information about working with .override files in Upstart environments, see init:
Upstart init daemon job configuration.

Configure SSM Agent to Use a Proxy (systemd)

The steps in the following procedure describe how to configure SSM Agent to use a proxy in systemd
environments. Some of the steps in this procedure contain explicit instructions for Ubuntu Server
instances installed by using Snap.

1. Connect to the instance where you installed SSM Agent.

2. Run the following command:

systemctl edit amazon-ssm-agent

For Ubuntu Server instances installed by using a snap, run the following command:

systemctl edit snap.amazon-ssm-agent.amazon-ssm-agent

3. Specify the following settings:

[Service]
Environment="http_proxy=http://hostname:port"
Environment="https_proxy=http(s)://hostname:port"
Environment="no_proxy=169.254.169.254"

Note
You must add the no_proxy setting to the file and specify the IP address listed here. It
is the instance metadata endpoint for Systems Manager. Without this IP address, calls to
Systems Manager fail.
4. Save your changes. The system creates a file named amazon-ssm-agent.override (or
override.conf on Amazon Linux 2) instances in the etc/systemd/system/amazon-ssm-
agent.service.d folder.
5. Restart SSM Agent by using the following commands:

sudo systemctl stop amazon-ssm-agent

sudo systemctl daemon-reload

For Ubuntu Server instances installed by using a snap, restart SSM Agent by using the following
command:

systemctl start snap.amazon-ssm-agent.amazon-ssm-agent

Note
For more information about working with .override files in systemd environments, see Modifying
Existing Unit Files.

83
 AWS Systems Manager User Guide
View SSM Agent Logs

Upgrade the Python Requests Module on Amazon Linux

Instances That Use a Proxy Server
To patch an instance that is using a proxy and that was created from an Amazon Linux AMI, Patch
Manager requires a recent version of the Python requests module to be installed on the instance. We
recommend always upgrading to the most recently released version.

To ensure the latest version of the Python requests module is installed, follow these steps:

1. Sign in to the Amazon Linux instance, or use the AWS-RunShellScript SSM document in Run
Command, and run the following command on the instance:

pip list | grep requests

• If the module is installed, the request returns the version number in a response similar to the
following:

requests (1.2.3)

• If the module is not installed, run the following command to install it:

pip install requests

• If pip itself is not installed, run the following command to install it:

sudo yum install -y python-pip

2. If the module is installed, but the version listed is earlier than 2.18.4 (such as 1.2.3 shown in the
previous step), run the following command to upgrade to the latest version of the Python requests
module:

pip install requests --upgrade

View SSM Agent Logs

SSM Agent writes information about executions, scheduled actions, errors, and health statuses to
log files on each instance. You can view log files by manually connecting to an instance, or you can
automatically send logs to Amazon CloudWatch Logs. For more information about sending logs to
CloudWatch, see Monitoring AWS Systems Manager (p. 882).

You can view SSM Agent logs on Linux instances in the following locations.

• /var/log/amazon/ssm/amazon-ssm-agent.log
• /var/log/amazon/ssm/errors.log

SSM Agent sterr and stdout files are written to the following directory: /var/lib/amazon/ssm.

For information about enabling SSM Agent debug logging, see Enable SSM Agent Debug
Logging (p. 644).

For more information about cihub/seelog configuration, see the Seelog Wiki on GitHub. For examples
of cihub/seelog configurations, see the cihub/seelog examples repository on GitHub.

84
 AWS Systems Manager User Guide
Uninstall SSM Agent from Linux Instances

Uninstall SSM Agent from Linux Instances

Use the following commands to uninstall SSM Agent.

Amazon Linux, Amazon Linux 2, RHEL, and CentOS

sudo yum erase amazon-ssm-agent –y

Ubuntu Server

• deb package installations:

sudo dpkg -r amazon-ssm-agent

• snap package installations:

sudo snap remove amazon-ssm-agent

Debian Server

sudo dpkg -r amazon-ssm-agent

SLES

sudo rpm --erase amazon-ssm-agent

Restrict Access to Root-Level Commands Through

SSM Agent
SSM Agent runs on Amazon EC2 instances using root permissions (Linux) or SYSTEM permissions
(Windows). Because these are the highest level of system access privileges, any trusted entity that has
been granted permission to send commands to SSM Agent has root or SYSTEM permissions. (In AWS, a
trusted entity that can perform actions and access resources in AWS is called a principal. A principal can
be an AWS account root user, an IAM user, or a role.)

This level of access is required for a principal to send authorized Systems Manager commands to SSM
Agent, but also makes it possible for a principal to run malicious code by exploiting any potential
vulnerabilities in SSM Agent.

In particular, permissions to run the commands SendCommand and StartSession should be carefully
restricted. A good first step is to grant permissions for each command only to select principals in your
organization. However, we recommend tightening your security posture even further by restricting which
instances a principal can run these commands on. This can be done in the IAM user policy assigned to the
principal. In the IAM policy, you can include a condition that limits the user to running commands only on
instances that are tagged with specific Amazon EC2 tags, or combinations of EC2 tags.

For example, say you have two fleets of instances, one for testing, one for production. In the IAM policy
applied to junior engineers, you specify that they can run commands only on instances tagged with
ssm:resourceTag/testServer. But for a smaller group of lead engineers, who should have access

85
 AWS Systems Manager User Guide
Automate Updates to SSM Agent

to all instances, you grant access to instances tagged with both ssm:resourceTag/testServer and
ssm:resourceTag/productionServer.

Using this approach, if junior engineers attempt to run a command on a production instance, they will be
denied access because their assigned IAM policy does not provide explicit access to instances tagged with
ssm:resourceTag/productionServer.

For more information and examples, see the following topics:

• Restricting Run Command Access Based on Instance Tags (p. 616)

• Restrict Session Access Based on Instance Tags (p. 585)

Automate Updates to SSM Agent

A new version of SSM Agent is released whenever new capabilities are added to Systems Manager or
updates are made to existing capabilities. If an older version of the agent is still running on an instance,
some SSM Agent processes can fail. For that reason, we recommend that you automate the process of
keeping SSM Agent up-to-date on your instances using either of the following methods.

• Use a State Manager association. For information, see the State Manager topic Automatically Update
SSM Agent (CLI) (p. 681).
• Use a maintenance window. For information, see the Maintenance Windows topics Automatically
Update SSM Agent (AWS CLI) and Automatically Update SSM Agent (Console).

If you prefer to update SSM Agent on your instances manually, you can subscribe to notifications that
AWS publishes when a new version of the agent is released. For information, see Subscribe to SSM Agent
Notifications (p. 86). For information about using Run Command to manually update one or more
instances with the latest version, see Update SSM Agent by using Run Command (p. 620).

Subscribe to SSM Agent Notifications

Amazon Simple Notification Service (Amazon SNS) can notify you when new versions of SSM Agent are
released. Use the following procedure to subscribe to these notifications.
Tip
You can also subscribe to notifications by watching the SSM Agent Release Notes page on
GitHub.

To subscribe to SSM Agent notifications

1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v3/home.

2. From the Region selector in the navigation bar, choose US East (N. Virginia), if it is not selected
already. You must select this Region because the SNS notifications for SSM Agent that you are
subscribing to are generated from this Region only.
3. In the navigation pane, choose Subscriptions.
4. Choose Create subscription.
5. For Create subscription, do the following:

a. For Topic ARN, use the following Amazon Resource Name (ARN):

arn:aws:sns:us-east-1:720620558202:SSM-Agent-Update

86
 AWS Systems Manager User Guide
About Minimum S3 Bucket Permissions for SSM Agent

b. For Protocol, choose Email or SMS.

c. For Endpoint, type an email address that you can use to receive the notifications. If you choose
SMS, type an area code and number.
d. Choose Create subscription.
6. If you chose Email, you'll receive an email asking you to confirm your subscription. Open the email
and follow the directions to complete your subscription.

Whenever a new version of SSM Agent is released, we send notifications to subscribers. If you no longer
want to receive these notifications, use the following procedure to unsubscribe.

To unsubscribe from SSM Agent notifications

1. Open the Amazon SNS console.

2. In the navigation pane, choose Subscriptions.
3. Select the subscription and then choose Actions, Delete subscriptions. When prompted for
confirmation, choose Delete.

About Minimum S3 Bucket Permissions for SSM

Agent
This topic provides information about the Amazon Simple Storage Service (Amazon S3) buckets that
SSM Agent might need to access to in order to perform Systems Manager operations. These buckets are
publicly accessible, but in some cases, you might need to provide explicit permission in an EC2 instance
profile for Systems Manager, or in a service role for instances in a hybrid environment. Most commonly,
you must grant these permissions if you are using a private VPC endpoint in your Systems Manager
operations. Otherwise, your resources can't access these public buckets.

To grant access to these buckets, you create a custom S3 permissions policy, and then attach it to your
instance profile (for EC2 instances) or your service role (for on-premises servers and virtual machines
(VMs) in a hybrid environment.
Note
These permissions only provide access to the AWS managed buckets required by SSM Agent.
They don't provide the permissions that are necessary for other Amazon S3 operations. They
also don't provide permission to your own S3 buckets.

For more information, see the following topics:

• Create an IAM Instance Profile for Systems Manager (p. 29)

• Create an IAM Service Role for a Hybrid Environment (p. 42)

Contents
• Required Permissions (p. 87)
• Example (p. 88)

Required Permissions
The following table describes each of the Amazon S3 policy permissions needed for using Systems
Manager.

87
 AWS Systems Manager User Guide
Example

Amazon S3 permissions required by SSM Agent

Permission Description

arn:aws:s3:::aws-ssm-region/* Provides access to the Amazon S3 bucket

containing modules required for use with SSM
documents.

arn:aws:s3:::aws-windows- Required for some SSM documents that support

downloads-region/* Windows operating systems.

arn:aws:s3:::amazon-ssm-region/* Required for updating SSM Agent installations.

These buckets contain the SSM Agent installation
packages, and the installation manifests that
are referenced by the AWS-UpdateSSMAgent
document and plugin.

arn:aws:s3:::amazon-ssm- Required for using versions of SSM Agent

packages-region/* prior to 2.2.45.0 to run the document AWS-
ConfigureAWSPackage.

arn:aws:s3:::region-birdwatcher-prod/* Provides access to the distribution service used

by version 2.2.45.0 and later of SSM Agent.
This service is used to run the document AWS-
ConfigureAWSPackage.

arn:aws:s3:::patch-baseline- Provides access to the Amazon S3 bucket

snapshot-region/* containing patch baseline snapshots. This is
required if you use the AWS-RunPatchBaseline
and AWS-ApplyPatchBaseline documents.

region represents the Region identifier for an AWS Region supported by AWS Systems Manager, such as
us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region column
in the AWS Systems Manager Table of Regions and Endpoints in the AWS General Reference.

Example
The following example illustrates how to provide access to the Amazon S3 buckets required for Systems
Manager operations in the US East (Ohio) Region (us-east-2).

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": [
"arn:aws:s3:::aws-ssm-us-east-2/*",
"arn:aws:s3:::aws-windows-downloads-us-east-2/*",
"arn:aws:s3:::amazon-ssm-us-east-2/*",
"arn:aws:s3:::amazon-ssm-packages-us-east-2/*",
"arn:aws:s3:::us-east-2-birdwatcher-prod/*",
"arn:aws:s3:::patch-baseline-snapshot-us-east-2/*"
]
}
]
}

88
 AWS Systems Manager User Guide
Example

Important
We recommend that you avoid using wildcard characters (*) in place of specific Regions
in this policy. For example, use arn:aws:s3:::aws-ssm-us-east-2/* and do not use
arn:aws:s3:::aws-ssm-*/*. Using wildcards could provide access to Amazon S3 buckets
that you don’t intend to grant access to. If you want to use the instance profile for more than
one Region, we recommend repeating the first Statement block for each Region.

89
 AWS Systems Manager User Guide
Referencing AWS Secrets Manager
Secrets from Parameter Store Parameters

Partner and Product Integration

You can use AWS Systems Manager with partner and product technologies to automate the deployment,
configuration, and maintenance of your managed instances.

Contents
• Referencing AWS Secrets Manager Secrets from Parameter Store Parameters (p. 90)
• Running Scripts from GitHub and Amazon S3 (p. 93)
• Using Chef InSpec Profiles with Systems Manager Compliance (p. 105)

Referencing AWS Secrets Manager Secrets from

Parameter Store Parameters
Secrets Manager helps you organize and manage important configuration data such as credentials,
passwords, and license keys. Parameter Store is now integrated with Secrets Manager so that you can
retrieve Secrets Manager secrets when using other AWS services that already support references to
Parameter Store parameters. These services include Amazon EC2, Amazon Elastic Container Service,
AWS Lambda, AWS CloudFormation, AWS CodeBuild, AWS CodeDeploy, and other Systems Manager
capabilities. By using Parameter Store to reference Secrets Manager secrets, you create a consistent and
secure process for calling and using secrets and reference data in your code and configuration scripts.

For more information about Secrets Manager, see What Is AWS Secrets Manager? in the AWS Secrets
Manager User Guide.
Important
Parameter Store functions as a pass-through service for references to Secrets Manager secrets.
Parameter Store doesn't retain data or metadata about secrets. The reference is stateless.

Restrictions
Note the following restrictions when using Parameter Store to reference Secrets Manager secrets:

• You can only retrieve Secrets Manager secrets by using the GetParameter and GetParameters API
actions. Modification operations and advance querying API actions, such as DescribeParameters or
GetParametersByPath, are not supported for Secrets Manager.
• You can use the AWS CLI, AWS Tools for Windows PowerShell, and the SDKs to retrieve a secret by
using Parameter Store.
• When you retrieve a Secrets Manager secret from Parameter Store, the
parameter name must begin with the following reserved path: /aws/reference/
secretsmanager/secret_ID_in_Secrets_Manager.

Here is an example: /aws/reference/secretsmanager/CFCreds1

• Parameter Store honors IAM policies attached to Secrets Manager secrets. For example, if User 1
doesn't have access to Secret A, then User 1 can't retrieve Secret A by using Parameter Store.
• Parameters that reference Secrets Manager secrets can't use the Parameter Store versioning or history
features.
• Parameter Store honors Secrets Manager version stages. If you reference a version stage, it can only
use letters, numbers, a period (.), a hyphen (-), or an underscore (_). All other symbols specified in the
version stage cause the reference to fail.

90
 AWS Systems Manager User Guide
How to Reference a Secrets Manager
Secret by Using Parameter Store

How to Reference a Secrets Manager Secret by Using

Parameter Store
The following procedure describes how to reference a Secrets Manager secret by using Parameter Store
APIs. The procedure references other procedures in the AWS Secrets Manager User Guide.
Note
Before you begin, verify that you have permission to reference Secrets Manager secrets in
Parameter Store parameters. If you have administrator privileges in Secrets Manager and
Systems Manager, then you can reference or retrieve secrets by using Parameter Store APIs.
If you reference a Secrets Manager secret in a Parameter Store parameter, and you don't
have permission to access that secret, then the reference fails. For more information, see
Authentication and Access Control for AWS Secrets Manager in the AWS Secrets Manager User
Guide.

To reference a Secrets Manager secret by using Parameter Store

1. Create a secret in Secrets Manager. For more information, see Creating and Managing Secrets with
AWS Secrets Manager.
2. Reference a secret by using the AWS CLI, AWS Tools for Windows PowerShell, or the SDK. When you
reference a Secrets Manager secret, the parameter name must begin with the following reserved
path: /aws/reference/secretsmanager/. By specifying this path, Systems Manager knows to retrieve
the secret from Secrets Manager instead of Parameter Store. Here are some example parameters
that correctly reference Secrets Manager secrets:

• /aws/reference/secretsmanager/CFCreds1
• /aws/reference/secretsmanager/DBPass

Here is a Java code example that references an access-key and a secret-key that are stored in Secrets
Manager. This code example sets up an Amazon DynamoDB client. The code retrieves configuration
data and credentials from Parameter Store. The configuration data is stored as a string parameter in
Parameter Store and the credentials are stored in Secrets Manager. Even though the configuration
data and credentials are stored in separate services, both sets of data can be access from Parameter
Store by using the GetParameter API.

/**
* Initialize AWS System Manager Client with default credentials
*/
AWSSimpleSystemsManagement ssm =
AWSSimpleSystemsManagementClientBuilder.defaultClient();

...

/**
* Example method to launch DynamoDB client with credentials different from default
* @return DynamoDB client
*/
AmazonDynamoDB getDynamoDbClient() {
//Getting AWS credentials from Secrets manager using GetParameter
BasicAWSCredentials differentAWSCreds = new BasicAWSCredentials(
getParameter("/aws/reference/secretsmanager/access-key"),
getParameter("/aws/reference/secretsmanager/secret-key"));

//Initialize the DDB Client with different credentials

final AmazonDynamoDB client = AmazonDynamoDBClient.builder()
.withCredentials(new AWSStaticCredentialsProvider(differentAWSCreds))
.withRegion(getParameter("region")) //Getting config from Parameter Store
.build();

91
 AWS Systems Manager User Guide
How to Reference a Secrets Manager
Secret by Using Parameter Store

return client;
}

/**
* Helper method to retrieve SSM Parameter's value
* @param parameterName identifier of the SSM Parameter
* @return decrypted parameter value
*/
public GetParameterResult getParameter(String parameterName) {
GetParameterRequest request = new GetParameterRequest();
request.setName(parameterName);
request.setWithDecryption(true);
return ssm.newGetParameterCall().call(request).getParameter().getValue();
}

Here are some AWS CLI examples.

AWS CLI Example 1: Reference by using the name of the secret

aws ssm get-parameter --name /aws/reference/secretsmanager/s1-secret --with-decryption

The command returns information like the following.

{
"Parameter": {
"Name": "/aws/reference/secretsmanager/s1-secret",
"Value": "Fl*MEishm!al875",
"Type": "SecureString",
"LastModifiedDate": 2018-05-14T21:47:14.743Z,
"ARN": "arn:aws:secretsmanager:us-west-1:123456789:secret:s1-secret-
E18LRP",
"SourceResult":
"{
\"CreatedDate\": 1526334434.743,
\"Name\": \"s1-secret\",
\"VersionId\": \"aaabbbccc-1111-222-333-123456789\",
\"SecretString\": \"Fl*MEishm!al875\",
\"VersionStages\": [\"AWSCURRENT\"],
\"ARN\": \"arn:aws:secretsmanager:us-west-
1:123456789:secret:s1-secret-E18LRP\"
}"
}
}

AWS CLI Example 2: Reference that includes the version ID

aws ssm get-parameter --name /aws/reference/secretsmanager/s1-secret:11111-aaa-bbb-

ccc-123456789 --with-decryption

The command returns information like the following.

{
"Parameter": {
"Name": "/aws/reference/secretsmanager/s1-secret",
"Value": "Fl*MEishm!al875",
"Type": "SecureString",
"LastModifiedDate": 2018-05-14T21:47:14.743Z,
"ARN": "arn:aws:secretsmanager:us-west-1:123456789:secret:s1-secret-
E18LRP",
"SourceResult":

92
 AWS Systems Manager User Guide
Running Scripts from GitHub and Amazon S3

"{
\"CreatedDate\": 1526334434.743,
\"Name\": \"s1-secret\",
\"VersionId\": \"11111-aaa-bbb-ccc-123456789\",
\"SecretString\": \"Fl*MEishm!al875\",
\"VersionStages\": [\"AWSCURRENT\"],
\"ARN\": \"arn:aws:secretsmanager:us-west-
1:123456789:secret:s1-secret-E18LRP\"
}"
"Selector": ":11111-aaa-bbb-ccc-123456789"
}
}

AWS CLI Example 3: Reference that includes the version stage

aws ssm get-parameter --name /aws/reference/secretsmanager/s1-secret:AWSCURRENT --with-

decryption

The command returns information like the following.

{
"Parameter": {
"Name": "/aws/reference/secretsmanager/s1-secret",
"Value": "Fl*MEishm!al875",
"Type": "SecureString",
"LastModifiedDate": 2018-05-14T21:47:14.743Z,
"ARN": "arn:aws:secretsmanager:us-west-1:123456789:secret:s1-secret-
E18LRP",
"SourceResult":
"{
\"CreatedDate\": 1526334434.743,
\"Name\": \"s1-secret\",
\"VersionId\": \"11111-aaa-bbb-ccc-123456789\",
\"SecretString\": \"Fl*MEishm!al875\",
\"VersionStages\": [\"AWSCURRENT\"],
\"ARN\": \"arn:aws:secretsmanager:us-west-
1:123456789:secret:s1-secret-E18LRP\"
}"
"Selector": ":AWSCURRENT"
}
}

Running Scripts from GitHub and Amazon S3

This section describes how to use the AWS-RunRemoteScript pre-defined SSM document to download
scripts from GitHub and Amazon S3, including Ansible Playbooks, Python, Ruby, and PowerShell scripts.
By using this document, you no longer need to manually port scripts into Amazon EC2 or wrap them in
SSM documents. Systems Manager integration with GitHub and Amazon S3 promotes infrastructure as
code, which reduces the time it takes to manage instances while standardizing configurations across your
fleet.

You can also create custom SSM documents that enable you to download and run scripts or other SSM
documents from remote locations. For more information, see Creating Composite Documents (p. 796).

Topics
• Running Scripts from GitHub (p. 94)
• Running Scripts from Amazon S3 (p. 98)

93
 AWS Systems Manager User Guide
Running Scripts from GitHub

Running Scripts from GitHub

This section describes how to download and run scripts from a private or public GitHub repository. You
can run different types of scripts, including Ansible Playbooks, Python, Ruby, and PowerShell scripts.

You can also download a directory that includes multiple scripts. When you run the primary script in
the directory, Systems Manager also runs any referenced scripts (as long as the referenced scripts are
included in the directory).

Note the following important details about running scripts from GitHub.

• Systems Manager does not check to see if your script is capable of running on an instance. Before you
download and run the script, you must verify that the required software is installed on the instance.
Or, you can create a composite document that installs the software by using either Run Command or
State Manager, and then downloads and runs the script.
• You are responsible for ensuring that all GitHub requirements are met. This includes refreshing your
access token, as needed. You must also ensure that you don't surpass the number of authenticated or
unauthenticated requests. For more information, see the GitHub documentation.

Topics
• Run Ansible Playbooks from GitHub (p. 94)
• Run Python Scripts from GitHub (p. 96)

Run Ansible Playbooks from GitHub

This section includes procedures to help you run Ansible Playbooks from GitHub by using either the
console or the AWS CLI.

Before You Begin

If you plan to run a script that is stored in a private GitHub repository, then you must create a Systems
Manager SecureString parameter for your GitHub security access token. You can't access a script in a
private GitHub repository by manually passing your token over SSH. The access token must be passed as
a Systems Manager SecureString parameter. For more information about creating a SecureString
parameter, see Creating Systems Manager Parameters (p. 847).

Run an Ansible Playbook from GitHub (Console)

Run an Ansible Playbook from GitHub

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose AWS-RunRemoteScript.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.

94
 AWS Systems Manager User Guide
Running Scripts from GitHub

6. In Command parameters, do the following:

• In Source Type, select GitHub.

• In the Source Info box, type the required information to access the source in the following format:

{"owner":"owner_name", "repository": "repository_name",

"path": "path_to_scripts_or_directory", "tokenInfo":"{{ssm-
secure:SecureString_parameter_name}}" }

For example:

{"owner":"TestUser1", "repository": "GitHubPrivateTest", "path": "scripts/

webserver.yml", "tokenInfo":"{{ssm-secure:mySecureStringParameter}}" }

This example downloads a file named webserver.yml.

• In the Command Line field, type parameters for the script execution. Here is an example.

ansible-playbook -i “localhost,” --check -c local webserver.yml

• (Optional) In the Working Directory field, type the name of a directory on the instance where you
want to download and run the script.
• (Optional) In Execution Timeout, specify the number of seconds for the system to wait before
failing the script command execution.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
11. Choose Run.
95
 AWS Systems Manager User Guide
Running Scripts from GitHub

Run an Ansible Playbook from GitHub by Using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to download and run a script from GitHub.

aws ssm send-command --document-name "AWS-RunRemoteScript" --instance-

ids "instance-IDs" --parameters '{"sourceType":["GitHub"],"sourceInfo":
["{\"owner\":\"owner_name\", \"repository\": \"repository_name\",
\"path\": \"path_to_file_or_directory\", \"tokenInfo\":\"{{ssm-
secure:name_of_your_SecureString_parameter}}\" }"],"commandLine":["commands_to_run"]}'

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --instance-ids "i-1234abcd"

--parameters '{"sourceType":["GitHub"],"sourceInfo":["{\"owner\":\"TestUser1\",
\"repository\": \"GitHubPrivateTest\", \"path\": \"scripts/webserver.yml\",
\"tokenInfo\":\"{{ssm-secure:mySecureStringParameter}}\" }"],"commandLine":["ansible-
playbook -i “localhost,” --check -c local webserver.yml"]}'

Run Python Scripts from GitHub

This section includes procedures to help you run Python scripts from GitHub by using either the console
or the AWS CLI.

Run a Python Script from GitHub (Console)

Run a Python Script from GitHub

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose AWS-RunRemoteScript.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. In Command parameters, do the following:

• In Source Type, select GitHub.

• In the Source Info text box, type the required information to access the source in the following
format:

{"owner":"owner_name", "repository": "repository_name",

"path": "path_to_scripts_or_directory", "tokenInfo":"{{ssm-
secure:SecureString_parameter_name}}" }

96
 AWS Systems Manager User Guide
Running Scripts from GitHub

For example:

{"owner":"TestUser1", "repository":"GitHubPrivateTest", "path": "scripts/python/

complex-script","tokenInfo":"{{ssm-secure:mySecureStringParameter}}"}

This example downloads a directory of scripts named complex-script.

• In the Command Line field, type parameters for the script execution. Here is an example.

mainFile.py argument-1 argument-2

This example runs mainFile.py, which can then run other scripts in the complex-script directory.
• (Optional) In the Working Directory field, type the name of a directory on the instance where you
want to download and run the script.
• (Optional) In Execution Timeout, specify the number of seconds for the system to wait before
failing the script command execution.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
11. Choose Run.

Run a Python Script from GitHub by Using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).

97
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

2. Run the following command to download and run a script from GitHub.

aws ssm send-command --document-name "AWS-RunRemoteScript" --instance-

ids "instance-IDs" --parameters '{"sourceType":["GitHub"],"sourceInfo":
["{\"owner\":\"owner_name\", \"repository\":\"repository_name\", \"path\":
\"path_to_script_or_directory"}"],"commandLine":["commands_to_run"]}'

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --instance-ids "i-abcd1234"

--parameters '{"sourceType":["GitHub"],"sourceInfo":["{\"owner\":\"TestUser1\",
\"repository\":\"GitHubTestPublic\", \"path\": \"scripts/python/complex-script
\"}"],"commandLine":["mainFile.py argument-1 argument-2 "]}'

This example downloads a directory of scripts name complex-script. The commandLine entry runs
mainFile.py, which can then run other scripts in the complex-script directory.

Running Scripts from Amazon S3

This section describes how to download and run scripts from Amazon S3. You can run different types of
scripts, including Ansible Playbooks, Python, Ruby, Shell, and PowerShell.

You can also download a directory that includes multiple scripts. When you run the primary script in
the directory, Systems Manager also runs any referenced scripts (as long as the referenced scripts are
included in the directory).

Note the following important details about running scripts from Amazon S3.

• Systems Manager does not check to see if your script is capable of running on an instance. Before you
download and run the script, you must verify that the required software is installed on the instance.
Or, you can create a composite document that installs the software by using either Run Command or
State Manager, and then downloads and runs the script.
• Verify that your AWS Identity and Access Management (IAM) user account, role, or group has
permission to read from the S3 bucket.

Topics
• Run Ruby Scripts from Amazon S3 (p. 98)
• Run Shell Scripts from Amazon S3 (p. 100)
• Run PowerShell Script from Amazon S3 (p. 103)

Run Ruby Scripts from Amazon S3

This section includes procedures to help you run Ruby scripts from Amazon S3 by using either the
Systems Manager console or the AWS CLI.

Run a Ruby Script from Amazon S3 (Console)

Run a Ruby Script from Amazon S3

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

98
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose AWS-RunRemoteScript.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. In Command parameters, do the following:

• In Source Type, select S3.

• In the Source Info text box, type the required information to access the source in the following
format:

{"path":"https://s3.amazonaws.com/path_to_script"}

For example:

{"path":"https://s3.amazonaws.com/rubytest/scripts/ruby/helloWorld.rb"}

• In the Command Line field, type parameters for the script execution. Here is an example.

helloWorld.rb argument-1 argument-2

• (Optional) In the Working Directory field, type the name of a directory on the instance where you
want to download and run the script.
• (Optional) In Execution Timeout, specify the number of seconds for the system to wait before
failing the script command execution.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.

99
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
11. Choose Run.

Run a Ruby Script from Amazon S3 by using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Depending on the operating system type on your local machine, run one of the following commands
to download and run a script from Amazon S3 (the Windows version includes the escape characters
("/") you need to run the command from your command line tool):

Windows local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript"

--targets "Key=instanceids,Values=instance-IDs" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://
s3.amazonaws.com/path_to_script\"}',"commandLine"="script_name_and_arguments"

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --

targets "Key=instanceids,Values=i-1234567890abcdef0" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://s3.amazonaws.com/RubyTest/scripts/
ruby/helloWorld.rb\"}',"commandLine"="helloWorld.rb argument-1 argument-2"

Linux local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=instance-IDs" --parameters '{"sourceType":["S3"],"sourceInfo":
["{\"path\":\"https://s3.amazonaws.com/path_to_script\"}"],"commandLine":
["script_name_and_arguments"]}'

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=i-1234567890abcdef0" --parameters '{"sourceType":
["S3"],"sourceInfo":["{\"path\":\"https://s3.amazonaws.com/RubyTest/scripts/ruby/
helloWorld.rb\"}"],"commandLine":["helloWorld.rb argument-1 argument-2"]}'

Run Shell Scripts from Amazon S3

This section includes procedures to help you run Shell scripts from Amazon S3 by using either the
Systems Manager console or the AWS CLI.

100
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

Run a Shell Script from Amazon S3 (Console)

Run a Shell Script from Amazon S3

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose AWS-RunRemoteScript.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. In Command parameters, do the following:

• In Source Type, select S3.

• In the Source Info text box, type the required information to access the source in the following
format:

{"path":"https://s3.amazonaws.com/path_to_script"}

For example:

{"path":"https://s3.amazonaws.com/shelltest/scripts/shell/helloWorld.sh"}

• In the Command Line field, type parameters for the script execution. Here is an example.

helloWorld.sh argument-1 argument-2

• (Optional) In the Working Directory field, type the name of a directory on the instance where you
want to download and run the script.
• (Optional) In Execution Timeout, specify the number of seconds for the system to wait before
failing the script command execution.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.

101
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
11. Choose Run.

Run a Shell Script from Amazon S3 by using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Depending on the operating system type on your local machine, run one of the following commands
to download and run a script from Amazon S3 (the Windows version includes the escape characters
("\") you need to run the command from your command line tool):

Windows local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript"

--targets "Key=instanceids,Values=instance-IDs" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://
s3.amazonaws.com/path_to_script\"}',"commandLine"="script_name_and_arguments"

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --

targets "Key=instanceids,Values=i-1234567890abcdef0" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://s3.amazonaws.com/ShellTest/scripts/
shell/helloWorld.sh\"}',"commandLine"="helloWorld.sh argument-1 argument-2"

Linux local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=instance-IDs" --parameters '{"sourceType":["S3"],"sourceInfo":
["{\"path\":\"https://s3.amazonaws.com/path_to_script\"}"],"commandLine":
["script_name_and_arguments"]}'

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=i-1234567890abcdef0" --parameters '{"sourceType":
["S3"],"sourceInfo":["{\"path\":\"https://s3.amazonaws.com/ShellTest/scripts/shell/
helloWorld.sh\"}"],"commandLine":["helloWorld.sh argument-1 argument-2"]}'

102
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

Run PowerShell Script from Amazon S3

This section includes procedures to help you run PowerShell scripts from Amazon S3 by using either the
EC2 console or the AWS CLI.

Run a PowerShell Script from Amazon S3 (Console)

Run a PowerShell Script from Amazon S3

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose AWS-RunRemoteScript.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. In Command parameters, do the following:

• In Source Type, select S3.

• In the Source Info text box, type the required information to access the source in the following
format:

{"path": "https://s3.amazonaws.com/path_to_script"}

For example:

{"path": "https://s3.amazonaws.com/PowerShellTest/powershell/helloPowershell.ps1"}

• In the Command Line field, type parameters for the script execution. Here is an example.

helloPowershell.ps1 argument-1 argument-2

• (Optional) In the Working Directory field, type the name of a directory on the instance where you
want to download and run the script.
• (Optional) In Execution Timeout, specify the number of seconds for the system to wait before
failing the script command execution.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.

103
 AWS Systems Manager User Guide
Running Scripts from Amazon S3

Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
11. Choose Run.

Run a PowerShell Script from S3 by Using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Depending on the operating system type on your local machine, run one of the following commands
to download and run a script from Amazon S3 (the Windows version includes the escape characters
("\") you need to run the command from your command line tool):

Windows local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript"

--targets "Key=instanceids,Values=instance-IDs" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://
s3.amazonaws.com/path_to_script\"}',"commandLine"="script_name_and_arguments"

Here is an example.

aws ssm send-command --document-name "AWS-RunRemoteScript" --

targets "Key=instanceids,Values=i-1234567890abcdef0" --parameters
"sourceType"="S3",sourceInfo='{\"path\":\"https://s3.amazonaws.com/PowerShellTest/
scripts/powershell/helloWorld.ps1\"}',"commandLine"="helloWorld.ps1 argument-1
argument-2"

Linux local machine:

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=instance-IDs" --parameters '{"sourceType":["S3"],"sourceInfo":
["{\"path\":\"https://s3.amazonaws.com/path_to_script\"}"],"commandLine":
["script_name_and_arguments"]}'

Here is an example.

104
 AWS Systems Manager User Guide
Using Chef InSpec Profiles with
Systems Manager Compliance

aws ssm send-command --document-name "AWS-RunRemoteScript" --targets

"Key=instanceids,Values=i-1234567890abcdef0" --parameters '{"sourceType":
["S3"],"sourceInfo":["{\"path\":\"https://s3.amazonaws.com/PowerShellTest/scripts/
powershell/helloWorld.ps1\"}"],"commandLine":["helloWorld.ps1 argument-1 argument-2"]}'

Using Chef InSpec Profiles with Systems Manager

Compliance
Systems Manager now integrates with Chef InSpec. InSpec is an open-source, runtime framework that
enables you to create human-readable profiles on GitHub or Amazon S3. Then you can use Systems
Manager to run compliance scans and view compliant and noncompliant instances. A profile is a security,
compliance, or policy requirement for your computing environment. For example, you can create profiles
that perform the following checks when you scan your instances with Systems Manager Compliance:

• Check if specific ports are open or closed.

• Check if specific applications are running.
• Check if certain packages are installed.
• Check Windows Registry keys for specific properties.

You can create InSpec profiles for Amazon EC2 instances and on-premises servers or virtual machines
(VMs) that you manage with Systems Manager. The following sample Chef InSpec profile checks to see if
port 22 is open.

control 'Scan Port' do

impact 10.0
title 'Server: Configure the service port'
desc 'Always specify which port the SSH server should listen to.
Prevent unexpected settings.'
describe sshd_config do
its('Port') { should eq('22') }
end
end

InSpec includes a collection of resources that help you quickly write checks and auditing controls. InSpec
uses the InSpec Domain-specific Language (DSL) for writing these controls in Ruby. You can also use
profiles created by a large community of InSpec users. For example, the DevSec chef-os-hardening
project on GitHub includes dozens of profiles to help you secure your instances and servers. You can
author and store profiles in GitHub or Amazon Simple Storage Service (Amazon S3).

How It Works
Here is how the process of using InSpec profiles with Systems Manager Compliance works.

1. Either identify predefined InSpec profiles that you want to use, or create your own. You can use
predefined profiles on GitHub to get started. For information about how to create your own InSpec
profiles, see Compliance Automation with InSpec.
2. Store profiles in either a public or private GitHub repository, or in an Amazon S3 bucket.
3. Run Compliance with your InSpec profiles by using the AWS-RunInspecChecks SSM document. You can
begin a Compliance scan by using Run Command (for on-demand scans), or you can schedule regular
Compliance scans by using State Manager.

105
 AWS Systems Manager User Guide
Running an InSpec Compliance Scan

4. Identify noncompliant instances by using the Compliance API or the Systems Manager Compliance
console.

Note
Chef uses a client on your instances to process the profile. You don't need to install the client.
When Systems Manager runs the AWS-RunInspecChecks SSM document, the system checks if
the client is installed. If not, Systems Manager installs the Chef client during the scan, and then
uninstalls the client after the scan is completed.

Running an InSpec Compliance Scan

This section includes information about how to run an InSpec Compliance scan by using the Systems
Manager console and the AWS CLI. The console procedure shows you how to configure State Manager to
run the scan. The AWS CLI procedure shows you how to configure Run Command to run the scan.

Running an InSpec Compliance Scan with State Manager by

Using the Console
To run an InSpec Compliance scan with State Manager by using the AWS Systems Manager
console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose State Manager.
3. Choose Create Association.
4. In the Provide association details section, enter a name.
5. In the Command document list, choose AWS-RunInspecChecks.
6. In the Document version list, choose Latest at runtime.
7. In the Parameters section, in the Source Type list, choose either GitHub or S3.

If you choose GitHub, then enter the path to an InSpec profile in either a public or private GitHub
repository in the Source Info field. Here is an example path to a public profile provided by the
Systems Manager team from the following location: https://github.com/awslabs/amazon-ssm/tree/
master/Compliance/InSpec/PortCheck.

{"owner":"awslabs","repository":"amazon-ssm","path":"Compliance/InSpec/
PortCheck","getOptions":"branch:master"}

If you choose S3, then enter a valid URL to an InSpec profile in an Amazon S3 bucket in the Source
Info field.

For more information about how Systems Manager integrates with GitHub and Amazon S3, see
Running Scripts from GitHub and Amazon S3 (p. 93).
8. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.

106
 AWS Systems Manager User Guide
Running an InSpec Compliance Scan

9. In the Specify schedule section, use the schedule builder options to create a schedule for when you
want the Compliance scan to run.
10. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
11. Choose Create Association. The system creates the association and automatically runs the
Compliance scan.
12. Wait several minutes for the scan to complete, and then choose Compliance in the navigation pane.
13. In Corresponding managed instances, locate instances where the Compliance Type column is
Custom:Inspec.
14. Choose an instance ID to view the details of noncompliant statuses.

Running an InSpec Compliance Scan with Run Command by

Using the AWS CLI
1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run one of the following commands to run an InSpec profile from either GitHub or Amazon S3.

The command takes the following parameters:

• sourceType: GitHub or Amazon S3

• sourceInfo: URL to the InSpec profile folder either in GitHub or an Amazon S3 bucket. The folder
must contain the base InSpec file (*.yml) and all related controls (*.rb).

GitHub

aws ssm send-command --document-name "AWS-RunInspecChecks" --targets

'[{"Key":"tag:tag_name","Values":["tag_value"]}]' --parameters '{"sourceType":
["GitHub"],"sourceInfo":["{\"owner\":\"owner_name\", \"repository\":
\"repository_name\", \"path\": \"Inspec.yml_file"}"]}'

Here is an example.

aws ssm send-command --document-name "AWS-RunInspecChecks" --targets

'[{"Key":"tag:testEnvironment","Values":["webServers"]}]' --parameters '{"sourceType":
["GitHub"],"getOptions":"branch:master","sourceInfo":["{\"owner\":\"awslabs\",
\"repository\":\"amazon-ssm\", \"path\": \"Compliance/InSpec/PortCheck\"}"]}'

Amazon S3

aws ssm send-command --document-name "AWS-RunInspecChecks" --

targets '[{"Key":"tag:tag_name","Values":["tag_value"]}]' --
parameters'{"sourceType":["S3"],"sourceInfo":["{\"path\":\"https://
s3.amazonaws.com/directory/Inspec.yml_file\"}"]}'

Here is an example.

107
 AWS Systems Manager User Guide
Running an InSpec Compliance Scan

aws ssm send-command --document-name "AWS-RunInspecChecks" --targets

'[{"Key":"tag:testEnvironment","Values":["webServers"]}]' --parameters'{"sourceType":
["S3"],"sourceInfo":["{\"path\":\"https://s3.amazonaws.com/Compliance/InSpec/
PortCheck.yml\"}"]}'

3. Run the following command to view a summary of the Compliance scan.

aws ssm list-resource-compliance-summaries --filters

Key=ComplianceType,Values=Custom:Inspec

4. Run the following command to drill down into an instance that is not compliant.

aws ssm list-compliance-items --resource-ids instance_ID --resource-type

ManagedInstance --filters Key=DocumentName,Values=AWS-RunInspecChecks

Related AWS Services

The following related services can help you assess Compliance and work with Chef.

• Amazon Inspector lets you perform security assessments on your instances based on and common
vulnerabilities described in Central Internet Security (CIS) standards.
• AWS OpsWorks for Chef Automate lets you run a Chef Automate server in AWS.

108
 AWS Systems Manager User Guide
CloudWatch Dashboards

Operations Management
Operations Management is a suite of capabilities that help you manage your AWS resources.

Topics
• Amazon CloudWatch Dashboards Hosted by Systems Manager (p. 109)
• AWS Systems Manager OpsCenter (p. 109)
• AWS Resource Groups (p. 140)
• Trusted Advisor and Personal Health Dashboards Hosted by Systems Manager (p. 140)

Amazon CloudWatch Dashboards Hosted by

Systems Manager
Amazon CloudWatch dashboards are customizable home pages in the CloudWatch console that you
can use to monitor your resources in a single view, even those resources that are spread across different
Regions. You can use CloudWatch dashboards to create customized views of the metrics and alarms for
your AWS resources. With dashboards, you can create the following:

• A single view for selected metrics and alarms to help you assess the health of your resources and
applications across one or more regions. You can select the color used for each metric on each graph,
so that you can easily track the same metric across multiple graphs.
• An operational playbook that provides guidance for team members during operational events about
how to respond to specific incidents.
• A common view of critical resource and application measurements that can be shared by team
members for faster communication flow during operational events.

You can create dashboards by using the console, the AWS CLI, or by using the PutDashboard API. For
more information, see Using Amazon CloudWatch Dashboards in the Amazon CloudWatch User Guide.

AWS Systems Manager OpsCenter

OpsCenter provides a central location where operations engineers and IT professionals can view,
investigate, and resolve operational work items (OpsItems) related to AWS resources. OpsCenter is
designed to reduce mean time to resolution for issues impacting AWS resources. This Systems Manager
capability aggregates and standardizes OpsItems across services while providing contextual investigation
data about each OpsItem, related OpsItems, and related resources. OpsCenter also provides Systems
Manager Automation documents (runbooks) that you can use to quickly resolve issues. You can specify
searchable, custom data for each OpsItem. You can also view automatically-generated summary reports
about OpsItems by status and source.

OpsCenter is integrated with Amazon CloudWatch Events. This means you can create CloudWatch Events
rules that automatically create OpsItems for any AWS service that publishes events to CloudWatch
Events. For example, you can configure SSM OpsItems as the target for the following types of events,
and hundreds more:

• Security issues, such as alerts from AWS Security Hub

• Performance issues, such as a throttling event for Amazon DynamoDB or degraded Amazon Elastic
Block Store (EBS) volume performance

109
 AWS Systems Manager User Guide
How Can OpsCenter Benefit My Organization?

• Failures, such as an Amazon EC2 Auto Scaling group failure to launch an instance or a Systems
Manager Automation execution failure
• Health alerts, such as an AWS Health alert for scheduled maintenance
• State changes, such as an Amazon EC2 instance state change from Running to Stopped

OpsCenter is also integrated with Amazon CloudWatch Application Insights for .NET and SQL Server. This
means you can automatically create OpsItems for problems detected in your applications.

Operations engineers and IT professionals can create, view, and edit OpsItems by using the OpsCenter
page in the AWS Systems Manager console, public API actions, the AWS CLI, AWS Tools for Windows
PowerShell, or the AWS SDKs. You can also use AWS Lambda with Amazon SNS to create OpsItems from
sources like CloudWatch alarms. OpsCenter public API actions also enable you to integrate OpsCenter
with your case management systems and health dashboards.

How Can OpsCenter Benefit My Organization?

AWS Systems Manager OpsCenter enables a standard and unified experience for viewing, working
on, and remediating issues related to AWS resources. A standard and unified experience improves the
time it takes to remedy issues, investigate related issues, and train new operations engineers and IT
professionals. A standard and unified experience also reduces the number of manual errors entered into
the system of managing and remediating issues.

More specifically, OpsCenter offers the following benefits for operations engineers and organizations:

• You no longer need to navigate across multiple console pages to view, investigate, and resolve
OpsItems related to AWS resources. OpsItems are aggregated, across services, in a central location.
• You can view service-specific and contextually relevant data for OpsItems that are automatically
generated by Amazon CloudWatch Events and CloudWatch Application Insights for .NET and SQL
Server.
• You can specify the Amazon Resource Name (ARN) of a resource related to an OpsItem. By specifying
related resources, OpsCenter uses built-in logic to help you avoid creating duplicate OpsItems.
• You can view details and resolution information about similar OpsItems.
• You can quickly view information about and execute Systems Manager Automation documents
(runbooks) to resolve issues.

What Are the Features of OpsCenter?

• Automated and manual OpsItem creation

OpsCenter is integrated with Amazon CloudWatch Events. This means you can create CloudWatch rules
that automatically create OpsItems for any AWS service that publishes events to CloudWatch Events.
You can also manually create OpsItems.

OpsCenter is also integrated with Amazon CloudWatch Application Insights for .NET and SQL Server.
This means you can automatically create OpsItems for problems detected in your applications.
• Detailed and searchable OpsItems

Each OpsItem includes multiple fields of information, including a title, ID, priority, description,
the source of the OpsItem, and the date/time it was last updated. Each OpsItem also includes the
following configurable features:
• Status: Open, In progress, Resolved, or Open and In progress.
• Related resources: A related resource is the impacted resource or the resource that triggered the
Amazon CloudWatch Events event that created the OpsItem. Each OpsItem includes a Related

110
 AWS Systems Manager User Guide
What Are the Features of OpsCenter?

resources section where OpsCenter automatically lists the Amazon Resource Name (ARN) of the
related resource. You can also manually specify ARNs of related resources. For some ARN types,
OpsCenter automatically creates a deep link that displays details about the resource without having
to visit other console pages to view that information. For example, if you specify the ARN of an EC2
instance, you can view all of the EC2-provided details about that instance in OpsCenter. You can
manually add the ARNs of additional related resources. Each OpsItem can list a maximum of 100
related resource ARNs. For more information, see Working with Related Resources (p. 125).
• Related and Similar OpsItems: The Related OpsItems feature lets you specify the IDs of OpsItems
that are in some way related to the current OpsItem. The Similar OpsItem feature automatically
reviews OpsItem titles and descriptions and then lists other OpsItems that may be related or of
interest to you.
• Searchable and private operational data: Operational data is custom data that provides useful
reference details about the OpsItem. For example, you can specify log files, error strings, license
keys, troubleshooting tips, or other relevant data. You enter operational data as key-value pairs. The
key has a maximum length of 128 characters. The value has a maximum size of 20 KB.

This custom data is searchable, but with restrictions. For the Searchable operational data feature,
all users with access to the OpsItem Overview page (as provided by the DescribeOpsItems API
action) can view and search on the specified data. For the Private operational data feature, the
data is only viewable by users who have access to the OpsItem (as provided by the GetOpsItem API
action).
• Deduplication: By specifying related resources, OpsCenter uses built-in logic to help you avoid
creating duplicate OpsItems. Additionally, OpsItems that are automatically created from an event in
CloudWatch include a deduplication string to reduce the number of duplicate OpsItems. For more
information, see Reducing Duplicate OpsItems (p. 130).
• Easy remediation using runbooks

Each OpsItem includes a Runbooks section with a list of Systems Manager Automation documents
that you can use to automatically remediate common issues with AWS resources. After you execute a
runbook from an OpsItem, the runbook is automatically associated with the related resource of the
OpsItem for future reference and easy execution. Additionally, if you automatically set up OpsItem
rules in CloudWatch by using OpsCenter, then CloudWatch automatically associates runbooks for
common events. For more information, see Remediating OpsItem Issues Using Systems Manager
Automation (p. 133).
• Change notification: You can specify the ARN of an Amazon Simple Notification Service (SNS) topic
and publish notifications anytime an OpsItem is changed or edited. The SNS topic must exist in the
same AWS Region as the OpsItem.
• Comprehensive OpsItem search capabilities: OpsCenter provides multiple search options to help you
quickly locate OpsItems. Here a few examples of how you can search: OpsItem ID, Title, Last modified
time, Operational data value, Source, and Automation ID of a runbook execution, to name a few. You
can further limit search results by using status filters.
• OpsItem summary reports

OpsCenter includes a summary report page that automatically displays the following sections:
• Status summary: a summary of OpsItems by status (Open, In progress, Resolved, Open and In
progress).
• Sources with most open OpsItems: a breakdown of the top AWS services with open OpsItems.
• OpsItems by source and age: a count of OpsItems grouped by source and days since creation.

For more information about viewing OpsCenter summary reports, see Viewing OpsCenter Summary
Reports (p. 136).
• IAM access control

By using AWS Identity and Access Management (IAM) policies, you can control which members of your
organization can create, view, list, and update OpsItems. You can also assign tags to OpsItems and

111
 AWS Systems Manager User Guide
How Does OpsCenter Work with Amazon
CloudWatch Events? Which Service Should I Use?

then create IAM policies that give access to users and groups based on tags. For more information, see
Getting Started with OpsCenter (p. 113).
• Logging and auditing capability support

You can audit and log OpsCenter user actions in your AWS account through integration with other
AWS services. For more information, see Auditing and Logging OpsCenter Activity (p. 140).
• Console, CLI, PowerShell, and SDK access to OpsCenter capabilities

You can work with OpsCenter by using the AWS Systems Manager console, AWS CLI, AWS Tools for
PowerShell, or the AWS SDK of your choice.

How Does OpsCenter Work with Amazon CloudWatch

Events? Which Service Should I Use?
Amazon CloudWatch Events delivers a near real-time stream of system events that describe changes in
AWS resources. Using simple rules that you can quickly set up, you can match events and route them to
one or more target functions or streams. Generally speaking, CloudWatch Events lets you know there is a
problem with your resources.

OpsCenter helps you investigate and remediate the problem. OpsCenter brings together data from
CloudWatch Events or data entered manually by engineers so that your engineers can perform a
thorough investigation. OpsCenter also provides Automation runbooks for quickly remediating
those issues. OpsCenter integrates with CloudWatch Events by enabling you to automatically create
OpsItems (or you can manually create OpsItems) to address the following types of issues: performance
degradation, state changes, execution failures, maintenance notifications, and security alerts.

Does OpsCenter Integrate with My Existing Case

Management System?
OpsCenter is designed to complement your existing case management systems. You can integrate
OpsItems into your existing case management system by using public API actions. You can also
maintain manual lifecycle workflows in your current systems and use OpsCenter as an investigation and
remediation hub.

For information about OpsCenter public API actions, see the following API actions in the AWS Systems
Manager API Reference.

• CreateOpsItem
• DescribeOpsItems
• GetOpsItem
• GetOpsSummary
• UpdateOpsItem

Is There a Charge to Use OpsCenter?

Yes. For more information, see AWS Systems Manager Pricing.

112
 AWS Systems Manager User Guide
Does OpsCenter Work with My On-
Premises and Hybrid Managed Instances?

Does OpsCenter Work with My On-Premises and

Hybrid Managed Instances?
Yes. You can use OpsCenter to investigate and remediate issues with your on-premises managed
instances that are configured for Systems Manager. For more information about setting up and
configuring on-premises servers and virtual machines for Systems Manager, see Setting Up AWS Systems
Manager for Hybrid Environments (p. 41).

What are the resource limits for OpsCenter?

Resource Default limit

Total number of OpsItems allowed per account 500,000

per AWS Region (including Open and Resolved
OpsItems)

Maximum number of OpsItems per account per 10,000

month

Maximum operational data value size 20 KB

Maximum number of associated Automation 10

runbooks per OpsItem

Maximum number of Automation runbook 10

executions stored in operational data under a
single associated runbook

Maximum number of related resources you can 100

specify per OpsItem

Maximum number of related OpsItems you can 10

specify per OpsItem

Maximum length of a deduplication string 64 characters

Topics
• Getting Started with OpsCenter (p. 113)
• Creating OpsItems (p. 119)
• Working with OpsItems (p. 125)
• Remediating OpsItem Issues Using Systems Manager Automation (p. 133)
• Viewing OpsCenter Summary Reports (p. 136)
• Supported Resources Reference (p. 136)
• Auditing and Logging OpsCenter Activity (p. 140)

Getting Started with OpsCenter

Complete the following steps to get started with OpsCenter.

Topics
• Step 1: Configuring CloudWatch Events Permissions for Automatically Creating OpsItems (p. 114)
• Step 2: Configuring User or Group Permissions for OpsCenter (p. 115)

113
 AWS Systems Manager User Guide
Getting Started with OpsCenter

• Step 3: (Optional) Create OpsItem Guidelines for Your Organization (p. 118)

Before You Begin

Before you get started with OpsCenter, review the pricing details. For more information, see AWS
Systems Manager Pricing. Also, verify that your IAM user, group, or role has permission to use Systems
Manager features and capabilities. For more information, see Setting Up AWS Systems Manager (p. 23).
Note
OpsCenter enables you to remediate issues with AWS resources by using Systems Manager
Automation documents (runbooks). To use this remediation capability, you must have
permission to run Systems Manager Automation documents. For more information, see Getting
Started with Automation (p. 144).

Step 1: Configuring CloudWatch Events Permissions for

Automatically Creating OpsItems
You can configure Amazon CloudWatch Events to automatically create OpsItems in response to events,
such as a state change for an AWS resource, a change in security settings, or a service unavailable state.
By default, Amazon CloudWatch Events doesn't have permission to create OpsItems. Grant permission
by using an AWS Identity and Access Management (IAM) policy. You assign the policy to a role, and then
attach the role to CloudWatch Events.

This section includes the following procedures.

• To create an OpsCenter policy for CloudWatch Events (p. 114)

• To create an OpsCenter role for CloudWatch Events (p. 115)
• To attach the OpsCenter policy to the OpsCenter role for CloudWatch Events (p. 115)

Use the following procedure to create an IAM policy that enables CloudWatch Events to automatically
create OpsItems.

To create an OpsCenter policy for CloudWatch Events

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Policies.
3. Choose Create policy.
4. Choose the JSON tab.
5. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:CreateOpsItem",
"Resource": "*"
}
]
}

6. Choose Review policy.

7. On the Review policy page, for Name, enter a name. For example: OpsCenter-CWE-Policy.
8. For Description, enter information about this policy that identifies its purpose.
9. Choose Create policy.

114
 AWS Systems Manager User Guide
Getting Started with OpsCenter

Use the following procedure to create an IAM role that enables CloudWatch Events to automatically
create OpsItems in OpsCenter.

To create an OpsCenter role for CloudWatch Events

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Choose Create role.
4. On the Create role page, under Select type of trusted entity, verify that AWS service is selected.
5. Under Choose the service that will use this role, choose CloudWatch Events.
6. Under Select your use case, choose CloudWatch Events, and then choose Next: Permissions.
7. On the Permissions page, leave the default settings and choose Next: Tags.
8. (Optional) On the Tags page, specify key-value tag pairs, and then choose Next: Review.
9. On the Review page, for Role name, enter a name. For example: OpsItem-CWE-Role.
10. For Description, either leave the default description or enter information about this role that
identifies its purpose.
11. Choose Create role.

Use the following procedure to attach the policy you created earlier to the role you just created.

To attach the OpsCenter policy to the OpsCenter role for CloudWatch Events

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Locate the role you just created.
4. Choose the name of the role to open the Summary page.
5. (Optional) You can detach the policies that were automatically assigned to this role when you
created it. Choose the X beside each policy to detach it.
6. Choose Attach policies.
7. On the Attach permissions page, locate the OpsCenter policy that you created earlier.
8. Choose this policy, and then choose Attach policy. IAM returns you to the Roles page.
9. Choose the name of the role to open the Summary page.
10. Copy the role ARN. You must specify this ARN when you configure OpsCenter to automatically
create OpsItems by using CloudWatch Events. For more information, see Enabling the Default
CloudWatch Events Rules for Automatically Creating OpsItems (p. 119).

CloudWatch Events now has the required permissions to automatically create OpsItems in OpsCenter.

Step 2: Configuring User or Group Permissions for OpsCenter

OpsItems can only be viewed or edited in the account where they were created. You can't share or
transfer OpsItems across AWS accounts. For this reason, we recommend that you configure permissions
for OpsCenter in the AWS account that is used to run your AWS workloads. You can then create AWS
Identity and Access Management (IAM) users or groups in that account. In this way, multiple operations
engineers or IT professionals can create, view, and edit OpsItems in the same AWS account.

OpsCenter uses the following API actions. You can use all features of OpsCenter if your IAM user, group,
or role has access to these actions. You can also create more restrictive access, as described later in this
section.

115
 AWS Systems Manager User Guide
Getting Started with OpsCenter

• CreateOpsItem
• DescribeOpsItems
• GetOpsItem
• GetOpsSummary
• UpdateOpsItem

The following procedure describes how to add a full-access inline policy to an IAM user. If you prefer, you
can specify read-only permission by assigning the following inline policy to a user's account, group, or
role.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetOpsItem",
"ssm:GetOpsSummary",
"ssm:DescribeOpsItems"
],
"Resource": "*"
}
]
}

For more information about creating and editing IAM policies, see Creating IAM Policies in the IAM User
Guide. For information about how to assign this policy to an IAM group, see Attaching a Policy to an IAM
Group.

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users.
3. In the list, choose a name.
4. Choose the Permissions tab.
5. On the right side of the page, under Permission policies, choose Add inline policy.
6. Choose the JSON tab.
7. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetOpsItem",
"ssm:UpdateOpsItem",
"ssm:DescribeOpsItems",
"ssm:CreateOpsItem",
"ssm:GetOpsSummary"

],
"Resource": "*"
}
]
}

8. Choose Review policy.

116
 AWS Systems Manager User Guide
Getting Started with OpsCenter

9. On the Review policy page, for Name, enter a name for the inline policy. For example: OpsCenter-
Access-Full.
10. Choose Create policy.

Restricting Access to OpsItems by Using Tags

You can also restrict access to OpsItems by using an inline IAM policy that specifies tags. The policy uses
the following format.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"One_or_more_OpsItem_API_actions"
],
"Resource": "*"
,
"Condition": { "StringEquals": { "ssm:resourceTag/tag_key": "tag_value" } }
}
]
}

Here is an example that species a tag key of Department and a tag value of Finance. With this policy,
the user can only call the GetOpsItem API action to view OpsItems that were previously tagged with
Key=Department and Value=Finance. Users can't view any other OpsItems.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetOpsItem"
],
"Resource": "*"
,
"Condition": { "StringEquals": { "ssm:resourceTag/Department": "Finance" } }
}
]
}

Here is an example that species API actions for viewing and updating OpsItems. This policy also specifies
two sets of tag key-value pairs: Department-Finance and Project-Unity.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:GetOpsItem",
"ssm:UpdateOpsItem"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"ssm:resourceTag/Department":"Finance",

117
 AWS Systems Manager User Guide
Getting Started with OpsCenter

"ssm:resourceTag/Project":"Unity"
}
}
}
]
}

For information about adding tags to an OpsItem, see Creating OpsItems Manually (p. 121).

Step 3: (Optional) Create OpsItem Guidelines for Your

Organization
We recommend that each organization create a simple set of guidelines that promote consistency when
creating and editing OpsItems. Guidelines make it easier for users to locate and resolve OpsItems. The
guidelines for your organization should define best practices when users enter information into the
following OpsItem fields.
Note
Amazon CloudWatch Events populates the Title, Source, and Description fields of automatically
generated OpsItems. You can edit the Title and the Description fields, but you can't edit the
Source field.

Field Description

Title Guidelines should encourage a consistent OpsItem

naming experience. For example, your guidelines
might require that each title include information
about the impacted resource, the status, the
environment, and the name or the alias of the
engineer actively working the issue, if applicable.
All OpsItems created by CloudWatch include a
title that describes the event that caused the
creation of the OpsItem, but you can edit these
titles.

You can search OpsItems for Title:contains. If your

naming guidelines encourage consistent use of
keywords, you improve your search results.

Source Guidelines can include specifying IDs, software

version numbers (if applicable) or other relevant
data to help users identify the origin of the issue.
You can't edit the Source field after the OpsItem
is created.

Priority (Optional) Guidelines include determining the

highest and lowest priority for your organization,
and any service-level agreements based on
priority. You can specify priority from 1 to 5.

Description Guidelines should suggest how much detail about

the issue to include and any steps (if applicable)
for reproducing the issue.

Notifications Guidelines should suggest which Amazon Simple

Notification Service (SNS) topic Amazon Resource
Name (ARN) to specify when creating or editing
OpsItems. Be aware that SNS notifications are

118
 AWS Systems Manager User Guide
Creating OpsItems

Field Description
region-specific. This means you must specify
an ARN that is in the same AWS Region as the
OpsItem.

Related Resources Guidelines can include details about which

Resources should or shouldn't have an ARN
specified. For supported AWS resource types,
the ARN creates a deep link to details about the
Resource.

Operational data You can specify custom data for each OpsItem
that provides context about the issue and other
relevant data for future reference. You can specify
searchable custom data. All users with access to
the OpsItem Overview page can search for and
view this data. You can also specify private custom
data that is only viewable by users who have
access to this OpsItem.

Guidelines could specify structure and standards

for key-value pairs. These key-value pairs can
describe operational data and resolution details,
leading to improved search results.

Creating OpsItems
You can create OpsItems automatically or manually. To automatically create OpsItems, you can choose
a bulk option that configures multiple services in Amazon CloudWatch Events to create OpsItems for
common resource issues. Or, if you prefer, you can selectively configure SSM OpsItems as the target of
specific events in CloudWatch Events.

This section includes the following topics.

• Enabling the Default CloudWatch Events Rules for Automatically Creating OpsItems (p. 119)
• Configuring CloudWatch Events to Automatically Create OpsItems for Specific Events (p. 121)
• Integrating with CloudWatch Application Insights for .NET and SQL Server (p. 121)
• Creating OpsItems Manually (p. 121)

Enabling the Default CloudWatch Events Rules for

Automatically Creating OpsItems
This section describes how to configure the default CloudWatch Events rules for automatically creating
OpsItems in response to the following events from AWS services. Enabling these default rules is optional,
but recommended. If you don't want CloudWatch Events to create OpsItems for these events, then you
can specify OpsCenter as the target of specific CloudWatch Events events. For more information, see
Configuring CloudWatch Events to Automatically Create OpsItems for Specific Events (p. 121).

AWS Service Event

Amazon EC2 Instance State Change (Stopped,

Terminated)

119
 AWS Systems Manager User Guide
Creating OpsItems

AWS Service Event

Amazon EC2 SSM Maintenance Window Execution

(Failed, Timed Out

Amazon EBS Snapshot Notification (Copy, Create,

Share, Failed)

Amazon EC2 Auto Scaling EC2 Instance (Launch Unsuccessful,

Termination Unsuccessful

AWS Health Amazon Relational Database Service

(RDS) Maintenance Scheduled

AWS Health RDS Issue Notification (example: RDS

Connectivity Issue)

AWS Health EC2 Maintenance Scheduled

AWS Health EC2 Issue Notification (example: Instance

Auto Recovery Failure)

AWS Health EBS Issue Notification (example: Degraded

EBS Volume Performance)

Note
In the following procedure, you must specify an IAM role with a permissions policy that enables
CloudWatch Events to create OpsItems in OpsCenter. For information about how to create this
role, see Getting Started with OpsCenter (p. 113).

To configure CloudWatch Events to automatically create OpsItems from multiple AWS

services

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose Configure sources.
4. Under Step 2: OpsItem source setup, for IAM Role, paste the ARN of the IAM role ARN that enables
CloudWatch Events to create OpsItems in OpsCenter.
5. Choose Set up.
6. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
7. In the navigation pane, choose Rules. Verify that the list includes new rules that begin with
SSMOpsItems-*, such as SSMOpsItems-AutoScaling-instance-launch-failure and SSMOpsItems-
RDS-issue.
Note
If you want, you can edit the new rules in CloudWatch.

After an OpsItem is created from an event, you can view the event details by opening the OpsItem and
scrolling down to the Operational data section.

120
 AWS Systems Manager User Guide
Creating OpsItems

For information about how to configure the options in an OpsItem, see Working with
OpsItems (p. 125).

Configuring CloudWatch Events to Automatically Create

OpsItems for Specific Events
Use the following procedure to configure SSM OpsItems as the target of a CloudWatch event. When
CloudWatch receives the event, it creates a new OpsItem.

To configure OpsCenter as a target of a CloudWatch event

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the navigation pane, choose Events, and then either choose to create a new rule or edit an
existing rule.
3. After specifying or verifying the details of the rule, choose Add target.
4. In the Select target type list, choose SSM OpsItem.
5. For Configure input, verify that Matched event is selected.
6. In the permissions section, choose Create a new role for this specific resource to create a new role
with the required permissions. Or, choose Use existing role and choose the IAM role you created
that gives CloudWatch permission to create OpsItems in OpsCenter. For more information about the
required role and permissions, see Getting Started with OpsCenter (p. 113).
7. Choose Configure details. CloudWatch opens the Step 2: Configure rule details page.
8. For Name, type a descriptive name that identifies the purpose of this rule.
9. For Description, type information about this rule.
10. Verify that the Enabled option is selected, and then choose Create rule.
11. In the navigation pane, choose Rules. Verify that the list includes a new rule that begins with
AwsSSMOpsCenter-*, such as AwsSSMOpsCenter-EC2 or AwsSSMOpsCenter-DynamoDB.

After an OpsItem is created from an event, you can view the event details by opening the OpsItem and
scrolling down to the Private operational data section.

For information about how to configure the options in an OpsItem, see Working with
OpsItems (p. 125).

Integrating with CloudWatch Application Insights for .NET and

SQL Server
OpsCenter integrates with Amazon CloudWatch Application Insights for .NET and SQL Server. This means
you can automatically create OpsItems for problems detected in your applications. For information
about how to configure Application Insights to create OpsItems, see Setting Up Your Application in the
Amazon CloudWatch User Guide.

Creating OpsItems Manually

This section includes procedures for manually create OpsItems for issues that aren't automatically
created by Amazon CloudWatch Events.

Before You Begin

121
 AWS Systems Manager User Guide
Creating OpsItems

If you manually create an OpsItem for an impacted AWS resource, then collect information about that
resource so that you can create an Amazon Resource Name (ARN). If you specify an ARN when you
create an OpsItem, then OpsCenter automatically creates a deep link to detailed information about
the resource. For example, if you specify the ARN of an impacted EC2 instance, then OpsCenter creates
a deep link to the details about that instance. For information about how to create an ARN, see the
Amazon Resource Names (ARNs) and AWS Service Namespaces in the Amazon Web Services General
Reference.
Note
OpsCenter does not support creating deep links for all ARN types. To view a list of resources the
support deep links based on ARNs, see Supported Resources Reference (p. 136).

This section includes the following procedures.

• To manually create an OpsItem (console) (p. 122)

• To manually create an OpsItem (AWS CLI) (p. 122)

To manually create an OpsItem (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose Create OpsItem. If you don't see this button, then choose the OpsItems tab, and then
choose Create OpsItem.
4. For Title, enter a descriptive name to help you understand the purpose of the OpsItem.
5. For Source, enter the type of impacted AWS resource or other source information to help users
understand the origin of the OpsItem.
Note
You can't edit the Source field after you create the OpsItem.
6. For Priority, choose the priority level.
7. For Description, enter information about this OpsItem including (if applicable) steps for reproducing
the issue.
8. For Deduplication string, enter words the system should use to check for duplicate OpsItems. For
more information about deduplication strings, see Reducing Duplicate OpsItems (p. 130).
9. (Optional) For Notifications, specify the SNS topic ARN where you want notifications sent when this
OpsItem is updated. You must specify an Amazon SNS ARN that is in the same AWS Region as the
OpsItem.
10. (Optional) Under Related resources, choose Add to specify the ARN of the impacted resource and
any related resources.
11. Choose Create OpsItem.

If successful, the OpsItem opens. For information about how to configure the options in an OpsItem, see
Working with OpsItems (p. 125).

To manually create an OpsItem (AWS CLI)

1. Open the AWS CLI and run the following command to create an OpsItem.

aws ssm create-ops-item --title "Descriptive_title" --description

"Information_about_the_issue" --priority Number_between_1_and_5 --
source Source_of_the_issue --operational-data Up_to_20_KB_of_data_or_path_to_JSON_file
--notifications Arn="SNS_ARN_in_same_Region" --tags "Key=key_name,Value=a_value"

Here are some examples.

122
 AWS Systems Manager User Guide
Creating OpsItems

Linux

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log
clean up may have failed which caused the disk to be full" --priority 2 --source
ec2 --operational-data '{"EC2":{"Value":"12345","Type":"SearchableString"}}'
--notifications Arn="arn:aws:sns:us-west-1:12345678:TestUser1" --tags
"Key=EC2,Value=ProductionServers"

The following command uses the /aws/resources key in OperationalData to create an OpsItem
with an Amazon DynamoDB related resource.

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean
up may have failed which caused the disk to be full" --priority 2 --source ec2
--operational-data '{"/aws/resources":{"Value":"[{\"arn\": \"arn:aws:dynamodb:us-
west-2:12345678:table/OpsItems\"}]","Type":"SearchableString"}}' --notifications
Arn="arn:aws:sns:us-west-2:12345678:TestUser"

The following command uses the /aws/automations key in OperationalData to create an OpsItem
that specifies the AWS-ASGEnterStandby document as an associated automation runbook.

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log
clean up may have failed which caused the disk to be full" --priority 2 --
source ec2 --operational-data '{"/aws/automations":{"Value":"[{\"automationId
\": \"AWS-ASGEnterStandby\", \"automationType\": \"AWS::SSM::Automation
\"}]","Type":"SearchableString"}}' --notifications Arn="arn:aws:sns:us-
west-2:12345678:TestUser"

Windows

aws ssm create-ops-item --title "RDS instance not responding" --description

"RDS instance not responding to ping" --priority 1 --source RDS --
operational-data={\"RDS\":{\"Value\":\"abcd\",\"Type\":\"SearchableString
\"}} --notifications Arn="arn:aws:sns:us-west-1:12345678:TestUser1" --tags
"Key=RDS,Value=ProductionServers"

The following command uses the /aws/resources key in OperationalData to create an OpsItem
with an Amazon EC2 instance related resource.

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean
up may have failed which caused the disk to be full" --priority 2 --source ec2 --
operational-data={\"/aws/resources\":{\"Value\":\"[{\\"""arn\\""":\\"""arn:aws:ec2:us-
east-1:123456789012:instance/i-1234567890abcdef0\\"""}]\",\"Type\":\"SearchableString
\"}}

The following command uses the /aws/automations key in OperationalData to create an OpsItem
that specifies the AWS-RestartEC2Instance document as an associated automation runbook.

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean
up may have failed which caused the disk to be full" --priority 2 --source ec2 --
operational-data={\"/aws/automations\":{\"Value\":\"[{\\"""automationId\\""":\\"""AWS-
RestartEC2Instance\\”"",\\"""automationType\\""":\\"""AWS::SSM::Automation\\"""}]\",
\"Type\":\"SearchableString\"}}

Specify operational data from a file

123
 AWS Systems Manager User Guide
Creating OpsItems

When you create an OpsItem, you can specify operational data from a file. The file must be a JSON
file, and the contents of the file must use the following format:

{
"key_name": {
"Type": "SearchableString",
"Value": "Up to 20 KB of data"
}
}

Here is an example.

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean
up may have failed which caused the disk to be full" --priority 2 --source ec2 --
operational-data file:///Users/TestUser1/Desktop/OpsItems/opsData.json --notifications
Arn="arn:aws:sns:us-west-1:12345678:TestUser1" --tags "Key=EC2,Value=Production"

Note
For information about how to enter JSON-formatted parameters on the command line
on different local operating systems, see Using Quotation Marks with Strings in the AWS
Command Line Interface User Guide.

The system returns information like the following:

{
"OpsItemId": "oi-1a2b3c4d5e6f"
}

2. Run the following command to view details about the OpsItem you created.

aws ssm get-ops-item --ops-item-id ID

The system returns information like the following:

{
"OpsItem": {
"CreatedBy": "arn:aws:iam::12345678:user/TestUser",
"CreatedTime": 1558386334.995,
"Description": "Log clean up may have failed which caused the disk to be full",
"LastModifiedBy": "arn:aws:iam::12345678:user/TestUser",
"LastModifiedTime": 1558386334.995,
"Notifications": [
{
"Arn": "arn:aws:sns:us-west-1:12345678:TestUser"
}
],
"Priority": 2,
"RelatedOpsItems": [],
"Status": "Open",
"OpsItemId": "oi-1a2b3c4d5e6f",
"Title": "EC2 instance disk full",
"Source": "ec2",
"OperationalData": {
"EC2": {
"Value": "12345",
"Type": "SearchableString"
}
}
}

124
 AWS Systems Manager User Guide
Working with OpsItems

3. Run the following command to update the OpsItem. This command changes the status from Open
(the default) to InProgress.

aws ssm update-ops-item --ops-item-id ID --status InProgress

The command has no output.

4. Run the following command again to verify that the status changed to InProgress

aws ssm get-ops-item --ops-item-id ID

Working with OpsItems

This section describes how to configure the options available in an OpsItem. For information about
creating OpsItems, see Creating OpsItems (p. 119).

Topics
• Working with Related Resources (p. 125)
• Editing OpsItem Details (p. 126)
• Working with Related and Similar OpsItems (p. 128)
• Working with Operational Data (p. 128)
• Reducing Duplicate OpsItems (p. 130)

Working with Related Resources

A related resource is the impacted resource (the resource that needs to be investigated or the resource
that triggered the Amazon CloudWatch Events event that created the OpsItem). Each OpsItem has a
Related resources section. If CloudWatch Events creates the OpsItem, then the system automatically
populates the OpsItem with the Amazon Resource Name (ARN) of the resource. You can also manually
specify ARNs of related resources. For some ARN types, OpsCenter automatically creates a deep link that
displays details about the resource without having to visit other console pages to view that information.
For example, you can specify the ARN of an Amazon EC2 instance. In OpsCenter, you can then view
all of the details that Amazon EC2 provides about that instance. To view a list of resource types that
automatically create deep links to related resource, see Supported Resources Reference (p. 136).
Note
You can manually add the ARNs of additional related resources. Each OpsItem can list a
maximum of 100 related resource ARNs.

To view and add related resources

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose the OpsItems tab.
4. Choose an OpsItem ID.

125
 AWS Systems Manager User Guide
Working with OpsItems

5. To view information about the impacted resource, choose the Related resources details tab.

This tab displays information about the resource from several AWS services. Expand the Resource
details section to view information about this resource as provided by the AWS service that hosts
it. You can also toggle through other related resources associated with this OpsItem by using the
Related resources list.
6. To add additional related resources, choose the Overview tab.
7. In the Related resources section, choose Add.
8. For Resource ARN, enter the ARN of the related resource, and then choose Add.
Note
If you don't know the ARN of the resource, you can manually create it. For information
about how to create an ARN, see the Amazon Resource Names (ARNs) and AWS Service
Namespaces in the Amazon Web Services General Reference.

Editing OpsItem Details

The OpsItem details section includes information about the OpsItem, including the description, title,
source, OpsItem ID, and the status, to name a few.

126
 AWS Systems Manager User Guide
Working with OpsItems

For OpsItems that were created automatically, Amazon CloudWatch Events populates the Title, Source,
and Description fields. You can edit the Title and the Description fields, but you can't edit the Source
field.

About OpsItem Status

When you edit an OpsItem, you can specify a status. The Status list includes the following options:

Status Details

Open Active in the system, but not being worked on by

an engineer.

In progress Active in the system and being worked on by an

engineer.

Resolved Not active in the system, but available in Search

and when using the Resolved filter on the
OpsItem Overview page. You can edit a resolved
OpsItem to change the status to Open or In
progress.

You can view reports about OpsItem statuses on the Summary tab. For more information, see Viewing
OpsCenter Summary Reports (p. 136).

About OpsItem Priority

When you edit an OpsItem, you can choose a priority for that OpsItem by choosing a value between
1 and 5. We recommend that your organization determine what each priority level means and a
corresponding service level agreement for each.

About the Notifications Field

When you edit an OpsItem, you can specify the ARN of an SNS topic in the Notifications field. By
specifying an ARN, you ensure that all stakeholders receive a notification when the OpsItem is edited,
including a status change. You may find it helpful to create different ARNs for notifications about
different types of AWS resources or different environments. For more information, see the Amazon
Simple Notification Service Developer Guide.

127
 AWS Systems Manager User Guide
Working with OpsItems

Important
The SNS topic must exist in the same AWS Region as the OpsItem. If they are in different
regions, the system returns an error.

To edit OpsItem details

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose an OpsItem ID to open the details page.
4. In the OpsItem details section, choose Edit.
5. Edit the details of the OpsItem according to the requirements and guidelines specified by your
organization.
6. When you are finished, choose Save.

Working with Related and Similar OpsItems

The Related and Similar OpsItem features are designed to help you investigate operations issues while
providing context about the scope of an issue. In the Related OpsItems section, you can specify a
maximum of 10 IDs for other OpsItems that are related to the current OpsItem. OpsItems can be related
in different ways, including a parent-child relationship between OpsItems, a root cause, or a duplicate.

The Similar OpsItems feature is a system-generated list of OpsItems that may be related or of interest
to you. To generate the list, the system scans the titles and descriptions of all OpsItems and returns
OpsItems that use similar words.

To add a related OpsItem from Similar OpsItems

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose an OpsItem ID to open the details page.
4. In the Related OpsItem section, choose Add.
5. For OpsItem ID, specify an ID.
6. Choose Add.

Working with Operational Data

Operational data is custom data that provides useful reference details about the OpsItem. For example,
you can specify log files, error strings, license keys, troubleshooting tips, or other relevant data. You

128
 AWS Systems Manager User Guide
Working with OpsItems

enter operational data as key-value pairs. The key has a maximum length of 128 characters. The value
has a maximum size of 20 KB. You can enter multiple key-value pairs of operational data.
Important
Operational data keys can't begin with the following: amazon, aws, amzn, ssm, /amazon, /aws, /
amzn, /ssm.

You can choose to make the data searchable by other users in the account or you can restrict search
access. Searchable data means that all users with access to the OpsItem Overview page (as provided by
the DescribeOpsItems API action) can view and search on the specified data. Operational data that is not
searchable is only viewable by users who have access to the OpsItem (as provided by the GetOpsItem API
action).

To add operational data to an OpsItem

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose an OpsItem ID to open the details page.
4. Expand either Operational data.
5. If no operational data exists for the OpsItem, then choose Add. If operational data already exists for
the OpsItem, choose Manage.
6. For Key, specify a word or words to help users understand the purpose of the data. The key can't
begin with the following: amazon, aws, amzn, ssm, /amazon, /aws, /amzn, /ssm.
7. For Value, specify the data.
8. Choose Save.

After you create operational data, you can edit the key and the value, remove the operational data, or
add additional key-value pairs by choosing Manage.

129
 AWS Systems Manager User Guide
Working with OpsItems

Note
You can filter OpsItems by using the Operational data operator on the OpsItems
page. In the Search box, choose Operational data, and then enter a key-value
pair in JSON. You must enter the key-value pair by using the following format:
{"key":"key_name","value":"a_value"}

Reducing Duplicate OpsItems

OpsCenter uses a combination of built-in logic and configurable deduplication strings to help avoid
creating duplicate OpsItems. Deduplication built-in logic is applied anytime the CreateOpsItem API
action is called. When creating the OpsItem, Systems Manager creates and stores a hash based on the
deduplication string and the resource that trigged the OpsItem. When a request is made to create a new
OpsItem, the system checks the deduplication string of the new request. If a matching hash exists for
this deduplication string, then Systems Manager doesn't create a new OpsItem.

Note the following information about OpsCenter and deduplication:

• Deduplication strings are not case sensitive. If the system finds a matching deduplication string in an
OpsItem, regardless of casing, the new OpsItem isn't created.
• If the system finds a matching deduplication string in an OpsItem, and that OpsItem has a status of
Open, then the new OpsItem isn't created. If a matching deduplication string is found in an OpsItem
that has a status of Resolved, then the system creates a new OpsItem.
• If the system finds a matching deduplication string in an OpsItem, but the resources are different, then
the system creates the new OpsItem.

Configuring Deduplication Strings

OpsCenter includes the following options for configuring deduplication strings.

• Edit preconfigured deduplication strings: Each of the OpsItem default CloudWatch Events rules
includes a preconfigured deduplication string. You can edit these deduplication strings in CloudWatch
Events.
• Manually specify deduplication strings: You can enter a deduplication string by using either the
Deduplication string field in the console or the OperationalData parameter when you create a new
OpsItem by using either the AWS CLI or AWS Tools for Windows PowerShell.

After the system creates an OpsItem, it populates the Deduplication string field, if a string was
specified. Here's an example.

130
 AWS Systems Manager User Guide
Working with OpsItems

After you create an OpsItem, you can't edit or change the deduplication strings in that OpsItem.

This sections includes the following procedures for configuring deduplication strings.

• Editing a deduplication String in an OpsCenter Default CloudWatch Events Rule (p. 131)
• Specifying a deduplication String by Using the AWS CLI (p. 132)

Note
For information about entering deduplication strings when you manually create an OpsItem in
the console, see Creating OpsItems Manually (p. 121).

Editing a deduplication String in an OpsCenter Default CloudWatch Events Rule

Use the following procedure to specify a deduplication string for a CloudWatch Events rule that targets
OpsCenter.

To edit a deduplication string in an OpsItem default CloudWatch Events rule

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the navigation pane, choose Rules.
3. Choose a rule, and then choose Actions, Edit.

4. In the Targets section, expand the lower Input transformer field and locate the
"operationalData": { "/aws/dedup" JSON entry and the deduplication strings that you want
to edit.

131
 AWS Systems Manager User Guide
Working with OpsItems

The deduplication string entry in CloudWatch Events rules uses the following JSON format.

"operationalData": { "/aws/dedup": {"type": "SearchableString","value": "{\"dedupString

\":\"Words the system should use to check for duplicate OpsItems\"}"}

Here is an example.

"operationalData": { "/aws/dedup": {"type": "SearchableString","value": "{\"dedupString

\":\"SSMOpsCenter-EBS-volume-performance-issue\"}"}

5. Edit the deduplications strings, and then choose Configure details to finish updating the rule.

Specifying a deduplication String by Using the AWS CLI

You can specify a deduplication string when you manually create a new OpsItem by using the AWS CLI.
You enter the deduplication string by using the OperationalData parameter. The parameter syntax
uses JSON, as shown here.

--operational-data '{"/aws/dedup":{"Value":"{\"dedupString\": \"Words the system should use

to check for duplicate OpsItems\"}","Type":"SearchableString"}}'

Here is an example command that specifies a deduplication string of disk full.

Linux

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean up may
have failed which caused the disk to be full" --priority 1 --source ec2 --operational-data
'{"/aws/dedup":{"Value":"{\"dedupString\": \"disk full\"}","Type":"SearchableString"}}'
--tags "Key=EC2,Value=ProductionServers" --notifications Arn="arn:aws:sns:us-
west-1:12345678:TestUser"

132
 AWS Systems Manager User Guide
Remediating OpsItem Issues

Windows

aws ssm create-ops-item --title "EC2 instance disk full" --description "Log clean up may
have failed which caused the disk to be full" --priority 1 --source EC2 --operational-
data={\"/aws/dedup\":{\"Value\":\"{\\"""dedupString\\""":\\"""disk full\\"""}\",\"Type
\":\"SearchableString\"}} --tags "Key=EC2,Value=ProductionServers" --notifications
Arn="arn:aws:sns:us-west-1:12345678:TestUser"

Remediating OpsItem Issues Using Systems Manager

Automation
AWS Systems Manager Automation helps you quickly remediate issues with AWS resources identified
in your OpsItems. Automation uses predefined SSM Automation documents (runbooks) to remediate
commons issues with AWS resources. For example, Automation includes runbooks to perform the
following actions:

• Stop, start, restart, and terminate Amazon Relational Database Service (Amazon RDS) and Amazon
Elastic Compute Cloud (Amazon EC2) instances.
• Create AWS resources such as Amazon Machine Images (AMIs), Amazon Elastic Block Store (Amazon
EBS) snapshots, and Amazon DynamoDB backups.
• Configure a resource to use AWS services, including Amazon CloudWatch Events, AWS CloudTrail, and
Amazon Simple Storage Service (Amazon S3) bucket logging and versioning.
• Attach an AWS Identity and Access Management (IAM) instance profile to an instance.
• Troubleshoot RDP and SSH connectivity issues for EC2 instances.
• Reset access for an EC2 instance.

Each OpsItem in the AWS Management Console includes a Runbooks section, as shown in the following.

If the OpsItem was automatically created by CloudWatch (as a result of the bulk method of setting up
OpsItem rules, as described in Enabling the Default CloudWatch Events Rules for Automatically Creating
OpsItems (p. 119)), then the list of runbooks is automatically filtered to reflect the recommended
runbooks for the specific issue. If the OpsItem was created manually or by specifying OpsItem as a target
of a CloudWatch event, then the Runbooks section lists all SSM Automation runbooks.

You can view information about a runbook by either choosing the runbook name in the console or by
using the Systems Manager Automation Document Details Reference (p. 294).

133
 AWS Systems Manager User Guide
Remediating OpsItem Issues

Using a Runbook to Remediate an OpsItem Issue

When you execute a runbook from an OpsItem, you can run a simple version or you can choose the
Advanced configuration option. The Advanced configuration opens the runbook in Systems Manager
Automation, which provides several options for executing the runbook.

The following procedure describes how to run a simple version of a runbook. For information about
executing an Advanced configuration runbook, see Working with Automation Executions (p. 150).

Before You Begin

Before you execute a runbook to remediate an OpsItem issue, do the following:

• Verify that you have permission to run Systems Manager Automation documents. For more
information, see Getting Started with Automation (p. 144).
• Collect resource-specific ID information for the runbook that you want to execute. For example, if you
want to execute a runbook that restarts an EC2 instance, then you must specify the ID of the instance
to restart.

To execute a runbook to remediate an OpsItem issue

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Choose the OpsItem ID to open the details page.

4. Scroll to the Runbooks section.

5. Use the Runbooks Search bar or the numbers in the upper right to find the runbook that you want
to execute.

134
 AWS Systems Manager User Guide
Remediating OpsItem Issues

6. Choose a runbook, and then choose Execute.

7. Enter the required information for the runbook, and then choose Execute.
8. In the navigation pane, choose Automation, and then choose the Execution ID link to view the steps
and the status of the execution.

Working with Associated Runbooks

After you execute a runbook from an OpsItem, the runbook is automatically associated with the related
resource of that OpsItem for future reference and easy execution. Associated runbooks are ranked higher
than others in the Runbooks list, as shown in the following.

Associated runbooks are also available in the Run automation list in the Related resources section, as
shown in the following.

135
 AWS Systems Manager User Guide
Viewing OpsCenter Summary Reports

Use the following procedure to execute a runbook that has already been associated with a
related resource in an OpsItem. For information about adding related resources, see Working with
OpsItems (p. 125).

To execute a resource-associated runbook to remediate an OpsItem issue

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. Open the OpsItem for which you want to execute a runbook.
4. In the Related resources section, choose the resource on which you want to execute a runbook.
5. Choose Run automation, and then choose the associated runbook that you want to execute.
6. Enter the required information for the runbook, and then choose Execute.
7. In the navigation pane, choose Automation, and then choose the Execution ID link to view the steps
and the status of the execution.

Viewing OpsCenter Summary Reports

OpsCenter includes a summary page that automatically displays the following information:

• OpsItem status summary: a summary of OpsItems by status (Open and In progress, Open, or In
Progress).
• Sources with most open OpsItems: a breakdown of the top AWS services that have open OpsItems.
• OpsItems by source and age: a count of OpsItems, grouped by source and days since creation.

To view the OpsCenter Summary page

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose OpsCenter.
3. On the OpsItems Overview page, choose Summary.
4. Under OpsItems by source and age, choose the Search bar to filter OpsItems according to Source.
Use the list to filter according to Status.

Supported Resources Reference

OpsCenter automatically creates a deep link to the primary resource page when you specify the
Amazon Resource Name (ARN) for the following types of AWS resources. For example, if you specify
the ARN of an Amazon EC2 instance in the Related Resources field, then OpsCenter creates a deep
link to the information about that instance in the Amazon EC2 console. This enables you to view
detailed information about your impacted AWS resources without having to leave OpsCenter. For more
information about adding related resources, see Working with Related Resources (p. 125).

136
 AWS Systems Manager User Guide
Supported Resources Reference

Supported Resources

Resource Name ARN Format

AWS Certificate Manager certificate

arn:aws:acm:region:account-
id:certificate/certificate-id

Amazon EC2 Auto Scaling group

arn:aws:autoscaling:region:account-
id:autoScalingGroup:groupid:autoScalingGroupName/
groupfriendlyname

Amazon CloudFront distribution

arn:aws:cloudfront::account-id:*

AWS CloudFormation stack

arn:aws:cloudformation:region:account-
id:stack/stackname/additionalidentifier

Amazon CloudWatch alarm

arn:aws:cloudwatch:region:account-
id:alarm:alarm-name

AWS CloudTrail trail

arn:aws:cloudtrail:region:account-
id:trail/trailname

AWS CodeBuild project

arn:aws:codebuild:region:account-
id:resourcetype/resource

AWS CodePipeline
arn:aws:codepipeline:region:account-
id:resource-specifier

Amazon DynamoDB table

arn:aws:dynamodb:region:account-
id:table/tablename

Amazon EC2 customer gateway

arn:aws:ec2:region:account-id:customer-
gateway/cgw-id

Amazon EC2 elastic IP

arn:aws:ec2:region:account-id:eip/eipalloc-
id

Amazon EC2 dedicated host

arn:aws:ec2:region:account-id:dedicated-
host/host-id

Amazon EC2 instance

arn:aws:ec2:region:account-
id:instance/instance-id

Amazon EC2 internet gateway

arn:aws:ec2:region:account-id:internet-
gateway/igw-id

137
 AWS Systems Manager User Guide
Supported Resources Reference

Resource Name ARN Format

Amazon EC2 network access control list (ACL)

arn:aws:ec2:region:account-id:network-
acl/nacl-id

Amazon EC2 network interface

arn:aws:ec2:region:account-id:network-
interface/eni-id

Amazon EC2 route table

arn:aws:ec2:region:account-id:route-
table/route-table-id

Amazon EC2 security group

arn:aws:ec2:region:account-id:security-
group/security-group-id

Amazon EC2 subnet

arn:aws:ec2:region:account-
id:subnet/subnet-id

Amazon EC2 volume

arn:aws:ec2:region:account-
id:volume/volume-id

Amazon EC2 VPC

arn:aws:ec2:region:account-id:vpc/vpc-id

Amazon EC2 VPN connection

arn:aws:ec2:region:account-id:vpn-
connection/vpn-id

Amazon EC2 VPN gateway

arn:aws:ec2:region:account-id:vpn-
gateway/vgw-id

AWS Elastic Beanstalk application

arn:aws:elasticbeanstalk:region:account-
id:application/applicationname

Elastic Load Balancing (classic load balancer)

arn:aws:elasticloadbalancing:region:account-
id:loadbalancer/name

Elastic Load Balancing (application load balancer)

arn:aws:elasticloadbalancing:region:account-
id:loadbalancer/app/load-balancer-
name/load-balancer-id

Elastic Load Balancing (network load balancer)

arn:aws:elasticloadbalancing:region:account-
id:loadbalancer/net/load-balancer-
name/load-balancer-id

AWS Identity and Access Management (IAM) group

arn:aws:iam::account-id:group/group-name

IAM policy
arn:aws:iam::account-id:policy/policy-name

138
 AWS Systems Manager User Guide
Supported Resources Reference

Resource Name ARN Format

IAM role
arn:aws:iam::account-id:role/role-name

IAM user
arn:aws:iam::account-id:user/user-name

AWS Lambda function

arn:aws:lambda:region:account-
id:function:function-name

Amazon Relational Database Service (Amazon

arn:aws:rds:region:account-id:cluster:db-
RDS) cluster cluster-name

Amazon RDS database instance

arn:aws:rds:region:account-id:db:db-
instance-name

Amazon RDS subscription

arn:aws:rds:region:account-
id:es:subscription-name

Amazon RDS security group

arn:aws:rds:region:account-
id:secgrp:security-group-name

Amazon RDS cluster snapshot

arn:aws:rds:region:account-id:cluster-
snapshot:cluster-snapshot-name

Amazon RDS subnet group

arn:aws:rds:region:account-
id:subgrp:subnet-group-name

Amazon Redshift cluster

arn:aws:redshift:region:account-
id:cluster:cluster-name

Amazon Redshift parameter group

arn:aws:redshift:region:account-
id:parametergroup:parameter-group-name

Amazon Redshift security group

arn:aws:redshift:region:account-
id:securitygroup:security-group-name

Amazon Redshift cluster snapshot

arn:aws:redshift:region:account-
id:snapshot:cluster-name/snapshot-name

Amazon Redshift subnet group

arn:aws:redshift:region:account-
id:subnetgroup:subnet-group-name

Amazon Simple Storage Service (Amazon S3)

arn:aws:s3:::bucket_name
bucket

139
 AWS Systems Manager User Guide
Auditing and Logging OpsCenter Activity

Resource Name ARN Format

AWS Config recording of AWS Systems Manager

arn:aws:ssm:region:account-id:managed-
managed instance inventory instance-inventory/instance_id

Systems Manager State Manager association

arn:aws:ssm:region:account-
id:association/association_ID

Auditing and Logging OpsCenter Activity

AWS CloudTrail captures OpsCenter API calls made in the AWS Systems Manager console, the AWS CLI,
and the Systems Manager SDK. You can view the information in the CloudTrail console or in an Amazon
Simple Storage Service (Amazon S3) bucket. One bucket is used for all CloudTrail logs for your account.

Logs of OpsCenter actions show create, update, get, and describe OpsItem activities. For more
information about viewing and using CloudTrail logs of Systems Manager activity, see Logging AWS
Systems Manager API Calls with AWS CloudTrail (p. 889).

AWS Resource Groups

A resource group is a collection of AWS resources that are all in the same AWS Region, and that match
criteria provided in a query. (In AWS, a resource is an entity that you can work with. Examples include
an Amazon EC2 instance, an AWS CloudFormation stack, and an Amazon S3 bucket.) You build queries
in the AWS Resource Groups (Resource Groups) console, or pass them as arguments to Resource Groups
commands in the AWS CLI.

With AWS Resource Groups, you can create a custom console that organizes and consolidates
information based on criteria that you specify in tags. After you add resources to a group you created in
Resource Groups, use AWS Systems Manager tools such as Automation to simplify management tasks on
your resource group. You can also use the resource groups you create as the basis for viewing monitoring
and configuration insights in Systems Manager.

For information about granting the IAM users in your account access to Resource Groups and its Tag
Editor in the AWS Management Console, see Create Policies for Tag Editor and Resource Groups (p. 25).

Resources

• AWS Resource Groups User Guide

• AWS CloudTrail User Guide
• AWS Config Developer Guide

Trusted Advisor and Personal Health Dashboards

Hosted by Systems Manager
Systems Manager hosts two online tools to help you provision your resources and monitor your account
for health events. Trusted Advisor is an online tool that provides you real time guidance to help you
provision your resources following AWS best practices. For more information, see Trusted Advisor.

The AWS Personal Health Dashboard provides information about AWS Health events that can affect
your account. The information is presented in two ways: a dashboard that shows recent and upcoming

140
 AWS Systems Manager User Guide
Trusted Advisor and PHD

events organized by category, and a full event log that shows all events from the past 90 days. For more
information, see Getting Started with the AWS Personal Health Dashboard.

141
 AWS Systems Manager User Guide
Automation

AWS Systems Manager Actions &

Change
AWS Systems Manager provides the following capabilities for taking action against or changing your
AWS resources.

Topics
• AWS Systems Manager Automation (p. 142)
• AWS Systems Manager Maintenance Windows (p. 444)

AWS Systems Manager Automation

Systems Manager Automation simplifies common maintenance and deployment tasks of Amazon EC2
instances and other AWS resources. Automation enables you to do the following.

• Build Automation workflows to configure and manage instances and AWS resources.
• Create custom workflows or use pre-defined workflows maintained by AWS.
• Receive notifications about Automation tasks and workflows by using Amazon CloudWatch Events.
• Monitor Automation progress and execution details by using the Amazon EC2 or the AWS Systems
Manager console.

Automation Use Cases

This section includes common uses cases for AWS Systems Manager Automation.

Perform common IT tasks

Automation can simplify common IT tasks such as changing the state of one or more instances (using an
approval workflow) and managing instance states according to a schedule. Here are some examples:

• Use the AWS-StopEC2InstanceWithApproval document to request that one or more AWS Identity
and Access Management (IAM) users approve the instance stop action. After the approval is received,
Automation stops the instance.
• Use the AWS-StopEC2Instance document to automatically stop instances on a schedule by using
Amazon CloudWatch Events or by using a maintenance window task. For example, you can configure
an Automation workflow to stop instances every Friday evening, and then restart them every Monday
morning.
• Use the AWS-UpdateCloudFormationStackWithApproval document to update resources that were
deployed by using CloudFormation template. The update applies a new template. You can configure
the Automation to request approval by one or more IAM users before the update begins.

For information about how to run an Automation workflow by using State Manager, see Running
Automation Workflows with Triggers Using State Manager (p. 182).

Safely perform disruptive tasks in bulk

Systems Manager includes features that help you target large groups of instances by using Amazon EC2
tags, and velocity controls that help you roll out changes according to the limits you define.

142
 AWS Systems Manager User Guide
Automation Use Cases

Use the AWS-RestartEC2InstanceWithApproval document to target an AWS resource group that includes
multiple instances. You can configure the Automation workflow to use velocity controls. For example,
you can specify the number of instances that should be restarted concurrently. You can also specify a
maximum number of errors that are allowed before the Automation workflow is cancelled.

Simplify complex tasks

Automation offers one-click automations for simplifying complex tasks such as creating golden Amazon
Machines Images (AMIs), and recovering unreachable EC2 instances. Here are some examples:

• Use the AWS-UpdateLinuxAmi and AWS-UpdateWindowsAmi documents to create golden AMIs from
a source AMI. You can run custom scripts before and after updates are applied. You can also include
or exclude specific packages from being installed. For examples of how to run these workflows, see
Automation Walkthroughs (p. 400).
• Use the AWSSupport-ExecuteEC2Rescue document to recover impaired instances. An instance can
become unreachable for a variety of reasons, including network misconfigurations, RDP issues, or
firewall settings. Troubleshooting and regaining access to the instance previously required dozens of
manual steps before you could regain access. The AWSSupport-ExecuteEC2Rescue document lets you
regain access by specifying an instance ID and clicking a button. For an example of how to run this
workflow, see Run the EC2Rescue Tool on Unreachable Instances (p. 422).

Enhance operations security

Using delegated administration, you can restrict or elevate user permissions for various types of tasks.

Delegated administration enables you to provide permissions for certain tasks on certain resource
without having to give a user direct permission to access the resources. This improves your overall
security profile. For example, assume that User1 doesn’t have permissions to restart EC2 instances, but
you would like to authorize the user to do so. Instead of allowing User1 direct permissions, you can:

• Create an IAM role with the permissions required to successfully stop and start EC2 instances.
• Create an Automation document and embed the role in the document. (The easiest way to do this is
to customize the AWS-RestartEC2Instance document and embed the role in the document instead of
assigning an Automation service role [or assume role]).
• Modify IAM permissions for User1 and allow the user permission to run the document.

For an example of how to delegate access to an Automation workflow, see Running an Automation
Workflow by Using Delegated Administration (p. 204).

Share best practices

Automation lets you share best practices with rest of your organization.

You can create best practices for resource management in Automation documents and easily share
the documents across AWS Regions and groups. You can also constrain the allowed values for the
parameters the document accepts.

Concepts

AWS Systems Manager Automation uses the following concepts.

Concept Details

Automation document A Systems Manager Automation document

defines the Automation workflow (the actions
that Systems Manager performs on your managed
instances and AWS resources). Automation
includes several pre-defined Automation

143
 AWS Systems Manager User Guide
Getting Started with Automation

Concept Details
documents that you can use to perform common
tasks like restarting one or more Amazon EC2
instances or creating an Amazon Machine
Image (AMI). Documents use JavaScript Object
Notation (JSON) or YAML, and they include steps
and parameters that you specify. Steps run in
sequential order. For more information, see
Working with Automation Documents (p. 217).

Automation action The Automation workflow defined in an

Automation document includes one or more
steps. Each step is associated with a particular
action or plugin. The action determines the
inputs, behavior, and outputs of the step. Steps
are defined in the mainSteps section of your
Automation document. For more information,
see the Systems Manager Automation Actions
Reference (p. 241).

Automation queue Each AWS account can run 25 Automations

simultaneously with a maximum of 75 child
Automations. If you attempt to run more than
this, Systems Manager adds the additional
executions to a queue and displays a status of
Pending. When an Automation completes (or
reaches a terminal state), the first execution in the
queue starts. Each AWS account can queue 1,000
Automation executions.

Contents
• Getting Started with Automation (p. 144)
• Working with Automation Executions (p. 150)
• Working with Automation Documents (p. 217)
• Automation Walkthroughs (p. 400)
• Troubleshooting Systems Manager Automation (p. 433)

Getting Started with Automation

To set up Automation, you must verify user access to the Automation service and situationally configure
roles so that the service can perform actions on your resources. To ensure proper access to Systems
Manager Automation, review the following user and service role requirements.

Verify user access

Verify that you have permission to run Automation workflows. If your AWS Identity and Access
Management (IAM) user account, group, or role is assigned administrator permissions, then you
have access to Systems Manager Automation. If you don't have administrator permissions, then an
administrator must give you permission by assigning the AmazonSSMFullAccess managed policy, or a
policy that provides comparable permissions, to your IAM account, group, or role.
Important
The IAM policy AmazonSSMFullAccess grants permissions to Systems Manager
actions. However, some Automation documents require permissions to other services,

144
 AWS Systems Manager User Guide
Getting Started with Automation

such as the document AWS-ReleaseElasticIP, which requires IAM permissions for

ec2:ReleaseAddress. Therefore, you must review the actions taken in an Automation
document to ensure your IAM user account, group, or role is assigned the necessary permissions
to perform the actions included in the document.

Configure service role access (situational)

Automation workflows can be initiated under the context of a service role (or assume role). This allows
the service to perform actions on your behalf. If you do not specify an assume role, Automation uses the
context of the user who invoked the execution.

However, the following situations require that you specify a service role for Automation:

• When you want to restrict a user's privileges on a resource, but you want the user to run an
Automation workflow that requires elevated privileges. In this scenario, you can create a service role
with elevated privileges and allow the user to run the workflow.
• When you create a State Manager Association that runs an Automation workflow.
• When you have operations that you expect to run longer than 12 hours.

If you need to create a service role for Automation, you can use one of the following methods.

Topics
• Method 1: Use AWS CloudFormation to Configure a Service Role for Automation (p. 145)
• Method 2: Use IAM to Configure Roles for Automation (p. 146)

Method 1: Use AWS CloudFormation to Configure a Service Role

for Automation
You can create a service role for Automation from an AWS CloudFormation template. After you
create the service role, you can specify the service role in Automation workflows using the parameter
AutomationAssumeRole. For information about how to run an Automation workflow using the
Automation service role, see Running an Automation Workflow by Using an IAM Service Role (p. 200).

Topics
• Create the Service Role Using AWS CloudFormation (p. 145)
• Copy Role Information for Automation (p. 146)

Create the Service Role Using AWS CloudFormation

Use the following procedure to create the required IAM role for Systems Manager Automation by using
AWS CloudFormation.

To create the required IAM role

1. Download the AWS-SystemsManager-AutomationServiceRole.zip folder. This folder includes the

AWS-SystemsManager-AutomationServiceRole.yaml AWS CloudFormation template file.
2. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.
3. Choose Create Stack.
4. In the Choose a template section, choose Upload a template to Amazon S3.
5. Choose Browse, and then choose the AWS-SystemsManager-AutomationServiceRole.yaml
AWS CloudFormation template file.

145
 AWS Systems Manager User Guide
Getting Started with Automation

6. Choose Next.
7. On the Specify Details page, in the Stack Name field, enter a name.
8. On the Options page, you don’t need to make any selections. Choose Next.
9. On the Review page, scroll down and choose the I acknowledge that AWS CloudFormation might
create IAM resources option.
10. Choose Create.

AWS CloudFormation shows the CREATE_IN_PROGRESS status for approximately three minutes. The
status changes to CREATE_COMPLETE after the stack is created and your roles are ready to use.
Important
If you run an automation that invokes other services by using an AWS Identity and Access
Management (IAM) service role, be aware that the service role must be configured with
permission to invoke those services. This requirement applies to all AWS Automation
documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-
CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few.
This requirement also applies to any custom Automation documents you create that invoke
other AWS services by using actions that call other services. For example, if you use the
aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few,
then you must configure the service role with permission to invoke those services. You can
enable permissions to other AWS services by adding an IAM inline policy to the role. For
more information, see (Optional) Add an Automation Inline Policy to Invoke Other AWS
Services (p. 147).

Copy Role Information for Automation

Use the following procedure to copy information about the Automation service role from the AWS
CloudFormation console. You must specify these roles when you run an Automation document.
Note
You do not need to copy role information using this procedure if you run the AWS-
UpdateLinuxAmi or AWS-UpdateWindowsAmi documents. These documents already have
the required roles specified as default values. The roles specified in these documents use IAM
managed policies.

To copy the role names

1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

2. Select the check box next to the Automation stack you created in the previous procedure.
3. Choose the Resources tab.
4. Choose the Physical ID link for AutomationServiceRole. The IAM console opens to a summary of
the Automation service role.
5. Copy the Amazon Resource Name (ARN) next to Role ARN. The ARN is similar to the following:
arn:aws:iam::12345678:role/AutomationServiceRole
6. Paste the ARN into a text file to use later.

You have finished configuring the service role for Automation. You can now use the Automation service
role ARN in your Automation documents.

Method 2: Use IAM to Configure Roles for Automation

If you need to create a service role for Systems Manager Automation, complete the following tasks.
For more information on when a service role is required for Automation, see Getting Started with
Automation (p. 144).

146
 AWS Systems Manager User Guide
Getting Started with Automation

Tasks
• Task 1: Create a Service Role for Automation (p. 147)
• Task 2: Add a Trust Relationship for Automation (p. 148)
• Task 3: Attach the iam:PassRole Policy to Your Automation Role (p. 149)
• Task 4: Configure User Access to Automation (p. 150)

Task 1: Create a Service Role for Automation

Use the following procedure to create a service role (or assume role) for Systems Manager Automation.
Note
You can also use this role in Automation documents, such as the AWS-
CreateManagedLinuxInstance document. Using this role or the ARNs in Automation
documents enables Automation to perform actions in your environment, such as launch new
instances and perform actions on your behalf.

To create an IAM role and allow Automation to assume it

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create role.
3. On the Select type of trusted entity page, under AWS Service, choose EC2.
4. In the Select your use case section, choose EC2, and then choose Next: Permissions.
5. On the Attached permissions policy page, search for the AmazonSSMAutomationRole policy,
choose it, and then choose Next: Review.
6. On the Review page, type a name in the Role name box, and then type a description.
7. Choose Create role. The system returns you to the Roles page.
8. On the Roles page, choose the role you just created to open the Summary page. Note the Role
Name and Role ARN. You will specify the role ARN when you attach the iam:PassRole policy to your
IAM account in the next procedure. You can also specify the role name and the ARN in Automation
documents.

Note
The AmazonSSMAutomationRole policy assigns the Automation role permission to a subset
of AWS Lambda functions within your account. These functions begin with "Automation". If
you plan to use Automation with Lambda functions, the Lambda ARN must use the following
format:
"arn:aws:lambda:*:*:function:Automation*"
If you have existing Lambda functions whose ARNs do not use this format, then you must also
attach an additional Lambda policy to your automation role, such as the AWSLambdaRole
policy. The additional policy or role must provide broader access to Lambda functions within the
AWS account.

(Optional) Add an Automation Inline Policy to Invoke Other AWS Services

If you run an automation that invokes other AWS services by using an IAM service role, the service
role must be configured with permission to invoke those services. This requirement applies to all
AWS Automation documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging,
AWS-CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few. This
requirement also applies to any custom Automation documents you create that invoke other AWS
services by using actions that call other services. For example, if you use the aws:executeAwsApi,
aws:CreateStack, or aws:copyImage actions, to name a few, then you must configure the service
role with permission to invoke those services. You can enable permissions to other AWS services by
adding an IAM inline policy to the role.

147
 AWS Systems Manager User Guide
Getting Started with Automation

To embed an inline policy for a service role (IAM Console)

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. In the list, choose the name of the role that you want to edit.
4. Choose the Permissions tab.
5. Choose Add inline policy.
6. Choose the JSON tab.
7. Enter a JSON policy document for the AWS services you want to invoke. Here are two example JSON
policy documents.

Amazon S3 PutObject and GetObject Example

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::my-bucket-name/*"
}
]
}

Amazon EC2 CreateSnapshot and DescribeSnapShots Example

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"*"
},
{
"Effect":"Allow",
"Action":"ec2:DescribeSnapshots",
"Resource":"*"
}
]
}

For details about the IAM policy language, see IAM JSON Policy Reference in the IAM User Guide.
8. When you are finished, choose Review policy. The Policy Validator reports any syntax errors.
9. On the Review policy page, enter a Name for the policy that you are creating. Review the policy
Summary to see the permissions that are granted by your policy. Then choose Create policy to save
your work.
10. After you create an inline policy, it is automatically embedded in your role.

Task 2: Add a Trust Relationship for Automation

Use the following procedure to configure the service role policy to trust Automation.

148
 AWS Systems Manager User Guide
Getting Started with Automation

To add a trust relationship for Automation

1. In the Summary page for the role you just created, choose the Trust Relationships tab, and then
choose Edit Trust Relationship.
2. Add "ssm.amazonaws.com", as shown in the following example.

{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"",
"Effect":"Allow",
"Principal":{
"Service":[
"ec2.amazonaws.com",
"ssm.amazonaws.com"
]
},
"Action":"sts:AssumeRole"
}
]
}

3. Choose Update Trust Policy.

4. Leave the Summary page open.

Task 3: Attach the iam:PassRole Policy to Your Automation Role

Use the following procedure to attach the iam:PassRole policy to your Automation service role. This
enables the Automation service to pass the role to other services or Systems Manager capabilities when
running Automation workflows.

To attach the iam:PassRole policy to your Automation role

1. In the Summary page for the role you just created, choose the Permissions tab.
2. Choose Add inline policy.
3. On the Create policy page, choose the Visual editor tab.
4. Choose Service, and then choose IAM.
5. Choose Select actions.
6. In the Filter actions text box, type PassRole, and then choose the PassRole option.
7. Choose Resources. Verify that Specific is selected, and then choose Add ARN.
8. In the Specify ARN for role field, paste the Automation role ARN that you copied at the end of Task
1. The system populates the Account and Role name with path fields.
Note
If you want the Automation service role to attach an IAM instance profile role to an EC2
instance, then you must add the ARN of the IAM instance profile role. This allows the
Automation service role to pass the IAM instance profile role to the target EC2 instance.
9. Choose Add.
10. Choose Review policy.
11. On the Review Policy page, type a name and then choose Create Policy.

149
 AWS Systems Manager User Guide
Working with Automation Executions

Task 4: Configure User Access to Automation

If your AWS Identity and Access Management (IAM) user account, group, or role is assigned administrator
permissions, then you have access to Systems Manager Automation. If you don't have administrator
permissions, then an administrator must give you permission by assigning the AmazonSSMFullAccess
managed policy, or a policy that provides comparable permissions, to your IAM account, group, or role.

Use the following procedure to configure a user account to use Automation. The user account you choose
will have permission to configure and run Automation. If you need to create a new user account, see
Creating an IAM User in Your AWS Account in the IAM User Guide.

To configure user access and attach the iam:PassRole policy to a user account

1. In the IAM navigation pane, choose Users, and then choose the user account you want to configure.
2. On the Permissions tab, in the policies list, verify that either the AmazonSSMFullAccess policy is
listed or there is a comparable policy that gives the account permissions to access Systems Manager.
3. Choose Add inline policy.
4. On the Create policy page, choose Visual Editor, and then choose Choose a service.
5. From AWS Services, choose AWS Identity and Access Management.
6. For Actions, enter PassRole in the Filter actions prompt, and choose PassRole.
7. In the Resources section, choose Add ARN, paste the ARN for the Automation service role you
copied at the end of Task 1, and then choose Add.
8. Choose Review policy.
9. On the Review Policy page, provide a Name for the policy and then choose Create policy.

You have finished configuring the required roles for Automation. You can now use the Automation
service role ARN in your Automation documents.

Working with Automation Executions

This section includes information about how to run Systems Manager Automation workflows. For more
examples of how to run Automation workflows, see Automation Walkthroughs (p. 400).

Contents
• Running a Simple Automation Workflow (p. 150)
• Running an Automation Workflow Manually (p. 154)
• Running an Automation Workflow with Approvers (p. 160)
• Running Automation Workflows That Use Targets and Rate Controls (p. 164)
• Running Automation Workflows Based on Triggers (p. 177)
• Running Automation Workflows by Using Different Security Models (p. 196)
• Running Automation Workflows in Multiple AWS Regions and Accounts (p. 208)

Running a Simple Automation Workflow

The following procedures describe how to run a simple Systems Manager Automation workflow
using the AWS Systems Manager console, AWS Command Line Interface (AWS CLI), and AWS Tools
for Windows PowerShell. The workflow runs in the context of the current AWS Identity and Access
Management (IAM) user. This means that you don't need to configure additional IAM permissions as long
as you have permission to run the Automation document and any actions called by the document. If
you have administrator permissions in IAM, then you already have permission to run this Automation
workflow.

150
 AWS Systems Manager User Guide
Working with Automation Executions

Note
For information about how to run an Automation workflow that uses an IAM service role or
more advanced forms of delegated administration, see Running Automation Workflows by
Using Different Security Models (p. 196).

Running a Simple Automation Workflow (Console)

The following procedure describes how to use the Systems Manager console to run a simple Automation
workflow.

To run a simple Automation workflow

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. In the Execution Mode section, choose Simple execution.
7. In the Input parameters section, specify the required inputs. Optionally, you can choose an IAM
service role from the AutomationAssumeRole list.
8. Choose Execute.

The console displays the status of the Automation execution. If the Automation fails to run, see
Troubleshooting Systems Manager Automation (p. 433).

Running a Simple Automation Workflow (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run a simple Automation workflow.

To run a simple Automation workflow

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to start a simple Automation workflow.

Linux

aws ssm start-automation-execution \

--document-name DocumentName \
--parameters ParametersRequiredByDocument

151
 AWS Systems Manager User Guide
Working with Automation Executions

Windows

aws ssm start-automation-execution ^

--document-name DocumentName ^
--parameters ParametersRequiredByDocument

PowerShell

Start-SSMAutomationExecution `
-DocumentName DocumentName `
-Parameter ParametersRequiredByDocument

Here is an example using the document AWS-RestartEC2Instance to restart the specified EC2
instance.

Linux

aws ssm start-automation-execution \

--document-name "AWS-RestartEC2Instance" \
--parameters "InstanceId=i-1234567890abcdef0"

Windows

aws ssm start-automation-execution ^

--document-name "AWS-RestartEC2Instance" ^
--parameters "InstanceId=i-1234567890abcdef0"

PowerShell

Start-SSMAutomationExecution `
-DocumentName AWS-RestartEC2Instance `
-Parameter @{"InstanceId"="i-1234567890abcdef0"}

The system returns information like the following.

Linux

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

Windows

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

PowerShell

4105a4fc-f944-11e6-9d32-0123456789ab

3. Run the following command to retrieve the status of the Automation workflow.

152
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

aws ssm describe-automation-executions \

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

Windows

aws ssm describe-automation-executions ^

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

PowerShell

Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "4105a4fc-f944-11e6-9d32-0123456789ab"}

The system returns information like the following.

Linux

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

Windows

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false

153
 AWS Systems Manager User Guide
Working with Automation Executions

},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

PowerShell

AutomationExecutionId : 4105a4fc-f944-11e6-9d32-0123456789ab
AutomationExecutionStatus : InProgress
AutomationType : Local
CurrentAction : aws:changeInstanceState
CurrentStepName : startInstances
DocumentName : AWS-RestartEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/
Admin
ExecutionEndTime : 1/1/0001 12:00:00 AM
ExecutionStartTime : 7/31/2019 7:17:28 PM
FailureMessage :
LogFile :
MaxConcurrency :
MaxErrors :
Mode : Auto
Outputs : {}
ParentAutomationExecutionId :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
Target :
TargetMaps : {}
TargetParameterName :
Targets : {}

Running an Automation Workflow Manually

The following procedures describe how to use the AWS Systems Manager console, AWS Command Line
Interface (AWS CLI), and AWS Tools for Windows PowerShell to run a Systems Manager Automation
workflow using the manual execution mode. By using the manual execution mode, the Automation
workflow starts in a Waiting status and pauses in the Waiting status between each step. This allows you
to control when the workflow proceeds, which is useful if you need to review the result of a step before
continuing.

The workflow runs in the context of the current AWS Identity and Access Management (IAM) user. This
means that you don't need to configure additional IAM permissions as long as you have permission
to run the Automation document and any actions called by the document. If you have administrator
permissions in IAM, then you already have permission to run this Automation workflow.
Note
For information about how to run an Automation workflow that uses an IAM service role or
more advanced forms of delegated administration, see Running Automation Workflows by
Using Different Security Models (p. 196).

154
 AWS Systems Manager User Guide
Working with Automation Executions

Running an Automation Workflow Step by Step (Console)

The following procedure shows how to use the Systems Manager console to manually run an Automation
workflow step by step.

To run an Automation workflow step by step

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. In the Execution Mode section, choose Manual execution.
7. In the Input parameters section, specify the required inputs. Optionally, you can choose an IAM
service role from the AutomationAssumeRole list.
8. Choose Execute.
9. Choose Execute this step when you are ready to start the first step of the Automation workflow.
The Automation workflow proceeds with step one and pauses before running any subsequent steps
specified in the Automation document you chose in step 3 of this procedure. If the document has
multiple steps, you must select Execute this step for each step for the workflow to proceed.
Note
The console displays the status of the Automation execution. If the Automation fails to run
a step, see Troubleshooting Systems Manager Automation (p. 433).
10. After you complete all steps specified in the Automation document, choose Complete and view
results to finish the Automation workflow and view the results.

Running an Automation Workflow Step by Step (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to manually run an Automation workflow step by step.

To run an Automation workflow step by step

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to start a manual Automation workflow.

155
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

aws ssm start-automation-execution \

--document-name DocumentName \
--mode Interactive \
--parameters ParametersRequiredByDocument

Windows

aws ssm start-automation-execution ^

--document-name DocumentName ^
--mode Interactive ^
--parameters ParametersRequiredByDocument

PowerShell

Start-SSMAutomationExecution `
-DocumentName DocumentName `
-Mode Interactive `
-Parameter ParametersRequiredByDocument

Here is an example using the document AWS-RestartEC2Instance to restart the specified EC2
instance.

Linux

aws ssm start-automation-execution \

--document-name "AWS-RestartEC2Instance" \
--mode Interactive \
--parameters "InstanceId=i-1234567890abcdef0"

Windows

aws ssm start-automation-execution ^

--document-name "AWS-RestartEC2Instance" ^
--mode Interactive ^
--parameters "InstanceId=i-1234567890abcdef0"

PowerShell

Start-SSMAutomationExecution `
-DocumentName AWS-RestartEC2Instance `
-Mode Interactive
-Parameter @{"InstanceId"="i-1234567890abcdef0"}

The system returns information like the following.

Linux

{
"AutomationExecutionId": "ba9cd881-1b36-4d31-a698-0123456789ab"
}

156
 AWS Systems Manager User Guide
Working with Automation Executions

Windows

{
"AutomationExecutionId": "ba9cd881-1b36-4d31-a698-0123456789ab"
}

PowerShell

27ba8174-59ae-4e13-8626-0123456789ab

3. Run the following command when you are ready to start the first step of the Automation workflow.
The Automation workflow proceeds with step one and pauses before running any subsequent steps
specified in the Automation document you chose in step 1 of this procedure. If the document has
multiple steps, you must run the following command for each step for the workflow to proceed.

Linux

aws ssm send-automation-signal \

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab \
--signal-type StartStep \
--payload StepName="stopInstances"

Windows

aws ssm send-automation-signal ^

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab ^
--signal-type StartStep ^
--payload StepName="stopInstances"

PowerShell

Send-SSMAutomationSignal `
-AutomationExecutionId 27ba8174-59ae-4e13-8626-0123456789ab `
-SignalType StartStep
-Payload @{"StepName"="stopInstances"}

There is no output if the command succeeds.

4. Run the following command to retrieve the status of each step execution in the Automation
workflow.

Linux

aws ssm describe-automation-step-executions \

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab

Windows

aws ssm describe-automation-step-executions ^

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab

PowerShell

Get-SSMAutomationStepExecution `

157
 AWS Systems Manager User Guide
Working with Automation Executions

-AutomationExecutionId 27ba8174-59ae-4e13-8626-e177cdc11686

The system returns information like the following.

Linux

{
"StepExecutions": [
{
"StepName": "stopInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167178.42,
"ExecutionEndTime": 1557167220.617,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"stopped\"",
"InstanceIds": "[\"i-1234567890abcdef0\"]"
},
"Outputs": {
"InstanceStates": [
"stopped"
]
},
"StepExecutionId": "654243ba-71e3-4771-b04f-0123456789ab",
"OverriddenParameters": {},
"ValidNextSteps": [
"startInstances"
]
},
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167273.754,
"ExecutionEndTime": 1557167480.73,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-1234567890abcdef0\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "8a4a1e0d-dc3e-4039-a599-0123456789ab",
"OverriddenParameters": {}
}
]
}

Windows

{
"StepExecutions": [
{
"StepName": "stopInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167178.42,
"ExecutionEndTime": 1557167220.617,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"stopped\"",

158
 AWS Systems Manager User Guide
Working with Automation Executions

"InstanceIds": "[\"i-1234567890abcdef0\"]"
},
"Outputs": {
"InstanceStates": [
"stopped"
]
},
"StepExecutionId": "654243ba-71e3-4771-b04f-0123456789ab",
"OverriddenParameters": {},
"ValidNextSteps": [
"startInstances"
]
},
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1557167273.754,
"ExecutionEndTime": 1557167480.73,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-1234567890abcdef0\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "8a4a1e0d-dc3e-4039-a599-0123456789ab",
"OverriddenParameters": {}
}
]
}

PowerShell

Action : aws:changeInstanceState
ExecutionEndTime : 5/6/2019 19:45:46
ExecutionStartTime : 5/6/2019 19:45:03
FailureDetails :
FailureMessage :
Inputs : {[DesiredState, "stopped"], [InstanceIds,
["i-1234567890abcdef0"]]}
IsCritical : False
IsEnd : False
MaxAttempts : 0
NextStep :
OnFailure :
Outputs : {[InstanceStates,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
OverriddenParameters : {}
Response :
ResponseCode :
StepExecutionId : 8fcc9641-24b7-40b3-a9be-0123456789ab
StepName : stopInstances
StepStatus : Success
TimeoutSeconds : 0
ValidNextSteps : {startInstances}

5. Run the following command to complete the Automation workflow after all steps specified within
the chosen Automation document have finished.

159
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

aws ssm stop-automation-execution \

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab \
--type Complete

Windows

aws ssm stop-automation-execution ^

--automation-execution-id ba9cd881-1b36-4d31-a698-0123456789ab ^
--type Complete

PowerShell

Stop-SSMAutomationExecution `
-AutomationExecutionId 27ba8174-59ae-4e13-8626-0123456789ab `
-Type Complete

There is no output if the command succeeds.

Running an Automation Workflow with Approvers

The following procedures describe how to use the AWS Systems Manager console, AWS Command
Line Interface (AWS CLI), and AWS Tools for Windows PowerShell to run an AWS Systems Manager
Automation workflow with approvals using simple execution. The workflow uses the Automation action
aws:approve, which temporarily pauses the Automation workflow until the designated principals
either approve or deny the action. The Automation workflow runs in the context of the current AWS
Identity and Access Management (IAM) user. This means that you don't need to configure additional IAM
permissions as long as you have permission to run the Automation document and any actions called by
the document. If you have administrator permissions in IAM, then you already have permission to run
this Automation workflow.
Note
For information about how to run an Automation workflow that uses an IAM service role or
more advanced forms of delegated administration, see Running Automation Workflows by
Using Different Security Models (p. 196).

Before You Begin

In addition to the standard inputs required by the Automation document, the aws:approve action
requires the following two parameters:

• A list of approvers. The list of approvers must contain at least one approver in the form of an IAM user
or a user ARN. If multiple approvers are provided, a corresponding minimum approval count must also
be specified within the automation document.
• An Amazon Simple Notification Service (Amazon SNS) topic ARN. The Amazon SNS topic name must
start with Automation.

This procedure assumes that you have already created an Amazon SNS topic, which is required to deliver
the approval request. For information, see Create a Topic in the Amazon Simple Notification Service
Developer Guide.

160
 AWS Systems Manager User Guide
Working with Automation Executions

Running an Automation Workflow with Approvers (Console)

To run an Automation workflow with approvers

The following procedure describes how to use the Systems Manager console to run an Automation
workflow with approvers.

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. On the Execute automation document page, choose Simple execution.
7. In the Input parameters section, specify the required input parameters.

For example, if you chose the AWS-StartEC2InstanceWithApproval document, then you must
specify or choose instance IDs for the InstanceId parameter.
8. In the Approvers section, specify the IAM users or user ARNs of approvers for the automation action.
9. In the SNSTopicARN section, specify the SNS topic ARN to use for sending approval notification. The
SNS topic name must start with Automation.
10. Optionally, you can choose an IAM service role from the AutomationAssumeRole list.
11. Choose Execute automation.

The specified approver receives an Amazon SNS notification with details to approve or reject the
Automation workflow. This approval action is valid for 7 days from the date of issue and can be issued
using the Systems Manager console or the AWS Command Line Interface (AWS CLI).

If you chose to approve the Automation workflow, the workflow continues to run the steps included in
the specified Automation document. The console displays the status of the Automation execution. If the
Automation fails to run, see Troubleshooting Systems Manager Automation (p. 433).

To approve or deny an Automation workflow

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then select the Automation workflow that was run
in the previous procedure.
3. Choose Actions and then choose Approve/Deny.
4. Choose to Approve or Deny and optionally provide a comment.
5. Choose Submit.

161
 AWS Systems Manager User Guide
Working with Automation Executions

Running an Automation Workflow with Approvers (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run an Automation workflow with approvers.

To run an Automation workflow with approvers

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Use the following command to run an Automation workflow with approvers. In the document name
section, specify an Automation document that includes the Automation action, aws:approve.

For Approvers, specify the IAM users or user ARNs of approvers for the action. For SNSTopic,
specify the SNS topic ARN to use to send approval notification. The SNS topic name must start with
Automation.
Note
The specific names of the parameter values for approvers and the SNS topic depend on the
values specified within the document you choose.

Linux

aws ssm start-automation-execution \

--document-name "AWS-StartEC2InstanceWithApproval" \
--parameters
"InstanceId=i-1234567890abcdef0,Approvers=arn:aws:iam::123456789012:role/
Administrator,SNSTopicArn=arn:aws:sns:us-east-1:123456789012:AutomationApproval"

Windows

aws ssm start-automation-execution ^

--document-name "AWS-StartEC2InstanceWithApproval" ^
--parameters
"InstanceId=i-1234567890abcdef0,Approvers=arn:aws:iam::123456789012:role/
Administrator,SNSTopicArn=arn:aws:sns:us-east-1:123456789012:AutomationApproval"

PowerShell

Start-SSMAutomationExecution `
-DocumentName AWS-StartEC2InstanceWithApproval `
-Parameters @{
"InstanceId"="i-1234567890abcdef0"
"Approvers"="arn:aws:iam::123456789012:role/Administrator"
"SNSTopicArn"="arn:aws:sns:us-east-1:123456789012:AutomationApproval"
}

The system returns information like the following.

Linux

{
"AutomationExecutionId": "df325c6d-b1b1-4aa0-8003-6cb7338213c6"
}

162
 AWS Systems Manager User Guide
Working with Automation Executions

Windows

{
"AutomationExecutionId": "df325c6d-b1b1-4aa0-8003-6cb7338213c6"
}

PowerShell

462fa82a-7fff-430a-8490-0123456789ab

To approve an Automation workflow

• Run the following command to approve an Automation workflow.

Linux

aws ssm send-automation-signal \

--automation-execution-id "4105a4fc-f944-11e6-9d32-0123456789ab" \
--signal-type "Approve" \
--payload "Comment=Replace_This_With_Approve_Comment"

Windows

aws ssm send-automation-signal ^

--automation-execution-id "4105a4fc-f944-11e6-9d32-0123456789ab" ^
--signal-type "Approve" ^
--payload "Comment=Replace_This_With_Approve_Comment"

PowerShell

Send-SSMAutomationSignal `
-AutomationExecutionId 462fa82a-7fff-430a-8490-0123456789ab `
-SignalType Approve `
-Payload @{"Comment"="Replace_This_With_Approval_Comment"}

There is no output if the command succeeds.

To deny an Automation workflow

• Run the following command to deny an Automation workflow.

Linux

aws ssm send-automation-signal \

--automation-execution-id "4105a4fc-f944-11e6-9d32-0123456789ab" \
--signal-type "Deny" \
--payload "Comment=Replace_This_With_Deny_Comment"

Windows

aws ssm send-automation-signal ^

--automation-execution-id "4105a4fc-f944-11e6-9d32-0123456789ab" ^
--signal-type "Deny" ^

163
 AWS Systems Manager User Guide
Working with Automation Executions

--payload "Comment=Replace_This_With_Deny_Comment"

PowerShell

Send-SSMAutomationSignal `
-AutomationExecutionId 462fa82a-7fff-430a-8490-0123456789ab `
-SignalType Deny `
-Payload @{"Comment"="Replace_This_With_Deny_Comment"}

There is no output if the command succeeds.

Running Automation Workflows That Use Targets and Rate

Controls
AWS Systems Manager enables you to run Automation workflows on a fleet of AWS resources by using
targets. Additionally, you can control the execution of the Automation across your fleet by specifying a
concurrency value and an error threshold. The concurrency value determines how many resources are
allowed to run the Automation simultaneously. An error threshold determines how many Automation
executions are allowed to fail before Systems Manager stops sending the workflow to other resources.
The concurrency and error threshold features are collectively called rate controls.

For more information about concurrency and error thresholds, see About Concurrency and Error
Thresholds (p. 176). For more information about targets, see About Targets (p. 171).

The following procedures describe how to run an Automation workflow with targets and rate controls by
using the AWS Systems Manager console, AWS Command Line Interface (AWS CLI), and AWS Tools for
Windows PowerShell.

Running an Automation workflow with targets and rate controls (Console)

The following procedure describes how to use the Systems Manager console to run an Automation
workflow with targets and rate controls.

To run an Automation workflow with targets and rate controls

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.

164
 AWS Systems Manager User Guide
Working with Automation Executions

6. In the Execution Mode section, choose Rate Control. You must use this mode or Multi-account and
Region if you want to use targets and rate controls.
7. In the Targets section, choose how you want to target the AWS Resources where you want to run the
Automation. These options are required.

a. Use the Parameter list to choose a parameter. The items in the Parameter list are determined
by the parameters in the Automation document that you selected at the start of this procedure.
By choosing a parameter you define the type of resource on which the Automation workflow
runs.
b. Use the Targets list to choose how you want to target resources. If you chose to target resources
by using AWS Resource Groups, then choose the name of the group from the Resource Group
list.

If you chose to target resources by using tags, then enter the tag key and (optionally) the tag
value in the fields provided. Choose Add.

If you chose to target resources by using parameter values, then enter the parameter value for
the parameter you chose in the Input parameters section.
8. In the Input parameters section, specify the required inputs. Optionally, you can choose an IAM
service role from the AutomationAssumeRole list.
Note
You may not need to choose some of the options in the Input parameters section. This is
because you targeted resources by using tags or a resource group. For example, if you chose
the AWS-RestartEC2Instance document, then you don't need to specify or choose instance
IDs in the Input parameters section. The Automation execution locates the instances to
restart by using the tags or Resource Group you specified.
9. Use the options in the Rate control section to restrict the number of AWS resources that can run the
Automation within each account-Region pair.

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the Automation workflow
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the Automation workflow
simultaneously.
10. In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors allowed before Automation stops sending
the workflow to other resources.
• Choose percentage to enter a percentage of errors allowed before Automation stops sending the
workflow to other resources.
11. Choose Execute.

Running an Automation Workflow with Targets and Rate Controls (Command

Line)
The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run an Automation workflow with targets and rate controls.

To run an Automation workflow with targets and rate controls

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).

165
 AWS Systems Manager User Guide
Working with Automation Executions

2. Run the following command to view a list of documents.

Linux

aws ssm list-documents

Windows

aws ssm list-documents

PowerShell

Get-SSMDocumentList

Note the name of the Automation document that you want to run.
3. Run the following command to view details about the Automation document. Note a parameter
name (for example, InstanceId) that you want to use for the --target-parameter-name
option. This parameter determines the type of resource on which the Automation runs.

Linux

aws ssm describe-document \

--name document_name

Windows

aws ssm describe-document ^

--name document_name

PowerShell

Get-SSMDocumentDescription `
-Name document_name

4. Create a command that uses the targets and rate control options you want to run. Here are some
template commands to help.

Targeting using tags

Linux

aws ssm start-automation-execution \

--document-name document_name \
--targets Key=tag:key_name,Values=value \
--target-parameter-name parameter_name \
--parameters
"input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2"
\
--max-concurrency 10 \
--max-errors 25%

Windows

aws ssm start-automation-execution ^

--document-name document_name ^

166
 AWS Systems Manager User Guide
Working with Automation Executions

--targets Key=tag:key_name,Values=value ^
--target-parameter-name parameter_name ^
--parameters
"input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2"
^
--max-concurrency 10 ^
--max-errors 25%

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "tag:key_name"
$Targets.Values = "value"

Start-SSMAutomationExecution `
-DocumentName "DocumentName" `
-Targets $Targets `
-TargetParameterName "Parameter_Name" `
-Parameter
@{"input_parameter_name1"="input_parameter_value1";"input_parameter_name2"="input_parameter_val
`
-MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
-MaxError "a_number_of_errors_or_a_percentage_of_target_set"

Targeting using parameter values

Linux

aws ssm start-automation-execution \

--document-name document_name \
--targets Key=ParameterValues,Values=value_1,value_2,value_3 \
--target-parameter-name parameter_name \
--parameters "input_parameter_name1=input_parameter_value1" \
--max-concurrency 10 \
--max-errors 25%

Windows

aws ssm start-automation-execution ^

--document-name document_name ^
--targets Key=ParameterValues,Values=value_1,value_2,value_3 ^
--target-parameter-name parameter_name ^
--parameters "input_parameter_name1=input_parameter_value1" ^
--max-concurrency 10 ^
--max-errors 25%

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ParameterValues"
$Targets.Values = "value_1","value_2","value_3"

Start-SSMAutomationExecution `
-DocumentName "DocumentName" `
-Targets $Targets `
-TargetParameterName "Parameter_Name" `
-Parameter @{"input_parameter_name1"="input_parameter_value1"} `
-MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
-MaxError "a_number_of_errors_or_a_percentage_of_target_set"

167
 AWS Systems Manager User Guide
Working with Automation Executions

Targeting using AWS Resource Groups

Linux

aws ssm start-automation-execution \

--document-name document_name \
--targets Key=ResourceGroup,Values=Resource_Group_name \
--target-parameter-name parameter_name \
--parameters
"input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2"
\
--max-concurrency 10 \
--max-errors 25%

Windows

aws ssm start-automation-execution ^

--document-name document_name ^
--targets Key=ResourceGroup,Values=Resource_Group_name ^
--target-parameter-name parameter_name ^
--parameters
"input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2"
^
--max-concurrency 10 ^
--max-errors 25%

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ResourceGroup"
$Targets.Values = "Resource_Group_Name"

Start-SSMAutomationExecution `
-DocumentName "DocumentName" `
-Targets $Targets `
-TargetParameterName "Parameter_Name" `
-Parameter
@{"input_parameter_name1"="input_parameter_value1";"input_parameter_name2"="input_parameter_val
`
-MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
-MaxError "a_number_of_errors_or_a_percentage_of_target_set"

The command returns an execution ID. Copy this ID to the clipboard. You can use this ID to view the
status of the workflow.

Linux

{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}

Windows

{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}

168
 AWS Systems Manager User Guide
Working with Automation Executions

PowerShell

a4a3c0e9-7efd-462a-8594-01234EXAMPLE

5. Run the following command to view the workflow execution.

Linux

aws ssm describe-automation-executions \

--filter Key=ExecutionId,Values=a4a3c0e9-7efd-462a-8594-01234EXAMPLE

Windows

aws ssm describe-automation-executions ^

--filter Key=ExecutionId,Values=a4a3c0e9-7efd-462a-8594-01234EXAMPLE

PowerShell

Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"}

6. To view details about the execution progress, run the following command.

Linux

aws ssm get-automation-execution \

--automation-execution-id a4a3c0e9-7efd-462a-8594-01234EXAMPLE

Windows

aws ssm get-automation-execution ^

--automation-execution-id a4a3c0e9-7efd-462a-8594-01234EXAMPLE

PowerShell

Get-SSMAutomationExecution `
-AutomationExecutionId a4a3c0e9-7efd-462a-8594-01234EXAMPLE

The system returns information like the following.

Linux

{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"

169
 AWS Systems Manager User Guide
Working with Automation Executions

],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}

Windows

{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"
],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",

170
 AWS Systems Manager User Guide
Working with Automation Executions

"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}

PowerShell

AutomationExecutionId : a4a3c0e9-7efd-462a-8594-01234EXAMPLE
AutomationExecutionStatus : Success
CurrentAction :
CurrentStepName :
DocumentName : AWS-StopEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/
Admin
ExecutionEndTime : 8/1/2019 5:46:59 PM
ExecutionStartTime : 8/1/2019 5:46:16 PM
FailureMessage :
MaxConcurrency : 1
MaxErrors : 1
Mode : Auto
Outputs : {}
Parameters : {}
ParentAutomationExecutionId :
ProgressCounters :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
StepExecutions : {i-02573cafcfEXAMPLE}
StepExecutionsTruncated : False
Target :
TargetLocations : {}
TargetMaps : {}
TargetParameterName : InstanceId
Targets : {tag:Name}

Note
You can also monitor the status of the workflow in the console. In the execution list, choose
the execution you just ran and then choose the Steps tab. This tab shows the status of the
workflow actions.

About Targets
The Targets parameter enables you to quickly define which resources in your fleet can run an
Automation workflow. For example, if you want to run an Automation that restarts your managed
instances, then instead of manually selecting dozens of instance IDs in the console or typing them in a
command, you can target instances by specifying Amazon EC2 tags with the Targets parameter.

171
 AWS Systems Manager User Guide
Working with Automation Executions

When you run an Automation that uses a target, Systems Manager creates a child Automation for each
target. For example, if you target Amazon Elastic Block Store (Amazon EBS) volumes by specifying
tags, and those tags resolve to 100 Amazon EBS volumes, then Systems Manager creates 100 child
Automation workflows. The parent Automation is complete when all child Automations reach a final
state.
Note
Any input parameters that you specify at runtime (either in the Input parameters section
of the console or by using the parameters option from the command line) are automatically
processed by all child Automations.

You can target resources for an Automation execution by using tags, Resource Groups, and parameter
values. Additionally, you can use the TargetMaps option to target multiple parameter values from the
command line or a file. The following section describes each of these targeting options in more detail.

Targeting Tags
Many AWS resources support tags, including Amazon EC2 and Amazon Relational Database Service
(Amazon RDS) instances, Amazon Elastic Block Store (Amazon EBS) volumes and snapshots, Resource
Groups, and Amazon Simple Storage Service (Amazon S3) buckets, to name a few. You can quickly
run Automation workflows on your AWS resources by targeting tags. A tag is a key-value pair, such as
Operating_System-Linux or Department-Finance. If you assign a specific name to a resource, then you
can also use the word "Name" as a key, and the name of the resource as the value.

When you specify a tag as the target for an Automation, you also specify a target parameter. The target
parameter uses the TargetParameterName option. By choosing a target parameter, you define the
type of resource on which the Automation runs. The target parameter you specify with the tag must
be a valid parameter defined in the Automation document. For example, if you want to target dozens
of Amazon EC2 instances by using tags, then choose the InstanceId target parameter. By choosing
this parameter, you define instances as the resource type for the Automation execution. The following
screenshot uses the AWS-DetachEBSVolume document. The logical target parameter is VolumeId.

The AWS-DetachEBSVolume document also includes a special property called Target type, which is set
to /AWS::EC2::Volume. This means that if the tag-key pair Finance-TestEnv returns different types
of resources (for example, Amazon EC2 instances, Amazon EBS volumes, Amazon EBS snapshots) then
only Amazon EBS volumes will be used.

172
 AWS Systems Manager User Guide
Working with Automation Executions

Important
Target parameter names are case sensitive. If you run Automations by using either the
AWS CLI or AWS Tools for Windows PowerShell, then you must enter the target parameter
name exactly as it is defined in the Automation document. If you don't, the system returns
an InvalidAutomationExecutionParametersException error. You can use the
DescribeDocument API action to see information about the available target parameters in a
specific document. Here is an example AWS CLI command that provides information about the
AWS-DeleteSnapshot document:

aws ssm describe-document --name AWS-DeleteSnapshot

Here are some example AWS CLI commands that target resources by using tags.

Example 1: Targeting tags using a key-value pair to restart Amazon EC2 instances

This example restarts all Amazon EC2 instances that are tagged with a key of Department and a value of
HumanResources. The target parameter uses the InstanceId parameter from the Automation document.
The example uses an additional parameter to run the automation by using an Automation service role
(also called an assume role).

aws ssm start-automation-execution --document-name AWS-RestartEC2Instance --targets

Key=tag:Department,Values=HumanResources --target-parameter-name InstanceId --parameters
"AutomationAssumeRole=arn:aws:iam::111122223333:role/AutomationServiceRole"

Example 2: Targeting tags using a key-value pair to delete Amazon EBS snapshots

The following example uses the AWS-DeleteSnapshot Automation document to delete all snapshots with
a key of Name and a value of January2018Backups. The target parameter uses the VolumeId parameter.

aws ssm start-automation-execution --document-name AWS-DeleteSnapshot --targets

Key=tag:Name,Values=January2018Backups --target-parameter-name VolumeId

Targeting AWS Resource Groups

You can specify a single AWS resource group as the target of an Automation. Systems Manager creates a
child Automation for every object in the target Resource Group.

For example, say that one of your Resource Groups is named PatchedAMIs. This Resource Group
includes a list of 25 Windows Amazon Machine Images (AMIs) that are routinely patched. If you run an
Automation that uses the AWS-CreateManagedWindowsInstance document and target this Resource
Group, then Systems Manager creates a child Automation for each of the 25 AMIs. This means, that by
targeting the PatchedAMIs Resource Group, the Automation creates 25 instances from a list of patched
AMIs. The parent Automation is complete when all child Automations complete processing or reach a
final state.

The following AWS CLI command applies to the PatchAMIs Resource Group example. The command
takes the AmiId parameter for the --target-parameter-name option. The command doesn't include
an additional parameter defining which type of instance to create from each AMI. The AWS-
CreateManagedWindowsInstance document defaults to the t2.medium instance type, so this command
would create 25 t2.medium Windows instances.

aws ssm start-automation-execution --document-name AWS-CreateManagedWindowsInstance --

targets Key=ResourceGroup,Values=PatchedAMIs --target-parameter-name AmiId

The following console example uses a Resource Group called t2-micro-instances.

173
 AWS Systems Manager User Guide
Working with Automation Executions

Targeting Parameter Values

You can also target a parameter value. You enter ParameterValues as the key and then enter the
specific resource value where you want the Automation workflow to run. If you specify multiple values,
Systems Manager runs a child Automation workflow on each value specified.

For example, say that your Automation document includes an InstanceID parameter. If you target
the values of the InstanceID parameter when you run the Automation, then Systems Manager runs a
child Automation for each instance ID value specified. The parent Automation is complete when the
Automation finishes running each specified instance, or if the execution fails. You can target a maximum
of 50 parameter values.

The following example uses the AWS-CreateImage Automation document. The target parameter name
specified is InstanceId. The key uses ParameterValues. The values are two Amazon EC2 instance IDs. This
command creates an Automation workflow for each instance, which produces an AMI from each instance.

aws ssm start-automation-execution --document-name AWS-CreateImage --target-parameter-name

InstanceId --targets Key=ParameterValues,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE

Note
AutomationAssumeRole is not a valid parameter. Don’t choose this item when running
Automation workflows that target a parameter value.

Targeting Parameter Value Maps

The TargetMaps option expands your ability to target ParameterValues. You can enter an array
of parameter values by using TargetMaps at the command line. You can specify a maximum of 50
parameter values at the command line. If you want to run commands that specify more than 50
parameter values, then you can enter the values in a JSON file. You can then call the file from the
command line.
Note
TargetMaps are not supported in the console.

Use the following format to specify multiple parameter values by using the TargetMaps option in a
command:

174
 AWS Systems Manager User Guide
Working with Automation Executions

aws ssm start-automation-execution —document-name name_of_document --target-

maps “parameterA=parameterA1, parameterB=parameterB1, parameterC=parameterC1”
“parameterA=parameterA2, parameterB=parameterB2, parameterC=parameterC2”
“parameterA=parameterA3, parameterB=parameterB3, parameterC=parameterC3”

If you want to enter more than 50 parameter values for the TargetMaps option, then specify the values
in a file by using the following JSON format. Using a JSON file also improves readability when providing
multiple parameter values.

{“parameterA”:”parameterValueA1”, “parameterB”:”parameterValueB1”,
“parameterC”:”parameterValueC1”},

{“parameterA”:”parameterValueA2”, “parameterB”:”parameterValueB2”,
“parameterC”:”parameterValueC2”},

{“parameterA”:”parameterValueA3”, “parameterB”:”parameterValueB3”,
“parameterC”:”parameterValueC3”}

Save the file with a .json file extension. You can call the file by using the following command:

aws ssm start-automation-execution --document-name name_of_document –-

parameters one_or_more_input_parameters --target-maps full_path_to_file/file_name.json

You can also download the file from an Amazon S3 bucket, as long as you have permission to read data
from the bucket. Use the following command format:

aws ssm start-automation-execution —document-name name_of_document --target-maps

http://bucket_name.s3.amazonaws.com/file_name.json

Here is an example scenario to help you understand the TargetMaps option. In this scenario, a user
wants to create Amazon EC2 instances of different types from different AMIs. To perform this task, the
user creates an Automation document named AMI_Testing. This document defines two input parameters:
instanceType and imageId.

{
"description": "AMI Testing",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"assumeRole": {
"type": "String",
"description": "Role under which to run the automation",
"default": ""
},
"instanceType": {
"type": "String",
"description": "Type of EC2 Instance to launch for this test"
},
"imageId": {
"type": "String",
"description": "Source AMI id from which to run instance"
}
},
"mainSteps": [

175
 AWS Systems Manager User Guide
Working with Automation Executions

{
"name": "runInstances",
"action": "aws:runInstances",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {
"ImageId": "{{imageId}}",
"InstanceType": "{{instanceType}}",
"MinInstanceCount": 1,
"MaxInstanceCount": 1
}
}
],
"outputs": [
"runInstances.InstanceIds"
]
}

The user then specifies the following target parameter values in a file named AMI_instance_types.json.

[
{
"instanceType" : ["t2.micro"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.small"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
}
]

The user can run the Automation and create the five Amazon EC2 instances defined in
AMI_instance_types.json by running the following command:

aws ssm start-automation-execution --document-name AMI_Testing --target-parameter-name

imageId --target-maps file:///home/TestUser/workspace/runinstances/AMI_instance_types.json

About Concurrency and Error Thresholds

You can control the execution of an Automation workflow across a fleet of AWS resources by specifying
a concurrency value and an error threshold. Concurrency and error threshold are collectively called rate
controls.

Concurrency

Concurrency enables you to specify how many resources are allowed to run an Automation
simultaneously. Concurrency helps to limit the impact or downtime on your resources when processing
an Automation. You can specify either an absolute number of resources, for example 20, or a percentage
of the target set, for example 10%.

176
 AWS Systems Manager User Guide
Working with Automation Executions

The queueing system delivers the Automation to a single resource and waits until the initial invocation
is complete before sending the Automation to two more resources. The system exponentially sends the
Automation to more resources until the concurrency value is met.

Error Thresholds

An error threshold enables you to specify how many Automation workflows are allowed to fail before
Systems Manager stops sending the Automation to other resources. You can specify either an absolute
number of errors, for example 10, or a percentage of the target set, for example 10%.

If you specify an absolute number of 3 errors, for example, the system stops sending the Automation
when the third error is received. If you specify 1, then the system stops sending the Automation to
additional resources after the first error result is returned.

If you send an Automation to, for example, 50 instances and set the error threshold to 10%, then the
system stops sending the command to additional instances when the fifth error is received. Invocations
that are already running an Automation when an error threshold is reached are allowed to be completed,
but some of these Automations might fail as well. If you need to ensure that there won’t be more
errors than the number specified for the error threshold, then set the Concurrency value to 1 so that
Automations proceed one at a time.

Running Automation Workflows Based on Triggers

This section includes information about how to run Automation workflows using a trigger. Automation
workflows can be initiated by several different triggers, such as Amazon CloudWatch Events, State
Manager Associations, or maintenance windows. By using triggers, you can run Automation workflows as
a result of a specific event or on a scheduled basis.

Contents
• Running Automation Workflows with Triggers using CloudWatch Events (p. 177)
• Running Automation Workflows with Triggers Using State Manager (p. 182)
• Running Automation Workflows with Triggers using Maintenance Windows (p. 190)

Running Automation Workflows with Triggers using CloudWatch Events

You can start an Automation workflow by specifying an Automation document as the target of an
Amazon CloudWatch event. You can start workflows according to a schedule, or when a specific
AWS system event occurs. For example, let's say you create an Automation document named
BootStrapInstances that installs software on an instance when an instance starts. To specify the
BootStrapInstances document (and corresponding workflow) as a target of a CloudWatch event, you
first create a new CloudWatch Events rule. (Here's an example rule: Service name: EC2, Event Type: EC2
Instance State-change Notification, Specific state(s): running, Any instance.) Then you use the following
procedures to specify the BootStrapInstances document as the target of the event using the CloudWatch
console, AWS Command Line Interface (AWS CLI), or AWS Tools for Windows PowerShell. When a new
instance starts, the system runs the workflow and installs software.

For information about creating Automation documents, see Working with Automation
Documents (p. 217).

Creating a CloudWatch Event that Runs an Automation Workflow (Console)

Use the following procedure to configure an Automation workflow as the target of a CloudWatch event.

To configure an Automation document as a target of a CloudWatch event rule

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.

177
 AWS Systems Manager User Guide
Working with Automation Executions

2. In the left navigation pane, choose Events, and then choose Create rule.
3. Choose Event Pattern or Schedule. Event Pattern lets you build a rule that generates events for
specific actions in AWS services. Schedule lets you build a rule that generates events according to a
schedule that you specify by using the cron format.
4. Choose the remaining options for the rule you want to create, and then choose Add target.
5. In the Select target type list, choose SSM Automation.
6. In the Document list, choose an Automation document to run when your target is invoked.
7. Expand Configure document version, and choose a version. $DEFAULT was explicitly set as the
default document version in Systems Manager. You can choose a specific version, or use the latest
version.
8. Expand Configure automation parameter(s), and either keep the default parameter values (if
available) or enter your own values.
Note
Required parameters have an asterisk (*) next to the parameter name. To create a target,
you must specify a value for each required parameter. If you don't, the system creates the
rule, but it won't run.
9. In the permissions section, choose an option. CloudWatch uses the role to start the Automation
workflow.
10. Choose Configure details and complete the wizard.

Create a CloudWatch Event that Runs an Automation Document (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to create a CloudWatch event rule and configure an Automation document as the target.

To configure an Automation document as a target of a CloudWatch event rule

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Create a command to specify a new CloudWatch event rule. Here are some template commands to
help.

Triggers based on a schedule

Linux

aws events put-rule \

--name "rule_name" \
--schedule-expression "cron_or_rate_expression"

Windows

aws events put-rule ^

--name "rule_name" ^
--schedule-expression "cron_or_rate_expression"

PowerShell

Write-CWERule `
-Name "rule_name" `
-ScheduleExpression "cron_or_rate_expression"

178
 AWS Systems Manager User Guide
Working with Automation Executions

The following example creates a CloudWatch event rule that triggers every day at 9:00am (UTC).

Linux

aws events put-rule \

--name "DailyAutomationRule" \
--schedule-expression "cron(0 9 * * ? *)"

Windows

aws events put-rule ^

--name "DailyAutomationRule" ^
--schedule-expression "cron(0 9 * * ? *)"

PowerShell

Write-CWERule `
-Name "DailyAutomationRule" `
-ScheduleExpression "cron(0 9 * * ? *)"

Triggers based on an event

Linux

aws events put-rule \

--name "rule_name" \
--event-pattern "{\"source\":[\"aws.service\"],\"detail-type\":
[\"service_event_detail_type\"]}"

Windows

aws events put-rule ^

--name "rule_name" ^
--event-pattern "{\"source\":[\"aws.service\"],\"detail-type\":
[\"service_event_detail_type\"]}"

PowerShell

Write-CWERule `
-Name "rule_name" `
-EventPattern '{"source":["aws.service"],"detail-type":
["service_event_detail_type"]}'

The following example creates a CloudWatch event rule that triggers when any Amazon EC2
instance in the region changes state.

Linux

aws events put-rule \

--name "EC2InstanceStateChanges" \
--event-pattern "{\"source\":[\"aws.ec2\"],\"detail-type\":[\"EC2 Instance State-
change Notification\"]}"

179
 AWS Systems Manager User Guide
Working with Automation Executions

Windows

aws events put-rule ^

--name "EC2InstanceStateChanges" ^
--event-pattern "{\"source\":[\"aws.ec2\"],\"detail-type\":[\"EC2 Instance State-
change Notification\"]}"

PowerShell

Write-CWERule `
-Name "EC2InstanceStateChanges" `
-EventPattern '{"source":["aws.ec2"],"detail-type":["EC2 Instance State-change
Notification"]}'

The command returns details for the new CloudWatch rule similar to the following.

Linux

{
"RuleArn": "arn:aws:events:us-east-1:123456789012:rule/automationrule"
}

Windows

{
"RuleArn": "arn:aws:events:us-east-1:123456789012:rule/automationrule"
}

PowerShell

arn:aws:events:us-east-1:123456789012:rule/EC2InstanceStateChanges

3. Create a command to specify an Automation document as a target of the CloudWatch event rule you
created in step 2. Here are some template commands to help.

Linux

aws events put-targets \

--rule CW_Event_Rule_Name \
--targets '{"Arn": "arn:aws:ssm:us-east-1:123456789012:automation-
definition/Automation_Document_Name","Input":"{\"DocumentParameter\":
[\"ParameterValue\"],\"AutomationAssumeRole\":
[\"arn:aws:iam::123456789012:role/AutomationServiceRole\"]}","Id":
"Target_Id","RoleArn": "arn:aws:iam::123456789012:role/service-
role/CWE_Role_Name_To_Run_Automation"}'

Windows

aws events put-targets ^

--rule CW_Event_Rule_Name ^
--targets '{"Arn": "arn:aws:ssm:us-east-1:123456789012:automation-
definition/Automation_Document_Name","Input":"{\"DocumentParameter\":
[\"ParameterValue\"],\"AutomationAssumeRole\":
[\"arn:aws:iam::123456789012:role/AutomationServiceRole\"]}","Id":

180
 AWS Systems Manager User Guide
Working with Automation Executions

"Target_Id","RoleArn": "arn:aws:iam::123456789012:role/service-
role/CWE_Role_Name_To_Run_Automation"}'

PowerShell

$Target = New-Object Amazon.CloudWatchEvents.Model.Target

$Target.Id = "Target_Id"
$Target.Arn = "arn:aws:ssm:us-east-1:123456789012:automation-
definition/Automation_Document_Name"
$Target.RoleArn = "arn:aws:iam::123456789012:role/service-
role/CWE_Role_Name_To_Run_Automation"
$Target.Input = '{"DocumentParameter":["DocumentValue"],"AutomationAssumeRole":
["arn:aws:iam::123456789012:role/AutomationServiceRole"]}'

Write-CWETarget `
-Rule "CW_Event_Rule_Name" `
-Target $Target

The following example creates a CloudWatch event target that starts the specified instance ID using
the document AWS-StartEC2Instance.

Linux

aws events put-targets \

--rule DailyAutomationRule \
--targets '{"Arn": "arn:aws:ssm:us-east-1:123456789012:automation-definition/
AWS-StartEC2Instance","Input":"{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"],
\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationServiceRole
\"]}","Id": "Target1","RoleArn": "arn:aws:iam::123456789012:role/service-role/
AWS_Events_Invoke_Start_Automation_Execution_1213609520"}'

Windows

aws events put-targets ^

--rule DailyAutomationRule ^
--targets '{"Arn": "arn:aws:ssm:us-east-1:123456789012:automation-definition/
AWS-StartEC2Instance","Input":"{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"],
\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/AutomationServiceRole
\"]}","Id": "Target1","RoleArn": "arn:aws:iam::123456789012:role/service-role/
AWS_Events_Invoke_Start_Automation_Execution_1213609520"}'

PowerShell

$Target = New-Object Amazon.CloudWatchEvents.Model.Target

$Target.Id = "Target1"
$Target.Arn = "arn:aws:ssm:us-east-1:123456789012:automation-definition/AWS-
StartEC2Instance"
$Target.RoleArn = "arn:aws:iam::123456789012:role/service-role/
AWS_Events_Invoke_Start_Automation_Execution_1213609520"
$Target.Input = '{"InstanceId":["i-02573cafcfEXAMPLE"],"AutomationAssumeRole":
["arn:aws:iam::123456789012:role/AutomationServiceRole"]}'

Write-CWETarget `
-Rule "DailyAutomationRule" `
-Target $Target

The system returns information like the following.

181
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

{
"FailedEntries": [],
"FailedEntryCount": 0
}

Windows

{
"FailedEntries": [],
"FailedEntryCount": 0
}

PowerShell

There is no output if the command succeeds for PowerShell.

Running Automation Workflows with Triggers Using State Manager

You can start an Automation workflow by creating a State Manager association with an Automation
document. By creating a State Manager association with an Automation document, you can target
different types of AWS resources. For example, you can create associations that enforce a desired state
on an AWS resource, including the following:

• Attach a Systems Manager role to Amazon EC2 instances to make them managed instances.
• Enforce desired ingress and egress rules for a security group.
• Create or delete Amazon DynamoDB (DynamoDB) backups.
• Create or delete Amazon Elastic Block Store (Amazon EBS) snapshots.
• Disable read and write permissions on Amazon Simple Storage Service (Amazon S3) buckets.
• Start, restart, or stop managed instances and Amazon Relational Database Service (Amazon RDS)
instances.
• Patch Windows and Linux AMIs.

Use the following procedures to create a State Manager Association that runs an Automation workflow
using the AWS Systems Manager console, AWS Command Line Interface (AWS CLI), or AWS Tools for
Windows PowerShell.

Before You Begin

Be aware of the following important details before you run Automation workflows by using State
Manager.

• Before you can create an association that runs an Automation document, verify that you configured
permissions for Systems Manager Automation. For more information, see Getting Started with
Automation (p. 144).
• State Manager associations that run Automation documents contribute to the maximum number of
concurrently running Automations in your AWS account. You can have a maximum of 25 concurrent
Automations running with a maximum of 75 child Automations running at one time. For information,
see AWS Systems Manager Limits.
• Systems Manager automatically creates a service-linked role so that State Manager has permission
to call Systems Manager Automation API actions. If you want, you can create the service-linked role
yourself by running the following command from the AWS CLI or AWS Tools for PowerShell.

182
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

aws iam create-service-linked-role \

--aws-service-name ssm.amazonaws.com

Windows

aws iam create-service-linked-role ^

--aws-service-name ssm.amazonaws.com

PowerShell

New-IAMServiceLinkedRole `
-AWSServiceName ssm.amazonaws.com

For more information about service-linked roles, see Service-Linked Role Permissions for Systems
Manager (p. 919).

Creating an Association That Runs an Automation Workflow (Console)

The following procedure describes how to use the Systems Manager console to create a State Manager
association that runs an Automation workflow.

To create a State Manager association that runs a Systems Manager Automation Workflow

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager, and then choose Create association.
3. In the Name field, specify a name. This is optional, but recommended.
4. In the Document list, choose a document. Use the Search bar to filter on Document type : Equal :
Automation documents. To view more Automation documents, use the numbers to the right of the
Search bar.
Note
You can view information about a document by choosing the document name.
5. Choose Simple execution to run the automation on one or more targets by specifying the resource
ID for those targets. Choose Rate control to run the automation across a fleet of AWS resources
by specifying a targeting option such as tags or AWS Resource Groups. You can also control the
execution of the automation across your resources by specifying concurrency and error thresholds.

If you chose Rate control, the Targets section appears.

6. In the Targets section, choose a method for targeting resources.

a. (Required) In the Parameter list, choose a parameter. The items in the Parameter list are
determined by the parameters in the Automation document that you selected at the start
of this procedure. By choosing a parameter, you define the type of resource on which the
Automation workflow runs.
b. (Required) In the Targets list, choose a method for targeting the resources.

• Resource Group: Choose the name of the group from the Resource Group list. For more
information about targeting AWS Resource Groups in Automation documents, see Targeting
AWS Resource Groups (p. 173).
• Tags: Enter the tag key and (optionally) the tag value in the fields provided. Choose Add.
For more information about targeting tags in Automation documents, see Targeting
Tags (p. 172).

183
 AWS Systems Manager User Guide
Working with Automation Executions

• Parameter Values: Enter values in the Input parameters section. If you specify multiple
values, Systems Manager runs a child Automation workflow on each value specified.

For example, say that your Automation document includes an InstanceID parameter. If
you target the values of the InstanceID parameter when you run the Automation, then
Systems Manager runs a child Automation for each instance ID value specified. The parent
Automation is complete when the Automation finishes running each specified instance, or if
the execution fails. You can target a maximum of 50 parameter values. For more information
about targeting parameter values in Automation documents, see Targeting Parameter
Values (p. 174).
7. In the Input parameters section, specify the required input parameters.

If you chose to target resources by using tags or a resource group, then you may not need to
choose some of the options in the Input parameters section. For example, if you chose the AWS-
RestartEC2Instance document, and you chose to target instances by using tags, then you don't need
to specify or choose instance IDs in the Input parameters section. The Automation execution locates
the instances to restart by using the tags you specified.
Important
You must specify a role ARN in the AutomationAssumeRole field. State Manager uses
the assume role to call AWS services specified in the Automation document and run
Automation associations on your behalf. For more information, see Running an Automation
Workflow by Using an IAM Service Role (p. 200).
8. In the Specify schedule section, choose On Schedule if you want to run the association at regular
intervals. If you choose this option, then use the options provided to create the schedule using Cron
or Rate expressions. For more information about Cron and Rate expressions for State Manager, see
Cron and Rate Expressions for Associations (p. 937).
Note
Rate expressions are the preferred scheduling mechanism for State Manager associations
that run Automation documents. Rate expressions allow more flexibility for running
associations in the event that you reach the maximum number of concurrently running
Automations. With a rate schedule, Systems Manager can retry the Automation shortly
after receiving notification that concurrent Automations have reached their maximum and
have been throttled.

Choose No schedule if you want to run the association one time.

9. (Optional) In the Rate Control section, choose Concurrency and Error threshold options to control
the Automation execution across your AWS resources.

a. In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the Automation workflow
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the Automation
workflow simultaneously.
b. In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors allowed before Automation stops
sending the workflow to other resources.
• Choose percentage to enter a percentage of errors allowed before Automation stops sending
the workflow to other resources.

For more information about using targets and rate controls with Automation, see Running
Automation Workflows That Use Targets and Rate Controls (p. 164).
10. Choose Create Association.

184
 AWS Systems Manager User Guide
Working with Automation Executions

Important
When you create an association, the association immediately runs against the specified
targets. The association then runs based on the cron or rate expression you chose. If you
chose No schedule, the association does not run again.

Creating an Association That Runs an Automation Workflow (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to create a State Manager association that runs an Automation workflow.

To create an association that runs an Automation workflow

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to view a list of documents.

Linux

aws ssm list-documents

Windows

aws ssm list-documents

PowerShell

Get-SSMDocumentList

Note the name of the Automation document that you want to use for the association.
3. Run the following command to view details about the Automation document.

Linux

aws ssm describe-document \

--name document_name

Note a parameter name (for example, InstanceId) that you want to use for the --
automation-target-parameter-name option. This parameter determines the type of
resource on which the Automation runs.
Windows

aws ssm describe-document ^

--name document_name

Note a parameter name (for example, InstanceId) that you want to use for the --
automation-target-parameter-name option. This parameter determines the type of
resource on which the Automation runs.
PowerShell

Get-SSMDocumentDescription `

185
 AWS Systems Manager User Guide
Working with Automation Executions

-Name document_name

Note a parameter name (for example, InstanceId) that you want to use for the
AutomationTargetParameterName option. This parameter determines the type of resource
on which the Automation runs.
4. Create a command that runs an Automation workflow using a State Manager association. Here are
some template commands to help.

Targeting using tags

Linux

aws ssm create-association \

--association-name AssociationName \
--targets Key=tag:TagKey,Values=TagValue \
--name AutomationDocumentName \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) \
--automation-target-parameter-name (parameter to target) \
--schedule "cron_or_rate_expression"

Note
If you create an association by using the AWS CLI, use the --targets parameter to
target instances for the association. Don't use the --instance-id parameter. The --
instance-id parameter is a legacy parameter.
Windows

aws ssm create-association ^

--association-name AssociationName ^
--targets Key=tag:TagKey,Values=TagValue ^
--name AutomationDocumentName ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) ^
--automation-target-parameter-name (parameter to target) ^
--schedule "cron_or_rate_expression"

Note
If you create an association by using the AWS CLI, use the --targets parameter to
target instances for the association. Don't use the --instance-id parameter. The --
instance-id parameter is a legacy parameter.
PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "tag:TagKey"
$Targets.Values = "TagValue"

New-SSMAssociation `
-AssociationName "AssociationName" `
-Target $Targets `
-Name "AutomationDocumentName" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM;
(Additional parameters, if any)" } `
-AutomationTargetParameterName "parameter_to_target" `
-ScheduleExpression "cron_or_rate_expression"

186
 AWS Systems Manager User Guide
Working with Automation Executions

Note
If you create an association by using the AWS Tools for PowerShell, use the Target
parameter to target instances for the association. Don't use the InstanceId
parameter. The InstanceId parameter is a legacy parameter.

Targeting using parameter values

Linux

aws ssm create-association \

--association-name AssociationName \
--targets Key=ParameterValues,Values=value_1,value_2,value_3 \
--name AutomationDocumentName \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) \
--automation-target-parameter-name (parameter to target) \
--schedule "cron_or_rate_expression"

Windows

aws ssm create-association ^

--association-name AssociationName ^
--targets Key=ParameterValues,Values=value_1,value_2,value_3 ^
--name AutomationDocumentName ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) ^
--automation-target-parameter-name (parameter to target) ^
--schedule "cron_or_rate_expression"

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ParameterValues"
$Targets.Values = "value_1","value_2","value_3"

New-SSMAssociation `
-AssociationName "AssociationName" `
-Target $Targets `
-Name "AutomationDocumentName" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM;
(Additional parameters, if any)"} `
-AutomationTargetParameterName "parameter_to_target" `
-ScheduleExpression "cron_or_rate_expression"

Targeting using AWS Resource Groups

Linux

aws ssm create-association \

--association-name AssociationName \
--targets Key=ResourceGroup,Values=Resource_Group_name \
--name AutomationDocumentName \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) \
--automation-target-parameter-name (parameter to target) \

187
 AWS Systems Manager User Guide
Working with Automation Executions

--schedule "cron_or_rate_expression"

Windows

aws ssm create-association ^

--association-name AssociationName ^
--targets Key=ResourceGroup,Values=Resource_Group_name ^
--name AutomationDocumentName ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM,(Additional parameters, if any) ^
--automation-target-parameter-name (parameter to target) ^
--schedule "cron_or_rate_expression"

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ResourceGroup"
$Targets.Values = "Resource_Group_Name"

New-SSMAssociation `
-AssociationName "AssociationName" `
-Target $Targets `
-Name "AutomationDocumentName" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM;
(Additional parameters, if any)"} `
-AutomationTargetParameterName "parameter_to_target" `
-ScheduleExpression "cron_or_rate_expression"

The command returns details for the new association similar to the following.

Linux

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 7 ? * MON *)",
"Name": "AWS-StartEC2Instance",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/aws-service-role/ssm.amazonaws.com/
AWSServiceRoleForAmazonSSM"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"AutomationTargetParameterName": "InstanceId",
"LastUpdateAssociationDate": 1564686638.498,
"Date": 1564686638.498,
"AssociationVersion": "1",
"AssociationName": "CLI",
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"

188
 AWS Systems Manager User Guide
Working with Automation Executions

}
]
}
}

Windows

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 7 ? * MON *)",
"Name": "AWS-StartEC2Instance",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/aws-service-role/ssm.amazonaws.com/
AWSServiceRoleForAmazonSSM"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"AutomationTargetParameterName": "InstanceId",
"LastUpdateAssociationDate": 1564686638.498,
"Date": 1564686638.498,
"AssociationVersion": "1",
"AssociationName": "CLI",
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
]
}
}

PowerShell

Name : AWS-StartEC2Instance
InstanceId :
Date : 8/1/2019 7:31:38 PM
Status.Name :
Status.Date :
Status.Message :
Status.AdditionalInfo :

Note
If you use tags to create an association on one or more target instances, and then you remove
the tags from an instance, that instance no longer runs the association. The instance is
disassociated from the State Manager document.

Troubleshooting State Manager Automation Executions

Systems Manager Automation enforces a limit of 25 concurrent executions, 75 child executions,

and 1,000 queued executions per account, per Region. If a State Manager association
that runs an Automation document shows a status of Failed and a detailed status of

189
 AWS Systems Manager User Guide
Working with Automation Executions

AutomationExecutionLimitExceeded, then your execution may have reached the limit. As a result,
Systems Manager throttles the executions. To resolve this issue, do the following:

• Use a different rate or cron expression for your association. For example, if the association is scheduled
to run every 30 minutes, then change the expression so that it runs every hour or two.
• Delete existing Automation executions that have a status of Pending. By deleting these executions,
you clear the current queue.

Running Automation Workflows with Triggers using Maintenance Windows

You can start an Automation workflow by configuring an Automation document as a registered task for
a maintenance window. By registering the Automation document as a registered task, the maintenance
window runs the automation workflow during the scheduled maintenance period.

For example, let's say you create an Automation document named CreateAMI that creates an Amazon
Machine Image (AMI) of instances registered as targets to the maintenance window. To specify the
CreateAMI document (and corresponding workflow) as a registered task of a maintenance window, you
first create a maintenance window and register targets. Then you use the following procedure to specify
the CreateAMI document as a registered task within the maintenance window. When the maintenance
window starts during the scheduled period, the system runs the automation workflow and creates an
AMI of the registered targets.

For information about creating Automation documents, see Working with Automation
Documents (p. 217).

Use the following procedures to configure an Automation workflow as a registered task for a
maintenance window using the AWS Systems Manager console, AWS Command Line Interface (AWS CLI),
or AWS Tools for Windows PowerShell.

Registering an Automation Workflow Task to a Maintenance Window (Console)

The following procedure describes how to use the Systems Manager console to configure an Automation
workflow as a registered task for a maintenance window.

Before You Begin

Before you complete the following procedure, you must create a maintenance window and register at
least one target. For more information, see the following procedures:

• Create a Maintenance Window (Console) (p. 456).

• Assign Targets to a Maintenance Window (Console) (p. 457)

To configure an Automation workflow as a registered task for a maintenance window

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the left navigation pane, choose Maintenance Windows, and then choose the maintenance
window you want to register an Automation task with.
3. Choose Actions. Then choose Register Automation task to run your choice of an Automation
workflow on targets by using an Automation document.
4. For Name, enter a name for the task.
5. For Description, enter a description.
6. For Document, choose the Automation document that defines the tasks to run.
7. For Document version, choose the document version to use.
8. For Task priority, specify a priority for this task. 1 is the highest priority. Tasks in a maintenance
window are scheduled in priority order; tasks that have the same priority are scheduled in parallel.

190
 AWS Systems Manager User Guide
Working with Automation Executions

9. In the Targets section, identify the targets on which you want to run this automation workflow by
specifying tags or by selecting instances manually.
Important
If you choose an Automation document that doesn't target managed instances, you must
still select at least one maintenance window target. In this situation, we recommend
registering a target for a tag key-value pair that is not used by your managed instances.
For example, if you choose the Automation document AWS-CopySnapshot, then the
resulting automation workflow targets Amazon Elastic Block Store (EBS) snapshots instead
of managed instances. In this case, you can register a target to your maintenance window,
which targets a tag key-value pair that is not used by your managed instances, such as
key=MaintenanceWindow and value=Snapshot.
10. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of targets on which to run the
automation workflow at the same time.
Note
If you selected targets by choosing tag key-value pairs, and you are not certain how many
targets use the selected tags, then limit the number of automation workflows that can
run at the same time by specifying a percentage.
When the maintenance window runs, a new Automation execution is initiated per target.
There is a limit of 25 concurrent executions of Automation and 75 child executions
of Automation per AWS account. If you specify a concurrency rate greater than 25,
concurrent executions greater than 25 are automatically added to the execution queue.
For information, see AWS Systems Manager Limits.
• For Error threshold, specify when to stop running the automation workflow on other targets after
it fails on either a number or a percentage of targets. For example, if you specify three errors, then
Systems Manager stops running automation workflows when the fourth error is received. Targets
still processing the workflow might also send errors.
11. In the IAM service role area, choose one of the following options to provide permissions for
Systems Manager to start the Automation workflow:

• Create and use a service-linked role for Systems Manager

Service-linked roles provide a secure way to delegate permissions to AWS services because only
the linked service can assume a service-linked role. Additionally, AWS automatically defines and
sets the permissions of service-linked roles, depending on the actions that the linked service
performs on your behalf.
Note
If a service-linked role has already been created for your account, choose Use the service-
linked role for Systems Manager.
• Use a custom service role

If you want to use stricter permissions than those provided by the service-linked role, you can
create a custom service role for maintenance window tasks. If you want to use Amazon SNS to
send notifications related to maintenance window tasks run through Run Command, you can
create a custom service role.

To create a custom service role, see one of the following topics:

• Control Access to Maintenance Windows (Console) (p. 446)
• Control Access to Maintenance Windows (AWS CLI) (p. 449)
• Control Access to Maintenance Windows (Tools for Windows PowerShell) (p. 452)

191
 AWS Systems Manager User Guide
Working with Automation Executions

To help you decide whether to use a custom service role or the Systems Manager service-linked role
with a maintenance window task, see Should I Use a Service-Linked Role or a Custom Service Role to
Run Maintenance Window Tasks? (p. 445).
12. In the Input Parameters section, specify parameters for the document. For Automation documents,
the system auto-populates some of the values. You can keep or replace these values.
Important
For Automation documents, you can optionally specify an Automation Assume Role. If
you don't specify a role for this parameter, then the Automation workflow assumes the
maintenance window service role you choose in step 11. As such, you must ensure that the
maintenance window service role you choose has the appropriate AWS Identity and Access
Management (IAM) permissions to perform the actions defined within the Automation
document.
For example, the service-linked role for Systems Manager doesn't have the IAM permission
ec2:CreateSnapshot, which is required to run the Automation document AWS-
CopySnapshot. In this scenario, you must either use a custom maintenance window service
role or specify an Automation assume role that has ec2:CreateSnapshot permissions.
For information, see Getting Started with Automation (p. 144).
13. Choose Register Automation task.

Registering an Automation Workflow Task to a Maintenance Window (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to configure an Automation workflow as a registered task for a maintenance window.

Before You Begin

Before you complete the following procedure, you must create a maintenance window and register at
least one target. For more information, see the following procedures:

• Step 1: Create the Maintenance Window (AWS CLI) (p. 463).

• Step 2: Register a Target Instance with the Maintenance Window (AWS CLI) (p. 464)

To configure an Automation workflow as a registered task for a maintenance window

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Create a command to configure an Automation workflow as a registered task for a maintenance
window. Here are some template commands to help.

Linux

aws ssm register-task-with-maintenance-window \

--window-id window_id \
--name task_name \
--task-arn document_name \
--targets Key=targets,Values=value_1,value_2,value_3 \
--service-role-arn service_role_arn \
--task-type AUTOMATION \
--task-invocation-parameters task_parameters_if_any \
--priority task_priority \
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
--max-errors a_number_of_errors_or_a_percentage_of_target_set

192
 AWS Systems Manager User Guide
Working with Automation Executions

Note
If you configure an Automation workflow as a registered task by using the AWS CLI,
use the --Task-Invocation-Parameters parameter to specify parameters to pass
to a task when it runs. Don't use the --Task-Parameters parameter. The --Task-
Parameters parameter is a legacy parameter.
Windows

aws ssm register-task-with-maintenance-window ^

--window-id window_id ^
--name task_name ^
--task-arn document_name ^
--targets Key=targets,Values=value_1,value_2,value_3 ^
--service-role-arn service_role_arn ^
--task-type AUTOMATION ^
--task-invocation-parameters task_parameters_if_any ^
--priority task_priority ^
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
--max-errors a_number_of_errors_or_a_percentage_of_target_set

Note
If you configure an Automation workflow as a registered task by using the AWS CLI,
use the --Task-Invocation-Parameters parameter to specify parameters to pass
to a task when it runs. Don't use the --Task-Parameters parameter. The --Task-
Parameters parameter is a legacy parameter.
PowerShell

Register-SSMTaskWithMaintenanceWindow `
-WindowId window_id `
-Name "task_name" `
-TaskArn "document_name" `
-Target @{ Key="targets";Values="value_1" } `
-ServiceRoleArn "service_role_arn" `
-TaskType "AUTOMATION" `
-Automation_Parameter
@{ "task_parameters_1"="task_parameter_1_value";"task_parameters_2"="task_parameter_2_value" }
`
-Priority task_priority `
-MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
-MaxError a_number_of_errors_or_a_percentage_of_target_set

Note
If you configure an Automation workflow as a registered task by using the AWS Tools
for PowerShell, use the -Automation_Parameter parameter to specify parameters to
pass to a task when the task runs. Don't use the -TaskParameters parameter. The -
TaskParameters parameter is a legacy parameter.

The following example configures an Automation workflow as a registered task to a maintenance

window with priority 1. The Automation workflow uses the AWS-StartEC2Instance document
and the specified Automation assume role to start EC2 instances registered as targets to the
maintenance window. The maintenance window runs the Automation workflow simultaneously on 5
instances maximum at any given time. Also, the registered task stops running on more instances for
a particular execution interval if the error count exceeds 1.

Linux

aws ssm register-task-with-maintenance-window \

--window-id mw-0c50858d01EXAMPLE \

193
 AWS Systems Manager User Guide
Working with Automation Executions

--name StartEC2Instances \
--task-arn AWS-StartEC2Instance \
--targets Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE \
--service-role-arn arn:aws:iam::123456789012:role/MaintenanceWindowRole \
--task-type AUTOMATION \
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":
[\"{{TARGET_ID}}\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/
AutomationAssumeRole\"]}}}" \
--priority 1 \
--max-concurrency 5 \
--max-errors 1

Windows

aws ssm register-task-with-maintenance-window ^

--window-id mw-0c50858d01EXAMPLE ^
--name StartEC2Instances ^
--task-arn AWS-StartEC2Instance ^
--targets Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE ^
--service-role-arn arn:aws:iam::123456789012:role/MaintenanceWindowRole ^
--task-type AUTOMATION ^
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":
[\"{{TARGET_ID}}\"],\"AutomationAssumeRole\":[\"arn:aws:iam::123456789012:role/
AutomationAssumeRole\"]}}}" ^
--priority 1 ^
--max-concurrency 5 ^
--max-errors 1

PowerShell

Register-SSMTaskWithMaintenanceWindow `
-WindowId mw-0c50858d01EXAMPLE `
-Name "StartEC2" `
-TaskArn "AWS-StartEC2Instance" `
-Target @{ Key="WindowTargetIds";Values="e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" }
`
-ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowRole" `
-TaskType "AUTOMATION" `
-Automation_Parameter
@{ "InstanceId"="{{TARGET_ID}}";"AutomationAssumeRole"="arn:aws:iam::123456789012:role/
AutomationAssumeRole" } `
-Priority 1 `
-MaxConcurrency 5 `
-MaxError 1

The command returns details for the new registered task similar to the following.

Linux

{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

Windows

{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

194
 AWS Systems Manager User Guide
Working with Automation Executions

PowerShell

4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

3. To view the registered task, run the following command.

Linux

aws ssm describe-maintenance-window-tasks \

--window-id mw-0c50858d01EXAMPLE

Windows

aws ssm describe-maintenance-window-tasks ^

--window-id mw-0c50858d01EXAMPLE

PowerShell

Get-SSMMaintenanceWindowTaskList `
-WindowId mw-0c50858d01EXAMPLE

The system returns information like the following.

Linux

{
"Tasks": [
{
"ServiceRoleArn": "arn:aws:iam::123456789012:role/
MaintenanceWindowRole",
"MaxErrors": "1",
"TaskArn": "AWS-StartEC2Instance",
"MaxConcurrency": "5",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters": {},
"Priority": 0,
"WindowId": "mw-0c50858d01EXAMPLE",
"Type": "AUTOMATION",
"Targets": [
{
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
],
"Key": "WindowTargetIds"
}
],
"Name": "StartEC2"
}
]
}

Windows

{
"Tasks": [
{

195
 AWS Systems Manager User Guide
Working with Automation Executions

"ServiceRoleArn": "arn:aws:iam::123456789012:role/
MaintenanceWindowRole",
"MaxErrors": "1",
"TaskArn": "AWS-StartEC2Instance",
"MaxConcurrency": "5",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters": {},
"Priority": 0,
"WindowId": "mw-0c50858d01EXAMPLE",
"Type": "AUTOMATION",
"Targets": [
{
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
],
"Key": "WindowTargetIds"
}
],
"Name": "StartEC2"
}
]
}

PowerShell

Description :
LoggingInfo :
MaxConcurrency : 5
MaxErrors : 1
Name : StartEC2
Priority : 1
ServiceRoleArn : arn:aws:iam::123456789012:role/MaintenanceWindowRole
Targets : {WindowTargetIds}
TaskArn : AWS-StartEC2Instance
TaskParameters : {}
Type : AUTOMATION
WindowId : mw-0c50858d01EXAMPLE
WindowTaskId : 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

Running Automation Workflows by Using Different Security

Models
This section includes information about how to run Automation workflows by using different security
models.

Topics
• Running an Automation Workflow as the Current Authenticated User (p. 196)
• Running an Automation Workflow by Using an IAM Service Role (p. 200)
• Running an Automation Workflow by Using Delegated Administration (p. 204)

Running an Automation Workflow as the Current Authenticated User

The following procedures describe how to run an Automation workflow that runs in the context of the
current AWS Identity and Access Management (IAM) user using the AWS Systems Manager console, AWS
Command Line Interface (AWS CLI), and AWS Tools for Windows PowerShell. Running the Automation
workflow in the context of the current IAM) user means that you don't need to configure additional IAM
permissions as long as you have permission to run the Automation document and any actions called

196
 AWS Systems Manager User Guide
Working with Automation Executions

by the document. If you have administrator permissions in IAM, then you have permission to run this
Automation.

Running an Automation Workflow as the Current Authenticated User (Console)

The following procedure describes how to use the Systems Manager console to run an Automation
workflow as the current authenticated user.

To run the Automation document as the current authenticated user

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. In the Execution Mode section, choose Simple execution.
Note
This procedure uses the Simple execution mode. However, you can alternatively choose
Rate control or Manual execution and run the Automation workflow as the current
authenticated user.
7. In the Input parameters section, specify the required inputs. To run the Automation workflow as the
current authenticated user, do not specify an IAM service role for the value AutomationAssumeRole.
8. Choose Execute. The console displays the status of the Automation execution.

Running an Automation Workflow as the Current Authenticated User (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run an Automation workflow as the current authenticated user.

To run the Automation document as the current authenticated user

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to start an Automation workflow as the current authenticated user.

Linux

aws ssm start-automation-execution \

--document-name DocumentName \
--parameters ParametersRequiredByDocument

197
 AWS Systems Manager User Guide
Working with Automation Executions

Windows

aws ssm start-automation-execution ^

--document-name DocumentName ^
--parameters ParametersRequiredByDocument

PowerShell

Start-SSMAutomationExecution `
-DocumentName DocumentName `
-Parameter ParametersRequiredByDocument

Here is an example using the document AWS-RestartEC2Instance to restart the specified EC2
instance.

Linux

aws ssm start-automation-execution \

--document-name "AWS-RestartEC2Instance" \
--parameters "InstanceId=i-1234567890abcdef0"

Windows

aws ssm start-automation-execution ^

--document-name "AWS-RestartEC2Instance" ^
--parameters "InstanceId=i-1234567890abcdef0"

PowerShell

Start-SSMAutomationExecution `
-DocumentName AWS-RestartEC2Instance `
-Parameter @{"InstanceId"="i-1234567890abcdef0"}

The system returns information like the following.

Linux

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

Windows

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

PowerShell

4105a4fc-f944-11e6-9d32-0123456789ab

3. Run the following command to retrieve the status of the Automation workflow.

198
 AWS Systems Manager User Guide
Working with Automation Executions

Linux

aws ssm describe-automation-executions \

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

Windows

aws ssm describe-automation-executions ^

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

PowerShell

Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "4105a4fc-f944-11e6-9d32-0123456789ab"}

The system returns information like the following.

Linux

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

Windows

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false

199
 AWS Systems Manager User Guide
Working with Automation Executions

},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

PowerShell

AutomationExecutionId : 4105a4fc-f944-11e6-9d32-0123456789ab
AutomationExecutionStatus : InProgress
AutomationType : Local
CurrentAction : aws:changeInstanceState
CurrentStepName : startInstances
DocumentName : AWS-RestartEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/
Admin
ExecutionEndTime : 1/1/0001 12:00:00 AM
ExecutionStartTime : 7/31/2019 7:17:28 PM
FailureMessage :
LogFile :
MaxConcurrency :
MaxErrors :
Mode : Auto
Outputs : {}
ParentAutomationExecutionId :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
Target :
TargetMaps : {}
TargetParameterName :
Targets : {}

Running an Automation Workflow by Using an IAM Service Role

The following procedures describe how to use the AWS Systems Manager console, AWS Command Line
Interface (AWS CLI), and AWS Tools for Windows PowerShell to run an Automation workflow using an
AWS Identity and Access Management (IAM) service role (or assume role). The service role gives the
Automation workflow permission to perform actions on your behalf. Configuring a service role is useful
when you want to restrict permissions and run actions with least privilege. This is useful, for example,
when you want to restrict a user's privileges on a resource, such as an Amazon EC2 instance, but you
want to allow the user to run an Automation workflow that performs a specific set of actions. In this
scenario, you can create a service role with elevated privileges and allow the user to run the Automation
workflow.

Before You Begin

Before you complete the following procedures, you must create the IAM service role and configure
a trust relationship for Automation. For more information, see Task 1: Create a Service Role for
Automation (p. 147) and Task 2: Add a Trust Relationship for Automation (p. 148).

Running an Automation Workflow by Using an IAM Service Role (Console)

The following procedure describes how to use the Systems Manager console to run an Automation
workflow that uses an IAM service role (or assume role).

200
 AWS Systems Manager User Guide
Working with Automation Executions

To run an Automation workflow using a service role

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. In the Execution Mode section, choose Simple execution.
Note
This procedure uses the Simple execution mode. However, you can alternatively choose
Rate control, Multi-account and Region, or Manual execution and run the Automation
workflow using a service role.
7. In the Input parameters section, specify the required inputs. In the Automation Assume Role box,
paste the ARN of the IAM service role.
8. Choose Execute. The console displays the status of the Automation execution.

Running an Automation Workflow by Using an IAM Service Role (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run an Automation workflow that uses an IAM service role (or assume role).

To run an Automation workflow using a service role

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to start an Automation workflow that uses an IAM service role.

Linux

aws ssm start-automation-execution \

--document-name DocumentName \
--parameters
"ParametersRequiredByDocument","AutomationAssumeRole=arn:aws:iam::123456789012:role/
AmazonSSMAutomationRole"

Windows

aws ssm start-automation-execution ^

--document-name DocumentName ^

201
 AWS Systems Manager User Guide
Working with Automation Executions

--parameters
"ParametersRequiredByDocument","AutomationAssumeRole=arn:aws:iam::123456789012:role/
AmazonSSMAutomationRole"

PowerShell

Start-SSMAutomationExecution `
-DocumentName DocumentName `
-Parameter @{
"ParametersRequiredByDocument"="ParameterValues";
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/
AmazonSSMAutomationRole"}

Here is an example using the document AWS-RestartEC2Instance to restart the specified EC2
instance using the IAM service role AmazonSSMAutomationRole.

Linux

aws ssm start-automation-execution \

--document-name "AWS-RestartEC2Instance" \
--parameters
"InstanceId=i-1234567890abcdef0","AutomationAssumeRole=arn:aws:iam::123456789012:role/
AmazonSSMAutomationRole"

Windows

aws ssm start-automation-execution ^

--document-name "AWS-RestartEC2Instance" ^
--parameters
"InstanceId=i-1234567890abcdef0","AutomationAssumeRole=arn:aws:iam::123456789012:role/
AmazonSSMAutomationRole"

PowerShell

Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"InstanceId"="i-1234567890abcdef0";
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-
AutomationAdministrationRole"}

The system returns information like the following.

Linux

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

Windows

{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
}

202
 AWS Systems Manager User Guide
Working with Automation Executions

PowerShell

4105a4fc-f944-11e6-9d32-0123456789ab

3. Run the following command to retrieve the status of the Automation workflow.

Linux

aws ssm describe-automation-executions \

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

Windows

aws ssm describe-automation-executions ^

--filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"

PowerShell

Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "4105a4fc-f944-11e6-9d32-0123456789ab"}

The system returns information like the following.

Linux

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",
"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

Windows

{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionStatus": "InProgress",
"CurrentStepName": "stopInstances",

203
 AWS Systems Manager User Guide
Working with Automation Executions

"Outputs": {},
"DocumentName": "AWS-RestartEC2Instance",
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
"DocumentVersion": "1",
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local",
"Mode": "Auto",
"ExecutionStartTime": 1564600648.159,
"CurrentAction": "aws:changeInstanceState",
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/
Admin",
"LogFile": "",
"Targets": []
}
]
}

PowerShell

AutomationExecutionId : 4105a4fc-f944-11e6-9d32-0123456789ab
AutomationExecutionStatus : InProgress
AutomationType : Local
CurrentAction : aws:changeInstanceState
CurrentStepName : startInstances
DocumentName : AWS-RestartEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/
Admin
ExecutionEndTime : 1/1/0001 12:00:00 AM
ExecutionStartTime : 7/31/2019 7:17:28 PM
FailureMessage :
LogFile :
MaxConcurrency :
MaxErrors :
Mode : Auto
Outputs : {}
ParentAutomationExecutionId :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
Target :
TargetMaps : {}
TargetParameterName :
Targets : {}

For more examples of how to use Systems Manager Automation, see Automation
Walkthroughs (p. 400). For information about how to get started with Automation, see Getting Started
with Automation (p. 144).

Running an Automation Workflow by Using Delegated Administration

When you run an AWS Systems Manager Automation workflow, by default, the Automation runs in the
context of the AWS Identity and Access Management (IAM) user who initiated the execution. This means,
for example, if your IAM user account has administrator permissions, then the Automation runs with
administrator permissions and full access to the resources being configured by the Automation workflow.
As a security best practice, we recommend that you run Automation workflows by using an IAM service
role (also called an assumed role) that is configured with the AmazonSSMAutomationRole managed
policy. Using an IAM service role to run Automation is called delegated administration.

204
 AWS Systems Manager User Guide
Working with Automation Executions

When you use a service role, the Automation workflow is allowed to run against the AWS resources, but
the user who ran the Automation has restricted access (or no access) to those resources. For example, you
can configure a service role and use it with Automation to restart one or more Amazon EC2 instances.
The Automation workflow restarts the instances, but the service role does not give the user permission
to access those instances.

You can specify a service role at runtime when you run an Automation workflow, or you can create
custom Automation documents and specify the service role directly in the document. If you specify a
service role, either at runtime or in an Automation document, then the service runs in the context of the
specified service role. If you don't specify a service role, then the system creates a temporary session in
the context of the user and runs the Automation.
Note
You must specify a service role for Automation workflows that you expect to run longer than
12 hours. If you start a long-running Automation in the context of a user, the user's temporary
session expires after 12 hours.

Delegated administration ensures elevated security and control of your AWS resources. It also enables an
enhanced auditing experience because actions are being performed against your resources by a central
service role instead of multiple IAM accounts.

To properly illustrate how delegated administration can work in an organization, this topic describes the
following tasks as though these tasks were performed by three different people in an organization:

• Create a test IAM user account called AutomationRestrictedOperator (Administrator).

• Create an IAM service role for Automation (Administrator).
• Create a simple Automation document (based on a preexisting Automation document) that specifies
the service role (SSM Document Author).
• Run the Automation as the test user (Restricted Operator).

In some organizations, all three of these tasks are performed by the same person, but identifying
the different roles here shows how delegated administration enables enhanced security in complex
organizations.
Important
As a security best practice, we recommend that you always use a service role to run Automation
workflows, even if you are an administrator who performs all of these tasks.

The procedures in this section link to topics in other AWS guides or other Systems Manager topics. We
recommend that you open links to other topics in a new tab in your web browser so you don't lose your
place in this topic.

Topics
• Create a Test User Account (p. 205)
• Create an IAM Service Role for Automation (p. 206)
• Create a custom Automation Document (p. 206)
• Run the Custom Automation Document (p. 207)

Create a Test User Account

This section describes how to create an IAM test user account with restricted permissions. The
permissions set allows the user to run Automation workflows, but the user doesn't have access to the
AWS resources targeted by Automation. The operator can also view the results of the Automation
workflows. You start by creating the custom IAM permissions policy, and then you create the user
account and assign permissions to it.

205
 AWS Systems Manager User Guide
Working with Automation Executions

Create an IAM Test User

1. Create a permissions policy named OperatorRestrictedPermissions. For information about how

to create a new IAM permissions policy, see Create an IAM Policy (Console) in the IAM User Guide.
Create the policy on the JSON tab, and specify the following permissions set.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:DescribeAutomationExecutions",
"ssm:DescribeAutomationStepExecutions",
"ssm:DescribeDocument",
"ssm:GetAutomationExecution",
"ssm:GetDocument",
"ssm:ListDocuments",
"ssm:ListDocumentVersions",
"ssm:StartAutomationExecution"
],
"Resource":"*"
}
]
}

2. Create a new IAM user account named AutomationRestrictedOperator. For information about how
to create a new IAM user, see Creating IAM Users (Console) in the IAM User Guide. When prompted,
choose Attach existing policies directly, and choose the policy you just created.
3. Note the user name, password, and the Console login link. You will log into this account later in this
topic.

Create an IAM Service Role for Automation

The following procedure links to other topics to help you create the service role and to configure
Automation to trust this role.

To create the service role and enable Automation to trust it

1. Create the Automation service role. For information, see Task 1: Create a Service Role for
Automation (p. 147).
2. Note the service role Amazon Resource Name (ARN). You will specify this ARN in the next procedure.
3. Configure a trust policy so that Automation trusts the service role. For more information, see Task 2:
Add a Trust Relationship for Automation (p. 148).

Create a custom Automation Document

This section describes how to create a custom Automation document that restarts Amazon
EC2 instances. AWS provides a default SSM document for restarting instances called AWS-
RestartEC2Instance. The following procedure copies the content of that document to show you how to
enter the service role in a document when you create your own. By specifying the service role directly
in the document, the user running the document does not require iam:PassRole permissions. Without
iam:PassRole permissions, the user can't use the service role elsewhere in AWS.

To create a custom Automation document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

206
 AWS Systems Manager User Guide
Working with Automation Executions

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose Create document.
4. In the Name field, type a name for the document, such as Restart-EC2InstanceDemo.
5. In the Document type list, choose Automation document.
6. In the Content section, choose JSON, and then paste the following content. Replace
AssumeRoleARN with the ARN of the service role you created in the previous procedure.

{
"description": "Restart EC2 instances(s)",
"schemaVersion": "0.3",
"assumeRole": "AssumeRoleARN",
"parameters": {
"InstanceId": {
"type": "StringList",
"description": "(Required) EC2 Instance to restart"
}
},
"mainSteps": [
{
"name": "stopInstances",
"action": "aws:changeInstanceState",
"inputs": {
"InstanceIds": "{{ InstanceId }}",
"DesiredState": "stopped"
}
},
{
"name": "startInstances",
"action": "aws:changeInstanceState",
"inputs": {
"InstanceIds": "{{ InstanceId }}",
"DesiredState": "running"
}
}
]
}

7. Choose Create document.

Run the Custom Automation Document

The following procedure describes how to run the document you just created using the restricted
operator role you created earlier in this topic. The user can run the document you created earlier because
their IAM account permissions enable them to see and run the document. The user can't, however, log on
to the instances that you will restart with this Automation workflow.

1. In the https://console.aws.amazon.com/ec2/, copy the instance IDs for one or more instances that
you want to restart by using the following Automation workflow.
2. Sign out of the AWS Management Console, and then sign back in by using the test user account
Console login link that you copied earlier.
3. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
4. In the navigation pane, choose Automation.

-or-

207
 AWS Systems Manager User Guide
Working with Automation Executions

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Automation.
5. Choose Execute automation.
6. Choose the custom Automation document you created earlier in this topic.
7. In the Document details section, verify that Document version is set to 1 (Default).
8. Choose Next.
9. In the Execution mode section, choose Simple execution.
10. In the Input parameters section, type one or more instance IDs that you want to restart, and then
choose Execute.

Execution details describes the status of the Automation. Step 1 stops the instances. Step 2 starts the
instances.

Running Automation Workflows in Multiple AWS Regions and

Accounts
You can run AWS Systems Manager Automations across multiple AWS Regions and AWS accounts or
AWS Organizational Units (OUs) from an Automation management account. Running Automations in
multiple Regions and accounts or OUs reduces the time required to administer your AWS resources while
enhancing the security of your computing environment.

For example, you can centrally implement patching and security updates, remediate compliance drift on
VPC configurations or Amazon S3 bucket policies, and manage resources, such as Amazon EC2 instances,
at scale. The following graphic shows an example of a user who is running the AWS-RestartEC2Instances
document in multiple Regions and accounts from an Automation management account. The Automation
locates the instances by using the specified tags in the specified Regions and accounts.
Note
When you run an Automation across multiple Regions and accounts, you target resources
by using tags or the name of an AWS resource group. The Automation fails to run on those
resources that don't have the specified tag or that aren't included in the specified resource
group.

208
 AWS Systems Manager User Guide
Working with Automation Executions

Important
Your account is charged for running Automations in multiple Regions and accounts. Multi-
Region and account step executions are considered special steps. There is no step limit for
special steps, but your account is charged for each step processed by Systems Manager. For
more information, see the AWS Systems Manager Pricing page.

How It Works

Running Automations across multiple Regions and accounts or OUs works as follows:

1. Verify that all resources on which you want to run the Automation, in all Regions and accounts or OUs,
use identical tags. If they don't, you can add them to an AWS resource group and target that group.
For more information, see What Is AWS Resource Groups?
2. Sign in to the AWS Identity and Access Management (IAM) account that you want to configure as the
Automation Master account.
3. Use the procedure in this topic to create an IAM execution role called AWS-SystemsManager-
AutomationExecutionRole. This role gives the user permission to run Automation workflows.
4. Use the procedure in this topic to create a second IAM role called AWS-SystemsManager-
AutomationAdministrationRole. This role gives the user permission to run Automation workflows in
multiple AWS accounts and OUs.
5. Choose the Automation document, Regions, and accounts or OUs where you want to run the
Automation workflow.
6. Run the Automation.
7. Use the GetAutomationExecution, DescribeAutomationStepExecutions, and
DescribeAutomationExecutions API actions from the AWS Systems Manager console or the AWS CLI to
monitor workflow progress.

209
 AWS Systems Manager User Guide
Working with Automation Executions

Setting Up Management Account Permissions for Multi-Region and Multi-

Account Automation Execution
Use the following procedure to create the required IAM roles for Systems Manager Automation multi-
Region and multi-account execution by using AWS CloudFormation. This procedure describes how to
create the AWS-SystemsManager-AutomationExecutionRole role. You must create this role in every
account that you want to target to run multi-Region and multi-account Automations.

This procedure also describes how to create the AWS-SystemsManager-AutomationAdministrationRole

role. You only need to create this role in the Automation management account.

To create the required IAM roles for Multi-Region and Multi-Account Automation Executions
by using AWS CloudFormation

1. Download the AWS-SystemsManager-AutomationExecutionRole.zip folder. This folder includes the

AWS-SystemsManager-AutomationExecutionRole.json AWS CloudFormation template file.
2. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.
3. Choose Create Stack.
4. In the Choose a template section, choose Upload a template to Amazon S3.
5. Choose Browse, and then choose the AWS-SystemsManager-AutomationExecutionRole.json AWS
CloudFormation template file.
6. Choose Next.
7. On the Specify Details page, in the Stack Name field, enter a name.
8. In the Parameters section, in the MasterAccountID field, enter the ID for the account that you want
to use to run multi-Region and multi-account Automations.
9. Choose Next.
10. On the Options page, enter values for any options you want to use. Choose Next.
11. On the Review page, scroll down and choose the I acknowledge that AWS CloudFormation might
create IAM resources option.
12. Choose Create.

AWS CloudFormation shows the CREATE_IN_PROGRESS status for approximately three minutes.
The status changes to CREATE_COMPLETE.
13. Repeat this procedure in every account that you want to target to run multi-Region and multi-
account Automations.
14. Download the AWS-SystemManager-AutomationAdministrationRole.zip folder and repeat this
procedure for the AWS-SystemManager-AutomationAdministrationRole role. You only need
to create the AWS-SystemManager-AutomationAdministrationRole role in the Automation
management account.

Run an Automation in Multiple Regions and Accounts (Console)

The following procedure describes how to use the Systems Manager console to run an Automation in
multiple Regions and accounts from the Automation management account.

Before You Begin

Before you complete the following procedure, note the following information:

• AWS account IDs or OUs where you want to run the Automation.
• AWS Systems Manager Regions where you want to run the Automation.
• The tag key and the tag value, or the name of the resource group, where you want to run the
Automation.

210
 AWS Systems Manager User Guide
Working with Automation Executions

To run an Automation workflow in multiple Regions and accounts

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation, and then choose Execute automation.
3. In the Automation document list, choose a document. Choose one or more options in the
Document categories pane to filter SSM documents according to their purpose. To view a document
that you own, choose the Owned by me tab. To view a document that is shared with your account,
choose the Shared with me tab. To view all documents, choose the All documents tab.
Note
You can view information about a document by choosing the document name.
4. In the Document details section, verify that Document version is set to the version that you want to
run. The system includes the following version options:

• Default version at runtime: Choose this option if the Automation document is updated
periodically and a new default version is assigned.
• Latest version at runtime: Choose this option if the Automation document is updated
periodically, and you want to run the version that was most recently updated.
• 1 (Default): Choose this option to run the first version of the document, which is the default.
5. Choose Next.
6. On the Execute automation document page, choose Multi-account and Region.
7. In the Target accounts and Regions section, use the Accounts and organizational (OUs) field to
specify the different AWS accounts or AWS Organizational Units (OUs) where you want to run the
Automation. Separate multiple accounts or OUs with a comma.
8. Use the AWS Regions list to choose one or more Regions where you want to run the Automation.
9. Use the Multi-Region and account rate control options to restrict the Automation execution to a
limited number of accounts running in a limited number of Regions. These options don't restrict the
number of AWS resources that can run the Automations.

a. In the Location (account-Region pair) concurrency section, choose an option to restrict the
number of Automation workflows that can run in multiple accounts and Regions at the same
time. For example, if you choose to run an Automation in five (5) AWS accounts, which are
located in four (4) AWS Regions, then Systems Manager runs Automations in a total of 20
account-Region pairs. You can use this option to specify an absolute number, such as 2, so that
the Automation only runs in two account-Region pairs at the same time. Or you can specify
a percentage of the account-Region pairs that can run at the same time. For example, with
20 account-Region pairs, if you specify 20%, then the Automation simultaneously runs in a
maximum of five (5) account-Region pairs.

• Choose targets to enter an absolute number of account-Region pairs that can run the
Automation workflow simultaneously.
• Choose percent to enter a percentage of the total number of account-Region pairs that can
run the Automation workflow simultaneously.
b. In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors allowed before Automation stops
sending the workflow to other resources.
• Choose percent to enter a percentage of errors allowed before Automation stops sending the
workflow to other resources.
10. In the Targets section, choose how you want to target the AWS Resources where you want to run the
Automation. These options are required.

a. Use the Parameter list to choose a parameter. The items in the Parameter list are determined
by the parameters in the Automation document that you selected at the start of this procedure.

211
 AWS Systems Manager User Guide
Working with Automation Executions

By choosing a parameter you define the type of resource on which the Automation workflow
runs.
b. Use the Targets list to choose how you want to target resources. If you chose to target resources
by using AWS Resource Groups, then choose the name of the group from the Resource Group
list.

If you chose to target resources by using tags, then enter the tag key and (optionally) the tag
value in the fields provided. Choose Add.

If you chose to target resources by using parameter values, then enter the parameter value for
the parameter you chose in the Input parameters section.
11. In the Input parameters section, specify the required inputs. Optionally, you can choose an IAM
service role from the AutomationAssumeRole list.
Note
You may not need to choose some of the options in the Input parameters section. This
is because you targeted resources in multiple Regions and accounts by using tags or a
resource group. For example, if you chose the AWS-RestartEC2Instance document, then
you don't need to specify or choose instance IDs in the Input parameters section. The
Automation execution locates the instances to restart by using the tags you specified.
12. Use the options in the Rate control section to restrict the number of AWS resources that can run the
Automation within each account-Region pair.

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the Automation workflow
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the Automation workflow
simultaneously.
13. In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors allowed before Automation stops sending
the workflow to other resources.
• Choose percentage to enter a percentage of errors allowed before Automation stops sending the
workflow to other resources.
14. Choose Execute.

Run an Automation in Multiple Regions and Accounts (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to run an Automation in multiple Regions and accounts from the Automation management
account.

Before You Begin

Before you complete the following procedure, note the following information:

• AWS account IDs or OUs where you want to run the Automation.
• AWS Systems Manager Regions where you want to run the Automation.
• The tag key and the tag value, or the name of the resource group, where you want to run the
Automation.

To run an Automation workflow in multiple Regions and accounts

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

212
 AWS Systems Manager User Guide
Working with Automation Executions

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Use the following format to create a command to run an Automation workflow in multiple Regions
and accounts.

Linux

aws ssm start-automation-execution \

--document-name name_of_Automation_document \
--parameters
AutomationAssumeRole=arn:aws:iam::Automation_management_account_ID:role/AWS-
SystemsManager-AutomationAdministrationRole \
--target-parameter-name parameter_name (required) \
--targets Key=tag_key,Values=tag_value \
--target-locations
Accounts=account_ID_1,account_ID_2,account_ID_3,Regions=Region_1,Region_2,ExecutionRoleName=AWS
SystemsManager-AutomationExecutionRole

Windows

aws ssm start-automation-execution ^

--document-name name_of_Automation_document ^
--parameters
AutomationAssumeRole=arn:aws:iam::Automation_management_account_ID:role/AWS-
SystemsManager-AutomationAdministrationRole ^
--target-parameter-name parameter_name (required) ^
--targets Key=tag_key,Values=tag_value ^
--target-locations
Accounts=account_ID_1,account_ID_2,account_ID_3,Regions=Region_1,Region_2,ExecutionRoleName=AWS
SystemsManager-AutomationExecutionRole

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "target_key"
$Targets.Values = "target_value"

Start-SSMAutomationExecution `
-DocumentName "name_of_Automation_document" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::Automation_management_account_ID:role/AWS-
SystemsManager-AutomationAdministrationRole" } `
-TargetParameterName "parameter_name (required)" `
-Target $Targets `
-TargetLocation @{
"Accounts"="account_ID_1","account_ID_2","account_ID_3";
"Regions"="Region_1","Region_2";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

Here are a few examples.

Example 1: This example restarts Amazon EC2 instances in the 123456789012 and 987654321098
accounts, which are located in the us-east-2 and us-west-1 Regions. The instances must be
tagged with the tag key-pair value Env-PROD.

Linux

aws ssm start-automation-execution \

213
 AWS Systems Manager User Guide
Working with Automation Executions

--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=tag:Env,Values=PROD \
--target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-
west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

Windows

aws ssm start-automation-execution ^

--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^
--targets Key=tag:Env,Values=PROD ^
--target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-
west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "tag:Env"
$Targets.Values = "PROD"

Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-
AutomationAdministrationRole" } `
-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="123456789012","987654321098";
"Regions"="us-east-2","us-west-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

Example 2: This example restarts Amazon EC2 instances in the 123456789012 and 987654321098
accounts, which are located in the eu-central-1 Region. The instances must be members of the
prod-instances AWS resource group.

Linux

aws ssm start-automation-execution \

--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=ResourceGroup,Values=prod-instances \
--target-locations Accounts=123456789012,987654321098,Regions=eu-
central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

Windows

aws ssm start-automation-execution ^

--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^

214
 AWS Systems Manager User Guide
Working with Automation Executions

--targets Key=ResourceGroup,Values=prod-instances ^
--target-locations Accounts=123456789012,987654321098,Regions=eu-
central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ResourceGroup"
$Targets.Values = "prod-instances"

Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-
AutomationAdministrationRole" } `
-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="123456789012","987654321098";
"Regions"="eu-central-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

Example 3: This example restarts Amazon EC2 instances in the ou-1a2b3c-4d5e6c AWS
organizational unit (OU). The instances are located in the us-west-1 and us-west-2 Regions. The
instances must be members of the WebServices AWS resource group.

Linux

aws ssm start-automation-execution \

--document-name AWS-RestartEC2Instance \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole \
--target-parameter-name InstanceId \
--targets Key=ResourceGroup,Values=WebServices \
--target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-
west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

Windows

aws ssm start-automation-execution ^

--document-name AWS-RestartEC2Instance ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-
SystemsManager-AutomationAdministrationRole ^
--target-parameter-name InstanceId ^
--targets Key=ResourceGroup,Values=WebServices ^
--target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-
west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole

PowerShell

$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target

$Targets.Key = "ResourceGroup"
$Targets.Values = "WebServices"

Start-SSMAutomationExecution `
-DocumentName "AWS-RestartEC2Instance" `
-Parameter @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-
AutomationAdministrationRole" } `

215
 AWS Systems Manager User Guide
Working with Automation Executions

-TargetParameterName "InstanceId" `
-Target $Targets `
-TargetLocation @{
"Accounts"="ou-1a2b3c-4d5e6c";
"Regions"="us-west-1";
"ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

The system returns information similar to the following.

Linux

{
"AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

Windows

{
"AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

PowerShell

4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

3. Run the following command to view the workflow execution.

Linux

aws ssm describe-automation-executions \

--filters Key=ExecutionId,Values=4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

Windows

aws ssm describe-automation-executions ^

--filters Key=ExecutionId,Values=4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

PowerShell

Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"}

4. Run the following command to view details about the execution progress.

Linux

aws ssm get-automation-execution \

--automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

Windows

aws ssm get-automation-execution ^

--automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

216
 AWS Systems Manager User Guide
Working with Automation Documents

PowerShell

Get-SSMAutomationExecution `
-AutomationExecutionId a4a3c0e9-7efd-462a-8594-01234EXAMPLE

Note
You can also monitor the status of the workflow in the console. In the execution list, choose
the execution you just ran and then choose the Steps tab. This tab shows he status of the
workflow actions.

Related Content
Centralized multi-account and multi-Region patching with AWS Systems Manager Automation

Working with Automation Documents

A Systems Manager Automation document defines the actions that Systems Manager performs on your
managed instances and AWS resources. Documents use JavaScript Object Notation (JSON) or YAML, and
they include steps and parameters that you specify. Steps run in sequential order.

Automation documents are Systems Manager documents of type Automation, as opposed to Command
and Policy documents. Automation documents currently support schema version 0.3. Command
documents use schema version 1.2, 2.0, or 2.2. Policy documents use schema version 2.0 or later.

To view information about the actions or plugins that you can specify in a Systems Manager Automation
document, see Systems Manager Automation Actions Reference (p. 241). To view information about
the plugins for all other SSM documents, see SSM Document Plugin Reference (p. 800).
Important
If you run an automation that invokes other services by using an AWS Identity and Access
Management (IAM) service role, be aware that the service role must be configured with
permission to invoke those services. This requirement applies to all AWS Automation
documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-
CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few.
This requirement also applies to any custom Automation documents you create that invoke
other AWS services by using actions that call other services. For example, if you use the
aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few,
then you must configure the service role with permission to invoke those services. You can
enable permissions to other AWS services by adding an IAM inline policy to the role. For
more information, see (Optional) Add an Automation Inline Policy to Invoke Other AWS
Services (p. 147).

Contents
• Creating Dynamic Automation Workflows with Conditional Branching (p. 217)
• Invoking Other AWS Services from a Systems Manager Automation Workflow (p. 228)
• Sharing a Systems Manager Automation Document (p. 238)
• Systems Manager Automation Documents Reference (p. 240)

Creating Dynamic Automation Workflows with Conditional

Branching
By default, the steps that you define in the mainSteps section of an Automation document run in
sequential order. After one action is completed, the next action specified in the mainSteps section

217
 AWS Systems Manager User Guide
Working with Automation Documents

begins. Furthermore, if an action fails to run, the entire Automation workflow fails (by default). You
can use the aws:branch Automation action and the Automation document options described in this
section to create Automation workflows that perform conditional branching. This means that you can
create Automation workflows that jump to a different step after evaluating different choices or that
dynamically respond to changes when a step completes. Here is a list of options that you can use to
create dynamic Automation workflows:

• aws:branch: This automation action enables you to create a dynamic Automation workflow that
evaluates multiple choices in a single step and then jumps to a different step in the Automation
document based on the results of that evaluation.
• nextStep: This option specifies which step in an Automation workflow to process next after
successfully completing a step.
• isEnd: This option stops an Automation execution at the end of a specific step. The default value for
this option is false.
• isCritical: This option designates a step as critical for the successful completion of the Automation. If a
step with this designation fails, then Automation reports the final status of the Automation as Failed.
The default value for this option is true.
• onFailure: This option indicates whether the workflow should abort, continue, or go to a different step
on failure. The default value for this option is abort.

The following section describes the aws:branch Automation action. For more information about
the nextStep, isEnd, isCritical, and onFailure workflow options, see Examples of How to Use
Dynamic Workflow Options (p. 226).

Working with the aws:branch action

The aws:branch action offers the most dynamic conditional branching options for Automation
workflows. As noted earlier, this action enables your Automation workflow to evaluate multiple
conditions in a single step and then jump to a new step based on the results of that evaluation. The
aws:branch action functions like an IF-ELIF-ELSE statement in programming.

Here is a YAML example of an aws:branch step:

- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing

When you specify the aws:branch action for a step, you specify Choices that the workflow must
evaluate. The workflow can evaluate Choices based on the value of a parameter that you specified in
the Parameters section of the Automation document. The workflow can also evaluate Choices based
on output from a previous step.

The Automation workflow evaluates each choice by using a Boolean expression. If the evaluation
determines that the first choice is true, then the workflow jumps to the step designated for that choice.
If the evaluation determines that the first choice is false, then the workflow evaluates the next choice.
If your step includes three or more Choices, then the workflow evaluates each choice in sequential
order until it evaluates a choice that is true. The workflow then jumps to the designated step for the true
choice.

218
 AWS Systems Manager User Guide
Working with Automation Documents

If none of the Choices are true, the workflow checks to see if the step contains a Default value. A
Default value defines a step that the workflow should jump to if none of the choices are true. If no
Default value is specified for the step, then the Automation workflow processes the next step in the
document.

Here is an aws:branch step in YAML named chooseOSfromParameter. The step includes two Choices:
(NextStep: runWindowsCommand) and (NextStep: runLinuxCommand). The Automation workflow
evaluates these Choices to determine which command to run for the appropriate operating system. The
Variable for each choice uses {{OSName}}, which is a parameter that the document author defined in
the Parameters section of the document.

mainSteps:
- name: chooseOSfromParameter
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OSName}}"
StringEquals: Windows
- NextStep: runLinuxCommand
Variable: "{{OSName}}"
StringEquals: Linux

Here is an aws:branch step in YAML named chooseOSfromOutput. The step includes two Choices:
(NextStep: runPowerShellCommand) and (NextStep: runShellCommand). The Automation
workflow evaluates these Choices to determine which command to run for the appropriate operating
system. The Variable for each choice uses {{GetInstance.platform}}, which is the output from
an earlier step in the document. This example also includes an option called Default. If the workflow
evaluates both Choices, and neither choice is true, then the Automation workflow jumps to a step
called PostProcessing.

mainSteps:
- name: chooseOSfromOutput
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing

Creating an aws:branch step in an Automation document

When you create an aws:branch step in an Automation document, you define the Choices the
workflow should evaluate to determine which step the workflow should jump to next. As noted earlier,
Choices are evaluated by using a Boolean expression. Each choice must define the following options:

• NextStep: The next step in the Automation document to process if the designated choice is true.
• Variable: Specify either the name of a parameter that is defined in the Parameters section of the
Automation document, or specify an output object from a previous step in the Automation document.

Specify parameter variables by using the following form:

Variable: "{{name_of_parameter}}"

219
 AWS Systems Manager User Guide
Working with Automation Documents

Specify output object variables by using the following form:

Variable: "{{previousStepName.outputFieldName}}"
Note
Creating the output variable is described in more detail in the next section, About Creating the
Output Variable (p. 221).
• Operation: The criteria used to evaluate the choice, such as StringEquals: Linux. The
aws:branch action supports the following operations:

String operations
• StringEquals
• EqualsIgnoreCase
• StartsWith
• EndsWith
• Contains

Numeric operations
• NumericEquals
• NumericGreater
• NumericLesser
• NumericGreaterOrEquals
• NumericLesser
• NumericLesserOrEquals

Boolean operation
• BooleanEquals
Important
When you create an Automation document, the system validates each operation in the
document. If an operation is not supported, the system returns an error when you try to
create the document.
• Default: Specify a fallback step that the workflow should jump to if none of the Choices are true.
Note
If you don't want to specify a Default value, then you can specify the isEnd workflow
option. If none of the Choices are true and no Default value is specified, then the
Automation workflow stops at the end of the step.

Use the following templates to help you construct the aws:branch step in your Automation documents:

YAML template

mainSteps:
- name: a name for the step
action: aws:branch
inputs:
Choices:
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
- NextStep: step to jump to if evaluation = true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value

220
 AWS Systems Manager User Guide
Working with Automation Documents

Default:
step to jump to if all choices are false

JSON template

{
"mainSteps":[
{
"name":"a name for the step",
"action":"aws:branch",
"inputs":{
"Choices":[
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
},
{
"NextStep":"step to jump to if evaluation = true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
}
],
"Default":"step to jump to if all choices are false"
}
}
]
}

About Creating the Output Variable

To create an aws:branch choice that references the output from a previous step, you need to identify
the name of the previous step and the name of the output field. You then combine the names of the step
and the field by using the following format:

Variable: "{{previousStepName.outputFieldName}}"

For example, the first step below is named GetInstance. And then, under outputs, there
is a field called platform. In the second step (ChooseOSforCommands), the author wants
to reference the output from the platform field as a variable. To create the variable, simply
combine the step name (GetInstance) and the output field name (platform) to create Variable:
"{{GetInstance.platform}}".

mainSteps:
- Name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"

221
 AWS Systems Manager User Guide
Working with Automation Documents

StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep

Here is a JSON example that shows how "Variable": "{{ describeInstance.Platform }}" is
created from the previous step ("describeInstance") and the output field ("Platform").

{
"name": "describeInstance",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
},
"outputs": [
{
"Name": "Platform",
"Selector": "$.Reservations[0].Instances[0].Platform",
"Type": "String"
}
],
"nextStep": "branchOnInstancePlatform"
},
{
"name": "branchOnInstancePlatform",
"action": "aws:branch",
"inputs": {
"Choices": [
{
"NextStep": "runEC2RescueForWindows",
"Variable": "{{ describeInstance.Platform }}",
"StringEquals": "windows"
}
],
"Default": "runEC2RescueForLinux"
}
}

Example aws:branch Automation Documents

Here are some example Automation documents that use aws:branch.

Example 1: Using aws:branch with an output variable to run commands based on the operating
system type

In the first step of this sample (GetInstance), the document author uses the aws:executeAwsApi
action to call the ssm DescribeInstanceInformation API action. The author uses this action to
determine the type of operating system being used by an instance. The aws:executeAwsApi action
outputs the instance ID and the platform type.

In the second step (ChooseOSforCommands), the author uses the aws:branch action with two
Choices (NextStep: runPowerShellCommand) and (NextStep: runShellCommand). The
Automation workflow evaluates the operating system of the instance by using the output from the
previous step (Variable: "{{GetInstance.platform}}"). The Automation workflow jumps to a
step for the designated operating system.

222
 AWS Systems Manager User Guide
Working with Automation Documents

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
mainSteps:
- name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep
- name: runShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: runPowerShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S

Example 2: Using aws:branch with a parameter variable to run commands based on the operating
system type

The document author defines several parameter options at the beginning of the document in the
parameters section. One parameter is named OperatingSystemName. In the first step (ChooseOS),
the author uses the aws:branch action with two Choices (NextStep: runWindowsCommand) and
(NextStep: runLinuxCommand). The variable for these Choices references the parameter option

223
 AWS Systems Manager User Guide
Working with Automation Documents

specified in the parameters section (Variable: "{{OperatingSystemName}}"). When the user

runs this Automation workflow, they specify a value at runtime for OperatingSystemName. The
Automation workflow uses the runtime parameter during the Choices evaluation. The Automation
workflow jumps to a step for the designated operating system based on the runtime parameter specified
for OperatingSystemName.

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
OperatingSystemName:
type: String
LinuxInstanceId:
type: String
WindowsInstanceId:
type: String
mainSteps:
- name: ChooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OperatingSystemName}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{OperatingSystemName}}"
StringEquals: linux
Default:
Sleep
- name: runLinuxCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunShellScript"
InstanceIds:
- "{{LinuxInstanceId}}"
Parameters:
commands:
- ls
isEnd: true
- name: runWindowsCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunPowerShellScript"
InstanceIds:
- "{{WindowsInstanceId}}"
Parameters:
commands:
- date
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S

Creating Complex Branching Documents with Operators

You can create complex branching documents by using the And, Or, and Not operators in your
aws:branch steps.

The 'And' Operator

224
 AWS Systems Manager User Guide
Working with Automation Documents

Use the And operator when you want multiple variables to be true for a choice. In the following
example, the first choice evaluates if an instance is running and uses the Windows operating system.
If the evaluation of both of these variables is true, then the Automation workflow jumps to the
runPowerShellCommand step. If one or more of the variables is false, then the workflow evaluates the
variables for the second choice.

mainSteps:
- name: switch2
action: aws:branch
inputs:
Choices:
- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Windows
NextStep: runPowerShellCommand

- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Linux
NextStep: runShellCommand
Default:
sleep3

The 'Or' Operator

Use the Or operator when you want any of multiple variables to be true for a choice. In the following
example, the first choice evaluates if a parameter string is Windows and if the output from an AWS
Lambda step is true. If the evaluation determines that either of these variables is true, then the
Automation workflow jumps to the RunPowerShellCommand step. If both variables are false, then the
workflow evaluates the variables for the second choice.

- Or:
- Variable: "{{parameter1}}"
StringEquals: Windows
- Variable: "{{BooleanParam1}}"
BooleanEquals: true
NextStep: RunPowershellCommand
- Or:
- Variable: "{{parameter2}}"
StringEquals: Linux
- Variable: "{{BooleanParam2}}"
BooleanEquals: true
NextStep: RunShellScript

The 'Not' Operator

Use the Not operator when you want to jump to a step defined when a variable is not true. In the
following example, the first choice evaluates if a parameter string is Not Linux. If the evaluation
determines that the variable is not Linux, then the Automation workflow jumps to the sleep2 step. If
the evaluation of the first choice determines that it is Linux, then the workflow evaluates the next choice.

mainSteps:
- name: switch
action: aws:branch
inputs:
Choices:

225
 AWS Systems Manager User Guide
Working with Automation Documents

- NextStep: sleep2
Not:
Variable: "{{testParam}}"
StringEquals: Linux
- NextStep: sleep1
Variable: "{{testParam}}"
StringEquals: Windows
Default:
sleep3

Examples of How to Use Dynamic Workflow Options

This section includes different examples of how to use dynamic workflow options in an Automation
document. Each example in this section extends the following Automation document. This document
has two actions. The first action is named InstallMsiPackage. It uses the aws:runCommand action to
install an application on a Windows Server instance. The second action is named TestInstall. It uses
the aws:invokeLambdaFunction action to perform a test of the installed application if the application
installed successfully. Step one specifies onFailure: Abort. This means that if the application did not
install successfully, the Automation workflow execution stops before step two.

Example 1: Automation document with two linear actions

---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
automationAssumeRole:
type: String
description: "(Required) Assume role."
packageName:
type: String
description: "(Required) MSI package to be installed."
instanceIds:
type: String
description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
maxAttempts: 2
onFailure: Abort
inputs:
InstanceIds:
- i-02573cafcfEXAMPLE
- i-0471e04240EXAMPLE
- i-07782c72faEXAMPLE
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
...

Creating a Dynamic Workflow that Jumps to Different Steps by Using the onFailure Option

The following example uses the onFailure: step:step_name, nextStep, and isEnd options to
create a dynamic Automation workflow. With this example, if the InstallMsiPackage action fails, then

226
 AWS Systems Manager User Guide
Working with Automation Documents

the workflow jumps to an action called PostFailure (onFailure: step:PostFailure) to run an AWS
Lambda function to perform some action in the event the install failed. If the install succeeds, then the
workflow process jumps to the TestInstall action (nextStep: TestInstall). Both the TestInstall
and the PostFailure steps use the isEnd option (isEnd: true) so that the workflow finishes the
workflow execution when either of those steps is completed.
Note
Using the isEnd option in the last step of the mainSteps section is optional. If the last step
does not jump to other steps, then the Automation workflow stops after running the action in
the last step.

Example 2: A dynamic workflow that jumps to different steps

mainSteps
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:PostFailure
maxAttempts: 2
inputs:
InstanceIds:
- i-02573cafcfEXAMPLE
- i-0471e04240EXAMPLE
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestInstall
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
isEnd: true
- name: PostFailure
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: PostFailureRecoveryLambdaFunction
isEnd: true
...

Note
Before processing an Automation document, the system verifies that the document does not
create an infinite loop. If an infinite loop is detected, Automation returns an error and a circle
trace showing which steps create the loop.

Creating a Dynamic Workflow that Defines Critical Steps

You can specify that a step is critical for the overall success of the Automation workflow. If a critical
step fails, then Automation reports the status of the execution as failed, even if one or more steps
ran successfully. In the following example, the user identifies the VerifyDependencies step if the
InstallMsiPackage step fails (onFailure: step:VerifyDependencies). The user specifies that the
InstallMsiPackage step is not critical (isCritical: false). In this example, if the application
failed to install, Automation processes the VerifyDependencies step to determine if one or more
dependencies is missing, which therefore caused the application install to fail.

Example 3: Defining critical steps for the Automation workflow

---
name: InstallMsiPackage

227
 AWS Systems Manager User Guide
Working with Automation Documents

action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage
...

Invoking Other AWS Services from a Systems Manager

Automation Workflow
You can invoke other AWS services and other Systems Manager capabilities in your Automation workflow
by using the following Automation actions in your Automation documents.

• aws:executeAwsApi: This Automation action calls and runs AWS API actions. Most API actions are
supported, although not all API actions have been tested. For example, the following API actions
are supported: CreateImage, Delete bucket, RebootDBInstance, and CreateGroups, to name a few.
Streaming API actions, such as the Get Object action, aren't supported.
• aws:waitForAwsResourceProperty: This Automation action enables your workflow to wait for a
specific resource state or event state before continuing the workflow. For example, you can use this
action with the Amazon Relational Database Service (Amazon RDS) DescribeDBInstances API action to
pause an Automation workflow so that a database instance has time to start.
• aws:assertAwsResourceProperty: This Automation action enables you to assert a specific
resource state or event state for a specific Automation step. For example, you can specify that an
Automation step must wait for an Amazon EC2 instance to start. Then it will call the Amazon EC2
DescribeInstanceStatus API action with the DesiredValue property of running. This ensures that the
Automation workflow waits for a running instance and then continues when the instance is, in fact,
running.

Here is a sample Automation document in YAML that uses the aws:executeAwsApi action to disable read
and write permissions on an Amazon S3 bucket.

---
description: Disable S3-Bucket's public WriteRead access via private ACL
schemaVersion: "0.3"
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
S3BucketName:
type: String
description: (Required) S3 Bucket subject to access restriction
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the
actions on your behalf.
default: ""
mainSteps:
- name: DisableS3BucketPublicReadWrite
action: aws:executeAwsApi
inputs:
Service: s3
Api: PutBucketAcl
Bucket: "{{S3BucketName}}"
ACL: private

228
 AWS Systems Manager User Guide
Working with Automation Documents

isEnd: true
...

Here is a sample Automation document in YAML that uses all three actions. The document does the
following:

• Uses the aws:executeAwsApi action to call the Amazon EC2 DescribeImages API action to get the name
of a specific Windows Server 2016 AMI. It outputs the image ID as ImageId.
• Uses the aws:executeAwsApi action to call the Amazon EC2 RunInstances API action to launch one
instance that uses the ImageId from the previous step. It outputs the instance ID as InstanceId.
• Uses the aws:waitForAwsResourceProperty action to poll the Amazon EC2 DescribeInstanceStatus API
action to wait for the instance to reach the running state. The action times out in 60 seconds. The
step times out if the instance state failed to reach running after 60 seconds of polling.
• Uses the aws:assertAwsResourceProperty action to call the Amazon EC2 DescribeInstanceStatus API
action to assert that the instance is in the running state. The step fails if the instance state is not
running.

---
description: Sample Automation Document Using AWS API Actions
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Optional) The ARN of the role that allows Automation to perform the
actions on your behalf."
default: ''
ImageName:
type: String
description: "(Optional) Image Name to launch ec2 instance with."
default: "Windows_Server-2016-English-Full-Base-2018.07.11"
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
- name: launchOneInstance
action: aws:executeAwsApi
inputs:
Service: ec2
Api: RunInstances
ImageId: "{{ getImageId.ImageId }}"
MaxCount: 1
MinCount: 1
outputs:
- Name: InstanceId
Selector: "$.Instances[0].InstanceId"
Type: "String"
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
# timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
timeoutSeconds: 60

229
 AWS Systems Manager User Guide
Working with Automation Documents

inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
- name: assertInstanceStateRunning
action: aws:assertAwsResourceProperty
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
outputs:
- "launchOneInstance.InstanceId"
...

Working with Inputs and Outputs

Each of the previously described Automation actions enables you to call a specific API action by
specifying the service namespace, the API action name, the input parameters, and the output
parameters. Inputs are defined by the API action that you choose. You can view the API actions (also
called methods) by choosing a service in the left navigation on the following Services Reference page.
Choose a method in the Client section for the service that you want to invoke. For example, all API
actions (methods) for Amazon Relational Database Service (Amazon RDS) are listed on the following
page: Amazon RDS methods.

You can view the schema for each Automation action in the following locations:

• aws:assertAwsResourceProperty (p. 250)

• aws:executeAwsApi (p. 269)
• aws:waitForAwsResourceProperty (p. 283)

The schemas include descriptions of the required fields for using each action.

Using the Selector/PropertySelector Fields

Each Automation action requires that you specify either an output Selector (for aws:executeAwsApi)
or a PropertySelector (for aws:assertAwsResourceProperty and aws:waitForAwsResourceProperty).
These fields are used to process the JSON response from an AWS API action. These fields use the
JSONPath syntax.

Here is an example to help illustrate this concept for the aws:executeAwsAPi action:

---
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"

230
 AWS Systems Manager User Guide
Working with Automation Documents

outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
...

In the aws:executeAwsApi step getImageId, the workflow invokes the DescribeImages

API action and receives a response from ec2. The workflow then applies Selector -
"$.Images[0].ImageId" to the API response and assigns the selected value to the output ImageId
variable. Other steps in the same Automation workflow can use the value of ImageId by specifying
"{{ getImageId.ImageId }}".

Here is an example to help illustrate this concept for the aws:waitForAwsResourceProperty action:

---
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
# timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
timeoutSeconds: 60
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
...

In the aws:waitForAwsResourceProperty step waitUntilInstanceStateRunning, the workflow

invokes the DescribeInstanceStatus API action and receives a response from ec2. The workflow
then applies PropertySelector - "$.InstanceStatuses[0].InstanceState.Name" to the
response and checks if the specified returned value matches a value in the DesiredValues list (in this
case running). The step repeats the process until the response returns an instance state of running.

Using JSONPath in an Automation Workflow

A JSONPath expression is a string beginning with "$." that is used to select one of more components
within a JSON element. The following list includes information about JSONPath operators that are
supported by Systems Manager Automation:

• Dot-notated child (.): Use with a JSON object. This operator selects the value of a specific key.
• Deep-scan (..): Use with a JSON element. This operator scans the JSON element level by level and
selects a list of values with the specific key. Note that the return type of this operator is always a
JSON array. In the context of an Automation step output type, the operator can be either StringList or
MapList.
• Array-Index ([ ]): Use with a JSON array. This operator gets the value of a specific index.

To better understand JSONPath operators, review the following JSON response from the ec2
DescribeInstances API action. Below this response are several examples that show different results
by applying different JSONPath expressions to the response from the DescribeInstances API action.

{
"NextToken": "abcdefg",
"Reservations": [
{
"OwnerId": "123456789012",
"ReservationId": "r-abcd12345678910",

231
 AWS Systems Manager User Guide
Working with Automation Documents

"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-000000000000"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 16,
"Name": "running"
}
}
],
"Groups": []
},
{
"OwnerId": "123456789012",
"ReservationId": "r-12345678910abcd",
"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-111111111111"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 80,
"Name": "stopped"
}
}
],
"Groups": []
}
]
}

JSONPath Example 1: Get a specific String from a JSON response

JSONPath:
$.Reservations[0].Instances[0].ImageId

Returns:
"ami-12345678"

Type: String

JSONPath Example 2: Get a specific Boolean from a JSON response

JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination

232
 AWS Systems Manager User Guide
Working with Automation Documents

Returns:
true

Type: Boolean

JSONPath Example 3: Get a specific Integer from a JSON response

JSONPath:
$.Reservations[0].Instances[0].State.Code

Returns:
16

Type: Integer

JSONPath Example 4: Deep scan a JSON response, then get all of the values for VolumeId as a
StringList

JSONPath:
$.Reservations..BlockDeviceMappings..VolumeId

Returns:
[
"vol-000000000000",
"vol-111111111111"
]

Type: StringList

JSONPath Example 5: Get a specific BlockDeviceMappings object as a StringMap

JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0]

Returns:
{
"Ebs" : {
"DeleteOnTermination" : true,
"Status" : "attached",
"VolumeId" : "vol-000000000000"
},
"DeviceName" : "/dev/xvda"
}

Type: StringMap

JSONPath Example 6: Deep scan a JSON response, then get all of the State objects as a MapList

JSONPath:
$.Reservations..Instances..State

Returns:
[
{
"Code" : 16,
"Name" : "running"
},
{
"Code" : 80,
"Name" : "stopped"
}

233
 AWS Systems Manager User Guide
Working with Automation Documents

Type: MapList

Important
If you run an automation that invokes other services by using an AWS Identity and Access
Management (IAM) service role, be aware that the service role must be configured with
permission to invoke those services. This requirement applies to all AWS Automation
documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-
CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few.
This requirement also applies to any custom Automation documents you create that invoke
other AWS services by using actions that call other services. For example, if you use the
aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few,
then you must configure the service role with permission to invoke those services. You can
enable permissions to other AWS services by adding an IAM inline policy to the role. For
more information, see (Optional) Add an Automation Inline Policy to Invoke Other AWS
Services (p. 147).

Sample Walkthrough: Start an Amazon RDS Instance from a Systems Manager

Automation Workflow
This sample walkthrough shows you how to create and run an Automation document in YAML that uses
all three API actions to see if an Amazon Relational Database Service (Amazon RDS) database instance is
running. If the instance isn't running, the workflow starts it.

To invoke an Amazon RDS API action from a Systems Manager Automation

1. Open a text editor and paste the following Automation document content into the file. Specify an
Automation role and the instance ID to check. You will add the mainSteps actions later.

---
description: Start RDS instance
schemaVersion: "0.3"
assumeRole: "The_Automation_role_to_use_when_running_the_document"
parameters:
InstanceId: The_instance_ID_to_start
type: String
description: (Required) RDS instance ID to start
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the
actions on your behalf.
default: ""
mainSteps:

2. For the first step of the workflow, you need to determine if the instance is already running. You
can use the aws:assertAwsResourceProperty action to determine and assert a specific instance
status. Before you can add the aws:assertAwsResourceProperty action to the document, you must
determine and specify the required inputs. The following list describes how to determine and specify
the required inputs. You can view an example of how to enter this information in the Automation
document following the list.

a. View the schema to see all available inputs for the aws:assertAwsResourceProperty (p. 250)
action.
b. Determine the namespace of the service to invoke. You can view a list of AWS service
namespaces in Amazon Resource Names (ARNs) and AWS Service Namespaces in the Amazon
Web Services General Reference. The namespace for Amazon RDS is rds.
c. Determine which Amazon RDS API action enables you to view the status of a database instance.
You can view the API actions (also called methods) on the Amazon RDS methods page.

234
 AWS Systems Manager User Guide
Working with Automation Documents

d. Specify one or more request parameters for the DescribeDBInstances API action. For example,
this action uses the DBInstanceIdentifier request parameter.
e. Determine one or more PropertySelectors. A PropertySelector is a response object that
is returned by the request of this API action. For example, on the Amazon RDS methods.
Choose the describe_db_instances method and scroll down to the Response Structure
section. DBInstances is listed as a response object. For the purposes of this walkthrough,
specify DBInstances and DBInstanceStatus as the PropertySelectors. Remember that
PropertySelectors are entered by using JSONPath. This means that you format the information
in the Automation document like this:

PropertySelector: "$.DBInstances[0].DBInstanceStatus".
f. Specify one or more DesiredValues. If you don't know the values you want to specify, then run
the DescribeDBInstances API action to determine possible values. For this walkthrough, specify
available and starting.
g. Enter the information you collected into the Automation document as shown in the following
example.

---
description: Start RDS instance
schemaVersion: "0.3"
assumeRole: "The_Automation_role_to_use_when_running_the_document"
parameters:
InstanceId: The_instance_ID_to_start
type: String
description: (Required) RDS Instance Id to stop
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the
actions on your behalf.
default: ""
mainSteps:
-
name: AssertNotStartingOrAvailable
action: aws:assertAwsResourceProperty
isCritical: false
onFailure: step:StartInstance
nextStep: CheckStart
inputs:
Service: rds
Api: DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}"
PropertySelector: "$.DBInstances[0].DBInstanceStatus"
DesiredValues: ["available", "starting"]

3. Specify an aws:executeAwsApi action in the mainSteps section to start the instance if the previous
action determined that it is not started.

a. View the schema to see all available inputs for aws:executeAwsApi (p. 269).
b. Specify the Amazon RDS StartDBInstance API action to start the instance.
c. Enter the information you collected into the Automation document as shown in the following
example.

---
description: Start RDS instance
schemaVersion: "0.3"
assumeRole: "{{ The_Automation_role_to_use_when_running_the_document }}"
parameters:
InstanceId:

235
 AWS Systems Manager User Guide
Working with Automation Documents

type: String
description: (Required) RDS Instance Id to stop
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the
actions on your behalf.
default: ""
mainSteps:
-
name: AssertNotStartingOrAvailable
action: aws:assertAwsResourceProperty
isCritical: false
onFailure: step:StartInstance
nextStep: CheckStart
inputs:
Service: rds
Api: DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}"
PropertySelector: "$.DBInstances[0].DBInstanceStatus"
DesiredValues: ["available", "starting"]
-
name: StartInstance
action: aws:executeAwsApi
inputs:
Service: rds
Api: StartDBInstance
DBInstanceIdentifier: "{{InstanceId}}"

4. Specify an aws:waitForAwsResourceProperty action in the mainSteps section to wait for the instance
to start before finishing the Automation workflow.

a. View the schema to see all available inputs for the aws:waitForAwsResourceProperty (p. 283).
b. Specify the Amazon RDS DescribeDBInstances API action to determine the instance status.
c. Specify $.DBInstances[0].DBInstanceStatus as the PropertySelector
d. Specify available as the DesiredValue.
e. Enter the information you collected into the Automation document as shown in the following
example.

---
description: Start RDS instance
schemaVersion: "0.3"
assumeRole: "{{ The_Automation_role_to_use_when_running_the_document }}"
parameters:
InstanceId:
type: String
description: (Required) RDS Instance Id to stop
AutomationAssumeRole:
type: String
description: (Optional) The ARN of the role that allows Automation to perform the
actions on your behalf.
default: ""
mainSteps:
-
name: AssertNotStartingOrAvailable
action: aws:assertAwsResourceProperty
isCritical: false
onFailure: step:StartInstance
nextStep: CheckStart
inputs:
Service: rds
Api: DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}"

236
 AWS Systems Manager User Guide
Working with Automation Documents

PropertySelector: "$.DBInstances[0].DBInstanceStatus"
DesiredValues: ["available", "starting"]
-
name: StartInstance
action: aws:executeAwsApi
inputs:
Service: rds
Api: StartDBInstance
DBInstanceIdentifier: "{{InstanceId}}"
-
name: CheckStart
action: aws:waitForAwsResourceProperty
onFailure: Abort
maxAttempts: 10
timeoutSeconds: 600
inputs:
Service: rds
Api: DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}"
PropertySelector: "$.DBInstances[0].DBInstanceStatus"
DesiredValues: ["available"]
isEnd: true
...

5. Save the file as sample.yaml.

6. Run the following command in the AWS CLI to add the document to your AWS account.

aws ssm create-document --name sampleDoc --document-type Automation --document-format

YAML --content file://sample.yaml

7. Run the following command to run the Automation execution by using the document you just
created. Make a note of the execution ID returned by Systems Manager after you start the execution.

aws ssm start-automation-execution --document-name sampleDoc

8. Run the following command to view the execution status.

aws ssm get-automation-execution --automation-execution-id automation_execution_id

Predefined Automation Documents that Invoke AWS APIs

Systems Manager Automation includes the following predefined SSM Automation documents that
invoke AWS APIs.

Document Name Purpose

AWS-StartRdsInstance Start an Amazon RDS instance.

AWS-StopRdsInstance Stop an Amazon RDS instance.

AWS-RebootRdsInstance Reboot an Amazon RDS instance.

AWS-CreateSnapshot Create an Amazon Elastic Block Store (Amazon

EBS) volume snapshot.

AWS-DeleteSnapshot Delete an Amazon EBS volume snapshot.

AWS-ConfigureS3BucketLogging Enable logging on an Amazon Simple Storage

Service (Amazon S3) bucket.

237
 AWS Systems Manager User Guide
Working with Automation Documents

Document Name Purpose

AWS-DisableS3BucketPublicReadWrite Disable read and write permissions on an Amazon

S3 bucket by using a private ACL.

AWS-ConfigureS3BucketVersioning Enable or suspend versioning on an Amazon S3

bucket.

AWS-DeleteDynamoDbBackup Delete a Amazon DynamoDB (DynamoDB) table

backup.

Either click the links in the table above, or use the following procedure to view more details about these
Automation documents in the Systems Manager console.

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose a document, and then choose View details.
4. Choose the Content tab.

Sharing a Systems Manager Automation Document

You can share a Systems Manager Automation document by using the AWS Systems Manager console, or
by programmatically calling the ModifyDocumentPermission API operation using the AWS Command
Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or the AWS SDK. Before you share an
Automation document, get the AWS account IDs of the people with whom you want to share. You will
specify these account IDs when you share the document.

Topics
• Share an Automation Document (Console) (p. 238)
• Share a Document (AWS CLI) (p. 239)
• Share an Automation Document (AWS Tools for Windows PowerShell) (p. 240)

Share an Automation Document (Console)

To share an Automation document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. In the documents list, choose the document you want to share, and then choose View details. On
the Permissions tab, verify that you are the document owner. Only a document owner can share a
document.
4. To share the command publicly, choose Public and then choose Save. To share the command
privately, choose Private, enter the AWS account ID, choose Add, and then choose Save.

238
 AWS Systems Manager User Guide
Working with Automation Documents

Share a Document (AWS CLI)

The following procedure requires that you specify an AWS Region for your AWS CLI session.

1. Open the AWS CLI on your local computer and run the following command to specify your
credentials.

aws config

AWS Access Key ID: [your key]

AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
2. Use the following command to list all of the Systems Manager Automation documents that are
available for you. The list includes documents that you created and documents that were shared
with you.

aws ssm list-documents --document-filter-list key=Owner,value=all

key=DocumentType,value=Automation

3. Use the following command to list all of the Systems Manager Automation documents that you
created.

aws ssm list-documents --document-filter-list key=Owner,value=self

key=DocumentType,value=Automation

4. Use the following command to get a specific document.

aws ssm get-document --name document name

5. Use the following command to get a description of the document.

aws ssm describe-document --name document name

6. Use the following command to view the permissions for the document.

aws ssm describe-document-permission --name document name --permission-type Share

7. Use the following command to modify the permissions for the document and share it. You must be
the owner of the document to edit the permissions. This command privately shares the document
with a specific individual, based on that person's AWS account ID.

aws ssm modify-document-permission --name document name --permission-type Share --

account-ids-to-add AWS account ID

Use the following command to share a document publicly.

aws ssm modify-document-permission --name document name --permission-type Share --

account-ids-to-add all

239
 AWS Systems Manager User Guide
Working with Automation Documents

Share an Automation Document (AWS Tools for Windows PowerShell)

The following procedure requires that you specify a region for your PowerShell session.

1. Open AWS Tools for Windows PowerShell on your local computer and run the following command
to specify your credentials.

Set-AWSCredentials –AccessKey your key –SecretKey your key

2. Use the following command to set the region for your PowerShell session. The example uses the us-
west-2 region.

Set-DefaultAWSRegion -Region us-west-2

3. Use the following command to list all of the Systems Manager Automation documents available for
you. The list includes documents that you created and documents that were shared with you.

Get-SSMDocumentList -DocumentFilterList
(@{"key"="Owner";"value"="All"},@{"key"="DocumentType";"value"="Automation"})

4. Use the following command to list all of the Systems Manager Automation documents that you have
created.

Get-SSMDocumentList -DocumentFilterList
(@{"key"="Owner";"value"="Self"},@{"key"="DocumentType";"value"="Automation"})

5. Use the following command to get a specific document.

Get-SSMDocument –Name document name

6. Use the following command to get a description of the document.

Get-SSMDocumentDescription –Name document name

7. Use the following command to view the permissions of the document.

Get- SSMDocumentPermission –Name document name -PermissionType Share

8. Use the following command to modify the permissions for the document and share it. You must be
the owner of the document to edit the permissions. This command privately shares the document
with a specific individual, based on that person's AWS account ID.

Edit-SSMDocumentPermission –Name document name -PermissionType Share -

AccountIdsToAdd AWS account ID

Use the following command to share a document publicly.

Edit-SSMDocumentPermission -Name document name -AccountIdsToAdd ('all') -PermissionType

Share

Systems Manager Automation Documents Reference

To help you get started quickly, Systems Manager provides pre-defined Automation documents. These
documents are maintained by Amazon Web Services and AWS Support. The Actions Reference describes
the actions (or plugins) that you can specify in an Automation document. The Automation Document

240
 AWS Systems Manager User Guide
Working with Automation Documents

Details Reference describes each of the predefined Automation documents provided by AWS Systems
Manager and AWS Support.
Important
If you run an automation that invokes other services by using an AWS Identity and Access
Management (IAM) service role, be aware that the service role must be configured with
permission to invoke those services. This requirement applies to all AWS Automation
documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-
CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few.
This requirement also applies to any custom Automation documents you create that invoke
other AWS services by using actions that call other services. For example, if you use the
aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few,
then you must configure the service role with permission to invoke those services. You can
enable permissions to other AWS services by adding an IAM inline policy to the role. For
more information, see (Optional) Add an Automation Inline Policy to Invoke Other AWS
Services (p. 147).

Topics
• Systems Manager Automation Actions Reference (p. 241)
• Automation System Variables (p. 285)
• Systems Manager Automation Document Details Reference (p. 294)

Systems Manager Automation Actions Reference

This reference describes the actions (or plugins) that you can specify in an AWS Systems Manager
Automation document. For information about plugins for other types of SSM documents, see SSM
Document Plugin Reference (p. 800).

Systems Manager Automation runs steps defined in Automation documents. Each step is associated
with a particular action. The action determines the inputs, behavior, and outputs of the step. Steps are
defined in the mainSteps section of your Automation document.

You don't need to specify the outputs of an action or step. The outputs are predetermined by the action
associated with the step. When you specify step inputs in your Automation documents, you can reference
one or more outputs from an earlier step. For example, you can make the output of aws:runInstances
available for a subsequent aws:runCommand action. You can also reference outputs from earlier steps in
the Output section of the Automation document.
Important
If you run an automation that invokes other services by using an AWS Identity and Access
Management (IAM) service role, be aware that the service role must be configured with
permission to invoke those services. This requirement applies to all AWS Automation
documents (AWS-* documents) such as the AWS-ConfigureS3BucketLogging, AWS-
CreateDynamoDBBackup, and AWS-RestartEC2Instance documents, to name a few.
This requirement also applies to any custom Automation documents you create that invoke
other AWS services by using actions that call other services. For example, if you use the
aws:executeAwsApi, aws:CreateStack, or aws:copyImage actions, to name a few,
then you must configure the service role with permission to invoke those services. You can
enable permissions to other AWS services by adding an IAM inline policy to the role. For
more information, see (Optional) Add an Automation Inline Policy to Invoke Other AWS
Services (p. 147).

Topics
• Common Properties In All Actions (p. 242)
• aws:approve (p. 246)
• aws:assertAwsResourceProperty (p. 250)

241
 AWS Systems Manager User Guide
Working with Automation Documents

• aws:branch (p. 252)

• aws:changeInstanceState (p. 254)
• aws:copyImage (p. 255)
• aws:createImage (p. 257)
• aws:createStack (p. 258)
• aws:createTags (p. 264)
• aws:deleteImage (p. 265)
• aws:deleteStack (p. 266)
• aws:executeAutomation (p. 267)
• aws:executeAwsApi (p. 269)
• aws:executeStateMachine (p. 271)
• aws:invokeLambdaFunction (p. 272)
• aws:pause (p. 273)
• aws:runCommand (p. 274)
• aws:runInstances (p. 277)
• aws:sleep (p. 282)
• aws:waitForAwsResourceProperty (p. 283)

Common Properties In All Actions

The following properties are common to all actions:

JSON

"mainSteps": [
{
"name": "name",
"action": "action",
"maxAttempts": value,
"timeoutSeconds": value,
"onFailure": "value",
"inputs": {
...
}
},
{
"name": "name",
"action": "action",
"maxAttempts": value,
"timeoutSeconds": value,
"onFailure": "value",
"inputs": {
...
}
}
]

YAML

mainSteps:
- name: name
action: action
maxAttempts: value

242
 AWS Systems Manager User Guide
Working with Automation Documents

timeoutSeconds: value
onFailure: value
inputs:
...
- name: name
action: action
maxAttempts: value
timeoutSeconds: value
onFailure: value
inputs:
...

name

An identifier that must be unique across all step names in the document.

Type: String

Required: Yes
action

The name of the action the step is to run. aws:runCommand (p. 274) is an example of an action you
can specify here. This document provides detailed information about all available actions.

Type: String

Required: Yes
maxAttempts

The number of times the step should be retried in case of failure. If the value is greater than 1, the
step is not considered to have failed until all retry attempts have failed. The default value is 1.

Type: Integer

Required: No
timeoutSeconds

The execution timeout value for the step. If the timeout is reached and the value of maxAttempts
is greater than 1, then the step is not considered to have timed out until all retries have been
attempted. There is no default value for this field.

Type: Integer

Required: No
onFailure

Indicates whether the workflow should abort, continue, or go to a different step on failure. The
default value for this option is abort.

Type: String

Valid values: Abort | Continue | step:step_name

Required: No
isEnd

This option stops an Automation execution at the end of a specific step. The Automation execution
stops if the step execution failed or succeeded. The default value is false.

243
 AWS Systems Manager User Guide
Working with Automation Documents

Type: Boolean

Valid values: true | false

Required: No

Here is an example of how to enter this option in the mainSteps section of your document:

JSON

"mainSteps":[
{
"name":"InstallMsiPackage",
"action":"aws:runCommand",
"onFailure":"step:PostFailure",
"maxAttempts":2,
"inputs":{
"InstanceIds":[
"i-1234567890EXAMPLE","i-abcdefghiEXAMPLE"
],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"msiexec /i {{packageName}}"
]
}
},
"nextStep":"TestPackage"
},
{
"name":"TestPackage",
"action":"aws:invokeLambdaFunction",
"maxAttempts":1,
"timeoutSeconds":500,
"inputs":{
"FunctionName":"TestLambdaFunction"
},
"isEnd":true
}
]

YAML

mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:PostFailure
maxAttempts: 2
inputs:
InstanceIds:
- i-1234567890EXAMPLE
- i-abcdefghiEXAMPLE
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage
- name: TestPackage
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction

244
 AWS Systems Manager User Guide
Working with Automation Documents

isEnd: true

nextStep

Specifies which step in an Automation workflow to process next after successfully completing a step.

Here is an example of how to enter this option in the mainSteps section of your document:

JSON

"mainSteps":[
{
"name":"InstallMsiPackage",
"action":"aws:runCommand",
"onFailure":"step:PostFailure",
"maxAttempts":2,
"inputs":{
"InstanceIds":[
"i-1234567890EXAMPLE","i-abcdefghiEXAMPLE"
],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"msiexec /i {{packageName}}"
]
}
},
"nextStep":"TestPackage"
}
]

YAML

mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:PostFailure
maxAttempts: 2
inputs:
InstanceIds:
- i-1234567890EXAMPLE
- i-abcdefghiEXAMPLE
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage

isCritical

Designates a step as critical for the successful completion of the Automation. If a step with this
designation fails, then Automation reports the final status of the Automation as Failed. The default
value for this option is true.

Type: Boolean

Valid values: true | false

Required: No

Here is an example of how to enter this option in the mainSteps section of your document:

JSON

245
 AWS Systems Manager User Guide
Working with Automation Documents

"mainSteps":[
{
"name":"InstallMsiPackage",
"action":"aws:runCommand",
"onFailure":"step:SomeOtherStep",
"isCritical":false,
"maxAttempts":2,
"inputs":{
"InstanceIds":["i-1234567890EXAMPLE","i-abcdefghiEXAMPLE"],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"msiexec /i {{packageName}}"
]
}
},
"nextStep":"TestPackage"
}
]

YAML

mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:SomeOtherStep
isCritical: false
maxAttempts: 2
inputs:
InstanceIds:
- i-1234567890EXAMPLE,i-abcdefghiEXAMPLE
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage

inputs

The properties specific to the action.

Type: Map

Required: Yes

aws:approve

Temporarily pauses an Automation execution until designated principals either approve or reject the
action. After the required number of approvals is reached, the Automation execution resumes. You can
insert the approval step any place in the mainSteps section of your Automation document.
Note
The default timeout for this action is 7 days (604800 seconds). You can limit or extend the
timeout by specifying the timeoutSeconds parameter for an aws:approve step. If the
automation step reaches the timeout value before receiving all required approval decisions, then
the step and the automation stop running and return a status of Timed Out.

In the following example, the aws:approve action temporarily pauses the Automation workflow until one
approver either accepts or rejects the workflow. Upon approval, the document runs a simple PowerShell
command.

246
 AWS Systems Manager User Guide
Working with Automation Documents

JSON

{
"description":"RunInstancesDemo1",
"schemaVersion":"0.3",
"assumeRole":"{{ assumeRole }}",
"parameters":{
"assumeRole":{
"type":"String"
},
"message":{
"type":"String"
}
},
"mainSteps":[
{
"name":"approve",
"action":"aws:approve",
"timeoutSeconds":1000,
"onFailure":"Abort",
"inputs":{
"NotificationArn":"arn:aws:sns:us-east-2:12345678901:AutomationApproval",
"Message":"{{ message }}",
"MinRequiredApprovals":1,
"Approvers":[
"arn:aws:iam::12345678901:user/AWS-User-1"
]
}
},
{
"name":"run",
"action":"aws:runCommand",
"inputs":{
"InstanceIds":[
"i-1a2b3c4d5e6f7g"
],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"date"
]
}
}
}
]
}

YAML

---
description: RunInstancesDemo1
schemaVersion: '0.3'
assumeRole: "{{ assumeRole }}"
parameters:
assumeRole:
type: String
message:
type: String
mainSteps:
- name: approve
action: aws:approve
timeoutSeconds: 1000
onFailure: Abort
inputs:

247
 AWS Systems Manager User Guide
Working with Automation Documents

NotificationArn: arn:aws:sns:us-east-2:12345678901:AutomationApproval
Message: "{{ message }}"
MinRequiredApprovals: 1
Approvers:
- arn:aws:iam::12345678901:user/AWS-User-1
- name: run
action: aws:runCommand
inputs:
InstanceIds:
- i-1a2b3c4d5e6f7g
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- date

You can approve or deny Automations that are waiting for approval in the console.

To approve or deny waiting Automations

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Automation.
3. Choose the option next to an Automation with a status of Waiting.

4. Choose Approve/Deny.
5. Review the details of the Automation.
6. Choose either Approve or Deny, type an optional comment, and then choose Submit.

Input

JSON

{
"NotificationArn":"arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest",
"Message":"Please approve this step of the Automation.",
"MinRequiredApprovals":3,
"Approvers":[
"IamUser1",
"IamUser2",
"arn:aws:iam::12345678901:user/IamUser3",
"arn:aws:iam::12345678901:role/IamRole"
]
}

YAML

248
 AWS Systems Manager User Guide
Working with Automation Documents

NotificationArn: arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest
Message: Please approve this step of the Automation.
MinRequiredApprovals: 3
Approvers:
- IamUser1
- IamUser2
- arn:aws:iam::12345678901:user/IamUser3
- arn:aws:iam::12345678901:role/IamRole

NotificationArn

The ARN of an Amazon SNS topic for Automation approvals. When you specify an aws:approve
step in an Automation document, Automation sends a message to this topic letting principals know
that they must either approve or reject an Automation step. The title of the Amazon SNS topic must
be prefixed with "Automation".

Type: String

Required: No
Message

The information you want to include in the SNS topic when the approval request is sent. The
maximum message length is 4096 characters.

Type: String

Required: No
MinRequiredApprovals

The minimum number of approvals required to resume the Automation execution. If you don't
specify a value, the system defaults to one. The value for this parameter must be a positive number.
The value for this parameter can't exceed the number of approvers defined by the Approvers
parameter.

Type: Integer

Required: No
Approvers

A list of AWS authenticated principals who are able to either approve or reject the action. The
maximum number of approvers is 10. You can specify principals by using any of the following
formats:
• An AWS Identity and Access Management (IAM) user name
• An IAM user ARN
• An IAM role ARN
• An IAM assume role user ARN

Type: StringList

Required: Yes

Output

ApprovalStatus

The approval status of the step. The status can be one of the following: Approved, Rejected, or
Waiting. Waiting means that Automation is waiting for input from approvers.

249
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String
ApproverDecisions

A JSON map that includes the approval decision of each approver.

Type: MapList

aws:assertAwsResourceProperty

The aws:assertAwsResourceProperty action enables you to assert a specific resource state or event state
for a specific Automation step. For example, you can specify that an Automation step must wait for an
Amazon EC2 instance to start. Then it will call the Amazon EC2 DescribeInstanceStatus API action with
the DesiredValue property of running. This ensures that the Automation workflow waits for a running
instance and then continues when the instance is, in fact, running.

For more information and examples of how to use this action, see Invoking Other AWS Services from a
Systems Manager Automation Workflow (p. 228).

Input

Inputs are defined by the API action that you choose.

JSON

{
"action": "aws:assertAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API action or method name",
"API action inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property values"
]
}
}

YAML

action: aws:assertAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API action or method name
API action inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property values

Service

The AWS service namespace that contains the API action that you want to run. For example, the
namespace for Systems Manager is ssm. The namespace for Amazon EC2 is ec2. You can view a list
of supported AWS service namespaces in the Available Services section of the AWS CLI Command
Reference.

Type: String

Required: Yes

250
 AWS Systems Manager User Guide
Working with Automation Documents

Api

The name of the API action that you want to run. You can view the API actions (also called methods)
by choosing a service in the left navigation on the following Services Reference page. Choose a
method in the Client section for the service that you want to invoke. For example, all API actions
(methods) for Amazon Relational Database Service (Amazon RDS) are listed on the following page:
Amazon RDS methods.

Type: String

Required: Yes
API action inputs

One or more API action inputs. You can view the available inputs (also called parameters) by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to see the available parameters, such as DBInstanceIdentifier, Name, and
Values. Use the following format to specify more than one input.

JSON

"inputs":{
"Service":"The official namespace of the service",
"Api":"The API action name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}

YAML

inputs:
Service: The official namespace of the service
Api: The API action name
API input 1: A value
API Input 2: A value
API Input 3: A value

Type: Determined by chosen API action

Required: Yes
PropertySelector

The JSONPath to a specific attribute in the response object. You can view the response objects by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to the Response Structure section. DBInstances is listed as a response
object.

Type: Integer, Boolean, String, StringList, StringMap, or MapList

Required: Yes
DesiredValues

The expected status or state on which to continue the Automation workflow. If you specify a
Boolean value, you must use a capital letter such as True or False.

251
 AWS Systems Manager User Guide
Working with Automation Documents

Type: Varies

Required: Yes

aws:branch

The aws:branch action enables you to create a dynamic Automation workflow that evaluates different
choices in a single step and then jumps to a different step in the Automation document based on the
results of that evaluation.

When you specify the aws:branch action for a step, you specify Choices that the workflow must
evaluate. The Choices can be based on either a value that you specified in the Parameters section
of the Automation document, or a dynamic value generated as the output from the previous step. The
Automation workflow evaluates each choice by using a Boolean expression. If the first choice is true,
then the workflow jumps to the step designated for that choice. If the first choice is false, the workflow
evaluates the next choice. The workflow continues evaluating each choice until it process a true choice.
The workflow then jumps to the designated step for the true choice.

If none of the choices are true, the workflow checks to see if the step contains a default value. A
default value defines a step that the workflow should jump to if none of the choices are true. If no
default value is specified for the step, then the Automation workflow processes the next step in the
document.

The aws:branch action supports complex choice evaluations by using a combination of And, Not, and
Or operators. For more information about how to use aws:branch, including example documents and
examples that use different operators, see Creating Dynamic Automation Workflows with Conditional
Branching (p. 217).

Input

Specify one or more Choices in a step. The Choices can be based on either a value that you specified
in the Parameters section of the Automation document, or a dynamic value generated as the output
from the previous step. Here is a YAML sample that evaluates a parameter.

mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example:
OS_name}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example:
OS_name}}"
StringEquals: linux
Default:
sleep3

Here is a YAML sample that evaluates output from a previous step.

mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Windows

252
 AWS Systems Manager User Guide
Working with Automation Documents

- NextStep: runShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Linux
Default:
sleep3

Choices

One or more expressions that the Automation should evaluate when determining the next step to
process. Choices are evaluated by using a Boolean expression. Each choice must define the following
options:
• NextStep: The next step in the Automation document to process if the designated choice is true.
• Variable: Specify either the name of a parameter that is defined in the Parameters section of
the Automation document. Or specify an output object from a previous step in the Automation
document. For more information about creating variables for aws:branch, see About Creating
the Output Variable (p. 221).
• Operation: The criteria used to evaluate the choice. The aws:branch action supports the
following operations:

String operations
• StringEquals
• EqualsIgnoreCase
• StartsWith
• EndsWith
• Contains

Numeric operations
• NumericEquals
• NumericGreater
• NumericLesser
• NumericGreaterOrEquals
• NumericLesser
• NumericLesserOrEquals

Boolean operation
• BooleanEquals
Important
When you create an Automation document, the system validates each operation in the
document. If an operation is not supported, the system returns an error when you try to
create the document.
Default

The name of a step the workflow should jump to if none of the Choices are true.

Type: String

Required: No

Note
The aws:branch action supports And, Or, and Not operators. For examples of aws:branch
that use operators, see Creating Dynamic Automation Workflows with Conditional
Branching (p. 217).

253
 AWS Systems Manager User Guide
Working with Automation Documents

aws:changeInstanceState

Changes or asserts the state of the instance.

This action can be used in assert mode (do not run the API to change the state but verify the instance is
in the desired state.) To use assert mode, set the CheckStateOnly parameter to true. This mode is useful
when running the Sysprep command on Windows, which is an asynchronous command that can run in
the background for a long time. You can ensure that the instance is stopped before you create an AMI.

Input

JSON

{
"name":"stopMyInstance",
"action": "aws:changeInstanceState",
"maxAttempts": 3,
"timeoutSeconds": 3600,
"onFailure": "Abort",
"inputs": {
"InstanceIds": ["i-1234567890abcdef0"],
"CheckStateOnly": true,
"DesiredState": "stopped"
}
}

YAML

name: stopMyInstance
action: aws:changeInstanceState
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
InstanceIds:
- i-1234567890abcdef0
CheckStateOnly: true
DesiredState: stopped

InstanceIds

The IDs of the instances.

Type: StringList

Required: Yes
CheckStateOnly

If false, sets the instance state to the desired state. If true, asserts the desired state using polling.

Default: false

Type: Boolean

Required: No
DesiredState

The desired state. When set to running, this action waits for the Amazon EC2 state to be Running,
the Instance Status to be OK, and the System Status to be OK before completing.

254
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Valid values: running | stopped | terminated

Required: Yes
Force

If set, forces the instances to stop. The instances do not have an opportunity to flush file system
caches or file system metadata. If you use this option, you must perform file system check and repair
procedures. This option is not recommended for Windows instances.

Type: Boolean

Required: No
AdditionalInfo

Reserved.

Type: String

Required: No

Output

None

aws:copyImage

Copies an AMI from any region into the current region. This action can also encrypt the new AMI.

Input

This action supports most CopyImage parameters. For more information, see CopyImage.

The following example creates a copy of an AMI in the Seoul region (SourceImageID: ami-0fe10819.
SourceRegion: ap-northeast-2). The new AMI is copied to the region where you initiated the
Automation action. The copied AMI will be encrypted because the optional Encrypted flag is set to
true.

JSON

{
"name": "createEncryptedCopy",
"action": "aws:copyImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"SourceImageId": "ami-0fe10819",
"SourceRegion": "ap-northeast-2",
"ImageName": "Encrypted Copy of LAMP base AMI in ap-northeast-2",
"Encrypted": true
}
}

YAML

name: createEncryptedCopy
action: aws:copyImage

255
 AWS Systems Manager User Guide
Working with Automation Documents

maxAttempts: 3
onFailure: Abort
inputs:
SourceImageId: ami-0fe10819
SourceRegion: ap-northeast-2
ImageName: Encrypted Copy of LAMP base AMI in ap-northeast-2
Encrypted: true

SourceRegion

The region where the source AMI currently exists.

Type: String

Required: Yes
SourceImageId

The AMI ID to copy from the source region.

Type: String

Required: Yes
ImageName

The name for the new image.

Type: String

Required: Yes
ImageDescription

A description for the target image.

Type: String

Required: No
Encrypted

Encrypt the target AMI.

Type: Boolean

Required: No
KmsKeyId

The full Amazon Resource Name (ARN) of the AWS Key Management Service CMK to use when
encrypting the snapshots of an image during a copy operation. For more information, see
CopyImage.

Type: String

Required: No
ClientToken

A unique, case-sensitive identifier that you provide to ensure request idempotency. For more
information, see CopyImage.

Type: String

256
 AWS Systems Manager User Guide
Working with Automation Documents

Required: No

Output

ImageId

The ID of the copied image.

ImageState

The state of the copied image.

Valid values: available | pending | failed

aws:createImage

Creates a new AMI from an instance that is either running or stopped.

Input

This action supports most CreateImage parameters. For more information, see CreateImage.

JSON

{
"name": "createMyImage",
"action": "aws:createImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"InstanceId": "i-1234567890abcdef0",
"ImageName": "AMI Created on{{global:DATE_TIME}}",
"NoReboot": true,
"ImageDescription": "My newly created AMI"
}
}

YAML

name: createMyImage
action: aws:createImage
maxAttempts: 3
onFailure: Abort
inputs:
InstanceId: i-1234567890abcdef0
ImageName: AMI Created on{{global:DATE_TIME}}
NoReboot: true
ImageDescription: My newly created AMI

InstanceId

The ID of the instance.

Type: String

Required: Yes
ImageName

The name for the image.

257
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: Yes
ImageDescription

A description of the image.

Type: String

Required: No
NoReboot

A boolean literal.

By default, Amazon EC2 attempts to shut down and reboot the instance before creating the image.
If the No Reboot option is set to true, Amazon EC2 doesn't shut down the instance before creating
the image. When this option is used, file system integrity on the created image can't be guaranteed.

If you do not want the instance to run after you create an AMI image from it, first use
the aws:changeInstanceState (p. 254) plugin to stop the instance, and then use this
aws:createImage plugin with the NoReboot option set to true.

Type: Boolean

Required: No
BlockDeviceMappings

The block devices for the instance.

Type: Map

Required: No

Output

ImageId

The ID of the newly created image.

ImageState

An execution script provided as a string literal value. If a literal value is entered, then it must be
Base64-encoded.

Required: No

aws:createStack

Creates a new AWS CloudFormation stack from a template.

Input

JSON

{
"name": "makeStack",
"action": "aws:createStack",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {

258
 AWS Systems Manager User Guide
Working with Automation Documents

"Capabilities": [
"CAPABILITY_IAM"
],
"StackName": "myStack",
"TemplateURL": "http://s3.amazonaws.com/mybucket/myStackTemplate",
"TimeoutInMinutes": 5
}
}

YAML

name: makeStack
action: aws:createStack
maxAttempts: 1
onFailure: Abort
inputs:
Capabilities:
- CAPABILITY_IAM
StackName: myStack
TemplateURL: http://s3.amazonaws.com/mybucket/myStackTemplate
TimeoutInMinutes: 5

Capabilities

A list of values that you specify before AWS CloudFormation can create certain stacks. Some stack
templates include resources that can affect permissions in your AWS account. For example, creating
new AWS Identity and Access Management (IAM) users can affect permissions in your account. For
those stacks, you must explicitly acknowledge their capabilities by specifying this parameter.

The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. The following resources
require you to specify this parameter.
• AWS::IAM::AccessKey
• AWS::IAM::Group
• AWS::IAM::InstanceProfile
• AWS::IAM::Policy
• AWS::IAM::Role
• AWS::IAM::User
• AWS::IAM::UserToGroupAddition

If your stack template contains these resources, we recommend that you review all permissions
associated with them and edit their permissions, if necessary.

If you have IAM resources, you can specify either capability. If you have IAM resources with custom
names, you must specify CAPABILITY_NAMED_IAM. If you don't specify this parameter, this action
returns an InsufficientCapabilities error.

For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Type: array of Strings

Valid Values: CAPABILITY_IAM | CAPABILITY_NAMED_IAM

Required: No
ClientRequestToken

A unique identifier for this CreateStack request. Specify this token if you set maxAttempts in this
step to a value greater than 1. By specifying this token, AWS CloudFormation knows that you're not
attempting to create a new stack with the same name.

259
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: No

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9][-a-zA-Z0-9]*
DisableRollback

Set to true to disable rollback of the stack if stack creation failed.

Conditional: You can specify either the DisableRollback parameter or the OnFailure parameter,
but not both.

Default: false

Type: Boolean

Required: No
NotificationARNs

The Amazon SNS topic ARNs for publishing stack-related events. You can find SNS topic ARNs using
the Amazon SNS console, https://console.aws.amazon.com/sns/v3/home.

Type: array of Strings

Array Members: Maximum number of 5 items.

Required: No
OnFailure

Determines the action to take if stack creation failed. You must specify DO_NOTHING, ROLLBACK, or
DELETE.

Conditional: You can specify either the OnFailure parameter or the DisableRollback parameter,
but not both.

Default: ROLLBACK

Type: String

Valid Values: DO_NOTHING | ROLLBACK | DELETE

Required: No
Parameters

A list of Parameter structures that specify input parameters for the stack. For more information,
see the Parameter data type.

Type: array of Parameter objects

Required: No
ResourceTypes

The template resource types that you have permissions to work with for this create stack action.
For example: AWS::EC2::Instance, AWS::EC2::*, or Custom::MyCustomInstance. Use the
following syntax to describe template resource types.
• For all AWS resources:

260
 AWS Systems Manager User Guide
Working with Automation Documents

AWS::*

• For all custom resources:

Custom::*

• For a specific custom resource:

Custom::logical_ID

• For all resources of a particular AWS service:

AWS::service_name::*

• For a specific AWS resource:

AWS::service_name::resource_logical_ID

If the list of resource types doesn't include a resource that you're creating, the stack creation fails. By
default, AWS CloudFormation grants permissions to all resource types. IAM uses this parameter for
AWS CloudFormation-specific condition keys in IAM policies. For more information, see Controlling
Access with AWS Identity and Access Management.

Type: array of Strings

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No
RoleARN

The Amazon Resource Name (ARN) of an IAM role that AWS CloudFormation assumes to create
the stack. AWS CloudFormation uses the role's credentials to make calls on your behalf. AWS
CloudFormation always uses this role for all future operations on the stack. As long as users have
permission to operate on the stack, AWS CloudFormation uses this role even if the users don't have
permission to pass it. Ensure that the role grants the least amount of privileges.

If you don't specify a value, AWS CloudFormation uses the role that was previously associated with
the stack. If no role is available, AWS CloudFormation uses a temporary session that is generated
from your user credentials.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
StackName

The name that is associated with the stack. The name must be unique in the region in which you are
creating the stack.
Note
A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It
must start with an alphabetic character and cannot be longer than 128 characters.

Type: String

Required: Yes

261
 AWS Systems Manager User Guide
Working with Automation Documents

StackPolicyBody

Structure containing the stack policy body. For more information, see Prevent Updates to Stack
Resources.

Conditional: You can specify either the StackPolicyBody parameter or the StackPolicyURL
parameter, but not both.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 16384.

Required: No
StackPolicyURL

Location of a file containing the stack policy. The URL must point to a policy located in an Amazon
S3 bucket in the same region as the stack. The maximum file size allowed for the stack policy is 16
KB.

Conditional: You can specify either the StackPolicyBody parameter or the StackPolicyURL
parameter, but not both.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1350.

Required: No
Tags

Key-value pairs to associate with this stack. AWS CloudFormation also propagates these tags to the
resources created in the stack. You can specify a maximum number of 10 tags.

Type: array of Tag objects

Required: No
TemplateBody

Structure containing the template body with a minimum length of 1 byte and a maximum length of
51,200 bytes. For more information, see Template Anatomy.

Conditional: You can specify either the TemplateBody parameter or the TemplateURL parameter,
but not both.

Type: String

Length Constraints: Minimum length of 1.

Required: No
TemplateURL

Location of a file containing the template body. The URL must point to a template that is located
in an Amazon S3 bucket. The maximum size allowed for the template is 460,800 bytes. For more
information, see Template Anatomy.

Conditional: You can specify either the TemplateBody parameter or the TemplateURL parameter,
but not both.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

262
 AWS Systems Manager User Guide
Working with Automation Documents

Required: No
TimeoutInMinutes

The amount of time that can pass before the stack status becomes CREATE_FAILED. If
DisableRollback is not set or is set to false, the stack will be rolled back.

Type: Integer

Valid Range: Minimum value of 1.

Required: No

Outputs

StackId

Unique identifier of the stack.

Type: String
StackStatus

Current status of the stack.

Type: String

Valid Values: CREATE_IN_PROGRESS | CREATE_FAILED | CREATE_COMPLETE

| ROLLBACK_IN_PROGRESS | ROLLBACK_FAILED | ROLLBACK_COMPLETE
| DELETE_IN_PROGRESS | DELETE_FAILED | DELETE_COMPLETE |
UPDATE_IN_PROGRESS | UPDATE_COMPLETE_CLEANUP_IN_PROGRESS |
UPDATE_COMPLETE | UPDATE_ROLLBACK_IN_PROGRESS | UPDATE_ROLLBACK_FAILED |
UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_ROLLBACK_COMPLETE |
REVIEW_IN_PROGRESS

Required: Yes
StackStatusReason

Success or failure message associated with the stack status.

Type: String

Required: No

For more information, see CreateStack.

Security Considerations

Before you can use the aws:createStack action, you must assign the following policy to the IAM
Automation assume role. For more information about the assume role, see Task 1: Create a Service Role
for Automation (p. 147).

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",

263
 AWS Systems Manager User Guide
Working with Automation Documents

"cloudformation:CreateStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}

aws:createTags

Create new tags for Amazon EC2 instances or Systems Manager managed instances.

Input

This action supports most EC2 CreateTags and SSM AddTagsToResource parameters. For more
information, see CreateTags and AddTagsToResource.

The following example shows how to tag an AMI and an instance as being production resources for a
particular department.

JSON

{
"name": "createTags",
"action": "aws:createTags",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"ResourceType": "EC2",
"ResourceIds": [
"ami-9a3768fa",
"i-02951acd5111a8169"
],
"Tags": [
{
"Key": "production",
"Value": ""
},
{
"Key": "department",
"Value": "devops"
}
]
}
}

YAML

name: createTags
action: aws:createTags
maxAttempts: 3
onFailure: Abort
inputs:
ResourceType: EC2
ResourceIds:
- ami-9a3768fa
- i-02951acd5111a8169
Tags:
- Key: production
Value: ''
- Key: department
Value: devops

264
 AWS Systems Manager User Guide
Working with Automation Documents

ResourceIds

The IDs of the resource(s) to be tagged. If resource type is not “EC2”, this field can contain only a
single item.

Type: String List

Required: Yes
Tags

The tags to associate with the resource(s).

Type: List of Maps

Required: Yes
ResourceType

The type of resource(s) to be tagged. If not supplied, the default value of “EC2” is used.

Type: String

Required: No

Valid Values: EC2 | ManagedInstance | MaintenanceWindow | Parameter

Output

None

aws:deleteImage

Deletes the specified image and all related snapshots.

Input

This action supports only one parameter. For more information, see the documentation for
DeregisterImage and DeleteSnapshot.

JSON

{
"name": "deleteMyImage",
"action": "aws:deleteImage",
"maxAttempts": 3,
"timeoutSeconds": 180,
"onFailure": "Abort",
"inputs": {
"ImageId": "ami-12345678"
}
}

YAML

name: deleteMyImage
action: aws:deleteImage
maxAttempts: 3
timeoutSeconds: 180
onFailure: Abort
inputs:
ImageId: ami-12345678

265
 AWS Systems Manager User Guide
Working with Automation Documents

ImageId

The ID of the image to be deleted.

Type: String

Required: Yes

Output

None

aws:deleteStack

Deletes an AWS CloudFormation stack.

Input

JSON

{
"name":"deleteStack",
"action":"aws:deleteStack",
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"StackName":"{{stackName}}"
}
}

YAML

name: deleteStack
action: aws:deleteStack
maxAttempts: 1
onFailure: Abort
inputs:
StackName: "{{stackName}}"

ClientRequestToken

A unique identifier for this DeleteStack request. Specify this token if you plan to retry requests so
that AWS CloudFormation knows that you're not attempting to delete a stack with the same name.
You can retry DeleteStack requests to verify that AWS CloudFormation received them.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z][-a-zA-Z0-9]*

Required: No
RetainResources.member.N

This input applies only to stacks that are in a DELETE_FAILED state. A list of logical resource IDs for
the resources you want to retain. During deletion, AWS CloudFormation deletes the stack, but does
not delete the retained resources.

Retaining resources is useful when you can't delete a resource, such as a non-empty Amazon S3
bucket, but you want to delete the stack.

266
 AWS Systems Manager User Guide
Working with Automation Documents

Type: array of strings

Required: No
RoleARN

The Amazon Resource Name (ARN) of an IAM role that AWS CloudFormation assumes to create
the stack. AWS CloudFormation uses the role's credentials to make calls on your behalf. AWS
CloudFormation always uses this role for all future operations on the stack. As long as users have
permission to operate on the stack, AWS CloudFormation uses this role even if the users don't have
permission to pass it. Ensure that the role grants the least amount of privileges.

If you don't specify a value, AWS CloudFormation uses the role that was previously associated with
the stack. If no role is available, AWS CloudFormation uses a temporary session that is generated
from your user credentials.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No
StackName

The name or the unique stack ID that is associated with the stack.

Type: String

Required: Yes

Security Considerations

Before you can use the aws:deleteStack action, you must assign the following policy to the IAM
Automation assume role. For more information about the assume role, see Task 1: Create a Service Role
for Automation (p. 147).

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}

aws:executeAutomation

Runs a secondary Automation workflow by calling a secondary Automation document. With this
action, you can create Automation documents for your most common workflows, and reference those
documents during an Automation execution. This action can simplify your Automation documents by
removing the need to duplicate steps across similar documents.

The secondary Automation runs in the context of the user who initiated the primary Automation. This
means that the secondary Automation uses the same IAM role or user account as the user who started
the first Automation.

267
 AWS Systems Manager User Guide
Working with Automation Documents

Important
If you specify parameters in a secondary Automation that use an assume role (a role that
uses the iam:passRole policy), then the user or role that initiated the primary Automation
must have permission to pass the assume role specified in the secondary Automation. For
more information about setting up an assume role for Automation, see Method 2: Use IAM to
Configure Roles for Automation (p. 146).

Input

JSON

{
"name":"Secondary_Automation_Workflow",
"action":"aws:executeAutomation",
"maxAttempts":3,
"timeoutSeconds":3600,
"onFailure":"Abort",
"inputs":{
"DocumentName":"secondaryWorkflow",
"RuntimeParameters":{
"instanceIds":[
"i-1234567890abcdef0"
]
}
}
}

YAML

name: Secondary_Automation_Workflow
action: aws:executeAutomation
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
DocumentName: secondaryWorkflow
RuntimeParameters:
instanceIds:
- i-1234567890abcdef0

DocumentName

The name of the secondary Automation document to run during the step. The document must
belong to the same AWS account as the primary Automation document.

Type: String

Required: Yes
DocumentVersion

The version of the secondary Automation document to run. If not specified, Automation runs the
default document version.

Type: String

Required: Yes
RuntimeParameters

Required parameters for the secondary document execution. The mapping uses the following
format: {"parameter1" : ["value1"], "parameter2" : ["value2"] }

268
 AWS Systems Manager User Guide
Working with Automation Documents

Type: Map

Required: No

Output

Output

The output generated by the secondary execution. You can reference the output by using the
following format: Secondary_Automation_Step_Name.Output

Type: StringList
ExecutionId

The execution ID of the secondary execution.

Type: String
Status

The status of the secondary execution.

Type: String

aws:executeAwsApi

Calls and runs AWS API actions. Most API actions are supported, although not all API actions have
been tested. For example, the following API actions are supported: CreateImage, Delete bucket,
RebootDBInstance, and CreateGroups, to name a few. Streaming API actions, such as the Get Object
action, aren't supported. For more information and examples of how to use this action, see Invoking
Other AWS Services from a Systems Manager Automation Workflow (p. 228).

Input

Inputs are defined by the API action that you choose.

JSON

{
"action":"aws:executeAwsApi",
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API action or method name",
"API action inputs or parameters":"A value"
},
"outputs":[ These are user-specified outputs
{
"Name":"The name for a user-specified output key",
"Selector":"A response object specified by using JSONPath format",
"Type":"The data type"
}
]
}

YAML

action: aws:executeAwsApi
inputs:
Service: The official namespace of the service

269
 AWS Systems Manager User Guide
Working with Automation Documents

Api: The API action or method name

API action inputs or parameters: A value
outputs: # These are user-specified outputs
- Name: The name for a user-specified output key
Selector: A response object specified by using jsonpath format
Type: The data type

Service

The AWS service namespace that contains the API action that you want to run. For example, the
namespace for Systems Manager is ssm. The namespace for Amazon EC2 is ec2. You can view a list
of supported AWS service namespaces in the Available Services section of the AWS CLI Command
Reference.

Type: String

Required: Yes
Api

The name of the API action that you want to run. You can view the API actions (also called methods)
by choosing a service in the left navigation on the following Services Reference page. Choose a
method in the Client section for the service that you want to invoke. For example, all API actions
(methods) for Amazon RDS are listed on the following page: Amazon RDS methods.

Type: String

Required: Yes
API action inputs

One or more API action inputs. You can view the available inputs (also called parameters) by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to see the available parameters, such as DBInstanceIdentifier, Name, and
Values.

JSON

"inputs":{
"Service":"The official namespace of the service",
"Api":"The API action name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}

YAML

inputs:
Service: The official namespace of the service
Api: The API action name
API input 1: A value
API Input 2: A value
API Input 3: A value

Type: Determined by chosen API action

Required: Yes

270
 AWS Systems Manager User Guide
Working with Automation Documents

Name

A name for the output.

Type: String

Required: Yes
Selector

The JSONPath to a specific attribute in the response object. You can view the response objects by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to the Response Structure section. DBInstances is listed as a response
object.

Type: Integer, Boolean, String, StringList, StringMap, or MapList

Required: Yes
Type

The data type for the response element.

Type: Varies

Required: Yes

aws:executeStateMachine

Run an AWS Step Functions state machine.

Input

This action supports most parameters for the Step Functions StartExecution API action.

JSON

{
"name": "executeTheStateMachine",
"action": "aws:executeStateMachine",
"inputs": {
"stateMachineArn": "StateMachine_ARN",
"input": "{\"parameters\":\"values\"}",
"name": "name"
}
}

YAML

name: executeTheStateMachine
action: aws:executeStateMachine
inputs:
stateMachineArn: StateMachine_ARN
input: '{"parameters":"values"}'
name: name

stateMachineArn

The ARN of the Step Functions state machine.

271
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: Yes
name

The name of the execution.

Type: String

Required: No
input

A string that contains the JSON input data for the execution.

Type: String

Required: No

aws:invokeLambdaFunction

Invokes the specified Lambda function.

Input

This action supports most invoked parameters for the Lambda service. For more information, see Invoke.

JSON

{
"name": "invokeMyLambdaFunction",
"action": "aws:invokeLambdaFunction",
"maxAttempts": 3,
"timeoutSeconds": 120,
"onFailure": "Abort",
"inputs": {
"FunctionName": "MyLambdaFunction"
}
}

YAML

name: invokeMyLambdaFunction
action: aws:invokeLambdaFunction
maxAttempts: 3
timeoutSeconds: 120
onFailure: Abort
inputs:
FunctionName: MyLambdaFunction

FunctionName

The name of the Lambda function. This function must exist.

Type: String

Required: Yes
Qualifier

The function version or alias name.

272
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: No
InvocationType

The invocation type. The default is RequestResponse.

Type: String

Valid values: Event | RequestResponse | DryRun

Required: No
LogType

If Tail, the invocation type must be RequestResponse. AWS Lambda returns the last 4 KB of log
data produced by your Lambda function, base64-encoded.

Type: String

Valid values: None | Tail

Required: No
ClientContext

The client-specific information.

Required: No
Payload

The JSON input for your Lambda function.

Required: No

Output

StatusCode

The function execution status code.

FunctionError

Indicates whether an error occurred while running the Lambda function. If an error occurred,
this field will show either Handled or Unhandled. Handled errors are reported by the function.
Unhandled errors are detected and reported by AWS Lambda.
LogResult

The base64-encoded logs for the Lambda function invocation. Logs are present only if the
invocation type is RequestResponse, and the logs were requested.
Payload

The JSON representation of the object returned by the Lambda function. Payload is present only if
the invocation type is RequestResponse.

aws:pause

This action pauses the Automation execution. Once paused, the execution status is Waiting. To continue
the Automation execution, use the SendAutomationSignal API action with the Resume signal type.

273
 AWS Systems Manager User Guide
Working with Automation Documents

Input

The input is as follows.

JSON

{
"name": "pauseThis",
"action": "aws:pause",
"inputs": {}
}

YAML

name: pauseThis
action: aws:pause
inputs: {}

Output

None

aws:runCommand

Runs the specified commands.

Note
Automation only supports output of one Run Command action. A document can include
multiple Run Command actions and plugins, but output is supported for only one action and
plugin at a time.

Input

This action supports most send command parameters. For more information, see SendCommand.

JSON

{
"name": "installPowerShellModule",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-InstallPowerShellModule",
"InstanceIds": ["i-1234567890abcdef0"],
"Parameters": {
"source": "https://my-s3-url.com/MyModule.zip ",
"sourceHash": "ASDFWER12321WRW"
}
}
}

YAML

name: installPowerShellModule
action: aws:runCommand
inputs:
DocumentName: AWS-InstallPowerShellModule
InstanceIds:
- i-1234567890abcdef0
Parameters:

274
 AWS Systems Manager User Guide
Working with Automation Documents

source: 'https://my-s3-url.com/MyModule.zip '

sourceHash: ASDFWER12321WRW

DocumentName

The name of the Run Command document.

Type: String

Required: Yes
InstanceIds

The instance IDs where you want the command to run. You can specify a maximum of 50 IDs. If you
don't want to specify individual instance IDs, then you can send commands to a fleet of instances by
using the Targets parameter. The Targets parameter accepts Amazon EC2 tags. For more information
about how to use the Targets parameter, see Using Targets and Rate Controls to Send Commands to
a Fleet (p. 622).

Type: StringList

Required: No (If you don't specify InstanceIds, then you must specify the Targets parameter.)
Targets

An array of search criteria that targets instances by using a Key,Value combination that you specify.
Targets is required if you don't provide one or more instance IDs in the call. For more information
about how to use the Targets parameter, see Using Targets and Rate Controls to Send Commands to
a Fleet (p. 622).

Type: MapList (The schema of the map in the list must match the object. For information, see Target
in the AWS Systems Manager API Reference.

Required: No (If you don't specify Targets, then you must specify InstanceIds.)

Here is an example:

{
"name": "installPowerShellModule",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-InstallPowerShellModule",
"Targets": [
{
"Key": "tag:Stage",
"Values": [
"Gamma", "Beta"
]
},
{
"Key": "tag-key",
"Values": [
"Suite"
]
}
]
"Parameters": {
"source": "https://my-s3-url.com/MyModule.zip ",
"sourceHash": "ASDFWER12321WRW"
}
}
}

275
 AWS Systems Manager User Guide
Working with Automation Documents

Parameters

The required and optional parameters specified in the document.

Type: Map

Required: No
CloudWatchOutputConfig

Configuration options for sending command output to Amazon CloudWatch Logs. For more
information about sending command output to CloudWatch Logs, see Configuring Amazon
CloudWatch Logs for Run Command (p. 614).

Type: StringMap (The schema of the map must match the object. For more information, see
CloudWatchOutputConfig in the AWS Systems Manager API Reference).

Required: No

Here is an example:

{
"name": "installPowerShellModule",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-InstallPowerShellModule",
"InstanceIds": ["i-1234567890abcdef0"],
"Parameters": {
"source": "https://my-s3-url.com/MyModule.zip ",
"sourceHash": "ASDFWER12321WRW"
},
"CloudWatchOutputConfig" : {
"CloudWatchLogGroupName": "CloudWatchGroupForSSMAutomationService",
"CloudWatchOutputEnabled": true
}
}
}

Comment

User-defined information about the command.

Type: String

Required: No
DocumentHash

The hash for the document.

Type: String

Required: No
DocumentHashType

The type of the hash.

Type: String

Valid values: Sha256 | Sha1

Required: No

276
 AWS Systems Manager User Guide
Working with Automation Documents

NotificationConfig

The configurations for sending notifications.

Required: No
OutputS3BucketName

The name of the S3 bucket for command execution responses.

Type: String

Required: No
OutputS3KeyPrefix

The prefix.

Type: String

Required: No
ServiceRoleArn

The ARN of the IAM role.

Type: String

Required: No
TimeoutSeconds

The run-command timeout value, in seconds.

Type: Integer

Required: No

Output

CommandId

The ID of the command.

Status

The status of the command.

ResponseCode

The response code of the command.

Output

The output of the command.

aws:runInstances

Launches a new instance.

Input

The action supports most API parameters. For more information, see the RunInstances API
documentation.

277
 AWS Systems Manager User Guide
Working with Automation Documents

JSON

{
"name":"launchInstance",
"action":"aws:runInstances",
"maxAttempts":3,
"timeoutSeconds":1200,
"onFailure":"Abort",
"inputs":{
"ImageId":"ami-12345678",
"InstanceType":"t2.micro",
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"myRunCmdRole",
"TagSpecifications":[
{
"ResourceType":"instance",
"Tags":[
{
"Key":"LaunchedBy",
"Value":"SSMAutomation"
},
{
"Key":"Category",
"Value":"HighAvailabilityFleetHost"
}
]
}
]
}
}

YAML

name: launchInstance
action: aws:runInstances
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: ami-12345678
InstanceType: t2.micro
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: myRunCmdRole
TagSpecifications:
- ResourceType: instance
Tags:
- Key: LaunchedBy
Value: SSMAutomation
- Key: Category
Value: HighAvailabilityFleetHost

ImageId

The ID of the Amazon Machine Image (AMI).

Type: String

Required: Yes
InstanceType

The instance type.

278
 AWS Systems Manager User Guide
Working with Automation Documents

Note
If an instance type value is not provided, the m1.small instance type is used.

Type: String

Required: No
MinInstanceCount

The minimum number of instances to be launched.

Type: String

Required: No
MaxInstanceCount

The maximum number of instances to be launched.

Type: String

Required: No
AdditionalInfo

Reserved.

Type: String

Required: No
BlockDeviceMappings

The block devices for the instance.

Type: MapList

Required: No
ClientToken

The identifier to ensure idempotency of the request.

Type: String

Required: No
DisableApiTermination

Enables or disables instance API termination

Type: Boolean

Required: No
EbsOptimized

Enables or disabled EBS optimization.

Type: Boolean

Required: No
IamInstanceProfileArn

The ARN of the IAM instance profile for the instance.

279
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: No
IamInstanceProfileName

The name of the IAM instance profile for the instance.

Type: String

Required: No
InstanceInitiatedShutdownBehavior

Indicates whether the instance stops or terminates on system shutdown.

Type: String

Required: No
KernelId

The ID of the kernel.

Type: String

Required: No
KeyName

The name of the key pair.

Type: String

Required: No
MaxInstanceCount

The maximum number of instances to filter when searching for offerings.

Type: Integer

Required: No
MinInstanceCount

The minimum number of instances to filter when searching for offerings.

Type: Integer

Required: No
Monitoring

Enables or disables detailed monitoring.

Type: Boolean

Required: No
NetworkInterfaces

The network interfaces.

Type: MapList

Required: No

280
 AWS Systems Manager User Guide
Working with Automation Documents

Placement

The placement for the instance.

Type: StringMap

Required: No
PrivateIpAddress

The primary IPv4 address.

Type: String

Required: No
RamdiskId

The ID of the RAM disk.

Type: String

Required: No
SecurityGroupIds

The IDs of the security groups for the instance.

Type: StringList

Required: No
SecurityGroups

The names of the security groups for the instance.

Type: StringList

Required: No
SubnetId

The subnet ID.

Type: String

Required: No
TagSpecifications

The tags to apply to the resources during launch. You can only tag instances and volumes at launch.
The specified tags are applied to all instances or volumes that are created during launch. To tag an
instance after it has been launched, use the aws:createTags (p. 264) action.

Type: MapList (For more information, see TagSpecification.)

Required: No
UserData

An execution script provided as a string literal value. If a literal value is entered, then it must be
Base64-encoded.

Type: String

Required: No

281
 AWS Systems Manager User Guide
Working with Automation Documents

Output

InstanceIds

The IDs of the instances.

aws:sleep
Delays Automation execution for a specified amount of time. This action uses the International
Organization for Standardization (ISO) 8601 date and time format. For more information about this date
and time format, see ISO 8601.

Input

You can delay execution for a specified duration.

JSON

{
"name":"sleep",
"action":"aws:sleep",
"inputs":{
"Duration":"PT10M"
}
}

YAML

name: sleep
action: aws:sleep
inputs:
Duration: PT10M

You can also delay execution until a specified date and time. If the specified date and time has passed,
the action proceeds immediately.

JSON

{
"name": "sleep",
"action": "aws:sleep",
"inputs": {
"Timestamp": "2020-01-01T01:00:00Z"
}
}

YAML

name: sleep
action: aws:sleep
inputs:
Timestamp: '2020-01-01T01:00:00Z'

Note
Automation currently supports a maximum delay of 604800 seconds (7 days).

Duration

An ISO 8601 duration. You can't specify a negative duration.

282
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Required: No
Timestamp

An ISO 8601 timestamp. If you don't specify a value for this parameter, then you must specify a
value for the Duration parameter.

Type: String

Required: No

Output

None

aws:waitForAwsResourceProperty

The aws:waitForAwsResourceProperty action enables your Automation workflow to wait for a specific
resource state or event state before continuing the workflow. For more information and examples
of how to use this action, see Invoking Other AWS Services from a Systems Manager Automation
Workflow (p. 228).

Input

Inputs are defined by the API action that you choose.

JSON

{
"action": "aws:waitForAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API action or method name",
"API action inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property value"
]
}
}

YAML

action: aws:waitForAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API action or method name
API action inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property value

Service

The AWS service namespace that contains the API action that you want to run. For example, the
namespace for Systems Manager is ssm. The namespace for Amazon EC2 is ec2. You can view a list

283
 AWS Systems Manager User Guide
Working with Automation Documents

of supported AWS service namespaces in the Available Services section of the AWS CLI Command
Reference.

Type: String

Required: Yes
Api

The name of the API action that you want to run. You can view the API actions (also called methods)
by choosing a service in the left navigation on the following Services Reference page. Choose a
method in the Client section for the service that you want to invoke. For example, all API actions
(methods) for Amazon RDS are listed on the following page: Amazon RDS methods.

Type: String

Required: Yes
API action inputs

One or more API action inputs. You can view the available inputs (also called parameters) by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to see the available parameters, such as DBInstanceIdentifier, Name, and
Values.

JSON

"inputs":{
"Service":"The official namespace of the service",
"Api":"The API action name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}

YAML

inputs:
Service: The official namespace of the service
Api: The API action name
API input 1: A value
API Input 2: A value
API Input 3: A value

Type: Determined by chosen API action

Required: Yes
PropertySelector

The JSONPath to a specific attribute in the response object. You can view the response objects by
choosing a service in the left navigation on the following Services Reference page. Choose a method
in the Client section for the service that you want to invoke. For example, all methods for Amazon
RDS are listed on the following page: Amazon RDS methods. Choose the describe_db_instances
method and scroll down to the Response Structure section. DBInstances is listed as a response
object.

Type: Integer, Boolean, String, StringList, StringMap, or MapList

Required: Yes

284
 AWS Systems Manager User Guide
Working with Automation Documents

DesiredValues

The expected status or state on which to continue the Automation workflow.

Type: Varies

Required: Yes

Automation System Variables

Systems Manager Automation documents use the following variables. For an example of how these
variables are used, view the JSON source of the AWS-UpdateWindowsAmi document.

To view the JSON source of the AWS-UpdateWindowsAmi document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.
3. In the document list, use either the Search bar or the numbers to the right of the Search bar to
choose the document AWS-UpdateWindowsAmi.
4. Choose the Content tab.

System Variables

Automation documents currently support the following system variables.

Variable Details

global:ACCOUNT_ID The AWS account ID of the AWS Identity and

Access Management (IAM) user or role in which
Automation runs.

global:DATE The date (at execution time) in the format yyyy-

MM-dd.

global:DATE_TIME The date and time (at execution time) in the

format yyyy-MM-dd_HH.mm.ss.

global:REGION The Region that the document is run in. For

example, us-east-2.

Automation Variables

Automation documents currently support the following automation variables.

Variable Details

automation:EXECUTION_ID The unique identifier assigned to the

current automation execution. For example,
1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c.

Topics
• Terminology (p. 286)
• Supported Scenarios (p. 289)
• Unsupported Scenarios (p. 291)

285
 AWS Systems Manager User Guide
Working with Automation Documents

Terminology

The following terms describe how variables and parameters are resolved.

Term Definition Example

Constant ARN A valid ARN without variables arn:aws:iam::123456789012:role/

roleName

Document parameter A parameter defined at

{
the document level for an "description": "Create
Automation document (for Image Demo",
example, instanceId). The "version": "0.3",
parameter is used in a basic "assumeRole":
string replace. Its value is "Your_Automation_Assume_Role_ARN",
supplied at Start Execution time. "parameters":{
"instanceId": {
"type": "STRING",
"description":
"Instance to create image
from"
}
}

System variable A general variable substituted

"activities": [
into the document when {
any part of the document is "id": "copyImage",
evaluated. "activityType": "AWS-
CopyImage",
"maxAttempts": 1,
"onFailure":
"Continue",
"inputs": {
"ImageName":
"{{imageName}}",
"SourceImageId":
"{{sourceImageId}}",
"SourceRegion":
"{{sourceRegion}}",
"Encrypted": true,
"ImageDescription":
"Test CopyImage Description
created on {{global:DATE}}"
}
}
]

Automation variable A variable relating to the

{
automation execution "name": "runFixedCmds",
substituted into the document "action":
when any part of the document "aws:runCommand",
is evaluated. "maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"DocumentName": "AWS-
RunPowerShellScript",
"InstanceIds": [

"{{LaunchInstance.InstanceIds}}"
],
"Parameters": {

286
 AWS Systems Manager User Guide
Working with Automation Documents

Term Definition Example

"commands": [
"dir",
"date",
"echo {Hello
{{ssm:administratorName}}}",

"“{{outputFormat}}” -f
“left”,”right”,”{{global:DATE}}”,”{{auto
]
}
}
}

287
 AWS Systems Manager User Guide
Working with Automation Documents

Term Definition Example

SSM parameter A variable defined within

{
Parameter Store. It is not "description": "Run
declared as a document Command Demo",
parameter. It may require "schemaVersion": "0.3",
permissions to access. "assumeRole":
"arn:aws:iam::123456789012:role/
roleName",
"parameters": {
"commands": {
"type":
"STRING_LIST",
"description":
"list of commands to run as
part of first step"
},
"instanceIds": {
"type":
"STRING_LIST",
"description":
"list of instances to run
commands on"
}
},
"mainSteps": [
{
"name":
"runFixedCmds",
"action":
"aws:runCommand",
"maxAttempts": 1,
"onFailure":
"Continue",
"inputs": {
"DocumentName":
"AWS-RunPowerShellScript",
"InstanceIds":
[

"{{LaunchInstance.InstanceIds}}"
],
"Parameters": {
"commands":
[
"dir",
"date",
"echo
{Hello {{ssm:administratorName}}}",

""{{outputFormat}}" -f
"left","right","{{global:DATE}}","{{auto
]
}
}
}

288
 AWS Systems Manager User Guide
Working with Automation Documents

Supported Scenarios

Scenario Comments Example

Constant ARN assumeRole at An authorization check is

{
create performed to verify that the "description": "Test
calling user is permitted to pass all Automation resolvable
the given assumeRole. parameters",
"schemaVersion": "0.3",

"assumeRole": "arn:aws:iam::123456789012
roleName",
"parameters": {
...

Document parameter supplied Must be defined in the

{
for assumeRole at create parameter list of the document. "description": "Test
all Automation resolvable
parameters",
"schemaVersion": "0.3",

"assumeRole": "{{dynamicARN}}",
"parameters": {
...

Value supplied for document Customer supplies the value

...
parameter at start. to use for a parameter. Any "parameters": {
execution inputs supplied at "amiId": {
start time need to be defined "type": "STRING",
in the parameter list of the "default":
document. "ami-7f2e6015",
"description": "list
of commands to run as part
of first step"
},
...

Inputs to Start Automation

Execution include : {"amiId" :
["ami-12345678"] }

SSM parameter referenced The variable exists within

...
within step definition the customer's account and "mainSteps": [
the assumeRole for the {
document has access to the "name":
variable. A check is performed "RunSomeCommands",
at create time to confirm the "action":
assumeRole has access. SSM "aws:runCommand",
"maxAttempts": 1,
parameters do not need to be
"onFailure":
set in the parameter list of the "Continue",
document. "inputs": {
"DocumentName":
"AWS:RunPowerShell",
"InstanceIds":
["{{LaunchInstance.InstanceIds}}"],
"Parameters": {

"commands" : [

289
 AWS Systems Manager User Guide
Working with Automation Documents

Scenario Comments Example

"echo {Hello
{{ssm:administratorName}}}"

}
}
},

...

System variable referenced A system variable is substituted

...
within step definition into the document at execution "mainSteps": [
time. The value injected into the {
document is relative to when the "name":
substitution occurs. That is, the "RunSomeCommands",
value of a time variable injected "action":
at step 1 is different from the "aws:runCommand",
"maxAttempts": 1,
value injected at step 3 because
"onFailure":
of the time it takes to run the "Continue",
steps between. System variables "inputs": {
do not need to be set in the "DocumentName":
parameter list of the document. "AWS:RunPowerShell",
"InstanceIds":
["{{LaunchInstance.InstanceIds}}"],
"Parameters": {

"commands" : [

"echo {The time is now

{{global:TIME}}}"

}
}
}, ...

Automation variable referenced Automation variables do not

...
within step definition. need to be set in the parameter "mainSteps": [
list of the document. The only {
supported Automation variable "name":
is automation:EXECUTION_ID. "invokeLambdaFunction",
"action":
"aws:invokeLambdaFunction",
"maxAttempts": 1,
"onFailure":
"Continue",
"inputs": {
"FunctionName":
"Hello-World-
LambdaFunction",

"Payload" :
"{ "executionId" :
"{{automation:EXECUTION_ID}}" }"
}
}
...

290
 AWS Systems Manager User Guide
Working with Automation Documents

Scenario Comments Example

Refer to output from previous This is parameter redirection.

...
step within next step definition. The output of a previous step "mainSteps": [
is referenced using the syntax {
{{stepName.OutputName}}. "name":
This syntax cannot be used by "LaunchInstance",
the customer for document "action":
parameters. This is resolved at "aws:runInstances",
"maxAttempts": 1,
the time of execution for the
"onFailure":
referring step. The parameter is "Continue",
not listed in the parameters of "inputs": {
the document. "ImageId":
"{{amiId}}",
"MinInstanceCount":
1,
"MaxInstanceCount":
2
}
},
{
"name":"changeState",
"action":
"aws:changeInstanceState",
"maxAttempts": 1,
"onFailure":
"Continue",
"inputs": {
"InstanceIds":
["{{LaunchInstance.InstanceIds}}"],
"DesiredState":
"terminated"
}
}

...

Unsupported Scenarios

Scenario Comment Example

SSM Parameter supplied for Not supported.

...
assumeRole at create
{
"description": "Test
all Automation resolvable
parameters",
"schemaVersion": "0.3",
"assumeRole":
"{{ssm:administratorRoleARN}}",
"parameters": {

...

Variable step definition The definition of a step in the

...
document is constructed by
variables. "mainSteps": [
{

291
 AWS Systems Manager User Guide
Working with Automation Documents

Scenario Comment Example

"name":
"LaunchInstance",
"action":
"aws:runInstances",
"{{attemptModel}}": 1,
"onFailure":
"Continue",
"inputs": {
"ImageId":
"ami-12345678",
"MinInstanceCount":
1,
"MaxInstanceCount":
2
}

...

User supplies input :

{ "attemptModel" :
"minAttempts" }

Cross referencing document The user supplies an input

...
parameters parameter at start time, which "parameters": {
is a reference to another "amiId": {
parameter in the document. "type": "STRING",
"default":
"ami-7f2e6015",
"description": "list
of commands to run as part
of first step"
},
"otherAmiId": {
"type": "STRING",
"description": "The
other amiId to try if this
one fails".

"default" : "{{amiId}}"
},

...

292
 AWS Systems Manager User Guide
Working with Automation Documents

Scenario Comment Example

Multi-level expansion The document defines a variable

...
that evaluates to the name of "parameters": {
a variable. This sits within the "param1": {
variable delimiters (that is {{ }}) "type": "STRING",
and is expanded to the value of "default": "param2",
that variable/parameter. "description": "The
parameter to reference"
},
"param2": {
"type": "STRING",
"default" : "echo
{Hello world}",
"description": "What
to run"
}
},
"mainSteps": [{
"name":
"runFixedCmds",
"action":
"aws:runCommand",
"maxAttempts": 1,
"onFailure":
"Continue",
"inputs": {
"DocumentName":
"AWS-RunPowerShellScript",

"InstanceIds" :
"{{LaunchInstance.InstanceIds}}",
"Parameters": {
"commands":
[ "{{ {{param1}} }}"]

...

Note: The customer intention

here would be to run a
runCommand of "echo {Hello
world}"

293
 AWS Systems Manager User Guide
Working with Automation Documents

Scenario Comment Example

Referencing output from a The user references the output

...
document step that is a different from a preceding document step mainSteps:
variable type within a subsequent step. The - name: getImageId
output is a variable type that action: aws:executeAwsApi
does not meet the requirements inputs:
of the action in the subsequent Service: ec2
step. Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageIdList
Selector: "$.Images"
Type: "StringList"
- name: copyMyImages
action: aws:copyImage
maxAttempts: 3
onFailure: Abort
inputs:
SourceImageId:
{{ getImageId.ImageIdList }}
SourceRegion: ap-
northeast-2
ImageName: Encrypted
Copies of LAMP base AMI in
ap-northeast-2
Encrypted: true
...
Note: You must provide
the type required by the
Automation action.
In this case, aws:copyImage
requires a "String" type
variable but the preceding
step outputs a "StringList"
type variable.

Systems Manager Automation Document Details Reference

This section includes topics that describe each of the Systems Manager Automation documents that
are owned by AWS and AWS Support. Each page provides an explanation of the required and optional
parameters you can specify when using the document. Each page also lists the steps in the document
and the output of the execution, if any.

You can view the JSON for these documents in the Systems Manager console.

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose a document, and then choose View details.
4. Choose the Content tab.

294
 AWS Systems Manager User Guide
Working with Automation Documents

Note
This section does not include a separate page for documents that require approval such as
the AWS-CreateManagedLinuxInstanceWithApproval or AWS-StopEC2InstanceWithApproval
document. Any document name that includes WithApproval, means the document includes the
aws:approve (p. 246) action. This action temporarily pauses an Automation execution until
designated principals either approve or reject the action. After the required number of approvals
is reached, the Automation execution resumes.

Topics
• AWSSupport-ActivateWindowsWithAmazonLicense (p. 296)
• AWS-ASGEnterStandby (p. 298)
• AWS-ASGExitStandby (p. 299)
• AWS-AttachEBSVolume (p. 300)
• AWS-AttachIAMToInstance (p. 301)
• AWS-ConfigureCloudWatchOnEC2Instance (p. 303)
• AWS-ConfigureS3BucketLogging (p. 304)
• AWS-ConfigureS3BucketVersioning (p. 306)
• AWS-CopySnapshot (p. 307)
• AWSEC2-CloneInstanceAndUpgradeWindows (p. 308)
• AWSEC2-CloneInstanceAndUpgradeSQLServer (p. 310)
• AWS-CreateDynamoDBBackup (p. 312)
• AWS-CreateImage (p. 313)
• AWS-CreateJiraIssue (p. 314)
• AWS-CreateManagedLinuxInstance (p. 316)
• AWS-CreateManagedWindowsInstance (p. 318)
• AWS-CreateSnapshot (p. 320)
• AWS-DeleteCloudFormationStack (p. 321)
• AWS-DeleteDynamoDBBackup (p. 322)
• AWS-DeleteDynamoDBTableBackups (p. 323)
• AWS-DeleteEBSVolumeSnapshots (p. 324)
• AWS-DeleteImage (p. 325)
• AWS-DeleteSnapshot (p. 326)
• AWS-DetachEBSVolume (p. 327)
• AWS-DisablePublicAccessForSecurityGroup (p. 328)
• AWS-Disables3BucketPublicReadWrite (p. 329)
• AWS-EnableCloudTrail (p. 330)
• AWS-Enables3BucketEncryption (p. 331)
• AWSSupport-ExecuteEC2Rescue (p. 332)
• AWSSupport-GrantPermissionsToIAMUser (p. 334)
• AWSSupport-ManageRDPSettings (p. 338)
• AWSSupport-ManageWindowsService (p. 340)
• AWS-PatchASGInstance (p. 342)
• AWS-PatchInstanceWithRollback (p. 343)
• AWS-PublishSNSNotification (p. 345)
• AWS-RebootRDSInstance (p. 346)
• AWSSupport-ResetAccess (p. 347)

295
 AWS Systems Manager User Guide
Working with Automation Documents

• AWS-ReleaseElasticIP (p. 349)

• AWS-ResizeInstance (p. 350)
• AWS-RestartEC2Instance (p. 351)
• AWSSupport-SendLogBundleToS3Bucket (p. 352)
• AWS-SetupInventory (p. 354)
• AWSSupport-SetupIPMonitoringFromVPC (p. 357)
• AWS-SetupManagedInstance (p. 364)
• AWS-SetupManagedRoleOnEC2Instance (p. 365)
• AWSEC2-SQLServerDBRestore (p. 367)
• AWS-StartEC2Instance (p. 370)
• AWSSupport-StartEC2RescueWorkflow (p. 371)
• AWS-StartRDSInstance (p. 378)
• AWS-StopEC2Instance (p. 379)
• AWS-StopRDSInstance (p. 380)
• AWS-TerminateEC2Instance (p. 381)
• AWSSupport-TerminateIPMonitoringFromVPC (p. 382)
• AWSSupport-TroubleshootRDP (p. 384)
• AWSSupport-TroubleshootSSH (p. 388)
• AWS-UpdateCloudFormationStack (p. 391)
• AWS-UpdateLinuxAmi (p. 392)
• AWS-UpdateWindowsAmi (p. 394)
• AWSSupport-UpgradeWindowsAWSDrivers (p. 397)

AWSSupport-ActivateWindowsWithAmazonLicense

Description

The AWSSupport-ActivateWindowsWithAmazonLicense automation document activates an Amazon

EC2 Windows Server instance with a license provided by Amazon by contacting SSM Agent installed on
your managed instance. Optionally, you can remediate Windows activation offline, which requires a stop
and start of your EC2 instance. If Windows is not activated, the document verifies, and when needed
repairs, the Windows route table (route to Amazon KMS servers), the KMS settings (server and port), and
attempts to activate Windows. Note: this document cannot be used on Bring Your Own License (BYOL)
Windows instances. For information about using your own license, see Microsoft Licensing on AWS.

Document Type

Automation

Owner

Amazon

Platforms

Windows

Parameters

• InstanceId

Type: String

296
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) ID of your EC2 Windows managed instance.

• ForceActivation

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Set it to True if you want to proceed even if Windows is already activated.
• AllowOffline

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Set it to true if you allow an offline Windows activation remediation in case
the online troubleshooting fails, or the provided instance is not a managed instance. Note: The offline
method requires the provided EC2 instance be stopped and then started. Data stored in instance store
volumes will be lost. The public IP address will change if you are not using an Elastic IP.
• SubnetId

Type: String

Default: CreateNewVPC

Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the
offline troubleshooting. Use SelectedInstanceSubnet to use the same subnet as your instance, or
CreateNewVPC to create a new VPC. IMPORTANT: The subnet must be in the same Availability Zone as
InstanceId, and it must allow access to the SSM endpoints.
• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWSSupport-

ActivateWindowsWithAmazonLicense --parameters "InstanceId=INSTANCEID"

Send the command with ForceActivation = True

aws ssm start-automation-execution --document-name AWSSupport-

ActivateWindowsWithAmazonLicense --parameters "InstanceId=INSTANCEID,ForceActivation=True"

Send the command with AllowOffline = True

aws ssm start-automation-execution --document-name AWSSupport-

ActivateWindowsWithAmazonLicense --parameters "InstanceId=INSTANCEID,AllowOffline=True"

297
 AWS Systems Manager User Guide
Working with Automation Documents

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. You must have at least
ssm:ExecuteAutomation and ssm:SendCommand to run the automation and send the command to the
instance, plus ssm:GetAutomationExecution to be able to read the automation output. For the offline
remediation, see the permissions needed by AWSSupport-StartEC2RescueWorkflow.

Document Steps

1. aws:assertAwsResourceProperty - Check the provided instance's platform is Windows.

2. aws:assertAwsResourceProperty - Confirm the provided instance is a managed instance
a. (Online activation fix) If the input instance is a managed instance, then run aws:runCommand to run
the PowerShell script to attempt to fix Windows activation.
b. (Offline activation fix) If the input instance is not a managed instance:
i. aws:assertAwsResourceProperty - Verifies the AllowOffline flag is set to True. If so, the offline fix
starts, otherwise the workflow ends.
ii. aws:executeAutomation - Invoke AWSSupport-StartEC2RescueWorkflow with the Windows
activation offline fix script. The script leverages EC2Config or EC2Launch depending on the OS
version.
iii. aws:executeAwsApi - Read the result from AWSSupport-StartEC2RescueWorkflow.

Outputs

activateWindows.Output

getActivateWindowsOfflineResult.Output

AWS-ASGEnterStandby

Description

Change the standby state of an Amazon EC2 instance in an Auto Scaling group.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

298
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) ID of an Amazon EC2 instance for which you want to change the standby state
within an Auto Scaling group.
• LambdaRoleArn

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ASGEnterStandby --parameters

"parameters"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

None

AWS-ASGExitStandby

Description

Change the standby state of an Amazon EC2 instance in an Auto Scaling group.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

299
 AWS Systems Manager User Guide
Working with Automation Documents

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) ID of an Amazon EC2 instance for which you want to change the standby state
within an Auto Scaling group.
• LambdaRoleArn

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ASGExitStandby --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

None

AWS-AttachEBSVolume

Description

Attach an Amazon Elastic Block Store (Amazon EBS) volume to an Amazon EC2 instance.

Document Type

Automation

Owner

Amazon

300
 AWS Systems Manager User Guide
Working with Automation Documents

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• Device

Type: String

Description: (Required) The device name (for example, /dev/sdh or xvdh ).

• InstanceId

Type: String

Description: (Required) The ID of the instance where you want to attach the volume.
• VolumeId

Type: String

Description: (Required) The ID of the Amazon EBS volume. The volume and instance must be in the
same Availability Zone.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-AttachEBSVolume --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:deleteStack

Outputs

None

AWS-AttachIAMToInstance

Description

Attach an AWS Identity and Access Management (IAM) role to a managed instance.

Document Type

301
 AWS Systems Manager User Guide
Working with Automation Documents

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) The ID of the instance on which you want to assign an IAM role.
• RoleName

Type: String

Description: (Required) The IAM role name to add to the managed instance.
• ForceReplace

Type: Boolean

Description: (Optional) Flag to specify whether to replace the existing IAM profile or not.

Default: true

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-AttachIAMToInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

1. aws:executeAwsApi - DescribeInstanceProfile - Find the IAM instance profile attached to the Amazon
EC2 instance.
2. aws:branch - CheckInstanceProfileAssociations - Check the IAM instance profile attached to the
Amazon EC2 instance.
a. If an IAM instance profile is attached and ForceReplace is set to true:
i. aws:executeAwsApi - DisassociateIamInstanceProfile - Disassociate the IAM instance profile from
the Amazon EC2 instance.

302
 AWS Systems Manager User Guide
Working with Automation Documents

b. aws:executeAwsApi - ListInstanceProfilesForRole - List instance profiles for the IAM role provided.
c. aws:branch - CheckInstanceProfileCreated - Check if the IAM role provided has an associated
instance profile.
i. If the IAM role has an associated instance profile:
A. aws:executeAwsApi - AttachIAMProfileToInstance - Attach the IAM instance profile role to the
Amazon EC2 instance.
i. If the IAM role does not have an associated instance profile:
A. aws:executeAwsApi - CreateInstanceProfileForRole - Create an instance profile role for the
specified IAM role.
B. aws:executeAwsApi - AddRoleToInstanceProfile - Attach the instance profile role to the
specified IAM role.
C. aws:executeAwsApi - GetInstanceProfile - Get the instance profile data for the specified IAM
role.
D. aws:executeAwsApi - AttachIAMProfileToInstanceWithRetry - Attach the IAM instance profile
role to the Amazon EC2 instance.

Outputs

AttachIAMProfileToInstanceWithRetry.AssociationId

GetInstanceProfile.InstanceProfileName

GetInstanceProfile.InstanceProfileArn

AttachIAMProfileToInstance.AssociationId

ListInstanceProfilesForRole.InstanceProfileName

ListInstanceProfilesForRole.InstanceProfileArn

AWS-ConfigureCloudWatchOnEC2Instance

Description

Configure Amazon CloudWatch on a managed instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

303
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Required) The ID of the managed that you want to configure to use CloudWatch.
• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role assumed by Lambda.

• properties

Type: String

Description: (Optional) The configuration for CloudWatch in JSON format.

• status

Allowed values: Enabled,Disabled

Default: Enabled

Description: (Optional) Specifies whether to enable or disable CloudWatch. Valid values: "Enabled" |
"Disabled".

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ConfigureCloudWatchOnEC2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

None

AWS-ConfigureS3BucketLogging

Description

Enable logging on an Amazon Simple Storage Service (Amazon S3) bucket.

Document Type

Automation

Owner

304
 AWS Systems Manager User Guide
Working with Automation Documents

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• BucketName

Type: String

Description: (Required) The name of the Amazon S3 Bucket for which you want to configure logging.
• GrantedPermission

Type: String

Allowed values: FULL_CONTROL,READ,WRITE

Description: (Required) Logging permissions assigned to the grantee for the bucket.
• GranteeEmailAddress

Type: String

(Optional) Email address of the grantee.

• GranteeId

Type: String

Description: (Optional) The canonical user ID of the grantee.

• GranteeType

Type: String

Allowed values: CanonicalUser,AmazonCustomerByEmail,Group

Description: (Required) Type of grantee.

• GranteeUri

Type: String

Description: (Optional) URI of the grantee group.

• TargetBucket

Type: String

Description: (Required) Specifies the bucket where you want Amazon S3 to store server access logs.
You can have your logs delivered to any bucket that you own. You can also configure multiple buckets
to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix
for each source bucket so that the delivered log files can be distinguished by key.
• TargetPrefix

Type: String

305
 AWS Systems Manager User Guide
Working with Automation Documents

Default: /

Description: (Optional) Specifies a prefix for the keys under which the log files will be stored.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ConfigureS3BucketLogging --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

aws:executeAwsApi

aws:executeAwsApi

aws:sleep

Outputs

None

AWS-ConfigureS3BucketVersioning

Description

Configure versioning for an Amazon Simple Storage Service (Amazon S3) bucket.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• BucketName

306
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Required) The name of the S3 Bucket whose encryption configuration will be managed.
• VersioningState

Type: String

Allowed values: Enabled,Suspended

Default: Enabled

Description: (Optional) Applied to the VersioningConfiguration.Status. When set to 'Enabled', this

process enables versioning for the objects in the bucket, all objects added to the bucket receive a
unique version ID. When set to 'Suspended', this process disables versioning for the objects in the
bucket. All objects added to the bucket receive the version ID null.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ConfigureS3BucketVersioning --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

Outputs

None

AWS-CopySnapshot

Description

Copy a snapshot of an Amazon Elastic Block Store (Amazon EBS) volume.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

307
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• Description

Type: String

Description: (Optional) A description for the Amazon EBS snapshot.

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role assumed by Lambda.

• SnapshotId

Type: String

Description: (Required) The ID of the Amazon EBS snapshot to copy.

• SourceRegion

Type: String

Description: (Required) The region where the source snapshot currently exists.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CopySnapshot --parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

copySnapshot.Payload

AWSEC2-CloneInstanceAndUpgradeWindows

Description

Create an Amazon Machine Image (AMI) from a Windows Server 2008 R2 instance, and then upgrade the
AMI to Windows Server 2012 R2. The upgrade operation is a multi-step process that can take 2 hours
to complete. The automation creates an AMI from the instance and then launches the newly created
AMI in the VPC/Subnet you provide. The Automation workflow performs an in-place upgrade from

308
 AWS Systems Manager User Guide
Working with Automation Documents

Windows Server 2008 R2 to Windows server 2012 R2. The workflow also updates or installs the AWS
drivers required by the upgraded instance. After the upgrade, the workflow creates a new AMI and then
terminates the upgraded instance.

You can test application functionality by launching the new AMI in your VPC. After you finish testing, and
before you perform another upgrade, schedule application downtime before completely switching over
to the upgraded instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows

Prerequisites

• Verify that SSM Agent is installed on your instance. For more information, see Installing and
Configuring SSM Agent on Windows Instances (p. 65).
• The subnet ID specified must be a public subnet with the auto-assign public IPv4 address set to true.
For more information, see Modifying the Public IPv4 Addressing Attribute for Your Subnet in the
Amazon VPC User Guide.
• This Automation works only with Windows Server 2008 R2 instances.
• This Automation works only on instances with an unencrypted EBS root volume. If the specified
instance has an encrypted root volume, the Automation workflow fails.
• Configure the Windows Server 2008 R2 instance with an AWS Identity and Access Management
(IAM) instance profile role. For more information, see Create an IAM Instance Profile for Systems
Manager (p. 29).
• Verify that the instance has 20 GB of free disk space in the boot disk.
• If the instance does not use an AWS-provided Windows license, then specify an EBS Snapshot ID that
includes Windows Server 2012 R2 installation media. To do this:
• Verify that the Amazon EC2 instance is running Windows Server 2012 or later.
• Create a 6 GB EBS volume in the same Availability Zone where the instance is running. Attach the
volume to the instance. Mount it, for example, as drive D.
• Right-click the ISO and mount it to an instance as, for example, drive E.
• Copy the content of the ISO from drive E:\ to drive D:\
• Create an EBS snapshot of the 6 GB volume created in step 2 above.

Limitations

This Automation doesn't support upgrading Windows domain controllers, clusters, or Windows work
stations. This Automation also doesn't support Windows instances with the following roles installed.

• Remote Desktop Session Host (RDSH)

• Remote Desktop Connection Broker (RDCB)
• Remote Desktop Virtualization Host (RDVH)
• Remote Desktop Web Access (RDWA)

Parameters

309
 AWS Systems Manager User Guide
Working with Automation Documents

• InstanceId

Type: String

Description: (Required) The instance running Windows Server 2008 R2.

• IamInstanceProfile

Type: String

Description: (Required) The name of the IAM instance profile that enables Systems Manager to manage
the instance.
• SubnetId

Type: String

Description: (Required) Provide a subnet for the upgrade process. Verify that the subnet has outbound
connectivity to AWS services, Amazon S3, and Microsoft (to download patches).
• BYOLWindowsMediaSnapshotId

Type: String

Description: (Optional) The ID of the Amazon EBS snapshot to copy that includes Windows Server
2012 R2 installation media. Required only if you are upgrading a BYOL instance.
• KeepPreUpgradeImageBackUp

Type: String

Description: (Optional) If set True, the Automation doesn't delete the AMI created from the instance
before the upgrade. If set to True, then you must delete the AMI. By default, the AMI is deleted.
• RebootInstanceBeforeTakingImage

Type: String

Description: (Optional) If set True, the Automation reboots the instance before creating a pre-upgrade
AMI. By default, the Automation doesn't reboot before upgrade.

AWSEC2-CloneInstanceAndUpgradeSQLServer

Description

Create an AMI from an Amazon EC2 Windows instance running SQL Server 2008 (or later), and then
upgrade the AMI to SQL Server 2016. The upgrade is a multi-step process that can take 2 hours to
complete. The Automation creates the AMI from the instance, and then launches the new AMI in the
subnet that you provide. The Automation then performs an in-place upgrade of SQL Server 2008 (or
later) to SQL Server 2016. After the upgrade, the Automation creates a new AMI before terminating the
upgraded instance.

You can test application functionality by launching the new AMI in your VPC. After you finish testing, and
before you perform another upgrade, schedule application downtime before completely switching over
to the upgraded instance.
Note
If you want to modify the computer name of the EC2 instance launched from the new AMI, see
Rename a Computer that Hosts a Stand-Alone Instance of SQL Server.

Document Type

Automation

310
 AWS Systems Manager User Guide
Working with Automation Documents

Owner

Amazon

Platforms

Windows

Prerequisites

• The Amazon EC2 instance must use a version of Windows Server that is Windows Server 2008 R2 (or
later) and SQL Server 2008 (or later).
• Verify that SSM Agent is installed on your instance. For more information, see Installing and
Configuring SSM Agent on Windows Instances (p. 65).
• Configure the instance to use an AWS Identity and Access Management (IAM) instance profile role. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
• Verify that the instance has 20 GB of free disk space in the instance boot disk.
• For instances that use a Bring Your Own License (BYOL) SQL Server version, the following additional
prerequisites apply:
• Provide an EBS snapshot ID that includes SQL Server 2016 installation media. To do this:

1. Verify that the Amazon EC2 instance is running Windows Server 2008 R2 or later.
2. Create a 6 GB EBS volume in the same Availability Zone where the instance is running. Attach
the volume to the instance. Mount it, for example, as drive D.
3. Right-click the ISO and mount it to an instance as, for example, drive E.
4. Copy the content of the ISO from drive E:\ to drive D:\
5. Create an EBS snapshot of the 6 GB volume created in step 2.

Limitations

• The upgrade can only be performed on a SQL Server using Windows authentication.
• Verify that no security patch updates are pending on the instances. Open Control Panel, then choose
Check for updates.
• SQL Server deployments in HA and mirroring mode are not supported.

Parameters

• InstanceId

Type: String

Description: (Required) The instance running Windows Server 2008 R2 (or later) and SQL Server 2008
(or later).
• IamInstanceProfile

Type: String

Description: (Required) The IAM instance profile.

• SubnetId

Type: String

Description: (Required) Provide a subnet for the upgrade process. Verify that the subnet has outbound
connectivity to AWS services, Amazon S3, and Microsoft (to download patches).

311
 AWS Systems Manager User Guide
Working with Automation Documents

• SQLServerSnapshotId

Type: String

Description: (Conditional) Snapshot ID for SQL Server 2016 installation media. This parameter is
required for instances that use a BYOL SQL Server version. This parameter is optional for SQL Server
license-included instances (instances launched using an AWS provided Amazon Machine Image for
Windows Server with Microsoft SQL Server).
• KeepPreUpgradeImageBackUp

Type: String

Description: (Optional) If set to True, the Automation doesn't delete the AMI created from the instance
before the upgrade. If set to True, then you must delete the AMI. By default, the AMI is deleted.
• RebootInstanceBeforeTakingImage

Type: String

Description: (Optional) If set to True, the Automation reboots the instance before creating a pre-
upgrade AMI. By default, the Automation doesn't reboot before upgrade.

Outputs

AMIId: The ID of the AMI created from the instance that was upgraded to SQL Server 2016

AWS-CreateDynamoDBBackup

Description

Create a backup of an Amazon DynamoDB table.

Document Type

Automation

Owner

Amazon

Platforms

This document is not restricted to specific operating system.

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• BackupName

Type: String

Description: (Required) Name of the backup to create.

• LambdaAssumeRole

Type: String

312
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• TableName

Type: String

Description: (Required) Name of the DynamoDB table.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateDynamoDbBackup --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:invokeLambdaFunction

aws:deleteStack

Outputs

createDynamoDbBackup.Payload

AWS-CreateImage

Description

Create a new Amazon Machine Image (AMI) from an Amazon EC2 instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

• AutomationAssumeRole

Type: String

313
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) The ID of the Amazon EC2 instance.

• NoReboot

Type: Boolean

Description: (Optional) Do not reboot the instance before creating the image.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateImage --parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createImage

Outputs

createImage.ImageId

AWS-CreateJiraIssue

Description

Create an issue in Jira.

Document Type

Automation

Owner

Amazon

Platform(s)

Windows, Linux

Parameters

• IssueDescription

Type: String

314
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) A detailed description of the issue.

• IssueSummary

Type: String

Description: (Required) A brief summary of the issue.

• IssueTypeName

Type: String

Description: (Required) The name of the type of issue you want to create (for example, Task, Sub-task,
Bug, etc.).
• JiraURL

Type: String

Description: (Required) The url of the Jira instance.

• JiraUsername

Type: String

Description: (Required) The name of the user the issue will be created with.
• ProjectKey

Type: String

Description: (Required) The key of the project the issue should be created in.
• SSMParameterName

Type: String

Description: (Required) The name of an encrypted SSM Parameter containing the API key or password
for the Jira user.
• AssigneeName

Type: String

Description: (Optional) The username of the person the issue should be assigned to.
• DueDate

Type: String

Description: (Optional) The due date for the issue in yyyy-mm-dd format.
• PriorityName

Type: String

Description: (Optional) The name of the priority of the issue.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateJiraIssue --

parameters parameters

315
 AWS Systems Manager User Guide
Working with Automation Documents

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack - Create CloudFormation stack to create Lambda IAM role and function.

aws:invokeLambdaFunction - Invoke Lambda function to create the Jira issue

aws:deleteStack - Delete the CloudFormation stack created.

Outputs

IssueId: ID of the newly created Jira issue

AWS-CreateManagedLinuxInstance

Description

Create an Amazon EC2 Linux instance that is configured for Systems Manager.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AmiId

Type: String

Description: (Required) AMI ID to use for launching the instance.

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf
• GroupName

Type: String

Default: SSMSecurityGroupForLinuxInstances

Description: (Required) Security group name to create.

• InstanceType

Type: String

316
 AWS Systems Manager User Guide
Working with Automation Documents

Default: t2.medium

Description: (Required) Type of instance to launch. Default is t2.medium.

• KeyPairName

Type: String

Description: (Required) Key pair to use when creating instance.

• RemoteAccessCidr

Type: String

Default: 0.0.0.0/0

Description: (Required) Creates Security group with port for SSH(Port range 22) open to IPs specified
by CIDR (default is 0.0.0.0/0). If the security group already exists it will not be modified and rules will
not be changed.
• RoleName

Type: String

Default: SSMManagedInstanceProfileRole

Description: (Required) Role name to create.

• StackName

Type: String

Default: CreateManagedInstanceStack{{automation:EXECUTION_ID}}

Description: (Optional) Specify stack name used by this document

• SubnetId

Type: String

Default: Default

Description: (Required) New instance will be deployed into this subnet or in the default subnet if not
specified.
• VpcId

Type: String

Default: Default

Description: (Required) New instance will be deployed into this Amazon Virtual Private Cloud (Amazon
VPC) or in the default Amazon VPC if not specified.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateManagedLinuxInstance --

parameters parameters

Retrieve the execution output

317
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:deleteStack

Outputs

None

AWS-CreateManagedWindowsInstance

Description

Create an Amazon EC2 Windows instance that is configured for Systems Manager.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AmiId

Type: String

Default: {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}

Description: (Required) AMI ID to use for launching the instance.

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf
• GroupName

Type: String

Default: SSMSecurityGroupForLinuxInstances

Description: (Required) Security group name to create.

• InstanceType

Type: String

Default: t2.medium

318
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) Type of instance to launch. Default is t2.medium.

• KeyPairName

Type: String

Description: (Required) Key pair to use when creating instance.

• RemoteAccessCidr

Type: String

Default: 0.0.0.0/0

Description: (Required) Creates security group with port for RDP (Port range 3389) open to IPs
specified by CIDR (default is 0.0.0.0/0). If the security group already exists it will not be modified and
rules will not be changed.
• RoleName

Type: String

Default: SSMManagedInstanceProfileRole

Description: (Required) Role name to create.

• StackName

Type: String

Default: CreateManagedInstanceStack{{automation:EXECUTION_ID}}

Description: (Optional) Specify stack name used by this document

• SubnetId

Type: String

Default: Default

Description: (Required) New instance will be deployed into this subnet or in the default subnet if not
specified.
• VpcId

Type: String

Default: Default

Description: (Required) New instance will be deployed into this Amazon Virtual Private Cloud (Amazon
VPC) or in the default Amazon VPC if not specified.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateManagedWindowsInstance --

parameters parameters

Retrieve the execution output

319
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:deleteStack

Outputs

None

AWS-CreateSnapshot

Description

Create a snapshot of an Amazon EBS volume.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• Description

Type: String

Description: (Optional) A description for the snapshot

• VolumeId

Type: String

Description: (Required) The ID of the volume.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-CreateSnapshot --

parameters parameters

Retrieve the execution output

320
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

aws:waitForAwsResourceProperty

Outputs

createSnapshot.Payload

AWS-DeleteCloudFormationStack

Description

Delete an AWS CloudFormation stack.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• StackNameOrId

Type: String

Description: (Required) Name or Unique ID of the CloudFormation stack to be deleted

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteCloudFormationStack --

parameters parameters

Retrieve the execution output

321
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:deleteStack

Outputs

None

AWS-DeleteDynamoDBBackup

Description

Delete the backup of an Amazon DynamoDB table.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• BackupArn

Type: String

Description: (Required) ARN of the DynamoDB table backup to delete.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteDynamoDbBackup --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

322
 AWS Systems Manager User Guide
Working with Automation Documents

aws:executeAwsApi

Outputs

None

AWS-DeleteDynamoDBTableBackups

Description

Delete DynamoDB table backups based on retention days or count.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• RetentionCount

Type: String

Default: 10

Description: (Optional) The number of backups to retain for the table. If more than the specified
number of backup exist, the oldest backups beyond that number are deleted. Either RetentionCount or
RetentionDays can be used, not both.
• RetentionDays

Type: String

Description: (Optional) The number of days to retain backups for the table. Backups older than the
specified number of days are deleted. Either RetentionCount or RetentionDays can be used, not both.
• TableName

Type: String

Description: (Required) Name of the DynamoDB table.

Examples

323
 AWS Systems Manager User Guide
Working with Automation Documents

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteDynamoDbTableBackups --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

deleteDynamoDbTableBackups.Payload

AWS-DeleteEBSVolumeSnapshots

Description

Delete a snapshot of an Amazon Elastic Block Store (Amazon EBS) volume.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• RetentionCount

Type: String

324
 AWS Systems Manager User Guide
Working with Automation Documents

Default: 10

Description: (Optional) Number of snapshots to keep for the volume. Either RetentionCount or
RetentionDays should be mentioned, not both.
• RetentionDays

Type: String

Description: (Optional) Number of days to keep snapshots for the volume. Either RetentionCount or
RetentionDays should be mentioned, not both
• VolumeId

Type: String

Description: (Required) The volume identifier to delete snapshots for.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteEbsVolumeSnapshots --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

deleteVolumeSnapshots.Payload

AWS-DeleteImage

Description

Delete an Amazon Machine Image (AMI) and all associated snapshots.

Document Type

Automation

Owner

Amazon

Platforms

325
 AWS Systems Manager User Guide
Working with Automation Documents

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• ImageId

Type: String

Description: (Required) The ID of the AMI.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteImage --parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:deleteImage

Outputs

None

AWS-DeleteSnapshot

Description

Delete a snapshot of an Amazon EBS volume.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

326
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• SnapshotId

Type: String

Description: (Required) The ID of the EBS snapshot.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DeleteSnapshot --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

Outputs

None

AWS-DetachEBSVolume

Description

Detach an Amazon EBS volume from an Amazon EC2 instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.

327
 AWS Systems Manager User Guide
Working with Automation Documents

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role assumed by Lambda

• VolumeId

Type: String

Description: (Required) The ID of the EBS volume. The volume and instance must be within the same
Availability Zone

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DetachEBSVolume --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

detachVolume.LogResult

AWS-DisablePublicAccessForSecurityGroup

Description

This document disables default SSH and RDP ports that are opened to all IP addresses.
Important
This document fails with an "InvalidPermission.NotFound" error for security groups that meet
both of the following criteria: 1) The security group is located in a non-default VPC; and 2) The
inbound rules for the security group don't specify open ports using all four of the following
patterns:

• 0.0.0.0/0
• ::/0
• SSH or RDP port + 0.0.0.0/0
• SSH or RDP port + ::/0

If the security group is located in a non-default VPC and, for example, specifies open ports using
only the SSH or RDP port + 0.0.0.0/0 format, then the document fails to run.

328
 AWS Systems Manager User Guide
Working with Automation Documents

Document Type

Automation

Owner

Amazon

Platform(s)

Windows, Linux

Parameters

• GroupId

Type: String

Description: (Required) The ID of the security group for which the ports should be disabled.
• IpAddressToBlock

Type: String

Description: (Optional) Additional IPv4 addresses from which access should be blocked, in the format
1.2.3.4/32.
• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DisablePublicAccessForSecurityGroup

--parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Outputs

None

AWS-Disables3BucketPublicReadWrite

Description

Use Amazon Simple Storage Service (Amazon S3) Block Public Access to disable read and write
access for a public Amazon S3 bucket. For more information, see Using Amazon S3 Block Public Access in
the Amazon Simple Storage Service Developer Guide.

Document Type

329
 AWS Systems Manager User Guide
Working with Automation Documents

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• S3BucketName

Type: String

Description: (Required) Amazon S3 bucket on which you want to restrict access.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-DisableS3BucketPublicReadWrite --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

Outputs

None

AWS-EnableCloudTrail

Description

Create an AWS CloudTrail trail and configure logging to an Amazon S3 bucket.

Document Type

Automation

Owner

330
 AWS Systems Manager User Guide
Working with Automation Documents

Amazon

Platform(s)

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• S3BucketName

Type: String

Description: (Required) Name of the Amazon S3 bucket designated for publishing log files.
Note
The S3 bucket must exist and the bucket policy must grant CloudTrail permission to write to
it. For information, see Amazon S3 Bucket Policy for CloudTrail.
• TrailName

Type: String

Description: (Required) The name of the new trail.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-EnableCloudTrail --parameters

TrailName=TrailName,S3BucketName=s3bucketname,AutomationAssumeRole=arn:aws:iam::123456789012:role/
AutomationRole

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi - cloudtrail:CreateTrail

Outputs

None

AWS-Enables3BucketEncryption

Description

Enable encryption for an Amazon Simple Storage Service (Amazon S3) bucket (encrypt the contents of
the bucket).

331
 AWS Systems Manager User Guide
Working with Automation Documents

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• BucketName

Type: String

Description: (Required) The name of the Amazon S3 bucket where you want to encrypt the contents.
• SSEAlgorithm

Type: String

Default: AES256

Description: (Optional) Server-side encryption algorithm to use for the default encryption.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-EnableS3BucketEncryption --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi

Outputs

None

AWSSupport-ExecuteEC2Rescue

Description

332
 AWS Systems Manager User Guide
Working with Automation Documents

This document will use the EC2Rescue tool to troubleshoot and where possible repair common
connectivity issues with the specified EC2 instance (Windows or Linux).

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• UnreachableInstanceId

Type: String

Description: (Required) ID of your unreachable EC2 instance. IMPORTANT: AWS Systems Manager
Automation stops this instance, and creates an AMI before attempting any operations. Data stored in
instance store volumes will be lost. The public IP address will change if you are not using an Elastic IP.
• SubnetId

Type: String

Default: CreateNewVPC

Description: (Optional) The subnet ID for the EC2Rescue instance. By default, AWS Systems Manager
Automation creates a new VPC. Alternatively, Use SelectedInstanceSubnet to use the same subnet as
your instance, or specify a custom subnet ID. IMPORTANT: The subnet must be in the same Availability
Zone as UnreachableInstanceId, and it must allow access to the SSM endpoints.
• EC2RescueInstanceType

Type: String

Allowed values: t2.small,t2.medium,t2.large

Default: t2.small

Description: (Required) The EC2 instance type for the EC2Rescue instance. Recommended size:
t2.small.
• LogDestination

Type: String

Description: (Optional) S3 bucket name in your account where you want to upload the troubleshooting
logs. Make sure the bucket policy does not grant unnecessary read/write permissions to parties that do
not need access to the collected logs.
• AssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use your IAM permissions to run this document.

Examples

333
 AWS Systems Manager User Guide
Working with Automation Documents

EC2Rescue an instance

aws ssm start-automation-execution --document-name AWSSupport-ExecuteEC2Rescue --parameters

'UnreachableInstanceId=INSTANCEID'

EC2Rescue an instance and use the current instance subnet for the EC2Rescue instance

aws ssm start-automation-execution --document-name AWSSupport-ExecuteEC2Rescue --parameters

'UnreachableInstanceId=INSTANCEID,SubnetId=SelectedInstanceSubnet'

EC2Rescue an instance and use a custom subnet for the EC2Rescue instance

aws ssm start-automation-execution --document-name AWSSupport-ExecuteEC2Rescue --parameters

'UnreachableInstanceId=INSTANCEID,SubnetId=SUBNETID'

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

You must have at least ssm:ExecuteAutomation and ssm:GetAutomationExecution to be able to

read the automation output. For more information about the required permissions see AWSSupport-
StartEC2RescueWorkflow

Document Steps

1. aws:assertAwsResourceProperty - Assert if the provided instance is Windows

a. (EC2Rescue for Windows) If the provided instance is Windows:
i. aws:executeAutomation - Invoke AWSSupport-StartEC2RescueWorkflow with the EC2Rescue for
Windows offline script
ii. aws:executeAwsApi - Retrieve the backup AMI ID from the nested automation
iii. aws:executeAwsApi - Retrieve the EC2Rescue summary from the nested automation
b. (EC2Rescue for Linux) If the provided instance is Linux:
i. aws:executeAutomation - Invoke AWSSupport-StartEC2RescueWorkflow with the EC2Rescue for
Linux offline script
ii. aws:executeAwsApi - Retrieve the backup AMI ID from the nested automation
iii. aws:executeAwsApi - Retrieve the EC2Rescue summary from the nested automation

Outputs

getEC2RescueForWindowsResult.Output

getWindowsBackupAmi.ImageId

getEC2RescueForLinuxResult.Output

getLinuxBackupAmi.ImageId

AWSSupport-GrantPermissionsToIAMUser

Description

334
 AWS Systems Manager User Guide
Working with Automation Documents

This document grants the specified permissions to an IAM group (new or existing), and adds the
existing IAM user to it. Policies you can choose from: Billing or Support. To enable billing access for
IAM, remember to also activate IAM user and federated user access to the Billing and Cost Management
pages.
Important
If you provide an existing IAM group, all current IAM users in the group receive the new
permissions.

Document Type

Automation

Owner

Amazon

Parameters

• IAMUserName

Type: String

Default: ExampleUser

Description: (Required) Must be an existing user.

• IAMGroupName

Type: String

Default: ExampleSupportAndBillingGroup

Description: (Required) Can be a new or existing group. Must comply with IAM Entity Name Limits.
• Permissions

Type: String

Allowed values: SupportFullAccess,BillingFullAccess,SupportAndBillingFullAccess

Default: SupportAndBillingFullAccess

Description: (Required) Choose one of: SupportFullAccess - Grants full access to the Support center |
BillingFullAccess - Grants full access to the Billing dashboard | SupportAndBillingFullAccess - Grants
full access to both Support center and the Billing dashboard. More info on policies under Document
details.
• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf. If no role is specified, AWS Systems Manager Automation will use the permissions of the user
that runs this document.
• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role assumed by lambda.

Examples

335
 AWS Systems Manager User Guide
Working with Automation Documents

Add IAM user BillingUser to IAM group BillingGroup and grant full access to the AWS Billing and Cost
Management console

aws ssm start-automation-execution --document-name "AWSSupport-GrantPermissionsToIAMUser"

--parameters "IAMGroupName=BillingGroup, IAMUserName=BillingUser,
Permissions=BillingFullAccess"

Add IAM user SupportUser to IAM group SupportGroup and grant full access to Support Center

aws ssm start-automation-execution --document-name "AWSSupport-GrantPermissionsToIAMUser"

--parameters "IAMGroupName=SupportGroup, IAMUserName=SupportUser,
Permissions=SupportFullAccess"

Add IAM user SupportAndBillingUser to IAM group SupportAndBillingGroup and grant full access both
Support Center and the AWS Billing and Cost Management console

aws ssm start-automation-execution --document-name "AWSSupport-GrantPermissionsToIAMUser"

--parameters "IAMGroupName=SupportAndBillingGroup, IAMUserName=SupportAndBillingUser"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

Least privileges depend on how AWSSupport-GrantPermissionsToIAMUser is run.

Direct execution

It is recommended you have the **AmazonSSMAutomationRole** Amazon managed policy attached, and
the following additional permissions to be able to create the Lambda function and the IAM Role to pass
to Lambda:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:CreateFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:ACCOUNTID:function:AWSSupport-*",
"Effect": "Allow"
},
{
"Effect" : "Allow",
"Action" : [
"iam:CreateGroup",
"iam:AddUserToGroup",
"iam:ListAttachedGroupPolicies",
"iam:GetGroup",
"iam:GetUser"
],
"Resource" : [
"arn:aws:iam::*:user/*",

336
 AWS Systems Manager User Guide
Working with Automation Documents

"arn:aws:iam::*:group/*"
]
},
{
"Effect" : "Allow",
"Action" : [
"iam:AttachGroupPolicy"
],
"Resource": "*",
"Condition": {
"ArnEquals": {
"iam:PolicyArn": [
"arn:aws:iam::aws:policy/job-function/Billing",
"arn:aws:iam::aws:policy/AWSSupportAccess"
]
}
}
},
{
"Effect" : "Allow",
"Action" : [
"iam:ListAccountAliases",
"iam:GetAccountSummary"
],
"Resource" : "*"
}
]
}

Using AutomationAssumeRole and LambdaAssumeRole

The user must have the ssm:ExecuteAutomation permissions on the document, and iam:PassRole on
the IAM roles passed as AutomationAssumeRole and LambdaAssumeRole. Here are the permissions
each IAM role needs:

AutomationAssumeRole

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:CreateFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource":
"arn:aws:lambda:*:ACCOUNTID:function:AWSSupport-*",
"Effect": "Allow"
}
]
}

LambdaAssumeRole

{
"Version": "2012-10-17",
"Statement": [
{
"Effect" : "Allow",
"Action" : [

337
 AWS Systems Manager User Guide
Working with Automation Documents

"iam:CreateGroup",
"iam:AddUserToGroup",
"iam:ListAttachedGroupPolicies",
"iam:GetGroup",
"iam:GetUser"
],
"Resource" : [
"arn:aws:iam::*:user/*",
"arn:aws:iam::*:group/*"
]
},
{
"Effect" : "Allow",
"Action" : [
"iam:AttachGroupPolicy"
],
"Resource": "*",
"Condition": {
"ArnEquals": {
"iam:PolicyArn": [
"arn:aws:iam::aws:policy/job-function/Billing",
"arn:aws:iam::aws:policy/AWSSupportAccess"
]
}
}
},
{
"Effect" : "Allow",
"Action" : [
"iam:ListAccountAliases",
"iam:GetAccountSummary"
],
"Resource" : "*"
}
]
}

Document Steps

1. aws:createStack - Run AWS CloudFormation Template to create a Lambda function.

2. aws:invokeLambdaFunction - Run Lambda to set IAM permissions.
3. aws:deleteStack - Delete CloudFormation Template.

Outputs

configureIAM.Payload

AWSSupport-ManageRDPSettings

Description

The AWSSupport-ManageRDPSettings automation document allows the user to manage common

Remote Desktop Protocol (RDP) settings, such as the RDP port and Network Layer Authentication (NLA).
By default, the document reads and outputs the values of the settings.
Important
Changes to the RDP settings should be carefully reviewed before running this document.

Document Type

Automation

338
 AWS Systems Manager User Guide
Working with Automation Documents

Owner

Amazon

Platforms

Windows

Parameters

• InstanceId

Type: String

Description: (Required) The ID of the managed instance to manage the RDP settings of.
• RDPPortAction

Type: String

Allowed values: Check,Modify

Default: Check

Description: (Required) An action to apply to the RDP port: Check, Modify.

• RDPPort

Type: String

Default: 3389

Description: (Optional) Specify the new RDP port. Used only when the action is set to Modify. The port
number must be between 1025-65535. Note: After the port is changed, the RDP service is restarted.
• NLASettingAction

Type: String

Allowed values: Check,Enable,Disable

Default: Check

Description: (Required) An action to perform on the NLA setting: Check, Enable, Disable.
• RemoteConnections

Type: String

Allowed values: Check,Enable,Disable

Default: Check

Description: (Required) An action to perform on the fDenyTSConnections setting: Check, Enable,

Disable.
• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

339
 AWS Systems Manager User Guide
Working with Automation Documents

Check RDP Settings

aws ssm start-automation-execution --document-name "AWSSupport-ManageRDPSettings" --

parameters "InstanceId=INSTANCEID"

Restore the default RDP port (3389), disable NLA, enable remote connections

aws ssm start-automation-execution --document-name "AWSSupport-ManageRDPSettings"

--parameters "InstanceId=INSTANCEID,RDPPortAction=Modify, RDPPort=3389,
NLASettingAction=Disable,RemoteConnections=Enable"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

The EC2 instance receiving the command must have an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. The user must have at least
ssm:SendCommand to send the command to the instance, plus ssm:GetCommandInvocation to be able
to read the command output.

Document Steps

aws:runCommand - Run the PowerShell script to change or check the RDP settings on the target
instance.

Outputs

manageRDPSettings.Output

AWSSupport-ManageWindowsService

Description

The AWSSupport-ManageWindowsService automation document enables a user to stop, start, restart,

pause, or disable any Windows service on the target instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows

Parameters

• InstanceId

Type: String

Description: (Required) The ID of the managed instance to manage the RDP settings of.

340
 AWS Systems Manager User Guide
Working with Automation Documents

• WindowsServiceName

Type: String

Description: (Required) A valid Windows service name.

• StartupType

Type: String

Allowed values: Check,Auto,Demand,Disabled,DelayedAutoStart

Default: Check

Description: (Required) A startup type to apply to the Windows service: Auto, Demand (Manual),
Disabled, DelayAutoStart, Check.
• ServiceAction

Type: String

Allowed values: Check,Restart,Force-Restart,Start,Stop,Force-Stop,Pause

Default: Check

Description: (Required) An action to apply to the Windows service: Restart, Force-Restart, Start, Stop,
Force-Stop, Pause, Check. Note: Force-Restart and Force-Stop can be used to restart and to stop a
service that has dependent services.
• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Check RDP Settings

aws ssm start-automation-execution --document-name "AWSSupport-ManageWindowsService" --

parameters "InstanceId=i-1234567890abcdef0, WindowsServiceName=TermService"

Change the Startup Type of the TermService to Auto and change Service Action to Start

aws ssm start-automation-execution --document-name "AWSSupport-ManageWindowsService"

--parameters "InstanceId=i-1234567890abcdef0, WindowsServiceName=TermService,
StartupType=Auto, ServiceAction=Start"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. The user must have at least
ssm:ExecuteAutomation and ssm:SendCommand to run the automation and send the command to the
instance, plus ssm:GetAutomationExecution to be able to read the automation output.

341
 AWS Systems Manager User Guide
Working with Automation Documents

Document Steps

aws:runCommand - Run the PowerShell script to apply the desired configuration to the Windows service
on the target instance.

Outputs

manageWindowsService.Output

AWS-PatchASGInstance

Description

Patch Amazon EC2 instances in an Auto Scaling group.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) ID of the instance to patch. Don't specify an instance ID that is configured to
run during a Maintenance Window.
• LambdaRoleArn

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• WaitForInstance

Type: String

Default: PT2M

Description: (Optional) Duration the Automation should sleep to allow the instance to come back into
service.
• WaitForReboot

Type: String

Default: PT5M

342
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) Duration the Automation should sleep to allow a patched instance to reboot.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-PatchAsgInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createTags

aws:executeAutomation

aws:runCommand

aws:sleep

aws:executeAutomation

aws:createTags

aws:sleep

Outputs

None

AWS-PatchInstanceWithRollback

Description

Brings Amazon EC2 instance into compliance with standing baseline; rolls back root volume on failure.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

343
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) EC2 InstanceId to which we apply the patch-baseline.

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• ReportS3Bucket

Type: String

Description: (Optional) Amazon S3 Bucket destination for the Compliance Report generated during
process.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-PatchInstanceWithRollback --

parameters InstanceId=i-1234567890abcdef0

{
"AutomationExecutionId": "ab08779f-002d-42dd-9222-0123456789ab"
}

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --query

'AutomationExecution.Output'

Document Steps

Step Number Step Name Automation Action

1 createDocumentStack aws:createStack

2 IdentifyRootVolume aws:invokeLambdaFunction

3 PrePatchSnapshot aws:executeAutomation

4 installMissingUpdates aws:runCommand

5 SleepThruInstallation aws:invokeLambdaFunction

6 CheckCompliance aws:invokeLambdaFunction

7 SaveComplianceReportToS3 aws:invokeLambdaFunction

8 ReportSuccessOrFailure aws:invokeLambdaFunction

344
 AWS Systems Manager User Guide
Working with Automation Documents

Step Number Step Name Automation Action

9 DeleteSnapshot aws:invokeLambdaFunction

10 createDocumentStack aws:deleteStack

Outputs

IdentifyRootVolume.Payload

PrePatchSnapshot.Output

SaveComplianceReportToS3.Payload

RestoreFromSnapshot.Payload

CheckCompliance.Payload

AWS-PublishSNSNotification

Description

Publish a notification to Amazon SNS.

Document Type

Automation

Owner

Amazon

Platform(s)

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• Message

Type: String

Description: (Required) The message to include in the SNS notification.

• TopicARN

Type: String

Description: (Required) The ARN of the SNS topic to publish the notification to.

Examples

Start the automation

345
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm start-automation-execution --document-name AWS-PublishSNSNotification --parameters

Message=message,TopicARN=arn:aws:sns:us-east-1:123456789012:SNSTopicARN

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi - sns:Publish

Outputs

None

AWS-RebootRDSInstance

Description

Reboot an Amazon Relational Database Service (Amazon RDS) instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) The ID of the Amazon RDS instance that you want to reboot.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-RebootRdsInstance --

parameters parameters

346
 AWS Systems Manager User Guide
Working with Automation Documents

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:assertAwsResourceProperty

aws:executeAwsApi

aws:waitForAwsResourceProperty

Outputs

None

AWSSupport-ResetAccess

Description

This document will use the EC2Rescue tool on the specified EC2 instance to re-enable password
decryption via the EC2 Console (Windows), or to generate and add a new SSH key pair (Linux). If you lost
your key pair, this automation will create a password-enabled AMI that you can use to launch a new EC2
instance with a key pair you own (Windows).

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• InstanceId

Type: String

Description: (Required) ID of the EC2 instance you want to reset access for.
Important
Systems Manager Automation stops this instance, and creates an AMI before attempting
any operations. Data stored in instance store volumes will be lost. The public IP address will
change if you are not using an Elastic IP.
• SubnetId

Type: String

Default: CreateNewVPC

Description: (Optional) The subnet ID for the EC2Rescue instance. By default, Systems Manager
Automation creates a new VPC. Alternatively, Use SelectedInstanceSubnet to use the same subnet as
your instance, or specify a custom subnet ID.

347
 AWS Systems Manager User Guide
Working with Automation Documents

Important
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to
the SSM endpoints.
• EC2RescueInstanceType

Type: String

Allowed values: t2.small,t2.medium,t2.large

Default: t2.small

Description: (Required) The EC2 instance type for the EC2Rescue instance. Recommended size:
t2.small.
• AssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Enable EC2 password generation for Windows

aws ssm start-automation-execution --document-name AWSSupport-ResetAccess --parameters

'InstanceId=WINDOWSINSTANCEID'

Enable EC2 password generation for Windows and use the provided instance's subnet for the EC2Rescue
instance

aws ssm start-automation-execution --document-name AWSSupport-ResetAccess --parameters

'InstanceId=WINDOWSINSTANCEID,SubnetId=SelectedInstanceSubnet'

Generate a new SSH key for Linux

aws ssm start-automation-execution --document-name AWSSupport-ResetAccess --parameters

'InstanceId=LINUXINSTANCEID'

Generate a new SSH key for Linux and use the provided instance's subnet for the EC2Rescue instance

aws ssm start-automation-execution --document-name AWSSupport-ResetAccess --parameters

'InstanceId=LINUXINSTANCEID,SubnetId=SelectedInstanceSubnet'

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

You must have at least ssm:ExecuteAutomation, ssm:GetParameter (to retrieve the SSH key parameter
name) and ssm:GetAutomationExecution to be able to read the automation output. For more
information about the required permissions, see AWSSupport-StartEC2RescueWorkflow (p. 371).

Document Steps

348
 AWS Systems Manager User Guide
Working with Automation Documents

1. aws:assertAwsResourceProperty - Assert if the provided instance is Windows.

a. (EC2Rescue for Windows) If the provided instance is Windows:
i. aws:executeAutomation - Invoke AWSSupport-StartEC2RescueWorkflow with the EC2Rescue for
Windows offline password reset script
ii. aws:executeAwsApi - Retrieve the backup AMI ID from the nested automation
iii. aws:executeAwsApi - Retrieve the password-enabled AMI ID from the nested automation
iv. aws:executeAwsApi - Retrieve the EC2Rescue summary from the nested automation
b. (EC2Rescue for Linux) If the provided instance is Linux:
i. aws:executeAutomation - Invoke AWSSupport-StartEC2RescueWorkflow with the EC2Rescue for
Linux offline SSH key injection script
ii. aws:executeAwsApi - Retrieve the backup AMI ID from the nested automation
iii. aws:executeAwsApi - Retrieve the SSM parameter name for the injected SSH key
iv. aws:executeAwsApi - Retrieve the EC2Rescue summary from the nested automation

Outputs

getEC2RescueForWindowsResult.Output

getWindowsBackupAmi.ImageId

getWindowsPasswordEnabledAmi.ImageId

getEC2RescueForLinuxResult.Output

getLinuxBackupAmi.ImageId

getLinuxSSHKeyParameter.Name

AWS-ReleaseElasticIP

Description

Release the specified Elastic IP address using the allocation ID.

Document Type

Automation

Owner

Amazon

Platform(s)

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• AllocationId

Type: String

349
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) The Allocation ID of the Elastic IP address.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ReleaseElasticIP --parameters

AllocationId=eipalloc-0123456789abcdefg

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAwsApi - ec2:ReleaseAddress

Outputs

None

AWS-ResizeInstance

Description

Change the instance type of an Amazon EC2 instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) The ID of the instance.

• InstanceType

350
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Required) The instance type.

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role assumed by Lambda.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-ResizeInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:changeInstanceState

aws:invokeLambdaFunction

aws:changeInstanceState

aws:deleteStack

Outputs

None

AWS-RestartEC2Instance

Description

Restart one or more Amazon EC2 instances.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

351
 AWS Systems Manager User Guide
Working with Automation Documents

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: StringList

Description: (Required) EC2 instance(s) to restart

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-RestartEC2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:changeInstanceState

aws:changeInstanceState

Outputs

None

AWSSupport-SendLogBundleToS3Bucket

Description

The AWSSupport-SendLogBundleToS3Bucket Automation document uploads a log bundle generated

by the EC2Rescue tool from the target instance to the specified S3 bucket. The automation execution
installs the platform specific version of EC2Rescue based on the platform of the target instance.
EC2Rescue is then used to collect all the available operating system (OS) logs.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

352
 AWS Systems Manager User Guide
Working with Automation Documents

Parameters

• InstanceId

Type: String

Description: (Required) The ID of the Windows or Linux managed instance you want to collect logs
from.
• S3BucketName

Type: String

Description: (Required) S3 bucket to upload the logs to.

• S3Path

Type: String

Default: AWSSupport-SendLogBundleToS3Bucket/

Description: (Optional) S3 path for the collected logs.

• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Collect logs from INSTANCEID and upload them to S3 Bucket mybucket

aws ssm start-automation-execution --document-name AWSSupport-SendLogBundleToS3Bucket --

parameters "InstanceId=INSTANCEID, S3BucketName=mybucket"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. The user must have at least
ssm:ExecuteAutomation and ssm:SendCommand to run the automation and send the command to the
instance, plus ssm:GetAutomationExecution to be able to read the automation output.

Document Steps

1. aws:runCommand - Install EC2Rescue via AWS-ConfigureAWSPackage.

2. aws:runCommand - Run the PowerShell script to collect Windows troubleshooting logs with
EC2Rescue.
3. aws:runCommand - Run the bash script to collect Linux troubleshooting logs with EC2Rescue.

Outputs

collectAndUploadWindowsLogBundle.Output

353
 AWS Systems Manager User Guide
Working with Automation Documents

collectAndUploadLinuxLogBundle.Output

AWS-SetupInventory

Description

Create a Systems Manager Inventory association for one or more managed instances. The system collects
metadata from your instances according to the schedule in the association. For more information, see
AWS Systems Manager Inventory (p. 512).

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• Applications

Type: String

Default: Enabled

Description: (Optional) Collect metadata about installed applications.

• AssociatedDocName

Type: String

Default: AWS-GatherSoftwareInventory

Description: (Optional) The name of the SSM document used to collect Inventory from the managed
instance.
• AssociationName

Type: String

Description: (Optional) A name for the Inventory association that will be assigned to the instance.
• AssocWaitTime

Type: String

Default: PT5M

Description: (Optional) Amount of time that Inventory collection should pause when the Inventory
association start time is reached. The time uses ISO 8601 format.
• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• AwsComponents

354
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Default: Enabled

Description: (Optional) Collect metadata for AWS Components like amazon-ssm-agent.

• CustomInventory

Type: String

Default: Enabled

Description: (Optional) Collect custom inventory metadata.

• Files

Type: String

Description: (Optional) Collect metadata about files on your instances. For more information
about how to collect this type of Inventory data, see Working with File and Windows Registry
Inventory (p. 518). Requires SSMAgent version 2.2.64.0 or later. Linux example: [{"Path":"/usr/
bin", "Pattern":["aws*", "*ssm*"],"Recursive":false},{"Path":"/var/log", "Pattern":["amazon*.*"],
"Recursive":true, "DirScanLimit":1000}] Windows example: [{"Path":"%PROGRAMFILES%", "Pattern":
["*.exe"],"Recursive":true}]
• InstanceDetailedInformation

Type: String

Default: Enabled

Description: (Optional) Collect additional information about the instance, including the CPU model,
speed, and the number of cores, to name a few.
• InstanceIds

Type: String

Default: *

Description: (Required) Amazon EC2 instances that you want to inventory.

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• NetworkConfig

Type: String

Default: Enabled

Description: (Optional) Collect metadata about network configurations.

• OutputS3BucketName

Type: String

Description: (Optional) Name of an Amazon S3 bucket where you want to write Inventory log data.
• OutputS3KeyPrefix

Type: String

355
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) An Amazon S3 key prefix (subfolder) where you want to write Inventory log
data.
• OutputS3Region

Type: String

Description: (Optional) The name of the AWS Region where the Amazon S3 exists.
• Schedule

Type: String

Default: cron(0 */30 * * * ? *)

Description: (Optional) A cron expression for the Inventory association schedule. The default is every
30 minutes.
• Services

Type: String

Default: Enabled

Description: (Optional, Windows OS only, requires SSMAgent version 2.2.64.0 and above) Collect data
for service configurations.
• WindowsRegistry

Type: String

Description: (Optional) Collect metadata about Microsoft Windows Registry keys. For more
information about how to collect this type of Inventory data, see Working with File and
Windows Registry Inventory (p. 518). Requires SSM Agent version 2.2.64.0 or later. Example:
[ {"Path":"HKEY_CURRENT_CONFIG\System","Recursive":true},{"Path":"HKEY_LOCAL_MACHINE
\SOFTWARE\Amazon\MachineImage", "ValueNames":["AMIName"]}]
• WindowsRoles

Type: String

Default: Enabled

Description: (Optional) Collect information about Windows roles on the instance. Applies to Windows
operating systems only. Requires SSMAgent version 2.2.64.0 or later.
• WindowsUpdates

Type: String

Default: Enabled

Description: (Optional) Collect data about all Windows Updates on the instance.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-SetupInventory --

parameters parameters

Retrieve the execution output

356
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:sleep

aws:invokeLambdaFunction

aws:deleteStack

Outputs

None

AWSSupport-SetupIPMonitoringFromVPC

Description

AWSSupport-SetupIPMonitoringFromVPC creates an Amazon EC2 instance in the specified subnet and

monitors selected target IPs (IPv4 or IPv6) by continuously running ping, MTR, traceroute and tracetcp
tests. The results are stored in Amazon CloudWatch Logs logs, and metric filters are applied to quickly
visualize latency and packet loss statistics in a CloudWatch dashboard.

Additional Information

The CloudWatch Logs data can be used for network troubleshooting and analysis of pattern/trends.
Additionally, you can configure CloudWatch alarms with Amazon SNS notifications when packet loss
and/or latency reach a threshold. The data can also be used when opening a Premium Support case, to
help isolate an issue quickly and reduce time to resolution when investigating a network issue.
Note
To clean up resources created by AWSSupport-SetupIPMonitoringFromVPC, you can run
the Automation document AWSSupport-TerminateIPMonitoringFromVPC. For more
information, see AWSSupport-TerminateIPMonitoringFromVPC (p. 382).

Document Type

Automation

Owner

Amazon

Parameters

• SubnetId

Type: String

Description: (Required) The subnet ID for the monitor instance. Be aware that if you specify a private
subnet, then you must make sure there is Internet access to allow the monitor instance to setup the
test (meaning, install the CloudWatch Logs agent, interact with Systems Manager and CloudWatch).
• TargetIPs

357
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Required) Comma separated list of IPv4s and/or IPv6s to monitor. No spaces allowed.
Maximum size is 255 characters. Be aware that if you provide an invalid IP, then the automation will
fail and rollback the test setup.
• CloudWatchLogGroupNamePrefix

Type: String

Default: /AWSSupport-SetupIPMonitoringFromVPC

Description: (Optional) Prefix used for each CloudWatch log group created for the test results.
• CloudWatchLogGroupRetentionInDays

Type: String

Allowed values: 1,3,5,7,14,30,60,90,120,150,180,365,400,545,731,1827,3653

Default: 7

Description: (Optional) Number of days you want to keep the network monitoring results for.
• InstanceType

Type: String

Allowed values: t2.micro, t2.small,t2.medium,t2.large

Default: t2.micro

Description: (Optional) The Amazon EC2 instance type for the EC2Rescue instance. Recommended size:
t2.micro.
• AutomationAssumeRole

Type: String

Description: (Optional) The AWS Identity and Access Management (IAM) role for this execution. If no
role is specified, then Systems Manager Automation uses the permissions of the user that runs this
document.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWSSupport-SetupIPMonitoringFromVPC --

parameters 'SubnetId=SUBNETID,TargetIPs="IPV41,IPV42,IPV61"'

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the user who runs the automation have the AmazonSSMAutomationRole IAM
managed policy attached. In addition, the user must have the following policy attached to their user
account, group, or role:

358
 AWS Systems Manager User Guide
Working with Automation Documents

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteInstanceProfile",
"iam:PutRolePolicy",
"iam:DeleteRolePolicy"
],
"Resource": [
"arn:aws:iam::AWS_account_ID:role/AWSSupport/SetupIPMonitoringFromVPC_*",
"arn:aws:iam::AWS_account_ID:instance-profile/AWSSupport/
SetupIPMonitoringFromVPC_*"
],
"Effect": "Allow"
},
{
"Action": [
"iam:DetachRolePolicy",
"iam:AttachRolePolicy"
],
"Resource": [
"arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore"
],
"Effect": "Allow"
},
{
"Action": [
"cloudwatch:DeleteDashboards"
],
"Resource": [
"*"
],
"Effect": "Allow"
},
{
"Action": [
"ec2:AuthorizeSecurityGroupEgress",
"ec2:CreateSecurityGroup",
"ec2:DeleteSecurityGroup",
"ec2:DescribeSubnets"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}

Document Steps

1. aws:executeAwsApi - describe the provided subnet.

2. aws:branch - evaluate the TargetIPs input.

359
 AWS Systems Manager User Guide
Working with Automation Documents

(IPv6) If TargetIPs contains an IPv6:

aws:assertAwsResourceProperty - check the provided subnet has an IPv6 pool associated

3. aws:executeAwsApi - get the latest Amazon Linux 2 AMI from Parameter Store.
4. aws:executeAwsApi - create a security group for the test in the subnet's VPC.

(Cleanup) If the security group creation fails:

aws:executeAwsApi - delete the security group created by the automation, if it exists.

5. aws:executeAwsApi - allow all outbound traffic in the test security group.

(Cleanup) If the security group egress rule creation fails:

aws:executeAwsApi - delete the security group created by the automation, if it exists.

6. aws:executeAwsApi - create an IAM role for the test Amazon EC2 instance

(Cleanup) If the role creation fails:

a. aws:executeAwsApi - delete the IAM role created by the automation, if it exists.
b. aws:executeAwsApi - delete the security group created by the automation, if it exists.
7. aws:executeAwsApi - attach the AmazonSSMManagedInstanceCore managed policy

(Cleanup) If the policy attachment fails:

a. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation, if attached.
b. aws:executeAwsApi - delete the IAM role created by the automation.
c. aws:executeAwsApi - delete the security group created by the automation, if it exists.
8. aws:executeAwsApi - attach an inline policy to allow setting CloudWatch log group retentions and
creating a CloudWatch dashboard

(Cleanup) If the inline policy attachment fails:

a. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation,
if created.
b. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
c. aws:executeAwsApi - delete the IAM role created by the automation.
d. aws:executeAwsApi - delete the security group created by the automation, if it exists.
9. aws:executeAwsApi - create an IAM instance profile.

(Cleanup) If the instance profile creation fails:

a. aws:executeAwsApi - delete the IAM instance profile created by the automation, if it exists.
b. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
c. aws:executeAwsApi - delete the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
d. aws:executeAwsApi - delete the IAM role created by the automation.
e. aws:executeAwsApi - delete the security group created by the automation, if it exists.
10.aws:executeAwsApi - associate the IAM instance profile to the IAM role.

(Cleanup) If the instance profile and role association fails:

a. aws:executeAwsApi - remove the IAM instance profile from the role, if associated.
b. aws:executeAwsApi - delete the IAM instance profile created by the automation.
c. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
360
 AWS Systems Manager User Guide
Working with Automation Documents

d. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role

created by the automation.
e. aws:executeAwsApi - delete the IAM role created by the automation.
f. aws:executeAwsApi - delete the security group created by the automation, if it exists.
11.aws:sleep - wait for the instance profile to become available.
12.aws:runInstances - create the test instance in the specified subnet, and with the instance profile
created earlier attached.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
13.aws:branch - evaluate the TargetIPs input.

(IPv6) If TargetIPs contains an IPv6:

aws:executeAwsApi - assign an IPv6 to the test instance.

14.aws:waitForAwsResourceProperty - wait for the test instance to become a managed instance.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
15.aws:runCommand - install test pre-requisites:

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
16.aws:runCommand - validate the provided IPs are syntactically correct IPv4 and/or IPv6 addresses:

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.

361
 AWS Systems Manager User Guide
Working with Automation Documents

d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
17.aws:runCommand - define the MTR test for each of the provided IPs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
18.aws:runCommand - define the first ping test for each of the provided IPs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
19.aws:runCommand - define the second ping test for each of the provided IPs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
20.aws:runCommand - define the tracepath test for each of the provided IPs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.

362
 AWS Systems Manager User Guide
Working with Automation Documents

21.aws:runCommand - define the traceroute test for each of the provided IPs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
22.aws:runCommand - configure CloudWatch logs.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
23.aws:runCommand - schedule cronjobs to run each test every minute.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
24.aws:sleep - wait for the tests to generate some data.
25.aws:runCommand - set the desired CloudWatch log group retentions.

(Cleanup) If the step fails:

a. aws:changeInstanceState - terminate the test instance.
b. aws:executeAwsApi - remove the IAM instance profile from the role.
c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
26.aws:runCommand - set the CloudWatch log group metric filters.

(Cleanup) If the step fails: 363

a. aws:changeInstanceState - terminate the test instance.

 AWS Systems Manager User Guide
Working with Automation Documents

b. aws:executeAwsApi - remove the IAM instance profile from the role.

c. aws:executeAwsApi - delete the IAM instance profile created by the automation.
d. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
e. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
f. aws:executeAwsApi - delete the IAM role created by the automation.
g. aws:executeAwsApi - delete the security group created by the automation, if it exists.
27.aws:runCommand - create the CloudWatch dashboard.

(Cleanup) If the step fails:

a. aws:executeAwsApi - delete the CloudWatch dashboard, if it exists.
b. aws:changeInstanceState - terminate the test instance.
c. aws:executeAwsApi - remove the IAM instance profile from the role.
d. aws:executeAwsApi - delete the IAM instance profile created by the automation.
e. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
f. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
g. aws:executeAwsApi - delete the IAM role created by the automation.
h. aws:executeAwsApi - delete the security group created by the automation, if it exists.

Outputs

createCloudWatchDashboards.Output - the URL of the CloudWatch dashboard.

createManagedInstance.InstanceIds - the test instance ID.

AWS-SetupManagedInstance

Description

Configure an instance with an AWS Identity and Access Management (IAM) role for Systems Manager
access.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

364
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) ID of the Amazon EC2 instance to configure

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• RoleName

Type: String

Default: SSMRoleForManagedInstance

Description: (Optional) The name of the IAM role for the Amazon EC2 instance. If this role
does not exist, it will be created. When specifying this value, verify that the role contains the
AmazonSSMManagedInstanceCore Managed Policy.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-SetupManagedInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:executeAutomation

aws:runCommand

aws:executeAutomation

Outputs

None

AWS-SetupManagedRoleOnEC2Instance
Description

Configure an instance with the SSMRoleForManagedInstance managed IAM role for Systems Manager
access.

Document Type

Automation

Owner

Amazon

Platforms

365
 AWS Systems Manager User Guide
Working with Automation Documents

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

Description: (Required) ID of the Amazon EC2 instance to configure

• LambdaAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Lambda created by Automation to perform the
actions on your behalf. If not specified a transient role will be created to run the Lambda function.
• RoleName

Type: String

Default: SSMRoleForManagedInstance

Description: (Optional) The name of the IAM role for the Amazon EC2 instance. If this role
does not exist, it will be created. When specifying this value, verify that the role contains the
AmazonSSMManagedInstanceCore Managed Policy.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-SetupManagedRoleOnEc2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:invokeLambdaFunction

aws:invokeLambdaFunction

aws:deleteStack

Outputs

366
 AWS Systems Manager User Guide
Working with Automation Documents

None

AWSEC2-SQLServerDBRestore
Description

The AWSEC2-SQLServerDBRestore document restores Microsoft SQL Server database backups

stored in Amazon S3 to SQL Server 2017 running on an Amazon Elastic Compute Cloud (EC2) Linux
instance. You may provide your own EC2 instance running SQL Server 2017 Linux. If an EC2 instance is
not provided, the automation workflow launches and configures a new Ubuntu 16.04 EC2 instance with
SQL Server 2017. The automation supports restoring full, differential, and transactional log backups.
This automation accepts multiple database backup files and automatically restores the most recent valid
backup of each database in the files provided.

To automate both backup and restore of an on-premises SQL Server database to an

Amazon EC2 instance running SQL Server 2017 Linux, see the AWS-signed PowerShell script
MigrateSQLServerToEC2Linux.ps1.
Important
This automation workflow resets the SQL Server server administrator (SA) user password every
time the workflow runs. After the automation workflow is complete, you must set your own SA
user password again before you connect to the SQL Server instance.

Document Type

Automation

Owner

Amazon

Platforms

Linux

Prerequisites

• This Automation document only works with Linux EC2 instances running SQL Server.
• This Automation workflow must be run by a user with, at minimum, the permissions designated in the
Required IAM Permissions section below.
• If you are providing your own EC2 instance:
• Configure the EC2 instance with an AWS Identity and Access Management (IAM) instance profile that
has the AmazonSSMManagedInstanceCore managed policy attached. For more information, see
Create an IAM Instance Profile for Systems Manager (p. 29).
• Verify that SSM Agent is installed on your EC2 instance. For more information, see Installing and
Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68).
• Verify that the EC2 instance has enough free disk space to download and restore the SQL Server
backups.

Limitations

This automation does not support restoring to SQL Server running on EC2 Windows instances. This
automation only restores database backups that are compatible with SQL Server Linux 2017. For more
information, see Editions and Supported Features of SQL Server 2017 on Linux.

Required IAM Permissions

The user who runs the Automation workflow must have the following permissions:

367
 AWS Systems Manager User Guide
Working with Automation Documents

"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeImages",
"ec2:RunInstances",
"ec2:CreateTags",
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus",
"ec2:RebootInstances",
"ssm:SendCommand",
"ssm:GetAutomationExecution",
"ssm:ListCommands",
"ssm:StartAutomationExecution",
"ssm:DescribeInstanceInformation",
"ssm:ListCommandInvocations",
"iam:PassRole"
],
"Resource": "*"
}
]
}

Parameters

• S3Input

Type: String

Description: (Required) S3 bucket name, comma-separated list of S3 object keys, or comma-separated

list of pre-signed S3 URLs containing the SQL backup files to be restored.
• IsS3PresignedUrl

Type: String

Description: (Optional) If S3Input is a pre-signed S3 URL, indicate “yes”.

Default value: "no"

Allowed values: "yes", "no"

• InstanceId

Type: String

Description: (Optional) The instance running SQL Server 2017 on Linux. If no InstanceId is provided,
the automation launches a new Amazon EC2 instance using the InstanceType and SQLServerEdition
provided.
• InstanceType

Type: String

Description: (Optional) The instance type of the EC2 instance to be launched.

• SQLServerEdition

Type: String

Description: (Optional) The edition of SQL Server 2017 to be installed on the newly created EC2
instance.

Allowed values: "Standard", "Enterprise", "Web", "Express"

368
 AWS Systems Manager User Guide
Working with Automation Documents

• SubnetId

Type: String

Description: (Optional) The subnet in which to launch the new EC2 instance. The subnet must have
outbound connectivity to AWS services. If a value for SubnetId is not provided, the automation uses
the default subnet.
• IamInstanceProfileName

Type: String

Description: (Optional) The IAM instance profile to attach to the new EC2 instance. The IAM instance
profile must have the AmazonSSMManagedInstanceCore managed policy attached.
• DataDirectorySize

Type: String

Description: (Optional) Desired volume size (GiB) of the SQL Server Data directory for the new EC2
instance.

Default value: 100

• LogDirectorySize

Type: String

Description: (Optional) Desired volume size (GiB) of the SQL Server Log directory for the new EC2
instance.

Default value: 100

• TempDbDirectorySize

Type: String

Description: (Optional) Desired volume size (GiB) of the SQL Server TempDB directory for the new EC2
instance.

Default value: 100

• DatabaseNames

Type: String

Description: (Optional) Comma-separated list of the names of databases to restore.

• KeyPair

Type: String

Description: (Optional) Key pair to use when creating the new EC2 instance.

Examples

Start the automation using an existing EC2 instance with two databases.

aws ssm start-automation-execution --document-name AWSEC2-RestoreSQLServer --

parameters "InstanceId='i-1234567890abcdef0',S3Input='sample-bucket/sample-
prefix',DatabaseNames='sample-database1, sample-database2'"

Start the automation and launch a new EC2 instance with the specified SQL Server edition.

369
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm start-automation-execution --document-name AWSEC2-RestoreSQLServer --parameters

"InstanceType='m4.large',SQLServerEdition='Standard',S3Input='sample-bucket/sample-
backup-1.bak, sample-bucket/sample-backup-2.bak',IamInstanceProfileName='sample-profile-
name',KeyPair='sample-keypair-name'"

Start the automation and launch a new EC2 instance with the specified SQL Server edition using a
presigned S3 URL.

aws ssm start-automation-execution --document-name AWSEC2-RestoreSQLServer --parameters

"InstanceType='m4.large',SQLServerEdition='Standard',S3Input='https://sample-
bucket.s3.amazonaws.com/sample-backup.bak?
abcdefg',IsS3PresignedUrl='yes',IamInstanceProfileName='sample-profile-
name',DataDirectorySize=200,LogDirectorySize=100,TempDbDirectorySize=200"

Retrieve the execution output.

aws ssm get-automation-execution --automation-execution-id ExecutionID --output text --

query 'AutomationExecution.Output'

Document Steps

For new EC2 instances:

1. aws:executeAwsApi - Retrieve the AMI ID for SQL Server 2017 on Ubuntu 16.04.
2. aws:runInstances - Launch a new EC2 Linux instance.
3. aws:waitForAwsResourceProperty - Wait for the newly created EC2 instance to be ready.
4. aws:executeAwsApi - Reboot the instance if the instance is not ready.
5. aws:assertAwsResourceProperty - Verify that SSM Agent is installed.
6. aws:runCommand - Run the SQL Server restore script in PowerShell.

For existing EC2 instances:

1. aws:waitForAwsResourceProperty - Verify that the EC2 instance is ready.

2. aws:executeAwsApi - Reboot the instance if the instance is not ready.
3. aws:assertAwsResourceProperty - Verify that SSM Agent is installed.
4. aws:runCommand - Run the SQL Server restore script in PowerShell.

Outputs

getInstance.InstanceId

restoreToNewInstance.Output

restoreToExistingInstance.Output

AWS-StartEC2Instance

Description

Start one or more Amazon EC2 instances.

370
 AWS Systems Manager User Guide
Working with Automation Documents

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: StringList

Description: (Required) Amazon EC2 instance(s) to start.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-StartEC2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:changeInstanceState

Outputs

None

AWSSupport-StartEC2RescueWorkflow

Description

The AWSSupport-StartEC2RescueWorkflow automation document runs the provided base64 encoded

script (Bash or Powershell) on a helper instance created to rescue your instance. The root volume of
your instance is attached and mounted to the helper instance, also known as the EC2Rescue instance.
If your instance is Windows, provide a Powershell script. Otherwise, use Bash. The workflow sets some
environment variables which you can use in your script. The environment variables contain information

371
 AWS Systems Manager User Guide
Working with Automation Documents

about the input you provided, as well as information about the offline root volume. The offline volume
is already mounted and ready to use. For example, you can save a Desired State Configuration file
to an offline Windows root volume, or chroot to an offline Linux root volume and perform an offline
remediation.

Additional Information

To base64 encode a script, you can use either Powershell or Bash. Powershell:

[System.Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes([System.IO.File]::ReadAllText

Bash:

base64 PATH_TO_FILE

Here is a list of environment variables you can use in your offline scripts, depending on the target OS

Windows:

Variable Description Example value

$env:EC2RESCUE_ACCOUNT_ID {{ global:ACCOUNT_ID }} 123456789012

$env:EC2RESCUE_DATE {{ global:DATE }} 2018-09-07

$env:EC2RESCUE_DATE_TIME {{ global:DATE_TIME }} 2018-09-07_18.09.59

$env:EC2RESCUE_EC2RW_DIR EC2Rescue for Windows C:\Program Files\Amazon

installation path \EC2Rescue

$env:EC2RESCUE_EC2RW_DIR EC2Rescue for Windows C:\Program Files\Amazon

installation path \EC2Rescue

$env:EC2RESCUE_EXECUTION_ID {{ automation:EXECUTION_ID }} 7ef8008e-219b-4aca-8bb5-65e2e898e20b

$env:EC2RESCUE_OFFLINE_CURRENT_CONTROL_SET
Offline Windows Current Control HKLM:\AWSTempSystem
Set path \ControlSet001

$env:EC2RESCUE_OFFLINE_DRIVE Offline Windows drive letter D:\

$env:EC2RESCUE_OFFLINE_EBS_DEVICE
Offline root volume EBS device xvdf

$env:EC2RESCUE_OFFLINE_KERNEL_VER
Offline Windows Kernel version 6.1.7601.24214

$env:EC2RESCUE_OFFLINE_OS_ARCHITECTURE
Offline Windows architecture AMD64

$env:EC2RESCUE_OFFLINE_OS_CAPTION
Offline Windows caption Windows Server 2008 R2
Datacenter

$env:EC2RESCUE_OFFLINE_OS_TYPE
Offline Windows OS type Server

$env:EC2RESCUE_OFFLINE_PROGRAM_FILES_DIR
Offline Windows Program files D:\Program Files
directory path

$env:EC2RESCUE_OFFLINE_PROGRAM_FILES_X86_DIR
Offline Windows Program files D:\Program Files (x86)
x86 directory path

$env:EC2RESCUE_OFFLINE_REGISTRY_DIR
Offline Windows registry D:\Windows\System32\config
directory path

372
 AWS Systems Manager User Guide
Working with Automation Documents

Variable Description Example value

$env:EC2RESCUE_OFFLINE_SYSTEM_ROOT
Offline Windows system root D:\Windows
directory path

$env:EC2RESCUE_REGION {{ global:REGION }} us-west-1

$env:EC2RESCUE_S3_BUCKET {{ S3BucketName }} mybucket

$env:EC2RESCUE_S3_PREFIX {{ S3Prefix }} myprefix/

$env:EC2RESCUE_SOURCE_INSTANCE
{{ InstanceId }} i-abcdefgh123456789

$script:EC2RESCUE_OFFLINE_WINDOWS_INSTALL
Offline Windows Installation Customer Powershell Object
metadata

Linux:

Variable Description Example value

EC2RESCUE_ACCOUNT_ID {{ global:ACCOUNT_ID }} 123456789012

EC2RESCUE_DATE {{ global:DATE }} 2018-09-07

EC2RESCUE_DATE_TIME {{ global:DATE_TIME }} 2018-09-07_18.09.59

EC2RESCUE_EC2RL_DIR EC2Rescue for Linux installation /usr/local/ec2rl-1.1.3

path

EC2RESCUE_EXECUTION_ID {{ automation:EXECUTION_ID }} 7ef8008e-219b-4aca-8bb5-65e2e898e20b

EC2RESCUE_OFFLINE_DEVICE Offline device name /dev/xvdf1

EC2RESCUE_OFFLINE_EBS_DEVICEOffline root volume EBS device /dev/sdf

EC2RESCUE_OFFLINE_SYSTEM_ROOT
Offline root volume mount point /mnt/mount

EC2RESCUE_PYTHON Python version python2.7

EC2RESCUE_REGION {{ global:REGION }} us-west-1

EC2RESCUE_S3_BUCKET {{ S3BucketName }} mybucket

EC2RESCUE_S3_PREFIX {{ S3Prefix }} myprefix/

EC2RESCUE_SOURCE_INSTANCE {{ InstanceId }} i-abcdefgh123456789

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

373
 AWS Systems Manager User Guide
Working with Automation Documents

• InstanceId

Type: String

Description: (Required) ID of your EC2 instance. IMPORTANT: AWS Systems Manager Automation stops
this instance. Data stored in instance store volumes will be lost. The public IP address will change if
you are not using an Elastic IP.
• OfflineScript

Type: String

Description: (Required) Base64 encoded script to run against the helper instance. Use Bash if your
source instance is Linux, and PowerShell if it is Windows.
• EC2RescueInstanceType

Type: String

Allowed values: t2.small,t2.medium,t2.large

Default: t2.small

Description: (Optional) The EC2 instance type for the EC2Rescue instance.
• SubnetId

Type: String

Default: SelectedInstanceSubnet

Description: (Optional) The subnet ID for the EC2Rescue instance. By default, the same subnet where
the provided instance resides is used. IMPORTANT: If you provide a custom subnet, it must be in the
same Availability Zone as InstanceId, and it must allow access to the SSM endpoints.
• S3BucketName

Type: String

Description: (Optional) S3 bucket name in your account where you want to upload the troubleshooting
logs. Make sure the bucket policy does not grant unnecessary read/write permissions to parties that do
not need access to the collected logs.
• S3Prefix

Type: String

Default: AWSSupport-EC2Rescue

Description: (Optional) A prefix for the S3 logs.

• AMIPrefix

Type: String

Default: AWSSupport-EC2Rescue

Description: (Optional) A prefix for the backup AMI name.

• CreatePreEC2RescueBackup

Type: String

Allowed values: True,False

Default: False

374
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) Set it to True to create an AMI of InstanceId before running the script. The AMI
will persist after the automation completes. It is your responsibility to secure access to the AMI, or to
delete it.
• CreatePostEC2RescueBackup

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Set it to True to create an AMI of InstanceId after running the script, before
starting it. The AMI will persist after the automation completes. It is your responsibility to secure
access to the AMI, or to delete it.
• UniqueId

Type: String

Default: {{ automation:EXECUTION_ID }}

Description: (Optional) A unique identifier for the workflow.

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this
document.

Examples

Print environment variables on a Windows helper instance

aws ssm start-automation-execution --document-name "AWSSupport-StartEC2RescueWorkflow" --

parameters
"InstanceId=WINDOWSINSTANCEID,OfflineScript=R2V0LUNoaWxkSXRlbSBlbnY6KiB8IFNvcnQtT2JqZWN0IE5hbWU="

Print environment variables on a Linux helper instance

aws ssm start-automation-execution --document-name "AWSSupport-StartEC2RescueWorkflow" --

parameters "InstanceId=LINUXINSTANCEID,OfflineScript=IyEvYmluL2Jhc2gKcHJpbnRlbnYgfCBzb3J0"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended the user who runs the automation have the AmazonSSMAutomationRole IAM
managed policy attached. In addition to that policy, the user must have:

{
"Version": "2012-10-17",
"Statement": [

375
 AWS Systems Manager User Guide
Working with Automation Documents

{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:An-AWS-Account-
ID:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::An-AWS-Account-ID:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::An-AWS-Account-ID:instance-profile/AWSSupport-
EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"

376
 AWS Systems Manager User Guide
Working with Automation Documents

],
"Resource": "*",
"Effect": "Allow"
}
]
}

Document Steps

1. aws:executeAwsApi - Describe the provided instance

2. aws:executeAwsApi - Describe the provided instance's root volume
3. aws:assertAwsResourceProperty - Check the root volume device type is EBS
4. aws:assertAwsResourceProperty - Check the root volume is not encrypted
5. aws:assertAwsResourceProperty - Check the provide subnet ID
a. (Use current instance subnet) - If *SubnetId = SelectedInstanceSubnet* then run aws:createStack to
deploy the EC2Rescue CloudFormation stack
b. (Create new VPC) - If *SubnetId = CreateNewVPC* then run aws:createStack to deploy the
EC2Rescue CloudFormation stack
c. (Use custom subnet) - In all other cases:

aws:assertAwsResourceProperty - Check the provided subnet is in the same Availability Zone as the
provided instance

aws:createStack - Deploy the EC2Rescue CloudFormation stack

6. aws:invokeLambdaFunction - Perfom additional input validation
7. aws:executeAwsApi - Update the EC2Rescue CloudFormation stack to create the EC2Rescue helper
instance
8. aws:waitForAwsResourceProperty - Wait for the EC2Rescue CloudFormation stack update to complete
9. aws:executeAwsApi - Describe the EC2Rescue CloudFormation stack output to obtain the EC2Rescue
helper instance ID
10.aws:waitForAwsResourceProperty - Wait for the EC2Rescue helper instance to become a managed
instance
11.aws:changeInstanceState - Stop the provided instance
12.aws:changeInstanceState - Stop the provided instance
13.aws:changeInstanceState - Force stop the provided instance
14.aws:assertAwsResourceProperty - Check the CreatePreEC2RescueBackup input value
a. (Create pre-EC2Rescue backup) - If *CreatePreEC2RescueBackup = True*
b. aws:executeAwsApi - Create an AMI backup of the provided instance
c. aws:createTags - Tag the AMI backup
15.aws:runCommand - Install EC2Rescue on the EC2Rescue helper instance
16.aws:executeAwsApi - Detach the root volume from the provided instance
17.aws:assertAwsResourceProperty - Check the provided instance platform
a. (Instance is Windows):

aws:executeAwsApi - Attach the root volume to the EC2Rescue helper instance as *xvdf*

aws:sleep - Sleep 10 seconds

aws:runCommand - Run the provided offline script in Powershell

b. (Instance is Linux):

aws:executeAwsApi - Attach the root volume to the EC2Rescue helper instance as */dev/sdf*

377
 AWS Systems Manager User Guide
Working with Automation Documents

aws:sleep - Sleep 10 seconds

aws:runCommand - Run the provided offline script in Bash

18.aws:changeInstanceState - Stop the EC2Rescue helper instance
19.aws:changeInstanceState - Force stop the EC2Rescue helper instance
20.aws:executeAwsApi - Detach the root volume from the EC2Rescue helper instance
21.aws:executeAwsApi - Attach the root volume back to the provided instance
22.aws:assertAwsResourceProperty - Check the CreatePostEC2RescueBackup input value
a. (Create post-EC2Rescue backup) - If *CreatePostEC2RescueBackup = True*
b. aws:executeAwsApi - Create an AMI backup of the provided instance
c. aws:createTags - Tag the AMI backup
23.aws:executeAwsApi - Restore the initial delete on termination state for the root volume of the
provided instance
24.aws:changeInstanceState - Restore the initial state of the provided instance (running/stopped)
25.aws:deleteStack - Delete the EC2Rescue CloudFormation stack

Outputs

runScriptForLinux.Output

runScriptForWindows.Output

preScriptBackup.ImageId

postScriptBackup.ImageId

AWS-StartRDSInstance

Description

Start an Amazon Relational Database Service (Amazon RDS) instance.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

378
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) ID of the Amazon RDS instance to start.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-StartRdsInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:assertAwsResourceProperty

aws:executeAwsApi

aws:waitForAwsResourceProperty

Outputs

None

AWS-StopEC2Instance

Description

Stop one or more Amazon EC2 instances.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: StringList

379
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) IDs of one or more Amazon EC2 instances to stop

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-StopEC2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:changeInstanceState

aws:changeInstanceState

Outputs

None

AWS-StopRDSInstance

Description

Stop an Amazon Relational Database Service (Amazon RDS) instance. This document calls the
StopDBInstance API action. The StopDBInstance API doesn't apply to Aurora MySQL and Aurora
PostgreSQL. For Aurora clusters, you must use the StopDBCluster API action instead.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: String

380
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) ID of the Amazon RDS instance to stop.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-StopRdsInstance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:assertAwsResourceProperty

aws:executeAwsApi

aws:waitForAwsResourceProperty

Outputs

None

AWS-TerminateEC2Instance

Description

Terminate one or more Amazon EC2 instances.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• InstanceId

Type: StringList

Description: (Required) IDs of one or more Amazon EC2 instances to terminate.

381
 AWS Systems Manager User Guide
Working with Automation Documents

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-TerminateEC2Instance --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:changeInstanceState

Outputs

None

AWSSupport-TerminateIPMonitoringFromVPC

Description

AWSSupport-TerminateIPMonitoringFromVPC terminates an IP monitoring test previously started by

AWSSupport-SetupIPMonitoringFromVPC. Data related to the specified test ID will be deleted.

Document Type

Automation

Owner

Amazon

Parameters

• AutomationExecutionId

Type: String

Description: (Required) AWSSupport-SetupIPMonitoringFromVPC automation execution ID of the test

you want to terminate.
• SubnetId

Type: String

Description: (Required) The subnet ID for the monitor instance.

• InstanceId

Type: String

Description: (Required) The instance ID for the monitor instance.

• AutomationAssumeRole

Type: String

382
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Start the automation

aws ssm start-automation-execution --document-name

AWSSupportTest-TerminateIPMonitoringFromVPC --parameters
'AutomationExecutionId=ID,SubnetId=ID,InstanceId=ID,'

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id ID --output text --query

'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the user who runs the automation have the AmazonSSMAutomationRole IAM
managed policy attached. In addition, the user must have the following policy attached to their user
account, group, or role:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"iam:DetachRolePolicy",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteInstanceProfile",
"iam:DeleteRolePolicy"
],
"Resource": [
"arn:aws:iam::An-AWS-Account-ID:role/AWSSupport/SetupIPMonitoringFromVPC_*",
"arn:aws:iam::An-AWS-Account-ID:instance-profile/AWSSupport/
SetupIPMonitoringFromVPC_*"
],
"Effect": "Allow"
},
{
"Action": [
"iam:DetachRolePolicy"
],
"Resource": [
"arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore"
],
"Effect": "Allow"
},
{
"Action": [
"cloudwatch:DeleteDashboards"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}

383
 AWS Systems Manager User Guide
Working with Automation Documents

Document Steps

1. aws:assertAwsResourceProperty - check AutomationExecutionId and InstanceId are related to the

same test.
2. aws:assertAwsResourceProperty - check SubnetId and InstanceId are related to the same test.
3. aws:executeAwsApi - retrieve the test security group.
4. aws:executeAwsApi - delete the CloudWatch dashboard.
5. aws:changeInstanceState - terminate the test instance.
6. aws:executeAwsApi - remove the IAM instance profile from the role.
7. aws:executeAwsApi - delete the IAM instance profile created by the automation.
8. aws:executeAwsApi - delete the CloudWatch inline policy from the role created by the automation.
9. aws:executeAwsApi - detach the AmazonSSMManagedInstanceCore managed policy from the role
created by the automation.
10.aws:executeAwsApi - delete the IAM role created by the automation.
11.aws:executeAwsApi - delete the security group created by the automation, if it exists.

Outputs

None

AWSSupport-TroubleshootRDP

Description

The AWSSupport-TroubleshootRDP automation document allows the user to check or modify common
settings on the target instance which may impact Remote Desktop Protocol (RDP) connections, such as
the RDP port, Network Layer Authentication (NLA) and Windows Firewall profiles. Optionally, changes
can be applied offline by stopping and starting the instance, if the user explicitly allows for offline
remediation. By default, the document reads and outputs the values of the settings.
Important
Changes to the RDP settings, RDP service and Windows Firewall profiles should be carefully
reviewed before running this document.

Document Type

Automation

Owner

Amazon

Platforms

Windows

Parameters

• InstanceId

Type: String

Description: (Required) The ID of the instance to troubleshoot the RDP settings of.
• Action

Type: String

384
 AWS Systems Manager User Guide
Working with Automation Documents

Allowed values: CheckAll,FixAll,Custom

Default: Custom

Description: (Optional) [Custom] Use the values from Firewall, RDPServiceStartupType,

RDPServiceAction, RDPPortAction, NLASettingAction and RemoteConnections to manage the settings.
[CheckAll] Read the values of the settings without changing them. [FixAll] Restore RDP default
settings, and disable the Windows Firewall.
• AllowOffline

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Fix only - Set it to true if you allow an offline RDP remediation in case the
online troubleshooting fails, or the provided instance is not a managed instance. Note: For the
offline remediation, SSM Automation stops the instance, and creates an AMI before attempting any
operations.
• Firewall

Type: String

Allowed values: Check,Disable

Default: Check

Description: (Optional) Check or disable the Windows firewall (all profiles).

• RDPServiceAction

Type: String

Allowed values: Check,Start,Restart,Force-Restart

Default: Check

Description: (Optional) Check, start, restart, or force-restart the RDP service (TermService).
• RDPServiceStartupType

Type: String

Allowed values: Check,Auto

Default: Check

Description: (Optional) Check or set the RDP service to automatically start when Windows boots.
• RDPPortAction

Type: String

Allowed values: Check,Modify

Default: Check

Description: (Optional) Check the current port used for RDP connections, or modify the RDP port back
to 3389 and restart the service.
• NLASettingAction
385
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Allowed values: Check,Disable

Default: Check

Description: (Optional) Check or disable Network Layer Authentication (NLA).

• RemoteConnections

Type: String

Allowed values: Check,Enable

Default: Check

Description: (Optional) An action to perform on the fDenyTSConnections setting: Check, Enable.

• SubnetId

Type: String

Default: SelectedInstanceSubnet

Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the
offline troubleshooting. If no subnet ID is specified, AWS Systems Manager Automation will create a
new VPC. IMPORTANT: The subnet must be in the same Availability Zone as InstanceId, and it must
allow access to the SSM endpoints.
• S3BucketName

Type: String

Description: (Optional) Offline only - S3 bucket name in your account where you want to upload the
troubleshooting logs. Make sure the bucket policy does not grant unnecessary read/write permissions
to parties that do not need access to the collected logs.
• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, AWS Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Check the current RDP status

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID"

Check the current RDP status

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID"

Disable the Windows firewall

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID,Action=Custom,Firewall=Disable"

386
 AWS Systems Manager User Guide
Working with Automation Documents

Restore the default RDP port

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID, RDPPortAction=Modify"

Disable NLA

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID, NLASettingAction=Disable"

Allow remote connections

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID, RemoteConnections=Allow"

Restore RDP default settings and disable all Windows Firewall profiles

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID, Action=FixAll"

Restore RDP default settings and disable all Windows Firewall profiles, with offline remediation if needed

aws ssm start-automation-execution --document-name "AWSSupport-TroubleshootRDP" --

parameters "InstanceId=INSTANCEID, Action=FixAll, AllowOffline=True"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. For the online remediation,
the user must have at least ssm:DescribeInstanceInformation, ssm:ExecuteAutomation
and ssm:SendCommand to run the automation and send the command to the instance, plus
ssm:GetAutomationExecution to be able to read the automation output. For the offline remediation,
the user must have at least ssm:DescribeInstanceInformation, ssm:ExecuteAutomation,
ec2:DescribeInstances, plus ssm:GetAutomationExecution to be able to read the automation
output. AWSSupport-TroubleshootRDP calls AWSSupport-ExecuteEC2Rescue to perform the offline
remediation - please review the permissions for AWSSupport-ExecuteEC2Rescue to ensure you can run
the automation successfully.

Document Steps

1. aws:assertAwsResourceProperty - Check if the instance is a Windows instance

2. aws:assertAwsResourceProperty - Check if the instance is a managed instance
3. (Online troubleshooting) If the instance is a managed instance, then:
a. aws:assertAwsResourceProperty - Check the provided Action value
b. (Online check) If the Action = CheckAll, then:

aws:runPowerShellScript - Runs the PowerShell script to get the Windows Firewall profiles status.

aws:executeAutomation - Calls AWSSupport-ManageWindowsService to get the RDP service status.

387
 AWS Systems Manager User Guide
Working with Automation Documents

aws:executeAutomation - Calls AWSSupport-ManageRDPSettings to get the RDP settings.

c. (Online fix) If the Action = FixAll, then:

aws:runPowerShellScript - Runs the PowerShell script to disable all Windows Firewall profiles.

aws:executeAutomation - Calls AWSSupport-ManageWindowsService to start the RDP service.

aws:executeAutomation - Calls AWSSupport-ManageRDPSettings to enable remote connections

and disable NLA.
d. (Online management) If the Action = Custom, then:

aws:runPowerShellScript - Runs the PowerShell script to manage the Windows Firewall profiles.

aws:executeAutomation - Calls AWSSupport-ManageWindowsService to manage the RDP service.

aws:executeAutomation - Calls AWSSupport-ManageRDPSettings to manage the RDP settings.

4. (Offline remediation) If the instance is not a managed instance then:
a. aws:assertAwsResourceProperty - Assert AllowOffline = True
b. aws:assertAwsResourceProperty - Assert Action = FixAll
c. aws:assertAwsResourceProperty - Assert the value of SubnetId

(Use the provided instance's subnet) If SubnetId is SELECTED_INSTANCE_SUBNET

aws:executeAwsApi - Retrieve the current instance's subnet.

aws:executeAutomation - Run AWSSupport-ExecuteEC2Rescue with provided instance's subnet.

d. (Use the provided custom subnet) If SubnetId is not SELECTED_INSTANCE_SUBNET

aws:executeAutomation - Run AWSSupport-ExecuteEC2Rescue with provided SubnetId value.

Outputs

manageFirewallProfiles.Output

manageRDPServiceSettings.Output

manageRDPSettings.Output

checkFirewallProfiles.Output

checkRDPServiceSettings.Output

checkRDPSettings.Output

disableFirewallProfiles.Output

restoreDefaultRDPServiceSettings.Output

restoreDefaultRDPSettings.Output

troubleshootRDPOffline.Output

troubleshootRDPOfflineWithSubnetId.Output

AWSSupport-TroubleshootSSH

Description

388
 AWS Systems Manager User Guide
Working with Automation Documents

The AWSSupport-TroubleshootSSH automation document installs the Amazon EC2Rescue tool for Linux,
and then uses the EC2Rescue tool to check or attempt to fix common issues that prevent a remote
connection to the Linux machine via SSH. Optionally, changes can be applied offline by stopping and
starting the instance, if the user explicitly allows for offline remediation. By default, the document
operates in read-only mode.

Document Type

Automation

Owner

Amazon

Platforms

Linux

Parameters

• InstanceId

Type: String

Description: (Required) ID of your EC2 Linux instance.

• Action

Type: String

Allowed values: CheckAll,FixAll

Default: CheckAll

Description: (Required) Specify whether to check for issues without fixing them or to check and
automatically fix any discovered issues.
• AllowOffline

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Fix only - Set it to true if you allow an offline SSH remediation in case the
online troubleshooting fails, or the provided instance is not a managed instance. Note: For the
offline remediation, SSM Automation stops the instance, and creates an AMI before attempting any
operations.
• SubnetId

Type: String

Default: SelectedInstanceSubnet

Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the
offline troubleshooting. If no subnet ID is specified, AWS Systems Manager Automation will create a
new VPC.
Important
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to
the SSM endpoints.

389
 AWS Systems Manager User Guide
Working with Automation Documents

• S3BucketName

Type: String

Description: (Optional) Offline only - S3 bucket name in your account where you want to upload the
troubleshooting logs. Make sure the bucket policy does not grant unnecessary read/write permissions
to parties that do not need access to the collected logs.
• AutomationAssumeRole

Type: String

Description: (Optional) The IAM role for this execution. If no role is specified, Systems Manager
Automation will use the permissions of the user that runs this document.

Examples

Check the current SSH status

aws ssm start-automation-execution --document-name AWSSupport-TroubleshootSSH --parameters

"InstanceId=INSTANCEID"

Perform an online fix of all detected SSH issues

aws ssm start-automation-execution --document-name AWSSupport-TroubleshootSSH --parameters

"InstanceId=INSTANCEID,Action=FixAll"

Perform an offline fix of all detected SSH issues

aws ssm start-automation-execution --document-name AWSSupport-TroubleshootSSH --parameters

"InstanceId=INSTANCEID,Action=FixAll,AllowOffline=True"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. For the online remediation,
the user must have at least ssm:DescribeInstanceInformation, ssm:ExecuteAutomation
and ssm:SendCommand to run the automation and send the command to the instance, plus
ssm:GetAutomationExecution to be able to read the automation output. For the offline remediation,
the user must have at least ssm:DescribeInstanceInformation, ssm:ExecuteAutomation,
ec2:DescribeInstances, plus ssm:GetAutomationExecution to be able to read the automation
output. AWSSupport-TroubleshootSSH calls AWSSupport-ExecuteEC2Rescue to perform the offline
remediation - please review the permissions for AWSSupport-ExecuteEC2Rescue to ensure you can run
the automation successfully.

Document Steps

1. aws:assertAwsResourceProperty - Check if the instance is a managed instance

a. (Online remediation) If the instance is a managed instance, then:
i. aws:configurePackage - Install EC2Rescue for Linux via AWS-ConfigureAWSPackage.
ii. aws:runCommand - Run the bash script to run EC2Rescue for Linux.

390
 AWS Systems Manager User Guide
Working with Automation Documents

b. (Offline remediation) If the instance is not a managed instance then:

i. aws:assertAwsResourceProperty - Assert AllowOffline = True
ii. aws:assertAwsResourceProperty - Assert Action = FixAll
iii. aws:assertAwsResourceProperty - Assert the value of SubnetId
iv. (Use the provided instance's subnet) If SubnetId is SelectedInstanceSubnet us
aws:executeAutomation to run AWSSupport-ExecuteEC2Rescue with provided instance's subnet.
v. (Use the provided custom subnet) If SubnetId is not SelectedInstanceSubnet use
aws:executeAutomation to run AWSSupport-ExecuteEC2Rescue with provided SubnetId value.

Outputs

troubleshootSSH.Output

troubleshootSSHOffline.Output

troubleshootSSHOfflineWithSubnetId.Output

AWS-UpdateCloudFormationStack

Description

Update an AWS CloudFormation stack by using an AWS CloudFormation template stored in an Amazon
S3 bucket.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf.
• LambdaAssumeRole

Type: String

Description: (Required) The ARN of the role assumed by Lambda

• StackNameOrId

Type: String

Description: (Required) Name or Unique ID of the AWS CloudFormation stack to be updated

• TemplateUrl

Type: String

391
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) Amazon S3 bucket location that contains the updated CloudFormation
template (e.g. https://s3.amazonaws.com/example/updated.template)

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-UpdateCloudFormationStack --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:createStack

aws:invokeLambdaFunction

aws:deleteStack

Outputs

None

AWS-UpdateLinuxAmi

Description

Update an Amazon Machine Image (AMI) with Linux distribution packages and Amazon software.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Default: arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole

Description: (Required) The ARN of the role that allows Automation to perform the actions on your
behalf.
• ExcludePackages

392
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Default: none

Description: (Optional) Names of packages to hold back from updates, under all conditions. By default
("none"), no package is excluded.
• IamInstanceProfileName

Type: String

Default: ManagedInstanceProfile

Description: (Required) The instance profile that enables Systems Manager to manage the instance.
• IncludePackages

Type: String

Default: all

Description: (Optional) Only update these named packages. By default ("all"), all available updates are
applied.
• InstanceType

Type: String

Default: t2.micro

Description: (Optional) Type of instance to launch as the workspace host. Instance types vary by
Region.
• PostUpdateScript

Type: String

Default: none

Description: (Optional) URL of a script to run after package updates are applied. Default ("none") is to
not run a script.
• PreUpdateScript

Type: String

Default: none

Description: (Optional) URL of a script to run before updates are applied. Default ("none") is to not run
a script.
• SourceAmiId

Type: String

Description: (Required) The source Amazon Machine Image ID.

• TargetAmiName

Type: String

Default: UpdateLinuxAmi_from_{{SourceAmiId}}_on_{{global:DATE_TIME}}

Description: (Optional) The name of the new AMI that will be created. Default is a system-generated
string including the source AMI id, and the creation time and date.

393
 AWS Systems Manager User Guide
Working with Automation Documents

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-UpdateLinuxAmi --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

aws:runInstances

aws:runCommand

aws:runCommand

aws:changeInstanceState

aws:createImage

aws:changeInstanceState

Outputs

createImage.ImageId

AWS-UpdateWindowsAmi

Description

Update a Microsoft Windows Amazon Machine Image (AMI). By default, this document installs all
Windows updates, Amazon software, and Amazon drivers. It then runs Sysprep to create a new AMI.
Supports Windows Server 2008 R2 or later.

Document Type

Automation

Owner

Amazon

Platforms

Windows, Linux

Parameters

• AutomationAssumeRole

Type: String

Default: arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole

394
 AWS Systems Manager User Guide
Working with Automation Documents

Description: (Required) The ARN of the role that allows Automation to perform the actions on your
behalf.
• Categories

Type: String

Description: (Optional) Specify one or more update categories. You can filter categories using comma-
separated values. Options: Application, Connectors, CriticalUpdates, DefinitionUpdates, DeveloperKits,
Drivers, FeaturePacks, Guidance, Microsoft, SecurityUpdates, ServicePacks, Tools, UpdateRollups,
Updates. Valid formats include a single entry, for example: CriticalUpdates. Or you can specify a
comma separated list: CriticalUpdates,SecurityUpdates. NOTE: There cannot be any spaces around the
commas.
• ExcludeKbs

Type: String

Description: (Optional) Specify one or more Microsoft Knowledge Base (KB) article IDs to exclude. You
can exclude multiple IDs using comma-separated values. Valid formats: KB9876543 or 9876543.
• IamInstanceProfileName

Type: String

Default: ManagedInstanceProfile

Description: (Required) The name of the role that enables Systems Manager to manage the instance.
• IncludeKbs

Type: String

Description: (Optional) Specify one or more Microsoft Knowledge Base (KB) article IDs to include. You
can install multiple IDs using comma-separated values. Valid formats: KB9876543 or 9876543.
• InstanceType

Type: String

Default: t2.medium

Description: (Optional) Type of instance to launch as the workspace host. Instance types vary by
region. Default is t2.medium.
• PostUpdateScript

Type: String

Description: (Optional) A script provided as a string. It will run after installing OS updates.
• PreUpdateScript

Type: String

Description: (Optional) A script provided as a string. It will run prior to installing OS updates.
• PublishedDateAfter

Type: String

Description: (Optional) Specify the date that the updates should be published after. For example, if
01/01/2017 is specified, any updates that were found during the Windows Update search that have
been published on or after 01/01/2017 will be returned.
• PublishedDateBefore

395
 AWS Systems Manager User Guide
Working with Automation Documents

Type: String

Description: (Optional) Specify the date that the updates should be published before. For example, if
01/01/2017 is specified, any updates that were found during the Windows Update search that have
been published on or before 01/01/2017 will be returned.
• PublishedDaysOld

Type: String

Description: (Optional) Specify the amount of days old the updates must be from the published date.
For example, if 10 is specified, any updates that were found during the Windows Update search that
have been published 10 or more days ago will be returned.
• SeverityLevels

Type: String

Description: (Optional) Specify one or more MSRC severity levels associated with an update. You
can filter severity levels using comma-separated values. By default patches for all security levels are
selected. If value supplied, the update list is filtered by those values. Options: Critical, Important, Low,
Moderate or Unspecified. Valid formats include a single entry, for example: Critical. Or, you can specify
a comma separated list: Critical,Important,Low.
• SourceAmiId

Type: String

Description: (Required) The source Amazon Machine Image ID.

• SubnetId

Type: String

Description: (Optional) Specify the SubnetId if you want to launch into a specific subnet.
• TargetAmiName

Type: String

Default: UpdateWindowsAmi_from_{{SourceAmiId}}_on_{{global:DATE_TIME}}

Description: (Optional) The name of the new AMI that will be created. Default is a system-generated
string including the source AMI id, and the creation time and date.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWS-UpdateWindowsAmi --

parameters parameters

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Document Steps

396
 AWS Systems Manager User Guide
Working with Automation Documents

aws:runInstances

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:runCommand

aws:changeInstanceState

aws:createImage

aws:changeInstanceState

Outputs

CreateImage.ImageId

AWSSupport-UpgradeWindowsAWSDrivers

Description

The AWSSupport-UpgradeWindowsAWSDrivers upgrades or repairs storage and network AWS drivers on

the specified Amazon EC2 instance. The document attempts to install the latest versions of AWS drivers
online by calling SSM Agent. If SSM Agent is not contactable, the document can perform an offline
installation of the AWS drivers if explicitly requested. Note: Both the online and offline upgrade will
create an AMI before attempting any operations, which will persist after the automation completes. It is
your responsibility to secure access to the AMI, or to delete it. The online method restarts the instance
as part of the upgrade process, while the offline method requires the provided Amazon EC2 instance be
stopped and then started.
Note
This document will fail on a domain controller. To update AWS PV drivers on a domain
controller, see Upgrade a Domain Controller (AWS PV Upgrade).

Document Type

Automation

Owner

Amazon

Platforms

Windows

397
 AWS Systems Manager User Guide
Working with Automation Documents

Parameters

• InstanceId

Type: String

Description: (Required) ID of your Amazon EC2 Windows instance.

• AllowOffline

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Set it to true if you allow an offline drivers upgrade in case the online
installation cannot be performed. Note: The offline method requires the provided EC2 instance be
stopped and then started. Data stored in instance store volumes will be lost. The public IP address will
change if you are not using an Elastic IP.
• SubnetId

Type: String

Default: SelectedInstanceSubnet

Description: (Optional) Offline only - The subnet ID for the EC2Rescue instance used to perform the
offline drivers upgrade. If no subnet ID is specified, Systems Manager Automation will create a new
VPC.
Important
The subnet must be in the same Availability Zone as InstanceId, and it must allow access to
the SSM endpoints.
• ForceUpgrade

Type: String

Allowed values: True,False

Default: False

Description: (Optional) Offline only - Set it to true if you allow the offline drivers upgrade to proceed
even though your instance already has the latest drivers installed.
• AutomationAssumeRole

Type: String

Description: (Optional) The ARN of the role that allows Automation to perform the actions on your
behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this
document.

Examples

Start the automation

aws ssm start-automation-execution --document-name AWSSupport-UpgradeWindowsAWSDrivers --

parameters "InstanceId=INSTANCEID"

Start the automation and allow an offline upgrade

398
 AWS Systems Manager User Guide
Working with Automation Documents

aws ssm start-automation-execution --document-name AWSSupport-UpgradeWindowsAWSDrivers --

parameters "InstanceId=INSTANCEID,AllowOffline=True"

Retrieve the execution output

aws ssm get-automation-execution --automation-execution-id EXECUTIONID --output text --

query 'AutomationExecution.Output'

Required IAM Permissions

It is recommended that the EC2 instance receiving the command has an IAM role with the
AmazonSSMManagedInstanceCore Amazon managed policy attached. You must have at
least ssm:ExecuteAutomation and ssm:SendCommand to run the automation and send the
command to the instance, plus ssm:GetAutomationExecution to be able to read the automation
output. If you are performing an offline upgrade, see the permissions required by AWSSupport-
StartEC2RescueWorkflow (p. 371).

Document Steps

1. aws:assertAwsResourceProperty - Verifies the input instance is Windows.

2. aws:assertAwsResourceProperty - Verifies the input instance is a managed instance. If so, the online
upgrade starts, otherwise the offline upgrade is evaluated.
a. (Online upgrade) If the input instance is a managed instance:
i. aws:createImage - Creates an AMI backup.
ii. aws:createTags - Tags the AMI backup.
iii. aws:runCommand - Installs ENA network driver via AWS-ConfigureAWSPackage.
iv. aws:runCommand - Installs NVMe driver via AWS-ConfigureAWSPackage.
v. aws:runCommand - Installs AWS PV driver via AWS-ConfigureAWSPackage.
b. (Offline upgrade) If the input instance is not a managed instance:
i. aws:assertAwsResourceProperty - Verifies the AllowOffline flag is set to True. If so, the offline
upgrade starts, otherwise the workflow ends.
ii. aws:changeInstanceState - Stop the source instance.
iii. aws:changeInstanceState - Force-stop the source instance.
iv. aws:createImage - Create an AMI backup of the source instance.
v. aws:createTags - Tag the AMI backup of the source instance.
vi. aws:executeAwsApi - Enable ENA for the instance
vii.aws:assertAwsResourceProperty - Assert the ForceUpgrade flag.
viii.Force offline upgrade) If ForceUpgrade = True then run aws:executeAutomation to invoke
AWSSupport-StartEC2RescueWorkflow with the drivers force upgrade script. This installs the
drivers regardless of the current version that is installed
ix. (Offline upgrade) If ForceUpgrade = False then run aws:executeAutomation to invoke
AWSSupport-StartEC2RescueWorkflow with the drivers upgrade script.

Outputs

preUpgradeBackup.ImageId

preOfflineUpgradeBackup.ImageId

installAwsEnaNetworkDriverOnInstance.Output

installAWSNVMeOnInstance.Output

399
 AWS Systems Manager User Guide
Automation Walkthroughs

installAWSPVDriverOnInstance.Output

upgradeDriversOffline.Output

forceUpgradeDriversOffline.Output

Automation Walkthroughs
The following walkthroughs help you get started with Systems Manager Automation using a predefined
Automation document.

Before you begin, you must configure Automation roles and permissions. For more information, see
Getting Started with Automation (p. 144). For information about creating a custom Automation
document, see Patch a Windows AMI (p. 408).

Walkthroughs
• Patching Amazon Machines Images (p. 400)
• Using AWS Support Self-Service Automations (p. 422)
• Using Automation with Jenkins (p. 431)

Patching Amazon Machines Images

This section includes walkthroughs that describe how to patch or update Amazon Machines Images
(AMIs).

Topics
• Patch a Linux AMI (Console) (p. 400)
• Patch a Linux AMI (AWS CLI) (p. 403)
• Patch a Windows AMI (p. 408)
• Simplify AMI Patching Using Automation, Lambda, and Parameter Store (p. 412)
• Patch an AMI and Update an Auto Scaling Group (p. 417)

Patch a Linux AMI (Console)

This Systems Manager Automation walkthrough shows you how to use the console and the Systems
Manager AWS-UpdateLinuxAmi document to automatically patch a Linux AMI with the latest versions
of packages that you specify. The AWS-UpdateLinuxAmi document also automates the installation
of additional site-specific packages and configurations. You can update a variety of Linux distributions
using this walkthrough, including Ubuntu, CentOS, RHEL, SLES, or Amazon Linux AMIs. For a full list of
supported Linux versions, see Patch Manager Prerequisites (p. 684).

The AWS-UpdateLinuxAmi document enables you to automate image-maintenance tasks without

having to author the workflow in JSON or YAML. You can use the AWS-UpdateLinuxAmi document to
perform the following types of tasks.

• Upgrade all distribution packages and Amazon software on an Amazon Linux, Red Hat, Ubuntu, SLES,
or Cent OS Amazon Machine Image (AMI). This is the default document behavior.
• Install SSM Agent on an existing image to enable Systems Manager capabilities, such as remote
command execution using Run Command or software inventory collection using Inventory.
• Install additional software packages.

Before You Begin

400
 AWS Systems Manager User Guide
Automation Walkthroughs

Before you begin working with Automation documents, configure roles and, optionally, CloudWatch
Events for Automation. For more information, see Getting Started with Automation (p. 144).

The AWS-UpdateLinuxAmi document accepts the following input parameters.

Parameter Type Description

SourceAmiId String (Required) The source AMI ID.

IamInstanceProfileName String (Required) The name of the AWS

Identity and Access Management
(IAM) instance profile role you
created in Getting Started
with Automation (p. 144).
The instance profile role
gives Automation permission
to perform actions on your
instances, such as running
commands or starting and
stopping services. The
Automation document uses
only the name of the instance
profile role. If you specify the
Amazon Resource Name (ARN),
the Automation execution fails.

AutomationAssumeRole String (Required) The name of the

IAM service role you created
in Getting Started with
Automation (p. 144). The
service role (also called an
assume role) gives Automation
permission to assume your IAM
role and perform actions on your
behalf. For example, the service
role allows Automation to create
a new AMI when running the
aws:createImage action in an
Automation document. For this
parameter, the complete ARN
must be specified.

TargetAmiName String (Optional) The name of the

new AMI after it is created.
The default name is a system-
generated string that includes
the source AMI ID, and the
creation time and date.

InstanceType String (Optional) The type of instance

to launch as the workspace host.
Instance types vary by region.
The default type is t2.micro.

PreUpdateScript String (Optional) URL of a script to

run before updates are applied.
Default (\"none\") is to not run a
script.

401
 AWS Systems Manager User Guide
Automation Walkthroughs

Parameter Type Description

PostUpdateScript String (Optional) URL of a script to

run after package updates are
applied. Default (\"none\") is to
not run a script.

IncludePackages String (Optional) Only update these

named packages. By default
(\"all\"), all available updates are
applied.

ExcludePackages String (Optional) Names of packages to

hold back from updates, under
all conditions. By default (\"none
\"), no package is excluded.

Automation Steps

The AWS-UpdateLinuxAmi document includes the following Automation steps, by default.

Step 1: launchInstance (aws:runInstances action)

This step launches an instance using Amazon EC2 userdata and an IAM instance profile role.
Userdata installs the appropriate SSM Agent, based on the operating system. Installing SSM Agent
enables you to utilize Systems Manager capabilities such as Run Command, State Manager, and
Inventory.
Step 2: updateOSSoftware (aws:runCommand action)

This step runs the following commands on the launched instance:

• Downloads an update script from Amazon S3.
• Runs an optional pre-update script.
• Updates distribution packages and Amazon software.
• Runs an optional post-update script.

The execution log is stored in the /tmp folder for the user to view later.

If you want to upgrade a specific set of packages, you can supply the list using the
IncludePackages parameter. When provided, the system attempts to update only these packages
and their dependencies. No other updates are performed. By default, when no include packages are
specified, the program updates all available packages.

If you want to exclude upgrading a specific set of packages, you can supply the list to the
ExcludePackages parameter. If provided, these packages remain at their current version,
independent of any other options specified. By default, when no exclude packages are specified, no
packages are excluded.
Step 3: stopInstance (aws:changeInstanceState action)

This step stops the updated instance.

Step 4: createImage (aws:createImage action)

This step creates a new AMI with a descriptive name that links it to the source ID and creation time.
For example: “AMI Generated by EC2 Automation on {{global:DATE_TIME}} from {{SourceAmiId}}”
where DATE_TIME and SourceID represent Automation variables.

402
 AWS Systems Manager User Guide
Automation Walkthroughs

Step 5: terminateInstance (aws:changeInstanceState action)

This step cleans up the execution by terminating the running instance.

Output

The execution returns the new AMI ID as output.

Note
By default, when Automation runs the AWS-UpdateLinuxAmi document, the system creates a
temporary instance in the default VPC (172.30.0.0/16). If you deleted the default VPC, you will
receive the following error:
VPC not defined 400
To solve this problem, you must make a copy of the AWS-UpdateLinuxAmi document and
specify a subnet ID. For more information, see VPC not defined 400 (p. 433).

To create a patched AMI using Automation (AWS Systems Manager)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Automation.
3. Choose Execute automation.
4. In the Automation document list, choose AWS-UpdateLinuxAmi.
5. In the Document details section, verify that Document version is set to Default version at runtime.
6. Choose Next.
7. In the Execution mode section, choose Simple Execution.
8. In the Input parameters section, enter the information you collected in the Before You Begin
section.
9. Choose Execute. The console displays the status of the Automation execution.

After the workflow finishes, launch a test instance from the updated AMI to verify changes.
Note
If any step in the workflow fails, information about the failure is listed on the Automation
Executions page. The workflow is designed to terminate the temporary instance after
successfully completing all tasks. If a step fails, the system might not terminate the instance. So
if a step fails, manually terminate the temporary instance.

Patch a Linux AMI (AWS CLI)

This Systems Manager Automation walkthrough shows you how to use the AWS CLI and the Systems
Manager AWS-UpdateLinuxAmi document to automatically patch a Linux AMI with the latest versions
of packages that you specify. The AWS-UpdateLinuxAmi document also automates the installation
of additional site-specific packages and configurations. You can update a variety of Linux distributions
using this walkthrough, including Ubuntu, CentOS, RHEL, SLES, or Amazon Linux AMIs. For a full list of
supported Linux versions, see Patch Manager Prerequisites (p. 684).

The AWS-UpdateLinuxAmi document enables you to automate image-maintenance tasks without

having to author the workflow in JSON or YAML. You can use the AWS-UpdateLinuxAmi document to
perform the following types of tasks.

• Upgrade all distribution packages and Amazon software on an Amazon Linux, Red Hat, Ubuntu, SLES,
or Cent OS Amazon Machine Image (AMI). This is the default document behavior.

403
 AWS Systems Manager User Guide
Automation Walkthroughs

• Install SSM Agent on an existing image to enable Systems Manager capabilities, such as remote
command execution using Run Command or software inventory collection using Inventory.
• Install additional software packages.

Before You Begin

Before you begin working with Automation documents, configure roles and, optionally, CloudWatch
Events for Automation. For more information, see Getting Started with Automation (p. 144).

The AWS-UpdateLinuxAmi document accepts the following input parameters.

Parameter Type Description

SourceAmiId String (Required) The source AMI ID.

You can automatically reference
the latest Amazon EC2 Linux
AMI ID by using a Systems
Manager Parameter Store
public parameter. For more
information, see Query for the
latest Amazon Linux AMI IDs
using AWS Systems Manager
Parameter Store.

IamInstanceProfileName String (Required) The name of the AWS

Identity and Access Management
(IAM) instance profile role you
created in Getting Started
with Automation (p. 144).
The instance profile role
gives Automation permission
to perform actions on your
instances, such as running
commands or starting and
stopping services. The
Automation document uses
only the name of the instance
profile role. If you specify the
Amazon Resource Name (ARN),
the Automation execution fails.

AutomationAssumeRole String (Required) The name of the

IAM service role you created
in Getting Started with
Automation (p. 144). The
service role (also called an
assume role) gives Automation
permission to assume your IAM
role and perform actions on your
behalf. For example, the service
role allows Automation to create
a new AMI when running the
aws:createImage action in an
Automation document. For this
parameter, the complete ARN
must be specified.

404
 AWS Systems Manager User Guide
Automation Walkthroughs

Parameter Type Description

TargetAmiName String (Optional) The name of the

new AMI after it is created.
The default name is a system-
generated string that includes
the source AMI ID, and the
creation time and date.

InstanceType String (Optional) The type of instance

to launch as the workspace host.
Instance types vary by region.
The default type is t2.micro.

PreUpdateScript String (Optional) URL of a script to

run before updates are applied.
Default (\"none\") is to not run a
script.

PostUpdateScript String (Optional) URL of a script to

run after package updates are
applied. Default (\"none\") is to
not run a script.

IncludePackages String (Optional) Only update these

named packages. By default
(\"all\"), all available updates are
applied.

ExcludePackages String (Optional) Names of packages to

hold back from updates, under
all conditions. By default (\"none
\"), no package is excluded.

Automation Steps

The AWS-UpdateLinuxAmi document includes the following Automation steps, by default.

Step 1: launchInstance (aws:runInstances action)

This step launches an instance using Amazon EC2 userdata and an IAM instance profile role.
Userdata installs the appropriate SSM Agent, based on the operating system. Installing SSM Agent
enables you to utilize Systems Manager capabilities such as Run Command, State Manager, and
Inventory.
Step 2: updateOSSoftware (aws:runCommand action)

This step runs the following commands on the launched instance:

• Downloads an update script from Amazon S3.
• Runs an optional pre-update script.
• Updates distribution packages and Amazon software.
• Runs an optional post-update script.

The execution log is stored in the /tmp folder for the user to view later.

If you want to upgrade a specific set of packages, you can supply the list using the
IncludePackages parameter. When provided, the system attempts to update only these packages

405
 AWS Systems Manager User Guide
Automation Walkthroughs

and their dependencies. No other updates are performed. By default, when no include packages are
specified, the program updates all available packages.

If you want to exclude upgrading a specific set of packages, you can supply the list to the
ExcludePackages parameter. If provided, these packages remain at their current version,
independent of any other options specified. By default, when no exclude packages are specified, no
packages are excluded.
Step 3: stopInstance (aws:changeInstanceState action)

This step stops the updated instance.

Step 4: createImage (aws:createImage action)

This step creates a new AMI with a descriptive name that links it to the source ID and creation time.
For example: “AMI Generated by EC2 Automation on {{global:DATE_TIME}} from {{SourceAmiId}}”
where DATE_TIME and SourceID represent Automation variables.
Step 5: terminateInstance (aws:changeInstanceState action)

This step cleans up the execution by terminating the running instance.

Output

The execution returns the new AMI ID as output.

Note
By default, when Automation runs the AWS-UpdateLinuxAmi document, the system creates a
temporary instance in the default VPC (172.30.0.0/16). If you deleted the default VPC, you will
receive the following error:
VPC not defined 400
To solve this problem, you must make a copy of the AWS-UpdateLinuxAmi document and
specify a subnet ID. For more information, see VPC not defined 400 (p. 433).

To create a patched AMI using Automation

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to run the AWS-UpdateLinuxAmi document and run the Automation
workflow. In the parameters section, specify an AMI source ID, an Amazon EC2 instance profile role,
and your Automation service role.

aws ssm start-automation-execution \

--document-name "AWS-UpdateLinuxAmi" \
--parameters \
"SourceAmiId=ami-0080e4c5bc078760e, \
IamInstanceProfileName=ManagedInstanceRole, \
AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'"

The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the
status of the workflow.

{
"AutomationExecutionId": "ID"
}

3. To view the workflow execution using the AWS CLI, run the following command:

aws ssm describe-automation-executions

406
 AWS Systems Manager User Guide
Automation Walkthroughs

4. To view details about the execution progress, run the following command.

aws ssm get-automation-execution --automation-execution-id ID

The update process can take 30 minutes or more to complete.

Note
You can also monitor the status of the workflow in the console. In the execution list, choose
the execution you just ran and then choose the Steps tab. This tab shows you the status of
the workflow actions.

After the workflow finishes, launch a test instance from the updated AMI to verify changes.
Note
If any step in the workflow fails, information about the failure is listed on the Automation
Executions page. The workflow is designed to terminate the temporary instance after
successfully completing all tasks. If a step fails, the system might not terminate the instance. So
if a step fails, manually terminate the temporary instance.

Additional Automation AWS CLI Examples

You can manage other aspects of Automation execution using the following tasks.

Stop an Execution

Run the following to stop a workflow. The command doesn't terminate associated instances.

aws ssm stop-automation-execution --automation-execution-id ID

Create Versions of Automation Documents

You can't change an existing automation document, but you can create a new version using the following
command:

aws ssm update-document --name "patchWindowsAmi" --content file:///Users/test-user/

Documents/patchWindowsAmi.json --document-version "\$LATEST"

Run the following command to view details about the existing document versions:

aws ssm list-document-versions --name "patchWindowsAmi"

The command returns information like the following:

{
"DocumentVersions": [
{
"IsDefaultVersion": false,
"Name": "patchWindowsAmi",
"DocumentVersion": "2",
"CreatedDate": 1475799950.484
},
{
"IsDefaultVersion": false,
"Name": "patchWindowsAmi",
"DocumentVersion": "1",
"CreatedDate": 1475799931.064
}
]
}

407
 AWS Systems Manager User Guide
Automation Walkthroughs

Run the following command to update the default version for execution. The default execution version
only changes when you explicitly set it to a new version. Creating a new document version does not
change the default version.

aws ssm update-document-default-version --name patchWindowsAmi --document-version 2

Delete a Document

Run the following command to delete an automation document:

aws ssm delete-document --name patchWindowsAMI

Patch a Windows AMI

The AWS-UpdateWindowsAmi document enables you to automate image maintenance tasks on your
Amazon Windows AMIs without having to author the workflow in JSON or YAML. This document is
supported for Windows Server 2008 R2 or later. You can use the AWS-UpdateWindowsAmi document to
perform the following types of tasks.

• Install all Windows updates and upgrade Amazon software (default behavior).
• Install specific Windows updates and upgrade Amazon software.
• Customize an AMI using your scripts.

Before You Begin

Before you begin working with Automation documents, configure roles and, optionally, CloudWatch
Events for Automation. For more information, see Getting Started with Automation (p. 144).
Note
Updates to SSM Agent are typically rolled out to different regions at different times. When you
customize or update an AMI, use only source AMIs published for the region that you are working
in. This will ensure that you are working with the latest SSM Agent released for that region and
avoid compatibility issues.

The AWS-UpdateWindowsAmi document accepts the following input parameters.

Parameter Type Description

SourceAmiId String (Required) The source AMI ID.

You can automatically reference
the latest Windows Server
AMI ID by using a Systems
Manager Parameter Store
public parameter. For more
information, see Query for
the latest Windows AMI IDs
using AWS Systems Manager
Parameter Store.

IamInstanceProfileName String (Required) The name of the AWS

Identity and Access Management
(IAM) instance profile role you
created in Getting Started
with Automation (p. 144).
The instance profile role
gives Automation permission

408
 AWS Systems Manager User Guide
Automation Walkthroughs

Parameter Type Description

to perform actions on your
instances, such as running
commands or starting and
stopping services. The
Automation document uses
only the name of the instance
profile role. If you specify the
Amazon Resource Name (ARN),
the Automation execution fails.

AutomationAssumeRole String (Required) The name of the

IAM service role you created
in Getting Started with
Automation (p. 144). The
service role (also called an
assume role) gives Automation
permission to assume your IAM
role and perform actions on your
behalf. For example, the service
role allows Automation to create
a new AMI when running the
aws:createImage action in an
Automation document. For this
parameter, the complete ARN
must be specified.

TargetAmiName String (Optional) The name of the

new AMI after it is created.
The default name is a system-
generated string that includes
the source AMI ID, and the
creation time and date.

InstanceType String (Optional) The type of instance

to launch as the workspace host.
Instance types vary by region.
The default type is t2.medium.

PreUpdateScript String (Optional) A script to run before

updating the AMI. Enter a script
in the Automation document or
at runtime as a parameter.

PostUpdateScript String (Optional) A script to run after

updating the AMI. Enter a script
in the Automation document or
at runtime as a parameter.

IncludeKbs String (Optional) Specify one or more

Microsoft Knowledge Base
(KB) article IDs to include. You
can install multiple IDs using
comma-separated values.
Valid formats: KB9876543 or
9876543.

409
 AWS Systems Manager User Guide
Automation Walkthroughs

Parameter Type Description

ExcludeKbs String (Optional) Specify one or more

Microsoft Knowledge Base
(KB) article IDs to exclude.
You can exclude multiple IDs
using comma-separated values.
Valid formats: KB9876543 or
9876543.

Categories String (Optional)Specify one or more

update categories. You can
filter categories using comma-
separated values. Options:
Critical Update, Security Update,
Definition Update, Update
Rollup, Service Pack, Tool,
Update, or Driver. Valid formats
include a single entry, for
example: Critical Update. Or, you
can specify a comma separated
list: Critical Update,Security
Update,Definition Update.

SeverityLevels String (Optional) Specify one or more

MSRC severity levels associated
with an update. You can filter
severity levels using comma-
separated values. Options:
Critical, Important, Low,
Moderate or Unspecified. Valid
formats include a single entry,
for example: Critical. Or, you can
specify a comma separated list:
Critical,Important,Low.

Automation Steps

The AWS-UpdateWindowsAmi document includes the following Automation steps, by default.

Step 1: launchInstance (aws:runInstances action)

This step launches an instance with an IAM instance profile role from the specified SourceAmiID.
Step 2: runPreUpdateScript (aws:runCommand action)

This step enables you to specify a script as a string that runs before updates are installed.
Step 3: updateEC2Config (aws:runCommand action)

This step uses the AWS-InstallPowerShellModule public document to download an AWS public
PowerShell module. Systems Manager verifies the integrity of the module by using an SHA-256
hash. Systems Manager then checks the operating system to determine whether to update
EC2Config or EC2Launch. EC2Config runs on Windows Server 2008 R2 through Windows Server
2012 R2. EC2Launch runs on Windows Server 2016.
Step 4: updateSSMAgent (aws:runCommand action)

This step updates SSM Agent by using the AWS-UpdateSSMAgent public document.

410
 AWS Systems Manager User Guide
Automation Walkthroughs

Step 5: updateAWSPVDriver (aws:runCommand action)

This step updates AWS PV drivers by using the AWS-ConfigureAWSPackage public document.
Step 6: updateAwsEnaNetworkDriver (aws:runCommand action)

This step updates AWS ENA Network drivers by using the AWS-ConfigureAWSPackage public
document.
Step 7: installWindowsUpdates (aws:runCommand action)

This step installs Windows updates by using the AWS-InstallWindowsUpdates public document. By
default, Systems Manager searches for and installs all missing updates. You can change the default
behavior by specifying one of the following parameters: IncludeKbs, ExcludeKbs, Categories,
or SeverityLevels.
Step 8: runPostUpdateScript (aws:runCommand action)

This step enables you to specify a script as a string that runs after the updates have been installed.
Step 9: runSysprepGeneralize (aws:runCommand action)

This step uses the AWS-InstallPowerShellModule public document to download an AWS public
PowerShell module. Systems Manager verifies the integrity of the module by using an SHA-256
hash. Systems Manager then runs sysprep using AWS-supported methods for either EC2Launch
(Windows Server 2016) or EC2Config (Windows Server 2008 R2 through 2012 R2).
Step 10: stopInstance (aws:changeInstanceState action)

This step stops the updated instance.

Step 11: createImage (aws:createImage action)

This step creates a new AMI with a descriptive name that links it to the source ID and creation time.
For example: “AMI Generated by EC2 Automation on {{global:DATE_TIME}} from {{SourceAmiId}}”
where DATE_TIME and SourceID represent Automation variables.
Step 12: TerminateInstance (aws:changeInstanceState action)

This step cleans up the execution by terminating the running instance.

Output

This section enables you to designate the outputs of various steps or values of any parameter as
the Automation output. By default, the output is the ID of the updated Windows AMI created by the
execution.

Note
By default, when Automation runs the AWS-UpdateWindowsAmi document and creates a
temporary instance, the system uses the default VPC (172.30.0.0/16). If you deleted the default
VPC, you will receive the following error:
VPC not defined 400
To solve this problem, you must make a copy of the AWS-UpdateWindowsAmi document and
specify a subnet ID. For more information, see VPC not defined 400 (p. 433).

To create a patched Windows AMI by using Automation

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to run the AWS-UpdateWindowsAmi document. In the parameters
section, specify an AMI source ID, an Amazon EC2 instance profile role, and your Automation service

411
 AWS Systems Manager User Guide
Automation Walkthroughs

role. The example command below uses a recent Amazon EC2 AMI to minimize the number of
patches that need to be applied. If you run this command more than once, you must specify a
unique value for targetAMIname. AMI names must be unique.

aws ssm start-automation-execution --document-name="AWS-UpdateWindowsAmi" --parameters

SourceAmiId='ami-0246f4914689c475f',IamInstanceProfileName='ManagedInstanceProfile',AutomationAssu
{{global:ACCOUNT_ID}}:role/AutomationServiceRole'

The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the
status of the workflow.

{
"AutomationExecutionId": "ID"
}

3. To view the workflow execution using the AWS CLI, run the following command:

aws ssm describe-automation-executions

4. To view details about the execution progress, run the following command.

aws ssm get-automation-execution --automation-execution-id ID

Note
Depending on the number of patches applied, the Windows patching process run in this sample
workflow can take 30 minutes or more to complete.

Simplify AMI Patching Using Automation, Lambda, and Parameter Store

The following example expands on how to update a Windows AMI, as described in Patch a Windows
AMI (p. 408). This example uses the model where an organization maintains and periodically patches
their own, proprietary AMIs rather than building from Amazon EC2 AMIs.

The following procedure shows how to automatically apply operating system (OS) patches to a Windows
AMI that is already considered to be the most up-to-date or latest AMI. In the example, the default value
of the parameter SourceAmiId is defined by a Systems Manager Parameter Store parameter called
latestAmi. The value of latestAmi is updated by an AWS Lambda function invoked at the end of the
Automation workflow. As a result of this Automation process, the time and effort spent patching AMIs is
minimized because patching is always applied to the most up-to-date AMI.

Before You Begin

Configure Automation roles and, optionally, CloudWatch Events for Automation. For more information,
see Getting Started with Automation (p. 144).

Contents
• Task 1: Create a Parameter in Systems Manager Parameter Store (p. 412)
• Task 2: Create an IAM Role for AWS Lambda (p. 413)
• Task 3: Create an AWS Lambda Function (p. 413)
• Task 4: Create an Automation Document and Patch the AMI (p. 415)

Task 1: Create a Parameter in Systems Manager Parameter Store

Create a string parameter in Parameter Store that uses the following information:

412
 AWS Systems Manager User Guide
Automation Walkthroughs

• Name: latestAmi.
• Value: a Windows AMI ID. For example: ami-188d6e0e.

For information about how to create a Parameter Store string parameter, see Creating Systems Manager
Parameters (p. 847).

Task 2: Create an IAM Role for AWS Lambda

Use the following procedure to create an IAM service role for AWS Lambda. This role includes the
AWSLambdaExecute and AmazonSSMFullAccess managed policies. These policies give Lambda
permission to update the value of the latestAmi parameter using a Lambda function and Systems
Manager.

To create an IAM service role for Lambda

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create New Role.
3. For Role name, type a role name that can help you identify the purpose of this role, for example,
lambda-ssm-role. Role names must be unique within your AWS account. After you type the name,
choose Next Step at the bottom of the page.
Note
Because various entities might reference the role, you cannot change the name of the role
after it has been created.
4. On the Select Role Type page, choose the AWS Service Roles section, and then choose AWS
Lambda.
5. On the Attach Policy page, choose AWSLambdaExecute and AmazonSSMFullAccess, and then
choose Next Step.
6. Choose Create Role.

Task 3: Create an AWS Lambda Function

Use the following procedure to create a Lambda function that automatically updates the value of the
latestAmi parameter.

To create a Lambda function

1. Sign in to the AWS Management Console and open the AWS Lambda console at https://
console.aws.amazon.com/lambda/.
2. Choose Create a Lambda function.
3. On the Create function page, choose Author from scratch.
4. For Function name, type Automation-UpdateSsmParam.
5. In the Runtime list, choose Python 2.7.
6. In the Permissions section, choose Use an existing role and choose the service role for Lambda that
you created in Task 2.
7. Choose Create function.
8. In the Lambda function code section, delete the pre-populated code in the field, and then paste the
following code sample.

from __future__ import print_function

413
 AWS Systems Manager User Guide
Automation Walkthroughs

import json
import boto3

print('Loading function')

#Updates an SSM parameter

#Expects parameterName, parameterValue
def lambda_handler(event, context):
print("Received event: " + json.dumps(event, indent=2))

# get SSM client

client = boto3.client('ssm')

#confirm parameter exists before updating it

response = client.describe_parameters(
Filters=[
{
'Key': 'Name',
'Values': [ event['parameterName'] ]
},
]
)

if not response['Parameters']:
print('No such parameter')
return 'SSM parameter not found.'

#if parameter has a Description field, update it PLUS the Value

if 'Description' in response['Parameters'][0]:
description = response['Parameters'][0]['Description']

response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Description=description,
Type='String',
Overwrite=True
)

#otherwise just update Value

else:
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Type='String',
Overwrite=True
)

reponseString = 'Updated parameter %s with value %s.' % (event['parameterName'],

event['parameterValue'])

return reponseString

9. Choose Save.
10. To test the Lambda function, from the Select a test event menu, choose Configure test events.
11. For Event name, enter a name for the test event, such as MyTestEvent.
12. Replace the existing text with the following JSON.

{
"parameterName":"latestAmi",
"parameterValue":"your AMI ID"
}

414
 AWS Systems Manager User Guide
Automation Walkthroughs

13. Choose Create.

14. Select Test to test the function. The output should state that the parameter was successfully
updated and include details about the update. For example, “Updated parameter latestAmi with
value ami-123456”.

Task 4: Create an Automation Document and Patch the AMI

Use the following procedure to create and run an Automation document that patches the AMI you
specified for the latestAmi parameter. After the Automation workflow completes, the value of latestAmi
is updated with the ID of the newly-patched AMI. Subsequent executions use the AMI created by the
previous execution.

To create an Automation document and patch an AMI

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose Create document.
4. In the Name field, type UpdateMyLatestWindowsAmi.
5. In the Document type list, choose Automation document.
6. Delete the brackets in the Content field, and then paste the following JSON sample document.
Note
You must change the values of assumeRole and IamInstanceProfileName in this
sample with the service role ARN and instance profile role you created when Getting
Started with Automation (p. 144).

{
"description":"Systems Manager Automation Demo – Patch AMI and Update SSM Param",
"schemaVersion":"0.3",
"assumeRole":"the role ARN you created",
"parameters":{
"sourceAMIid":{
"type":"String",
"description":"AMI to patch",
"default":"{{ssm:latestAmi}}"
},
"targetAMIname":{
"type":"String",
"description":"Name of new AMI",
"default":"patchedAMI-{{global:DATE_TIME}}"
}
},
"mainSteps":[
{
"name":"startInstances",
"action":"aws:runInstances",
"timeoutSeconds":1200,
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"ImageId":"{{ sourceAMIid }}",
"InstanceType":"m3.large",
"MinInstanceCount":1,
"MaxInstanceCount":1,

415
 AWS Systems Manager User Guide
Automation Walkthroughs

"IamInstanceProfileName":"the name of the IAM role you created"

}
},
{
"name":"installMissingWindowsUpdates",
"action":"aws:runCommand",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"DocumentName":"AWS-InstallMissingWindowsUpdates",
"InstanceIds":[
"{{ startInstances.InstanceIds }}"
],
"Parameters":{
"UpdateLevel":"Important"
}
}
},
{
"name":"stopInstance",
"action":"aws:changeInstanceState",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceIds":[
"{{ startInstances.InstanceIds }}"
],
"DesiredState":"stopped"
}
},
{
"name":"createImage",
"action":"aws:createImage",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceId":"{{ startInstances.InstanceIds }}",
"ImageName":"{{ targetAMIname }}",
"NoReboot":true,
"ImageDescription":"AMI created by EC2 Automation"
}
},
{
"name":"terminateInstance",
"action":"aws:changeInstanceState",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceIds":[
"{{ startInstances.InstanceIds }}"
],
"DesiredState":"terminated"
}
},
{
"name":"updateSsmParam",
"action":"aws:invokeLambdaFunction",
"timeoutSeconds":1200,
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"FunctionName":"Automation-UpdateSsmParam",
"Payload":"{\"parameterName\":\"latestAmi\", \"parameterValue\":
\"{{createImage.ImageId}}\"}"
}
}

416
 AWS Systems Manager User Guide
Automation Walkthroughs

],
"outputs":[
"createImage.ImageId"
]
}

7. Choose Create document to save the document.

8. In the navigation pane, choose Automations, and then choose Execute automation.
9. In the Automation document list, choose UpdateMyLatestWindowsAmi.
10. In the Document details section verify that Document version is set to 1.
11. In the Execution mode section, choose Execute the entire automation at once.
12. Leave the Targets and Rate Control option disabled.
13. After execution completes, choose Parameter Store in the navigation pane and confirm that the
new value for latestAmi matches the value returned by the Automation workflow. You can also
verify the new AMI ID matches the Automation output in the AMIs section of the EC2 console.

Patch an AMI and Update an Auto Scaling Group

The following example builds on the Simplify AMI Patching Using Automation, Lambda, and Parameter
Store (p. 412) example by adding a step that updates an Auto Scaling group with the newly-patched
AMI. This approach ensures that new images are automatically made available to different computing
environments that use Auto Scaling groups.

The final step of the Automation workflow in this example uses an AWS Lambda function to copy an
existing launch configuration and set the AMI ID to the newly-patched AMI. The Auto Scaling group
is then updated with the new launch configuration. In this type of Auto Scaling scenario, users could
terminate existing instances in the Auto Scaling group to force a new instance to launch that uses
the new image. Or, users could wait and allow scale-in or scale-out events to naturally launch newer
instances.

Before You Begin

Complete the following tasks before you begin this example.

• Configure IAM roles for Automation. Systems Manager requires an instance profile role and a
service role ARN to process Automation workflows. For more information, see Getting Started with
Automation (p. 144).
• If you are not familiar with Lambda, we recommend that you create a simple Lambda function by
using the Create a Simple Lambda Function topic in the AWS Lambda Developer Guide. The topic will
help you understand, in detail, some of the steps required to create a Lambda function.

Task 1: Create an IAM Role for AWS Lambda

Use the following procedure to create an IAM service role for AWS Lambda. This role includes the
AWSLambdaExecute and AutoScalingFullAccess managed policies. These policies give Lambda
permission to create a new Auto Scaling group with the latest, patched AMI using a Lambda function.

To create an IAM service role for Lambda

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create role.
3. On the Select type of trusted entity page, under AWS Service, choose Lambda.
4. In the Select your use case section, choose Lambda, and then choose Next: Permissions.

417
 AWS Systems Manager User Guide
Automation Walkthroughs

5. On the Attach permissions policy page, search for AWSLambdaExecute, and then choose the
option next to it. Search for AutoScalingFullAccess, and then choose the option next to it.
6. Chooes Next: Review.
7. On the Review page, verify that AWSLambdaExecute and AutoScalingFullAccess are listed under
Policies.

8. Type a name in the Role name box, and then type a description.
9. Choose Create role. The system returns you to the Roles page.

Task 2: Create an AWS Lambda Function

Use the following procedure to create a Lambda function that automatically updates an existing Auto
Scaling group with the latest, patched AMI.

To create a Lambda function

1. Sign in to the AWS Management Console and open the AWS Lambda console at https://
console.aws.amazon.com/lambda/.
2. Choose Create function.
3. Verify that Author from scratch is selected.
4. In the Name field type Automation-UpdateAsg.
5. In the Runtime list, choose Python 2.7.
6. In the Role list, verify that Choose an existing role is selected.
7. In the Existing role list, choose the role you created earlier.
8. Choose Create function. The systems displays a code and configuration page for Automation-
UpdateSAsg.
9. Make no changes in the Designer section.
10. In the Function code section, delete the pre-populated code in the lambda_function field, and then
paste the following code sample.

from __future__ import print_function

import json
import datetime
import time
import boto3

print('Loading function')

418
 AWS Systems Manager User Guide
Automation Walkthroughs

def lambda_handler(event, context):

print("Received event: " + json.dumps(event, indent=2))

# get autoscaling client

client = boto3.client('autoscaling')

# get object for the ASG we're going to update, filter by name of target ASG
response =
client.describe_auto_scaling_groups(AutoScalingGroupNames=[event['targetASG']])

if not response['AutoScalingGroups']:
return 'No such ASG'

# get name of InstanceID in current ASG that we'll use to model new Launch
Configuration after
sourceInstanceId = response.get('AutoScalingGroups')[0]['Instances'][0]
['InstanceId']

# create LC using instance from target ASG as a template, only diff is the name of
the new LC and new AMI
timeStamp = time.time()
timeStampString = datetime.datetime.fromtimestamp(timeStamp).strftime('%Y-%m-%d
%H-%M-%S')
newLaunchConfigName = 'LC '+ event['newAmiID'] + ' ' + timeStampString
client.create_launch_configuration(
InstanceId = sourceInstanceId,
LaunchConfigurationName=newLaunchConfigName,
ImageId= event['newAmiID'] )

# update ASG to use new LC

response = client.update_auto_scaling_group(AutoScalingGroupName =
event['targetASG'],LaunchConfigurationName = newLaunchConfigName)

return 'Updated ASG `%s` with new launch configuration `%s` which includes AMI `
%s`.' % (event['targetASG'], newLaunchConfigName, event['newAmiID'])

11. Specify the remaining configuration options on this page.

12. Choose Save.
13. Choose Test.
14. In the Configure test event page, verify that Create new test event is selected.
15. In the Event template list, verify that Hello World is selected.
16. In the Event name field, type a name.
17. Replace the existing sample with the following JSON. Enter an AMI ID and Auto Scaling group.

{
"newAmiID":"valid AMI ID",
"targetASG":"name of your Auto Scaling group"
}

18. Choose Save.

19. Choose Test. The output states that the Auto Scaling group was successfully updated with a new
launch configuration.

Task 3: Create an Automation Document, Patch the AMI, and Update the Auto Scaling Group

Use the following procedure to create and run an Automation document that patches the AMI you
specified for the latestAmi parameter. The Automation workflow then updates the Auto Scaling group to
use the latest, patched AMI.

419
 AWS Systems Manager User Guide
Automation Walkthroughs

To create and run the Automation document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose Create document.
4. In the Name field, type PatchAmiandUpdateAsg.
5. In the Document type list, choose Automation document.
6. Delete the brackets in the Content field, and then paste the following JSON sample document.
Note
You must change the values of assumeRole and IamInstanceProfileName in this
sample with the service role ARN and instance profile role you created when Getting
Started with Automation (p. 144).

{
"description":"Systems Manager Automation Demo - Patch AMI and Update ASG",
"schemaVersion":"0.3",
"assumeRole":"the service role ARN you created",
"parameters":{
"sourceAMIid":{
"type":"String",
"description":"AMI to patch"
},
"targetAMIname":{
"type":"String",
"description":"Name of new AMI",
"default":"patchedAMI-{{global:DATE_TIME}}"
},
"targetASG":{
"type":"String",
"description":"Autosaling group to Update"
}
},
"mainSteps":[
{
"name":"startInstances",
"action":"aws:runInstances",
"timeoutSeconds":1200,
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"ImageId":"{{ sourceAMIid }}",
"InstanceType":"m3.large",
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"the name of the instance IAM role you created"
}
},
{
"name":"installMissingWindowsUpdates",
"action":"aws:runCommand",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"DocumentName":"AWS-InstallMissingWindowsUpdates",
"InstanceIds":[
"{{ startInstances.InstanceIds }}"

420
 AWS Systems Manager User Guide
Automation Walkthroughs

],
"Parameters":{
"UpdateLevel":"Important"
}
}
},
{
"name":"stopInstance",
"action":"aws:changeInstanceState",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceIds":[
"{{ startInstances.InstanceIds }}"
],
"DesiredState":"stopped"
}
},
{
"name":"createImage",
"action":"aws:createImage",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceId":"{{ startInstances.InstanceIds }}",
"ImageName":"{{ targetAMIname }}",
"NoReboot":true,
"ImageDescription":"AMI created by EC2 Automation"
}
},
{
"name":"terminateInstance",
"action":"aws:changeInstanceState",
"maxAttempts":1,
"onFailure":"Continue",
"inputs":{
"InstanceIds":[
"{{ startInstances.InstanceIds }}"
],
"DesiredState":"terminated"
}
},
{
"name":"updateASG",
"action":"aws:invokeLambdaFunction",
"timeoutSeconds":1200,
"maxAttempts":1,
"onFailure":"Abort",
"inputs": {
"FunctionName": "Automation-UpdateAsg",
"Payload": "{\"targetASG\":\"{{targetASG}}\", \"newAmiID\":
\"{{createImage.ImageId}}\"}"
}
}
],
"outputs":[
"createImage.ImageId"
]
}

7. Choose Create document to save the document.

8. Choose Automations, and then choose Execute automation.
9. In the Automation document list, choose PatchAmiandUpdateAsg.
10. In the Document details section verify that Document version is set to 1.

421
 AWS Systems Manager User Guide
Automation Walkthroughs

11. In the Execution mode section, choose Execute the entire automation at once.
12. Leave the Targets and Rate Control option disabled.
13. Specify a Windows AMI ID for sourceAMIid and your Auto Scaling group name for targetASG.
14. Choose Execute automation.
15. After execution completes, in the Amazon EC2 console, choose Auto Scaling, and then choose
Launch Configurations. Verify that you see the new launch configuration, and that it uses the new
AMI ID.
16. Choose Auto Scaling, and then choose Auto Scaling Groups. Verify that the Auto Scaling group uses
the new launch configuration.
17. Terminate one or more instances in your Auto Scaling group. Replacement instances will be
launched with the new AMI ID.

Note
You can further automate deployment of the new AMI by editing the Lambda function to
gracefully terminate instances. You can also invoke your own Lambda function and utilize
the ability of AWS CloudFormation to update Auto Scaling groups. For more information, see
UpdatePolicy Attribute.

Using AWS Support Self-Service Automations

This section describes how to run Automations created by the AWS Support team to help you
troubleshoot common issues with your AWS resources.

Topics
• Run the EC2Rescue Tool on Unreachable Instances (p. 422)
• Reset Passwords and SSH Keys on Amazon EC2 Instances (p. 426)

Run the EC2Rescue Tool on Unreachable Instances

EC2Rescue can help you diagnose and troubleshoot problems on Amazon EC2 Linux and Windows
Server instances. You can run the tool manually, as described in Using EC2Rescue for Linux Server and
Using EC2Rescue for Windows Server. Or, you can run the tool automatically by using Systems Manager
Automation and the AWSSupport-ExecuteEC2Rescue document. The AWSSupport-ExecuteEC2Rescue
document is designed to perform a combination of Systems Manager actions, AWS CloudFormation
actions, and Lambda functions that automate the steps normally required to use EC2Rescue.

You can use the AWSSupport-ExecuteEC2Rescue document to troubleshoot and potentially remediate
different types of operating system (OS) issues. See the following topics for a complete list:

Windows: See Rescue Action in Using EC2Rescue for Windows Server with the Command Line.

Linux: Some EC2Rescue for Linux modules detect and attempt to remediate issues. For more
information, see the aws-ec2rescue-linux documentation for each module on GitHub.

How It Works

Troubleshooting an instance with Automation and the AWSSupport-ExecuteEC2Rescue document works

as follows:

• You specify the ID of the unreachable instance and run the Automation workflow.
• The system creates a temporary VPC, and then runs a series of Lambda functions to configure the VPC.
• The system identifies a subnet for your temporary VPC in the same Availability Zone as your original
instance.
• The system launches a temporary, SSM-enabled helper instance.

422
 AWS Systems Manager User Guide
Automation Walkthroughs

• The system stops your original instance, and creates a backup. It then attaches the original root
volume to the helper instance.
• The system uses Run Command to run EC2Rescue on the helper instance. EC2Rescue identifies and
attempts to fix issues on the attached, original root volume. When finished, EC2Rescue reattaches the
root volume back to the original instance.
• The system restarts your original instance, and terminates the temporary instance. The system also
terminates the temporary VPC and the Lambda functions created at the start of the automation.

Before You Begin

Before you run the following Automation, do the following:

• Copy the instance ID of the unreachable instance. You will specify this ID in the procedure.
• Optionally, collect the ID of a subnet in the same availability zone as your unreachable instance. The
EC2Rescue instance will be created in this subnet. If you don’t specify a subnet, then Automation
creates a new temporary VPC in your AWS account. Verify that your AWS account has at least one
VPC available. By default, you can create five VPCs in a Region. If you already created five VPCs in the
Region, the automation fails without making changes to your instance. For more information, see VPC
and Subnets.
• Optionally, you can create and specify an AWS Identity and Access Management (IAM) role for
Automation. If you don't specify this role, then Automation runs in the context of the user who ran the
automation. For more information about creating roles for Automation, see Running an Automation
Workflow by Using an IAM Service Role (p. 200).

Granting AWSSupport-EC2Rescue Permissions to Perform Actions On Your Instances

EC2Rescue needs permission to perform a series of actions on your instances during the Automation
execution. These actions invoke the AWS Lambda, IAM, and Amazon EC2 services to safely and securely
attempt to remediate issues with your instances. If you have Administrator-level permissions in your
AWS account and/or VPC, you might be able to run the automation without configuring permissions, as
described in this section. If you don't have Administrator-level permissions, then you or an administrator
must configure permissions by using one of the following options.

• Granting Permissions By Using IAM Policies (p. 423)

• Granting Permissions By Using An AWS CloudFormation Template (p. 425)

Granting Permissions By Using IAM Policies

You can either attach the following IAM policy to your IAM user account, group, or role as an inline
policy; or, you can create a new IAM managed policy and attach it to your user account, group, or role.
For more information about adding an inline policy to your user account, group, or role see Working With
Inline Policies. For more information about creating a new managed policy, see Working With Managed
Policies.
Note
If you create a new IAM managed policy, you must also attach the AmazonSSMAutomationRole
managed policy to it so that your instances can communicate with the Systems Manager API.

IAM Policy for AWSSupport-EC2Rescue

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",

423
 AWS Systems Manager User Guide
Automation Walkthroughs

"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:An-AWS-Account-ID:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::An-AWS-Account-ID:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::An-AWS-Account-ID:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"
],
"Resource": "*",
"Effect": "Allow"
}
]

424
 AWS Systems Manager User Guide
Automation Walkthroughs

Granting Permissions By Using An AWS CloudFormation Template

AWS CloudFormation automates the process of creating IAM roles and policies by using a preconfigured
template. Use the following procedure to create the required IAM roles and policies for the EC2Rescue
Automation by using AWS CloudFormation.

To create the required IAM roles and policies for EC2Rescue

1. Choose the Launch Stack button. The button opens the AWS CloudFormation console and
populates the Specify an Amazon S3 template URL field with the URL to the EC2Rescue template.
Note
Choose View to view the template.

View Launch

View

2. Choose Next.
3. On the Specify Details page, in the Stack Name field, either choose to keep the default value or
specify your own value. Choose Next.
4. On the Options page, you don’t need to make any selections. Choose Next.
5. On the Review page, scroll down and choose the I acknowledge that AWS CloudFormation might
create IAM resources option.
6. Choose Create.

AWS CloudFormation shows the CREATE_IN_PROGRESS status for approximately three minutes.
The status changes to CREATE_COMPLETE after the stack has been created.
7. In the stack list, choose the option next to the stack you just created, and then choose the Outputs
tab.
8. Copy the Value. The is the ARN of the AssumeRole. You will specify this ARN when you run the
Automation.

Running the Automation

Important
The following Automation execution stops the unreachable instance. Stopping the instance can
result in lost data on attached instance store volumes (if present). Stopping the instance can
also cause the public IP to change, if no Elastic IP is associated.

To run the AWSSupport-ExecuteEC2Rescue Automation

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Automation.
3. Choose Execute automation.
4. In the Automation document section, choose Owned by Me or Amazon from the list.
5. In the documents list, choose AWSSupport-ExecuteEC2Rescue. The document owner is Amazon.

425
 AWS Systems Manager User Guide
Automation Walkthroughs

6. In the Document details section verify that Document version is set to the highest default version.
For example, 6 (default).
7. In the Execution mode section, choose Simple Execution.
8. In the Input parameters section, specify the following parameters:

a. For UnreachableInstanceId, specify the ID of the unreachable instance.

b. For LogDestination, specify an Amazon S3 bucket if you want to collect operating system-level
logs while troubleshooting your instance. Logs are automatically uploaded to the specified
bucket.
c. For EC2RescueInstanceType, specify an instance type for the EC2Rescue instance. The default
instance type is t2.small.
d. For SubnetId, specify a subnet in an existing VPC in the same availability zone as the
unreachable instance. By default, Systems Manager creates a new VPC, but you can specify a
subnet in an existing VPC if you want.
Note
If you don't see the option to specify a bucket or a subnet ID, verify that you are using
the latest Default version of the document.
e. For AssumeRole, if you created roles for this Automation by using the CloudFormation
procedure described earlier in this topic, then specify the AssumeRole ARN that you copied from
the CloudFormation console.
9. Choose Execute automation.

The Automation creates a backup AMI as part of the workflow. All other resources created by the
Automation workflow are automatically deleted, but this AMI remains in your account. The AMI is named
using the following convention:

Backup AMI: AWSSupport-EC2Rescue:UnreachableInstanceId

You can locate this AMI in the Amazon EC2 console by searching on the Automation execution ID.

Reset Passwords and SSH Keys on Amazon EC2 Instances

You can use the AWSSupport-ResetAccess document to automatically reenable local Administrator
password generation on Amazon EC2 Windows instances, and to generate a new SSH key on Amazon
EC2 Linux instances. The AWSSupport-ResetAccess document is designed to perform a combination of
Systems Manager actions, AWS CloudFormation actions, and Lambda functions that automate the steps
normally required to reset the local administrator password.

You can use Automation with the AWSSupport-ResetAccess document to solve the following problems:

Windows

You lost the EC2 key pair: To resolve this problem, you can use the AWSSupport-ResetAccess document
to create a password-enabled AMI from your current instance, launch a new instance from the AMI, and
select a key pair you own.

You lost the local Administrator password: To resolve this problem, you can use the AWSSupport-
ResetAccess document to generate a new password that you can decrypt with the current EC2 key pair.

Linux

You lost your EC2 key pair, or you configured SSH access to the instance with a key you lost: To resolve this
problem, you can use the AWSSupport-ResetAccess document to create a new SSH key for your current
instance, which enables you to connect to the instance again.
Note
If your EC2 Windows instance is configured for Systems Manager, you can also reset your local
Administrator password by using EC2Rescue and Run Command. For more information, see

426
 AWS Systems Manager User Guide
Automation Walkthroughs

Using EC2Rescue for Windows Server with Systems Manager Run Command in the Amazon EC2
User Guide for Windows Instances.

How It Works

Troubleshooting an instance with Automation and the AWSSupport-ResetAccess document works as

follows:

• You specify the ID of the instance and run the Automation workflow.
• The system creates a temporary VPC, and then runs a series of Lambda functions to configure the VPC.
• The system identifies a subnet for your temporary VPC in the same Availability Zone as your original
instance.
• The system launches a temporary, SSM-enabled helper instance.
• The system stops your original instance, and creates a backup. It then attaches the original root
volume to the helper instance.
• The system uses Run Command to run EC2Rescue on the helper instance. On Windows, EC2Rescue
enables password generation for the local Administrator by using EC2Config or EC2Launch on the
attached, original root volume. On Linux, EC2Rescue generates and injects a new SSH key and saves
the private key, encrypted, in Parameter Store. When finished, EC2Rescue reattaches the root volume
back to the original instance.
• The system creates a new Amazon Machine Image (AMI) of your instance, now that password
generation is enabled. You can use this AMI to create a new EC2 instance, and associate a new key pair
if needed.
• The system restarts your original instance, and terminates the temporary instance. The system also
terminates the temporary VPC and the Lambda functions created at the start of the automation.
• Windows: Your instance generates a new password you can decode from the EC2 console using the
current key pair assigned to the instance.

Linux: You can SSH to the instance by using the SSH key stored in Systems Manager Parameter Store
as /ec2rl/openssh/instance_id/key.

Before You Begin

Before you run the following Automation, do the following:

• Copy the instance ID of the instance on which you want to reset the Administator password. You will
specify this ID in the procedure.
• Optionally, collect the ID of a subnet in the same availability zone as your unreachable instance. The
EC2Rescue instance will be created in this subnet. If you don’t specify a subnet, then Automation
creates a new temporary VPC in your AWS account. Verify that your AWS account has at least one
VPC available. By default, you can create five VPCs in a Region. If you already created five VPCs in the
Region, the automation fails without making changes to your instance. For more information, see VPC
and Subnets.
• Optionally, you can create and specify an AWS Identity and Access Management (IAM) role for
Automation. If you don't specify this role, then Automation runs in the context of the user who ran the
automation. For more information about creating roles for Automation, see Running an Automation
Workflow by Using an IAM Service Role (p. 200).

Granting AWSSupport-EC2Rescue Permissions to Perform Actions On Your Instances

EC2Rescue needs permission to perform a series of actions on your instances during the Automation
execution. These actions invoke the AWS Lambda, IAM, and Amazon EC2 services to safely and securely
attempt to remediate issues with your instances. If you have Administrator-level permissions in your
AWS account and/or VPC, you might be able to run the automation without configuring permissions, as

427
 AWS Systems Manager User Guide
Automation Walkthroughs

described in this section. If you don't have Administrator-level permissions, then you or an administrator
must configure permissions by using one of the following options.

• Granting Permissions By Using IAM Policies (p. 428)

• Granting Permissions By Using An AWS CloudFormation Template (p. 429)

Granting Permissions By Using IAM Policies

You can either attach the following IAM policy to your IAM user account, group, or role as an inline
policy; or, you can create a new IAM managed policy and attach it to your user account, group, or role.
For more information about adding an inline policy to your user account, group, or role see Working With
Inline Policies. For more information about creating a new managed policy, see Working With Managed
Policies.
Note
If you create a new IAM managed policy, you must also attach the AmazonSSMAutomationRole
managed policy to it so that your instances can communicate with the Systems Manager API.

IAM Policy for AWSSupport-ResetAccess

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:An-AWS-Account-ID:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::An-AWS-Account-ID:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::An-AWS-Account-ID:instance-profile/AWSSupport-EC2Rescue-*"
],

428
 AWS Systems Manager User Guide
Automation Walkthroughs

"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"
],
"Resource": "*",
"Effect": "Allow"
}
]
}

Granting Permissions By Using An AWS CloudFormation Template

AWS CloudFormation automates the process of creating IAM roles and policies by using a preconfigured
template. Use the following procedure to create the required IAM roles and policies for the EC2Rescue
Automation by using AWS CloudFormation.

To create the required IAM roles and policies for EC2Rescue

1. Choose the Launch Stack button. The button opens the AWS CloudFormation console and
populates the Specify an Amazon S3 template URL field with the URL to the EC2Rescue template.
Note
Choose View to view the template.

View Launch

View

2. Choose Next.
3. On the Specify Details page, in the Stack Name field, either choose to keep the default value or
specify your own value. Choose Next.
4. On the Options page, you don’t need to make any selections. Choose Next.
5. On the Review page, scroll down and choose the I acknowledge that AWS CloudFormation might
create IAM resources option.
6. Choose Create.

AWS CloudFormation shows the CREATE_IN_PROGRESS status for approximately three minutes.
The status changes to CREATE_COMPLETE after the stack has been created.

429
 AWS Systems Manager User Guide
Automation Walkthroughs

7. In the stack list, choose the option next to the stack you just created, and then choose the Outputs
tab.
8. Copy the Value. The is the ARN of the AssumeRole. You will specify this ARN when you run the
Automation.

Note
This procedure creates an AWS CloudFormation stack in the US East (Ohio) Region (us-east-2),
but the IAM role created by this process is a global resource available in all Regions.

Running the Automation

The following procedure describes how to run the AWSSupport-ResetAccess document by using the
AWS Systems Manager console.
Important
The following Automation execution stops the instance. Stopping the instance can result in lost
data on attached instance store volumes (if present). Stopping the instance can also cause the
public IP to change, if no Elastic IP is associated. To avoid these configuration changes, use Run
Command to reset access. For more information, see Using EC2Rescue for Windows Server with
Systems Manager Run Command in the Amazon EC2 User Guide for Windows Instances.

To run the AWSSupport-ResetAccess Automation

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Automation.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Automation.
3. Choose Execute automation.
4. In the Document name section, choose Owned by Me or Amazon from the list.
5. In the documents list, choose AWSSupport-ResetAccess. The document owner is Amazon.
6. In the Document details section verify that Document version is set to the highest default version.
For example, 4 (default).
7. In the Execution mode section, choose Simple Execution.
8. In the Input parameters section, specify the following parameters:

a. For InstanceID, specify the ID of the unreachable instance.

b. For EC2RescueInstanceType, specify an instance type for the EC2Rescue instance. The default
instance type is t2.small.
c. For SubnetId, specify a subnet in an existing VPC in the same availability zone as the instance
you specified. By default, Systems Manager creates a new VPC, but you can specify a subnet in
an existing VPC if you want.
Note
If you don't see the option to specify a subnet ID, verify that you are using the latest
Default version of the document.
d. For Assume Role, if you created roles for this Automation by using the CloudFormation
procedure described earlier in this topic, then specify the AssumeRole ARN that you copied from
the CloudFormation console.
9. Choose Execute.
10. To monitor the execution progress, choose the running Automation, and then choose the Steps
tab. When the execution is finished, choose the Descriptions tab, and then choose View output to

430
 AWS Systems Manager User Guide
Automation Walkthroughs

view the results. To view the output of individual steps, choose the Steps tab, and then choose View
Outputs next to a step.

The Automation creates a backup AMI and a password-enabled AMI as part of the workflow. All other
resources created by the Automation workflow are automatically deleted, but these AMIs remain in your
account. The AMIs are named using the following conventions:

• Backup AMI: AWSSupport-EC2Rescue:InstanceId

• Password-enabled AMI: AWSSupport-EC2Rescue: Password-enabled AMI from InstanceId

You can locate these AMIs by searching on the Automation execution ID.

For Linux, the new SSH private key for your instance is saved, encrypted, in Parameter Store. The
parameter name is /ec2rl/openssh/instance_id/key.

Using Automation with Jenkins

If your organization uses Jenkins software in a CI/CD pipeline, you can add Automation as a post-build
step to pre-install application releases into Amazon Machines Images (AMIs). You can also use the
Jenkins scheduling feature to call Automation and create your own operating system (OS) patching
cadence.

The example below shows how to invoke Automation from a Jenkins server that is running either on-
premises or in Amazon EC2. For authentication, the Jenkins server uses AWS credentials based on an
AWS Identity and Access Management (IAM) user that you create in the example. If your Jenkins server is
running in Amazon EC2, you can also authenticate it using an IAM instance profile role.
Note
Be sure to follow Jenkins security best-practices when configuring your instance.

Before You Begin

Complete the following tasks before you configure Automation with Jenkins.

• Complete the Simplify AMI Patching Using Automation, Lambda, and Parameter Store (p. 412)
example. The following example uses the UpdateMyLatestWindowsAmi automation document
created in that example.
• Configure IAM roles for Automation. Systems Manager requires an instance profile role and a
service role ARN to process Automation workflows. For more information, see Getting Started with
Automation (p. 144).
• After you configure IAM roles for Automation, use the following procedure to create an IAM user
account for your Jenkins server. The Automation workflow uses the IAM user account's Access key and
Secret key to authenticate the Jenkins server during execution.

To create a user account for the Jenkins server

1. From the Users page on the IAM console, choose Add User.
2. In the Set user details section, specify a user name (for example, Jenkins).
3. In the Select AWS access type section, choose Programmatic Access.
4. Choose Next:Permissions.
5. In the Set permissions for section, choose Attach existing policies directly.
6. In the filter field, type AmazonSSMFullAccess.
7. Choose the check box next to the policy, and then choose Next:Review.
8. Verify the details, and then choose Create.

431
 AWS Systems Manager User Guide
Automation Walkthroughs

9. Copy the Access and Secret keys to a text file. You will specify these credentials in the next
procedure.

Use the following procedure to configure the AWS CLI on your Jenkins server.

To configure the Jenkins server for Automation

1. If it's not already installed, download the AWS CLI to your Jenkins server. For more information, see
Installing the AWS Command Line Interface.
2. In a terminal window on your Jenkins server, run the following commands to configure the AWS CLI.

sudo su – jenkins
aws configure

For information, see Install or Upgrade the AWS CLI (p. 58).
3. When prompted, enter the AWS Access key and Secret key you received when you created the
Jenkins user in IAM. Specify a default region. For more information about configuring the AWS CLI
see Configuring the AWS Command Line Interface.

Use the following procedure to configure your Jenkins project to invoke Automation.

To configure your Jenkins server to invoke Automation

1. Open the Jenkins console in a web browser.

2. Choose the project that you want to configure with Automation, and then choose Configure.
3. On the Build tab, choose Add Build Step.
4. Choose Execute shell or Execute Windows batch command (depending on your operating system).
5. In the Command box, run an AWS CLI command like the following:

aws --region the AWS Region of your source AMI ssm start-automation-execution --
document-name your document name --parameters parameters for the document

The following example command uses the UpdateMyLatestWindowsAmi document and the
Systems Manager Parameter latestAmi created in Simplify AMI Patching Using Automation,
Lambda, and Parameter Store (p. 412):

aws --region region-id ssm start-automation-execution \

--document-name UpdateMyLatestWindowsAmi \
--parameters \
"sourceAMIid='{{ssm:latestAmi}}'"

In Jenkins, the command looks like the example in the following screenshot.

432
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

6. In the Jenkins project, choose Build Now. Jenkins returns output similar to the following example.

Troubleshooting Systems Manager Automation

Use the following information to help you troubleshoot problems with the Automation service. This
topic includes specific tasks to resolve issues based on Automation error messages.

Topics
• Common Automation Errors (p. 433)
• Automation Execution Failed to Start (p. 441)
• Execution Started, but Status is Failed (p. 442)
• Execution Started, but Timed Out (p. 443)

Common Automation Errors

This section includes information about common Automation errors.

VPC not defined 400

By default, when Automation runs either the AWS-UpdateLinuxAmi document or the AWS-
UpdateWindowsAmi document, the system creates a temporary instance in the default VPC
(172.30.0.0/16). If you deleted the default VPC, you will receive the following error:

VPC not defined 400

To solve this problem, you must create a new Automation document that includes the subnet ID. Copy a
sample document below that includes the subnet ID parameter and create a new document.

AWS-UpdateLinuxAmi

433
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

{
"schemaVersion":"0.3",
"description":"Updates AMI with Linux distribution packages and Amazon software.
For details,see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sysman-ami-
walkthrough.html",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"SourceAmiId":{
"type":"String",
"description":"(Required) The source Amazon Machine Image ID."
},
"IamInstanceProfileName":{
"type":"String",
"description":"(Required) The name of the role that enables Systems Manager (SSM)
to manage the instance.",
"default":"ManagedInstanceProfile"
},
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The ARN of the role that allows Automation to perform
the actions on your behalf.",
"default":"arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole"
},
"SubnetId":{
"type":"String",
"description":"(Required) The subnet that the created instance will be placed
into."
},
"TargetAmiName":{
"type":"String",
"description":"(Optional) The name of the new AMI that will be created. Default is
a system-generated string including the source AMI id, and the creation time and date.",
"default":"UpdateLinuxAmi_from_{{SourceAmiId}}_on_{{global:DATE_TIME}}"
},
"InstanceType":{
"type":"String",
"description":"(Optional) Type of instance to launch as the workspace host.
Instance types vary by region. Default is t2.micro.",
"default":"t2.micro"
},
"PreUpdateScript":{
"type":"String",
"description":"(Optional) URL of a script to run before updates are applied.
Default (\"none\") is to not run a script.",
"default":"none"
},
"PostUpdateScript":{
"type":"String",
"description":"(Optional) URL of a script to run after package updates are
applied. Default (\"none\") is to not run a script.",
"default":"none"
},
"IncludePackages":{
"type":"String",
"description":"(Optional) Only update these named packages. By default (\"all\"),
all available updates are applied.",
"default":"all"
},
"ExcludePackages":{
"type":"String",
"description":"(Optional) Names of packages to hold back from updates, under all
conditions. By default (\"none\"), no package is excluded.",
"default":"none"
}
},

434
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

"mainSteps":[
{
"name":"launchInstance",
"action":"aws:runInstances",
"maxAttempts":3,
"timeoutSeconds":1200,
"onFailure":"Abort",
"inputs":{
"ImageId":"{{SourceAmiId}}",
"InstanceType":"{{InstanceType}}",
"SubnetId":"{{ SubnetId }}",

"UserData":"IyEvYmluL2Jhc2gNCg0KZnVuY3Rpb24gZ2V0X2NvbnRlbnRzKCkgew0KICAgIGlmIFsgLXggIiQod2hpY2ggY3VybC
+ICIkU0NSSVBUX05BTUUiDQogIEZJTEVfU0laRT0kKGR1IC1rIC90bXAvJFNDUklQVF9OQU1FIHwgY3V0IC1mMSkNCiAgZWNobyBBV1
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"{{IamInstanceProfileName}}"
}
},
{
"name":"updateOSSoftware",
"action":"aws:runCommand",
"maxAttempts":3,
"timeoutSeconds":3600,
"onFailure":"Abort",
"inputs":{
"DocumentName":"AWS-RunShellScript",
"InstanceIds":[
"{{launchInstance.InstanceIds}}"
],
"Parameters":{
"commands":[
"set -e",
"[ -x \"$(which wget)\" ] && get_contents='wget $1 -O -'",
"[ -x \"$(which curl)\" ] && get_contents='curl -s -f $1'",
"eval $get_contents https://aws-ssm-downloads-
{{global:REGION}}.s3.amazonaws.com/scripts/aws-update-linux-instance > /tmp/aws-update-
linux-instance",
"chmod +x /tmp/aws-update-linux-instance",
"/tmp/aws-update-linux-instance --pre-update-script '{{PreUpdateScript}}'
--post-update-script '{{PostUpdateScript}}' --include-packages '{{IncludePackages}}' --
exclude-packages '{{ExcludePackages}}' 2>&1 | tee /tmp/aws-update-linux-instance.log"
]
}
}
},
{
"name":"stopInstance",
"action":"aws:changeInstanceState",
"maxAttempts":3,
"timeoutSeconds":1200,
"onFailure":"Abort",
"inputs":{
"InstanceIds":[
"{{launchInstance.InstanceIds}}"
],
"DesiredState":"stopped"
}
},
{
"name":"createImage",
"action":"aws:createImage",
"maxAttempts":3,
"onFailure":"Abort",
"inputs":{
"InstanceId":"{{launchInstance.InstanceIds}}",

435
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

"ImageName":"{{TargetAmiName}}",
"NoReboot":true,
"ImageDescription":"AMI Generated by EC2 Automation on {{global:DATE_TIME}}
from {{SourceAmiId}}"
}
},
{
"name":"terminateInstance",
"action":"aws:changeInstanceState",
"maxAttempts":3,
"onFailure":"Continue",
"inputs":{
"InstanceIds":[
"{{launchInstance.InstanceIds}}"
],
"DesiredState":"terminated"
}
}
],
"outputs":[
"createImage.ImageId"
]
}

AWS-UpdateWindowsAmi

{
"schemaVersion":"0.3",
"description":"Updates a Microsoft Windows AMI. By default it will install all Windows
updates, Amazon software, and Amazon drivers. It will then sysprep and create a new AMI.
Supports Windows Server 2008 R2 and greater.",
"assumeRole":"{{ AutomationAssumeRole }}",
"parameters":{
"SourceAmiId":{
"type":"String",
"description":"(Required) The source Amazon Machine Image ID."
},
"IamInstanceProfileName":{
"type":"String",
"description":"(Required) The name of the role that enables Systems Manager to
manage the instance.",
"default":"ManagedInstanceProfile"
},
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The ARN of the role that allows Automation to perform
the actions on your behalf.",
"default":"arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole"
},
"SubnetId": {
"type": "String",
"description": "(Required) The subnet that the created instance will be placed
into."
},
"TargetAmiName":{
"type":"String",
"description":"(Optional) The name of the new AMI that will be created. Default is
a system-generated string including the source AMI id, and the creation time and date.",
"default":"UpdateWindowsAmi_from_{{SourceAmiId}}_on_{{global:DATE_TIME}}"
},
"InstanceType":{
"type":"String",
"description":"(Optional) Type of instance to launch as the workspace host.
Instance types vary by region. Default is t2.medium.",
"default":"t2.medium"

436
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

},
"IncludeKbs":{
"type":"String",
"description":"(Optional) Specify one or more Microsoft Knowledge Base (KB)
article IDs to include. You can install multiple IDs using comma-separated values. When
specified, the categories and security level values are ignored. Valid formats: KB9876543
or 9876543.",
"default":""
},
"ExcludeKbs":{
"type":"String",
"description":"(Optional) Specify one or more Microsoft Knowledge Base (KB)
article IDs to exclude. You can exclude multiple IDs using comma-separated values. When
specified, all these KBs are excluded from install process. Valid formats: KB9876543 or
9876543.",
"default":""
},
"Categories":{
"type":"String",
"description":"(Optional) Specify one or more update categories. You can filter
categories using comma-separated values. By default patches for all categories are
selected. If value supplied, the update list is filtered by those values. Options:
Critical Update, Security Update, Definition Update, Update Rollup, Service Pack, Tool,
Update or Driver. Valid formats include a single entry, for example: Critical Update. Or,
you can specify a comma separated list: Critical Update,Security Update,Definition Update.
NOTE: There cannot be any spaces around the commas.",
"default":""
},
"SeverityLevels":{
"type":"String",
"description":"(Optional) Specify one or more MSRC severity levels associated with
an update. You can filter severity levels using comma-separated values. By default patches
for all security levels are selected. If value supplied, the update list is filtered by
those values. Options: Critical, Important, Low, Moderate or Unspecified. Valid formats
include a single entry, for example: Critical. Or, you can specify a comma separated list:
Critical,Important,Low.",
"default":""
},
"PreUpdateScript":{
"type":"String",
"description":"(Optional) A script provided as a string. It will run prior to
installing OS updates.",
"default":""
},
"PostUpdateScript":{
"type":"String",
"description":"(Optional) A script provided as a string. It will run after
installing OS updates.",
"default":""
}
},
"mainSteps":[
{
"name":"LaunchInstance",
"action":"aws:runInstances",
"timeoutSeconds":1800,
"maxAttempts":3,
"onFailure":"Abort",
"inputs":{
"ImageId":"{{ SourceAmiId }}",
"InstanceType":"{{ InstanceType }}",
"SubnetId":"{{ SubnetId }}",
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"{{ IamInstanceProfileName }}"
}

437
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

},
{
"name":"RunPreUpdateScript",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":1800,
"inputs":{
"DocumentName":"AWS-RunPowerShellScript",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"commands":"{{ PreUpdateScript }}"
}
}
},
{
"name":"UpdateSSMAgent",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":600,
"inputs":{
"DocumentName":"AWS-UpdateSSMAgent",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
]
}
},
{
"name":"UpdateEC2Config",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-InstallPowerShellModule",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"executionTimeout":"7200",
"source":"https://aws-ssm-downloads-{{global:REGION}}.s3.amazonaws.com/
PSModules/AWSUpdateWindowsInstance/Latest/AWSUpdateWindowsInstance.zip",

"sourceHash":"14CAD416F4A054894EBD2091EA4B99E542368BE5895BDD466B567C1ABA87C87C",
"commands":[
"Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force",
"Import-Module AWSUpdateWindowsInstance",
"if ([Environment]::OSVersion.Version.Major -ge 10) {",
" Install-AwsUwiEC2Launch -Id {{ automation:EXECUTION_ID }}",
"} else {",
" Install-AwsUwiEC2Config -Id {{ automation:EXECUTION_ID }}",
"}"
]
}
}
},
{
"name":"UpdateAWSPVDriver",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":600,
"inputs":{

438
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

"DocumentName":"AWS-ConfigureAWSPackage",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"name":"AWSPVDriver",
"action":"Install"
}
}
},
{
"name":"InstallWindowsUpdates",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":14400,
"inputs":{
"DocumentName":"AWS-InstallWindowsUpdates",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"Action":"Install",
"IncludeKbs":"{{ IncludeKbs }}",
"ExcludeKbs":"{{ ExcludeKbs }}",
"Categories":"{{ Categories }}",
"SeverityLevels":"{{ SeverityLevels }}"
}
}
},
{
"name":"RunPostUpdateScript",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":1800,
"inputs":{
"DocumentName":"AWS-RunPowerShellScript",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"commands":"{{ PostUpdateScript }}"
}
}
},
{
"name":"RunSysprepGeneralize",
"action":"aws:runCommand",
"maxAttempts":3,
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-InstallPowerShellModule",
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"Parameters":{
"executionTimeout":"7200",
"source":"https://aws-ssm-downloads-{{global:REGION}}.s3.amazonaws.com/
PSModules/AWSUpdateWindowsInstance/Latest/AWSUpdateWindowsInstance.zip",

"sourceHash":"14CAD416F4A054894EBD2091EA4B99E542368BE5895BDD466B567C1ABA87C87C",
"commands":[
"Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force",
"Import-Module AWSUpdateWindowsInstance",

439
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

"Start-AwsUwiSysprep -Id {{ automation:EXECUTION_ID }}"

]
}
}
},
{
"name":"StopInstance",
"action":"aws:changeInstanceState",
"maxAttempts":3,
"timeoutSeconds":7200,
"onFailure":"Abort",
"inputs":{
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"CheckStateOnly":false,
"DesiredState":"stopped"
}
},
{
"name":"CreateImage",
"action":"aws:createImage",
"maxAttempts":3,
"onFailure":"Abort",
"inputs":{
"InstanceId":"{{ LaunchInstance.InstanceIds }}",
"ImageName":"{{ TargetAmiName }}",
"NoReboot":true,
"ImageDescription":"Test CreateImage Description"
}
},
{
"name":"CreateTags",
"action":"aws:createTags",
"maxAttempts":3,
"onFailure":"Abort",
"inputs":{
"ResourceType":"EC2",
"ResourceIds":[
"{{ CreateImage.ImageId }}"
],
"Tags":[
{
"Key":"Original_AMI_ID",
"Value":"Created from {{ SourceAmiId }}"
}
]
}
},
{
"name":"TerminateInstance",
"action":"aws:changeInstanceState",
"maxAttempts":3,
"onFailure":"Abort",
"inputs":{
"InstanceIds":[
"{{ LaunchInstance.InstanceIds }}"
],
"DesiredState":"terminated"
}
}
],
"outputs":[
"CreateImage.ImageId"
]

440
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

Automation Execution Failed to Start

An Automation execution can fail with an access denied error or an invalid assume role error if you have
not properly configured IAM users, roles, and policies for Automation.

Access Denied
The following examples describe situations when an Automation execution failed to start with an access
denied error.

Access Denied to Systems Manager API

Error message: User: user arn is not authorized to perform:

ssm:StartAutomationExecution on resource: document arn (Service:
AWSSimpleSystemsManagement; Status Code: 400; Error Code:
AccessDeniedException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

• Possible cause 1: The IAM user attempting to start the Automation execution does not have permission
to invoke the StartAutomationExecution API. To resolve this issue, attach the required IAM policy
to the user account that was used to start the execution. For more information, see Task 4: Configure
User Access to Automation (p. 150).
• Possible cause 2: The IAM user attempting to start the Automation execution has permission to invoke
the StartAutomationExecution API, but does not have permission to invoke the API by using
the specific Automation document. To resolve this issue, attach the required IAM policy to the user
account that was used to start the execution. For more information, see Task 4: Configure User Access
to Automation (p. 150).

Access Denied Because of Missing PassRole Permissions

Error message: User: user arn is not authorized to perform: iam:PassRole on

resource: automation assume role arn (Service: AWSSimpleSystemsManagement;
Status Code: 400; Error Code: AccessDeniedException; Request ID: xxxxxxxx-xxxx-
xxxx-xxxx-xxxxxxxxxxxx)

The IAM user attempting to start the Automation execution does not have PassRole permission for the
assume role. To resolve this issue, attach the iam:PassRole policy to the role of the IAM user attempting
to start the Automation execution. For more information, see Task 3: Attach the iam:PassRole Policy to
Your Automation Role (p. 149).

Invalid Assume Role

When you run an Automation, an assume role is either provided in the document or passed as a
parameter value for the document. Different types of errors can occur if the assume role is not specified
or configured properly.

Malformed Assume Role

Error message: The format of the supplied assume role ARN is invalid. The assume
role is improperly formatted. To resolve this issue, verify that a valid assume role is specified in your
Automation document or as a runtime parameter when running the Automation.

Assume Role Can't Be Assumed

Error message: The defined assume role is unable to be assumed.

(Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code:
InvalidAutomationExecutionParametersException; Request ID: xxxxxxxx-xxxx-xxxx-
xxxx-xxxxxxxxxxxx)

441
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

• Possible cause 1: The assume role does not exist. To resolve this issue, create the role. For more
information, see the section called “Getting Started with Automation” (p. 144). Specific details
for creating this role are described in the following topic, Task 1: Create a Service Role for
Automation (p. 147).
• Possible cause 2: The assume role does not have a trust relationship with the Systems Manager service.
To resolve this issue, create the trust relationship. For more information, see Task 2: Add a Trust
Relationship for Automation (p. 148).

Execution Started, but Status is Failed

Action-Specific Failures
Automation documents contain steps and steps run in order. Each step invokes one or more AWS service
APIs. The APIs determine the inputs, behavior, and outputs of the step. There are multiple places where
an error can cause a step to fail. Failure messages indicate when and where an error occurred.

To see a failure message in the EC2 console, choose the View Outputs link of the failed step. To
see a failure message from the AWS CLI, call get-automation-execution and look for the
FailureMessage attribute in a failed StepExecution.

In the following examples, a step associated with the aws:runInstance action failed. Each example
explores a different type of error.

Missing Image

Error message: Automation Step Execution fails when it is launching the

instance(s). Get Exception from RunInstances API of ec2 Service. Exception
Message from RunInstances API: [The image id '[ami id]' does not exist
(Service: AmazonEC2; Status Code: 400; Error Code: InvalidAMIID.NotFound;
Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation
Service Troubleshooting Guide for more diagnosis details.

The aws:runInstances action received input for an ImageId that doesn't exist. To resolve this
problem, update the automation document or parameter values with the correct AMI ID.

Assume Role Policy Doesn't Have Sufficient Permissions

Error message: Automation Step Execution fails when it is launching the

instance(s). Get Exception from RunInstances API of ec2 Service. Exception
Message from RunInstances API: [You are not authorized to perform this
operation. Encoded authorization failure message: xxxxxxx (Service: AmazonEC2;
Status Code: 403; Error Code: UnauthorizedOperation; Request ID: xxxxxxxx-xxxx-
xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation Service Troubleshooting
Guide for more diagnosis details.

The assume role doesn't have sufficient permission to invoke the RunInstances API on Amazon EC2
instances. To resolve this problem, attach an IAM policy to the assume role that has permission to
invoke the RunInstances API. For more information, see the Method 2: Use IAM to Configure Roles for
Automation (p. 146).

Unexpected State

Error message: Step fails when it is verifying launched instance(s) are ready to
be used. Instance i-xxxxxxxxx entered unexpected state: shutting-down. Please
refer to Automation Service Troubleshooting Guide for more diagnosis details.

• Possible cause 1: There is a problem with the instance or the Amazon EC2 service. To resolve this
problem, login to the instance or review the instance system log to understand why the instance
started shutting down.

442
 AWS Systems Manager User Guide
Troubleshooting Systems Manager Automation

• Possible cause 2: The user data script specified for the aws:runInstances action has a problem or
incorrect syntax. Verify the syntax of the user data script. Also, verify that the user data scripts doesn't
shut down the instance, or invoke other scripts that shut down the instance.

Action-Specific Failures Reference

When a step fails, the failure message might indicate which service was being invoked when the failure
occurred. The following table lists the services invoked by each action. The table also provides links to
information about each service.

Action AWS Service(s) Invoked For Information About Troubleshooting

by This Action This Service Content

aws:runInstances Amazon EC2 Amazon EC2 User Guide Troubleshooting EC2

Instances

aws:changeInstanceState Amazon EC2 Amazon EC2 User Guide Troubleshooting EC2

Instances

aws:runCommand Systems Manager AWS Systems Troubleshooting

Manager Run Systems Manager Run
Command (p. 613) Command (p. 642)

aws:createImage Amazon EC2 Amazon Machines  

Images

aws:createStack AWS CloudFormation AWS CloudFormation Troubleshooting AWS

User Guide CloudFormation

aws:deleteStack AWS CloudFormation AWS CloudFormation Troubleshooting AWS

User Guide CloudFormation

aws:deleteImage Amazon EC2 Amazon Machines  

Images

aws:copyImage Amazon EC2 Amazon Machines  

Images

aws:createTag Amazon EC2, Systems EC2 Resource and Tags  

Manager

aws:invokeLambdaFunction
AWS Lambda AWS Lambda Developer Troublshooting Lambda
Guide

Automation Service Internal Error

Error message: Internal Server Error. Please refer to Automation Service
Troubleshooting Guide for more diagnosis details.

A problem with the Automation service is preventing the specified Automation document from running
correctly. To resolve this issue, contact AWS Support. Provide the execution ID and customer ID, if
available.

Execution Started, but Timed Out

Error message: Step timed out while step is verifying launched instance(s) are
ready to be used. Please refer to Automation Service Troubleshooting Guide for
more diagnosis details.

443
 AWS Systems Manager User Guide
Maintenance Windows

A step in the aws:runInstances action timed out. This can happen if the step action takes longer to
run than the value specified for timeoutSeconds in the step. To resolve this issue, specify a longer
value for timeoutSeconds. If that does not solve the problem, investigate why the step takes longer to
run than expected.

AWS Systems Manager Maintenance Windows

AWS Systems Manager Maintenance Windows let you define a schedule for when to perform potentially
disruptive actions on your instances such as patching an operating system, updating drivers, or installing
software or patches. Maintenance Windows also lets you schedule actions on numerous other AWS
resource types, such as Amazon Simple Storage Service (Amazon S3) buckets, Amazon Simple Queue
Service (Amazon SQS) queues, AWS Key Management Service (AWS KMS) keys, and many more. For a full
list of supported resource types that you can include in a maintenance window target, see Supported
Resources for AWS Resource Groups in the AWS Resource Groups User Guide.

Each maintenance window has a schedule, a maximum duration, a set of registered targets (the instances
or other AWS resources that are acted upon), and a set of registered tasks. You can add tags to your
maintenance windows when you create or update them. (Tags are keys that help identify and sort your
resources within your organization.) You can also specify dates that a maintenance window should not
run before or after, and you can specify the international time zone on which to base the maintenance
window schedule. (For an explanation of how the various schedule-related options for maintenance
windows relate to one another, see Reference: Maintenance Windows Scheduling and Active Period
Options (p. 939).)

Maintenance windows support running four types of tasks:

• Systems Manager Run Command commands

For more information about Run Command, see AWS Systems Manager Run Command (p. 613).
• Systems Manager Automation workflows

For more information about Automation workflows, see AWS Systems Manager Automation (p. 142).
• AWS Lambda functions

For more information about Lambda functions, see Working with Lambda Functions in the AWS
Lambda Developer Guide.
• AWS Step Functions tasks

For more information about Step Functions, see the AWS Step Functions Developer Guide.

This means you can use maintenance windows to perform tasks like the following on your selected
targets:

• Install or update applications.

• Apply patches.
• Install or update SSM Agent.
• Run PowerShell commands and Linux shell scripts by using a Systems Manager Run Command task.
• Build Amazon Machine Images (AMIs), boot-strap software, and configure instances by using a Systems
Manager Automation task.
• Run AWS Lambda functions that trigger additional actions, such as scanning your instances for patch
updates.
• Run AWS Step Functions state machines to perform tasks such as removing an instance from an Elastic
Load Balancing environment, patching the instance, and then adding the instance back to the Elastic
Load Balancing environment.

444
 AWS Systems Manager User Guide
Controlling Access

• Target instances that are offline by specifying an AWS resource group as the target.

Contents
• Controlling Access to Maintenance Windows (p. 445)
• Working with Maintenance Windows (Console) (p. 455)
• Systems Manager Maintenance Windows Tutorials (AWS CLI) (p. 461)
• Maintenance Windows Walkthroughs (p. 496)

Controlling Access to Maintenance Windows

Before users in your account can create and schedule maintenance window tasks, they must be granted
the necessary permissions. To grant these permissions to users, an administrator must perform these two
tasks:

Task 1: Configure instance permissions

Provide the Maintenance Windows service with the AWS Identity and Access Management (IAM)
permissions needed to run maintenance window tasks on your instances by doing one of the following:

• Create a custom service role for maintenance window tasks

• Create a service-linked role for Systems Manager

You specify one of these roles as part of the configuration when you create a maintenance window task.
This allows Systems Manager to run tasks in maintenance windows on your behalf.
Note
A service-linked role for Systems Manager might already have been created in your account.
Currently, the service-linked role also provides permissions for the Inventory capability.

To help you decide whether to use a custom service role or the Systems Manager service-linked role with
a maintenance window task, see Should I Use a Service-Linked Role or a Custom Service Role to Run
Maintenance Window Tasks? (p. 445).

Task 2: Configure user permissions

Granting iam:PassRole permissions to the users in your account who assigns tasks to maintenance
windows. This allows them to pass the role to the maintenance window service. Without this explicit
permission, a user can't assign tasks to a maintenance window.

Should I Use a Service-Linked Role or a Custom Service Role to

Run Maintenance Window Tasks?
To run maintenance tasks on your target instances, the Maintenance Windows service must have
permission to access and run tasks on your instances. You can provide this permission by specifying
either the Systems Manager service-linked role or a custom service role as part of a task configuration.

The type of role you should choose depends on the following factors:

Custom service role: Use a custom service role for maintenance window tasks in these cases:

• If you want to use Amazon Simple Notification Service (Amazon SNS) to send notifications related to
maintenance window tasks run through Run Command. You can enable SNS notifications when you
create a maintenance window task.
• If you want to use a more restrictive set of permissions than those provided by the service-linked role.
The service-linked role supports very limited resource-level constraints. For example, say you want
to allow maintenance window tasks to run on a limited set of instances, or you want to allow only

445
 AWS Systems Manager User Guide
Controlling Access

certain SSM documents run on your target instances. In these cases, you specify stricter permissions in
a custom service role.
• If you need a more permissive or expanded set of permissions than those provided by the service-
linked role. Some actions in Automation documents require expanded permissions.

For example, some Automation actions work with AWS CloudFormation stacks. Therefore, the
permissions cloudformation:CreateStack, cloudformation:DescribeStack, and
cloudformation:DeleteStack are required.

Another example: the Automation document AWS-CopySnapshot requires permission to create an

Amazon Elastic Block Store (Amazon EBS) snapshot, and so the service role needs the permission
ec2:CreateSnapshot. This permission isn't included in the service-linked role for Systems Manager.

For information about the role permissions needed by Automation documents, see the document
descriptions in Systems Manager Automation Document Details Reference (p. 294).

Systems Manager service-linked role: We recommend that you use a Systems Manager service-linked
role in all other cases.

For more information about the Systems Manager service-linked role, see Service-Linked Role
Permissions for Systems Manager (p. 919).

Topics
• Control Access to Maintenance Windows (Console) (p. 446)
• Control Access to Maintenance Windows (AWS CLI) (p. 449)
• Control Access to Maintenance Windows (Tools for Windows PowerShell) (p. 452)
• Troubleshooting IAM Maintenance Window Permissions (p. 455)

Control Access to Maintenance Windows (Console)

The following procedures describe how to use the AWS Systems Manager console to create the required
roles and permissions for maintenance windows.

Topics
• Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (Console) (p. 446)
• Task 2: Assign the IAM PassRole Policy to an IAM User or Group (Console) (p. 448)

Task 1: (Optional) Create a Custom Service Role for Maintenance Windows

(Console)
Use the following procedure to create a custom service role for the Maintenance Windows capability so
that Systems Manager can run tasks on your behalf.
Important
A custom service role is not required if you choose to use a Systems Manager service-linked
role to let maintenance windows run tasks on your behalf instead. If you do not have a Systems
Manager service-linked role in your account, you can create it when you create or update a
maintenance window task using the Systems Manager console. For more information, see the
following topics:

• Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance Window
Tasks? (p. 445)
• Service-Linked Role Permissions for Systems Manager (p. 919)
• Assign Tasks to a Maintenance Window (Console) (p. 458)

446
 AWS Systems Manager User Guide
Controlling Access

To create a custom service role (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create role.
3. Mark the following selections:

1. Select type of trusted entity area: AWS service

2. Choose the service that will use this role area: EC2
3. Select your use case area: EC2
4. Choose Next: Permissions.
5. In the list of policies, select the box next to AmazonSSMMaintenanceWindowRole, and then choose
Next: Review.
6. In Role name, enter a name that identifies this role as a Maintenance Windows role; for example my-
maintenance-window-role.
7. Optional: Change the default role description to reflect the purpose of this role. For example:
"Performs Maintenance Window tasks on your behalf."
8. Choose Create role. The system returns you to the Roles page.
9. Choose the name of the role you just created.
10. Choose the Trust relationships tab, and then choose Edit trust relationship.
11. Delete the current policy, and then copy and paste the following policy into the Policy Document
field:

{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"",
"Effect":"Allow",
"Principal":{
"Service":[
"ssm.amazonaws.com",
"sns.amazonaws.com"
]
},
"Action":"sts:AssumeRole"
}
]
}

Note
"sns.amazonaws.com" is required only if you plan to use Amazon SNS to send
notifications related to maintenance window tasks run through Run Command. See step 13
below for more information.
12. Choose Update Trust Policy, and then copy or make a note of the role name and the Role ARN
value on the Summary page. You specify this information when you create your maintenance
window.
13. If you plan to configure a maintenance window to send notifications about command statuses using
Amazon SNS, when run through a Run Command command task, do the following:

1. Choose the Permissions tab.

2. Choose Add inline policy, and then choose the JSON tab.
3. In Policy Document, paste the following:

{
"Version": "2012-10-17",

447
 AWS Systems Manager User Guide
Controlling Access

"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "sns-access-role-arn"
}
]
}

sns-access-role-arn represents the ARN of the existing IAM role to be for sending SNS
notifications related to the maintenance window, in the format of arn:aws:iam::account-
id:role/role-name. For example: arn:aws:iam::111222333444:role/my-sns-access-
role.
Note
In the Systems Manager console, this ARN is selected in the IAM Role list on the Register
run command task page. For information, see Assign Tasks to a Maintenance Window
(Console) (p. 458). In the Systems Manager API, this ARN is entered as the value of
ServiceRoleArn in the SendCommand request.
4. Choose Review policy.
5. For Name, enter a name to identify this as a policy to allow sending Amazon SNS notifications.
14. Choose Create policy.

Task 2: Assign the IAM PassRole Policy to an IAM User or Group (Console)
When you register a task with a maintenance window, you specify either a custom service role or a
Systems Manager service-linked role to run the actual task operations. This is the role that the service
assumes when it runs tasks on your behalf. Before that, to register the task itself, you must assign the
IAM PassRole policy to an IAM user account or an IAM group. This allows the IAM user or IAM group to
specify, as part of registering those tasks with the maintenance window, the role that should be used
when running tasks. For information, see Granting a User Permissions to Pass a Role to an AWS Service in
the IAM User Guide.

Depending on whether you are assigning the iam: Passrole permission to an individual user or a
group, use one of the following procedures to provide the minimum permissions required to register
tasks with a maintenance window.

To assign the IAM PassRole policy to an IAM user account (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. Choose Users, and then choose the name of the user account you want to update.
3. On the Permissions tabs, in the policies list, verify that the AmazonSSMFullAccess policy is listed,
or that there is a comparable policy that gives the IAM user permission to call the Systems Manager
API. Add the permission if it is not included already. For information, see Adding and Removing IAM
Policies (Console) in the IAM User Guide.
4. Choose Add inline policy.
5. On the Create policy page, on the Visual edtior tab, in the Select a service area, choose IAM.
6. In the Actions area, choose PassRole.
Tip
Type passr in the filter box to quickly locate PassRole.
7. Choose the Resources line, and then choose Add ARN.
8. For Specify ARN for role, paste the role ARN you created in the previous procedure, and then choose
Save changes.
9. Choose Review policy.

448
 AWS Systems Manager User Guide
Controlling Access

10. On the Review policy page, enter a name in the Name box to identify this PassRole policy, and then
choose Create policy.

To assign the IAM PassRole policy to an IAM group (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Groups.
3. In the list of groups, select the name of the group you want to assign the iam:PassRole
permission to.
4. In the Inline Policies area, do one of the following:

• If no inline policies have been added yet, choose click here.

• If one or more inline policies have been added, choose Create Group Policy.
5. Select Policy Generator, and then choose Select.
6. Make the following selections:

1. Effect: Allow
2. AWS Service: Identity and Access Management
3. Actions: PassRole
4. Amazon Resource Name (ARN): Enter the ARN of the maintenance window role you created in
Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (Console) (p. 446)
7. Choose Add Statement, and then choose Next Step.
8. Choose Apply Policy.

Control Access to Maintenance Windows (AWS CLI)

The following procedures describe how to use the AWS CLI to create the required roles and permissions
for Maintenance Windows.

Topics
• Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (AWS CLI) (p. 449)
• Task 2: Assign the IAM PassRole Policy to an IAM User or Group (p. 451)

Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (AWS
CLI)
Important
A custom service role is not required if you choose to use a Systems Manager service-linked
role to let maintenance windows run tasks on your behalf instead. If you do not have a Systems
Manager service-linked role in your account, you can create it when you create or update a
maintenance window task using the Systems Manager console. For more information, see the
following topics:

• Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance Window
Tasks? (p. 445)
• Service-Linked Role Permissions for Systems Manager (p. 919)
• Assign Tasks to a Maintenance Window (Console) (p. 458)

1. Copy and paste the following trust policy into a text file. Save the file with the following name and
file extension: mw-role-trust-policy.json.

449
 AWS Systems Manager User Guide
Controlling Access

Note
"sns.amazonaws.com" is required only if you plan to use Amazon SNS to send
notifications related to maintenance window tasks run through the SendCommand API or
send-command in the AWS CLI.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":[
"ssm.amazonaws.com",
"sns.amazonaws.com"
]
},
"Action":"sts:AssumeRole"
}
]
}

2. Open the AWS CLI and run the following command in the directory where you placed mw-role-
trust-policy.json in order to create a maintenance window role called mw-task-role. The
command assigns the policy you created in the previous step to this role:

aws iam create-role --role-name mw-task-role --assume-role-policy-document file://mw-

role-trust-policy.json

The system returns information like the following:

{
"Role":{
"AssumeRolePolicyDocument":{
"Version":"2012-10-17",
"Statement":[
{
"Action":"sts:AssumeRole",
"Effect":"Allow",
"Principal":{
"Service":[
"ssm.amazonaws.com",
"ec2.amazonaws.com",
"sns.amazonaws.com"
]
}
}
]
},
"RoleId":"AROAIIZKPBKS2LEXAMPLE",
"CreateDate":"2017-04-04T03:40:17.373Z",
"RoleName":"mw-task-role",
"Path":"/",
"Arn":"arn:aws:iam::123456789012:role/mw-task-role"
}
}

Note
Make a note of the RoleName and the Arn. You specify these when you create a
maintenance window.

450
 AWS Systems Manager User Guide
Controlling Access

3. Run the following command to attach the AmazonSSMMaintenanceWindowRole managed policy

to the role you created in step 2:

aws iam attach-role-policy --role-name mw-task-role --policy-arn

arn:aws:iam::aws:policy/service-role/AmazonSSMMaintenanceWindowRole

Task 2: Assign the IAM PassRole Policy to an IAM User or Group

When you register a task with a maintenance window, you specify either a custom service role or a
Systems Manager service-linked role to run the actual task operations. This is the role that the service
assumes when it runs tasks on your behalf. Before that, to register the task itself, you must assign the
IAM PassRole policy to an IAM user account or an IAM group. This allows the IAM user or IAM group to
specify, as part of registering those tasks with the maintenance window, the role that should be used
when running tasks. For information, see Granting a User Permissions to Pass a Role to an AWS Service in
the IAM User Guide.

To assign the IAM PassRole policy to an IAM user account or group (AWS CLI)

1. Copy and paste the following IAM policy into a text editor and save it with the following name and
file extension: mw-passrole-policy.json.

{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"Stmt1491345526000",
"Effect":"Allow",
"Action":[
"iam:GetRole",
"iam:PassRole",
"ssm:RegisterTaskWithMaintenanceWindow"
],
"Resource":[
"*"
]
}
]
}

2. Open the AWS CLI.

3. Depending on whether you are assigning the permission to an IAM user or group, run one of the
following commands.

• For an IAM user:

aws iam put-user-policy --user-name user-name --policy-name "policy-name" --policy-

document path-to-document

For user-name, specify the IAM user who assigns tasks to maintenance windows. For policy-
name, specify the name you want to use to identify the policy. For path-to-document, specify
the path to the file you saved in step 1. For example: file://C:\Temp\mw-passrole-
policy.json
Note
If you plan to register tasks for maintenance windows using the AWS Systems Manager
console, you must also assign the AmazonSSMFullAccess policy to your user account.
Run the following command to assign this policy to your account:

451
 AWS Systems Manager User Guide
Controlling Access

aws iam attach-user-policy --policy-arn arn:aws:iam::aws:policy/

AmazonSSMFullAccess --user-name user-name

• For an IAM group:

aws iam put-group-policy --group-name group-name --policy-name "policy-name" --

policy-document path-to-document

For group-name, specify the IAM group whose members assign tasks to maintenance windows.
For policy-name, specify the name you want to use to identify the policy. For path-to-
document, specify the path to the file you saved in step 1. For example: file://C:\Temp\mw-
passrole-policy.json
Note
If you plan to register tasks for maintenance windows using the AWS Systems Manager
console, you must also assign the AmazonSSMFullAccess policy to your group. Run the
following command to assign this policy to your group:

aws iam attach-group-policy --policy-arn arn:aws:iam::aws:policy/

AmazonSSMFullAccess --group-name group-name

4. Run the following command to verify that the policy has been assigned to the group:

aws iam list-group-policies --group-name group-name

Control Access to Maintenance Windows (Tools for Windows

PowerShell)
The following procedures describe how to use the Tools for Windows PowerShell to create the required
roles and permissions for the Maintenance Windows capability.

Topics
• Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (AWS CLI) (p. 452)
• Task 2: Assign the IAM PassRole Policy to an IAM User or Group (AWS CLI) (p. 453)

Task 1: (Optional) Create a Custom Service Role for Maintenance Windows (AWS
CLI)

Important
A custom service role is not required if you choose to use a Systems Manager service-linked
role to let maintenance windows run tasks on your behalf instead. If you do not have a Systems
Manager service-linked role in your account, you can create it when you create or update a
maintenance window task using the Systems Manager console. For more information, see the
following topics:

• Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance Window
Tasks? (p. 445)
• Service-Linked Role Permissions for Systems Manager (p. 919)
• Assign Tasks to a Maintenance Window (Console) (p. 458)

452
 AWS Systems Manager User Guide
Controlling Access

1. Copy and paste the following trust policy into a text file. Save the file with the following name and
file extension: mw-role-trust-policy.json.
Note
"sns.amazonaws.com" is required only if you plan to use Amazon SNS to send
notifications related to maintenance window tasks run through the SendCommand API.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Principal":{
"Service":[
"ssm.amazonaws.com",
"sns.amazonaws.com"
]
},
"Action":"sts:AssumeRole"
}
]
}

2. Open Tools for Windows PowerShell and run the following command to create a role with a name
that identifies this role as a maintenance window role; for example my-maintenance-window-
role. The role uses the policy that you created in the previous step:

New-IAMRole -RoleName "mw-task-role" -AssumeRolePolicyDocument (Get-Content -raw .\mw-

role-trust-policy.json)

The system returns information like the following.

Arn : arn:aws:iam::123456789012:role/mw-task-role
AssumeRolePolicyDocument : ExampleDoc12345678
CreateDate : 4/4/2017 11:24:43
Path : /
RoleId : AROAIIZKPBKS2LEXAMPLE
RoleName : mw-task-role

3. Run the following command to attach the AmazonSSMMaintenanceWindowRole managed policy

to the role you created in the previous step:

Register-IAMRolePolicy -RoleName mw-task-role -PolicyArn

arn:aws:iam::aws:policy/service-role/AmazonSSMMaintenanceWindowRole

Task 2: Assign the IAM PassRole Policy to an IAM User or Group (AWS CLI)
When you register a task with a maintenance window, you specify either a custom service role or a
Systems Manager service-linked role to run the actual task operations. This is the role that the service
assumes when it runs tasks on your behalf. Before that, to register the task itself, you must assign the
IAM PassRole policy to an IAM user account or an IAM group. This allows the IAM user or IAM group to
specify, as part of registering those tasks with the maintenance window, the role that should be used
when running tasks. For information, see Granting a User Permissions to Pass a Role to an AWS Service in
the IAM User Guide.

1. Copy and paste the following IAM policy into a text editor and save it with the .json file extension.

453
 AWS Systems Manager User Guide
Controlling Access

"Version":"2012-10-17",
"Statement":[
{
"Sid":"Stmt1491345526000",
"Effect":"Allow",
"Action":[
"iam:GetRole",
"iam:PassRole",
"ssm:RegisterTaskWithMaintenanceWindow"
],
"Resource":[
"*"
]
}
]
}

2. Open Tools for Windows PowerShell.

3. Depending on whether you are assigning the permission to an IAM user or group, run one of the
following commands.

• For an IAM user:

Write-IAMUserPolicy -UserName user-name -PolicyDocument (Get-Content -raw path-to-

document) -PolicyName policy-name

For user-name, specify the IAM user who assigns tasks to maintenance windows. For policy-
name, specify the name you want to use to identify the policy. For path-to-document, specify
the path to the file you saved in step 1. For example: C:\temp\passrole-policy.json
Note
If you plan to register tasks for maintenance windows using the AWS Systems Manager
console, you must also assign the AmazonSSMFullAccess policy to your user account.
Run the following command to assign this policy to your account:

Register-IAMUserPolicy -UserName user-name -PolicyArn arn:aws:iam::aws:policy/

AmazonSSMFullAccess

• For an IAM group:

Write-IAMGroupPolicy -GroupName group-name -PolicyDocument (Get-Content -raw path-to-

document) -PolicyName policy-name

For group-name, specify the IAM group that assigns tasks to maintenance windows. For policy-
name, specify the name you want to use to identify the policy. For path-to-document, specify
the path to the file you saved in step 1. For example: C:\temp\passrole-policy.json

Note
If you plan to register tasks for maintenance windows using the AWS Systems Manager
console, you must also assign the AmazonSSMFullAccess policy to your user account. Run
the following command to assign this policy to your group:

Register-IAMGroupPolicy -GroupName group-name -PolicyArn

arn:aws:iam::aws:policy/AmazonSSMFullAccess

4. Run the following command to verify that the policy has been assigned to the group:

454
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

Get-IAMGroupPolicies -GroupName group-name

Troubleshooting IAM Maintenance Window Permissions

Use the following information to help you troubleshoot common issues with Maintenance Windows
permissions in AWS Systems Manager.

Edit Task Error: On the page for editing a maintenance window task, the IAM
role list returns an error message: "We couldn't find the IAM maintenance
window role specified for this task. It might have been deleted, or it might not
have been created yet."
Problem 1: The IAM maintenance window role you originally specified was deleted after you created the
task.

Possible fixes: (1) Select a different IAM maintenance window role, if one exists in your account, or
create a new one and select it for the task. (2) Create or select a Systems Manager service-linked role. For
more information, see Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance
Window Tasks? (p. 445).

Problem 2: If the task was created using the AWS CLI, Tools for Windows PowerShell, or an AWS SDK,
a non-existent IAM maintenance window role name could have been specified. For example, the IAM
maintenance window role could have been deleted before you created the task, or the role name could
have been typed incorrectly, such as myrole instead of my-role.

Possible fixes: (1) Select the correct name of the IAM maintenance window role you want to use, or
create a new one to specify for the task. (2) Create or select a Systems Manager service-linked role. For
more information, see Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance
Window Tasks? (p. 445).

Working with Maintenance Windows (Console)

This section describes how to create, configure, and update, and delete maintenance windows using the
Systems Manager console. This section also provides information about managing the targets and tasks
of a maintenance window.
Important
We recommend that you initially create and configure maintenance windows in a test
environment.

Before You Begin

Before you create a maintenance window, you must configure access to Maintenance Windows. For more
information, see Controlling Access to Maintenance Windows (p. 445).

Topics
• Create a Maintenance Window (Console) (p. 456)
• Assign Targets to a Maintenance Window (Console) (p. 457)
• Assign Tasks to a Maintenance Window (Console) (p. 458)
• Update or Delete a Maintenance Window (Console) (p. 460)

455
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

Create a Maintenance Window (Console)

In this procedure, you create a maintenance window and specify its basic options, such as name,
schedule, and duration. In later steps, you choose the targets, or resources, that it updates and the tasks
that run during the maintenance window execution.
Note
For an explanation of how the various schedule-related options for maintenance windows
relate to one another, see Reference: Maintenance Windows Scheduling and Active Period
Options (p. 939).

To create a Maintenance Window (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.
3. Choose Create a maintenance window.
4. For Name, enter a descriptive name to help you identify this maintenance window as a test
maintenance window.
5. For Description, enter a description.
6. Choose Allow unregistered targets if you want to allow a maintenance window task to run on
managed instances, even if you have not registered those instances as targets. If you choose this
option, then you can choose the unregistered instances (by instance ID) when you register a task
with the maintenance window.

If you don't choose this option, then you must choose previously-registered targets when you
register a task with the maintenance window.
7. Specify a schedule for the maintenance window by using one of the three scheduling options.

For information about building cron/rate expressions, see Reference: Cron and Rate Expressions for
Systems Manager (p. 933).
8. For Duration, enter the number of hours the maintenance window will run. The value you specify
determines the specific end time for the maintenance window based on the time it begins. No
maintenance window tasks are permitted to start after the resulting endtime minus the number of
hours you specify for Stop initiating tasks in the next step.

For example, if the maintenance window starts at 3 PM, the duration is three hours, and the Stop
initiating tasks value is one hour, no maintenance window tasks can start after 5 PM.
9. For Stop initiating tasks, enter the number of hours before the end of the maintenance window
that the system should stop scheduling new tasks to run.
10. (Optional) For Start date (optional), specify a date and time, in ISO-8601 Extended format, for
when you want the maintenance window to become active. This allows you to delay activation of
the maintenance window until the specified future date.
11. (Optional) For End date (optional), specify a date and time, in ISO-8601 Extended format, for when
you want the maintenance window to become inactive. This allows you to set a date and time in the
future after which the maintenance window no longer runs.
12. (Optional) For Time zone (optional), specify the time zone to base scheduled maintenance window
executions on, in Internet Assigned Numbers Authority (IANA) format. For example: "America/
Los_Angeles", "etc/UTC", or "Asia/Seoul".

For more information about valid formats, see the Time Zone Database on the IANA website.
13. (Optional) In the Manage tags area, apply one or more tag key name/value pairs to the maintenance
window.

Tags are optional metadata that you assign to a resource. Tags enable you to categorize a resource
in different ways, such as by purpose, owner, or environment. For example, you might want to tag a

456
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

maintenance window to identify the type of tasks it runs, the types of targets, and the environment
it runs in. In this case, you could specify the following key name/value pairs:

• Key=TaskType,Value=AgentUpdate
• Key=OS,Value=Windows
• Key=Environment,Value=Production
14. Choose Create maintenance window. The system returns you to the maintenance window page. The
state of the maintenance window you just created is Enabled.

Assign Targets to a Maintenance Window (Console)

In this procedure, you register a target with a maintenance window. In other words, you specify which
resources the maintenance window performs actions on.

To assign targets to a maintenance window (console)

1. In the list of maintenance windows, choose the maintenance window to add targets to.
2. Choose Actions, and then choose Register targets.
3. (Optional) For Target name, enter a name for the targets.
4. (Optional) For Description, enter a description.
5. (Optional) For Owner information, specify information to include in any CloudWatch Events raised
while running tasks for these targets in this maintenance window.

For information about using CloudWatch Events to monitor Systems Manager events, see
Monitoring Systems Manager Events with Amazon CloudWatch Events (p. 891).
6. In the Targets area, choose one of the options described in the following table.

Option Description

Specify instance tags For Instance tags, specify one or more tag
keys and (optional) values that have been or
will be added to managed instances in your
account. When the maintenance window runs,
it attempts to perform tasks on all of the
managed instances to which these tags have
been added.

Choose instances manually From the list, select the box for each instance
that you want to include in the maintenance
window target.

The list includes all instances in your account

that are configured for use with Systems
Manager.

If you don’t see an instance you want to include

in the target, verify that the required setup
steps have been completed:

• For Amazon EC2 instances, see Setting Up

AWS Systems Manager (p. 23).
• For on-premises instances and virtual
machines (VMs), see Setting Up AWS Systems
Manager for Hybrid Environments (p. 41)

457
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

Option Description

Choose resource groups For Resource group, choose the name of an

existing resource group in your account from
the list.

For information about creating and working

with resource groups, see the following topics:

• What is AWS Resource Groups? in the AWS

Resource Groups User Guide
• Resource Groups and Tagging for AWS in the
AWS News Blog

For Resource types, select up to five available

resource types, or choose All resource types.

If the tasks you assign to the maintenance

window do not act on one of the resource types
you added to the target, the system might
report an error. Tasks for which a supported
resource type is found continue to run despite
these errors.

For example, suppose you add the following

resource types to this target:

• AWS::S3::Bucket
• AWS::DynamoDB::Table
• AWS::EC2::Instance

But later, when you add tasks to the

maintenance window, you include only tasks
that perform actions on instances, such as
applying a patch baseline or rebooting an
instance. In the maintenancewindow log, an
error might be reported for no S3 buckets or
DynamoDB tables being found. However, the
maintenance window still runs tasks on the
instances in your resource group.
7. Choose Register targets.

If you want to assign more targets to this maintenance window, choose the Targets tab, and then
choose Register target. With this option, you can choose a different means of targeting. For example,
if you previously targeted instances by instance ID, you can register new targets and target instances by
specifying tags applied to managed instances or choosing resource types from a resource group.

Assign Tasks to a Maintenance Window (Console)

In this procedure, you add a task to a maintenance window. Tasks are the actions performed on a
resource during a maintenance window execution.

The following four types of tasks can be added to a maintenance window:

• Systems Manager Run Command commands

458
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

• Systems Manager Automation workflows

• AWS Lambda functions
• AWS Step Functions tasks

To assign tasks to a maintenance window

1. In the list of maintenance windows, choose a maintenance window .

2. Choose Actions and then,choose the option for the type of task you want to register with the
maintenance window:

• Register Run command task

• Register Automation task
• Register Lambda task
• Register Step Functions task
3. For Name, enter a name for the task.
4. For Description, enter a description.
5. For Document, choose the SSM Command or Automation document that defines the tasks to run.
6. For Document version (for Automation tasks), choose the document version to use.
7. For Task priority, specify a priority for this task. 1 is the highest priority. Tasks in a maintenance
window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
8. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
9. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
10. In the IAM service role area, choose one of the following options to provide permissions for
Systems Manager to run tasks on your target instances:

• Create and use a service-linked role for Systems Manager

Service-linked roles provide a secure way to delegate permissions to AWS services because only
the linked service can assume a service-linked role. Additionally, AWS automatically defines and
sets the permissions of service-linked roles, depending on the actions that the linked service
performs on your behalf.
Note
If a service-linked role has already been created for your account, choose Use the service-
linked role for Systems Manager.
• Use a custom service role

459
 AWS Systems Manager User Guide
Working with Maintenance Windows (Console)

You can create a custom service role for maintenance window tasks if you want to use stricter
permissions than those provided by the service-linked role. Or you can create a custom service
role if you want to use Amazon SNS to send notifications related to maintenance window tasks
run through Run Command

If you need to create a custom service role, see one of the following topics:
• Control Access to Maintenance Windows (Console) (p. 446)
• Control Access to Maintenance Windows (AWS CLI) (p. 449)
• Control Access to Maintenance Windows (Tools for Windows PowerShell) (p. 452)

To help you decide whether to use a custom service role or the Systems Manager service-linked role
with a maintenance window task, see Should I Use a Service-Linked Role or a Custom Service Role to
Run Maintenance Window Tasks? (p. 445).
11. In the Input Parameters section, specify parameters for the document. For Automation documents,
the system auto-populates some of the values. You can keep or replace these values.
12. Complete the wizard.

Update or Delete a Maintenance Window (Console)

You can update or delete a maintenance window. You can also update or delete the targets or tasks of
a maintenance window. If you edit the details of a maintenance window, you can change the schedule,
targets, and tasks. You can also specify names and descriptions for windows, targets, and tasks, which
helps you better understand their purpose, and makes it easier to manage your queue of windows.

This section describes how to update or delete a maintenance window, targets, and tasks by using the
AWS Systems Manager console. For examples of how to do this by using the AWS CLI, see Tutorial:
Update a Maintenance Window (AWS CLI) (p. 490).

Topics
• Update or Delete a Maintenance Window (Console) (p. 460)
• Update or Delete Maintenance Window Targets (Console) (p. 461)
• Update or Delete Maintenance Window Tasks (Console) (p. 461)

Update or Delete a Maintenance Window (Console)

You can update a maintenance window to change its name, description, and schedule, and whether the
maintenance window should allow unregistered targets.

To update or delete a maintenance window

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.
3. Choose the maintenance window that you want to update or delete, and then do one of the
following:

• Choose Delete. The system prompts you to confirm your actions.

• Choose Edit. On the Edit maintenance window page, change the values and options that you
want, and then choose Edit maintenance window.

For information about the configuration choices you can make, see Create a Maintenance Window
(Console) (p. 456).

460
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Update or Delete Maintenance Window Targets (Console)

You can update or delete the targets of a maintenance window. If you choose to update a maintenance
window target you can specify a new target name, description, and owner. You can also choose different
targets.

To update or delete the targets of a maintenance window

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.
3. Choose the name of the maintenance window that you want to update, and then do one of the
following:

• To update targets, choose Edit.

• To delete targets, choose Deregister targets, and then choose the Targets tab.

Choose the target to delete, and then choose Deregister target. In the Deregister maintenance
windows target window, leave the Safely deregister target option selected if you want the
system to check if the target is referenced by any tasks before deleting it. If the target is
referenced by a task, the system returns an error and doesn't delete the target. Clear the Safely
deregister target option if you want the system to delete the target even if it is referenced by a
task.

Choose Deregister.

Update or Delete Maintenance Window Tasks (Console)

You can update or delete the tasks of a maintenance window. If you choose to update, you can specify
a new task name, description, and owner. For Run Command and Automation tasks, you can choose a
different SSM document for the tasks. You can't, however, edit a task to change its type. For example, if
you created an Automation task, you can't edit that task and change it to a Run Command task.

To update or delete the tasks of a maintenance window (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.
3. Choose the maintenance window that you want to update.
4. Choose the Tasks tab.
5. If you want to delete a task, choose the small x button next to Edit. If you want to edit the task,
choose Edit.
6. Change the values and options that you want, and then choose Edit Task. The system returns you to
the maintenance window page.

Systems Manager Maintenance Windows Tutorials

(AWS CLI)
This section includes tutorials that help you learn how to use the AWS Command Line Interface (AWS
CLI) to do the following:

• Create and configure a maintenance window

• View information about a maintenance window

461
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

• View information about maintenance windows tasks and task executions

• Update a maintenance window
• Delete a maintenance window

Complete prerequisites

Before trying these tutorials, complete the following prerequisites.

• Configure the AWS CLI on your local machine: Before you can run AWS CLI commands, you must
install and configure the CLI on your local machine. For information, see Install or Upgrade the AWS
CLI (p. 58).
• Verify maintenance window roles and permissions: An AWS administrator in your account must grant
you the AWS Identity and Access Management (IAM) permissions you need to manage maintenance
windows using the CLI. For information, see Controlling Access to Maintenance Windows (p. 445).
• Create or configure a Systems Manager-compatible instance: You need at least one Amazon EC2
instance that is configured for use with Systems Manager in order to complete the tutorials. This
means that SSM Agent is installed on the instance, and an IAM instance profile for Systems Manager is
attached to the instance.

We recommend launching an instance from one of the following Amazon Machine Image (AMI) types.
SSM Agent is preinstalled on each one:
• Windows Server 2003-2012 R2 AMIs published in November 2016 or later
• Windows Server 2016 and 2019
• Amazon Linux
• Amazon Linux 2
• Ubuntu Server 16.04
• Ubuntu Server 18.04

For information about installing SSM Agent on an instance, see the following topics:
• Installing and Configuring SSM Agent on Windows Instances (p. 65)
• Installing and Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68)

For information about creating and attaching an IAM instance profile for Systems Manager to your
instance, see the following topics:
• Create an IAM Instance Profile for Systems Manager (p. 29)
• Attach an IAM Instance Profile to an Amazon EC2 Instance (p. 34)
• Create additional resources as needed: Many Run Command tasks do not require you to create
resources other than those listed in this prerequisites topic. For that reason, we provide a simple Run
Command task for you to use your first time through the tutorials. You also need an Amazon EC2
instance that is configured to use with Systems Manager, as described above. After you configure that
instance, you can register a simple Run Command task.

The Systems Manager Maintenance Windows capability supports running four types of tasks:
• Systems Manager Run Command commands
• Systems Manager Automation workflows
• AWS Lambda functions
• AWS Step Functions tasks

In general, if a maintenance window task that you want to run requires additional resources, you
should create them first. For example, if you want a maintenance window that runs an AWS Lambda
function, create the Lambda function before you begin; for a Run Command task, create the S3 bucket
that you can save command output to (if you462plan to do so); and so on.
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Keep track of resource IDs

As you complete the tasks in this AWS CLI tutorial, keep track of resource IDs generated by the
commands you run. You use many of these as input for subsequent commands. For example, when you
create the maintenance window, the system provides you with a maintenance window ID in this format:

{
"WindowId":"mw-0c50858d01EXAMPLE"
}

Make a note of the following system-generated IDs because the tutorials in this section use them:

• WindowId
• WindowTargetId
• WindowTaskId
• WindowExecutionId
• TaskExecutionId
• InvocationId
• ExecutionId

You also need the ID of the Amazon EC2 instance you plan to use in the tutorial. For example:
i-02573cafcfEXAMPLE

Tutorials
• Tutorial: Create and Configure a Maintenance Window (AWS CLI) (p. 463)
• Tutorial: View Information About a Maintenance Windows (AWS CLI) (p. 479)
• Tutorial: View Information About Tasks and Task Executions (AWS CLI) (p. 488)
• Tutorial: Update a Maintenance Window (AWS CLI) (p. 490)
• Tutorial: Delete a Maintenance Window (AWS CLI) (p. 496)

Tutorial: Create and Configure a Maintenance Window (AWS CLI)

This tutorial demonstrates how to use the AWS CLI to create and configure a maintenance window, its
targets, and its tasks. The main path through the tutorial consists of simple steps. You create a single
maintenance window, identify a single target, and set up a simple task for the maintenance window to
run. Along the way, we provide information you can use to try more complicated scenarios.

As you follow the steps in this tutorial, replace the values in italicized red text with your own options
and IDs. For example, replace the maintenance window ID mw-0c50858d01EXAMPLE and the instance ID
i-02573cafcfEXAMPLE with IDs of resources you create.

Contents
• Step 1: Create the Maintenance Window (AWS CLI) (p. 463)
• Step 2: Register a Target Instance with the Maintenance Window (AWS CLI) (p. 464)
• Step 3: Register a Task with the Maintenance Window (AWS CLI) (p. 467)

Step 1: Create the Maintenance Window (AWS CLI)

In this step, you create a maintenance window and specify its basic options, such as name, schedule, and
duration. In later steps, you choose the instance it updates and the task it runs.

463
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

In our example, you create a maintenance window that runs every five minutes. Normally, you would not
run a maintenance window this frequently. However, this rate lets you see your tutorial results quickly.
We'll show you how to change to a less frequent rate after the task has run successfully.

To create a maintenance window (AWS CLI)

1. Open the AWS CLI and run the following command to create a maintenance window that does the
following:

• Runs every five minutes for up to two hours (as needed).

• Prevents new tasks from starting within one hour of the end of the maintenance window
execution.
• Allows unassociated targets (instances that you haven't registered with the maintenance window).
• Indicates through the use of custom tags that its creator intends to use it in a tutorial.

aws ssm create-maintenance-window --name "My-First-Maintenance-Window" --schedule

"rate(5 minutes)" --duration 2 --cutoff 1 --allow-unassociated-targets --tags
"Key=Purpose,Value=Tutorial"

The system returns information like the following:

{
"WindowId":"mw-0c50858d01EXAMPLE"
}

2. Now run this command to view details about this and any other maintenance windows already in
your account:

aws ssm describe-maintenance-windows

The system returns information like the following:

{
"WindowIdentities":[
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"Enabled": true,
"Duration": 2,
"Cutoff": 1,
"NextExecutionTime": "2019-05-11T16:46:16.991Z"
}
]
}

Continue to Step 2: Register a Target Instance with the Maintenance Window (AWS CLI) (p. 464).

Step 2: Register a Target Instance with the Maintenance Window (AWS CLI)
In this step, you register a target with your new maintenance window. In this case, you specify which
instance to update when the maintenance window runs.

For an example of registering more than one instance at a time using instance IDs, examples of using
tags to identify multiple instances, and examples of specifying resource groups as targets, see Examples:
Register Targets with a Maintenance Window (p. 465).

464
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Note
You should already have created an Amazon EC2 instance to use in this step, as described in the
Maintenance Windows tutorial prerequisites (p. 461).

To register a target instance with a maintenance window (AWS CLI)

1. Run the following command:

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

resource-type "INSTANCE" --target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE"

The system returns information like the following

{
"WindowTargetId":"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}

2. Now run the following command to view details about your maintenance window target:

aws ssm describe-maintenance-window-targets --window-id "mw-0c50858d01EXAMPLE"

The system returns information like the following:

{
"Targets": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"ResourceType": "INSTANCE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
]
}
]
}

Continue to Step 3: Register a Task with the Maintenance Window (AWS CLI) (p. 467).

Examples: Register Targets with a Maintenance Window

You can register a single instance as a target using its instance ID, as demonstrated in Step 2: Register
a Target Instance with the Maintenance Window (AWS CLI) (p. 464). You can also register one or more
instances as targets using the command formats on this page.

In general, there are two methods for identifying the instances you want to use as maintenance window
targets: specifying individual instances, and using resource tags. The resource tags method provides
more options, as shown in examples 2-3.

You can also specify one or more resource groups as the target of a maintenance window. A resource
group can include instances and many other types of supported AWS resources. Examples 4 and 5, next,
demonstrate how to add resource groups to your maintenance window targets.

For more information about creating and managing resource groups, see What is AWS Resource Groups?
in the AWS Resource Groups User Guide and Resource Groups and Tagging for AWS in the AWS News Blog.

465
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

For information about limits for the Maintenance Windows capability, in addition to those specified in
the following examples, see AWS Systems Manager Limits in the Amazon Web Services General Reference.

Topics
• Example 1: Register Multiple Targets Using Instance IDs (p. 466)
• Example 2: Register Targets Using Resource Tags Applied to Instances (p. 466)
• Example 3: Register Targets Using a Group of Tag Keys (Without Tag Values) (p. 466)
• Example 4: Register Targets Using a Resource Group Name (p. 467)

Example 1: Register Multiple Targets Using Instance IDs

Use the following command format to register multiple instances as targets using their instance IDs:

aws ssm register-target-with-maintenance-window --window-id

"mw-0c50858d01EXAMPLE" --resource-type "INSTANCE" --target
"Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE"

Recommended use: Most useful when registering a unique group of instances with any maintenance
window for the first time and they do not share a common instance tag.

Limits: You can specify up to 50 instances total for each maintenance window target.

Example 2: Register Targets Using Resource Tags Applied to Instances

Use the following command format to register instances that are all already tagged with a key-value pair
you have assigned:

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

resource-type "INSTANCE" --target "Key=tag:Region,Values=East"

Recommended use: Most useful when registering a unique group of instances with any maintenance
window for the first time and they do share a common instance tag.

Limits: You can specify up to fivekey-value pairs total for each target.
Note
You can tag a group of instances with the tag-key Patch Group and assign the instances a
common key value, such as my-patch-group. Patch Manager evaluates the Patch Group key
on instances to help determine which patch baseline applies to them. If your task will run the
AWS-ApplyPatchBaseline or AWS-RunPatchBaseline SSM document, you can specify
the same Patch Group key-value pair when you register targets with a maintenance window.
For example: --target "Key=tag:Patch Group,Values=my-patch-group. Doing so
enables you to easily use a maintenance window to update patches on a group of instances that
are already associated with the same patch baseline. For more information, see About Patch
Groups (p. 714).

Example 3: Register Targets Using a Group of Tag Keys (Without Tag Values)
Use the following command to register instances that all have one or more tag keys assigned to them,
regardless of their key values.

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

resource-type "INSTANCE" --target "Key=tag-key,Values=Name,Instance-Type,CostCenter"

Recommended use: Useful when you want to target instances by specifying multiple tag keys (without
their values) rather than just one tag-key or a tag key-value pair.

Limits: You can specify up to five tag-keys total for each target.

466
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Example 4: Register Targets Using a Resource Group Name

Use the following command to register a specified resource group, regardless of the type of resources it
contains. If the tasks you assign to the maintenance window do not act on a type of resource included in
this resource group, the system might report an error. Tasks for which a supported resource type is found
continue to run despite these errors.

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

resource-type "RESOURCE_GROUP" --target "Key=resource-groups:Name,Values=MyResourceGroup"

Recommended use: Useful when you want to quickly specify a resource group as a target without
evaluating whether all of its resource types will be targeted by a maintenance window, or when you
know that the resource group contains only the resource types that your tasks perform actions on.

Limits: You can specify only one resource group as a target.

Example 5: Register Targets by Filtering Resource Types in a Resource Group

Use the following command to register only certain resource types that belong to a resource group that
you specify. With this option, even if you add a task for a resource type that belongs to the resource
group, the task won’t run if you haven’t explicitly added the resource type to the filter.

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

resource-type "RESOURCE_GROUP" --target "Key=resource-groups:Name,Values=MyResourceGroup"
"Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::Instance,AWS::ECS::Cluster"

Recommended use: Useful when you want to maintain strict control over the types of AWS resources
your maintenance window can run actions on, or when your resource group contains a large number of
resource types and you want to avoid unnecessary error reports in your maintenance window logs.

Limits: You can specify only one resource group as a target.

Step 3: Register a Task with the Maintenance Window (AWS CLI)

In this step of the tutorial, you register a Run Command task that runs the df command on your Amazon
EC2 instance for Linux. The results of this standard Linux command show how much space is free and
how much is used on the disk file system of your instance.

-or-

If you are targeting an Amazon EC2 instance for Windows Server instance instead of Linux, replace df
in the following command with ipconfig. Output from this command lists details about the IP address,
subnet mask, and default gateway for adapters on the target instance.

When you are ready to register other task types, or use more of the available Run Command options, see
Examples: Register Tasks with a Maintenance Window (p. 470). There, we provide more information
about all four task types, and some of their most important options, to help you plan for more extensive
real-world scenarios.

To register a task with a maintenance window

1. Depending on the operating system type on your local machine, run one of the following
commands. The version to run from a local Windows machine includes the escape characters ("/")
that you need to run the command from your command line tool.

Windows local machine:

aws ssm register-task-with-maintenance-window --window-id mw-0c50858d01EXAMPLE --

task-arn "AWS-RunShellScript" --max-concurrency 1 --max-errors 1 --priority 10 --

467
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --task-type "RUN_COMMAND" --task-

invocation-parameters={\"RunCommand\":{\"Parameters\":{\"commands\":[\"df\"]}}}

Linux local machine:

aws ssm register-task-with-maintenance-window --window-id mw-0c50858d01EXAMPLE --

task-arn "AWS-RunShellScript" --max-concurrency 1 --max-errors 1 --priority 10 --
targets "Key=InstanceIds,Values=i-0471e04240EXAMPLE" --task-type "RUN_COMMAND" --task-
invocation-parameters '{"RunCommand":{"Parameters":{"commands":["df"]}}}'

The system returns information similar to the following:

{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

2. Now run the following command to view details about the maintenance window task you created.

aws ssm describe-maintenance-window-tasks --window-id mw-0c50858d01EXAMPLE

3. The system returns information similar to the following:

{
"Tasks": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskArn": "AWS-RunShellScript",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 10,
"ServiceRoleArn": "arn:aws:iam::123456789012:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "1",
"MaxErrors": "1"
}
]
}

4. Wait until the task has had time to run, based on the schedule you specified in Step 1: Create the
Maintenance Window (AWS CLI) (p. 463). For example, if you specified --schedule "rate(5
minutes)", wait five minutes. Then run the following command to view information about any
executions that occurred for this task.

aws ssm describe-maintenance-window-executions --window-id mw-0c50858d01EXAMPLE

The system returns information similar to the following:

{
"WindowExecutions": [
{

468
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
}
]
}

Tip
After the task completes successfully, you can decrease the rate at which the maintenance
window runs. For example, run the following command to decrease the frequency to once a
week:

aws ssm update-maintenance-window --window-id mw-0c50858d01EXAMPLE --schedule

"rate(7 days)"

For information about managing maintenance window schedules, see Reference: Cron and Rate
Expressions for Systems Manager (p. 933) and Reference: Maintenance Windows Scheduling
and Active Period Options (p. 939).
For information about using the AWS CLI to modify a maintenance window, see Tutorial: Update
a Maintenance Window (AWS CLI) (p. 490).

For practice running AWS CLI commands to view more details about your maintenance window task
and its executions, continue to Tutorial: View Information About Tasks and Task Executions (AWS
CLI) (p. 488).

About tutorial command output

It's beyond the scope of this tutorial to use the AWS CLI to view the output of the Run Command
command associated with your maintenance window task executions.

You could view this data, however, using the AWS CLI. (You could also view the output in the Systems
Manager console or in a log file stored in an Amazon S3 bucket, if you had configured the maintenance
window to store command output there.) You would find that the output of the df command on a Linux
instance is similar to the following:

Filesystem 1K-blocks Used Available Use% Mounted on

devtmpfs 485716 0 485716 0% /dev

tmpfs 503624 0 503624 0% /dev/shm

tmpfs 503624 328 503296 1% /run

tmpfs 503624 0 503624 0% /sys/fs/cgroup

/dev/xvda1 8376300 1464160 6912140 18% /

The output of the ipconfig command on a Windows Server instance is similar to the following:

Windows IP Configuration

Ethernet adapter Ethernet 2:

Connection-specific DNS Suffix . : example.com

IPv4 Address. . . . . . . . . . . : 10.24.34.0/23
Subnet Mask . . . . . . . . . . . : 255.255.255.255
Default Gateway . . . . . . . . . : 0.0.0.0

469
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Ethernet adapter Ethernet:

Media State . . . . . . . . . . . : Media disconnected

Connection-specific DNS Suffix . : abc1.wa.example.net

Wireless LAN adapter Local Area Connection* 1:

Media State . . . . . . . . . . . : Media disconnected

Connection-specific DNS Suffix . :

Wireless LAN adapter Wi-Fi:

Connection-specific DNS Suffix . :

Link-local IPv6 Address . . . . . : fe80::100b:c234:66d6:d24f%4
IPv4 Address. . . . . . . . . . . : 192.0.2.0
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 192.0.2.0

Ethernet adapter Bluetooth Network Connection:

Media State . . . . . . . . . . . : Media disconnected

Connection-specific DNS Suffix . :

Examples: Register Tasks with a Maintenance Window

You can register a Systems Manager Run Command task with a maintenance window using the AWS CLI,
as demonstrated in Step 3: Register a Task with the Maintenance Window (AWS CLI) (p. 467). You can
also register tasks for Systems Manager Automation workflows, AWS Lambda functions, and AWS Step
Functions tasks, as demonstrated below.

In this topic, we provide examples of using the register-task-with-maintenance-window CLI

command to register each of the four supported task types with a maintenance window. The examples
are for demonstration only, but you can modify them to create working task registration commands.

Using the --cli-input-json option

To better manage your task options, you can use the command option --cli-input-json, with option
values referenced in a JSON file.

To use the sample JSON file content we provide in the following examples, do the following on your
local machine:

1. Create a file with a name such as MyRunCommandTask.json, MyAutomationTask.json, or

another name that you prefer.
2. Copy the contents of our JSON sample into the file.
3. Modify the contents of the file for your task registration, and then save the file.
4. In the same directory where you stored the file, run the following command. Substitute your file
name for MyFile.json.

aws ssm register-task-with-maintenance-window --cli-input-json file://MyFile.json

About pseudo parameters

In some examples, we use pseudo parameters as the method to pass ID information to your tasks.
For example, {{TARGET_ID}} is used to pass instance ID information to Automation, Lambda, and
Step Functions tasks in our examples. For more information about pseudo parameters in --task-
invocation-parameters content, see About Pseudo Parameters (p. 477).

More information

470
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

For information about some fundamental register-task-with-maintenance-window options, see

About register-task-with-maintenance-windows Options (p. 474).

For comprehensive information about command options, see the following topics:

• register-task-with-maintenance-window in the AWS CLI Command Reference

• RegisterTaskWithMaintenanceWindow in the AWS Systems Manager API Reference

Task Registration Examples

The following sections provide a sample AWS CLI command for registering a supported task type and a
JSON sample that can be used with the --cli-input-json option.
Note
The CLI commands we provide are formatted to run from a local Linux machine. To run them
from a local Windows machine, remove the line breaks (\) from the ends of the lines. The
sample JSON content format works on both Linux and Windows local machines.

Register a Systems Manager Run Command Task

The following examples demonstrate how to register Systems Manager Run Command tasks with a
maintenance window using the AWS CLI:

AWS CLI command:

aws ssm register-task-with-maintenance-window --window-id mw-0c50858d01EXAMPLE \

--task-arn "AWS-RunShellScript" --max-concurrency 1 --max-errors 1 --priority 10 \
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --task-type "RUN_COMMAND" \
--task-invocation-parameters "{"RunCommand":{"Parameters":{"commands":["df"]}}}"

JSON content to use with --cli-input-json file option:

{
"TaskType": "RUN_COMMAND",
"WindowId": "mw-0c50858d01EXAMPLE",
"Description": "My Run Command task to update SSM Agent on an instance",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "My-Run-Command-Task",
"Priority": 10,
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "AWS-UpdateSSMAgent",
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "A TaskInvocationParameters test comment",
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:us-east-2:123456789012:my-sns-topic-name",
"NotificationEvents": [
"All"
],
"NotificationType": "Invocation"
},
"OutputS3BucketName": "my-s3-bucket-name",
"OutputS3KeyPrefix": "my-s3-bucket-folder-name",
"TimeoutSeconds": 3600

471
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

}
}
}

Register a Systems Manager Automation Task

The following examples demonstrate how to register Systems Manager Automation tasks with a
maintenance window using the AWS CLI:

AWS CLI command:

aws ssm register-task-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" \

--targets Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE \
--task-arn "AWS-RestartEC2Instance" \
--service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole \
--task-type AUTOMATION \
--task-invocation-parameters
"Automation={DocumentVersion=5,Parameters={instanceId='{{TARGET_ID}}'}}" \
--priority 0 --max-concurrency 10 --max-errors 5 --name "My-Automation-Task" \
--description "A description for my Automation task"

JSON content to use with --cli-input-json file option:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "AWS-PatchInstanceWithRollback",
"TaskType": "AUTOMATION",
"MaxConcurrency": "10",
"MaxErrors": "10",
"TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "1",
"Parameters": {
"instanceId": [
"{{TARGET_ID}}"
]
}
}
}
}

Register an AWS Lambda Task

The following examples demonstrate how to register AWS Lambda function tasks with a maintenance
window using the AWS CLI.

For these examples, the user who created the Lambda function named it SSMrestart-my-instances
and created two parameters called targetId and targetType.
Important
The IAM policy for Maintenance Windows requires that you prefix Lambda function (or
alias) names with SSM. Before you proceed to register this type of task, you must update
its name in AWS Lambda to include SSM. For example, if your Lambda function name is
MyLambdaFunction, change it to SSMMyLambdaFunction.

472
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

AWS CLI command:

aws ssm register-task-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" \

--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --priority 2 \
--max-concurrency 10 --max-errors 5 --name "My-Lambda-Example" \
--description "A description for my LAMBDA example task" --task-type "LAMBDA" \
--task-arn "arn:aws:lambda:us-east-2:123456789012:function:serverlessrepo-SSMrestart-my-
instances-C4JF9EXAMPLE" \
--task-invocation-parameters '{"Lambda":{\"Payload\":{\"targetId\":\"{{TARGET_ID}}\",
\"targetType\":\"{{TARGET_TYPE}}\"},"Qualifier": "$LATEST"}}'

JSON content to use with --cli-input-json file option:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "SSM_RestartMyInstances",
"TaskType": "LAMBDA",
"MaxConcurrency": "10",
"MaxErrors": "10",
"TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"targetId\": \"{{TARGET_ID}}\", \"targetType\":
\"{{TARGET_TYPE}}\" }",
"Qualifier": "$LATEST"
}
},
"Name": "My-Lambda-Task",
"Description": "A description for my LAMBDA task",
"Priority": 5
}

Register an AWS Step Functions Task

The following examples demonstrate how to register AWS Step Functions state machine tasks with a
maintenance window using the AWS CLI.

For these examples, the user who created the Step Functions state machine created a state machine
named SSMMyStateMachine with a parameter called targetId.
Important
The IAM policy for Maintenance Windows requires that you prefix Step Functions state
machine names with SSM. Before you proceed to register this type of task, you must update
its name in AWS Step Functions to include SSM. For example, if your state machine name is
MyStateMachine, change it to SSMMyStateMachine.

AWS CLI command:

aws ssm register-task-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" \

--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--task-arn arn:aws:states:us-east-2:123456789012:stateMachine:SSMMyStateMachine-
MggiqEXAMPLE \
--task-type STEP_FUNCTIONS \

473
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

--task-invocation-parameters '{"StepFunctions":{"Input":"{\"targetId\":
\"{{TARGET_ID}}\"}"}, "Name": "{{INVOCATION_ID}}"}' \
--priority 0 --max-concurrency 10 --max-errors 5 \
--name "My-Step-Functions-Task" --description "A description for my Step Functions task"

JSON content to use with --cli-input-json file option:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "SSM_MyStateMachine",
"TaskType": "STEP_FUNCTIONS",
"MaxConcurrency": "10",
"MaxErrors": "10",
"TaskInvocationParameters": {
"StepFunctions": {
"Input": "{ \"targetId\": \"{{TARGET_ID}}\" }",
"Name": "{{INVOCATION_ID}}"
}
},
"Name": "My-Step-Functions-Task",
"Description": "A description for my Step Functions task",
"Priority": 5
}

About register-task-with-maintenance-windows Options

The register-task-with-maintenance-window command provides several options for configuring a

task according to your needs. Some are required, some are optional, and some apply to only a single
maintenance window task type.

This topic provides information about some of these options to help you work with samples in this
tutorial section. For information about all command options, see register-task-with-maintenance-
window in the AWS CLI Command Reference.

About the --task-arn option

The option --task-arn is used to specify the resource that the task uses during execution. The value
that you specify depends on the type of task you are registering, as described in the following table.

TaskArn formats for maintenance window tasks

Maintenance window task type TaskArn value

RUN_COMMAND and AUTOMATION TaskArn is the SSM document name or ARN. For
example:

AWS-RunBatchShellScript

-or-

arn:aws:ssm:us-
east-2:111122223333:document/My-
Document.

474
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Maintenance window task type TaskArn value

LAMBDA TaskArn is the function name or ARN. For

example:

SSMMy-Lambda-Function

-or-

arn:aws:lambda:us-
east-2:111122223333:function:SSMMyLambdaFunction.
Important
The IAM policy for maintenance windows
requires that you prefix Lambda function
(or alias) names with SSM. Before you
register this type of task, you must
update its name in AWS Lambda to
include SSM. For example, if your Lambda
function name is MyLambdaFunction,
change it to SSMMyLambdaFunction.

STEP_FUNCTIONS TaskArn is the state machine ARN. For example:

arn:aws:states:us-
east-2:111122223333:stateMachine:SSMMyStateMachin
Important
The IAM policy for maintenance windows
requires that you prefix Step Functions
state machine names with SSM. Before
you register this type of task, you must
update its name in AWS Step Functions
to include SSM. For example, if your state
machine name is MyStateMachine,
change it to SSMMyStateMachine.

About the --service-role-arn option

The role for Systems Manager to assume when running the maintenance window task.

Specifying a service role ARN is optional. If you do not specify a service role ARN, Systems Manager
creates a service-linked role or uses your account's service-linked role.

Note that the service-linked role for Systems Manager doesn't provide the permissions needed for all
scenarios. For more information, see Should I Use a Service-Linked Role or a Custom Service Role to Run
Maintenance Window Tasks? (p. 445)

About the --task-invocation-parameters option

The --task-invocation-parameters option is used to specify the parameters that are unique to
each of the four task types. The supported parameters for each of the four task types are described in
the following table.
Note
For information about using pseudo parameters in --task-invocation-parameters
content, such as {{TARGET_ID}}, see About Pseudo Parameters (p. 477).

Task invocation parameters options for maintenance window tasks

475
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Maintenance window task type Available parameters Example

RUN_COMMAND Comment
"TaskInvocationParameters":
{
DocumentHash "RunCommand": {
"Comment": "My
DocumentHashType Run Command task comment",
"DocumentHash":
NotificationConfig "6554ed3d--
truncated--5EXAMPLE",
OutputS3BucketName
"DocumentHashType":
OutPutS3KeyPrefix "Sha256",

Parameters "NotificationConfig": {

ServiceRoleArn "NotificationArn":
"arn:aws:sns:us-
TimeoutSeconds east-2:123456789012:my-sns-
topic-name",

"NotificationEvents": [

"FAILURE"
],

"NotificationType":
"Invocation"
},

"OutputS3BucketName": "my-
s3-bucket-name",

"OutputS3KeyPrefix": "my-
s3-bucket-folder-name",
"Parameters": {
"commands":
[
"Get-
ChildItem$env: temp-Recurse|
Remove-Item-Recurse-force"
]
},

"ServiceRoleArn":
"arn:aws:iam::123456789012:role/
MyMaintenanceWindowServiceRole",

"TimeoutSeconds": 3600
}
}

AUTOMATION DocumentVersion
"TaskInvocationParameters":
{
Parameters "Automation": {

"DocumentVersion": "3",
"Parameters": {

"instanceid": [

"{{TARGET_ID}}"
]

476
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Maintenance window task type Available parameters Example

}
}
}

LAMBDA ClientContext
"TaskInvocationParameters":
{
Payload "Lambda": {
"ClientContext":
Qualifier "ew0KICAi--
truncated--0KIEXAMPLE",
"Payload":
"{ \"targetId\":
\"{{TARGET_ID}}\",
\"targetType\":
\"{{TARGET_TYPE}}\" }",
"Qualifier":
"$LATEST"
}
}

STEP_FUNCTIONS Input
"TaskInvocationParameters":
{
Name "StepFunctions": {
"Input":
"{ \"targetId\":
\"{{TARGET_ID}}\" }",
"Name":
"{{INVOCATION_ID}}"
}
}

About Pseudo Parameters

When you register a task, you use the --task-invocation-parameters option to specify the
parameters that are unique to each of the four task types. You can also reference certain values using
pseudo parameter syntax, such as {{TARGET_ID}}. When the maintenance window task runs, it passes
the correct values instead of the pseudo parameter placeholders.

For Run Command tasks, the connections to targets (instances) are handled automatically. For the other
task types–Automation, Step Functions, and Lambda–you must include the {{TARGET_ID}} pseudo
parameters in the --task-invocation-parameters option. When the task runs, the actual instance
ID is supplied in place of {{TARGET_ID}}.

Examples

For example, suppose that your payload for a Lambda task needs to reference the instance ID
and target type when it runs. If the task would only ever run on a single instance, with instance ID
i-02573cafcfEXAMPLE, you could use the following:

"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
"TaskType": "LAMBDA",
"TaskInvocationParameters": {
"Lambda": {
"Payload": "{ \"targetId\": \"i-02573cafcfEXAMPLE\", \"targetType\": \"INSTANCE
\" }",
"Qualifier": "$LATEST",
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE"

477
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

}
}

However, if you include multiple instance IDs in the custom "targetId" field, the operation fails.
Therefore, to run the task on multiple instances, you use the {{TARGET_ID}} and {{TARGET_TYPE}}
pseudo parameters. In this case, the ID of each instance in the target group is passed to the task
execution through the {{TARGET_ID}} pseduo parameter, and the task runs on every instance in your
target group:

"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
"TaskType": "LAMBDA",
"TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"targetId\": \"{{TARGET_ID}}\", \"targetType\":
\"{{TARGET_TYPE}}\" }",
"Qualifier": "$LATEST"
}
}

As another example, to run an Automation task that stops your Amazon EC2 instances, you specify the
AWS-StopEC2Instance SSM document as the TaskArn value and use the {{TARGET_ID} pseudo
parameter:

"TaskArn": "AWS-StopEC2Instance",
"TaskType": "AUTOMATION"
"TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "1",
"Parameters": {
"instanceId": [
"{{TARGET_ID}}"
]
}
}
}

Available pseudo parameters

The following list describes the pseudo parameters that you can specify using the
{{PSEUDO_PARAMETER}} syntax in the --task-invocation-parameters option.

• TARGET_ID: The ID of the target. If the target type is INSTANCE (currently the only supported type),
then the target ID is the instance ID.
• TARGET_TYPE: The type of target. Currently only INSTANCE is supported.
• WINDOW_ID: The ID of the target maintenance window.
• WINDOW_TASK_ID: The ID of the window task that is executing.
• WINDOW_TARGET_ID: The ID of the window target that includes the target (target ID).
• WINDOW_EXECUTION_ID: The ID of the current window execution.
• TASK_EXECUTION_ID: The ID of the current task execution.
• INVOCATION_ID: The ID of the current invocation.

478
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Tutorial: View Information About a Maintenance Windows (AWS

CLI)
This tutorial includes commands to help you update or get information about your maintenance
windows, tasks, executions, and invocations. The examples are organized by command to demonstrate
how to use command options to filter for the type of detail you want to see.

As you follow the steps in this tutorial, replace the values in italicized red text with your own options
and IDs. For example, replace the maintenance window ID mw-0c50858d01EXAMPLE and the instance ID
i-02573cafcfEXAMPLE with IDs of resources you create.

For information about setting up and configuring the CLI, see Installing the AWS Command Line
Interface and Configuring the AWS Command Line Interface.

Command Examples
• Examples for 'describe-maintenance-windows' (p. 479)
• Examples for 'describe-maintenance-window-targets' (p. 481)
• Examples for 'describe-maintenance-window-tasks' (p. 481)
• Examples for 'describe-maintenance-windows-for-target' (p. 484)
• Examples for 'describe-maintenance-window-executions' (p. 484)
• Examples for 'describe-maintenance-window-schedule' (p. 485)

Examples for 'describe-maintenance-windows'

List all maintenance windows in your AWS account

Run the following command:

aws ssm describe-maintenance-windows

The system returns information like the following:

{
"WindowIdentities":[
{
"WindowId":"mw-0c50858d01EXAMPLE",
"Name":"My-First-Maintenance-Window",
"Enabled":true,
"Duration":2,
"Cutoff":0,
"NextExecutionTime": "2019-05-18T17:01:01.137Z"
},
{
"WindowId":"mw-9a8b7c6d5eEXAMPLE",
"Name":"My-Second-Maintenance-Window",
"Enabled":true,
"Duration":4,
"Cutoff":1,
"NextExecutionTime": "2019-05-30T03:30:00.137Z"
},
]
}

List all enabled maintenance windows

Run the following command:

479
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=true"

The system returns information like the following:

{
"WindowIdentities":[
{
"WindowId":"mw-0c50858d01EXAMPLE",
"Name":"My-First-Maintenance-Window",
"Enabled":true,
"Duration":2,
"Cutoff":0,
"NextExecutionTime": "2019-05-18T17:01:01.137Z"
},
{
"WindowId":"mw-9a8b7c6d5eEXAMPLE",
"Name":"My-Second-Maintenance-Window",
"Enabled":true,
"Duration":4,
"Cutoff":1,
"NextExecutionTime": "2019-05-30T03:30:00.137Z"
},
]
}

List all disabled maintenance windows

Run the following command:

aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=false"

The system returns information like the following:

{
"WindowIdentities": [
{
"WindowId": "mw-6e5c9d4b7cEXAMPLE",
"Name": "My-Disabled-Maintenance-Window",
"Enabled": false,
"Duration": 2,
"Cutoff": 1
}
]
}

List all maintenance windows having names that start with a certain prefix

Run the following command:

aws ssm describe-maintenance-windows --filters "Key=Name,Values=My"

The system returns information like the following:

{
"WindowIdentities": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"Enabled": true,

480
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"Duration": 2,
"Cutoff": 0,
"NextExecutionTime": "2019-05-18T17:01:01.137Z"
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"Name": "My-Second-Maintenance-Window",
"Enabled": true,
"Duration": 4,
"Cutoff": 1,
"NextExecutionTime": "2019-05-30T03:30:00.137Z"
},
{
"WindowId": "mw-6e5c9d4b7cEXAMPLE",
"Name": "My-Disabled-Maintenance-Window",
"Enabled": false,
"Duration": 2,
"Cutoff": 1
}
]
}

Examples for 'describe-maintenance-window-targets'

Display the targets for a maintenance window matching a specific owner information value

Run the following command:

aws ssm describe-maintenance-window-targets --window-id "mw-6e5c9d4b7cEXAMPLE" --filters

"Key=Type,Values=INSTANCE"

Note
The supported filter keys are Type, WindowTargetId and OwnerInformation.

The system returns information like the following:

{
"Targets": [
{
"WindowId": "mw-6e5c9d4b7cEXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"ResourceType": "INSTANCE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE",
"i-0471e04240EXAMPLE",
"i-07782c72faEXAMPLE"
]
}
]
}
]
}

Examples for 'describe-maintenance-window-tasks'

Show all registered tasks that invoke the AWS-RunPowerShellScript Run Command

Run the following command:

481
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

aws ssm describe-maintenance-window-tasks --window-id "mw-0c50858d01EXAMPLE" --filters

"Key=TaskArn,Values=AWS-RunPowerShellScript"

The system returns information like the following:

{
"Tasks":[
{
"ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxErrors":"1",
"TaskArn":"AWS-RunPowerShellScript",
"MaxConcurrency":"1",
"WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters":{
"commands":{
"Values":[
"driverquery.exe"
]
}
},
"Priority":3,
"Type":"RUN_COMMAND",
"Targets":[
{
"TaskTargetId":"i-02573cafcfEXAMPLE",
"TaskTargetType":"INSTANCE"
}
]
},
{
"ServiceRoleArn":"arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxErrors":"1",
"TaskArn":"AWS-RunPowerShellScript",
"MaxConcurrency":"1",
"WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters":{
"commands":{
"Values":[
"ipconfig"
]
}
},
"Priority":1,
"Type":"RUN_COMMAND",
"Targets":[
{
"TaskTargetId":"i-02573cafcfEXAMPLE",
"TaskTargetType":"WINDOW_TARGET"
}
]
}
]
}

Show all registered tasks that have a priority of "3"

Run the following command:

aws ssm describe-maintenance-window-tasks --window-id "mw-9a8b7c6d5eEXAMPLE" --filters

"Key=Priority,Values=3"

482
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

The system returns information like the following:

{
"Tasks":[
{
"ServiceRoleArn":"arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxErrors":"1",
"TaskArn":"AWS-RunPowerShellScript",
"MaxConcurrency":"1",
"WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters":{
"commands":{
"Values":[
"driverquery.exe"
]
}
},
"Priority":3,
"Type":"RUN_COMMAND",
"Targets":[
{
"TaskTargetId":"i-02573cafcfEXAMPLE",
"TaskTargetType":"INSTANCE"
}
]
}
]
}

Show all registered tasks that have a priority of "1" and use Run Command

Run the following command:

aws ssm describe-maintenance-window-tasks --window-id "mw-0c50858d01EXAMPLE" --filters

"Key=Priority,Values=1" "Key=TaskType,Values=RUN_COMMAND"

The system returns information like the following:

{
"Tasks": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskArn": "AWS-RunShellScript",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 1,
"ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "1",
"MaxErrors": "1"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",

483
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"WindowTaskId": "8a5c4629-31b0-4edd-8aea-33698EXAMPLE",
"TaskArn": "AWS-UpdateSSMAgent",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-0471e04240EXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 1,
"ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM"",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "My-Run-Command-Task",
"Description": "My Run Command task to update SSM Agent on an instance"
}
]
}

Examples for 'describe-maintenance-windows-for-target'

List information about the maintenance window targets or tasks associated with a specific instance

Run the following command:

aws ssm describe-maintenance-windows-for-target --resource-type INSTANCE --targets

"Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --max-results 10

The system returns information like the following:

{
"WindowIdentities": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window"
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"Name": "My-Second-Maintenance-Window"
}
]
}

Examples for 'describe-maintenance-window-executions'

List all tasks run before a certain date

Run the following command:

aws ssm describe-maintenance-window-executions --window-id "mw-9a8b7c6d5eEXAMPLE" --filters

"Key=ExecutedBefore,Values=2019-05-12T05:00:00Z"

The system returns information like the following:

{
"WindowExecutions": [
{

484
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "FAILED",
"StatusDetails": "The following SSM parameters are invalid: LevelUp",
"StartTime": 1557617747.993,
"EndTime": 1557617748.101
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557594085.428,
"EndTime": 1557594090.978
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593793.483,
"EndTime": 1557593798.978
}
]
}

List all tasks run after a certain date

Run the following command:

aws ssm describe-maintenance-window-executions --window-id "mw-9a8b7c6d5eEXAMPLE" --filters

"Key=ExecutedAfter,Values=2018-12-31T17:00:00Z"

The system returns information like the following:

{
"WindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "FAILED",
"StatusDetails": "The following SSM parameters are invalid: LevelUp",
"StartTime": 1557617747.993,
"EndTime": 1557617748.101
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557594085.428,
"EndTime": 1557594090.978
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593793.483,
"EndTime": 1557593798.978
}
]
}

Examples for 'describe-maintenance-window-schedule'

Display the next ten scheduled maintenance window runs for a particular instance

485
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Run the following command:

aws ssm describe-maintenance-window-schedule --resource-type INSTANCE --targets

"Key=InstanceIds,Values=i-07782c72faEXAMPLE" --max-results 10

The system returns information like the following:

{
"ScheduledWindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-05-18T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-05-25T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-06-01T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-06-08T23:35:24.902Z"
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"Name": "My-Second-Maintenance-Window",
"ExecutionTime": "2019-06-15T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-06-22T23:35:24.902Z"
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"Name": "My-Second-Maintenance-Window",
"ExecutionTime": "2019-06-29T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-07-06T23:35:24.902Z"
},
{
"WindowId": "mw-9a8b7c6d5eEXAMPLE",
"Name": "My-Second-Maintenance-Window",
"ExecutionTime": "2019-07-13T23:35:24.902Z"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"ExecutionTime": "2019-07-20T23:35:24.902Z"
}
],
"NextToken": "AAEABUXdceT92FvtKld/dGHELj5Mi+GKW/EXAMPLE"
}

486
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

Display the maintenance window schedule for instances tagged with a certain key-value pair

Run the following command:

aws ssm describe-maintenance-window-schedule --resource-type INSTANCE --targets

"Key=tag:prod,Values=rhel7"

The system returns information like the following:

{
"ScheduledWindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "DemoRateStartDate",
"ExecutionTime": "2019-10-20T05:34:56-07:00"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "DemoRateStartDate",
"ExecutionTime": "2019-10-21T05:34:56-07:00"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "DemoRateStartDate",
"ExecutionTime": "2019-10-22T05:34:56-07:00"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "DemoRateStartDate",
"ExecutionTime": "2019-10-23T05:34:56-07:00"
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "DemoRateStartDate",
"ExecutionTime": "2019-10-24T05:34:56-07:00"
}
],
"NextToken": "AAEABccwSXqQRGKiTZ1yzGELR6cxW4W/EXAMPLE"
}

Display start times for next four runs of a maintenance window

Run the following command:

aws ssm describe-maintenance-window-schedule --window-id "mw-0c50858d01EXAMPLE" --max-

results "4"

The system returns information like the following:

{
"WindowSchedule": [
{
"ScheduledWindowExecutions": [
{
"ExecutionTime": "2019-10-04T10:10:10Z",
"Name": "My-First-Maintenance-Window",
"WindowId": "mw-0c50858d01EXAMPLE"
},
{
"ExecutionTime": "2019-10-11T10:10:10Z",
"Name": "My-First-Maintenance-Window",

487
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"WindowId": "mw-0c50858d01EXAMPLE"
},
{
"ExecutionTime": "2019-10-18T10:10:10Z",
"Name": "My-First-Maintenance-Window",
"WindowId": "mw-0c50858d01EXAMPLE"
},
{
"ExecutionTime": "2019-10-25T10:10:10Z",
"Name": "My-First-Maintenance-Window",
"WindowId": "mw-0c50858d01EXAMPLE"
}
]
}
]
}

Tutorial: View Information About Tasks and Task Executions

(AWS CLI)
This tutorial demonstrates how to use the AWS CLI to view details about your completed maintenance
window task executions.

If you are continuing directly from Tutorial: Create and Configure a Maintenance Window (AWS
CLI) (p. 463), make sure you have allowed enough time for your maintenance window to run at least
once in order to see its execution results.

As you follow the steps in this tutorial, replace the values in italicized red text with your own options
and IDs. For example, replace the maintenance window ID mw-0c50858d01EXAMPLE and the instance ID
i-02573cafcfEXAMPLE with IDs of resources you create.

To view information about tasks and task executions (AWS CLI)

1. Run the following command to view a list of task executions for a specific maintenance window:

aws ssm describe-maintenance-window-executions --window-id "mw-0c50858d01EXAMPLE"

The system returns information like the following:

{
"WindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593793.483,
"EndTime": 1557593798.978
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"Status": "SUCCESS",
"StatusDetails": "No tasks to execute.",

488
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"StartTime": 1557593193.309,
"EndTime": 1557593193.334
}
]
}}

2. Run the following command to get information about a maintenance window task execution:

aws ssm get-maintenance-window-execution --window-execution-id "14bea65d-5ccc-462d-

a2f3-e99c8EXAMPLE"

The system returns information like the following:

{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskIds": [
"c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
],
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
}

3. Run the following command to list the tasks run as part of a maintenance window execution:

aws ssm describe-maintenance-window-execution-tasks --window-execution-id

"14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE"

The system returns information like the following:

{
"WindowExecutionTaskIdentities": [
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.162,
"EndTime": 1557593498.57,
"TaskArn": "AWS-RunShellScript",
"TaskType": "RUN_COMMAND"
}
]
}

4. Run the following command to get the details of a task execution:

aws ssm get-maintenance-window-execution-task --window-execution-id

"14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" --task-id "c9b05aba-197f-4d8d-be34-
e73fbEXAMPLE"

The system returns information like the following:

{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"TaskArn": "AWS-RunShellScript",
"ServiceRole": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/
AWSServiceRoleForAmazonSSM",
"Type": "RUN_COMMAND",
"TaskParameters": [

489
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

{
"aws:InstanceId": {
"Values": [
"i-02573cafcfEXAMPLE"
]
},
"commands": {
"Values": [
"df"
]
}
}
],
"Priority": 10,
"MaxConcurrency": "1",
"MaxErrors": "1",
"Status": "SUCCESS",
"StartTime": 1557593493.162,
"EndTime": 1557593498.57
}

5. Run the following command to get the specific task invocations performed for a task execution.

aws ssm describe-maintenance-window-execution-task-invocations --window-execution-

id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" --task-id "c9b05aba-197f-4d8d-be34-
e73fbEXAMPLE"

The system returns information like the following.

{
"WindowExecutionTaskInvocationIdentities": [
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"InvocationId": "c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId": "76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"TaskType": "RUN_COMMAND",
"Parameters": "{\"documentName\":\"AWS-RunShellScript\",\"instanceIds\":
[\"i-02573cafcfEXAMPLE\"],\"maxConcurrency\":\"1\",\"maxErrors\":\"1\",\"parameters\":
{\"commands\":[\"df\"]}}",
"Status": "SUCCESS",
"StatusDetails": "Success",
"StartTime": 1557593493.222,
"EndTime": 1557593498.466
}
]
}

Tutorial: Update a Maintenance Window (AWS CLI)

This tutorial demonstrates how to use the AWS CLI to update a maintenance window. It also shows
you how to update different task types, including those for Systems Manager Run Command, Systems
Manager Automation, AWS Lambda, and AWS Step Functions.

The examples in this section use the following Systems Manager actions for updating a maintenance
window.

• UpdateMaintenanceWindow
• UpdateMaintenanceWindowTarget
• UpdateMaintenanceWindowTask

490
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

• DeregisterTargetFromMaintenanceWindow

For information about using the Systems Manager console to update a maintenance window, see Update
or Delete a Maintenance Window (Console) (p. 460).

As you follow the steps in this tutorial, replace the values in italicized red text with your own options
and IDs. For example, replace the maintenance window ID mw-0c50858d01EXAMPLE and the instance ID
i-02573cafcfEXAMPLE with IDs of resources you create.

To update a maintenance window (AWS CLI)

1. Open the AWS CLI and run the following command to update a target to include a name and a
description:

aws ssm update-maintenance-window-target --window-id "mw-0c50858d01EXAMPLE" --window-

target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --name "My-Maintenance-Window-Target"
--description "Description for my maintenance window target"

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
],
"Name": "My-Maintenance-Window-Target",
"Description": "Description for my maintenance window target"
}

2. Run the following command to use the replace option to remove the description field and add an
additional target. The description field is removed, because the update does not include the field (a
null value). Be sure to specify an additional instance that has been configured for use with Systems
Manager:

aws ssm update-maintenance-window-target --window-id "mw-0c50858d01EXAMPLE"

--window-target-id "d208dedf-3f6b-41ff-ace8-8e751EXAMPLE" --targets
"Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" --name "My-
Maintenance-Window-Target" --replace

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE",
"i-0471e04240EXAMPLE"
]
}
],

491
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"Name": "My-Maintenance-Window-Target"
}

3. The start-date option allows you to delay activation of a maintenance window until a specified
future date. The end-date option allows you to set a date and time in the future after which the
maintenance window no longer runs. Specify the options in ISO-8601 Extended format.

Run the following command to specify a date and time range for regularly scheduled maintenance
window executions:

aws ssm update-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --start-date

"2020-10-01T10:10:10Z" --end-date "2020-11-01T10:10:10Z"

4. If you created a Run Command task, run the following command to update it:
Tip
If your target is an Amazon EC2 instance for Windows Server, change df to ipconfig, and
AWS-RunShellScript to AWS-RunPowerShellScript in the following command.

aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE"

--window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets
"Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-
arn "AWS-RunShellScript" --service-role-arn "arn:aws:iam::111122223333:role/
MaintenanceWindowsRole" --task-invocation-parameters "RunCommand={Comment=Revising my
Run Command task,Parameters={commands=df}}" --priority 1 --max-concurrency 10 --max-
errors 4 --name "My-Task-Name" --description "A description for my Run Command task"

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "AWS-RunShellScript",
"ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
"TaskParameters": {},
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "Revising my Run Command task",
"Parameters": {
"commands": [
"df"
]
}
}
},
"Priority": 1,
"MaxConcurrency": "10",
"MaxErrors": "4",
"Name": "My-Task-Name",
"Description": "A description for my Run Command task"
}

5. If you are updating a Lambda task, adapt and run the following command to update the task:

492
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

aws ssm update-maintenance-window-task --window-id mw-0c50858d01EXAMPLE

--window-task-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE --targets
"Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-arn
"arn:aws:lambda:us-east-2:111122223333:function:SSMTestLambda" --service-role-
arn "arn:aws:iam::111122223333:role/MaintenanceWindowsRole" --task-invocation-
parameters '{"Lambda":{"Payload":"{\"targetId\":\"{{TARGET_ID}}\",\"targetType\":
\"{{TARGET_TYPE}}\"}"}}' --priority 1 --max-concurrency 10 --max-errors 5 --name "New-
Lambda-Task-Name" --description "A description for my Lambda task"

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}
],
"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestLambda",
"ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
"TaskParameters": {},
"TaskInvocationParameters": {
"Lambda": {
"Payload": "e30="
}
},
"Priority": 1,
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "New-Lambda-Task-Name",
"Description": "A description for my Lambda task"
}

6. If you are updating an AWS Step Functions task, adapt and run the following command to update its
task-invocation-parameters:

aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE"

--window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets
"Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-arn
"arn:aws:states:us-east-2:111122223333:execution:SSMStepFunctionTest" --service-
role-arn "arn:aws:iam::111122223333:role/MaintenanceWindowsRole" --task-invocation-
parameters '{"StepFunctions":{"Input":"{\"instanceId\":\"{{ TARGET_ID }}\"}"}}' --
priority 0 --max-concurrency 10 --max-errors 5 --name "My-Step-Functions-Task" --
description "A description for my Step Functions task"

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "arn:aws:states:us-east-2:111122223333:execution:SSMStepFunctionTest",

493
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
"TaskParameters": {},
"TaskInvocationParameters": {
"StepFunctions": {
"Input": "{\"instanceId\":\"{{ TARGET_ID }}\"}"
}
},
"Priority": 0,
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "My-Step-Functions-Task",
"Description": "A description for my Step Functions task"
}

7. Run the following command to unregister a target from a maintenance window. This example uses
the safe parameter to determine if the target is referenced by any tasks and therefore safe to
unregister:

aws ssm deregister-target-from-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --safe

The system returns information like the following:

An error occurred (TargetInUseException) when calling the

DeregisterTargetFromMaintenanceWindow operation: This Target cannot be deregistered
because it is still referenced in Task: 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE

8. Run the following command to unregister a target from a maintenance window even if the target is
referenced by a task. You can force the unregister operation by using the no-safe parameter:

aws ssm deregister-target-from-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --no-safe

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}

9. Run the following command to update a Run Command task. This example uses a
Systems Manager Parameter Store parameter called UpdateLevel, which is formated as
follows:'{{ssm:UpdateLevel}}'

aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE"

--window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --
targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --task-
invocation-parameters "RunCommand={Comment=A comment for my task
update,Parameters={UpdateLevel='{{ssm:UpdateLevel}}'}}"

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [

494
 AWS Systems Manager User Guide
Maintenance Windows Tutorials (AWS CLI)

"i-02573cafcfEXAMPLE"
]
}
],
"TaskArn": "AWS-RunShellScript",
"ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"TaskParameters": {},
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "A comment for my task update",
"Parameters": {
"UpdateLevel": [
"{{ssm:UpdateLevel}}"
]
}
}
},
"Priority": 10,
"MaxConcurrency": "1",
"MaxErrors": "1"
}

10. Run the following command to update an Automation task to specify WINDOW_ID and
WINDOW_TASK_ID parameters for the task-invocation-parameters parameter:

aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE"

--window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets
"Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE --task-arn
"AutoTestDoc" --service-role-arn arn:aws:iam::111122223333:role/aws-service-
role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM --task-invocation-parameters
"Automation={Parameters={instanceId='{{TARGET_ID}}',initiator='{{WINDOW_ID}}.Task-
{{WINDOW_TASK_ID}}'}}" --priority 3 --max-concurrency 10 --max-errors 5

The system returns information like the following:

{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "AutoTestDoc",
"ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/
ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"TaskParameters": {},
"TaskInvocationParameters": {
"Automation": {
"Parameters": {
"multi": [
"{{WINDOW_TASK_ID}}"
],
"single": [
"{{WINDOW_ID}}"
]
}
}
},

495
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

"Priority": 0,
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "My-Automation-Task",
"Description": "A description for my Automation task"
}

Tutorial: Delete a Maintenance Window (AWS CLI)

To delete a maintenance window you created in these tutorials, run the following command:

aws ssm delete-maintenance-window --window-id "mw-0c50858d01EXAMPLE"

The system returns information like the following:

{
"WindowId":"mw-0c50858d01EXAMPLE"
}

Maintenance Windows Walkthroughs

The walkthroughs in this section show you how to create an AWS Systems Manager maintenance window
using either the AWS Command Line Interface or the AWS Systems Manager Console. The maintenance
window that you create updates SSM Agent on managed instances.

Contents
• Walkthrough: Create a Maintenance Window to Update SSM Agent (AWS CLI) (p. 496)
• Walkthrough: Create a Maintenance Window to Update SSM Agent (Console) (p. 500)

You can also view sample commands in the Systems Manager AWS CLI Reference.

Walkthrough: Create a Maintenance Window to Update SSM

Agent (AWS CLI)
The following walkthrough shows you how to use the AWS CLI to create an AWS Systems Manager
maintenance window. The walkthrough also describes how to register your managed instances as targets
and register a Run Command task to update SSM Agent.

Before You Begin

Before you complete the following procedure, you must either have administrator privileges on the
instances you want to configure or you must have been granted the appropriate permissions in AWS
Identity and Access Management (IAM). Additionally, verify that you have at least one running Amazon
EC2 instance (Linux or Windows) that is configured for Systems Manager. For more information, see
Systems Manager Prerequisites (p. 12).

Topics
• Step 1: Get Started (p. 497)
• Step 2: Create the Maintenance Window (p. 497)
• Step 3: Register Maintenance Window Targets (AWS CLI) (p. 498)
• Step 4: Register a Run Command Task for the Maintenance Window to Update SSM Agent (p. 499)

496
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

Step 1: Get Started

To run commands using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Verify that an instance is ready to be registered as a target for a maintenance window.

Run the following command to view which instances are online.

aws ssm describe-instance-information --query "InstanceInformationList[*]"

Run the following command to view details about a particular instance.

aws ssm describe-instance-information --instance-information-filter-list

key=InstanceIds,valueSet=instance ID

Step 2: Create the Maintenance Window

Use the following procedure to create a maintenance window and specify its basic options, such as
schedule and duration.

Create a maintenance window (AWS CLI)

1. Open the AWS CLI and run the following commands to create a maintenance window that runs
weekly on Sundays at 02:00, in the United States Pacific time zone, with a 1 hour cutoff:

aws ssm create-maintenance-window --name "My-First-Maintenance-Window" --schedule

"cron(0 2 ? * SUN *)" --duration 2 --schedule-timezone "America/Los_Angeles" --
cutoff 1 --no-allow-unassociated-targets

For information about creating cron expressions for the schedule parameter, see Reference: Cron
and Rate Expressions for Systems Manager (p. 933).

For an explanation of how the various schedule-related options for maintenance windows relate to
one another, see Reference: Maintenance Windows Scheduling and Active Period Options (p. 939).

The system returns information like the following:

{
"WindowId":"mw-0c50858d01EXAMPLE"
}

2. To list this and any other maintenance windows created in your AWS account in your current AWS
Region, run the following command:

aws ssm describe-maintenance-windows

The system returns information like the following:

{
"WindowIdentities": [
{
"Cutoff": 1,

497
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

"Name": "My-First-Maintenance-Window",
"NextExecutionTime": "2019-02-03T02:00-08:00",
"Enabled": true,
"WindowId": "mw-0c50858d01EXAMPLE",
"Duration": 2
}
]
}

Step 3: Register Maintenance Window Targets (AWS CLI)

Use the following procedure to register a target with your maintenance window created in Step 2. By
registering a target, you specify which instances to update.

To register maintenance window targets (AWS CLI)

1. Run the following command:

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --resource-type "INSTANCE"

The system returns information like the following, which includes a maintenance window target ID.
Copy or note the WindowTargetId value. You must specify this ID in the next step to register a task
for this maintenance window.

{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}

Alternative commands

Use the following command to register multiple managed instances:

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" --resource-
type "INSTANCE"

Use the following command to register instances by using Amazon EC2 tags. For example:

aws ssm register-target-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --

targets "Key=tag:Environment,Values=Prod" "Key=tag:Role,Values=Web" --resource-type
"INSTANCE"

2. Run the following command to display the targets for a maintenance window:

aws ssm describe-maintenance-window-targets --window-id "mw-0c50858d01EXAMPLE"

The system returns information like the following:

{
"Targets": [
{
"ResourceType": "INSTANCE",
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{

498
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

"Values": [
"i-02573cafcfEXAMPLE"
],
"Key": "InstanceIds"
}
],
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
},
{
"ResourceType": "INSTANCE",
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Values": [
"Prod"
],
"Key": "tag:Environment"
},
{
"Values": [
"Web"
],
"Key": "tag:Role"
}
],
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}
]
}

Step 4: Register a Run Command Task for the Maintenance Window to Update
SSM Agent
Use the following procedure to register a Run Command task for the maintenance window you created in
Step 2. The Run Command task updates SSM Agent on the registered targets.

To register a Run Command task for a maintenance window to update SSM Agent (AWS CLI)

1. Run the following command to register a Run Command task for the maintenance window using the
WindowTargetId value in Step 3. The task updates SSM Agent by using the AWS-UpdateSSMAgent
document.

aws ssm register-task-with-maintenance-window --window-id "mw-0c50858d01EXAMPLE"

--task-arn "AWS-UpdateSSMAgent" --name "UpdateSSMAgent" --targets
"Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --service-role-arn
"arn:aws:iam::1122334455:role/MW-Role" --task-type "RUN_COMMAND" --max-concurrency 1
--max-errors 1 --priority 10

Note
If the targets you registered in the preceding step are Windows Server 2012 R2 or earlier,
you must use the AWS-UpdateEC2Config document.

The system returns information like the following:

{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}

2. Run the following command to list all registered tasks for a maintenance window.

499
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

aws ssm describe-maintenance-window-tasks --window-id "mw-0c50858d01EXAMPLE"

The system returns information like the following:

{
"Tasks": [
{
"ServiceRoleArn": "arn:aws:iam::111122223333:role/MW-Role",
"MaxErrors": "1",
"TaskArn": "AWS-UpdateSSMAgent",
"MaxConcurrency": "1",
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
"TaskParameters": {},
"Priority": 10,
"WindowId": "mw-0c50858d01EXAMPLE",
"Type": "RUN_COMMAND",
"Targets": [
{
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
],
"Key": "WindowTargetIds"
}
],
"Name": "UpdateSSMAgent"
}
]
}

Walkthrough: Create a Maintenance Window to Update SSM

Agent (Console)
The following walkthrough shows you how to use the AWS Systems Manager console to create an AWS
Systems Manager maintenance window. The walkthrough also describes how to register your managed
instances as targets and register a Run Command task to update SSM Agent.

Before You Begin

Before you complete the following procedure, you must either have administrator privileges on the
instances you want to configure or you must have been granted the appropriate permissions in AWS
Identity and Access Management (IAM). Additionally, verify that you have at least one running Amazon
EC2 instance (Linux or Windows) that is configured for Systems Manager. For more information, see
Systems Manager Prerequisites (p. 12).

Topics
• Step 1: Create the Maintenance Window (Console) (p. 500)
• Step 2: Register Maintenance Window Targets (Console) (p. 501)
• Step 3: Register a Run Command Task for the Maintenance Window to Update SSM Agent
(Console) (p. 502)

Step 1: Create the Maintenance Window (Console)

To create a maintenance window (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

500
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

2. In the navigation pane, choose Maintenance Windows.

3. Choose Create maintenance window.
4. For Name, enter a descriptive name to help you identify this maintenance window as a test
maintenance window.
5. For Description, enter a description.
6. Choose Allow unregistered targets if you want to allow a maintenance window task to run on
managed instances, even if you have not registered those instances as targets. If you choose this
option, then you can choose the unregistered instances (by instance ID) when you register a task
with the maintenance window.

If you don't choose this option, then you must choose previously-registered targets when you
register a task with the maintenance window.
7. Specify a schedule for the maintenance window by using one of the three scheduling options.

For information about building cron/rate expressions, see Reference: Cron and Rate Expressions for
Systems Manager (p. 933).
8. For Duration, enter the number of hours the maintenance window should run.
9. For Stop initiating tasks, enter the number of hours before the end of the maintenance window
that the system should stop scheduling new tasks to run.
10. (Optional) For Start date (optional), specify a date and time, in ISO-8601 Extended format, for
when you want the maintenance window to become active. This allows you to delay activation of
the maintenance window until the specified future date.
11. (Optional) For End date (optional), specify a date and time, in ISO-8601 Extended format, for when
you want the maintenance window to become inactive. This allows you to set a date and time in the
future after which the maintenance window no longer runs.
12. (Optional) For Time zone (optional), specify the time zone to base scheduled maintenance window
executions on, in Internet Assigned Numbers Authority (IANA) format. For example: "America/
Los_Angeles", "etc/UTC", or "Asia/Seoul".

For more information about valid formats, see the Time Zone Database on the IANA website.
13. Choose Create maintenance window. The system returns you to the maintenance window page. The
maintenance window you just created is in the Enabled state.

Step 2: Register Maintenance Window Targets (Console)

Use the following procedure to register a target with the maintenance window you created in Step 1. By
registering a target, you specify which instances to update.

To assign targets to a maintenance window (console)

1. In the list of maintenance windows, choose the maintenance window you just created.
2. Choose Actions, and then choose Register targets.
3. For Target Name, enter a name for the target.
4. For Description, enter a description.
5. (Optional) For Owner information, specify your name or work alias. Owner information is included
in any Amazon CloudWatch Events raised while running tasks for these targets in this maintenance
window.

For information about using CloudWatch Events to monitor Systems Manager events, see
Monitoring Systems Manager Events with Amazon CloudWatch Events (p. 891).
6. In the Select targets by section, choose Specifying Tags to target instances by using Amazon EC2
tags that you previously assigned to the instances. Choose Manually Selecting Instances to choose
individual instances according to their instance IDs.

501
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

Note
If you don't see the instances that you want to target, verify that those instances are
configured for Systems Manager. For more information, see Setting Up AWS Systems
Manager (p. 23).
7. Choose Register target.

Step 3: Register a Run Command Task for the Maintenance Window to Update
SSM Agent (Console)
Use the following procedure to register a Run Command task for the maintenance window you created in
Step 1. The Run Command task updates SSM Agent on the registered targets.

To assign tasks to a maintenance window (console)

1. In the list of maintenance windows, choose the maintenance window you just created.
2. Choose Actions, and then choose Register Run Command task.
3. For Name, enter a name for the task, such as UpdateSSMAgent.
4. For Description, enter a description.
5. For Document, choose the SSM Command document AWS-UpdateSSMAgent.
Note
If the targets you registered in the preceding step are Windows Server 2012 R2 or earlier,
you must use the AWS-UpdateEC2Config document.
6. For Task priority, specify a priority for this task. 1 is the highest priority. Tasks in a maintenance
window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
7. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. For IAM service role, choose one of the following options to provide permissions for Systems
Manager to run tasks on your target instances:

• Create and use a service-linked role for Systems Manager

Service-linked roles provide a secure way to delegate permissions to AWS services because only
the linked service can assume a service-linked role. Additionally, AWS automatically defines and
sets the permissions of service-linked roles, depending on the actions that the linked service
performs on your behalf.

502
 AWS Systems Manager User Guide
Maintenance Windows Walkthroughs

Note
If a service-linked role has already been created for your account, choose Use the service-
linked role for Systems Manager.
• Use a custom service role

You can create a custom service role for maintenance window tasks if you want to use stricter
permissions than those provided by the service-linked role. Or you can create a custom service
role if you want to use Amazon Simple Notification Service (Amazon SNS) to send notifications
related to maintenance window tasks run through Run Command.

If you need to create a custom service role, see one of the following topics:
• Control Access to Maintenance Windows (Console) (p. 446)
• Control Access to Maintenance Windows (AWS CLI) (p. 449)
• Control Access to Maintenance Windows (Tools for Windows PowerShell) (p. 452)

To help you decide whether to use a custom service role or the Systems Manager service-linked role
with a maintenance window task, see Should I Use a Service-Linked Role or a Custom Service Role to
Run Maintenance Window Tasks? (p. 445).
10. In the Output options section, you can optionally enable writing command output to an Amazon S3
bucket. If you choose to enable this option, specify the Amazon S3 bucket name and optional S3 key
prefix to which you want the command output written.
11. In the SNS notifications section, you can optionally enable Systems Manager to send notifications
about command statuses using Amazon SNS. If you choose to enable this option, you need to
specify the following:

a. The IAM role to trigger Amazon SNS notifications.

b. The Amazon SNS topic to be used.
c. The specific event types about which you want to be notified.
d. The notification type that you want to receive when the status of a command changes.
For commands sent to multiple instances, choose Invocation to receive notification on an
invocation (per-instance) basis when the status of each invocation changes.
12. In the Input Parameters section, you can optionally provide a specific version of SSM Agent to
install, or you can allow SSM Agent service to be downgraded to an earlier version. However, for this
walkthrough we don't provide a version. Therefore, SSM Agent is be updated to the latest version.
13. Choose Register Run Command task.

503
 AWS Systems Manager User Guide
Compliance

AWS Systems Manager Instances &

Nodes
AWS Systems Manager provides the following capabilities for managing your Amazon EC2 instances,
your on-premises servers and virtual machines (VMs) in your hybrid environment, and other types of
AWS resources (nodes).

Topics
• AWS Systems Manager Configuration Compliance (p. 504)
• AWS Systems Manager Inventory (p. 512)
• AWS Systems Manager Managed Instances (p. 563)
• AWS Systems Manager Activations (p. 567)
• AWS Systems Manager Session Manager (p. 567)
• AWS Systems Manager Run Command (p. 613)
• AWS Systems Manager State Manager (p. 645)
• AWS Systems Manager Patch Manager (p. 683)
• AWS Systems Manager Distributor (p. 749)

AWS Systems Manager Configuration Compliance

You can use AWS Systems Manager Configuration Compliance to scan your fleet of managed instances
for patch compliance and configuration inconsistencies. You can collect and aggregate data from
multiple AWS accounts and Regions, and then drill down into specific resources that aren’t compliant.
By default, Configuration Compliance displays current compliance data about Systems Manager Patch
Manager patching and Systems Manager State Manager associations. Systems Manager Compliance
offers the following additional benefits and features:

• View compliance history and change tracking for Patch Manager patching data and State Manager
associations by using AWS Config.
• Customize Systems Manager Compliance to create your own compliance types based on your IT or
business requirements.
• Remediate issues by using Systems Manager Run Command, State Manager, or Amazon CloudWatch
Events.
• Port data to Amazon Athena and Amazon QuickSight to generate fleet-wide reports.

Configuration Compliance is offered at no additional charge. You only pay for the AWS resources that
you use.
Note
Systems Manager integrates with Chef InSpec. InSpec is an open-source, runtime framework
that enables you to create human-readable profiles on GitHub or Amazon S3. Then you can use
Systems Manager to run compliance scans and view compliant and noncompliant instances. For
more information, see Using Chef InSpec Profiles with Systems Manager Compliance (p. 105).

Contents

504
 AWS Systems Manager User Guide
Getting Started with Configuration Compliance

• Getting Started with Configuration Compliance (p. 505)

• Creating a Resource Data Sync for Configuration Compliance (p. 505)
• Working With Configuration Compliance (p. 507)
• Remediating Compliance Issues (p. 510)
• Configuration Compliance Walkthrough (AWS CLI) (p. 511)

Getting Started with Configuration Compliance

To get started with Configuration Compliance, complete the following tasks.

Task For More Information

Configuration Compliance works with Patch Systems Manager Prerequisites (p. 12)
Manager patch data, State Manager associations,
and custom compliance types on Systems
Manager managed instances. Verify that your
Amazon EC2 instances and hybrid machines are
configured as managed instances by verifying
Systems Manager prerequisites.

Update SSM Agent on your managed instances to Working with SSM Agent (p. 64)
the latest version.

If you plan to monitor patch compliance, verify AWS Systems Manager Patch Manager (p. 683)
that you've configured Systems Manager Patch
Manager. You must perform patching operations
by using Patch Manager before Configuration
Compliance can display patch compliance data.

If you plan to monitor association compliance, AWS Systems Manager State Manager (p. 645)
verify that you've created State Manager
associations. You must create associations before
Configuration Compliance can display association
compliance data.

(Optional) Configure the system to view Viewing Compliance Configuration History and
compliance history and change tracking. Change Tracking (p. 509)

(Optional) Create custom compliance types. Configuration Compliance Walkthrough (AWS

CLI) (p. 511)

(Optional) Create a Resource Data Sync to Creating a Resource Data Sync for Configuration
aggregate all compliance data in a target Amazon Compliance (p. 505)
S3 bucket.

Creating a Resource Data Sync for Configuration

Compliance
You can use Systems Manager Resource Data Sync to send compliance data from all of your managed
instances to a target Amazon S3 bucket. When you create the sync, you can specify managed instances
from multiple AWS accounts, AWS Regions, and your on-premises hybrid environment. Resource Data
Sync then automatically updates the centralized data when new compliance data is collected. With all
compliance data stored in a target Amazon S3 bucket, you can use services like Amazon Athena and

505
 AWS Systems Manager User Guide
Creating a Resource Data Sync
for Configuration Compliance

Amazon QuickSight to query and analyze the aggregated data. Configuring Resource Data Sync for
configuration compliance is a one-time operation.

The following graphic shows how Resource Data Sync aggregates all data from different accounts,
Regions, and your hybrid environment to a central repository.

Use the following procedure to create a Resource Data Sync for Configuration Compliance by using the
Amazon EC2 console.

To create and configure an Amazon S3 Bucket for Resource Data Sync (console)

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

2. Create a bucket to store your aggregated Inventory data. For more information, see Create a Bucket
in the Amazon Simple Storage Service Getting Started Guide. Make a note of the bucket name and the
AWS Region where you created it.
3. Choose the Permissions tab, and then choose Bucket Policy.
4. Copy and paste the following bucket policy into the policy editor. Replace Bucket-Name and
Account-ID with the name of the Amazon S3 bucket you created and a valid AWS account ID.
Optionally, replace Bucket-Prefix with the name of an Amazon S3 prefix (subdirectory). If you
didn't create a prefix, remove Bucket-Prefix/ from the ARN in the policy.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SSMBucketPermissionsCheck",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::Bucket-Name"
},
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",

506
 AWS Systems Manager User Guide
Working With Configuration Compliance

"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": ["arn:aws:s3:::Bucket-Name/Bucket-Prefix/*/
accountid=Account_ID_number/*"],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control"
}
}
}
]
}

To create a Resource Data Sync

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Managed Instances.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Managed Instances.
3. Choose Resource Data Syncs, and then choose Create resource data sync.
4. In the Sync name field, type a name for the sync configuration.
5. In the Bucket name field, type the name of the Amazon S3 bucket you created at the start of this
procedure.
6. (Optional) In the Bucket prefix field, type the name of an Amazon S3 bucket prefix (subdirectory).
7. In the Bucket region field, choose This region if the Amazon S3 bucket you created is located in the
current AWS Region. If the bucket is located in a different AWS Region, choose Another region, and
type the name of the Region.
Note
If the sync and the target Amazon S3 bucket are located in different regions, you may be
subject to data transfer pricing. For more information, see Amazon S3 Pricing.
8. Choose Create.

Working With Configuration Compliance

Configuration Compliance collects and reports data about the status of Patch Manager patching,
State Manager associations, and custom compliance types. This section includes details about each of
these compliance types and how to view Systems Manager compliance data. This section also includes
information about how to view compliance history and change tracking.
Note
Systems Manager integrates with Chef InSpec. InSpec is an open-source, runtime framework
that enables you to create human-readable profiles on GitHub or Amazon S3. Then you can use
Systems Manager to run compliance scans and view compliant and noncompliant instances. For
more information, see Using Chef InSpec Profiles with Systems Manager Compliance (p. 105).

Topics
• About Patch Compliance (p. 508)
• About State Manager Association Compliance (p. 508)
• About Custom Compliance (p. 508)

507
 AWS Systems Manager User Guide
Working With Configuration Compliance

• Viewing Current Compliance Data (p. 508)

• Viewing Compliance Configuration History and Change Tracking (p. 509)

About Patch Compliance

After you use Systems Manager Patch Manager to install patches on your instances, compliance status
information is immediately available to you in the console or in response to AWS CLI commands or
corresponding Systems Manager API actions.

For information about patch compliance status values, see About Patch Compliance States (p. 708).

About State Manager Association Compliance

After you create one or more State Manager associations, compliance status information is immediately
available to you in the console or in response to AWS CLI commands or corresponding Systems
Manager API actions. For associations, Configuration Compliance shows statuses of Compliant or Non-
compliant and the severity level assigned to the association, such as Critical or Medium.

About Custom Compliance

You can assign compliance metadata to a managed instance. This metadata can then be aggregated
with other compliance data for compliance reporting purposes. For example, say that your business runs
versions 2.0, 3.0, and 4.0 of software X on your managed instances. The company wants to standardize
on version 4.0, meaning that instances running versions 2.0 and 3.0 are non-compliant. You can use the
PutComplianceItems API action to explicitly note which managed instances are running older versions
of software X. Currently you can only assign compliance metadata by using the AWS CLI, AWS Tools for
Windows PowerShell, or the SDKs. The following CLI sample command assigns compliance metadata to a
managed instance and specifies the compliance type in the required format Custom:.

aws ssm put-compliance-items --resource-id i-1234567890abcdef0 --

resource-type ManagedInstance --compliance-type Custom:SoftwareXCheck
--execution-summary ExecutionTime=AnyStringToDenoteTimeOrDate --items
Id=Version2.0,Title=SoftwareXVersion,Severity=CRITICAL,Status=NON_COMPLIANT

Compliance managers can then view summaries or create reports about which instances are or aren't
compliant. You can assign a maximum of 10 different custom compliance types to an instance.

For an example of how to create a custom compliance type and view compliance data, see Configuration
Compliance Walkthrough (AWS CLI) (p. 511).

Viewing Current Compliance Data

This section describes how to view compliance data in the AWS Systems Manager console and by using
the AWS CLI. For information about how to view patch and association compliance history and change
tracking, see Viewing Compliance Configuration History and Change Tracking (p. 509).

Topics
• Viewing Current Compliance Data (Console) (p. 508)
• Viewing Current Compliance Data (AWS CLI) (p. 509)

Viewing Current Compliance Data (Console)

Use the following procedure to view compliance data in the Systems Manager console.

508
 AWS Systems Manager User Guide
Working With Configuration Compliance

To view current compliance reports in the Systems Manager console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Compliance.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Compliance in the navigation pane.
3. In the Corresponding managed instances area, choose an instance ID to view its detailed
configuration compliance report.

Note
For information about fixing compliance issues, see Remediating Compliance Issues (p. 510).

Viewing Current Compliance Data (AWS CLI)

You can view summaries of compliance data for patching, associations, and custom compliance types in
the in the AWS CLI by using the following AWS CLI commands.

list-compliance-summaries

Returns a summary count of compliant and non-compliant association statuses according to the
filter you specify. (API: ListComplianceSummaries)
list-resource-compliance-summaries

Returns a resource-level summary count. The summary includes information about compliant and
non-compliant statuses and detailed compliance-item severity counts, according to the filter criteria
you specify. (API: ListResourceComplianceSummaries)

You can view additional compliance data for patching by using the following AWS CLI commands.

describe-patch-group-state

Returns high-level aggregated patch compliance state for a patch group. (API:
DescribePatchGroupState)
describe-instance-patch-states-for-patch-group

Returns the high-level patch state for the instances in the specified patch group. (API:
DescribeInstancePatchStatesForPatchGroup)

Note
For an illustration of how to configure patching and view patch compliance details by using the
AWS CLI, see Tutorial: Patch a Server Environment (AWS CLI) (p. 732).

Viewing Compliance Configuration History and Change Tracking

Systems Manager Configuration Compliance displays current patching and association compliance
data for your managed instances. You can view patching and association compliance history and
change tracking by using AWS Config. AWS Config provides a detailed view of the configuration of AWS
resources in your AWS account. This includes how the resources are related to one another and how they
were configured in the past so that you can see how the configurations and relationships change over
time. To view patching and association compliance history and change tracking, you must enable the
following resources in AWS Config:

• SSM:PatchCompliance

509
 AWS Systems Manager User Guide
Remediating Compliance Issues

• SSM:AssociationCompliance

For information about how to choose and configure these specific resources in AWS Config, see Selecting
Which Resources AWS Config Records in the AWS Config Developer Guide.
Note
For information about AWS Config pricing, see Pricing.

Remediating Compliance Issues

You can quickly remediate patch and association compliance issues by using Systems Manager Run
Command. You can target either instance IDs or Amazon EC2 tags and run the AWS-RunPatchBaseline
document or the AWS-RefreshAssociation document. If refreshing the association or re-running the
patch baseline fails to resolve the compliance issue, then you need to investigate your associations, patch
baselines, or instance configurations to understand why the Run Command executions did not resolve
the problem.

For more information about patching, see AWS Systems Manager Patch Manager (p. 683) and About
the SSM Document AWS-RunPatchBaseline (p. 703).

For more information about associations, see Working with Associations in Systems Manager (p. 647).

For more information about running a command, see Running Commands Using Systems Manager Run
Command (p. 619).

Specify Configuration Compliance as the target of a CloudWatch Events event

You can also configure CloudWatch Events to perform an action in response to Configuration Compliance
events. For example, if one or more instances fail to install Critical patch updates or run an association
that installs anti-virus software, then you can configure CloudWatch to run the AWS-RunPatchBaseline
document or the AWS-RefreshAssocation document when the Configuration Compliance event occurs.

Use the following procedure to configure Configuration Compliance as the target of a CloudWatch event.

To configure Configuration Compliance as the target of a CloudWatch event (console)

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then choose Create rule.
3. Choose Event Pattern. Event Pattern lets you build a rule that generates events for specific actions
in AWS services.
4. In the Service Name field, choose EC2 Simple Systems Manager (SSM)
5. In the Event Type field, choose Configuration Compliance.
6. Choose Add target.
7. In the Select target type list, choose SSM Run Command.
8. In the Document list, choose an SSM document to run when your target is invoked. For
example, choose AWS-RunPatchBaseline for a non-compliant patch event, or choose AWS-
RefreshAssociation for a non-compliant association event.
9. Specify information for the remaining fields and parameters.
Note
Required fields and parameters have an asterisk (*) next to the name. To create a target, you
must specify a value for each required parameter or field. If you don't, the system creates
the rule, but the rule won't be run.
10. Choose Configure details and complete the wizard.

510
 AWS Systems Manager User Guide
Configuration Compliance Walkthrough (AWS CLI)

Configuration Compliance Walkthrough (AWS CLI)

The following procedure walks you through the process of using the PutComplianceItems API action to
assign custom compliance metadata to a resource. You can also use this API action to manually assign
patch or association compliance metadata to an instance, as shown in the following walkthrough. For
more information about custom compliance, see About Custom Compliance (p. 508).

To assign custom compliance metadata to a managed instance (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to assign custom compliance metadata to an instance. Currently the
only supported resource type is ManagedInstance.

aws ssm put-compliance-items --resource-id Instance ID --resource-type ManagedInstance

--compliance-type Custom:User-defined string --execution-summary ExecutionTime=User-
defined time and/or date value --items Id=User-defined ID,Title=User-defined
title,Severity=One or more comma-separated severities:CRITICAL, MAJOR,
MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT

3. Repeat the previous step to assign additional custom compliance metadata to one or more
instances. You can also manually assign patch or association compliance metadata to managed
instances by using the following commands:

Association compliance metadata

aws ssm put-compliance-items --resource-id Instance ID --resource-type ManagedInstance

--compliance-type Association --execution-summary ExecutionTime=User-defined time
and/or date value --items Id=User-defined ID,Title=User-defined title,Severity=One
or more comma-separated severities:CRITICAL,MAJOR,MINOR,INFORMATIONAL, or
UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT,Details="{DocumentName=The SSM document
for the association,DocumentVersion=A version number}"

Patch compliance metadata

aws ssm put-compliance-items --resource-id Instance ID --resource-type ManagedInstance

--compliance-type Patch --execution-summary ExecutionTime=User-defined time and/
or date value,ExecutionId=User-defined ID,ExecutionType=Command --items Id=for
example, KB12345,Title=User-defined title,Severity=One or more comma-separated
severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or
NON_COMPLIANT,Details="{PatchGroup=Name of group,PatchSeverity=The patch severity, for
example, CRITICAL}"

4. Run the following command to view a list of compliance items for a specific managed instance. Use
filters to drill down into specific compliance data.

aws ssm list-compliance-items --resource-ids Instance ID --resource-types

ManagedInstance --filters One or more filters.

The following examples show you how to use this command with filters.

aws ssm list-compliance-items --resource-ids i-1234567890abcdef0 --resource-

type ManagedInstance --filters Key=DocumentName,Values=AWS-RunPowerShellScript
Key=Status,Values=NON_COMPLIANT,Type=NotEqual Key=Id,Values=cee20ae7-6388-488e-8be1-
a88cc6c46dcc Key=Severity,Values=UNSPECIFIED

511
 AWS Systems Manager User Guide
Inventory

aws ssm list-resource-compliance-summaries --filters

Key=OverallSeverity,Values=UNSPECIFIED

aws ssm list-resource-compliance-summaries --filters

Key=OverallSeverity,Values=UNSPECIFIED Key=ComplianceType,Values=Association
Key=InstanceId,Values=i-1234567890abcdef0

5. Run the following command to view a summary of compliance statuses. Use filters to drill down into
specific compliance data.

aws ssm list-resource-compliance-summaries --filters One or more filters.

The following examples show you how to use this command with filters.

aws ssm list-resource-compliance-summaries --filters Key=ExecutionType,Values=Command

aws ssm list-resource-compliance-summaries --filters

Key=AWS:InstanceInformation.PlatformType,Values=Windows
Key=OverallSeverity,Values=CRITICAL

6. Run the following command to view a summary count of compliant and non-compliant resources for
a compliance type. Use filters to drill down into specific compliance data.

aws ssm list-compliance-summaries --filters One or more filters.

The following examples show you how to use this command with filters.

aws ssm list-compliance-summaries --filters

Key=AWS:InstanceInformation.PlatformType,Values=Windows
Key=PatchGroup,Values=TestGroup

aws ssm list-compliance-summaries --filters

Key=AWS:InstanceInformation.PlatformType,Values=Windows
Key=ExecutionId,Values=4adf0526-6aed-4694-97a5-145222f4c2b6

AWS Systems Manager Inventory

AWS Systems Manager Inventory provides visibility into your Amazon EC2 and on-premises computing
environment. You can use Inventory to collect metadata from your managed instances. You can store this
metadata in a central Amazon Simple Storage Service (Amazon S3) bucket, and then use built-in tools
to query the data and quickly determine which instances are running the software and configurations
required by your software policy, and which instances need to be updated. You can configure Inventory
on all of your managed instances by using a one-click procedure. You can also configure and view
inventory data from multiple AWS Regions and accounts.

If the pre-configured metadata types collected by Systems Manager Inventory don't meet your needs,
then you can create custom inventory. Custom inventory is simply a JSON file with information that
you provide and add to the managed instance in a specific directory. When Systems Manager Inventory
collects data, it captures this custom inventory data. For example, if you run a large datacenter, you can
specify the rack location of each of your servers as custom inventory. You can then view the rack space
data when you view other inventory data.

512
 AWS Systems Manager User Guide
Inventory

Important
Systems Manager Inventory collects only metadata from your managed instances. Inventory
does not access proprietary information or data.

The following table lists the types of metadata that you can collect with Systems Manager Inventory. The
table also lists the instances you can collect inventory information from and the collection intervals you
can specify.

Configuration Details

Metadata types You can configure Inventory to collect the

following types of metadata:

• Applications: Application names, publishers,

versions, etc.
• AWS components: EC2 driver, agents, versions,
etc.
• Files: Name, size, version, installed date,
modification and last accessed times, etc.
• Network configuration: IP address, MAC
address, DNS, gateway, subnet mask, etc.
• Windows updates: Hotfix ID, installed by,
installed date, etc.
• Instance details: System name, operating
systems (OS) name, OS version, last boot, DNS,
domain, work group, OS architecture, etc.
• Services: Name, display name, status,
dependent services, service type, start type, etc.
• Tags: Tags assigned to your instances.
• Windows Registry: Registry key path, value
name, value type, and value.
• Windows roles: Name, display name, path,
feature type, installed state, etc.
• Custom inventory: Metadata that was assigned
to a managed instance as described in Working
with Custom Inventory (p. 541).

Note
To view a list of all metadata collected
by Inventory, see Metadata Collected by
Inventory (p. 515).

Instances to collect information from You can choose to inventory all instances in your
AWS account, individually select instances, or
target groups of instances by using Amazon EC2
tags. For more information about performing
inventory collection on all of your instances, see
Inventory All Managed Instances in Your AWS
Account (p. 524).

When to collect information You can specify a collection interval in terms of

minutes, hours, days, and weeks. The shortest
collection interval is every 30 minutes.

513
 AWS Systems Manager User Guide
Inventory

Note
Depending on the amount of data collected, the system can take several minutes to report the
data to the output you specified. After the information is collected, the metadata is sent over a
secure HTTPS channel to a plain-text AWS store that is accessible only from your AWS account.

You can view the data in the AWS Systems Manager console on the Inventory page, which includes
several predefined cards to help you query the data.

Note
Inventory cards automatically filter out Amazon EC2 managed instances with a state of
Terminated and Stopped. For on-premises managed instances, Inventory cards automatically
filter out instances with a state of Terminated.

If you create a Resource Data Sync to synchronize and store all of your data in a single Amazon
S3 bucket, then you can drill down into the data on the Inventory Detailed View page. For more
information, see Querying Inventory Data from Multiple Regions and Accounts (p. 527).

Contents
• Learn More About Systems Manager Inventory (p. 515)
• Configuring Resource Data Sync for Inventory (p. 520)

514
 AWS Systems Manager User Guide
Learn More About Inventory

• Configuring Inventory Collection (p. 523)

• Working with Systems Manager Inventory Data (p. 527)
• Working with Custom Inventory (p. 541)
• Viewing Inventory History and Change Tracking (p. 551)
• Systems Manager Inventory Walkthroughs (p. 552)
• Troubleshooting Problems with Systems Manager Inventory (p. 562)

Learn More About Systems Manager Inventory

When you configure Systems Manager Inventory, you specify the type of metadata to collect, the
instances from where the metadata should be collected, and a schedule for metadata collection. These
configurations are saved with your AWS account as a Systems Manager State Manager association. An
association is simply a configuration.
Note
Inventory only collects metadata. It does not collect any personal or proprietary data.

Topics
• Metadata Collected by Inventory (p. 515)
• Working with File and Windows Registry Inventory (p. 518)
• Related AWS Services (p. 520)

Metadata Collected by Inventory

The following sample shows the complete list of metadata collected by each Inventory plugin.

[
{
"typeName": "AWS:InstanceInformation",
"version": "1.0",
"attributes":[
{ "name": "AgentType", "dataType" : "STRING"},
{ "name": "AgentVersion", "dataType" : "STRING"},
{ "name": "ComputerName", "dataType" : "STRING"},
{ "name": "IamRole", "dataType" : "STRING"},
{ "name": "InstanceId", "dataType" : "STRING"},
{ "name": "IpAddress", "dataType" : "STRING"},
{ "name": "PlatformName", "dataType" : "STRING"},
{ "name": "PlatformType", "dataType" : "STRING"},
{ "name": "PlatformVersion", "dataType" : "STRING"},
{ "name": "ResourceType", "dataType" : "STRING"}
]
},
{
"typeName" : "AWS:Application",
"version": "1.1",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "ApplicationType", "dataType": "STRING"},
{ "name": "Publisher", "dataType": "STRING"},
{ "name": "Version", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "Architecture", "dataType": "STRING"},
{ "name": "URL", "dataType": "STRING"},
{ "name": "Summary", "dataType": "STRING"},

515
 AWS Systems Manager User Guide
Learn More About Inventory

{ "name": "PackageId", "dataType": "STRING"},

{ "name": "Release", "dataType": "STRING"},
{ "name": "Epoch", "dataType": "STRING"}
]
},
{
"typeName" : "AWS:File",
"version": "1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "Size", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "FileVersion", "dataType": "STRING"},
{ "name": "InstalledDate", "dataType": "STRING"},
{ "name": "ModificationTime", "dataType": "STRING"},
{ "name": "LastAccessTime", "dataType": "STRING"},
{ "name": "ProductName", "dataType": "STRING"},
{ "name": "InstalledDir", "dataType": "STRING"},
{ "name": "ProductLanguage", "dataType": "STRING"},
{ "name": "CompanyName", "dataType": "STRING"},
{ "name": "ProductVersion", "dataType": "STRING"}
]
},
{
"typeName": "AWS:AWSComponent",
"version": "1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "ApplicationType", "dataType": "STRING"},
{ "name": "Publisher", "dataType": "STRING"},
{ "name": "Version", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "Architecture", "dataType": "STRING"},
{ "name": "URL", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsUpdate",
"version":"1.0",
"attributes":[
{ "name": "HotFixId", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "InstalledBy", "dataType": "STRING"}
]
},
{
"typeName": "AWS:Network",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "SubnetMask", "dataType": "STRING"},
{ "name": "Gateway", "dataType": "STRING"},
{ "name": "DHCPServer", "dataType": "STRING"},
{ "name": "DNSServer", "dataType": "STRING"},
{ "name": "MacAddress", "dataType": "STRING"},
{ "name": "IPV4", "dataType": "STRING"},
{ "name": "IPV6", "dataType": "STRING"}
]
},
{
"typeName": "AWS:PatchSummary",
"version":"1.0",
"attributes":[
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "BaselineId", "dataType": "STRING"},

516
 AWS Systems Manager User Guide
Learn More About Inventory

{ "name": "SnapshotId", "dataType": "STRING"},

{ "name": "OwnerInformation", "dataType": "STRING"},
{ "name": "InstalledCount", "dataType": "NUMBER"},
{ "name": "InstalledOtherCount", "dataType": "NUMBER"},
{ "name": "NotApplicableCount", "dataType": "NUMBER"},
{ "name": "MissingCount", "dataType": "NUMBER"},
{ "name": "FailedCount", "dataType": "NUMBER"},
{ "name": "OperationType", "dataType": "STRING"},
{ "name": "OperationStartTime", "dataType": "STRING"},
{ "name": "OperationEndTime", "dataType": "STRING"}
]
},
{
"typeName": "AWS:ComplianceItem",
"version":"1.0",
"attributes":[
{ "name": "ComplianceType", "dataType": "STRING"},
{ "name": "ExecutionId", "dataType": "STRING"},
{ "name": "ExecutionType", "dataType": "STRING"},
{ "name": "ExecutionTime", "dataType": "STRING"},
{ "name": "Id", "dataType": "STRING"},
{ "name": "Title", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "Severity", "dataType": "STRING"},
{ "name": "DocumentName", "dataType": "STRING"},
{ "name": "DocumentVersion", "dataType": "STRING"},
{ "name": "Classification", "dataType": "STRING"},
{ "name": "PatchBaselineId", "dataType": "STRING"},
{ "name": "PatchSeverity", "dataType": "STRING"},
{ "name": "PatchState", "dataType": "STRING"},
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"}
]
},
{
"typeName": "AWS:ComplianceSummary",
"version":"1.0",
"attributes":[
{ "name": "ComplianceType", "dataType": "STRING"},
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "PatchBaselineId", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "OverallSeverity", "dataType": "STRING"},
{ "name": "ExecutionId", "dataType": "STRING"},
{ "name": "ExecutionType", "dataType": "STRING"},
{ "name": "ExecutionTime", "dataType": "STRING"},
{ "name": "CompliantCriticalCount", "dataType": "NUMBER"},
{ "name": "CompliantHighCount", "dataType": "NUMBER"},
{ "name": "CompliantMediumCount", "dataType": "NUMBER"},
{ "name": "CompliantLowCount", "dataType": "NUMBER"},
{ "name": "CompliantInformationalCount", "dataType": "NUMBER"},
{ "name": "CompliantUnspecifiedCount", "dataType": "NUMBER"},
{ "name": "NonCompliantCriticalCount", "dataType": "NUMBER"},
{ "name": "NonCompliantHighCount", "dataType": "NUMBER"},
{ "name": "NonCompliantMediumCount", "dataType": "NUMBER"},
{ "name": "NonCompliantLowCount", "dataType": "NUMBER"},
{ "name": "NonCompliantInformationalCount", "dataType": "NUMBER"},
{ "name": "NonCompliantUnspecifiedCount", "dataType": "NUMBER"}
]
},
{
"typeName": "AWS:InstanceDetailedInformation",
"version":"1.0",
"attributes":[
{ "name": "CPUModel", "dataType": "STRING"},
{ "name": "CPUCores", "dataType": "NUMBER"},

517
 AWS Systems Manager User Guide
Learn More About Inventory

{ "name": "CPUs", "dataType": "NUMBER"},

{ "name": "CPUSpeedMHz", "dataType": "NUMBER"},
{ "name": "CPUSockets", "dataType": "NUMBER"},
{ "name": "CPUHyperThreadEnabled", "dataType": "STRING"},
{ "name": "OSServicePack", "dataType": "STRING"}
]
},
{
"typeName": "AWS:Service",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "DisplayName", "dataType": "STRING"},
{ "name": "ServiceType", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "DependentServices", "dataType": "STRING"},
{ "name": "ServicesDependedOn", "dataType": "STRING"},
{ "name": "StartType", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsRegistry",
"version":"1.0",
"attributes":[
{ "name": "KeyPath", "dataType": "STRING"},
{ "name": "ValueName", "dataType": "STRING"},
{ "name": "ValueType", "dataType": "STRING"},
{ "name": "Value", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsRole",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "DisplayName", "dataType": "STRING"},
{ "name": "Path", "dataType": "STRING"},
{ "name": "FeatureType", "dataType": "STRING"},
{ "name": "DependsOn", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "Installed", "dataType": "STRING"},
{ "name": "InstalledState", "dataType": "STRING"},
{ "name": "SubFeatures", "dataType": "STRING"},
{ "name": "ServerComponentDescriptor", "dataType": "STRING"},
{ "name": "Parent", "dataType": "STRING"}
]
}
]

Note
With the release of version 2.5, RPM Package Manager replaced the Serial attribute with Epoch.
The Epoch attribute is a monotonically increasing integer like Serial. When you inventory by
using the AWS:Application type, note that a larger value for Epoch means a newer version. If
Epoch values are the same or empty, then use the value of the Version or Release attribute to
determine the newer version.

Working with File and Windows Registry Inventory

Systems Manager Inventory enables you to search and inventory files on Windows and Linux operating
systems. You can also search and inventory the Windows Registry.

Files: You can collect metadata information about files, including file names, the time files were created,
the time files were last modified and accessed, and file sizes, to name a few. To start collecting file

518
 AWS Systems Manager User Guide
Learn More About Inventory

inventory, you specify a file path where you want to perform the inventory, one or more patterns that
define the types of files you want to inventory, and if the path should be traversed recursively. Systems
Manager inventories all file metadata for files in the specified path that match the pattern. File inventory
uses the following parameter input.

{
"Path": string,
"Pattern": array[string],
"Recursive": true,
"DirScanLimit" : number // Optional
}

• Path: The directory path where you want to inventory files. For Windows, you can use environment
variables like %PROGRAMFILES% as long as the variable maps to a single directory path. For example,
if you use %PATH% that maps to multiple directory paths, Inventory throws an error.
• Pattern: An array of patterns to identify files.
• Recursive: A Boolean value indicating whether Inventory should recursively traverse the directories.
• DirScanLimit: An optional value specifying how many directories to scan. Use this parameter to
minimize performance impact on your instances. By default, Inventory scans a maximum of 5,000
directories.

Note
Inventory collects metadata for a maximum of 500 files across all specified paths.

Here are some examples of how to specify the parameters when performing an inventory of files.

• On Linux, collect metadata of .sh files in the /home/ec2-user directory, excluding all subdirectories.

[{"Path":"/home/ec2-user","Pattern":["*.sh", "*.sh"],"Recursive":false}]

• On Windows, collect metadata of all ".exe" files in the Program Files folder, including subdirectories
recursively.

[{"Path":"C:\Program Files","Pattern":["*.exe"],"Recursive":true}]

• On Windows, collect metadata of specific log patterns.

[{"Path":"C:\ProgramData\Amazon","Pattern":["*amazon*.log"],"Recursive":true}]

• Limit the directory count when performing recursive collection.

[{"Path":"C:\Users","Pattern":["*.ps1"],"Recursive":true, "DirScanLimit": 1000}]

Windows Registry: You can collect Windows Registry keys and values. You can choose a key path and
collect all keys and values recursively. You can also collect a specific registry key and its value for a
specific path. Inventory collects the key path, name, type, and the value.

{
"Path": string,
"Recursive": true,
"ValueNames": array[string] // optional
}

• Path: The path to the Registry key.

519
 AWS Systems Manager User Guide
Configuring Resource Data Sync for Inventory

• Recursive: A Boolean value indicating whether Inventory should recursively traverse Registry paths.
• ValueNames: An array of value names for performing inventory of Registry keys. If you use this
parameter, Systems Manager will inventory only the specified value names for the specified path.

Note
Inventory collects a maximum of 250 Registry key values for all specified paths.

Here are some examples of how to specify the parameters when performing an inventory of the
Windows Registry.

• Collect all keys and values recursively for a specific path.

[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon","Recursive": true}]

• Collect all keys and values for a specific path (recursive search disabled).

[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Intel\PSIS\PSIS_DECODER", "Recursive": false}]

• Collect a specific key by using the ValueNames option.

{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\MachineImage","ValueNames":["AMIName"]}

Related AWS Services

Systems Manager Inventory provides a snapshot of your current inventory to help you manage software
policy and improve the security posture of your entire fleet. You can extend your inventory management
and migration capabilities using the following AWS services.

• AWS Config provides a historical record of changes to your inventory, along with the ability to create
rules to generate notifications when a configuration item is changed. For more information, see,
Recording Amazon EC2 managed instance inventory in the AWS Config Developer Guide.
• AWS Application Discovery Service is designed to collect inventory on OS type, application inventory,
processes, connections, and server performance metrics from your on-premises VMs to support a
successful migration to AWS. For more information, see the Application Discovery Service User Guide.

Configuring Resource Data Sync for Inventory

You can use Systems Manager Resource Data Sync to send Inventory data collected from all of your
managed instances to a single Amazon S3 bucket. Resource Data Sync then automatically updates the
centralized data when new Inventory data is collected. With all Inventory data stored in a target Amazon
S3 bucket, you can use services like Amazon Athena and Amazon QuickSight to query and analyze the
aggregated data.

For example, say that you've configured Inventory to collect data about the operating system (OS) and
applications running on a fleet of 150 managed instances. Some of these instances are located in a
hybrid data center, and others are running in Amazon EC2 across multiple AWS Regions. If you have not
configured Resource Data Sync for Inventory, you either need to manually gather the collected inventory
data for each instance, or you have to create scripts to gather this information. You would then need to
port the data into an application so that you can run queries and analyze it.

With Resource Data Sync, you perform a one-time operation that synchronizes all Inventory data from
all of your managed instances. After the sync is successfully created, Systems Manager creates a baseline
of all Inventory data and saves it in the target Amazon S3 bucket. When new inventory data is collected,

520
 AWS Systems Manager User Guide
Configuring Resource Data Sync for Inventory

Systems Manager automatically updates the data in the Amazon S3 bucket. You can then quickly and
cost-effectively port the data to Amazon Athena and Amazon QuickSight.

Diagram 1 shows how Resource Data Sync aggregates inventory data from managed instances in
Amazon EC2 and a hybrid environment to a target Amazon S3 bucket. This diagram also shows how
Resource Data Sync works with multiple AWS accounts and AWS Regions.

Diagram 1: Resource Data Sync with Multiple AWS Accounts and AWS Regions

If you delete a managed instance, Resource Data Sync preserves the Inventory file for the deleted
instance. For running instances, however, Resource Data Sync automatically overwrites old inventory files
when new files are created and written to the Amazon S3 bucket. If you want to track inventory changes
over time, you can use the AWS Config service to track the SSM:MangagedInstanceInventory
resource type. For more information, see Getting Started with AWS Config.

Create a Resource Data Sync for Inventory

Use the following procedure to create a Resource Data Sync for Inventory by using the Amazon S3 and
AWS Systems Manager consoles. You can also use AWS CloudFormation to create or delete a Resource
Data Sync. To use AWS CloudFormation, add the AWS::SSM::ResourceDataSync resource to your AWS
CloudFormation template. For information, see one of the following documentation resources:

• AWS CloudFormation resource for Resource Data Sync in AWS Systems Manager (blog)
• Working with AWS CloudFormation Templates in the AWS CloudFormation User Guide

Note
You can use AWS Key Management Service (AWS KMS) to encrypt Inventory data in the Amazon
S3 bucket. For an example of how to create an encrypted sync by using the AWS CLI and how
to work with the centralized data in Amazon Athena and Amazon QuickSight, see Walkthrough:
Use Resource Data Sync to Aggregate Inventory Data (p. 556).

To create and configure an Amazon S3 Bucket for Resource Data Sync

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

521
 AWS Systems Manager User Guide
Configuring Resource Data Sync for Inventory

2. Create a bucket to store your aggregated Inventory data. For more information, see Create a Bucket
in the Amazon Simple Storage Service Getting Started Guide. Make a note of the bucket name and the
AWS Region where you created it.
3. Choose the Permissions tab, and then choose Bucket Policy.
4. Copy and paste the following bucket policy into the policy editor. Replace bucket-name and
account-id with the name of the Amazon S3 bucket you created and a valid AWS account ID.

To enable multiple AWS accounts to send inventory data to the central Amazon S3 bucket, specify
each account in the policy as shown in the following Resource sample:

"Resource": [
"arn:aws:s3:::MyTestS3Bucket/*/accountid=123456789012/*",
"arn:aws:s3:::MyTestS3Bucket/*/accountid=a1b2c3d4e5f6/*",
"arn:aws:s3:::MyTestS3Bucket/*/accountid=1234abcd56ef/*"
],

Optionally, replace bucket-prefix with the name of an Amazon S3 prefix (subdirectory). If you
didn't create a prefix, remove bucket-prefix/ from the ARN in the following policy.
Note
For information about viewing your AWS account ID, see Your AWS Account ID and Its Alias
in the IAM User Guide.

{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"SSMBucketPermissionsCheck",
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Action":"s3:GetBucketAcl",
"Resource":"arn:aws:s3:::bucket-name"
},
{
"Sid":" SSMBucketDelivery",
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Action":"s3:PutObject",
"Resource":[
"arn:aws:s3:::bucket-name/bucket-prefix/*/accountid=account-id-1/*",
"arn:aws:s3:::bucket-name/bucket-prefix/*/accountid=account-id-2/*",
"arn:aws:s3:::bucket-name/bucket-prefix/*/accountid=account-id-3/*"
],
"Condition":{
"StringEquals":{
"s3:x-amz-acl":"bucket-owner-full-control"
}
}
}
]
}

To create a Resource Data Sync

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

522
 AWS Systems Manager User Guide
Configuring Inventory Collection

2. In the navigation pane, choose Managed Instances.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Managed Instances.
3. Choose Resource Data Syncs, and then choose Create resource data sync.
4. In the Sync name field, type a name for the sync configuration.
5. In the Bucket name field, type the name of the Amazon S3 bucket you created at the start of this
procedure.
6. (Optional) In the Bucket prefix field, type the name of an Amazon S3 bucket prefix (subdirectory).
7. In the Bucket region field, choose This region if the Amazon S3 bucket you created is located in the
current AWS Region. If the bucket is located in a different AWS Region, choose Another region, and
type the name of the Region.
Note
If the sync and the target Amazon S3 bucket are located in different regions, you may be
subject to data transfer pricing. For more information, see Amazon S3 Pricing.
8. In the KMS Key ARN field, type or paste a KMS Key ARN to encrypt inventory data in Amazon S3.
9. Choose Create.

To synchronize inventory data from multiple AWS Regions, you must create a Resource Data Sync in
each Region. Repeat this procedure in each AWS Region where you want to collect inventory data and
send it to the central Amazon S3 bucket. When you create the sync in each Region, specify the central
Amazon S3 bucket in the Bucket name field. Then use the Bucket region option to choose the Region
where you created the central Amazon S3 bucket, as shown in the following screen shot. The next time
the association runs to collect inventory data, Systems Manager stores the data in the central Amazon S3
bucket.

Configuring Inventory Collection

This section describes how to configure inventory collection on one or more managed instances by using
the Systems Manager console. For an example of how to configure inventory collection by using the AWS
CLI, see Systems Manager Inventory Walkthroughs (p. 552).

523
 AWS Systems Manager User Guide
Configuring Inventory Collection

When you configure inventory collection, you start by creating a Systems Manager State Manager
association. Systems Manager collects the inventory data when the association is run. If you don't create
the association first, and attempt to invoke the aws:softwareInventory plugin by using, for example, Run
Command, the system returns the following error:

The aws:softwareInventory plugin can only be invoked via ssm-associate.

Also note that an instance can have only have one Inventory association configured at a time. If you
configure an instance with two or more associations, the Inventory association doesn't run and no
inventory data is collected.

Before You Begin

Before you configure inventory collection, complete the following tasks.

• Update SSM Agent on the instances you want to inventory. By running the latest version of SSM
Agent, you ensure that you can collect metadata for all supported inventory types. For information
about how to update SSM Agent by using State Manager, see Automatically Update SSM Agent
(CLI) (p. 681).
• Verify that your instances meet Systems Manager prerequisites. For more information, see Systems
Manager Prerequisites (p. 12).
• (Optional) Create a Resource Data Sync to centrally store Inventory data in an Amazon S3 bucket.
Resource Data Sync then automatically updates the centralized data when new Inventory data is
collected. For more information, see Configuring Resource Data Sync for Inventory (p. 520).
• (Optional) Create a JSON file to collect custom inventory. For more information, see Working with
Custom Inventory (p. 541).

Inventory All Managed Instances in Your AWS Account

You can easily inventory all managed instances in your AWS account by creating a global inventory
association. A global inventory association performs the following actions:

• Automatically applies the global inventory configuration (association) to all existing managed
instances in your AWS account. Instances that already have an inventory association are skipped when
the global inventory association is applied and runs. When an instance is skipped, the detailed status
message states Overridden By Explicit Inventory Association. Those instances are skipped
by the global association, but they will still report inventory when they run their assigned inventory
association.
• Automatically adds new instances created in your AWS account to the global inventory association.

Note

• If an instance is configured for the global inventory association, and you assign a specific
association to that instance, then Systems Manager Inventory deprioritizes the global
association and applies the specific association.
• Global inventory associations are available in SSM Agent version 2.0.790.0 or later. For
information about how to update SSM Agent on your instances, see Update SSM Agent by
using Run Command (p. 620).

Configuring Inventory Collection with One Click (Console)

Use the following procedure to configure all managed instances in your AWS account and in a single AWS
Region for Inventory with one click from the Systems Manager console.

524
 AWS Systems Manager User Guide
Configuring Inventory Collection

To configure all of your managed instances in the current Region for Systems Manager
Inventory

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Inventory.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Inventory in the navigation pane.
3. In the Managed instances with inventory enabled card, choose Click here to enable inventory on
all instances.

If successful, the console displays the following message.

Depending on the number of managed instances in your account, it can take several minutes for the
global inventory association to be applied. Wait a few minutes and then refresh the page. Verify that
the graphic changes to reflect that inventory is configured on all of your managed instances.

Configuring Collection by Using the Console

This section includes information about how to configure Systems Manager Inventory to collect
metadata from your managed instances by using the Systems Manager console. You can quickly collect
metadata from all instances in a specific AWS account (and any future instances that might be created in
that account) or you can selectively collect Inventory data by using tags or instance IDs.

To configure inventory collection

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Inventory.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Inventory in the navigation pane.
3. Choose Setup Inventory.
4. In the Targets section, identify the instances where you want to run this operation by choosing one
of the following.

• Selecting all managed instances in this account - This option selects all managed instances for
which there is no existing inventory association. If you choose this option, instances that already

525
 AWS Systems Manager User Guide
Configuring Inventory Collection

had inventory associations are skipped during inventory collection, and shown with a status of
Skipped in inventory results. For more information, see Inventory All Managed Instances in Your
AWS Account (p. 524).
• Specifying a tag - This option lets you specify a single tag to identify instances in your account
from which you want to collect inventory. If you use a tag, any instances created in the future
with the same tag will also report inventory. If there is an existing inventory association with all
instances, using a tag to select specific instances as a target for a different inventory overrides
instance membership in the All managed instances target group. Instances with the specified tag
are skipped on future inventory collection from All managed instances.
• Manually selecting instances - This option lets you choose specific managed instances in your
account. Explicitly choosing specific instances by using this option overrides inventory associations
on the All managed instances target. The instance is skipped on future inventory collection from
All managed instances.
5. In the Schedule section, choose how often you want the system to collect inventory metadata from
your instances.
6. In the Parameters section, use the lists to enable or disable different types of inventory collection.
See the following samples if you want to create an inventory search for Files or the Windows
Registry.

Files

• On Linux, collect metadata of .sh files in the /home/ec2-user directory, excluding all
subdirectories.

[{"Path":"/home/ec2-user","Pattern":["*.sh", "*.sh"],"Recursive":false}]

• On Windows, collect metadata of all ".exe" files in the Program Files folder, including
subdirectories recursively.

[{"Path":"C:\Program Files","Pattern":["*.exe"],"Recursive":true}]

• On Windows, collect metadata of specific log patterns.

[{"Path":"C:\ProgramData\Amazon","Pattern":["*amazon*.log"],"Recursive":true}]

• Limit the directory count when performing recursive collection.

[{"Path":"C:\Users","Pattern":["*.ps1"],"Recursive":true, "DirScanLimit": 1000}]

Windows Registry

• Collect all keys and values recursively for a specific path.

[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon","Recursive": true}]

• Collect all keys and values for a specific path (recursive search disabled).

[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Intel\PSIS\PSIS_DECODER", "Recursive": false}]

• Collect a specific key by using the ValueNames option.

{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\MachineImage","ValueNames":["AMIName"]}

526
 AWS Systems Manager User Guide
Working with Inventory Data

For more information about collecting File and Windows Registry inventory, see Working with File
and Windows Registry Inventory (p. 518).
7. In the Advanced section, choose Sync inventory execution logs to an S3 bucket if you want to store
the association execution status in an Amazon S3 bucket.
8. Choose Setup Inventory. Systems Manager creates a State Manager association and immediately
runs Inventory on the instances.
9. In the navigation pane, choose State Manager. Verify that a new association was created that uses
the AWS-GatherSoftwareInventory document. Also, verify that the Status field shows Success. If
you chose the option to Sync inventory execution logs to an S3 bucket, then you can view the log
data in Amazon S3 after a few minutes. If you want to view inventory data for a specific instance,
then choose Managed Instances in the navigation pane.
10. Choose an instance, and then choose View details.
11. On the instance details page, choose Inventory. Use the Inventory type lists to filter the inventory.

Working with Systems Manager Inventory Data

This section includes topics that describe how to query and aggregate Inventory data.

Topics
• Querying Inventory Data from Multiple Regions and Accounts (p. 527)
• Querying an Inventory Collection by Using Filters (p. 532)
• Aggregating Inventory Data (p. 532)

Querying Inventory Data from Multiple Regions and Accounts

AWS Systems Manager Inventory integrates with Amazon Athena to help you query inventory data
from multiple AWS Regions and accounts. Athena integration uses Resource Data Sync so that you can
view inventory data from all of your managed instances on the Inventory Detail View page in the AWS
Systems Manager console.
Important
This feature uses AWS Glue to crawl the data in your Amazon Simple Storage Service (Amazon
S3) bucket, and Amazon Athena to query the data. Depending on how much data is crawled
and queried, you can be charged for using these services. With AWS Glue, you pay an hourly
rate, billed by the second, for crawlers (discovering data) and ETL jobs (processing and loading
data). With Athena, you are charged based on the amount of data scanned by each query. We
encourage you to view the pricing guidelines for these services before you use Amazon Athena
integration with Systems Manager Inventory. For more information, see Amazon Athena pricing
and AWS Glue pricing.

You can view inventory data on the Inventory Detail View page in all AWS Regions where Amazon
Athena is available.

Before you begin

Athena integration uses Resource Data Sync. You must set up and configure Resource Data Sync to use
this feature. For more information, see Configuring Resource Data Sync for Inventory (p. 520).

Also, be aware that the Inventory Detail View page displays inventory data for the owner of the central
Amazon S3 bucket used by Resource Data Sync. If you are not the owner of the central Amazon S3
bucket, then you won't see inventory data on the Inventory Detail View page.

527
 AWS Systems Manager User Guide
Working with Inventory Data

Configuring Access
Before you can query and view data from multiple accounts and Regions on the Inventory Detail View
page in the Systems Manager console, you must configure your AWS Identity and Access Management
(IAM) user account. The following procedure describes how to use the IAM console to configure your IAM
user account so that you can view inventory data on the Inventory Detail View page.

To configure access to the Inventory Detail View page

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Users, and then choose the user account you want to configure. The
Summary page opens.
3. On the Permissions tab, choose Add permissions.
4. On the Grant permissions page, choose Attach existing policies directly.
5. In the Search field, search for AWSQuicksightAthenaAccess.
6. Choose the option next to this policy, and then choose Next: Review.
7. Choose Add permissions.
8. Choose the user name again to return to the Summary page.
9. Now add an inline policy so that AWS Glue can crawl your inventory data. On the Permissions tab, at
the right side of the page, choose Add inline policy. The Create policy page opens.
10. Choose the JSON tab.
11. Delete the existing JSON text in the editor, and then copy and paste the following policy into the
JSON editor.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"glue:GetCrawlers",
"glue:GetCrawler",
"glue:GetTables",
"glue:StartCrawler",
"glue:CreateCrawler"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"iam:PassRole",
"iam:CreateRole",
"iam:AttachRolePolicy"
],
"Resource": [
"arn:aws:iam::account_ID:role/*"
]
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"iam:CreatePolicy"
],
"Resource": [

528
 AWS Systems Manager User Guide
Working with Inventory Data

"arn:aws:iam::account_ID:policy/*"
]
}
]
}

12. On the Review Policy page, enter a name in the Name field.
13. Choose Create policy.

Important
When you choose a Resource Data Sync on the Inventory Detail View page, Systems Manager
automatically creates the Amazon-GlueServicePolicyForSSM role. This role enables AWS
Glue to access the Amazon S3 bucket for Resource Data Sync. Systems Manager automatically
attaches the following policies to the role:

• Amazon-GlueServicePolicyForSSM-{Amazon S3 bucket name}: This policy enables

communication between AWS Glue and Systems Manager Inventory.
• AWSGlueServiceRole: This is an AWS managed policy that enables access to AWS Glue.

If a policy with the name Amazon-GlueServicePolicyForSSM-{Amazon S3 bucket name}

already exists in your IAM user account, and this policy is not attached to the Amazon-
GlueServiceRoleForSSM role, then the system returns an error. To resolve this issue, use the
IAM console to verify that the contents of the Amazon-GlueServicePolicyForSSM-{Amazon
S3 bucket name} policy match the inline policy in this procedure. Then attach the policy to the
Amazon-GlueServiceRoleForSSM role.

Querying Data on the Detailed Inventory View Page

Use the following procedure to view inventory data from multiple AWS Regions and accounts on the
Detailed Inventory View page.
Important
The Inventory Detailed View page is only available in AWS Regions that offer Amazon Athena.
If the following tabs are not displayed on the Inventory page, it means Athena is not available in
the Region and you can't use the Detailed View to query data.

To view inventory data from multiple Regions and accounts in the AWS Systems Manager
console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Inventory.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Inventory in the navigation pane.
3. Choose the Detailed View tab.

529
 AWS Systems Manager User Guide
Working with Inventory Data

4. Choose the Resource Data Sync for which you want to query data.

5. In the Inventory Type list, choose the type of inventory data that you want to query, and then press
Enter.

6. To filter the data, choose the Filter bar, and then choose a filter option.

The following example shows AWSComponent inventory data filtered on the us-east-2 Region.

530
 AWS Systems Manager User Guide
Working with Inventory Data

You can use the Export to CSV button to view the current query set in a spreadsheet application such as
Microsoft Excel. You can also use the Query History and Run Advanced Queries buttons to view history
details and interact with your data in Amazon Athena.

Editing the AWS Glue Crawler Schedule

AWS Glue crawls the Systems Manager Inventory data in the central Amazon S3 bucket twice daily, by
default. If you frequently change the types of data to collect on your instances then you might want to
crawl the data more frequently, as described in the following procedure.
Important
AWS Glue charges your account based on an hourly rate, billed by the second, for crawlers
(discovering data) and ETL jobs (processing and loading data). Before you change the crawler
schedule, view the AWS Glue pricing page.

To change the inventory data crawler schedule

1. Open the AWS Glue console at https://console.aws.amazon.com/glue/.

2. In the navigation pane, choose Crawlers.
3. In the crawlers list, choose the option next to the Systems Manager Inventory data crawler. The
crawler name uses the following format:

AWSSystemsManager-Resource_Data_Sync_bucket_name-Region-AWS_account_ID
4. Choose Action, and then choose Edit crawler.
5. In the navigation pane, choose Schedule.
6. In the Cron expression field, specify a new schedule by using a cron format. For more information
about the cron format, see Time-Based Schedules for Jobs and Crawlers in the AWS Glue Developer
Guide.

531
 AWS Systems Manager User Guide
Working with Inventory Data

Important
You can pause the crawler to stop incurring charges from AWS Glue. If you pause the crawler, or
if you change the frequency so that the data is crawled less often, then the Detailed Inventory
View might display data that is not current.

Querying an Inventory Collection by Using Filters

After you collect inventory data, you can use the filter capabilities in Systems Manager to query a list of
managed instances that meet certain filter criteria.

To query instances based on inventory filters

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Inventory.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Inventory in the navigation pane.
3. In the Filter by resource groups, tags or inventory types section, choose the filter box. A list of
predefined filters appears.
4. Choose an attribute to filter on. For example, choose AWS:Application. If prompted, choose a
secondary attribute to filter. For example, choose AWS:Application.Name.
5. Choose a delimiter from the list. For example, choose Begin with. A text box appears in the filter.
6. Type a value in the text box. For example, type Amazon (SSM Agent is named Amazon SSM Agent).
7. Press Enter. The system returns a list of managed instances that include an application name that
begins with the word Amazon.

Note
You can combine multiple filters to refine your search.

Aggregating Inventory Data

After you configure your managed instances for AWS Systems Manager Inventory, you can view
aggregated counts of Inventory data. For example, say you configured dozens or hundreds of managed
instances to collect the AWS:Application Inventory type. By using the information in this section, you can
see an exact count of how many instances are configured to collect this data.

You can also see specific Inventory details by aggregating on a data type. For example, the
AWS:InstanceInformation Inventory type collects operating system platform information with the
Platform data type. By aggregating data on the Platform data type, you can quickly see how many
instances are running Windows and how many are running Linux.

The procedures in this section describe how to view aggregated counts of Inventory data by using the
AWS CLI. You can also view pre-configured aggregated counts in the AWS Systems Manager console on
the Inventory page. These pre-configured dashboards are called Inventory Insights and they offer one-
click remediation of your Inventory configuration issues.

Note the following important details about aggregation counts of Inventory data:

• Systems Manager Inventory stores Inventory data for 30 days. This means that aggregated counts of
Inventory include all data collected during the last 30 days.
• Inventory shows data that has been sent by an instance over the course of its lifetime. If an instance
was previously configured to report a specific Inventory data type, for example AWS:Network,
and later you change the configuration to stop collecting that type, aggregation counts still show
AWS:Network data until the instance has been terminated.

532
 AWS Systems Manager User Guide
Working with Inventory Data

• If an instance was previously configured to collect Inventory data, and you terminate that instance,
Inventory counts still show data for the deleted instance for 30 days.

For information about how to quickly configure and collect Inventory data from all instances in a specific
AWS account (and any future instances that might be created in that account) see Configuring Collection
by Using the Console (p. 525).

Topics
• Aggregating Inventory Data to See Counts of Instances that Collect Specific Types of Data (p. 533)
• Aggregating Inventory Data with Groups to See Which Instances Are and Aren't Configured to Collect
an Inventory Type (p. 537)

Aggregating Inventory Data to See Counts of Instances that Collect Specific

Types of Data
You can use the GetInventory API action to view aggregated counts of instances that collect one or
more Inventory types and data types. For example, the AWS:InstanceInformation Inventory type
enables you to view an aggregate of operating systems by using the GetInventory API action with the
AWS:InstanceInformation.PlatformType data type. Here is an example AWS CLI command and output:

aws ssm get-inventory --aggregators "Expression=AWS:InstanceInformation.PlatformType"

The system returns information like the following.

{
"Entities":[
{
"Data":{
"AWS:InstanceInformation":{
"Content":[
{
"Count":"7",
"PlatformType":"windows"
},
{
"Count":"5",
"PlatformType":"linux"
}
]
}
}
}
]
}

Getting started

Determine the Inventory types and data types for which you want to view counts. You can view a list of
Inventory types and data types that support aggregation by running the following command in the AWS
CLI:

aws ssm get-inventory-schema --aggregator

The command returns a JSON list of Inventory types and data types that support aggregation. The
TypeName field shows supported Inventory types. And the Name field shows each data type. For

533
 AWS Systems Manager User Guide
Working with Inventory Data

example, in the following list, the AWS:Application Inventory type includes data types for Name and
Version.

{
"Schemas": [
{
"TypeName": "AWS:Application",
"Version": "1.1",
"DisplayName": "Application",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "Version"
}
]
},
{
"TypeName": "AWS:InstanceInformation",
"Version": "1.0",
"DisplayName": "Platform",
"Attributes": [
{
"DataType": "STRING",
"Name": "PlatformName"
},
{
"DataType": "STRING",
"Name": "PlatformType"
},
{
"DataType": "STRING",
"Name": "PlatformVersion"
}
]
},
{
"TypeName": "AWS:ResourceGroup",
"Version": "1.0",
"DisplayName": "ResourceGroup",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
}
]
},
{
"TypeName": "AWS:Service",
"Version": "1.0",
"DisplayName": "Service",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "DisplayName"
},
{
"DataType": "STRING",

534
 AWS Systems Manager User Guide
Working with Inventory Data

"Name": "ServiceType"
},
{
"DataType": "STRING",
"Name": "Status"
},
{
"DataType": "STRING",
"Name": "StartType"
}
]
},
{
"TypeName": "AWS:WindowsRole",
"Version": "1.0",
"DisplayName": "WindowsRole",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "DisplayName"
},
{
"DataType": "STRING",
"Name": "FeatureType"
},
{
"DataType": "STRING",
"Name": "Installed"
}
]
}
]
}

You can aggregate data for any of the listed Inventory types by creating a commmand that uses the
following syntax:

aws ssm get-inventory --aggregators "Expression=InventoryType.DataType"

Here are some examples.

Example 1

This example aggregates a count of the Windows roles used by your instances.

aws ssm get-inventory --aggregators "Expression=AWS:WindowsRole.Name"

Example 2

This example aggregates a count of the applications installed on your instances.

aws ssm get-inventory --aggregators "Expression=AWS:Application.Name"

Combining Multiple Aggregators

You can also combine multiple Inventory types and data types in one command to help you better
understand the data. Here are some examples.

535
 AWS Systems Manager User Guide
Working with Inventory Data

Example 1

This example aggregates a count of the operating system types used by your instances. It also returns
the specific name of the operating systems.

aws ssm get-inventory --aggregators '[{"Expression":

"AWS:InstanceInformation.PlatformType", "Aggregators":[{"Expression":
"AWS:InstanceInformation.PlatformName"}]}]'

Example 2

This example aggregates a count of the applications running on your instances and the specific version
of each application.

aws ssm get-inventory --aggregators '[{"Expression": "AWS:Application.Name", "Aggregators":

[{"Expression": "AWS:Application.Version"}]}]'

If you prefer, you can create an aggregation expression with one or more Inventory types and data types
in a JSON file and call the file from the AWS CLI. The JSON in the file must use the following syntax:

[
{
"Expression": "string",
"Aggregators": [
{
"Expression": "string"
}
]
}
]

You must save the file with the .json file extension.

Here is an example that uses multiple Inventory types and data types.

[
{
"Expression": "AWS:Application.Name",
"Aggregators": [
{
"Expression": "AWS:Application.Version",
"Aggregators": [
{
"Expression": "AWS:InstanceInformation.PlatformType"
}
]
}
]
}
]

Use the following command to call the file from the AWS CLI.

aws ssm get-inventory --aggregators file://file_name.json

The command returns information like the following:

{"Entities":
[

536
 AWS Systems Manager User Guide
Working with Inventory Data

{"Data":
{"AWS:Application":
{"Content":
[
{"Count": "3",
"PlatformType": "linux",
"Version": "2.6.5",
"Name": "audit-libs"},
{"Count": "2",
"PlatformType": "windows",
"Version": "2.6.5",
"Name": "audit-libs"},
{"Count": "4",
"PlatformType": "windows",
"Version": "6.2.8",
"Name": "microsoft office"},
{"Count": "2",
"PlatformType": "windows",
"Version": "2.6.5",
"Name": "chrome"},
{"Count": "1",
"PlatformType": "linux",
"Version": "2.6.5",
"Name": "chrome"},
{"Count": "2",
"PlatformType": "linux",
"Version": "6.3",
"Name": "authconfig"}
]
}
},
"ResourceType": "ManagedInstance"}
]
}

Aggregating Inventory Data with Groups to See Which Instances Are and Aren't
Configured to Collect an Inventory Type
Groups enable you to quickly see a count of which managed instances are and aren’t configured to
collect one or more Inventory types. With groups, you specify one or more Inventory types and a filter
that uses the exists operator.

For example, say that you have four managed instances configured to collect the following Inventory
types:

• Instance 1: AWS:Application
• Instance 2: AWS:File
• Instance 3: AWS:Application, AWS:File
• Instance 4: AWS:Network

You can run the following command from the AWS CLI to see how many instances are configured to
collect both the AWS:Application and AWS:File Inventory types. The response also returns a count of how
many instance aren't configured to collect both of these Inventory types.

aws ssm get-inventory --aggregators

'Groups=[{Name=ApplicationAndFile,Filters=[{Key=TypeName,Values=[AWS:Application],Type=Exists},
{Key=TypeName,Values=[AWS:File],Type=Exists}]}]'

The command response shows that only one managed instance is configured to collect both the
AWS:Application and AWS:File Inventory types.

537
 AWS Systems Manager User Guide
Working with Inventory Data

{
"Entities":[
{
"Data":{
"ApplicationAndFile":{
"Content":[
{
"notMatchingCount":"3"
},
{
"matchingCount":"1"
}
]
}
}
}
]
}

Note
Groups don't return data type counts. Also, you can't drill-down into the results to see the
instances IDs that are or aren't configured to collect the Inventory type.

If you prefer, you can create an aggregation expression with one or more Inventory types in a JSON file
and call the file from the AWS CLI. The JSON in the file must use the following syntax:

{
"Aggregators":[
{
"Groups":[
{
"Name":"Name",
"Filters":[
{
"Key":"TypeName",
"Values":[
"Inventory_type"
],
"Type":"Exists"
},
{
"Key":"TypeName",
"Values":[
"Inventory_type"
],
"Type":"Exists"
}
]
}
]
}
]
}

You must save the file with the .json file extension.

Use the following command to call the file from the AWS CLI.

aws ssm get-inventory --cli-input-json file://file_name.json

Additional examples

538
 AWS Systems Manager User Guide
Working with Inventory Data

The following examples show you how to aggregate Inventory data to see which managed instances are
and aren't configured to collect the specified Inventory types. These examples use the AWS CLI. Each
example includes a full command with filters that you can run from the command line and a sample
input.json file if you prefer to enter the information in a file.

Example 1

This example aggregates a count of instances that are and aren't configured to collect either the
AWS:Application or the AWS:File Inventory types.

Run the following command from the AWS CLI.

aws ssm get-inventory --aggregators

'Groups=[{Name=ApplicationORFile,Filters=[{Key=TypeName,Values=[AWS:Application,
AWS:File],Type=Exists}]}]'

If you prefer to use a file, copy and paste the following sample into a file and save it as input.json.

{
"Aggregators":[
{
"Groups":[
{
"Name":"ApplicationORFile",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Application",
"AWS:File"
],
"Type":"Exists"
}
]
}
]
}
]
}

Run the following command from the AWS CLI.

aws ssm get-inventory --cli-input-json file://input.json

The command returns information like the following:

{
"Entities":[
{
"Data":{
"ApplicationORFile":{
"Content":[
{
"notMatchingCount":"1"
},
{
"matchingCount":"3"
}
]

539
 AWS Systems Manager User Guide
Working with Inventory Data

}
}
}
]
}

Example 2

This example aggregates a count of instances that are and aren't configured to collect the
AWS:Application, AWS:File, and AWS:Network inventory types.

Run the following command from the AWS CLI.

aws ssm get-inventory --aggregators

'Groups=[{Name=Application,Filters=[{Key=TypeName,Values=[AWS:Application],Type=Exists}]},
{Name=File,Filters=[{Key=TypeName,Values=[AWS:File],Type=Exists}]},
{Name=Network,Filters=[{Key=TypeName,Values=[AWS:Network],Type=Exists}]}]'

If you prefer to use a file, copy and paste the following sample into a file and save it as input.json.

{
"Aggregators":[
{
"Groups":[
{
"Name":"Application",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Application"
],
"Type":"Exists"
}
]
},
{
"Name":"File",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:File"
],
"Type":"Exists"
}
]
},
{
"Name":"Network",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Network"
],
"Type":"Exists"
}
]
}
]
}

540
 AWS Systems Manager User Guide
Working with Custom Inventory

]
}

Run the following command from the AWS CLI.

aws ssm get-inventory --cli-input-json file://input.json

The command returns information like the following:

{
"Entities":[
{
"Data":{
"Application":{
"Content":[
{
"notMatchingCount":"2"
},
{
"matchingCount":"2"
}
]
},
"File":{
"Content":[
{
"notMatchingCount":"2"
},
{
"matchingCount":"2"
}
]
},
"Network":{
"Content":[
{
"notMatchingCount":"3"
},
{
"matchingCount":"1"
}
]
}
}
}
]
}

Working with Custom Inventory

You can assign any metadata you want to your instances by creating custom inventory. For example,
let's say you manage a large number of servers in racks in your data center, and these servers have been
configured as Systems Manager managed instances. Currently, you store information about server rack
location in a spreadsheet. With custom inventory, you can specify the rack location of each instance
as metadata on the instance. When you collect inventory by using Systems Manager, the metadata is
collected with other inventory metadata. You can then port all inventory metadata to a central Amazon
S3 bucket by using Resource Data Sync and query the data.
Note
Systems Manager supports a maximum of 20 custom inventory types per AWS account.

541
 AWS Systems Manager User Guide
Working with Custom Inventory

To assign custom inventory to an instance, you can either use the Systems Manager PutInventory API
action, as described in Walkthrough: Assign Custom Inventory Metadata to an Instance (p. 553). Or,
you can create a custom inventory JSON file and upload it to the instance. This section describes how to
create the JSON file.

The following example JSON file with custom inventory specifies rack information about an
on-premises server. This examples specifies one type of custom inventory data ("TypeName":
"Custom:RackInformation"), with multiple entries under Content that describe the data.

{
"SchemaVersion": "1.0",
"TypeName": "Custom:RackInformation",
"Content": {
"Location": "US-EAST-02.CMH.RACK1",
"InstalledTime": "2016-01-01T01:01:01Z",
"vendor": "DELL",
"Zone" : "BJS12",
"TimeZone": "UTC-8"
}
}

You can also specify distinct entries in the Content section, as shown in the following example.

{
"SchemaVersion": "1.0",
"TypeName": "Custom:PuppetModuleInfo",
"Content": [{
"Name": "puppetlabs/aws",
"Version": "1.0"
},
{
"Name": "puppetlabs/dsc",
"Version": "2.0"
}
]
}

The JSON schema for custom inventory requires SchemaVersion, TypeName, and Content sections, but
you can define the information in those sections.

{
"SchemaVersion": "user_defined",
"TypeName": "Custom:user_defined",
"Content": {
"user_defined_attribute1": "user_defined_value1",
"user_defined_attribute2": "user_defined_value2",
"user_defined_attribute3": "user_defined_value3",
"user_defined_attribute4": "user_defined_value4"
}
}

TypeName is limited to 100 characters. Also, the TypeName section must start with Custom. For
example, Custom:PuppetModuleInfo. Both Custom and the Data you specify must begin with
a capital letter. The following examples would cause an exception: "CUSTOM:RackInformation",
"custom:rackinformation".

The Content section includes attributes and data. These items are not case-sensitive. However, if you
define an attribute (for example: "Vendor": "DELL"), then you must consistently reference this attribute in
your custom inventory files. If you specify "Vendor": "DELL" (using a capital “V” in vendor) in one file, and

542
 AWS Systems Manager User Guide
Working with Custom Inventory

then you specify "vendor": "DELL" (using a lowercase “v” in vendor) in another file, the system returns an
error.
Note
You must save the file with a .json extension.

After you create the file, you must save it on the instance. The following table shows the location where
custom inventory JSON files must be stored on the instance:

Operating System Path

Windows %SystemDrive%\ProgramData\Amazon\SSM
\InstanceData\<instance-id>\inventory\custom

Linux /var/lib/amazon/ssm/<instance-id>/inventory/
custom

For an example of how to use custom inventory, see Get Disk Utilization of Your Fleet Using EC2 Systems
Manager Custom Inventory Types.

Deleting Custom Inventory

You can use the DeleteInventory API action to delete a custom inventory type and the data associated
with that type. You call the delete-inventory command by using the AWS CLI to delete all data for an
inventory type. You call the delete-inventory command with the SchemaDeleteOption to delete a
custom inventory type.
Note
An inventory type is also called an inventory schema.

The SchemaDeleteOption parameter includes the following options:

• DeleteSchema: This option deletes the specified custom type and all data associated with it. You can
recreate the schema later, if you want.
• DisableSchema: If you choose this option, the system disables the current version, deletes all data for
it, and ignores all new data if the version is less than or equal to the disabled version. You can enable
this inventory type again by calling the PutInventory action for a version greater than the disabled
version.

To delete or disable custom inventory by using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to use the dry-run option to see which data will be deleted from the
system. This command doesn't delete any data.

aws ssm delete-inventory --type-name "Custom:custom_type_name" --dry-run

The system returns information like the following.

{
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,

543
 AWS Systems Manager User Guide
Working with Custom Inventory

"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}

For information about how to understand the delete inventory summary, see Understanding the
Delete Inventory Summary (p. 547).
3. Run the following command to delete all data for a custom inventory type.

aws ssm delete-inventory --type-name "Custom:custom_type_name"

Note
The output of this command doesn't show the deletion progress. For this reason,
TotalCount and Remaining Count are always the same because the system has not deleted
anything yet. You can use the describe-inventory-deletions command to show the deletion
progress, as described later in this topic.

The system returns information like the following.

{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"custom_type_name"
}

The system deletes all data for the specified custom inventory type from the Systems Manager
Inventory service.
4. Run the following command. The command performs the following actions for the current version
of the inventory type: disables the current version, deletes all data for it, and ignores all new data if
the version is less than or equal to the disabled version.

aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option

"DisableSchema"

The system returns information like the following.

544
 AWS Systems Manager User Guide
Working with Custom Inventory

{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}

You can view a disabled inventory type by using the following command.

aws ssm get-inventory-schema --type-name Custom:custom_type_name

5. Run the following command to delete an inventory type.

aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option

"DeleteSchema"

The system deletes the schema and all inventory data for the specified custom type.

The system returns information like the following.

{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}

545
 AWS Systems Manager User Guide
Working with Custom Inventory

Viewing the Deletion Status

You can check the status of a delete operation by using the describe-inventory-deletions AWS CLI
command. You can specify a deletion ID to view the status of a specific delete operation. Or, you can
omit the deletion ID to view a list of all deletions run in the last 30 days.

1. Run the following command to view the status of a deletion operation. The system returned the
deletion ID in the delete-inventory summary.

aws ssm describe-inventory-deletions --deletion-id system_generated_deletion_ID

The system returns the latest status. The delete operation might not be finished yet. The system
returns information like the following.

{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 1,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 1,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "InProgress",
"LastStatusMessage": "The Delete is in progress",
"LastStatusUpdateTime": 1521744844,
"TypeName": "Custom:custom_type_name"}
]
}

If the delete operation is successful, the LastStatusMessage states: Deletion is successful.

{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521745253,
"TypeName": "Custom:custom_type_name"}
]
}

2. Run the following command to view a list of all deletions run in the last 30 days.

aws ssm describe-inventory-deletions --max-results a number

546
 AWS Systems Manager User Guide
Working with Custom Inventory

{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521682552,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521682852,
"TypeName": "Custom:custom_type_name"},
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521745253,
"TypeName": "Custom:custom_type_name"},
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521680145,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521680471,
"TypeName": "Custom:custom_type_name"}
],
"NextToken": "next-token"

Understanding the Delete Inventory Summary

To help you understand the contents of the delete inventory summary, consider the following
example. A user assigned Custom:RackSpace inventory to three instances. Inventory items 1 and 2
use custom type version 1.0 ("SchemaVersion":"1.0"). Inventory item 3 uses custom type version 2.0
("SchemaVersion":"2.0").

RackSpace custom inventory 1

547
 AWS Systems Manager User Guide
Working with Custom Inventory

"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567890",
"SchemaVersion":"1.0" "Content":[
{
content of custom type omitted
}
]
}

RackSpace custom inventory 2

{
"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567891",
"SchemaVersion":"1.0" "Content":[
{
content of custom type omitted
}
]
}

RackSpace custom inventory 3

{
"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567892",
"SchemaVersion":"2.0" "Content":[
{
content of custom type omitted
}
]
}

The user runs the following command to preview which data will be deleted.

aws ssm delete-inventory --type-name "Custom:RackSpace" --dry-run

The system returns information like the following.

{
"DeletionId":"1111-2222-333-444-66666",
"DeletionSummary":{
"RemainingCount":3,
"TotalCount":3,
TotalCount and RemainingCount are the number of items that would be deleted
if this was not a dry run. These numbers are the same because the system didn't delete
anything.
"SummaryItems":[
{
"Count":2, The system found two items that use SchemaVersion 1.0.
Neither item was deleted.
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1, The system found one item that uses SchemaVersion 1.0.
This item was not deleted.
"RemainingCount":1,

548
 AWS Systems Manager User Guide
Working with Custom Inventory

"Version":"2.0"
}
],

},
"TypeName":"Custom:RackSpace"
}

The user runs the following command to delete the Custom:RackSpace inventory.
Note
The output of this command doesn't show the deletion progress. For this reason, TotalCount
and Remaining Count are always the same because the system has not deleted anything yet.
You can use the describe-inventory-deletions command to show the deletion progress.

aws ssm delete-inventory --type-name "Custom:RackSpace"

The system returns information like the following.

{
"DeletionId":"1111-2222-333-444-7777777",
"DeletionSummary":{
"RemainingCount":3, There are three items to delete
"SummaryItems":[
{
"Count":2, The system found two items that use SchemaVersion 1.0.
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1, The system found one item that uses SchemaVersion 2.0.
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"RackSpace"
}

Viewing Inventory Delete Actions in CloudWatch Events

You can configure Amazon CloudWatch Events to create an event anytime a user deletes custom
inventory. CloudWatch Events offers three types of events for custom inventory delete operations:

• Delete action for an instance: If the custom inventory for a specific managed instance was
successfully deleted or not.
• Delete action summary: A summary of the delete action.
• Warning for disabled custom inventory type: A warning event if a user called the PutInventory API
action for a custom inventory type version that was previously-disabled.

Here are examples of each event:

Delete action for an instance

{
"version":"0",
"id":"998c9cde-56c0-b38b-707f-0411b3ff9d11",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",

549
 AWS Systems Manager User Guide
Working with Custom Inventory

"account":"478678815555",
"time":"2018-05-24T22:24:34Z",
"region":"us-east-1",
"resources":[
"arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0a5feb270fc3f0b97"
],
"detail":{
"action-status":"succeeded",
"action":"delete",
"resource-type":"managed-instance",
"resource-id":"i-0a5feb270fc3f0b97",
"action-reason":"",
"type-name":"Custom:MyInfo"
}
}

Delete action summary

{
"version":"0",
"id":"83898300-f576-5181-7a67-fb3e45e4fad4",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",
"account":"478678815555",
"time":"2018-05-24T22:28:25Z",
"region":"us-east-1",
"resources":[

],
"detail":{
"action-status":"succeeded",
"action":"delete-summary",
"resource-type":"managed-instance",
"resource-id":"",
"action-reason":"The delete for type name Custom:MyInfo was completed. The deletion
summary is: {\"totalCount\":2,\"remainingCount\":0,\"summaryItems\":[{\"version\":\"1.0\",
\"count\":2,\"remainingCount\":0}]}",
"type-name":"Custom:MyInfo"
}
}

Warning for disabled custom inventory type

{
"version":"0",
"id":"49c1855c-9c57-b5d7-8518-b64aeeef5e4a",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",
"account":"478678815555",
"time":"2018-05-24T22:46:58Z",
"region":"us-east-1",
"resources":[
"arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0ee2d86a2cfc371f6"
],
"detail":{
"action-status":"failed",
"action":"put",
"resource-type":"managed-instance",
"resource-id":"i-0ee2d86a2cfc371f6",
"action-reason":"The inventory item with type name Custom:MyInfo was sent with a
disabled schema versison 1.0. You must send a version greater than 1.0",
"type-name":"Custom:MyInfo"
}

550
 AWS Systems Manager User Guide
Viewing Inventory History and Change Tracking

Use the following procedure to create a CloudWatch Events rule for custom inventory delete operations.
This procedure shows you how to create a rule that sends notifications for custom inventory delete
operations to an Amazon SNS topic. Before you begin, verify that you have an Amazon SNS topic, or
create a new one. For more information, see Getting Started in the Amazon Simple Notification Service
Developer Guide.

To configure CloudWatch Events for delete inventory operations

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then choose Create rule.
3. Under Event Source, verify that Event Pattern is selected.
4. In the Service Name field, choose EC2 Simple Systems Manager (SSM).
5. In the Event Type field, choose Inventory.
6. Verify that Any detail type is selected, and then choose Add targets.
7. In the Select target type list, choose SNS topic, and then choose your topic from the list.
8. In the Configure input list, verify that Matched event is selected.
9. Choose Configure details.
10. Specify a name and a description, and then choose Create rule.

Viewing Inventory History and Change Tracking

You can view Inventory history and change tracking for all of your managed instances by using AWS
Config. AWS Config provides a detailed view of the configuration of AWS resources in your AWS account.
This includes how the resources are related to one another and how they were configured in the past so
that you can see how the configurations and relationships change over time. To view Inventory history
and change tracking, you must enable the following resources in AWS Config.

• SSM:ManagedInstanceInventory
• SSM:PatchCompliance
• SSM:AssociationCompliance

Note
By enabling SSM:PatchCompliance and SSM:AssociationCompliance, you can view Patch
Manager patching and State Manager association compliance history and change tracking.
For more information about compliance management for these resources, see Working With
Configuration Compliance (p. 507).

The following procedure describes how to enable Inventory history and change-track recording in AWS
Config by using the AWS CLI. For more information about how to choose and configure these resources
in AWS Config, see Selecting Which Resources AWS Config Records in the AWS Config Developer Guide.
For information about AWS Config pricing, see Pricing.

Before You Begin

AWS Config requires AWS Identity and Access Management (IAM) permissions to get configuration
details about Systems Manager resources. In the following procedure, you must specify an Amazon
Resource Name (ARN) for an IAM role that gives AWS Config permission to Systems Manager resources.
You can attach the AWSConfigRole managed policy to the IAM role that you assign to AWS Config. For
information about how to create an IAM role and assign the AWSConfigRole managed policy to that
role, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

551
 AWS Systems Manager User Guide
Inventory Walkthroughs

To enable Inventory history and change-track recording in AWS Config

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Copy and paste the following JSON sample into a simple text file and save it as recordingGroup.json.

{
"allSupported":false,
"includeGlobalResourceTypes":false,
"resourceTypes":[
"AWS::SSM::AssociationCompliance",
"AWS::SSM::PatchCompliance",
"AWS::SSM::ManagedInstanceInventory"
]
}

3. Run the following command to load the recordingGroup.json file into AWS Config.

aws configservice put-configuration-recorder --configuration-recorder

name=myRecorder,roleARN=arn:aws:iam::123456789012:role/myConfigRole --recording-group
file://recordingGroup.json

4. Run the following command to start recording Inventory history and change tracking.

aws configservice start-configuration-recorder --configuration-recorder-name myRecorder

After you configure history and change tracking, you can drill down into the history for a specific
managed instance by choosing the AWS Config button in the Systems Manager console.

You can access the AWS Config button from either the Managed Instances page or the Inventory page.
Depending on your monitor size, you might need to scroll to the right side of the page to see the button.

Systems Manager Inventory Walkthroughs

Use the following walkthroughs to collect and manage Inventory data. We recommend that you initially
perform these walkthroughs with managed instances in a test environment.

Before You Begin

Before you start these walkthroughs, complete the following tasks.

• Update SSM Agent on the instances you want to inventory. By running the latest version of SSM
Agent, you ensure that you can collect metadata for all supported inventory types. For information
about how to update SSM Agent by using State Manager, see Automatically Update SSM Agent
(CLI) (p. 681).
• Verify that your instances meet Systems Manager prerequisites. For more information, see Systems
Manager Prerequisites (p. 12).
• (Optional) Create a JSON file to collect custom inventory. For more information, see Working with
Custom Inventory (p. 541).

Contents
• Walkthrough: Assign Custom Inventory Metadata to an Instance (p. 553)
• Walkthrough: Configure Your Managed Instances for Inventory by Using the CLI (p. 554)

552
 AWS Systems Manager User Guide
Inventory Walkthroughs

• Walkthrough: Use Resource Data Sync to Aggregate Inventory Data (p. 556)

Walkthrough: Assign Custom Inventory Metadata to an Instance

The following procedure walks you through the process of using the PutInventory API action to assign
custom Inventory metadata to a managed instance. This example assigns rack location information to an
instance. For more information about custom Inventory, see Working with Custom Inventory (p. 541).

To assign custom Inventory metadata to an instance

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to assign rack location information to an instance.

aws ssm put-inventory --instance-id "ID" --items '[{"CaptureTime":

"2016-08-22T10:01:01Z", "TypeName": "Custom:RackInfo", "Content":[{"RackLocation":
"Bay B/Row C/Rack D/Shelf E"}], "SchemaVersion": "1.0"}]'

3. Run the following command to view custom inventory entries for this instance.

aws ssm list-inventory-entries --instance-id ID --type-name "Custom:RackInfo"

The system responds with information like the following.

{
"InstanceId": "ID",
"TypeName": "Custom:RackInfo",
"Entries": [
{
"RackLocation": "Bay B/Row C/Rack D/Shelf E"
}
],
"SchemaVersion": "1.0",
"CaptureTime": "2016-08-22T10:01:01Z"
}

4. Run the following command to view the custom inventory schema.

aws ssm get-inventory-schema --type-name Custom:RackInfo

The system responds with information like the following.

{
"Schemas": [
{
"TypeName": "Custom:RackInfo",
"Version": "1.0",
"Attributes": [
{
"DataType": "STRING",
"Name": "RackLocation"
}
]
}
]
}

553
 AWS Systems Manager User Guide
Inventory Walkthroughs

Walkthrough: Configure Your Managed Instances for Inventory

by Using the CLI
The following procedures walk you through the process of configuring Inventory to collect metadata
from your managed instances. When you configure Inventory collection, you start by creating a Systems
Manager State Manager association. Systems Manager collects the Inventory data when the association
is run. If you don't create the association first, and attempt to invoke the aws:softwareInventory plugin
by using, for example, Run Command, the system returns the following error:

The aws:softwareInventory plugin can only be invoked via ssm-associate.

Note
An instance can have only one Inventory association configured at a time. If you configure an
instance with two or more Inventory associations, the association doesn't run and no inventory
data is collected.

Quickly Configure All of Your Managed Instances for Inventory (CLI)

You can quickly configure all managed instances in your AWS account and in the current Region to
collect inventory data. This is called creating a global inventory association. To create a global inventory
association by using the AWS CLI, use the wildcard option for the instanceIds value, as shown in the
following procedure.

To configure inventory for all managed instances in your AWS account and in the current
Region (CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command.

aws ssm create-association --name AWS-GatherSoftwareInventory --targets

Key=InstanceIds,Values=* --schedule-expression "rate(1 day)" --parameters
applications=Enabled,awsComponents=Enabled,customInventory=Enabled,instanceDetailedInformation=Ena

Note
This command does not enable inventory of file or Windows Registry metadata. To inventory
these datatypes, use the next procedure.

Manually Configuring Inventory on Your Managed Instances (CLI)

Use the following procedure to manually configure Inventory on your managed instances by using
instance IDs or tags.

To manually configure your managed instances for inventory (CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create a State Manager association that runs Inventory on the
instance. This command configures the service to run every six hours and to collect network
configuration, Windows Update, and application metadata from an instance.

aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets

"Key=instanceids,Values=an instance ID" --schedule-expression "cron(0 0/30 * 1/1
* ? *)" --output-location "{ \"S3Location\": { \"OutputS3Region\": \"region-id\",

554
 AWS Systems Manager User Guide
Inventory Walkthroughs

\"OutputS3BucketName\": \"Test bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" --

parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"

region-id represents the AWS Region where the instance is located, such as us-east-2 for the US
East (Ohio) Region.

The system responds with information like the following.

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 0/30 * 1/1 * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "Test",
"OutputS3BucketName": "Test bucket",
"OutputS3Region": "us-east-2"
}
},
"Name": "The name you specified",
"Parameters": {
"applications": [
"Enabled"
],
"networkConfig": [
"Enabled"
],
"windowsUpdates": [
"Enabled"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g",
"DocumentVersion": "$DEFAULT",
"LastUpdateAssociationDate": 1480544990.06,
"Date": 1480544990.06,
"Targets": [
{
"Values": [
"i-1a2b3c4d5e6f7g"
],
"Key": "InstanceIds"
}
]
}
}

You can target large groups of instances by using the Targets parameter with EC2 tags. For
example:

aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets

"Key=tag:Environment,Values=Production" --schedule-expression "cron(0 0/30 * 1/1
* ? *)" --output-location "{ \"S3Location\": { \"OutputS3Region\": \"us-east-2\",
\"OutputS3BucketName\": \"Test bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" --
parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"

You can also inventory files and Windows Registry keys on a Windows instance by using the files
and windowsRegistry inventory types with expressions. For more information about these
inventory types, see Working with File and Windows Registry Inventory (p. 518).

555
 AWS Systems Manager User Guide
Inventory Walkthroughs

aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets

"Key=instanceids,Values=i-0704358e3a3da9eb1" --schedule-expression "cron(0
0/30 * 1/1 * ? *)" --parameters '{"files":["[{\"Path\": \"C:\\Program Files\",
\"Pattern\": [\"*.exe\"], \"Recursive\": true}]"], "windowsRegistry": ["[{\"Path\":
\"HKEY_LOCAL_MACHINE\\Software\\Amazon\", \"Recursive\":true}]"]}' --profile dev-pdx

3. Run the following command to view the association status.

aws ssm describe-instance-associations-status --instance-id an instance ID

The system responds with information like the following.

{
"InstanceAssociationStatusInfos": [
{
"Status": "Pending",
"DetailedStatus": "Associated",
"Name": "reInvent2016PolicyDocumentTest",
"InstanceId": "i-1a2b3c4d5e6f7g",
"AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g",
"DocumentVersion": "1"
}
]
}

Walkthrough: Use Resource Data Sync to Aggregate Inventory

Data
The following walkthrough describes how to create a Resource Data Sync configuration by using the
AWS CLI. A Resource Data Sync automatically ports Inventory data from all of your managed instances
to a central Amazon S3 bucket. The sync automatically updates the data in the central Amazon S3
bucket whenever new Inventory data is discovered. This walkthrough also describes how to use Amazon
Athena and Amazon QuickSight to query and analyze the aggregated data. For information about
creating a Resource Data Sync by using the Amazon EC2 console, see Configuring Resource Data Sync for
Inventory (p. 520).
Note
This walkthrough includes information about how to encrypt the sync by using AWS Key
Management Service (AWS KMS). Inventory does not collect any user-specific, proprietary, or
sensitive data so encryption is optional. For more information about AWS KMS, see AWS Key
Management Service Developer Guide.

Before You Begin

Before you start this walkthrough, you must collect Inventory metadata from your managed instances.
For the purpose of the Amazon Athena and Amazon QuickSight sections in this walkthrough, we
recommend that you collect Application metadata. For more information about how to collect Inventory
data, see Walkthrough: Configure Your Managed Instances for Inventory by Using the CLI (p. 554).

(Optional) If you want to encrypt the sync by using AWS KMS, then you must either create a new key that
includes the following policy, or you must update an existing key and add this policy to it.

{
"Version":"2012-10-17",
"Id":"ssm-access-policy",
"Statement":[
{

556
 AWS Systems Manager User Guide
Inventory Walkthroughs

"Sid":"ssm-access-policy-statement",
"Action":[
"kms:GenerateDataKey"
],
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Resource":"arn:aws:kms:region:AWS-account-ID:key/KMS-key-id"
}
]
}

To create a Resource Data Sync for Inventory

1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

2. Create a bucket to store your aggregated Inventory data. For more information, see Create a Bucket
in the Amazon Simple Storage Service Getting Started Guide. Make a note of the bucket name and
the AWS Region where you created it.
3. After you create the bucket, choose the Permissions tab, and then choose Bucket Policy.
4. Copy and paste the following bucket policy into the policy editor. Replace bucket-name and
account-id with the name of the Amazon S3 bucket you created and a valid AWS account ID.
Optionally, replace bucket-prefix with the name of an Amazon S3 prefix (subdirectory). If you did
not created a prefix, remove bucket-prefix/ from the ARN in the policy.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SSMBucketPermissionsCheck",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::bucket-name"
},
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": ["arn:aws:s3:::bucket-name/bucket-prefix/*/accountid=account-
id/*"],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control"
}
}
}
]
}

5. (Optional) If you want to encrypt the sync, then you must add the following policy to the bucket.
Repeat the previous step to add the following policy to the bucket.

{
"Version":"2012-10-17",
"Statement":[

557
 AWS Systems Manager User Guide
Inventory Walkthroughs

{
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Action":"s3:PutObject",
"Resource":"arn:aws:s3:::bucket-name/prefix/*",
"Condition":{
"StringEquals":{
"s3:x-amz-server-side-encryption":"aws:kms",
"s3:x-amz-server-side-encryption-aws-kms-key-
id":"arn:aws:kms:region:AWS-account-ID:key/KMS-key-ID"
}
}
}
]
}

6. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
7. (Optional) If you want to encrypt the sync, run the following command to verify that the bucket
policy is enforcing the KMS key requirement.

aws s3 cp ./A file in the bucket s3://bucket-name/prefix/ --sse aws:kms --sse-kms-key-

id "arn:aws:kms:region:AWS-account-ID:key/KMS-key-id" --region region

8. Run the following command to create a Resource Data Sync configuration with the Amazon S3
bucket you created at the start of this procedure. This command creates a sync from the AWS Region
you are currently logged into.
Note
If the sync and the target Amazon S3 bucket are located in different regions, you may be
subject to data transfer pricing. For more information, see Amazon S3 Pricing.

aws ssm create-resource-data-sync --sync-name a name --s3-destination

"BucketName=the name of the S3 bucket,Prefix=the name of the prefix, if
specified,SyncFormat=JsonSerDe,Region=the region where the S3 bucket was created"

You can use the region parameter to specify where the sync configuration should be created. In the
following example, Inventory data from the us-west-1 Region, will be synchronized in the Amazon
S3 bucket in the us-west-2 Region.

aws ssm create-resource-data-sync --sync-name InventoryDataWest --s3-destination

"BucketName=InventoryData,Prefix=HybridEnv,SyncFormat=JsonSerDe,Region=us-west-2" --
region us-west-1

(Optional) If you want to encrypt the sync by using AWS KMS, run the following command to create
the sync. If you encrypt the sync, then the AWS KMS key and the Amazon S3 bucket must be in the
same Region.

aws ssm create-resource-data-sync --sync-name sync-name --s3-destination

"BucketName=bucket-
name,Prefix=prefix,SyncFormat=JsonSerDe,AWSKMSKeyARN=arn:aws:kms:region:AWS-account-
ID:key/KMS-key-id,Region=bucket-region" --region region

9. Run the following command to view the status of sync configuration.

aws ssm list-resource-data-sync

558
 AWS Systems Manager User Guide
Inventory Walkthroughs

If you created the sync configuration in a different Region, then you must specify the region
parameter, as shown in the following example.

aws ssm list-resource-data-sync --region us-west-1

10. After the sync configuration is created successfully, browse the target bucket in Amazon S3.
Inventory data should appear within a few minutes.

Working with the Data in Amazon Athena

The following section describes how to view and query the data in Amazon Athena. Before you begin,
we recommend that you learn about Athena. For more information, see What is Amazon Athena? and
Working with Data in the Amazon Athena User Guide.

To view and query the data in Amazon Athena

1. Open the Athena console at https://console.aws.amazon.com/athena/.

2. Copy and paste the following statement into the query editor and then choose Run Query.

CREATE DATABASE ssminventory

The system creates a database called ssminventory.

3. Copy and paste the following statement into the query editor and then choose Run Query. Replace
bucket-name and bucket-prefix with the name and prefix of the Amazon S3 target.

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Application (

Name string,
ApplicationType string,
Publisher string,
Version string,
InstalledTime string,
Architecture string,
URL string,
Summary string,
PackageId string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:Application/'

4. Copy and paste the following statement into the query editor and then choose Run Query.

MSCK REPAIR TABLE ssminventory.AWS_Application

The system partitions the table.

Note
If you create Resource Data Syncs from additional AWS Regions or accounts, then you
must run this command again to update the partitions. You may also need to update your
Amazon S3 bucket policy.
5. To preview your data, choose the view icon next to the AWS_Application table.

559
 AWS Systems Manager User Guide
Inventory Walkthroughs

6. Copy and paste the following statement into the query editor and then choose Run Query.

SELECT a.name, a.version, count( a.version) frequency

from aws_application a where
a.name = 'aws-cfn-bootstrap'
group by a.name, a.version
order by frequency desc

The query returns a count of different versions of aws-cfn-bootstrap, which is an AWS application
present on Amazon EC2 Linux and Windows instances.
7. Individually copy and paste the following statements into the query editor, replace bucket-
name and bucket-prefix with information for Amazon S3, and then choose Run Query. These
statements set up additional Inventory tables in Athena.

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_AWSComponent (

`ResourceId` string,
`Name` string,
`ApplicationType` string,
`Publisher` string,
`Version` string,
`InstalledTime` string,
`Architecture` string,
`URL` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:AWSComponent/'

MSCK REPAIR TABLE ssminventory.AWS_AWSComponent

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_WindowsUpdate (

`ResourceId` string,
`HotFixId` string,
`Description` string,
`InstalledTime` string,
`InstalledBy` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:WindowsUpdate/'

MSCK REPAIR TABLE ssminventory.AWS_WindowsUpdate

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_InstanceInformation (

`AgentType` string,
`AgentVersion` string,
`ComputerName` string,
`IamRole` string,
`InstanceId` string,
`IpAddress` string,
`PlatformName` string,

560
 AWS Systems Manager User Guide
Inventory Walkthroughs

`PlatformType` string,
`PlatformVersion` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:InstanceInformation/'

MSCK REPAIR TABLE ssminventory.AWS_InstanceInformation

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Network (

`ResourceId` string,
`Name` string,
`SubnetMask` string,
`Gateway` string,
`DHCPServer` string,
`DNSServer` string,
`MacAddress` string,
`IPV4` string,
`IPV6` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:Network/'

MSCK REPAIR TABLE ssminventory.AWS_Network

CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_PatchSummary (

`ResourceId` string,
`PatchGroup` string,
`BaselineId` string,
`SnapshotId` string,
`OwnerInformation` string,
`InstalledCount` int,
`InstalledOtherCount` int,
`NotApplicableCount` int,
`MissingCount` int,
`FailedCount` int,
`OperationType` string,
`OperationStartTime` string,
`OperationEndTime` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://bucket-name/bucket-prefix/AWS:PatchSummary/'

MSCK REPAIR TABLE ssminventory.AWS_PatchSummary

Working with the Data in Amazon QuickSight

The following section provides an overview with links for building a visualization in Amazon QuickSight.

To build a visualization in Amazon QuickSight

1. Sign up for Amazon QuickSight and then log in to the QuickSight console.

561
 AWS Systems Manager User Guide
Troubleshooting Inventory

2. Create a data set from the AWS_Application table and any other tables you created. For more
information, see Creating a Data Set Using Amazon Athena Data.
3. Join tables. For example, you could join the instanceid column from
AWS_InstanceInformation because it matches the resourceid column in other inventory
tables. For more information about joining tables, see Joining Tables.
4. Build a visualization. For more information, see Working with Amazon QuickSight Visuals.

Troubleshooting Problems with Systems Manager

Inventory
This topic includes information about how to troubleshoot common errors or problems with Systems
Manager Inventory.

Console doesn't display Inventory Dashboard | Detailed View | Settings tabs

The Inventory Detailed View page is only available in AWS Regions that offer Amazon Athena. If the
following tabs are not displayed on the Inventory page, it means Athena is not available in the Region
and you can't use the Detailed View to query data.

UnsupportedAgent

If the detailed status of an inventory association shows UnsupportedAgent, and the Association status
shows Failed, then the version of SSM Agent on the instance is not correct. To create a global inventory
association (to inventory all instances in your AWS account) for example, you must use SSM Agent
version 2.0.790.0 or later. You can view the agent version running on each of your instances on the
Managed Instances page in the Agent version column. For information about how to update SSM Agent
on your instances, see Update SSM Agent by using Run Command (p. 620).

Skipped

If the status of the inventory association for an instance shows Skipped, this means that you created a
global inventory association, but the skipped instance already had an inventory association assigned to
it. The global inventory association was not assigned to this instance, and no inventory was collected by
the global inventory association. However, the instance will still report inventory data when the specific
inventory association runs.

Failed

If the status of the inventory association for an instance shows Failed, this could mean that the instance
has multiple inventory associations assigned to it. An instance can only have one inventory association
assigned at a time. An inventory association uses the AWS-GatherSoftwareInventory SSM document. You
can run the following command by using the AWS CLI to view a list of associations for an instance.

562
 AWS Systems Manager User Guide
Managed Instances

aws ssm describe-instance-associations-status --instance-id instance ID

AWS Systems Manager Managed Instances

A managed instance is any machine configured for AWS Systems Manager. You can configure Amazon
EC2 instances or on-premises machines in a hybrid environment as managed instances. Systems Manager
supports various distributions of Linux, including Raspberry Pi devices, and Microsoft Windows Server.
Note
In the AWS Management Console, any machine prefixed with "mi-" is an on-premises server or
virtual machine (VM) managed instance.

AWS Systems Manager offers a standard-instances tier and an advanced-instances tier for servers and
VMs in your hybrid environment. The standard-instances tier enables you to register a maximum of 1,000
servers or VMs per AWS account per AWS Region. If you need to register more than 1,000 servers or VMs
in a single account and Region, then use the advanced-instances tier. You can create as many instances as
you like in the advanced-instances tier, but all instances configured for Systems Manager are priced on a
pay-per-use basis. For more information about enabling advanced instances, see (Optional) Enable the
Advanced-Instances Tier (p. 53). For more information about pricing, see AWS Systems Manager Pricing.
Note

• Advanced instances also enable you to connect to your hybrid machines by using AWS
Systems Manager Session Manager. Session Manager provides interactive shell access to your
instances. For more information, see AWS Systems Manager Session Manager (p. 567).
• The standard-instances limit also applies to Amazon EC2 instances that use a Systems
Manager on-premises activation (which is not a common scenario).
• Microsoft application patching is only available on Amazon EC2 instances and in the
advanced-instances tier. To patch Microsoft applications on on-premises servers and VMs,
you must enable the advanced-instances tier. For more information, see About Patching
Applications on Windows Server (p. 719).

If you don't see your managed instances listed in the console, then do the following:

1. Verify that the console is open in the AWS Region where you created your managed instances. You can
switch Regions by using the list in the top, right corner of the console.
2. Verify that your instances meet Systems Manager requirements. For information, see Systems
Manager Prerequisites (p. 12).
3. For servers and VMs in a hybrid environment, verify that you completed the activation process. For
more information, see Setting Up AWS Systems Manager for Hybrid Environments (p. 41).

Note
Systems Manager requires accurate time references in order to perform its operations. If your
instance's date and time are not set correctly, they may not match the signature date of your API
requests. For more information, see Use Cases and Best Practices (p. 942).

Verify Systems Manager support on an instance

AWS Config provides AWS Managed Rules, which are predefined, customizable rules that AWS Config
uses to evaluate whether your AWS resource configurations comply with common best practices.
AWS Config Managed Rules include the ec2-instance-managed-by-systems-manager rule. This rule
checks whether the Amazon EC2 instances in your account are managed by Systems Manager. For more
information, see AWS Config Managed Rules.

563
 AWS Systems Manager User Guide
Resetting Passwords on Managed Instances

Verify Systems Manager Prerequisites

For information about Systems Manager prerequisites, see Systems Manager Prerequisites (p. 12). For
information about configuring on-premises servers and VMs as managed instances, see Setting Up AWS
Systems Manager for Hybrid Environments (p. 41).

Increase security posture on managed instances

For more information increasing your security posture against unauthorized root-level commands on
your instances, see Restrict Access to Root-Level Commands Through SSM Agent (p. 85)

Reset the password on a managed instance

If you forget or want to change the password to one of your managed instances, you can reset it using
the AWS Systems Manager Managed Instances console or the AWS CLI. For more information, see
Resetting Passwords on Managed Instances (p. 564).

Resetting Passwords on Managed Instances

You can reset the password for any user on a managed instance. This includes Amazon EC2 instances, on-
premises servers, and virtual machines (VMs) that are managed by AWS Systems Manager. The password
reset functionality is built on the AWS Systems Manager Session Manager capability. You can use this
functionality to connect to instances without opening inbound ports, maintaining bastion hosts, or
managing SSH keys.

This makes the password reset option useful when a user has forgotten a password, or when you want to
quickly update a password without making an RDP or SSH connection to the instance.

Prerequisites

Before you can reset the password on an instance, the following requirements must be met:

• The instance you want to change a password on must be a Systems Manager managed instance. This
means that SSM Agent is installed on the instance. (SSM Agent Version 2.3.668.0 or later is required
for changing passwords.) For information about installing or updating SSM Agent, see Working with
SSM Agent (p. 64).
• The password reset functionality uses the AWS Session Manager configuration that is set up for your
account to connect to the instance. Therefore, the prerequisites for using Session Manager must have
been completed for your account in the current Region. For more information, see Getting Started
with Session Manager (p. 571).
Note
Session Manager support for on-premises servers is provided for the advanced-instances tier
only. For information, see (Optional) Enable the Advanced-Instances Tier (p. 53).
• The AWS user who is changing the password must have the ssm:SendCommand permission for the
instance. For information, see Restricting Run Command Access Based on Instance Tags (p. 616).

Restricting Access

You can limit a user's ability to reset passwords to specific instances. This is done by using identity-
based policies for the Session Manager ssm:StartSession action with the AWS-PasswordReset SSM
document. For more information, see Control User Session Access to Instances (p. 579).

Encrypting Data

You must enable AWS Key Management Service (AWS KMS) end-to-end encryption for Session Manager
data to use the password reset option for managed instances. For more information, see Enable AWS
KMS Key Encryption of Session Data (Console) (p. 590).

564
 AWS Systems Manager User Guide
Resetting Passwords on Managed Instances

Reset a Password on a Managed Instance

You can reset a password on a Systems Manager managed instance using the AWS Systems Manager
Managed Instances console or the AWS CLI.

To change the password on a managed instance (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Managed Instances.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Managed Instances.
3. Choose the button next to the instance that needs a new password.
4. In the Actions menu, choose Reset password.
5. For User name, type the name of the user for which you are changing the password. This can be any
user name that has an account on the instance.
6. Choose Submit.
7. Follow the prompts in the Enter new password command window to specify the new password.
Note
If the version of SSM Agent on the instance doesn't support password resets, you are
prompted to install a supported version using Run Command.

To reset the password on a managed instance (CLI)

1. To reset the password for a user on a managed instance, run the following command.
Note
To use the AWS CLI to reset a password, the Session Manager plugin must be installed on
your local machine. For information, see (Optional) Install the Session Manager Plugin for
the AWS CLI (p. 599).

aws ssm start-session --target instance-id --document-name "AWS-PasswordReset" --

parameters "{"username": "user-name"}"

instance-id represents the ID of an instance configured for use with Systems Manager and its
Session Manager capability.

user-name represents the name of the user you want to reset password for on the instance.
2. Follow the prompts in the Enter new password command window to specify the new password.

Troubleshoot Password Resets on Managed Instances

Many password reset issues can be resolved by ensuring that you have completed the Password Reset
Prerequisites (p. 564). For other problems, use the following information to help you troubleshoot
password reset issues.

Topics
• Instance not available (p. 566)
• SSM Agent not up-to-date (console) (p. 566)
• Password reset options do not appear (CLI) (p. 566)
• No authorization to run ssm:SendCommand (p. 566)

565
 AWS Systems Manager User Guide
Resetting Passwords on Managed Instances

• Session Manager error message (p. 567)

Instance not available

Problem: You want to reset the password for an Amazon EC2 instance on the Managed instances
console page, but the instance is not in the list.

• Solution: The instance you want to connect to might not be configured to use with the AWS Systems
Manager service. To use an Amazon EC2 instance with Systems Manager, an IAM instance profile that
gives Systems Manager permission to perform actions on your instances must be attached to the
instance. For information, see Create an IAM Instance Profile for Systems Manager (p. 29). To use an
on-premises server or virtual machine (VM) that you have activated for use with Systems Manager, you
must create an IAM service role that gives Systems Manager permission to perform actions on your
machines. For information, see Create an IAM Service Role for a Hybrid Environment (p. 42). (Session
Manager support for on-premises servers and VMs is provided for the advanced-instances tier only. For
information, see (Optional) Enable the Advanced-Instances Tier (p. 53).)

SSM Agent not up-to-date (console)

Problem: A message reports that the version of SSM Agent doesn't support password reset functionality.

• Solution: Version 2.3.668.0 or later of SSM Agent is required to perform password resets. In the
console, you can begin the process of updating the agent on the instance by choosing Update SSM
Agent.

An updated version of SSM Agent is released whenever new capabilities are added to Systems Manager
or updates are made to existing capabilities. If an older version of the agent is running on an instance,
some SSM Agent processes can fail. For that reason, we recommend that you automate the process
of keeping SSM Agent up-to-date on your instances. For information, see Automate Updates to SSM
Agent (p. 86). To be notified about SSM Agent updates, subscribe to the SSM Agent Release Notes
page on GitHub.

Password reset options do not appear (CLI)

Problem: You connect successfully to an instance using the AWS CLI start-session command. You
specified the SSM Document AWS-PasswordReset and provided a valid user name, but prompts to
change the password do not appear.

• Solution: The version of SSM Agent on the instance is not up-to-date. Version 2.3.668.0 or later is
required to perform password resets.

An updated version of SSM Agent is released whenever new capabilities are added to Systems Manager
or updates are made to existing capabilities. If an older version of the agent is running on an instance,
some SSM Agent processes can fail. For that reason, we recommend that you automate the process
of keeping SSM Agent up-to-date on your instances. For information, see Automate Updates to SSM
Agent (p. 86). To be notified about SSM Agent updates, subscribe to the SSM Agent Release Notes
page on GitHub.

No authorization to run ssm:SendCommand

Problem: You attempt to connect to an instance to change its password but receive an error message
saying that you aren't authorized to run ssm:SendCommand on the instance.

• Solution: Your IAM user policy must include permission to run the ssm:SendCommand command. For
information, see Restricting Run Command Access Based on Instance Tags (p. 616).

566
 AWS Systems Manager User Guide
Activations

Session Manager error message

Problem: You receive an error message related to Session Manager.

• Solution: Password reset support requires that Session Manager is configured correctly. For
information, see Getting Started with Session Manager (p. 571) and Troubleshooting Session
Manager (p. 611).

Related Content

• For information about increasing your security posture against unauthorized root-level commands on
your instances, see Restrict Access to Root-Level Commands Through SSM Agent (p. 85)
• AWS Config provides AWS Managed Rules, which are predefined, customizable rules that AWS Config
uses to evaluate whether your AWS resource configurations comply with common best practices.
AWS Config Managed Rules include the ec2-instance-managed-by-systems-manager rule. This rule
checks whether the Amazon EC2 instances in your account are managed by Systems Manager. For
more information, see AWS Config Managed Rules.

AWS Systems Manager Activations

To set up servers and virtual machines (VMs) in your hybrid environment as managed instances, you
create a managed-instance activation. After you complete the activation, you receive an activation code
and ID. This code/ID combination functions like an Amazon EC2 access ID and secret key to provide
secure access to the Systems Manager service from your managed instances.

For information about configuring on-premises servers and VMs as managed instances, see Setting Up
AWS Systems Manager for Hybrid Environments (p. 41).

About AWS Systems Manager Instances Tiers

AWS Systems Manager offers a standard-instances tier and an advanced-instances tier for servers and
VMs in your hybrid environment. The standard-instances tier enables you to register a maximum of 1,000
servers or VMs per AWS account per AWS Region. If you need to register more than 1,000 servers or VMs
in a single account and Region, then use the advanced-instances tier. You can create as many instances as
you like in the advanced-instances tier, but all instances configured for Systems Manager are priced on a
pay-per-use basis. For more information about enabling advanced instances, see (Optional) Enable the
Advanced-Instances Tier (p. 53). For more information about pricing, see AWS Systems Manager Pricing.
Note

• Advanced instances also enable you to connect to your hybrid machines by using AWS
Systems Manager Session Manager. Session Manager provides interactive shell access to your
instances. For more information, see AWS Systems Manager Session Manager (p. 567).
• The standard-instances limit also applies to Amazon EC2 instances that use a Systems
Manager on-premises activation (which is not a common scenario).
• Microsoft application patching is only available on Amazon EC2 instances and in the
advanced-instances tier. To patch Microsoft applications on on-premises servers and VMs,
you must enable the advanced-instances tier. For more information, see About Patching
Applications on Windows Server (p. 719).

AWS Systems Manager Session Manager

Session Manager is a fully managed AWS Systems Manager capability that lets you manage your Amazon
EC2 instances through an interactive one-click browser-based shell or through the AWS CLI. Session

567
 AWS Systems Manager User Guide
How can Session Manager benefit my organization?

Manager provides secure and auditable instance management without the need to open inbound
ports, maintain bastion hosts, or manage SSH keys. Session Manager also makes it easy to comply with
corporate policies that require controlled access to instances, strict security practices, and fully auditable
logs with instance access details, while still providing end users with simple one-click cross-platform
access to your Amazon EC2 instances.

How can Session Manager benefit my organization?

Session Manager offers these benefits:

• Centralized access control to instances using IAM policies

Administrators have a single place to grant and revoke access to instances. Using only AWS Identity
and Access Management (IAM) policies, you can control which individual users or groups in your
organization can use Session Manager and which instances they can access.
• No open inbound ports and no need to manage bastion hosts or SSH keys

Leaving inbound SSH ports and remote PowerShell ports open on your instances greatly increases
the risk of entities running unauthorized or malicious commands on the instances. Session Manager
helps you improve your security posture by letting you close these inbound ports, freeing you from
managing SSH keys and certificates, bastion hosts, and jump boxes.
• One-click access to instances from the console and CLI

Using the AWS Systems Manager console, you can start a session with a single click. Using the AWS
CLI, you can also start a session that runs a single command or a sequence of commands. Because
permissions to instances are provided through IAM policies instead of SSH keys or other mechanisms,
the connection time is greatly reduced.
• Port forwarding

Redirect any port inside your remote instance to a local port on a client. After that, connect to the
local port and access the server application that is running inside the instance.
• Cross-platform support for both Windows and Linux

Session Manager provides both Windows and Linux support from a single tool. For example, you don't
need to use an SSH client for Linux instances and an RDP connection for Windows instances.
• Logging and auditing session activity

To meet operational or security requirements in your organization, you might need to provide a record
of the connections made to your instances and the commands that were run on them. You can also
receive notifications when a user in your organization starts or ends session activity.

Logging and auditing capabilities are provided through integration with the following AWS services:
• AWS CloudTrail – AWS CloudTrail captures information about Session Manager API calls made in
your AWS account and writes it to log files that are stored in an Amazon S3 bucket you specify.
One bucket is used for all CloudTrail logs for your account. For more information, see Logging AWS
Systems Manager API Calls with AWS CloudTrail (p. 889).
• Amazon Simple Storage Service – You can choose to store session log data in an Amazon S3
bucket of your choice for auditing purposes. Log data can be sent to your S3 bucket with or without
encryption using your AWS Key Management Service (AWS KMS) key. For more information, see
Logging Session Data Using Amazon S3 (Console) (p. 608).
• Amazon CloudWatch Logs – CloudWatch Logs lets you monitor, store, and access log files from
various AWS services. You can send session log data to a CloudWatch Logs log group for auditing
purposes. Log data can be sent to your log group with or without AWS KMS encryption using your
AWS KMS key. For more information, see Logging Session Data Using Amazon CloudWatch Logs
(Console) (p. 609).

568
 AWS Systems Manager User Guide
Who Should Use Session Manager?

• Amazon CloudWatch Events and Amazon Simple Notification Service – CloudWatch Events
lets you set up rules to detect when changes happen to AWS resources that you specify. You can
create a rule to detect when a user in your organization starts or stops a session, and then receive a
notification through Amazon SNS (for example, a text or email message) about the event. You can
also configure a CloudWatch event to trigger other responses. For more information, see Monitoring
Session Activity Using Amazon CloudWatch Events (Console) (p. 610).

Who Should Use Session Manager?

• Any AWS customer who wants to improve their security and audit posture, reduce operational
overhead by centralizing access control on instances, and reduce inbound instance access.
• Information Security experts who want to monitor and track instance access and activity, close down
inbound ports on instances, or enable connections to instances that do not have a public IP address.
• Administrators who want to grant and revoke access from a single location, and who want to provide
one solution to users for both Windows and Linux instances.
• End users who want to connect to an instance with just one click from the browser or CLI without
having to provide SSH keys.

What Are the Main Features of Session Manager?

• Support for both Windows and Linux instances

Session Manager lets you establish secure connections to your Amazon Elastic Compute Cloud
(Amazon EC2) instances. For a list of supported Windows and Linux operating system types, see
Getting Started with Session Manager (p. 571).
Note
Session Manager support for on-premises servers is provided for the advanced-instances tier
only. For information, see (Optional) Enable the Advanced-Instances Tier (p. 53).
• Console, CLI, and SDK access to Session Manager capabilities

You can work with Session Manager in the following ways:

The AWS Systems Manager console includes access to all the Session Manager capabilities for both
administrators and end-users. You can perform any task that's related to your sessions by using the
Systems Manager console.

The AWS CLI includes access to Session Manager capabilities for end users. You can start a session,
view a list of sessions, and permanently terminate a session by using the AWS CLI.
Note
To use the AWS CLI to run session commands, you must be using version 1.16.12 of the CLI
(or later), and you must have installed the Session Manager plugin on your local machine. For
information, see (Optional) Install the Session Manager Plugin for the AWS CLI (p. 599).

The Session Manager SDK consists of libraries and sample code that enables application developers to
build frontend applications, such as custom shells or self-service portals for internal users that natively
use Session Manager to connect to instances. Developers and partners can integrate Session Manager
into their client-side tooling or Automation workflows using the Session Manager APIs. You can even
build custom solutions.
• IAM access control

Through the use of IAM policies, you can control which members of your organization can initiate
sessions to instances and which instances they can access. You can also provide temporary access

569
 AWS Systems Manager User Guide
What Is a Session?

to your instances. For example, you might want to give an on-call engineer (or a group of on-call
engineers) access to production servers only for the duration of their rotation.
• Logging and auditing capability support

Session Manager provide you with options for auditing and logging session histories in your AWS
account through integration with a number of other AWS services. For more information, see Auditing
and Logging Session Activity (p. 608).
• Customer key data encryption support

You can configure Session Manager to encrypt the session data logs that you send to an Amazon
S3 bucket or stream to a CloudWatch Logs log group. You can also configure Session Manager
to further encrypt the data transmitted between client machines and your instances during your
sessions. For information, see Auditing and Logging Session Activity (p. 608) and Configure Session
Preferences (p. 587).
• AWS PrivateLink support for instances without public IP addresses

You can also set up VPC Endpoints for Systems Manager using AWS PrivateLink to further secure your
sessions. PrivateLink limits all network traffic between your managed instances, Systems Manager, and
Amazon EC2 to the Amazon network. For more information, see (Optional) Create a Virtual Private
Cloud Endpoint (p. 36).
• Tunneling

In a session, use a Session-type SSM document to tunnel traffic, such as http or a custom protocol,
between a local port on a client machine and a remote port on an instance.
• Interactive Commands

Create a Session-type SSM document that uses a session to interactively run a single command, giving
you a way to manage what users can do on an instance.

What Is a Session?
A session is a connection made to an instance using Session Manager. Sessions are based on a secure
bi-directional communication channel between the client (you) and the remote managed instance
that streams inputs and outputs for commands. Traffic between a client and a managed instance is
encrypted using TLS 1.2, and requests to create the connection are signed using Sigv4. This two-way
communication enables interactive bash and PowerShell access to instances. You can also use an AWS
Key Management Service (AWS KMS) key to further encrypt data beyond the default TLS encryption.

For example, say that John is an on-call engineer in your IT department. He receives notification
of an issue that requires him to remotely connect to an instance, such as a failure that requires
troubleshooting or a directive to change a simple configuration option on an instance. Using the AWS
Systems Manager console or the AWS CLI, John starts a session connecting him to the instance, runs
commands on the instance needed to complete the task, and then terminates the session.

When John sends that first command to start the session, the Session Manager service authenticates
his ID, verifies the permissions granted to him by an IAM policy, checks configuration settings (such
as verifying allowed limits for the sessions), and sends a message to SSM Agent to open the two-way
connection. After the connection is established and John types the next command, the command output
from SSM Agent is uploaded to this communication channel and sent back to his local machine.

Topics
• Getting Started with Session Manager (p. 571)
• Working with Session Manager (p. 598)
• Auditing and Logging Session Activity (p. 608)
• Troubleshooting Session Manager (p. 611)

570
 AWS Systems Manager User Guide
Getting Started with Session Manager

Getting Started with Session Manager

Before you use Session Manager to connect to the Amazon EC2 instances in your account, complete the
steps in the following topics.

Topics
• Step 1: Complete Session Manager Prerequisites (p. 571)
• Step 2: Verify or Create an IAM Instance Profile with Session Manager Permissions (p. 573)
• Step 3: Control User Session Access to Instances (p. 579)
• Step 4: Configure Session Preferences (p. 587)
• Step 5: (Optional) Use PrivateLink to Set Up a VPC Endpoint for Session Manager (p. 594)
• Step 6: (Optional) Disable or Enable ssm-user Account Administrative Permissions (p. 594)
• Step 7: (Optional) Enable SSH Connections Through Session Manager (p. 597)

Step 1: Complete Session Manager Prerequisites

Before using Session Manager, make sure your environment meets the following requirements.

Session Manager Prerequisites

Requirement Description

Supported Operating Systems AWS Session Manager supports the following

operating system versions:
Note
Session Manager supports Amazon
EC2 instances, as well as servers or
virtual machines (VMs) in your hybrid
environment that use the advanced-
instances tier. For more information
about advanced instances, see (Optional)
Enable the Advanced-Instances
Tier (p. 53).

Linux

Session Manager supports all the versions of Linux

that are supported for AWS Systems Manager as
a whole. For information, see Systems Manager
Prerequisites (p. 12).

Windows

Session Manager supports Windows Server 2008

R2 through Windows Server 2016.
Note
Microsoft Windows Server 2016 Nano is
not supported.

SSM Agent SSM Agent version 2.3.68.0 or later must be

installed on the instances you want to connect
to through sessions. To use the option to encrypt
session data using a customer master key (CMK)
created in AWS Key Management Service (AWS

571
 AWS Systems Manager User Guide
Getting Started with Session Manager

Requirement Description
KMS), version 2.3.539.0 or later of SSM Agent
must be installed.

To install or update SSM Agent, see Working with

SSM Agent (p. 64).

About the ssm-user account

Starting with version 2.3.50.0 of SSM Agent, the

agent creates a user account on the instance,
with root or administrator privileges, called ssm-
user. (On versions before 2.3.612.0, the account
is created when SSM Agent starts or restarts. On
version 2.3.612.0 and later, ssm-user is created
the first time a session starts on the instance.)
Sessions are launched using the administrative
credentials of this user account. For information
about restricting administrative control for
this account, see Step 6: (Optional) Disable
or Enable ssm-user Account Administrative
Permissions (p. 594).

ssm-user on Windows Server domain controllers

Beginning with SSM Agent version 2.3.612.0, the

ssm-user account is not created automatically
on managed instances that are used as Windows
Server domain controllers. To use Session
Manager on a Windows Server machine being
used as a domain controller, you must create the
ssm-user account manually if it isn't already
present. On Windows Server, SSM Agent sets a
new password for the ssm-user account each
time a session starts, so you do not need to
specify a password when you create the account.

572
 AWS Systems Manager User Guide
Getting Started with Session Manager

Requirement Description

AWS CLI (Optional) If you use the AWS CLI to start your
sessions (instead of using the AWS Systems
Manager console), version 1.16.12 or later of the
CLI must be installed on your local machine.

You can call aws --version to check the version.

If you need to install or upgrade the CLI, see

Installing the AWS Command Line Interface in the
AWS Command Line Interface User Guide.
Important
An updated version of SSM Agent is
released whenever new capabilities are
added to Systems Manager or updates
are made to existing capabilities. If an
older version of the agent is running on
an instance, some SSM Agent processes
can fail. For that reason, we recommend
that you automate the process of keeping
SSM Agent up-to-date on your instances.
For information, see Automate Updates
to SSM Agent (p. 86). To be notified
about SSM Agent updates, subscribe to
the SSM Agent Release Notes page on
GitHub.

In addition, to use the CLI to manage your

instances with Session Manager, you must first
install the Session Manager plugin on your
local machine. For information, see (Optional)
Install the Session Manager Plugin for the AWS
CLI (p. 599).

Step 2: Verify or Create an IAM Instance Profile with Session

Manager Permissions
By default, AWS Systems Manager doesn't have permission to perform actions on your instances. You
must grant access by using an IAM instance profile. An instance profile is a container that passes IAM role
information to an Amazon EC2 instance at launch. This requirement applies to permissions for all AWS
Systems Manager capabilities, not only those specific to Session Manager.

If you already use other Systems Manager capabilities, such as Run Command or Parameter
Store, an instance profile with the required basic permissions for Session Manager might already
be attached to your instances. If an instance profile that contains the AWS managed policy
AmazonSSMManagedInstanceCore is already attached to your instances, the required permissions for
Session Manager are already provided.

However, in some cases, you might need to modify the permissions attached to your instance profile. For
example, you want to provide a narrower set of instance permissions, you have created a custom policy
for your instance profile, or you want to use Amazon S3 encryption or AWS KMS encryption options for
securing session data. For these cases, do one of the following to allow Session Manager actions to be
performed on your instances:

• Embed permissions for Session Manager actions in a custom instance profile

573
 AWS Systems Manager User Guide
Getting Started with Session Manager

To add permissions for Session Manager actions to an existing IAM instance profile that does not rely
on the AWS-provided default policy AmazonSSMManagedInstanceCore, follow the steps in Adding
Session Manager Permissions to an Existing Instance Profile (p. 574).
• Create a custom IAM instance profile with Session Manager permissions only

To create an IAM instance profile that contains permissions only for Session Manager actions, follow
the steps in Create a Custom IAM Instance Profile for Session Manager (p. 575).
• Create and use a new instance profile with permissions for all Systems Manager actions

To create an IAM instance profile for Systems Manager managed instances that uses an AWS-supplied
default policy granting all Systems Manager permissions, follow the steps in Create an IAM Instance
Profile for Systems Manager (p. 29).

Note
You can attach an IAM instance profile to an Amazon EC2 instance as you launch it or to a
previously launched instance. For more information, see Instance Profiles.

Topics
• Adding Session Manager Permissions to an Existing Instance Profile (p. 574)
• Create a Custom IAM Instance Profile for Session Manager (p. 575)

Adding Session Manager Permissions to an Existing Instance Profile

Follow these steps to embed Session Manager permissions in an existing IAM instance profile that
does not rely on the AWS-provided default policy AmazonSSMManagedInstanceCore for instance
permissions. Note that this procedure assumes that your existing profile already includes other Systems
Manager ssm permissions for actions you want to allow access to. This policy alone is not enough to use
Session Manager.

To add Session Manager permissions to an existing instance profile (console)

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Choose the name of the role to embed a policy in.
4. Choose the Permissions tab.
5. Scroll to the bottom of the page and choose Add inline policy.
6. Choose the JSON tab.
7. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
},
{

574
 AWS Systems Manager User Guide
Getting Started with Session Manager

"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}
]
}

About 'ssmmessages'

For information about ssmmessages, see Reference: ec2messages, ssmmessages, and Other API
Calls (p. 941).

About 'kms:Decrypt'

In this policy, the kms:Decrypt permission enables customer key encryption and
decryption for session data. If you will use AWS Key Management Service (AWS
KMS) encryption for your session data, replace key-name with the ARN of the
customer master key (CMK) you want to use, in the format arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE.

If you will not use AWS KMS encryption for your session data, you can remove the following content
from the policy:

,
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}

For information about using AWS KMS and a CMK to encrypt session data, see Enable AWS KMS Key
Encryption of Session Data (Console) (p. 590).
8. Choose Review policy.
9. On the Review policy page, for Name, enter a name for the inline policy. For example:
SessionManagerPermissions.
10. Choose Create policy.

Create a Custom IAM Instance Profile for Session Manager

You can create a custom IAM instance profile that provides permissions for only Session Manager actions
on your instances. You can also create a policy to provide the permissions needed for logs of session
activity to be sent to Amazon S3 and CloudWatch Logs.

After you create an instance profile, see Attaching an IAM Role to an Instance and Attach or Replace
an Instance Profile for information about how to attach the instance profile to an instance, For more
information about IAM instance profiles and roles, see Using Instance Profile and IAM Roles for Amazon
EC2 in the IAM User Guide.

575
 AWS Systems Manager User Guide
Getting Started with Session Manager

Topics
• Creating an Instance Profile with Minimal Session Manager Permissions (Console) (p. 576)
• Creating an Instance Profile with Permissions for Session Manager and Amazon S3 and CloudWatch
Logs (Console) (p. 577)

Creating an Instance Profile with Minimal Session Manager Permissions (Console)

Use the following procedure to create a custom IAM instance profile with a policy that provides
permissions for only Session Manager actions on your instances.

To create an instance profile with minimal Session Manager permissions (console)

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Policies, and then choose Create policy. (If a Get Started button
appears, choose it, and then choose Create Policy.)
3. Choose the JSON tab.
4. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:UpdateInstanceInformation",
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}
]
}

About 'ssmmessages'

For information about ssmmessages, see Reference: ec2messages, ssmmessages, and Other API
Calls (p. 941).

About 'kms:Decrypt'

In this policy, the kms:Decrypt permission enables customer key encryption and
decryption for session data. If you will use AWS Key Management Service (AWS

576
 AWS Systems Manager User Guide
Getting Started with Session Manager

KMS) encryption for your session data, replace key-name with the ARN of the
customer master key (CMK) you want to use, in the format arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE.

If you will not use AWS KMS encryption for your session data, you can remove the following content
from the policy:

,
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}

For information about using AWS KMS and a CMK to encrypt session data, see Enable AWS KMS Key
Encryption of Session Data (Console) (p. 590).
5. Choose Review policy.
6. On the Review policy page, for Name, enter a name for the inline policy. For example:
SessionManagerPermissions.
7. (Optional) For Description, enter a description for the policy.
8. Choose Create policy.
9. In the navigation pane, choose Roles, and then choose Create role.
10. On the Create role page, choose AWS service, and from the Choose the service that will use this
role list, choose EC2.
11. Choose Next: Permissions.
12. On the Attached permissions policy page, select the check box to the left of name of the policy you
just created. For example: SessionManagerPermissions.
13. Choose Next: Review.
14. On the Review page, for Role name, enter a name for the IAM instance profile. For example
MySessionManagerInstanceProfile.
15. (Optional) For Role description, enter a description for the instance profile.
16. Choose Create role.

Creating an Instance Profile with Permissions for Session Manager and Amazon S3 and
CloudWatch Logs (Console)

Use the following procedure to create a custom IAM instance profile with a policy that provides
permissions for Session Manager actions on your instances. The policy also provides the permissions
needed for session logs to be stored in Amazon S3 buckets and CloudWatch Logs log groups.

For information about specifying preferences for storing session logs, see Auditing and Logging Session
Activity (p. 608).

To create an instance profile with permissions for Session Manager and Amazon S3 and
CloudWatch Logs (console)

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Policies, and then choose Create policy. (If a Get Started button
appears, choose it, and then choose Create Policy.)
3. Choose the JSON tab.

577
 AWS Systems Manager User Guide
Getting Started with Session Manager

4. Replace the default content with the following. Be sure to replace s3-bucket-name and s3-
bucket-prefix with the names for your bucket and its prefix (if any). For information about
ssmmessages in the following policy, see Reference: ec2messages, ssmmessages, and Other API
Calls (p. 941).

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel",
"ssm:UpdateInstanceInformation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::s3-bucket-name/s3-bucket-prefix"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "*"
}
]
}

Important
To output session logs to an Amazon S3 bucket owned by a different AWS account, you
must add the IAM s3:PutObjectAcl permission to this policy. If this permission isn't
added, the account that owns the S3 bucket cannot access the session output logs.
5. Choose Review policy.
6. On the Review policy page, for Name, enter a name for the inline policy. For example:
SessionManagerPermissions.
7. (Optional) For Description, enter a description for the policy.
8. Choose Create policy.
9. In the navigation pane, choose Roles, and then choose Create role.

578
 AWS Systems Manager User Guide
Getting Started with Session Manager

10. On the Create role page, choose AWS service, and from the Choose the service that will use this
role list, choose EC2.
11. Choose Next: Permissions.
12. On the Attached permissions policy page, select the check box to the left of name of the policy you
just created. For example: SessionManagerPermissions.
13. Choose Next: Review.
14. On the Review page, for Role name, enter a name for the IAM instance profile. For example
MySessionManagerInstanceProfile.
15. (Optional) For Role description, enter a description for the instance profile.
16. Choose Create role.

Step 3: Control User Session Access to Instances

Session Manager allows you to centrally grant and revoke user access to instances. Using IAM policies,
you control which instances specific users or groups can connect to, and you control what Session
Manager API actions they can perform on the instances they are given access to.

About Session ID ARN Formats

IAM policies for Session Manager access use variables for user names as part of session IDs. Session IDs
in turn are used in session Amazon Resource Names (ARNs) to control access. Session ARNs have the
following format:

arn:aws:ssm:region-id:account-id:session/session-id

For example:

arn:aws:ssm:us-east-2:123456789012:session/JohnDoe-1a2b3c4d5eEXAMPLE

You can use a pair of AWS-supplied default IAM policies, one for end users and one for administrators,
to supply permissions for Session Manager activities. Or you can create custom IAM policies for different
permissions requirements you might have.

For more information about using variables in IAM policies, see IAM Policy Elements: Variables.

For information about how to create policies and attach them to IAM users or groups, see Creating IAM
Policies and Adding and Removing IAM Policies in the IAM User Guide.

Topics
• Enforce Document Permission Check for Default CLI Scenario (p. 579)
• Quickstart Default IAM Policies for Session Manager (p. 581)
• Additional Sample IAM Policies for Session Manager (p. 584)

Enforce Document Permission Check for Default CLI Scenario

When you configure Session Manager for your account, the system creates an SSM document named
SSM-SessionManagerRunShell. This SSM document stores your requirements for whether session
data is saved in an Amazon S3 bucket or Amazon CloudWatch Logs log group, whether session data
is encrypted using AWS Key Management Service, and whether Run As support is enabled for your
sessions. For example:

{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",

579
 AWS Systems Manager User Guide
Getting Started with Session Manager

"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "MyBucketName",
"s3KeyPrefix": "MyBucketPrefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyLogGroupName",
"cloudWatchEncryptionEnabled": true,
"kmsKeyId": "MyKMSKeyID",
"runAsEnabled": true,
"runAsDefaultUser": "MyDefaultRunAsUser"
}
}

By default, if a user in your account has been granted permission in their IAM user policy to start
sessions, that user has access to this SSM document. This means that when they use the AWS CLI to
run the start-session command, and they do not specify a configuration document, the system
uses SSM-SessionManagerRunShell and launches the full interactive shell. The session starts even if
the user’s IAM policy doesn’t grant explicit permission to access the SSM-SessionManagerRunShell
document.

For example, the following command doesn’t specify a Session Manager configuration document.

aws ssm start-session --target i-02573cafcfEXAMPLE

The following example does specify the default Session Manager configuration document.

aws ssm start-session --document-name SSM-SessionManagerRunShell --target

i-02573cafcfEXAMPLE

For cases where the user doesn’t specify a document name in the start-session CLI command, you
can ensure that the user has been granted explicit access to this default configuration document. You
do this by adding the following condition element to the IAM policy that controls the user’s access to
sessions:

"Condition": {
"BoolIfExists": {
"ssm:SessionDocumentAccessCheck": "true"
}
}

With this condition element set to true in the user’s associated IAM policy, explicit access to SSM-
SessionManagerRunShell must be granted in the IAM policy. For example:

{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": "arn:aws:ssm:region:account-id:document/SSM-
SessionManagerRunShell"
}

This condition element applies only to the default SSM-SessionManagerRunShell configuration

document, and only when a user doesn’t specify a configuration document name in an CLI start-
session command. In other words, it ensures that the user has been granted access to SSM-
SessionManagerRunShell when they run the following command:

aws ssm start-session --target i-02573cafcfEXAMPLE

580
 AWS Systems Manager User Guide
Getting Started with Session Manager

For an example of specifying a Session Manager configuration document in a user’s IAM policy, see
Quickstart End User Policy for Session Manager (p. 581).

Other Scenarios

Using the default SSM-SessionManagerRunShell configuration document is the only case when a
document name can be omitted from the start-session CLI command. In other cases, the document
name must be specified, and the system checks whether the user has been granted explicit access to the
configuration document they specify.

For example, if a user specifies the name of a custom configuration document you have created, the
user’s IAM policy must grant them permission to access that document.

If a user runs a command to start a session using SSH, the user’s policy must grant them access to the
AWS-StartSSHSession configuration document.
Note
In order to start a session using SSH, configuration steps must be completed on both the target
instance and the user's local machine. For information, see (Optional) Enable SSH Connections
Through Session Manager (p. 597).

Quickstart Default IAM Policies for Session Manager

Use the following samples to help you create IAM policies that provide the most commonly needed
permissions for Session Manager access.
Note
You can also use an AWS KMS key policy to control which IAM users, IAM roles, and AWS
accounts are given access to your CMK. For information, see Overview of Managing Access to
Your AWS KMS Resources and Using Key Policies in AWS KMS in the AWS Key Management
Service Developer Guide.

Topics
• Quickstart End User Policy for Session Manager (p. 581)
• Quickstart Administrator Policy for Session Manager (p. 583)

Quickstart End User Policy for Session Manager

Use the following example to create an IAM end user policy for Session Manager. It provides end users
the ability start a session to a particular instance and the ability to terminate only their own sessions.
Refer to Additional Sample IAM Policies for Session Manager (p. 584) for examples of customizations
you might want to make to the policy.

Replace instance-id with the ID of the instance you want to grant access to, in the format
i-02573cafcfEXAMPLE. Replace region and account-id with your AWS Region and AWS Account ID.
For example, us-east-2 and 111122223333.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/instance-id"
]
},
{

581
 AWS Systems Manager User Guide
Getting Started with Session Manager

"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetDocument"
],
"Resource": [
"arn:aws:ssm:region:account-id:document/SSM-SessionManagerRunShell"
],
"Condition": {
"BoolIfExists": {
"ssm:SessionDocumentAccessCheck": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "key-name"
}
]
}

1
SSM-SessionManagerRunShell is the default name of the SSM document that Session Manager
creates to store your session configuration preferences. You can create a custom configuration
document and specify it in this policy instead. You can also specify the AWS-provided document AWS-
StartSSHSession for users who are starting sessions using SSH. For information about configuration
steps needed to support sessions using SSH, see (Optional) Enable SSH Connections Through Session
Manager (p. 597).

2
If you specify the condition element ssm:SessionDocumentAccessCheck as true, the
system checks that a user was granted explicit access to the configuration document SSM-
SessionManagerRunShell before allowing a session to start. For more information, see Enforce
Document Permission Check for Default CLI Scenario (p. 579).

About 'kms:GenerateDataKey

The kms:GenerateDataKey permission enables the creation of a data encryption

key that will be used to encrypt session data. If you will use AWS Key Management
Service (AWS KMS) encryption for your session data, replace key-name with the ARN
of the customer master key (CMK) you want to use, in the format arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE.

582
 AWS Systems Manager User Guide
Getting Started with Session Manager

If you will not use AWS KMS key encryption for your session data, remove the following content from the
policy:

,
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "key-name"
}

For information about AWS KMS and CMKs for encrypting session data, see Enable AWS KMS Key
Encryption of Session Data (Console) (p. 590).

Quickstart Administrator Policy for Session Manager

Use the following example to create an IAM administrator policy for Session Manager.
It provides administrators the ability to start a session to instances that are tagged with
Key=Finance,Value=WebServers, permission to create, update and delete preferences, and
permission to terminate only their own sessions. Refer to Additional Sample IAM Policies for Session
Manager (p. 584) for examples of customizations you might want to make to the policy.
Note
Update the tag/value pair Key=Finance,Value=WebServers with the tags applied to your
instances. Replace region and account-id with your AWS Region and AWS Account ID. For
example, us-east-2 and 111122223333.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/Finance": [
"WebServers"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:CreateDocument",
"ssm:UpdateDocument",
"ssm:GetDocument"

583
 AWS Systems Manager User Guide
Getting Started with Session Manager

],
"Resource": "arn:aws:ssm:region:account-id:document/SSM-SessionManagerRunShell"
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}

Additional Sample IAM Policies for Session Manager

Refer to the following example policies to help you create a custom IAM policy for any Session Manager
user access scenarios you want to support.

Topics
• Example 1: Restrict Access to Specific Instances (p. 584)
• Example 2: Restrict Access Based on Instance Tags (p. 585)
• Example 3: Allow a User to Terminate Only Sessions They Started (p. 586)
• Example 4: Allow Full (Administrative) Access to All Sessions (p. 586)

Example 1: Restrict Access to Specific Instances

You can restrict access to specific instances by creating an IAM user policy that includes the IDs of
the instances. In the following example, the user is allowed Session Manager access to three specific
instances only, and allowed to terminate only their sessions on those instances. If the user sends a
command to any other instance or attempts to terminate any other session, the command result will
include AccessDenied.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:us-east-2:123456789012:instance/i-1234567890EXAMPLE",
"arn:aws:ec2:us-east-2:123456789012:instance/i-abcdefghijEXAMPLE",
"arn:aws:ec2:us-east-2:123456789012:instance/i-0e9d8c7b6aEXAMPLE"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}

584
 AWS Systems Manager User Guide
Getting Started with Session Manager

Example 2: Restrict Access Based on Instance Tags

You can restrict access to instances based on specific Amazon EC2 tags. In the following example, the
user is allowed to start sessions (Effect: Allow, Action: ssm:StartSession) on any instance
(Resource: arn:aws:ec2:*:*:instance/*) with the condition that the instance is a Finance
WebServer (ssm:resourceTag/Finance: WebServer). If the user sends a command to an instance
that is not tagged or that has any tag other than Finance: WebServer, the command result will
include AccessDenied.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/Finance": [
"WebServers"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}

You can create IAM policies that enable a user to start sessions to instances that are tagged with multiple
tags. The following policy enables the user to start sessions to instances that have of both the specified
tags applied to them. If a user sends a command to an instance that is not tagged with both of these
tags, the command result will include AccessDenied.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:StartSession"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}

585
 AWS Systems Manager User Guide
Getting Started with Session Manager

}
}
]
}

For more information about creating IAM user policies, see Managed Policies and Inline Policies in the
IAM User Guide. For more information about tagging instances, see Tagging Your Amazon EC2 Resources
in the Amazon EC2 User Guide for Linux Instances (content applies to Windows and Linux instances). For
more information increasing your security posture against unauthorized root-level commands on your
instances, see Restrict Access to Root-Level Commands Through SSM Agent (p. 85)

Example 3: Allow a User to Terminate Only Sessions They Started

The following IAM policy lets a user view the IDs of all sessions in your account but interact with
instances only through sessions they started. A user who is assigned the following policy can't connect to
or terminate other users' sessions. The policy uses the variable {aws:username} to achieve this.

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ssm:DescribeSessions"
],
"Effect": "Allow",
"Resource": [
"*"
]
},
{
"Action": [
"ssm:TerminateSession"
],
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}

Example 4: Allow Full (Administrative) Access to All Sessions

The following IAM policy allows a user to fully interact with all instances and all sessions created by all
users for all instances. It should be granted only to an Administrator who needs full control over your
organization's Session Manager activities.

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ssm:StartSession",
"ssm:TerminateSession",
"ssm:ResumeSession",
"ssm:DescribeSessions",
"ssm:GetConnectionStatus"
],
"Effect": "Allow",
"Resource": [
"*"
]

586
 AWS Systems Manager User Guide
Getting Started with Session Manager

}
]
}

Step 4: Configure Session Preferences

An IAM user with administrator permissions can do the following:

• Enable Run As support for Linux instances. This makes it possible to start sessions using the credentials
of a specified operating system user instead of the credentials of a system-generated ssm-user
account that Session Manager can create on a managed instance.
• Configure Session Manager to use AWS KMS key encryption to provide additional protection to the
data transmitted between client machines and managed instances.
• Configure Session Manager to create and send session history logs to an Amazon Simple Storage
Service (Amazon S3) bucket or an Amazon CloudWatch Logs log group. The stored log data can then
be used to audit or report on the session connections made to your instances and the commands run
on them during the sessions.

Note
Before a user can update Session Manager preferences, they must have been granted the
specific permissions that will let them make these updates, if they do not possess them already.
Without these permissions, the user can't configure logging options or set other session
preferences for your account.

Topics
• Grant or Deny a User Permissions to Update Session Manager Preferences (p. 587)
• Enable Run As Support for Linux Instances (p. 588)
• Enable AWS KMS Key Encryption of Session Data (Console) (p. 590)
• Create Session Manager Preferences (AWS CLI) (p. 591)
• Update Session Manager Preferences (AWS CLI) (p. 592)

For information about using the Systems Manager console to configure options for logging session data,
see the following topics.

• Logging Session Data Using Amazon S3 (Console) (p. 608)

• Logging Session Data Using Amazon CloudWatch Logs (Console) (p. 609)

Grant or Deny a User Permissions to Update Session Manager Preferences

Account preferences are stored as SSM documents for each AWS Region. Before a user can update
account preferences for sessions in your account, they must be granted the necessary permissions to
access the type of SSM document where these preferences are stored. These permissions are granted
through an IAM policy.

Administrator policy to allow preferences to be created and updated

An administrator can have the following policy to create and update preferences at any time. The
following policy allows permission to access and update the SSM-SessionManagerRunShell
document in the us-east-2 account 123456789012.

{
"Version": "2012-10-17",
"Statement": [
{

587
 AWS Systems Manager User Guide
Getting Started with Session Manager

"Action": [
"ssm:CreateDocument",
"ssm:UpdateDocument",
"ssm:DeleteDocument"
],
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:us-east-2:123456789012:document/SSM-SessionManagerRunShell"
]
}
]
}

User policy to prevent preferences from being updated

Use the following policy to prevent end users in your account from updating or overriding any Session
Manager preferences.

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ssm:CreateDocument",
"ssm:UpdateDocument",
"ssm:DeleteDocument"
],
"Effect": "Deny",
"Resource": [
"arn:aws:ssm:us-east-2:123456789012:document/SSM-SessionManagerRunShell"
]
}
]
}

Enable Run As Support for Linux Instances

By default, sessions are launched using the credentials of a system-generated ssm-user account that is
created on a managed instance. (On Linux machines, this account is added to /etc/sudoers/.) You can
instead launch sessions using the credentials of an operating system account. Session Manager provides
two methods for specifying the operating system account to use.

Method 1: Tag an IAM user or role (recommended)

You can specify the operating system user account that is used to start sessions by tagging an IAM user
or associated role with the AWS-provided key name SSMSessionRunAs, and specifying the OS user
name as its value. For example, if the OS user account name is DevRoleLogin, the corresponding tag to
use is SSMSessionRunAs = DevRoleLogin.

Using this method, you could specify a different OS account name for each IAM user or role you tag, or
use the same OS user name for them all.

For more information about tagging IAM entities, see the following topics:

• Tagging IAM Entities in the IAM User Guide

• Add Tags to Manage Your AWS IAM Users and Roles on the AWS Security Blog

Method 2: Specify an OS user name in Session Manager preferences

When you configure Session Manager preferences in the console or by using the AWS CLI, you can specify
the operating system user name to start sessions with.

588
 AWS Systems Manager User Guide
Getting Started with Session Manager

Using this method, all sessions are run by the same OS user for all the IAM users in your account who
connect to the instance using Session Manager.

How It Works

If you enable Run As support for sessions, the system checks for access permissions as follows:

1. For the user who is starting the session, has their IAM user account or role been tagged with
SSMSessionRunAs = os-user-account-name?

If Yes, does the user name exist on the instance? If it does, start the session. If it does not, do not allow
a session to start.

If the IAM user's account or role has not been tagged with SSMSessionRunAs = os-user-
account-name, continue to step 2.
2. If the IAM user's account or role hasn't been tagged with SSMSessionRunAs = os-user-account-
name, has an OS user name been specified in the AWS account's Session Manager preferences?

If Yes, does the user name exist on the instance? If it does, start the session. If it does not, do not allow
a session to start.

At this point, Session Manager does not fall back on the default ssm-user account. In other words,
enabling Run As support prevents sessions from being started using an ssm-user account on an
instance.

To enable Run As support for Linux instances

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. Choose the Preferences tab, and then choose Edit.
4. Select the check box next to Enable Run As support for Linux instances.
5. Do one of the following:

• Choose the IAM console link. In the navigation pane, choose either Users or Roles. Choose the
entity (user or role) to add tags to, and then choose the Tags tab. Enter SSMSessionRunAs for
the key name. Enter the name of a user account on your target instance for the key value. Choose
Save changes.

For example:

• For (Optional) Enter an operating system user name for starting sessions, enter the name of the
operating system user account on the target instance that you want to use to start sessions.
6. Choose Save.

589
 AWS Systems Manager User Guide
Getting Started with Session Manager

Enable AWS KMS Key Encryption of Session Data (Console)

Use AWS Key Management Service (AWS KMS) to create and manage keys. With AWS KMS, you can
control the use of encryption across a wide range of AWS services and in your applications. You can
specify that session data transmitted between your Amazon EC2 instances and the local machines of
users in your AWS account is encrypted using AWS KMS key encryption. (This is in addition to the TLS 1.2
encryption that AWS already provides by default.) AWS KMS key encryption for sessions is accomplished
using a customer master key (CMK) that is created in AWS KMS.
Note
You must enable AWS KMS encryption in order to reset passwords on your managed instances
from the Systems Manager console. For more information, see Reset a Password on a Managed
Instance (p. 565).

You can use a key that you created in your AWS account. You can also use a key that was created in a
different AWS account. The creator of the key in a different AWS account must provide you with the
permissions needed to use the key.

After you enable AWS KMS key encryption for your session data, both the users who start sessions and
the instances that they connect to must have permission to use the key. You provide permission to use
the CMK with Session Manager through IAM policies. For information, see the following topics:

• Add CMK permissions for users in your account: Quickstart Default IAM Policies for Session
Manager (p. 581).
• Add CMK permissions for instances in your account: Step 2: Verify or Create an IAM Instance Profile
with Session Manager Permissions (p. 573).

For more information about creating and managing AWS KMS keys, see the AWS Key Management Service
Developer Guide.

For information about using the AWS CLI to enable AWS KMS key encryption of session data in your
account, see Create Session Manager Preferences (AWS CLI) (p. 591) or Update Session Manager
Preferences (AWS CLI) (p. 592).
Note
There is a charge to use CMKs. For information, see AWS Key Management Service pricing.

To enable AWS KMS key encryption of session data (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. Choose the Preferences tab, and then choose Edit.
4. Select the check box next to Key Management Service (KMS).
5. Do one of the following:

• Choose the button next to Select an AWS KMS key in my current account, then select a key from
the list.

-or-

Choose the button next to Enter a KMS key alias or KMS key ARN. Manually enter an AWS KMS
key alias for a key created in your current account, or enter the key ARN for a key in another
account. For example:
• Key alias: alias/my-kms-key-alias
• Key ARN: arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE

590
 AWS Systems Manager User Guide
Getting Started with Session Manager

-or-

Choose Create new key to create a new CMK in your account. After you create the new key, return
to the Preferences tab and select the key for encrypting session data in your account.

For more information about sharing keys, see Allowing External AWS Accounts to Access a CMK in
the AWS Key Management Service Developer Guide.
6. Choose Save.

Create Session Manager Preferences (AWS CLI)

The following procedure describes how to use the AWS CLI and the create-document command to
create Session Manager preferences for your account in the selected AWS Region. Use Session Manager
preferences to specify options for logging session data in an Amazon S3 bucket or Amazon CloudWatch
Logs log group. You can also use Session Manager preferences to encrypt your session data.

For information about using the CLI to update existing Session Manager preferences, see Update Session
Manager Preferences (AWS CLI) (p. 592).

To create Session Manager preferences (AWS CLI)

1. Create a JSON file on your local machine with a name such as SessionManagerRunShell.json,
and then paste the following content into it:

{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "",
"s3KeyPrefix": "",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "",
"cloudWatchEncryptionEnabled": true,
"kmsKeyId": "",
"runAsEnabled": "",
"runAsDefaultUser": ""
}
}

2. Specify where you want to send session data. You can specify an S3 bucket name (with an optional
prefix) or a CloudWatch Logs log group name. If you want to further encrypt data between local
client and EC2 instances, provide the AWS KMS key to use for encryption. For example:

{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "MyBucketName",
"s3KeyPrefix": "MyBucketPrefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyLogGroupName",
"cloudWatchEncryptionEnabled": true,
"kmsKeyId": "MyKMSKeyID",
"runAsEnabled": true,
"runAsDefaultUser": "MyDefaultRunAsUser"
}

591
 AWS Systems Manager User Guide
Getting Started with Session Manager

Note
If you do not want to encrypt the session log data, change "true" to "false" for
s3EncryptionEnabled.
If you aren't sending logs to either an S3 bucket or a CloudWatch Logs log group, don't
want to encrypt active session data, or don't want to enable Run As support for the sessions
in your account, you can delete the lines for those options. Make sure the last line in the
"inputs" section does not end with a comma.
If you add a AWS KMS key ID to encrypt your session data, both the users who start sessions
and the instances that they connect to must have permission to use the key. You provide
permission to use the CMK with Session Manager through IAM policies. For information, see
the following topics:

• Add CMK permissions for users in your account: Quickstart Default IAM Policies for
Session Manager (p. 581).
• Add CMK permissions for instances in your account: Step 2: Verify or Create an IAM
Instance Profile with Session Manager Permissions (p. 573).
3. Save the file.
4. In the directory where you created the JSON file, run the following command:

aws ssm create-document --name SSM-SessionManagerRunShell --content "file://

SessionManagerRunShell.json" --document-type "Session" --document-format JSON

Important
Be sure to include file:// before the file name. It is required in this command.

If successful, the command returns output similar to the following:

{
"DocumentDescription": {
"Status": "Creating",
"Hash": "ce4fd0a2ab9b0fae759004ba603174c3ec2231f21a81db8690a33eb66EXAMPLE",
"Name": "SSM-SessionManagerRunShell",
"Tags": [],
"DocumentType": "Session",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "1",
"HashType": "Sha256",
"CreatedDate": 1547750660.918,
"Owner": "111122223333",
"SchemaVersion": "1.0",
"DefaultVersion": "1",
"DocumentFormat": "JSON",
"LatestVersion": "1"
}
}

Update Session Manager Preferences (AWS CLI)

The following procedure describes how to use the AWS CLI and the update-document command to make
changes to the Session Manager preferences for your account in the selected AWS Region. Use Session
Manager preferences to specify options for logging session data in an Amazon S3 bucket or Amazon
CloudWatch Logs log group. You can also use Session Manager preferences to encrypt your session data.

592
 AWS Systems Manager User Guide
Getting Started with Session Manager

To update Session Manager preferences (AWS CLI)

1. Create a JSON file on your local machine with a name such as SessionManagerRunShell.json,
and then paste the following content into it:

{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "",
"s3KeyPrefix": "",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "",
"cloudWatchEncryptionEnabled": true,
"kmsKeyId": "",
"runAsEnabled": "",
"runAsDefaultUser": ""
}
}

2. Specify where you want to send session data. You can specify an S3 bucket name (with an optional
prefix) or a CloudWatch Logs log group name. If you want to further encrypt data between local
client and EC2 instances, provide the AWS KMS key to use for encryption. For example:

{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "MyBucketName",
"s3KeyPrefix": "MyBucketPrefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyLogGroupName",
"cloudWatchEncryptionEnabled": true,
"kmsKeyId": "MyKMSKeyID",
"runAsEnabled": true,
"runAsDefaultUser": "MyDefaultRunAsUser"
}
}

Note
If you do not want to encrypt the session log data, change "true" to "false" for
s3EncryptionEnabled.
If you aren't sending logs to either an S3 bucket or a CloudWatch Logs log group, don't
want to encrypt active session data, or don't want to enable Run As support for the sessions
in your account, you can delete the lines for those options. Make sure the last line in the
"inputs" section does not end with a comma.
If you add a AWS KMS key ID to encrypt your session data, both the users who start sessions
and the instances that they connect to must have permission to use the key. You provide
permission to use the CMK with Session Manager through IAM policies. For information, see
the following topics:

• Add CMK permissions for users in your account: Quickstart Default IAM Policies for
Session Manager (p. 581).
• Add CMK permissions for instances in your account: Step 2: Verify or Create an IAM
Instance Profile with Session Manager Permissions (p. 573).
3. Save the file.
4. In the directory where you created the JSON file, run the following command:

593
 AWS Systems Manager User Guide
Getting Started with Session Manager

aws ssm update-document --name "SSM-SessionManagerRunShell" --content "file://

SessionManagerRunShell.json" --document-version "\$LATEST"

Important
Be sure to include file:// before the file name. It is required in this command.

If successful, the command returns output similar to the following:

{
"DocumentDescription": {
"Status": "Updating",
"Hash": "ce4fd0a2ab9b0fae759004ba603174c3ec2231f21a81db8690a33eb66EXAMPLE",
"Name": "SSM-SessionManagerRunShell",
"Tags": [],
"DocumentType": "Session",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "2",
"HashType": "Sha256",
"CreatedDate": 1537206341.565,
"Owner": "111122223333",
"SchemaVersion": "1.0",
"DefaultVersion": "1",
"DocumentFormat": "JSON",
"LatestVersion": "2"
}
}

Step 5: (Optional) Use PrivateLink to Set Up a VPC Endpoint for

Session Manager
You can further improve the security posture of your managed instances by configuring AWS Systems
Manager to use an interface VPC endpoint. Interface endpoints are powered by AWS PrivateLink, a
technology that enables you to privately access Amazon EC2 and Systems Manager APIs by using private
IP addresses.

PrivateLink restricts all network traffic between your managed instances, Systems Manager, and Amazon
EC2 to the Amazon network. (Managed instances don't have access to the internet.) Also, you don't need
an internet gateway, a NAT device, or a virtual private gateway.

In addition to the three endpoints required to use PrivateLink with Systems Manager, you can create a
fourth, com.amazonaws.region.ssmmessages, for use with Session Manager.

For more information, see (Optional) Create a Virtual Private Cloud Endpoint (p. 36).

Step 6: (Optional) Disable or Enable ssm-user Account

Administrative Permissions
When a version of SSM Agent that supports Session Manager starts on an instance, it creates a user
account with root or administrator privileges called ssm-user. On Linux machines, the account is added to
/etc/sudoers. On Windows machines, it is added to the Administrators group. Sessions are launched
using the credentials of this user account.

594
 AWS Systems Manager User Guide
Getting Started with Session Manager

If you want to prevent Session Manager users from running administrative commands on an instance,
you can update its ssm-user permissions. You can also restore these permissions after they have been
removed.

Topics
• Managing ssm-user sudo Account Permissions on Linux (p. 595)
• Managing ssm-user Administrator Account Permissions on Windows Server (p. 596)

Managing ssm-user sudo Account Permissions on Linux

Use one of the following procedures to disable or enable the ssm-user account sudo permissions on
Linux instances:

Use Run Command to modify ssm-user sudo permissions (console)

• Use the procedure in Running Commands from the Console (p. 619) with the following values:

• For Command document, choose AWS-RunShellScript.

• To remove sudo access, in the Command parameters area, paste the following in the Commands
box:

cd /etc/sudoers.d
echo "#User rules for ssm-user" > ssm-agent-users

-or-

To restore sudo access, in the Command parameters area, paste the following in the Commands
box:

cd /etc/sudoers.d
echo "ssm-user ALL=(ALL) NOPASSWD:ALL" > ssm-agent-users

Use the command line to modify ssm-user sudo permissions (AWS CLI)

1. Connect to the instance and run the following command:

sudo -s

2. Change the working directory using the following command:

cd /etc/sudoers.d

3. Open the file named ssm-agent-users for editing.

4. To remove sudo access, delete the following line:

ssm-user ALL=(ALL) NOPASSWD:ALL

-or-

To restore sudo access, add the following line:

ssm-user ALL=(ALL) NOPASSWD:ALL

5. Save the file.

595
 AWS Systems Manager User Guide
Getting Started with Session Manager

Managing ssm-user Administrator Account Permissions on Windows Server

Use one of the following procedures to disable or enable the ssm-user account Administrator
permissions on Windows Server instances:

Use Run Command to modify Administrator permissions (console)

• Use the procedure in Running Commands from the Console (p. 619) with the following values:

For Command document, choose AWS-RunPowerShellScript.

To remove administrative access, in the Command parameters area, paste the following in the
Commands box:

net localgroup "Administrators" "ssm-user" /delete

-or-

To restore administrative access, in the Command parameters area, paste the following in the
Commands box:

net localgroup "Administrators" "ssm-user" /add

Use the PowerShell or Command Prompt window to modify Administrator permissions

1. Connect to the instance and open the PowerShell or Command Prompt window.
2. To remove administrative access, run the following command:

net localgroup "Administrators" "ssm-user" /delete

-or-

To restore administrative access, run the following command:

net localgroup "Administrators" "ssm-user" /add

Use the Windows console to modify Administrator permissions

1. Connect to the instance and open the PowerShell or Command Prompt window.
2. From the command line, run lusrmgr.msc to open the Local Users and Groups console.
3. Open the Users directory, and then open ssm-user.
4. On the Member Of tab, do one of the following:

• To remove administrative access, select Administrators, and then choose Remove.

-or-

To restore administrative access, type Administrators in the text box, and then choose Add.
5. Choose OK.

596
 AWS Systems Manager User Guide
Getting Started with Session Manager

Step 7: (Optional) Enable SSH Connections Through Session

Manager
You can enable users in your AWS account to use the AWS CLI to establish Secure Shell (SSH) connections
to instances using Session Manager. Users who connect using SSH can also copy files between their local
machines and managed instances using Secure Copy Protocol (SCP). You can use this functionality to
connect to instances without opening inbound ports or maintaining bastion hosts. You can also choose
to explicity disable SSH connections to your instances through Session Manager.

To enable SSH connections through Session Manager

1. On the managed instance to which you want to enable SSH connections, do the following:

• Ensure that SSH is running on the instance. (You can close inbound ports on the instance.)
• Ensure that SSM Agent version 2.3.672.0 or later is installed on the instance.

For information about installing or updating SSM Agent on an instance, see the following topics:
• Installing and Configuring SSM Agent on Windows Instances (p. 65).
• Installing and Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68)
• Install SSM Agent for a Hybrid Environment (Windows) (p. 48)
• Install SSM Agent for a Hybrid Environment (Linux) (p. 50)
Note
To use Session Manager with on-premises servers and virtual machines (VMs) that you
activated as managed instances, you must use the Advanced-Instances Tier. For more
information about advanced instances, see (Optional) Enable the Advanced-Instances
Tier (p. 53).
2. On the local machine from which you want to connect to a managed instance using SSH, do the
following:

• Ensure that version 1.1.23.0 or later of the Session Manager plugin is installed.

For information about installing the Session Manager plugin, see (Optional) Install the Session
Manager Plugin for the AWS CLI (p. 599).
• Update the SSH configuration file to enable running a proxy command that starts a Session
Manager session and transfer all data through the connection.

Linux
Tip
The SSH configuration file is typically located at ~/.ssh/config.

Add the following to the configuration file on the local machine:

# SSH over Session Manager

host i-* mi-*
ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-
StartSSHSession --parameters 'portNumber=%p'"

Windows
Tip
The SSH configuration file is typically located at C:\Users\username\.ssh\config.

Add the following to the configuration file on the local machine:

# SSH over Session Manager

597
 AWS Systems Manager User Guide
Working with Session Manager

host i-* mi-*

ProxyCommand C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe "aws
ssm start-session --target %h --document-name AWS-StartSSHSession --parameters
portNumber=%p"

• Create or verify that you have a Privacy Enhanced Mail Certificate (a PEM file), or at minimum a
public key, to use when establishing connections to managed instances. (You specify the path to
the certificate or key as part of the command to start a session. For information about starting a
session using SSH, see Starting a Session (SSH) (p. 605).)

To disable SSH connections through Session Manager

• Option 1: Open the IAM console at https://console.aws.amazon.com/iam/. In the navigation pane,

choose Policies, and then update the permissions policy for the user or role to block from starting
Session Manager sessions. For example, prepare to modify the user quickstart policy you created in
Quickstart End User Policy for Session Manager (p. 581). Add the following element to the policy,
or replace any permissions that allow a user to start a session:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor1",
"Effect": "Deny",
"Action": "ssm:StartSession",
"Resource": "arn:aws:ssm:*:*:document/AWS-StartSSHSession"
}
]
}

Option 2: Attach an inline policy to a user policy by using the AWS Management Console, the AWS
CLI, or the AWS API.

Using the method of your choice, attach the policy statement in Option 1 to the policy for an AWS
user, group, or role.

For information, see Adding and Removing IAM Identity Permissions in the IAM User Guide,

Working with Session Manager

You can use the AWS Systems Manager console or the AWS CLI to start sessions that connect you to
the Amazon EC2 instances your system administrator has granted you access to using AWS Identity and
Access Management (IAM) policies. Depending on your permissions, you can also view information about
sessions, resume inactive sessions that have not timed out, and terminate sessions.

For more information about sessions, see What Is a Session? (p. 570)

Topics
• (Optional) Install the Session Manager Plugin for the AWS CLI (p. 599)
• Start a Session (p. 604)
• Terminate a Session (p. 606)
• View Session History (p. 607)

598
 AWS Systems Manager User Guide
Working with Session Manager

(Optional) Install the Session Manager Plugin for the AWS CLI
If you want to use the AWS CLI to start and terminate sessions that connect you to your managed
instances, you must first install the Session Manager plugin on your local machine. The plugin can be
installed on supported versions of Microsoft Windows, macOS, Linux, and Ubuntu Server.

Use the Latest Version of the Session Manager Plugin

The plugin is updated occasionally with enhanced functionality. We recommend that you regularly
ensure you are using the latest version of the plugin. For more information, see Session Manager Plugin
Latest Version and Release History (p. 603).

Installation Prerequisite

AWS CLI version 1.16.12 or later must be installed on your local machine in order to use the Session
Manager plugin.

Topics
• Install the Session Manager Plugin on Windows (p. 599)
• Install and Uninstall the Session Manager Plugin on macOS (p. 600)
• Install Session Manager Plugin on Linux (p. 601)
• Install the Session Manager Plugin on Ubuntu Server (p. 601)
• Verify the Session Manager Plugin Installation (p. 601)
• (Optional) Enable Session Manager Plugin Logging (p. 602)
• Session Manager Plugin Latest Version and Release History (p. 603)

Install the Session Manager Plugin on Windows

You can install the Session Manager plugin on Microsoft Windows Vista or later using the standalone
installer.

When updates are released, you must repeat the installation process to get the latest version of the
Session Manager plugin.
Note
For best results, we recommend starting sessions on Windows clients using the Windows
PowerShell application version 5 or later. On Microsoft Windows 10, the Command Prompt also
provides reliable support for Session Manager operations.

To install the Session Manager plugin using the EXE installer

1. Download the installer using the following URL:

https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/
SessionManagerPluginSetup.exe

2. Run the downloaded installer and follow the on-screen the instructions.

Leave the install location box blank to install the plugin to the default directory:

• C:\%PROGRAMFILES%\Amazon\SessionManagerPlugin\bin\
3. Verify that the installation was successful. For information, see Verify the Session Manager Plugin
Installation (p. 601).
Note
If Windows is unable to find the executable, you might need to re-open the command
prompt or add the installation directory to your PATH environment variable manually.

599
 AWS Systems Manager User Guide
Working with Session Manager

For information, see the troubleshooting topic Session Manager Plugin Not Automatically
Added to Command Line Path (Windows) (p. 612).

Install and Uninstall the Session Manager Plugin on macOS

You can install the Session Manager plugin on macOS using the bundled installer.
Important
The bundled installer does not support installing to paths that contain spaces.

To install the Session Manager plugin using the bundled installer (macOS)

1. Download the bundled installer:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/
sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"

2. Unzip the package:

unzip sessionmanager-bundle.zip

3. Run the install command:

sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/

bin/session-manager-plugin

Note
The plugin requires Python 2.6.5 or later or Python 3.3. By default, the install script runs
under the system default version of Python. If you have installed an alternative version of
Python and want to use that to install the Session Manager plugin, run the install script
with that version by absolute path to the Python executable. For example:

sudo /usr/local/bin/python3.6 sessionmanager-bundle/install -i /usr/local/

sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

The installer installs the Session Manager plugin at /usr/local/sessionmanagerplugin and

creates the symlink session-manager-plugin in the /usr/local/bin directory. This eliminates
the need to specify the install directory in the user's $PATH variable.

To see an explanation of the -i and -b options, use the -h option:

./sessionmanager-bundle/install -h

4. Verify that the installation was successful. For information, see Verify the Session Manager Plugin
Installation (p. 601).

Note
If you ever want to uninstall the plugin, run the following two commands, one at a time:

sudo rm -rf /usr/local/sessionmanagerplugin

sudo rm /usr/local/bin/session-manager-plugin

600
 AWS Systems Manager User Guide
Working with Session Manager

Install Session Manager Plugin on Linux

1. Download the Session Manager plugin RPM package:

• 64-bit:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/
session-manager-plugin.rpm" -o "session-manager-plugin.rpm"

• 32-bit:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_32bit/
session-manager-plugin.rpm" -o "session-manager-plugin.rpm"

2. Run the install command:

sudo yum install -y session-manager-plugin.rpm

3. Verify that the installation was successful. For information, see Verify the Session Manager Plugin
Installation (p. 601).

Note
If you ever want to uninstall the plugin, run sudo yum erase session-manager-plugin -
y

Install the Session Manager Plugin on Ubuntu Server

1. Download the Session Manager plugin deb package:

• 64-bit:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/
session-manager-plugin.deb" -o "session-manager-plugin.deb"

• 32-bit:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_32bit/
session-manager-plugin.deb" -o "session-manager-plugin.deb"

2. Run the install command:

sudo dpkg -i session-manager-plugin.deb

3. Verify that the installation was successful. For information, see Verify the Session Manager Plugin
Installation (p. 601).

Note
If you ever want to uninstall the plugin, run sudo dpkg -r session-manager-plugin

Verify the Session Manager Plugin Installation

Run the following commands to verify that the Session Manager plugin installed successfully:

session-manager-plugin

If the installation was successful, the following message is returned:

601
 AWS Systems Manager User Guide
Working with Session Manager

The Session Manager plugin is installed successfully. Use the AWS CLI to start a session.

You can also test the installation by running the following command in the AWS CLI:
Note
This command will work only if your Session Manager administrator has granted you the
necessary IAM permissions to access the target instance using Session Manager.

aws ssm start-session --target id-of-an-instance-you-have-permissions-to-access

(Optional) Enable Session Manager Plugin Logging

The Session Manager plugin includes an option to enable logging for sessions that you run. By default,
logging is disabled.

If you enable logging, the Session Manager plugin creates log files for both application activity
(session-manager-plugin.log) and errors (errors.log) on your local machine.

Topics
• Enable Logging for the Session Manager Plugin (Windows) (p. 602)
• Enable Logging for the Session Manager Plugin (Linux and macOS) (p. 602)

Enable Logging for the Session Manager Plugin (Windows)

1. Locate the seelog.xml.template file for the plugin.

The default location is C:\%PROGRAMDATA%\Amazon\SessionManagerPlugin

\seelog.xml.template.
2. Change the name of the file to seelog.xml.
3. Open the file and change minlevel="off" to minlevel="info" or minlevel="debug".
Note
By default, log entries about opening a data channel and reconnecting sessions are
recorded at the INFO level. Data flow (packets and acknowledgement) entries are recorded
at the DEBUG level.
4. Change other configuration options you want to modify. Options you can change include:

• Debug level: You can change the debug level from formatid="fmtinfo" to outputs
formatid="fmtdebug".
• Log file options: You can make changes to the log file options, including where the logs are
stored, with the exception of the log file names.
Important
Do not change the file names or logging will not work correctly.

<rollingfile type="size" filename="C:\%PROGRAMDATA%\Amazon\SessionManagerPlugin\Logs

\session-manager-plugin.log" maxsize="30000000" maxrolls="5"/>
<filter levels="error,critical" formatid="fmterror">
<rollingfile type="size" filename="C:\%PROGRAMDATA%\Amazon\SessionManagerPlugin\Logs
\errors.log" maxsize="10000000" maxrolls="5"/>

5. Save the file.

Enable Logging for the Session Manager Plugin (Linux and macOS)

1. Locate the seelog.xml.template file for the plugin.

602
 AWS Systems Manager User Guide
Working with Session Manager

The default location is /usr/local/sessionmanagerplugin/seelog.xml.template.

2. Change the name of the file to seelog.xml.
3. Open the file and change minlevel="off" to minlevel="info" or minlevel="debug".
Note
By default, log entries about opening data channels and reconnecting sessions are recorded
at the INFO level. Data flow (packets and acknowledgement) entries are recorded at the
DEBUG level.
4. Change other configuration options you want to modify. Options you can change include:

• Debug level: You can change the debug level from formatid="fmtinfo" to outputs
formatid="fmtdebug"
• Log file options: You can make changes to the log file options, including where the logs are
stored, with the exception of the log file names.
Important
Do not change the file names or logging will not work correctly.

<rollingfile type="size" filename="/usr/local/sessionmanagerplugin/logs/session-

manager-plugin.log" maxsize="30000000" maxrolls="5"/>
<filter levels="error,critical" formatid="fmterror">
<rollingfile type="size" filename="/usr/local/sessionmanagerplugin/logs/errors.log"
maxsize="10000000" maxrolls="5"/>

Important
If you use the specified default directory for storing logs, you must either run session
commands using sudo or give the directory where the plugin is installed full read and
write permissions. To bypass these restrictions, change the location where logs are stored.
5. Save the file.

Session Manager Plugin Latest Version and Release History

Your local machine must be running a supported version of the Session Manager plugin. If you are
running an earlier version, your Session Manager operations might not succeed.

The current minimum supported version is 1.1.17.0.

The latest release is version 1.1.33.0.

To see if you have the latest version, run the following command in the AWS CLI:
Note
The command returns results only if the plugin is located in the default installation directory for
your operating system type. You can also check the version in the contents of the VERSION file
in the directory where you have installed the plugin.

session-manager-plugin --version

The following table lists all releases of the Session Manager plugin and the features and enhancements
included with each version.

Version Release date Details

1.1.33.0 September 26, 2019 Enhancement: (Port forwarding sessions only) Send a disconnect
signal to the server when the client drops the TCP connection.

603
 AWS Systems Manager User Guide
Working with Session Manager

Version Release date Details

1.1.31.0 September 6, 2019 Enhancement: Update to keep port forwarding session open
until remote server closes the connection.

1.1.26.0 July 30, 2019 Enhancement: Limit the rate of data transfer during a session.

1.1.23.0 July 9, 2019 Enhancement: Add support for running SSH sessions using
Session Manager.

1.1.17.0 April 4, 2019 Enhancement: Add support for further encryption of session
data using AWS Key Management Service (AWS KMS).

1.0.37.0 September 20, 2018 Enhancement: Bug fix for Windows version.

1.0.0.0 September 11, 2018 Initial release of the Session Manager plugin.

Start a Session
You can use the AWS Systems Manager console, the AWS CLI, or SSH to start a session.

Topics
• Starting a Session (Console) (p. 604)
• Starting a Session (AWS CLI) (p. 605)
• Starting a Session (SSH) (p. 605)
• Starting a Session (Port Forwarding) (p. 605)
• Starting a Session (Interactive Commands) (p. 606)

Starting a Session (Console)

You can use the AWS Systems Manager console to start a session with an instance in your account.

To start a session (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Session Manager in the navigation pane.
3. Choose Start session.
4. For Target instances, choose the option button to the left of the instance you want to connect to.

If an instance you want to connect to is not in the list, or is listed but an error message reports, "The
instance you selected is not configured to use Session Manager," see Instance Not Available or Not
Configured for Session Manager (p. 611) for troubleshooting steps.
5. Choose Start session.

After the connection is made, you can run bash commands (Linux) or PowerShell commands (Windows)
as you would through any other connection type.

604
 AWS Systems Manager User Guide
Working with Session Manager

Starting a Session (AWS CLI)

To start a session using the AWS CLI, run the following command:
Note
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed
on your local machine. For information, see (Optional) Install the Session Manager Plugin for the
AWS CLI (p. 599).

aws ssm start-session --target instance-id

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its
Session Manager capability. For example: i-02573cafcfEXAMPLE.

For information about other options you can use with the start-session command, see start-session in
the AWS Systems Manager section of the AWS CLI Command Reference.

Starting a Session (SSH)

To start a session using SSH, run the following command:
Note
To start a session using SSH, your target instance must be configured to support SSH
connections. For more information, see (Optional) Enable SSH Connections Through Session
Manager (p. 597).

ssh -i /path/my-key-pair.pem username@instance-id

/path/my-key-pair.pem represents the path to your Privacy Enhanced Mail (PEM) certificate.

username@instance-id represents the user name you use to connect to the instance, and the instance
ID. For example: JaneDoe@i-02573cafcfEXAMPLE.
Tip
When you start a session using SSH, you can copy local files to the target instance using the
following command format.

scp -i /path/my-key-pair.pem /path/SampleFile.txt username@instance-id:~

For information about other options you can use with the start-session command, see start-session in
the AWS Systems Manager section of the AWS CLI Command Reference.

Starting a Session (Port Forwarding)

To start a port forwarding session, run the following command from the CLI:
Note
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed
on your local machine. For information, see (Optional) Install the Session Manager Plugin for the
AWS CLI (p. 599).

aws ssm start-session --target instance-id --document-name AWS-StartPortForwardingSession

--parameters '{"portNumber":["80"], "localPortNumber":["56789"]}'

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its
Session Manager capability. For example: i-02573cafcfEXAMPLE.

portNumber represents the remote port on the instance where traffic should be redirected to. . For
example: 3389. If this parameter is not specified, Session Manager assumes 80 as the default remote
port.

605
 AWS Systems Manager User Guide
Working with Session Manager

localPortNumber represents the local port on the client where traffic should be redirected to. For
example: 56789.

For information about other options you can use with the start-session command, see start-session in
the AWS Systems Manager section of the AWS CLI Command Reference.

Starting a Session (Interactive Commands)

To start an Interactive Command session, run the following command::
Note
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed
on your local machine. For information, see (Optional) Install the Session Manager Plugin for the
AWS CLI (p. 599).

aws ssm start-session --target instance-id --document-name

TestInteractiveCommandSessionDocument --parameters '{"logpath":["/var/log/amazon/ssm/
amazon-ssm-agent.log"]}'

instance-id represents of the ID of an instance configured for use with AWS Systems Manager and its
Session Manager capability. For example: i-02573cafcfEXAMPLE.

For information about other options you can use with the start-session command, see start-session in
the AWS Systems Manager section of the AWS CLI Command Reference.

Related Content

Port Forwarding Using AWS Systems Manager Session Manager on the AWS News Blog.

Terminate a Session
You can use the AWS Systems Manager console or the AWS CLI to terminate a session that you started
to connect to an instance in your account. If there is no user activity after 20 minutes, a session is
terminated. After a session is terminated, it can't be resumed.

Topics
• Terminating a Session (Console) (p. 606)
• Terminating a Session (AWS CLI) (p. 606)

Terminating a Session (Console)

You can use the AWS Systems Manager console to terminate a session with an instance in your account.

To terminate a session (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. For Sessions, choose the option button to the left of the session you want to terminate.
4. Choose Terminate.

Terminating a Session (AWS CLI)

To terminate a session using the AWS CLI, run the following command:
Note
To use the AWS CLI to run session commands, the Session Manager plugin must also be installed
on your local machine. For information, see (Optional) Install the Session Manager Plugin for the
AWS CLI (p. 599).

606
 AWS Systems Manager User Guide
Working with Session Manager

aws ssm terminate-session --session-id session-id

session-id represents of the ID of an active Session Manager session that you want to end
permanently.

For more information about the terminate-session command, see terminate-session in the AWS Systems
Manager section of the AWS CLI Command Reference.

View Session History

You can use the AWS Systems Manager console or the AWS CLI to view information about sessions in
your account. In the console, you can view session details such the following:

• The ID of the session

• Which user connected to an instance through a session
• The ID of the instance
• When the session began and ended
• The status of the session
• The location specified for storing session logs (if enabled)

Using the AWS CLI, you can view a list of sessions in your account, but not the additional details that are
available in the console.

For information about auditing and logging session history information, see Auditing and Logging
Session Activity (p. 608).

Topics
• Viewing Session History (Console) (p. 607)
• Viewing Session History (AWS CLI) (p. 607)

Viewing Session History (Console)

You can use the AWS Systems Manager console to view details about the sessions in your account.

To view session history (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. Choose Start session.
4. Choose the Session history tab.

Viewing Session History (AWS CLI)

To view a list of sessions in your account using the AWS CLI, run the following command:

aws ssm describe-sessions --state History

For information about other options you can use with the describe-sessions command, see describe-
sessions in the AWS Systems Manager section of the AWS CLI Command Reference.

607
 AWS Systems Manager User Guide
Auditing and Logging Session Activity

Auditing and Logging Session Activity

In addition to providing information about current and completed sessions in the Systems Manager
console, Session Manager provides you with options for auditing and logging session activity in your
AWS account. This allows you to do the following:

• Create and store session logs for archival purposes.

• Generate a report showing details of every connection made to your instances using Session Manager
over the past 30 days.
• Generate notifications of session activity in your AWS account, such as Amazon Simple Notification
Service (Amazon SNS) notifications.
• Automatically initiate another action on an AWS resource as the result of session activity, such as
running an AWS Lambda function, starting an AWS CodePipeline pipeline, or running an AWS Systems
Manager Run Command document.

Note
If you are using Windows Server 2012 or earlier, the data in your logs might not be formatted
optimally. We recommend using Windows Server 2012 R2 and later for optimal log formats.
If you are using Linux instances, ensure that the screen utility is installed. If it is not, your log
data might be truncated. On Amazon Linux, Amazon Linux 2, and Ubuntu Server, the screen
utility is installed by default. To install screen manually, depending on your version of Linux, run
either sudo yum install screen or sudo apt-get install screen.

Refer to the following topics for more information about auditing and logging options for Session
Manager.

Audit Session Activity Using AWS CloudTrail

AWS CloudTrail captures session API calls through the Systems Manager console, the AWS CLI, and the
Systems Manager SDK. The information can be viewed on the CloudTrail console or stored in a specified
Amazon S3 bucket. One bucket is used for all CloudTrail logs for your account.

For more information, see Logging AWS Systems Manager API Calls with AWS CloudTrail (p. 889).

Logging Session Data Using Amazon S3 (Console)

You can choose to store session log data in a specified Amazon S3 bucket for auditing purposes. The
default option is for logs to be sent to an encrypted S3 bucket. Encryption is performed using the key
specified for the bucket, either an AWS Key Management Service (AWS KMS) key or an Amazon S3
Server-Side Encryption (SSE) key (AES-256).
Important
When you use virtual hosted–style buckets with Secure Sockets Layer (SSL), the SSL wildcard
certificate only matches buckets that don't contain periods. To work around this, use HTTP or
write your own certificate verification logic. We recommend that you do not use periods (".") in
bucket names when using virtual hosted–style buckets.

S3 Bucket Encryption

In order to send logs to your S3 bucket with encryption, encryption must be enabled on the bucket. For
more information about S3 bucket encryption, see Amazon S3 Default Encryption for S3 Buckets.

Customer-managed CMK

If you are using an AWS KMS customer master key (CMK) that you manage yourself (a customer-
managed CMK) to encrypt your bucket, then the IAM instance profile attached to your instances must
have explicit permissions to read the CMK. If you use an AWS-managed CMK, the instance does not

608
 AWS Systems Manager User Guide
Auditing and Logging Session Activity

require this explicit permission. For more information about providing the instance profile with access to
use the CMK, see Allows Key Users to Use the CMK in the AWS Key Management Service Developer Guide.

Follow these steps to configure Session Manager to store session logs in an Amazon S3 bucket.
Note
You can also use the AWS CLI to specify or change the S3 bucket that session data is sent to. For
information, see Update Session Manager Preferences (AWS CLI) (p. 592).

To log session data using Amazon S3 (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. Choose the Preferences tab, and then choose Edit.
4. Select the check box next to S3 bucket.
5. (Optional) If you do not want to encrypt the log data that is sent to the S3 bucket, clear the check
box next to Encrypt log data. Otherwise, log data is encrypted using the server-side encryption
key specified for the bucket. You must also clear the check box if encryption is not enabled on the
bucket.
6. For S3 bucket name, select one of the following:
Note
We recommend that you do not use periods (".") in bucket names when using virtual
hosted–style buckets. For more information about S3 bucket-naming conventions, see
Bucket Restrictions and Limitations in the Amazon Simple Storage Service Developer Guide.

• Choose a bucket name from the list: Select an S3 bucket that has already been created in your
account to store session log data.
• Enter a bucket name in the text box: Enter the name of an S3 bucket that has already been
created in your account to store session log data.
7. (Optional) For S3 key prefix, enter the name of an existing or new folder to store logs in the selected
bucket.
8. Choose Save.

For more information about working with Amazon S3 and S3 buckets, see the Amazon Simple Storage
Service Getting Started Guide and the Amazon Simple Storage Service Console User Guide.

Logging Session Data Using Amazon CloudWatch Logs (Console)

Amazon CloudWatch Logs lets you monitor, store, and access log files from various AWS services. You
can stream session log data to a CloudWatch Logs log group for auditing purposes. The default option is
for log data to be sent with encryption using your AWS KMS key, but you can stream the data to your log
group with or without encryption.

Follow these steps to configure Session Manager to stream session log data to a CloudWatch Logs log
group.
Note
You can also use the AWS CLI to specify or change the CloudWatch Logs log group that session
data is sent to. For information, see Update Session Manager Preferences (AWS CLI) (p. 592).

To log session data using Amazon CloudWatch Logs (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Session Manager.
3. Choose the Preferences tab, and then choose Edit.
4. Select the check box next to CloudWatch logs.

609
 AWS Systems Manager User Guide
Auditing and Logging Session Activity

5. (Optional) If you do not want to encrypt the log data that is sent to CloudWatch Logs, clear
the check box next to Encrypt log data. Otherwise, log data is encrypted using the server-side
encryption key specified for the log group. You must also clear the check box if encryption is not
enabled on the log group.
6. For CloudWatch logs, to specify the existing CloudWatch Logs log group in your AWS account to
upload session logs to, select one of the following:

• Choose a log group from the list: Select a log group that has already been created in your
account to store session log data.
• Enter a log group name in the text box: Enter the name of a log group that has already been
created in your account to store session log data.
7. Choose Save.

For more information about working with CloudWatch Logs, see the Amazon CloudWatch Logs User
Guide.

Monitoring Session Activity Using Amazon CloudWatch Events

(Console)
CloudWatch Events lets you set up rules to detect when changes happen to AWS resources. You can
create a rule to detect when a user in your organization starts or terminates a session, and then, for
example, receive a notification through Amazon SNS about the event.

CloudWatch Events support for Session Manager relies on records of API actions that were recorded by
CloudTrail. (You can use CloudTrail integration with CloudWatch Events to respond to most AWS Systems
Manager events.)

The following steps outline how to trigger notifications through Amazon Simple Notification Service
(Amazon SNS) when a Session Manager API event occurs, such as StartSession.

To monitor session activity using Amazon CloudWatch Events (console)

1. Create an Amazon SNS topic to use for sending notifications when the Session Manager event occurs
that you want to track.

For more information, see Create a Topic in the Amazon Simple Notification Service Developer Guide.
2. Create a CloudWatch Events rule to invoke the Amazon SNS target for the type of Session Manager
event you want to track.

For information about how to create the rule, see Creating a CloudWatch Events Rule That Triggers
on an Event in the Amazon CloudWatch Events User Guide.

As you follow the steps to create the rule, make the following selections:

• For Service Name, choose EC2 Simple Systems Manager (SSM).

• For Event Type, choose AWS API Call via CloudTrail.
• Choose Specific operation(s), and then enter the Session Manager command or commands (one
at a time) you want to receive notifications for. You can choose StartSession, ResumeSession,
and TerminateSession. (CloudWatch Events doesn't support Get*, List*, and Describe*
commands.)
• ForTargets, choose SNS topic. For Topic, choose the name of the Amazon SNS topic you created
in Step 1.

For more information, see the Amazon CloudWatch Events User Guide and the Amazon Simple Notification
Service Getting Started Guide.

610
 AWS Systems Manager User Guide
Troubleshooting Session Manager

Troubleshooting Session Manager

Use the following information to help you troubleshoot problems with Session Manager.

Topics
• No Permission to Start a Session (p. 611)
• No Permission to Change Session Preferences (p. 611)
• Instance Not Available or Not Configured for Session Manager (p. 611)
• Session Manager Plugin Not Found (p. 612)
• Session Manager Plugin Not Automatically Added to Command Line Path (Windows) (p. 612)

No Permission to Start a Session

Problem: You attempt to start a session, but the system tells you that you do not have the necessary
permissions.

• Solution: A system administrator has not granted you IAM policy permissions for starting Session
Manager sessions. For information, see Control User Session Access to Instances (p. 579).

No Permission to Change Session Preferences

Problem: You attempt to update global session preferences for your organization, but the system tells
you that you do not have the necessary permissions.

• Solution: A system administrator has not granted you IAM policy permissions for setting Session
Manager preferences. For information, see Grant or Deny a User Permissions to Update Session
Manager Preferences (p. 587).

Instance Not Available or Not Configured for Session Manager

Problem 1: You want to start a session on the Start a session console page, but an instance is not in the
list.

• Solution: The instance you want to connect to might not have been configured to use with the AWS
Systems Manager service. To use an instance with Systems Manager, an IAM instance profile that gives
Systems Manager permission to perform actions on your instances must be attached to the instance.
For information, see Create an IAM Instance Profile for Systems Manager (p. 29).
Note
If SSM Agent is already running on an instance when you attach the IAM instance profile, you
might need to restart the agent before the instance is listed on the Start a session console
page.

Problem 2: An instance you want to connect is in the list on the Start a session console page, but the
page reports that "The instance you selected is not configured to use Session Manager."

• Solution A: The instance has been configured for use with the AWS Systems Manager service, but
the IAM instance profile attached to the instance might not include permissions for the Session
Manager capability. For information, see Verify or Create an IAM Instance Profile with Session Manager
Permissions (p. 573).
• Solution B: The instance is not running a version of SSM Agent that supports Session Manager. Update
SSM Agent on the instance to version 2.3.68.0 or later.

611
 AWS Systems Manager User Guide
Troubleshooting Session Manager

Update SSM Agent manually on an instance by following the steps in Install and Configure SSM
Agent on Amazon EC2 Windows Instances (p. 66) or Manually Install SSM Agent on Amazon EC2 Linux
Instances (p. 68), depending on the operating system.

Alternatively, use the Run Command document AWS-UpdateSSMAgent to update the agent
version on one or more instances at a time. For information, see Update SSM Agent by using Run
Command (p. 620).
Tip
To always keep your agent up-to-date, we recommend updating SSM Agent to the latest
version on an automated schedule that you define using either of the following methods:
• Run AWS-UpdateSSMAgent as part of a State Manager association. For information, see
Automatically Update SSM Agent (CLI) (p. 681).
• Run AWS-UpdateSSMAgent as part of a maintenance window. For information
about working with maintenance windows, see Working with Maintenance Windows
(Console) (p. 455) and Tutorial: Create and Configure a Maintenance Window (AWS
CLI) (p. 463).

Session Manager Plugin Not Found

To use the AWS CLI to run session commands, the Session Manager plugin must also be installed on
your local machine. For information, see (Optional) Install the Session Manager Plugin for the AWS
CLI (p. 599).

Session Manager Plugin Not Automatically Added to Command

Line Path (Windows)
When you install the Session Manager plugin on Windows, the session-manager-plugin executable
should be automatically added to your operating system's PATH environment variable. If the command
failed after you ran it to check whether the Session Manager plugin installed correctly (aws ssm
start-session --target instance-id), you might need to set it manually using the following
procedure.

To modify your PATH variable (Windows)

1. Press the Windows key and enter environment variables.

2. Choose Edit environment variables for your account.
3. Choose PATH and then choose Edit.
4. Add paths to the Variable value field, separated by semicolons. For example: C:\existing
\path;C:\new\path

C:\existing\path represents the value already in the field. C:\new\path represents the path
you want to add. For example:

• 64-bit machines: C:\Program Files\Amazon\SessionManagerPlugin\bin\

• 32-bit machines: C:\Program Files (x86)\Amazon\SessionManagerPlugin\bin\
5. Choose OK twice to apply the new settings.
6. Close any running command prompts and re-open.

612
 AWS Systems Manager User Guide
Run Command

AWS Systems Manager Run Command

AWS Systems Manager Run Command lets you remotely and securely manage the configuration of
your managed instances. A managed instance is any Amazon EC2 instance or on-premises machine in
your hybrid environment that has been configured for Systems Manager. Run Command enables you
to automate common administrative tasks and perform ad hoc configuration changes at scale. You can
use Run Command from the AWS console, the AWS Command Line Interface, AWS Tools for Windows
PowerShell, or the AWS SDKs. Run Command is offered at no additional cost.

Administrators use Run Command to perform the following types of tasks on their managed instances:
install or bootstrap applications, build a deployment pipeline, capture log files when an instance is
terminated from an Auto Scaling group, and join instances to a Windows domain, to name a few.

Getting Started

The following table includes information to help you get started with Run Command.

Topic Details

Systems Manager Prerequisites (p. 12) (Required) Verify that your instances meet the
minimum requirements for Run Command,
configure required roles, and install SSM Agent.

Setting Up AWS Systems Manager for Hybrid (Optional) Register on-premises servers and VMs
Environments (p. 41) with AWS so that you can manage them using Run
Command.

Running Commands Using Systems Manager Run Learn how to run a command from the EC2
Command (p. 619) console and how to run commands to a fleet of
managed instances.

Run Command Walkthroughs (p. 631) Learn how to run commands using either AWS
Tools for Windows PowerShell or the AWS CLI.

Related Content

• Remotely Run Commands on an EC2 Instance (10 minute tutorial)

• AWS Systems Manager Limits
• AWS Systems Manager API Reference

Contents
• Setting Up Run Command (p. 613)
• Running Commands Using Systems Manager Run Command (p. 619)
• Understanding Command Statuses (p. 627)
• Run Command Walkthroughs (p. 631)
• Troubleshooting Systems Manager Run Command (p. 642)

Setting Up Run Command

Before you can manage instances by using Run Command, you must configure an AWS Identity and
Access Management (IAM) user policy for any user who will run commands, and an IAM instance profile
role for any instance that will process commands. For more information, see Setting Up AWS Systems
Manager (p. 23).

613
 AWS Systems Manager User Guide
Setting Up Run Command

This section also includes recommended tasks for monitoring command executions and restricting
command access to tagged instances. The tasks in this section are not required, but they can help
minimize the security posture and day-to-day management of your instances. For this reason, we highly
recommend you complete the tasks in this section.

Topics
• Configuring Amazon CloudWatch Logs for Run Command (p. 614)
• Configuring CloudWatch Events for Run Command (p. 615)
• Restricting Run Command Access Based on Instance Tags (p. 616)

Configuring Amazon CloudWatch Logs for Run Command

When you send a command by using Run Command, you can specify where you want to send the
command output. By default, Systems Manager returns only the first 2,500 characters of the command
output. If you want to view the full details of the command output, you can specify an Amazon Simple
Storage Service (Amazon S3) bucket. Or you can specify Amazon CloudWatch Logs. If you specify
CloudWatch Logs, Run Command periodically sends all command output and error logs to CloudWatch
Logs. You can monitor output logs in near real-time, search for specific phrases, values, or patterns, and
create alarms based on the search.

If you configured your instance or on-premises hybrid machine to use the AWS Identity
and Access Management (IAM) managed policies AmazonSSMManagedInstanceCore and
CloudWatchAgentServerPolicy, then your instance requires no additional configuration to send output
to CloudWatch Logs. You simply need to choose this option if sending commands from the console, or
add the cloud-watch-output-config section and CloudWatchOutputEnabled parameter if using
the AWS CLI, Tools for Windows PowerShell, or an API action. The cloud-watch-output-config
section and CloudWatchOutputEnabled parameter are described in more detail later in this topic.

For information about adding policies to an instance profile for Amazon EC2 instances, see Create an IAM
Instance Profile for Systems Manager (p. 29). For information about adding policies to a service role for
on-premises instances and virtuals machines that you plan to use as managed instances, see Create an
IAM Service Role for a Hybrid Environment (p. 42).

For information about updating an existing instance profile, see Add Permissions to a Systems Manager
Instance Profile (Console) (p. 32).

If you are using a custom policy on your instances, then you must update the policy on each instance to
allow Systems Manager to send output and logs to CloudWatch Logs. Add the following policy objects to
your custom policy. For more information, about updating an IAM policy, see Editing IAM Policies in the
IAM User Guide.

{
"Effect":"Allow",
"Action":[
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutLogEvents"
],
"Resource":"*"
},

Specifying CloudWatch Logs When You Send Commands

To specify CloudWatch Logs as the output when you send a command from the AWS Management
Console, choose CloudWatch Output in the Output options section. Optionally, you can specify the

614
 AWS Systems Manager User Guide
Setting Up Run Command

name of CloudWatch Logs group where you want to send command output. If you don't specify a group
name, Systems Manager automatically creates a log group for you. The log group uses the following
naming format: aws/ssm/SystemsManagerDocumentName.

If you run commands by using the AWS CLI, then you must specify the cloud-watch-output-config
section in your command. This section enables you to specify the CloudWatchOutputEnabled
parameter, and optionally, the CloudWatchLogGroupName parameter. Here is an example:

aws ssm send-command --document-name "AWS-RunPowerShellScript" --parameters commands=["echo

helloWorld"] --targets "Key=instanceids,Values=an instance ID” --cloud-watch-output-config
'{"CloudWatchLogGroupName":"log group name","CloudWatchOutputEnabled":true}'

Viewing Command Output in CloudWatch Logs

As soon as the command starts to run, Systems Manager sends output to CloudWatch Logs in near real-
time. The output in CloudWatch Logs uses the following format:

CommandID/InstanceID/PluginID/stdout

CommandID/InstanceID/PluginID/stderr

Output from the execution is uploaded every 30 seconds or when the buffer exceeds 200 KB, whichever
happens first.
Note
Log Streams are only created when output data is available. For example, if there is no error
data for an execution, the stderr stream isn't created.

Here is an example of the command output as it appears in CloudWatch Logs.

Group - /aws/ssm/AWS-RunShellScript
Streams –
1234-567-8910/i-abcd-efg-hijk/AWS-RunPowerShellScript/stdout
24/1234-567-8910/i-abcd-efg-hijk/AWS-RunPowerShellScript/stderr

Configuring CloudWatch Events for Run Command

Use Amazon CloudWatch Events to log command execution status changes. You can create a rule that
runs whenever there is a state transition, or when there is a transition to one or more states that are of
interest.

You can also specify Run Command as a target action when a CloudWatch event occurs. For example,
say a CloudWatch event is triggered that an instance in an Auto Scaling group is about to terminate. You
can configure CloudWatch so the target of that event is a Run Command script that captures the log
files from the instance before it is terminated. You can also configure a Run Command action when a
new instance is created in an Auto Scaling group. For example, when CloudWatch receives the instance-
created event, Run Command could enable the web server role or install software on the instance.

• Configuring CloudWatch Events for Run Command (p. 615)

• Configure Run Command as a CloudWatch Events Target (p. 616)

Configuring CloudWatch Events for Run Command

You can configure CloudWatch Events to notify you of Run Command status changes, or a status change
for a specific command invocation. Use the following procedure to configure CloudWatch Events to send
notification about Run Command.

615
 AWS Systems Manager User Guide
Setting Up Run Command

To configure CloudWatch Events for Run Command

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then choose Create rule.
3. Under Event Source, verify that Event Pattern is selected.
4. In the Service Name field, choose EC2 Simple Systems Manager (SSM)
5. In the Event Type field, choose Run Command.
6. Choose the detail types and statuses for which you want to receive notifications, and then choose
Add targets.
7. In the Select target type list, choose a target type. For information about the different types of
targets, see the corresponding AWS Help documentation.
8. Choose Configure details.
9. Specify the rule details, and then choose Create rule.

Configure Run Command as a CloudWatch Events Target

Use the following procedure to configure a Run Command action as the target of a CloudWatch event.

To configure Run Command as a target of a CloudWatch event

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then either choose to create a new rule or edit an
existing rule.
3. After specifying or verifying the details of the rule, choose Add target.
4. In the Select target type list, choose SSM Run Command.
5. In the Document list, choose an SSM document. The document determines the type of actions Run
Command can perform on your instances.
Note
Verify that the document you choose can run on the instance operating system. Some
documents run only on Windows or only on Linux operating systems. For more information
about SSM Documents, see AWS Systems Manager Documents (p. 775).
6. In the Target key field, specify either InstanceIds or tag:EC2_tag_name. Here are some examples of
a Target key that uses an EC2 tag: tag:production and tag:server-role.
7. In the Target value(s) field, if you chose InstanceIds in the previous step, specify one or more
instance IDs separated by commas. If you chose tag:EC2_tag_name in the previous step, specify one
or more tag values. After you type the value, for example web-server or database, choose Add.
8. In the Configure parameter(s) section, choose an option and then complete any fields populated
by your choice. Use the hover text for more information about the options. For more information
about the parameter fields for your document, see Running Commands Using Systems Manager Run
Command (p. 619) and choose the procedure for your document.
9. In the permissions section, choose Create a new role for this specific resource to create a new role
with the required instance profile role for Run Command. Or, choose Use existing role. For more
information about roles required for Run Command, see Setting Up AWS Systems Manager (p. 23).
10. Choose Configure details and complete the wizard.

Restricting Run Command Access Based on Instance Tags

You can further restrict command execution to specific instances by creating an IAM user policy that
includes a condition that the user can only run commands on instances that are tagged with specific

616
 AWS Systems Manager User Guide
Setting Up Run Command

Amazon EC2 tags. In the following example, the user is allowed to use Run Command (Effect: Allow,
Action: ssm:SendCommand) by using any SSM document (Resource: arn:aws:ssm:*:*:document/*) on
any instance (Resource: arn:aws:ec2:*:*:instance/*) with the condition that the instance is a Finance
WebServer (ssm:resourceTag/Finance: WebServer). If the user sends a command to an instance
that is not tagged or that has any tag other than Finance: WebServer, the execution results show
AccessDenied.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:*:*:document/*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ec2:*:*:instance/*"
],
"Condition":{
"StringLike":{
"ssm:resourceTag/Finance":[
"WebServers"
]
}
}
}
]
}

You can create IAM policies that enable a user to run commands on instances that are tagged with
multiple tags. The following policy enables the user to run commands on instances that have two tags. If
a user sends a command to an instance that is not tagged with both of these tags, the execution results
show AccessDenied.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},

617
 AWS Systems Manager User Guide
Setting Up Run Command

{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}

You can also create IAM policies that enable a user to run commands on multiple groups of tagged
instances. The following policy enables the user to run commands on either group of tagged instances,
or both groups.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[

618
 AWS Systems Manager User Guide
Running Commands

"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}

For more information about creating IAM user policies, see Managed Policies and Inline Policies in the
IAM User Guide. For more information about tagging instances, see Tagging Your Amazon EC2 Resources
in the Amazon EC2 User Guide for Linux Instances (content applies to Windows and Linux instances).

Running Commands Using Systems Manager Run

Command
This section includes information about how to send commands from the AWS Systems Manager
console, and how to send commands to a fleet of instances by using the Targets parameter with EC2
tags. This section also includes information about how to cancel a command.

For information about how to send commands using Windows PowerShell, see Walkthrough: Use the
AWS Tools for Windows PowerShell with Run Command (p. 634) or the examples in the AWS Systems
Manager section of the AWS Tools for PowerShell Cmdlet Reference. For information about how to send
commands using the AWS CLI, see the Walkthrough: Use the AWS CLI with Run Command (p. 631) or
the examples in the SSM CLI Reference.
Important
If this is your first time using Run Command, we recommend executing commands against a test
instance or an instance that is not being used in a production environment.

Contents
• Running Commands from the Console (p. 619)
• Sending Commands that Use the Document Version Parameter (p. 622)
• Using Targets and Rate Controls to Send Commands to a Fleet (p. 622)
• Rebooting Managed Instance from Scripts (p. 625)
• Canceling a Command (p. 627)

Running Commands from the Console

You can use Run Command from the console to configure instances without having to login to each
instance. This topic includes an example that shows how to update SSM Agent (p. 620) on an instance
by using Run Command.

Before You Begin

Before you send a command using Run Command, verify that your instances meet Systems Manager
requirements (p. 12).

619
 AWS Systems Manager User Guide
Running Commands

To send a command using Run Command

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. In the Command document list, choose a Systems Manager document.
4. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
5. In the Command parameters section, specify values for required parameters.
6. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
7. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
8. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
9. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
10. Choose Run.

For information about canceling a command, see the section called “Canceling a Command” (p. 627).

Update SSM Agent by using Run Command

The following procedure describes how to quickly update SSM Agent running on your Windows and
Linux instances. You can update to either the latest version or downgrade to an older version. When

620
 AWS Systems Manager User Guide
Running Commands

you run the command, the system downloads the version from AWS, installs it, and then uninstalls the
version that existed before the command was run. If an error occurs during this process, the system rolls
back to the version on the server before the command was run and the command status shows that the
command failed.
Note
To be notified about SSM Agent updates, subscribe to the SSM Agent Release Notes page on
GitHub.

To update SSM Agent using Run Command

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. In the Command document list, choose AWS-UpdateSSMAgent.
4. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
5. In the Command parameters section, specify values for the following parameters, if you want:

a. (Optional) For Version, type the version of SSM Agent to install. You can install older versions of
the agent. If you do not specify a version, the service installs the latest version.
b. (Optional) For Allow Downgrade, choose true to install an earlier version of SSM Agent. If you
choose this option, you must specify the earlier version number. Choose false to install only the
newest version of the service.
6. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
7. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
8. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).

621
 AWS Systems Manager User Guide
Running Commands

9. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
10. Choose Run.

Sending Commands that Use the Document Version Parameter

You can use the document-version parameter to specify which version of an SSM document to use when
the command runs. You can specify one of the following options for this parameter:

• $DEFAULT
• $LATEST
• Version number

If you run commands by using the AWS CLI, then you must escape the first two options by using a
backslash. If you specify a version number, then you don't need to use the backslash. For example:

--document-version "\$DEFAULT"

--document-version "\$LATEST"

--document-version "3"

Use the following procedure to run a command by using the AWS CLI that uses the document-version
parameter.

To run commands using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. List all available documents

This command lists all of the documents available for your account based on IAM permissions. The
command returns a list of Linux and Windows documents.

aws ssm list-documents

3. Use the following command to view the different versions of a document.

aws ssm list-document-versions --name "document name"

4. Use the following command to run a command that uses an SSM document version.

aws ssm send-command --document-name "AWS-RunShellScript" --parameters commands="echo

Hello",executionTimeout=3600 --instance-ids instance-ID --endpoint-url "https://us-
east-2.amazonaws.com" --region "us-east-2" --document-version "\$DEFAULT, \$LATEST, or
a version number"

Using Targets and Rate Controls to Send Commands to a Fleet

You can send commands to tens, hundreds, or thousands of instances by using the targets parameter
(the Select Targets by Specifying a Tag option in the Amazon EC2 console). The targets parameter

622
 AWS Systems Manager User Guide
Running Commands

accepts a Key,Value combination based on Amazon EC2 tags that you specified for your instances.
When you run the command, the system locates and attempts to run the command on all instances
that match the specified tags. For more information about Amazon EC2 tags, see Tagging Your Amazon
EC2 Resources in the Amazon EC2 User Guide (content applies to Windows and Linux instances). You can
also send commands to instances that belong to an AWS resource group. For more information about
resource groups, see What are Resource Groups? in the AWS Resource Groups User Guide.
Note
You can also use the targets parameter to target a list of specific instance IDs, as described in
the next section.

To control command execution across hundreds or thousands of instances, Run Command also includes
parameters for restricting how many instances can simultaneously process a request and how many
errors can be thrown by a command before the command is terminated.

Contents
• Targeting Multiple Instances (p. 623)
• Using Concurrency Controls (p. 625)
• Using Error Controls (p. 625)

Targeting Multiple Instances

You can run a command and target instances by specifying tags applied to managed instances, AWS
resource group names, or instance IDs.
Note
Sample commands in this section are truncated using [...].

For use with the AWS CLI send-command command, the targets parameter supports the syntax
demonstrated in the following examples:

Example 1: Targeting Tags

aws ssm send-command --document-name name --targets Key=tag:tag_name,Values=tag_value [...]

Example 2: Targeting an AWS Resource Group

You can specify a maximum of one resource group name per command. When you create a resource
group, we recommend including AWS::SSM:ManagedInstance and AWS::EC2::Instance as resource
types in your grouping criteria.
Note
In order to send commands that target a resource group, you must have been granted IAM
permissions to list, or view, the resources that belong to that group. For more information, see
Set Up Permissions in the AWS Resource Groups User Guide.

aws ssm send-command --document-name --targets Key=resource-groups:name,Values=resource-

group-name [...]

Example 3: Targeting Instance IDs

aws ssm send-command --document-name name --targets Key=instanceids,Values=ID1,ID2,ID3

[...]

If you tagged instances for different environments using a Key named Environment and Values of
Development, Test, Pre-production and Production, then you could send a command to all of the
instances in one of these environments by using the targets parameter with the following syntax:

623
 AWS Systems Manager User Guide
Running Commands

aws ssm send-command --document-name name --targets Key=tag:Environment,Values=Development

[...]

You could target additional instances in other environments by adding to the Values list. Separate items
using commas.

aws ssm send-command --document-name name --targets

Key=tag:Environment,Values=Development,Test,Pre-production [...]

Example: Refining your targets using multiple Key criteria

You can refine the number of targets for your command by including multiple Key criteria. If you include
more than one Key criteria, the system targets instances that meet all of the criteria. The following
command targets all instances tagged for the Finance Department and tagged for the database server
role.

aws ssm send-command --document-name name --targets Key=tag:Department,Values=Finance

Key=tag:ServerRole,Values=Database [...]

Example: Using multiple Key and Value criteria

Expanding on the previous example, you can target multiple departments and multiple server roles by
including additional items in the Values criteria.

aws ssm send-command --document-name name --targets

Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database
[...]

Example: Targeting tagged instances using multipleValues criteria

If you tagged instances for different environments using a Key named Department and Values of
Sales and Finance, then you could send a command to all of the instances in these environments by
using the targets parameter with the following syntax:

aws ssm send-command --document-name name --targets Key=tag:Department,Values=Sales,Finance

[...]

Note
You can specify a maximum of 5 keys, and 5 values for each key.

If either a tag key (the tag name) or a tag value includes spaces, then you must enclose the tag key or the
value in quotation marks, as show in the following examples.

Example 1: Spaces in Value tag.

aws ssm send-command --document-name name --targets Key=tag:OS,Values="Windows Server 2016

Nano" [...]

Example 2: Spaces in tag key and Value.

aws ssm send-command --document-name name --targets Key="tag:Operating

System",Values="Windows Server 2016 Nano" [...]

Example 3: Spaces in one item in a list of Values.

624
 AWS Systems Manager User Guide
Running Commands

aws ssm send-command --document-name name --targets

Key=tag:Department,Values="Sales","Finance","Systems Mgmt" [...]

Using Concurrency Controls

You can control how many servers run the command at the same time by using the max-concurrency
parameter (the Execute on field in the Amazon EC2 console). You can specify either an absolute number
of instances, for example 10, or a percentage of the target set, for example 10%. The queueing system
delivers the command to a single instance and waits until the initial invocation completes before sending
the command to two more instances. The system exponentially sends commands to more instances until
the value of max-concurrency is met. The default for value max-concurrency is 50. The following
examples show you how to specify values for the max-concurrency parameter:

aws ssm send-command --document-name name --max-concurrency 10 --targets

Key=tag:Environment,Values=Development [...]

aws ssm send-command --document-name name --max-concurrency 10% --targets

Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database
[...]

Using Error Controls

You can also control the execution of a command to hundreds or thousands of instances by setting
an error limit using the max-errors parameters (the Stop after __ errors field in the Amazon EC2
console). The parameter specifies how many errors are allowed before the system stops sending the
command to additional instances. You can specify either an absolute number of errors, for example
10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops
sending the command when the fourth error is received. If you specify 0, then the system stops sending
the command to additional instances after the first error result is returned. If you send a command to
50 instances and set max-errors to 10%, then the system stops sending the command to additional
instances when the sixth error is received.

Invocations that are already running a command when max-errors is reached are allowed to complete,
but some of these invocations may fail as well. If you need to ensure that there won’t be more than max-
errors failed invocations, set max-concurrency to 1 so the invocations proceed one at a time. The
default for max-errors is 0. The following examples show you how to specify values for the max-errors
parameter:

aws ssm send-command --document-name name --max-errors 10 --targets

Key=tag:Database,Values=Development [...]

aws ssm send-command --document-name name --max-errors 10% --targets

Key=tag:Environment,Values=Development [...]

aws ssm send-command --document-name name --max-concurrency 1 --max-errors 1 --targets

Key=tag:Environment,Values=Production [...]

Rebooting Managed Instance from Scripts

If the scripts that you run by using Run Command reboot managed instances, then you must specify
an exit code in your script. If you attempt to reboot an instance from a script by using some other
mechanism, the script execution status might not be updated correctly, even if the reboot is the last

625
 AWS Systems Manager User Guide
Running Commands

step in your script. For Windows managed instances, you specify exit 3010 in your script. For Linux
managed instances, you specify exit 194. The exit code instructs SSM Agent to reboot the managed
instance, and then restart the script after the reboot completed. Before starting the reboot, SSM Agent
informs the Systems Manager service in the cloud that communication will be disrupted during the
server reboot.

Create idempotent scripts

When developing scripts that reboot managed instances, make the scripts idempotent so the script
execution continues where it left off after the reboot. Idempotent scripts manage state and validate
if the action was performed or not. This prevents a step from running multiple times when it is only
intended to run once.

Here is an outline example of an idempotent script the reboots the instance multiple times.

$name = Get current computer name

If ($name –ne $desiredName)
{
Rename computer
exit 3010
}

$domain = Get current domain name

If ($domain –ne $desiredDomain)
{
Join domain
exit 3010
}

If (desired package not installed)

{
Install package
exit 3010
}

The following script samples use exit codes to restart instances. The Windows example installs the
Hyper-V application on the instance, and then restarts the instance. The Linux example installs package
updates on Amazon Linux, and then restarts the instance.

Windows example

$hyperV = Get-WindowsFeature -Name Hyper-V

if(-not $hyperV.Installed)
{
# Install Hyper-V and then send a reboot request to SSM Agent.
Install-WindowsFeature -Name Hyper-V -IncludeManagementTools
exit 3010
}

Amazon Linux example

#!/bin/bash
yum -y update
needs-restarting -r
if [ $? -eq 1 ]
then
exit 194
else
exit 0
fi

626
 AWS Systems Manager User Guide
Understanding Command Statuses

Canceling a Command
You can attempt to cancel a command as long as the service shows that it is in either a Pending or
Executing state. However, even if a command is still in one of these states, we cannot guarantee that the
command will be terminated and the underlying process stopped.

To cancel a command using the console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Select the command invocation that you want to cancel.
4. Choose Cancel command.

To cancel a command using the AWS CLI

Use the following command.

aws ssm cancel-command --command-id "command ID" --instance-ids "instance ID"

For information about the status of a cancelled command, see Understanding Command
Statuses (p. 627).

Understanding Command Statuses

Systems Manager Run Command reports detailed status information about the different states a
command experiences during processing and for each instance that processed the command. You can
monitor command statuses using the following methods.

• Click the Refresh icon on the Run Command page in the Amazon EC2 console.
• Call list-commands or list-command-invocations using the AWS CLI. Or call Get-SSMCommand or Get-
SSMCommandInvocation using AWS Tools for Windows PowerShell.
• Configure CloudWatch Events to log status changes.
• Configure Amazon SNS to send notifications for all status changes or specific statuses like Failed or
TimedOut.

Run Command Status

Run Command reports status details for three areas: plugins, invocations, and an overall command
status. A plugin is a code-execution block that is defined in your command's Systems Manager document.
The AWS-* documents include only one plugin, but you can create your own documents that use
multiple plugins. For more information about plugins, see SSM Document Plugin Reference (p. 800).

When you send a command to multiple instances at the same time, each copy of the command targeting
each instance is a command invocation. For example, if you use the AWS-RunShellScript document and
send an ifconfig command to 20 instances, that command has 20 invocations. Each command invocation
individually reports status. The plugins for a given command invocation individually report status as well.

Lastly, Run Command includes an aggregated command status for all plugins and invocations. The
aggregated command status can be different than the status reported by plugins or invocations, as
noted in the following tables.

627
 AWS Systems Manager User Guide
Understanding Command Statuses

Note
If you run commands to large numbers of instances using the max-concurrency or max-
errors parameters, command status reflects the limits imposed by those parameters, as
described in the following tables. For more information about these parameters, see Using
Targets and Rate Controls to Send Commands to a Fleet (p. 622).

Detailed Status for Command Plugins and Invocations

Status Details

Pending The command was not yet received by the agent

on the instance. If the command is not received
by the agent before the value specified by the
Timeout (seconds) parameter is reached, then the
status changes to Delivery Timed Out.

In Progress The command was received by the agent, or the

command started executing on the instance.
Depending on the result of all command plugins,
the status will change to Success, Failed, or
Execution Timed Out. If the agent is not
available on the instance, the command status will
show In Progress until the agent is available
again. The status will then change to a terminal
state.

Delayed The system attempted to send the command to

the instance but was not successful. The system
will retry again.

Success The command was received by SSM Agent on

the instance and returned an exit code of zero.
This status does not mean the command was
successfully processed on the instance. This is a
terminal state.
Note
To troubleshoot errors or get more
information about the command
execution, send a command that handles
errors or exceptions by returning
appropriate exit codes (non-zero exit
codes for command failure).

Delivery Timed Out The command was not delivered to the instance
before the delivery timeout expired. Delivery
timeouts do not count against the parent
command’s max-errors limit, but they do
contribute to whether the parent command status
is Success or Incomplete. This is a terminal
state.

Execution Timed Out Command execution started on the instance,

but the execution was not complete before the
execution timeout expired. Execution timeouts
count against the max-errors limit of the parent
command. This is a terminal state. When the
timeout is reached, Systems Manager stops the
command execution.

628
 AWS Systems Manager User Guide
Understanding Command Statuses

Status Details

Failed The command was not successful on the instance.

For a plugin, this indicates that the result code
was not zero. For a command invocation, this
indicates that the result code for one or more
plugins was not zero. Invocation failures count
against the max-errors limit of the parent
command. This is a terminal state.

Canceled The command was terminated before it was

completed. This is a terminal state.

Undeliverable The command can't be delivered to the instance.

The instance might not exist or it might not be
responding. Undeliverable invocations don't count
against the parent command’s max-errors limit,
and they don't contribute to whether the parent
command status is Success or Incomplete. This
is a terminal state.

Terminated The parent command exceeded its max-errors

limit and subsequent command invocations were
canceled by the system. This is a terminal state.

Invalid Platform The command was sent to an instance that did

not match the required platforms specified by the
chosen document. InvalidPlatform does not count
against the parent command’s max-errors limit,
and does not contribute to whether the parent
command status is Success or Failed. This is a
terminal state.

Access Denied The IAM user or role initiating the command

does not have access to the targeted managed
instance. AccessDenied does not count against
the parent command’s max-errors limit, but
does contribute to whether the parent command
status is Success or Failed. (For example, if
all invocations in a command have the status
AccessDenied, then the command status
returned is Failed. However, if a command
has 5 invocations, 4 of which return the status
AccessDenied and 1 of which returns the status
Success, then the parent command's status is
Success.) This is a terminal state.

Detailed Status for a Command

Status Details

Pending The command was not yet received by an agent

on any instances.

In Progress The command has been sent to at least one

instance but has not reached a final state on all
instances.

629
 AWS Systems Manager User Guide
Understanding Command Statuses

Status Details

Delayed The system attempted to send the command to

the instance but was not successful. The system
will retry again.

Success The command was received by SSM Agent on all

specified or targeted instances and returned an
exit code of zero. All command invocations have
reached a terminal state, and the value of max-
errors was not reached. This status does not
mean the command was successfully processed
on all specified or targeted instances. This is a
terminal state.
Note
To troubleshoot errors or get more
information about the command
execution, send a command that handles
errors or exceptions by returning
appropriate exit codes (non-zero exit
codes for command failure).

Delivery Timed Out The command was not delivered to the instance
before the delivery timeout expired. The value
of max-errors or more command invocations
shows a status of Delivery Timed Out. This is
a terminal state.

Execution Timed Out Command execution started on the instance,

but the execution was not complete before the
execution timeout expired. The value of max-
errors or more command invocations shows
a status of Execution Timed Out. This is a
terminal state.

Failed The command was not successful on the instance.

The value of max-errors or more command
invocations shows a status of Failed. This is a
terminal state.

Incomplete The command was attempted on all instances

and one or more of the invocations does not
have a value of Success. However, not enough
invocations failed for the status to be Failed.
This is a terminal state.

Canceled The command was terminated before it was

completed. This is a terminal state.

Rate Exceeded The number of instances targeted by the

command exceeded the account limit for pending
invocations. The system has canceled the
command before executing it on any instance.
This is a terminal state.

630
 AWS Systems Manager User Guide
Run Command Walkthroughs

Status Details

Access Denied The IAM user or role initiating the command

does not have access to the targeted resource
group. AccessDenied does not count against
the parent command’s max-errors limit, but
does contribute to whether the parent command
status is Success or Failed. (For example, if
all invocations in a command have the status
AccessDenied, then the command status
returned is Failed. However, if a command
has 5 invocations, 4 of which return the status
AccessDenied and 1 of which returns the status
Success, then the parent command's status is
Success.) This is a terminal state.

No Instances In Tag The tag key-pair value or resource group targeted

by the command does not match any managed
instances. This is a terminal state.

Run Command Walkthroughs

The walkthroughs in this section show you how to run commands with Run Command using either the
AWS Command Line Interface or AWS Tools for Windows PowerShell.

Contents
• Walkthrough: Use the AWS CLI with Run Command (p. 631)
• Walkthrough: Use the AWS Tools for Windows PowerShell with Run Command (p. 634)

You can also view sample commands in the following references.

• Systems Manager AWS CLI Reference

• Systems Manager AWS Tools for Windows PowerShell Reference

Walkthrough: Use the AWS CLI with Run Command

The following sample walkthrough shows you how to use the AWS CLI to view information about
commands and command parameters, how to run commands, and how to view the status of those
commands.
Important
Only trusted administrators should be allowed to use Systems Manager pre-configured
documents shown in this topic. The commands or scripts specified in Systems Manager
documents run with administrative privilege on your instances. If a user has permission to run
any of the pre-defined Systems Manager documents (any document that begins with AWS),
then that user also has administrator access to the instance. For all other users, you should
create restrictive documents and share them with specific users. For more information about
restricting access to Run Command, see Create Non-Admin IAM Users and Groups for Systems
Manager (p. 25).

Topics
• Step 1: Getting Started (p. 632)
• Step 2: Run Shell Scripts (p. 632)

631
 AWS Systems Manager User Guide
Run Command Walkthroughs

• Step 3: Send a Command Using the AWS-RunShellScript document - Example 1 (p. 633)
• Step 4: Send a Command Using the AWS-RunShellScript document - Example 2 (p. 633)
• Additional Examples (p. 633)

Step 1: Getting Started

You must either have administrator privileges on the instances you want to configure or you must
have been granted the appropriate permission in IAM. Also note, this example uses the US East (Ohio)
Region (us-east-2). Run Command is currently available in the AWS Regions listed in AWS Systems
Manager in the Amazon Web Services General Reference. For more information, see Systems Manager
Prerequisites (p. 12).

To run commands using the AWS CLI

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. List all available documents

This command lists all of the documents available for your account based on IAM permissions. The
command returns a list of Linux and Windows documents.

aws ssm list-documents

3. Verify that an instance is ready to receive commands

The output of the following command shows if instances are online.

aws ssm describe-instance-information --output text --query

"InstanceInformationList[*]"

4. Use the following command to view details about a particular instance.

Note
To run the commands in this walkthrough, you must replace the instance and command
IDs. The command ID is returned as a response of the send-command. The instance ID is
available from the Amazon EC2 console.

aws ssm describe-instance-information --instance-information-filter-list

key=InstanceIds,valueSet=instance ID

Step 2: Run Shell Scripts

Using Run Command and the AWS-RunShellScript document, you can run any command or script on an
EC2 instance as if you were logged on locally.

To view the description and available parameters

• Use the following command to view a description of the Systems Manager JSON document.

aws ssm describe-document --name "AWS-RunShellScript" --query

"[Document.Name,Document.Description]"

• Use the following command to view the available parameters and details about those parameters.

632
 AWS Systems Manager User Guide
Run Command Walkthroughs

aws ssm describe-document --name "AWS-RunShellScript" --query "Document.Parameters[*]"

Step 3: Send a Command Using the AWS-RunShellScript document - Example 1

Use the following command to get IP information for an instance.

aws ssm send-command --instance-ids "instance ID" --document-name "AWS-RunShellScript" --

comment "IP config" --parameters commands=ifconfig --output text

Get command information with response data

The following command uses the Command ID that was returned from the previous command to get
the details and response data of the command execution. The system returns the response data if the
command completed. If the command execution shows "Pending" or "InProgress" you will need to
run this command again to see the response data.

aws ssm list-command-invocations --command-id $sh_command_id --details

Step 4: Send a Command Using the AWS-RunShellScript document - Example 2

The following command displays the default user account running the commands.

sh_command_id=$(aws ssm send-command --instance-ids "instance ID" --document-name

"AWS-RunShellScript" --comment "Demo run shell script on Linux Instance" --parameters
commands=whoami --output text --query "Command.CommandId")

Get command status

The following command uses the Command ID to get the status of the command execution on the
instance. This example uses the Command ID that was returned in the previous command.

aws ssm list-commands --command-id "command_ID"

Get command details

The following command uses the Command ID from the previous command to get the status of the
command execution on a per instance basis.

aws ssm list-command-invocations --command-id "command_ID" --details

Get command information with response data for a specific instance

The following command returns the output of the original aws ssm send-command for a specific
instance.

aws ssm list-command-invocations --instance-id instance ID --command-id "command_ID" --

details

Additional Examples
The following command returns the version of Python running on an instance.

sh_command_id=$(aws ssm send-command --instance-ids "instance ID" --document-name

"AWS-RunShellScript" --comment "Demo run shell script on Linux Instances" --

633
 AWS Systems Manager User Guide
Run Command Walkthroughs

parameters commands='python -V' --output text --query "Command.CommandId") sh -c

'aws ssm list-command-invocations --command-id "$sh_command_id" --details --query
"CommandInvocations[].CommandPlugins[].{Status:Status,Output:Output}"'

The following command runs a Python script using Run Command.

sh_command_id=$(aws ssm send-command --instance-ids "instance ID" --document-name

"AWS-RunShellScript" --comment "Demo run shell script on Linux Instances" --
parameters '{"commands":["#!/usr/bin/python","print \"Hello world from python\""]}'
--output text --query "Command.CommandId") sh -c 'aws ssm list-command-invocations --
command-id "$sh_command_id" --details --query "CommandInvocations[].CommandPlugins[].
{Status:Status,Output:Output}"'

Walkthrough: Use the AWS Tools for Windows PowerShell with

Run Command
The following examples show how to use the Tools for Windows PowerShell to view information
about commands and command parameters, how to run commands, and how to view the status of
those commands. This walkthrough includes an example for each of the pre-defined Systems Manager
documents.
Important
Only trusted administrators should be allowed to use Systems Manager pre-configured
documents shown in this topic. The commands or scripts specified in Systems Manager
documents run with administrative privilege on your instances. If a user has permission to run
any of the pre-defined Systems Manager documents (any document that begins with AWS),
then that user also has administrator access to the instance. For all other users, you should
create restrictive documents and share them with specific users. For more information about
restricting access to Run Command, see Create Non-Admin IAM Users and Groups for Systems
Manager (p. 25).

Topics
• Configure AWS Tools for Windows PowerShell Session Settings (p. 634)
• List all Available Documents (p. 635)
• Run PowerShell Commands or Scripts (p. 635)
• Install an Application Using the AWS-InstallApplication Document (p. 636)
• Install a PowerShell Module Using the AWS-InstallPowerShellModule JSON Document (p. 637)
• Join an Instance to a Domain Using the AWS-JoinDirectoryServiceDomain JSON Document (p. 637)
• Send Windows Metrics to Amazon CloudWatch using the AWS-ConfigureCloudWatch
document (p. 638)
• Update EC2Config Using the AWS-UpdateEC2Config Document (p. 639)
• Enable/Disable Windows Automatic Update Using the AWS-ConfigureWindowsUpdate
document (p. 640)
• Manage Windows Updates Using Run Command (p. 641)

Configure AWS Tools for Windows PowerShell Session Settings

Specify your credentials

Open AWS Tools for Windows PowerShell on your local computer and run the following command
to specify your credentials. You must either have administrator privileges on the instances you want to
configure or you must have been granted the appropriate permission in IAM. For more information, see
Systems Manager Prerequisites (p. 12).

634
 AWS Systems Manager User Guide
Run Command Walkthroughs

Set-AWSCredentials –AccessKey key_name –SecretKey key_name

Set a default AWS Region

Run the following command to set the region for your PowerShell session. The example uses the US East
(Ohio) Region (us-east-2). Run Command is currently available in the AWS Regions listed in AWS Systems
Manager in the Amazon Web Services General Reference.

Set-DefaultAWSRegion -Region us-east-2

List all Available Documents

This command lists all of the documents available for your account:

Get-SSMDocumentList

Run PowerShell Commands or Scripts

Using Run Command and the AWS-RunPowerShell document, you can run any command or script on an
EC2 instance as if you were logged onto the instance using Remote Desktop. You can issue commands or
type in a path to a local script to run the command.
Note
For information about rebooting servers and instances when using Run Command to call scripts,
see Rebooting Managed Instance from Scripts (p. 625).

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-RunPowerShellScript"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-RunPowerShellScript" | select -ExpandProperty

Parameters

Send a command using the AWS-RunPowerShellScript document

The following command shows the contents of the C:\Users directory and the contents of the C:\
directory on two instances.

$runPSCommand=Send-SSMCommand -InstanceId @('Instance-ID', 'Instance-ID') -DocumentName

AWS-RunPowerShellScript -Comment 'Demo AWS-RunPowerShellScript with two instances' -
Parameter @{'commands'=@('dir C:\Users', 'dir C:\')}

Get command request details

The following command uses the Command ID to get the status of the command execution on both
instances. This example uses the Command ID that was returned in the previous command.

Get-SSMCommand -CommandId $runPSCommand.CommandId

The status of the command in this example can be Success, Pending, or InProgress.

Get command information per instance

635
 AWS Systems Manager User Guide
Run Command Walkthroughs

The following command uses the command ID from the previous command to get the status of the
command execution on a per instance basis.

Get-SSMCommandInvocation -CommandId $runPSCommand.CommandId

Get command information with response data for a specific instance

The following command returns the output of the original Send-SSMCommand for a specific instance.

Get-SSMCommandInvocation -CommandId $runPSCommand.CommandId -Details $true -

InstanceId Instance-ID | select -ExpandProperty CommandPlugins

Cancel a command
The following command cancels the Send-SSMCommand for the AWS-RunPowerShellScript document.

$cancelCommandResponse=Send-SSMCommand -InstanceId @('Instance-ID','Instance-ID') -

DocumentName AWS-RunPowerShellScript -Comment 'Demo AWS-RunPowerShellScript with two
instances' -Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'}
Stop-SSMCommand -CommandId $cancelCommandResponse.CommandId

Check the command status

The following command checks the status of the Cancel command.

Get-SSMCommand -CommandId $cancelCommandResponse.CommandId

Install an Application Using the AWS-InstallApplication Document

Using Run Command and the AWS-InstallApplication document, you can install, repair, or uninstall
applications on instances. The command requires the path or address to an MSI.
Note
For information about rebooting servers and instances when using Run Command to call scripts,
see Rebooting Managed Instance from Scripts (p. 625).

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-InstallApplication"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-InstallApplication" | select -ExpandProperty

Parameters

Send a command using the AWS-InstallApplication document

The following command installs a version of Python on your instance in unattended mode, and logs the
output to a local text file on your C: drive.

$installAppCommand=Send-SSMCommand -InstanceId Instance-ID -DocumentName AWS-

InstallApplication -Parameter @{'source'='https://www.python.org/ftp/python/2.7.9/
python-2.7.9.msi'; 'parameters'='/norestart /quiet /log c:\pythoninstall.txt'}

Get command information per instance

The following command uses the Command ID to get the status of the command execution

636
 AWS Systems Manager User Guide
Run Command Walkthroughs

Get-SSMCommandInvocation -CommandId $installAppCommand.CommandId -Details $true

Get command information with response data for a specific instance

The following command returns the results of the Python installation.

Get-SSMCommandInvocation -CommandId $installAppCommand.CommandId -Details $true -

InstanceId Instance-ID | select -ExpandProperty CommandPlugins

Install a PowerShell Module Using the AWS-InstallPowerShellModule JSON

Document
You can use Run Command to install PowerShell modules on an EC2 instance. For more information
about PowerShell modules, see Windows PowerShell Modules.

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-InstallPowerShellModule"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-InstallPowerShellModule" | select -ExpandProperty

Parameters

Install a PowerShell module

The following command downloads the EZOut.zip file, installs it, and then runs an additional command
to install XPS viewer. Lastly, the output of this command is uploaded to an Amazon S3 bucket named
demo-ssm-output-bucket.

$installPSCommand=Send-SSMCommand -InstanceId Instance-ID -DocumentName AWS-

InstallPowerShellModule -Parameter @{'source'='https://gallery.technet.microsoft.com/
EZOut-33ae0fb7/file/110351/1/EZOut.zip';'commands'=@('Add-WindowsFeature -name XPS-Viewer -
restart')} -OutputS3BucketName demo-ssm-output-bucket

Get command information per instance

The following command uses the Command ID to get the status of the command execution.

Get-SSMCommandInvocation -CommandId $installPSCommand.CommandId -Details $true

Get command information with response data for the instance

The following command returns the output of the original Send-SSMCommand for the specific
command ID.

Get-SSMCommandInvocation -CommandId $installPSCommand.CommandId -Details $true | select -

ExpandProperty CommandPlugins

Join an Instance to a Domain Using the AWS-JoinDirectoryServiceDomain JSON

Document
Using Run Command, you can quickly join an instance to an AWS Directory Service domain. Before
executing this command you must create a directory. We also recommend that you learn more about the
AWS Directory Service. For more information, see What Is AWS Directory Service?.

637
 AWS Systems Manager User Guide
Run Command Walkthroughs

Currently you can only join an instance to a domain. You cannot remove an instance from a domain.
Note
For information about rebooting servers and instances when using Run Command to call scripts,
see Rebooting Managed Instance from Scripts (p. 625).

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-JoinDirectoryServiceDomain"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-JoinDirectoryServiceDomain" | select -ExpandProperty

Parameters

Join an instance to a domain

The following command joins the instance to the given AWS Directory Service domain and uploads any
generated output to the Amazon S3 bucket.

$domainJoinCommand=Send-SSMCommand -InstanceId Instance-ID -DocumentName

AWS-JoinDirectoryServiceDomain -Parameter @{'directoryId'='d-9067386b64';
'directoryName'='ssm.test.amazon.com'; 'dnsIpAddresses'=@('172.31.38.48',
'172.31.55.243')} -OutputS3BucketName demo-ssm-output-bucket

Get command information per instance

The following command uses the Command ID to get the status of the command execution.

Get-SSMCommandInvocation -CommandId $domainJoinCommand.CommandId -Details $true

Get command information with response data for the instance

This command returns the output of the original Send-SSMCommand for the specific command ID.

Get-SSMCommandInvocation -CommandId $domainJoinCommand.CommandId -Details $true | select -

ExpandProperty CommandPlugins

Send Windows Metrics to Amazon CloudWatch using the AWS-

ConfigureCloudWatch document
You can send Windows Server messages in the application, system, security, and Event Tracing for
Windows (ETW) logs to Amazon CloudWatch Logs. When you enable logging for the first time, Systems
Manager sends all logs generated within one (1) minute from the time that you start uploading logs for
the application, system, security, and ETW logs. Logs that occurred before this time are not included.
If you disable logging and then later re-enable logging, Systems Manager sends logs from the time it
left off. For any custom log files and Internet Information Services (IIS) logs, Systems Manager reads the
log files from the beginning. In addition, Systems Manager can also send performance counter data to
Amazon CloudWatch.

If you previously enabled CloudWatch integration in EC2Config, the Systems Manager settings override
any settings stored locally on the instance in the C:\Program Files\Amazon\EC2ConfigService\Settings
\AWS.EC2.Windows.CloudWatch.json file. For more information about using EC2Config to manage
performance counters and logs on single instance, see Sending Performance Counters to CloudWatch
and Logs to CloudWatch Logs.

638
 AWS Systems Manager User Guide
Run Command Walkthroughs

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-ConfigureCloudWatch"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-ConfigureCloudWatch" | select -ExpandProperty

Parameters

Send Application Logs to CloudWatch

The following command configures the instance and moves Windows Applications logs to CloudWatch.

$cloudWatchCommand=Send-SSMCommand -InstanceID Instance-ID -DocumentName

'AWS-ConfigureCloudWatch' -Parameter @{'properties'='{"engineConfiguration":
{"PollInterval":"00:00:15", "Components":[{"Id":"ApplicationEventLog",
"FullName":"AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch",
"Parameters":{"LogName":"Application", "Levels":"7"}},{"Id":"CloudWatch",
"FullName":"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch",
"Parameters":{"Region":"us-east-2", "LogGroup":"My-Log-Group",
"LogStream":"i-02573cafcfEXAMPLE"}}], "Flows":{"Flows":
["ApplicationEventLog,CloudWatch"]}}}'}

Get command information per instance

The following command uses the Command ID to get the status of the command execution.

Get-SSMCommandInvocation -CommandId $cloudWatchCommand.CommandId -Details $true

Get command information with response data for a specific instance

The following command returns the results of the Amazon CloudWatch configuration.

Get-SSMCommandInvocation -CommandId $cloudWatchCommand.CommandId -Details $true -

InstanceId Instance-ID | select -ExpandProperty CommandPlugins

Send Performance Counters to CloudWatch Using the AWS-ConfigureCloudWatch document

The following demonstration command uploads performance counters to CloudWatch. For more
information, see the Amazon CloudWatch User Guide.

$cloudWatchMetricsCommand=Send-SSMCommand -InstanceID Instance-ID -DocumentName

'AWS-ConfigureCloudWatch' -Parameter @{'properties'='{"engineConfiguration":
{"PollInterval":"00:00:15", "Components":[{"Id":"PerformanceCounter",
"FullName":"AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AW
"Parameters":{"CategoryName":"Memory", "CounterName":"Available
MBytes", "InstanceName":"", "MetricName":"AvailableMemory",
"Unit":"Megabytes","DimensionName":"", "DimensionValue":""}},{"Id":"CloudWatch",
"FullName":"AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch
"Parameters":{"AccessKey":"", "SecretKey":"","Region":"us-east-2", "NameSpace":"Windows-
Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'}

Update EC2Config Using the AWS-UpdateEC2Config Document

Using Run Command and the AWS-EC2ConfigUpdate document, you can update the EC2Config service
running on your Windows instances. This command can update the EC2Config service to the latest
version or a version you specify.

639
 AWS Systems Manager User Guide
Run Command Walkthroughs

View the description and available parameters

Get-SSMDocumentDescription -Name "AWS-UpdateEC2Config"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-UpdateEC2Config" | select -ExpandProperty Parameters

Update EC2Config to the latest version

Send-SSMCommand -InstanceId Instance-ID -DocumentName "AWS-UpdateEC2Config"

Get command information with response data for the instance

This command returns the output of the specified command from the previous Send-SSMCommand:

Get-SSMCommandInvocation -CommandId ID -Details $true -InstanceId Instance-ID | select -

ExpandProperty CommandPlugins

Update EC2Config to a specific version

The following command will downgrade EC2Config to an older version:

Send-SSMCommand -InstanceId Instance-ID -DocumentName "AWS-UpdateEC2Config" -Parameter

@{'version'='3.8.354'; 'allowDowngrade'='true'}

Enable/Disable Windows Automatic Update Using the AWS-

ConfigureWindowsUpdate document
Using Run Command and the AWS-ConfigureWindowsUpdate document, you can enable or disable
automatic Windows updates on your Windows instances. This command configures the Windows update
agent to download and install Windows updates on the day and hour that you specify. If an update
requires a reboot, the computer reboots automatically 15 minutes after updates have been installed.
With this command you can also configure Windows update to check for updates but not install them.
The AWS-ConfigureWindowsUpdate document is compatible with Windows Server 2008, 2008 R2, 2012,
2012 R2, and 2016.

View the description and available parameters

Get-SSMDocumentDescription –Name "AWS-ConfigureWindowsUpdate"

View more information about parameters

Get-SSMDocumentDescription -Name "AWS-ConfigureWindowsUpdate" | select -ExpandProperty

Parameters

Enable Windows automatic update

The following command configures Windows Update to automatically download and install updates
daily at 10:00 pm.

$configureWindowsUpdateCommand = Send-SSMCommand -InstanceId Instance-ID -DocumentName

'AWS-ConfigureWindowsUpdate' -Parameters @{'updateLevel'='InstallUpdatesAutomatically';
'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}

640
 AWS Systems Manager User Guide
Run Command Walkthroughs

View command status for enabling Windows automatic update

The following command uses the Command ID to get the status of the command execution for enabling
Windows Automatic Update.

Get-SSMCommandInvocation -Details $true -CommandId $configureWindowsUpdateCommand.CommandId

| select -ExpandProperty CommandPlugins

Disable Windows automatic update

The following command lowers the Windows Update notification level so the system checks for updates
but does not automatically update the instance.

$configureWindowsUpdateCommand = Send-SSMCommand -InstanceId Instance-ID -DocumentName

'AWS-ConfigureWindowsUpdate' -Parameters @{'updateLevel'='NeverCheckForUpdates'}

View command status for disabling Windows automatic update

The following command uses the Command ID to get the status of the command execution for disabling
Windows automatic update.

Get-SSMCommandInvocation -Details $true -CommandId $configureWindowsUpdateCommand.CommandId

| select -ExpandProperty CommandPlugins

Manage Windows Updates Using Run Command

Using Run Command and the AWS-InstallWindowsUpdates document, you can manage updates for
Amazon EC2 Windows instances. This command scans for or installs missing updates on your EC2
Windows instances and optionally reboots following installation. You can also specify the appropriate
classifications and severity levels for updates to install in your environment.
Note
For information about rebooting servers and instances when using Run Command to call scripts,
see Rebooting Managed Instance from Scripts (p. 625).

The following examples demonstrate how to perform the specified Windows Update management tasks.

Search for all missing Windows updates

Send-SSMCommand `
-InstanceId Instance-ID `
-DocumentName 'AWS-InstallWindowsUpdates' `
-Parameters @{'Action'='Scan'}

Install specific Windows updates

Send-SSMCommand `
-InstanceId Instance-ID `
-DocumentName 'AWS-InstallWindowsUpdates' `
-Parameters
@{'Action'='Install';'IncludeKbs'='KB4503308,KB890830,KB4507419';'AllowReboot'='True'}

Install important missing Windows updates

Send-SSMCommand `

641
 AWS Systems Manager User Guide
Troubleshooting Run Command

-InstanceId Instance-ID `
-DocumentName 'AWS-InstallWindowsUpdates' `
-Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'}

Install missing Windows updates with specific exclusions

Send-SSMCommand `
-InstanceId i-047e6c6dcb97b18da `
-DocumentName 'AWS-InstallWindowsUpdates' `
-Parameters @{'Action'='Install';'ExcludeKbs'='KB2267602,KB4052623';'AllowReboot'='True'}

Troubleshooting Systems Manager Run Command

Run Command provides status details with each command execution. For more information about the
details of command statuses, see Understanding Command Statuses (p. 627). You can also use the
information in this topic to help troubleshoot problems with Run Command.

Topics
• Where Are My Instances? (p. 642)
• Getting Status Information on Windows Instances (p. 642)
• Getting Status Information on Linux Instances (p. 643)
• Troubleshooting SSM Agent (p. 643)

Where Are My Instances?

In the Run a command page, after you choose an SSM document to run and select Manually selecting
instances in the Targets section, a list is displayed of instances you can choose to run the command on. If
an instance you expect to see is not listed, check the following requirements:

• SSM Agent: Make sure the latest version of SSM Agent is installed on the instance. Only Amazon
EC2 Windows Amazon Machine Images (AMIs) and some Linux AMIs are pre-configured with SSM
Agent. For information about installing or reinstalling SSM Agent on an instance, see Installing and
Configuring SSM Agent on Amazon EC2 Linux Instances (p. 68) or Installing and Configuring SSM
Agent on Windows Instances (p. 65).
• IAM instance role: Verify that the instance is configured with an AWS Identity and Access Management
(IAM) role that enables the instance to communicate with the Systems Manager API. Also verify
that your user account has an IAM user trust policy that enables your account to communicate with
the Systems Manager API. For more information, see Create an IAM Instance Profile for Systems
Manager (p. 29).
• Target operating system type: Double-check that you have selected an SSM document that
supports the type of instance you want to update. Most SSM documents support both Windows
and Linux instances, but some do not. For example, if you select the SSM document AWS-
InstallPowerShellModule, which applies only to Windows instances, you will not see Linux
instances in the target instances list.

Getting Status Information on Windows Instances

Use the following command to get status details about one or more instances:

Get-SSMInstanceInformation -InstanceInformationFilterList
@{Key="InstanceIds";ValueSet="instance-ID","instance-ID"}

642
 AWS Systems Manager User Guide
Troubleshooting Run Command

Use the following command with no filters to see all instances registered to your account that are
currently reporting an online status. Substitute the ValueSet="Online" with "ConnectionLost" or
"Inactive" to view those statuses:

Get-SSMInstanceInformation -InstanceInformationFilterList
@{Key="PingStatus";ValueSet="Online"}

Use the following command to see which instances are running the latest version of the EC2Config
service. Substitute ValueSet="LATEST" with a specific version (for example, 3.0.54 or 3.10) to view those
details:

Get-SSMInstanceInformation -InstanceInformationFilterList
@{Key="AgentVersion";ValueSet="LATEST"}

Getting Status Information on Linux Instances

Use the following command to get status details about one or more instances:

aws ssm describe-instance-information --instance-information-filter-list

key=InstanceIds,valueSet=instance-ID

Use the following command with no filters to see all instances registered to your account that are
currently reporting an online status. Substitute the ValueSet="Online" with "ConnectionLost" or
"Inactive" to view those statuses:

aws ssm describe-instance-information --instance-information-filter-list

key=PingStatus,valueSet=Online

Use the following command to see which instances are running the latest version of SSM Agent.
Substitute ValueSet="LATEST" with a specific version (for example, 1.0.145 or 1.0) to view those details:

aws ssm describe-instance-information --instance-information-filter-list

key=AgentVersion,valueSet=LATEST

If the describe-instance-information API operation returns an AgentStatus of Online, then your instance
is ready to be managed using Run Command. If the status is Inactive, the instance has one or more of the
following problems.

• SSM Agent is not installed.

• The instance does not have outbound internet connectivity.
• The instance was not launched with an IAM role that enables it to communicate with the SSM API, or
the permissions for the IAM role are not correct for Run Command. For more information, see Create
an IAM Instance Profile for Systems Manager (p. 29).

Troubleshooting SSM Agent

If you experience problems executing commands using Run Command, there might be a problem with
SSM Agent. Use the following information to help you view SSM Agent log files and troubleshoot the
agent.

Topics
• View SSM Agent Log Files (p. 644)
• Enable SSM Agent Debug Logging (p. 644)

643
 AWS Systems Manager User Guide
Troubleshooting Run Command

View SSM Agent Log Files

SSM Agent logs information in the following files. The information in these files can help you
troubleshoot problems.
Note
If you choose to view these logs by using Windows File Explorer, be sure to enable the viewing
of hidden files and system files in Folder Options.

On Windows

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

On Linux

• /var/log/amazon/ssm/amazon-ssm-agent.log
• /var/log/amazon/ssm/errors.log

Enable SSM Agent Debug Logging

Use the follow procedure to enable SSM Agent debug logging on Windows Server and Linux managed
instances.

1. Either use Systems Manager Session Manager to connect to the instance where you want to enable
debug logging, or log on to the managed instance. For more information, see Working with Session
Manager (p. 598).
2. Make a copy of the seelog.xml.template file. Change the name of the copy to seelog.xml. The file is
located in the following directory:

1. Windows Server: %PROGRAMFILES%\Amazon\SSM\seelog.xml.template

2. Linux: /etc/amazon/ssm/seelog.xml.template
3. Edit the seelog.xml file to change the default logging behavior. Change the value of minlevel
from info to debug, as shown in the following example.

<seelog type="adaptive" mininterval="2000000" maxinterval="100000000"

critmsgcount="500" minlevel="debug">

4. Windows only: Locate the following entry:

filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\amazon-ssm-agent.log"

Change this entry to use the following path:

filename="C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log"

5. Windows only: Locate the following entry:

filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\errors.log"

Change this entry to use the following path:

filename="C:\ProgramData\Amazon\SSM\Logs\errors.log"

644
 AWS Systems Manager User Guide
State Manager

6. Restart SSM Agent.

• Windows Server: Use Windows Services Manager to restart the Amazon SSM Agent.
• Linux: Run the following command:

sudo restart amazon-ssm-agent

AWS Systems Manager State Manager

AWS Systems Manager State Manager is a secure and scalable configuration management service that
automates the process of keeping your Amazon EC2 and hybrid infrastructure in a state that you define.

The following list describes the types of tasks you can perform with State Manager.

• Bootstrap instances with specific software at start-up

• Download and update agents on a defined schedule, including SSM Agent
• Configure network settings
• Join instances to a Windows domain (Windows instances only)
• Patch instances with software updates throughout their lifecycle
• Run scripts on Linux and Windows managed instances throughout their lifecycle

State Manager integrates with AWS CloudTrail to provide a record of all executions that you can audit,
and Amazon CloudWatch Events to track state changes. You can also choose to store and view detailed
command output in Amazon S3. For more information, see the following topics:

• Logging AWS Systems Manager API Calls with AWS CloudTrail (p. 889)
• Monitoring Systems Manager Events with Amazon CloudWatch Events (p. 891)
• (Optional) Set Up Integrations with Other AWS Services (p. 40)

Getting Started with State Manager

Complete the following tasks to get started with State Manager.

Task For More Information

Verify Systems Manager prerequisites Systems Manager Prerequisites (p. 12)

Learn more about State Manager About State Manager (p. 646)

Create and assign a State Manager association to Create an Association (p. 647)
your instances

Related Content

See the following blog posts for additional examples of how to use State Manager:

• Combating Configuration Drift Using Amazon EC2 Systems Manager and Windows PowerShell DSC
• Configure Amazon EC2 Instances in an Auto Scaling Group Using State Manager

Topics

645
 AWS Systems Manager User Guide
About State Manager

• About State Manager (p. 646)

• Working with Associations in Systems Manager (p. 647)
• Systems Manager State Manager Walkthroughs (p. 667)

About State Manager

AWS Systems Manager State Manager is a secure and scalable service that automates the process of
keeping your Amazon EC2 and hybrid infrastructure in a state that you define.

Here's how it works:

1. Determine the state you want to apply to your managed instances.

Do you want to ensure that your managed instance are configured with specific applications, such
as anti-virus or malware applications? Do you want to automate the process of updating the SSM
Agent or other AWS packages such as AWSPVDriver? Do you need to ensure that specific ports are
closed or open? To get started with State Manager, determine the state that you want to apply to
your managed instances. The state that you want to apply will determine which SSM document you
use to create a State Manager association.

A State Manager association is a configuration that is assigned to your managed instances. The
configuration defines the state that you want to maintain on your instances. For example, an
association can specify that anti-virus software must be installed and running on your instances, or
that certain ports must be closed. The association specifies a schedule for when the configuration
is reapplied. The association also specifies actions to take when applying the configuration. For
example, an association for anti-virus software might run once a day. If the software is not installed,
then State Manager installs it. If the software is installed, but the service is not running, then the
association might instruct State Manager to start the service.
2. Determine if a preconfigured SSM document can help you create the State Manager association.

State Manager uses SSM documents to create an association. Systems Manager includes dozens of
preconfigured SSM documents that you can use to create an association. Preconfigured documents
are ready to perform common tasks like installing applications, configuring Amazon CloudWatch,
running Systems Manager Automations, running PowerShell and Shell scripts, and joining a
Directory Service domain for Active Directory, to name a few. You simply need to specify the name
of the document and information for the required parameters, and then run the command to create
the association. You can view all SSM documents in the Systems Manager console.

You can then choose the name of a document to learn more about each one. Here are two examples:
AWS-ConfigureAWSPackage and AWS-InstallApplication.
3. Create the association.

You can create the association by using the AWS Systems Manager console, the AWS CLI, AWS Tools
for Windows PowerShell, or the Systems Manager API. When you create the association, you specify
the following information:
1. The parameters for the SSM document (for example, the path to the application to install or the
script to run on the instances).
2. A schedule for when or how often to apply the state. You can specify a cron or rate expression.
For more information about creating schedules by using cron and rate expressions, see Cron and
Rate Expressions for Associations (p. 937).
3. Targets for the association. You can target managed instances by individually specifying IDs, or
you can target large groups of managed instances by specifying Amazon EC2 tags. You can also
target all managed instances in the current AWS Region and AWS account.

When you run the command to create the association, Systems Manager binds the information
you specified (schedule, targets, SSM document, and parameters) to the managed instances. The

646
 AWS Systems Manager User Guide
Working with Associations

status of the association initially shows "Pending" as the system attempts to reach all targets and
immediately apply the state specified in the association.
Note
If you create a new association that is scheduled to run while an earlier association is still
running, the earlier association is timed out and the new association runs.

Systems Manager reports the status of the request to create associations on the managed instances.
You can view status details in the console or by using the DescribeInstanceAssociationsStatus
API action. If you choose to write the output of the command to Amazon S3 when you create an
association, you can also view the output in the Amazon S3 bucket you specify.

For more information, see Create an Association (p. 647).

4. Monitor and update.

After you create the association, State Manager reapplies the configuration according to the
schedule that you defined in the association. You can view the status of your associations on
the State Manager page in the console or by directly calling the association ID generated by
Systems Manager when you created the association. For more information, see Viewing Association
Histories (p. 660). You can update your association documents and reapply them as necessary. You
can also create multiple versions of an association. For more information, see Edit and Create a New
Version of an Association (p. 656).

Working with Associations in Systems Manager

A State Manager association is a configuration that is assigned to your managed instances. The
configuration defines the state that you want to maintain on your instances. For example, an association
can specify that anti-virus software must be installed and running on your instances, or that certain
ports must be closed. The association specifies a schedule for when the configuration is reapplied. The
association also specifies actions to take when applying the configuration. For example, an association
for anti-virus software might run once a day. If the software is not installed, then State Manager installs
it. If the software is installed, but the service is not running, then the association might instruct State
Manager to start the service.

Use the following topics to help you create and manage State Manager associations.

Topics
• Create an Association (p. 647)
• Using Targets and Rate Controls with State Manager Associations (p. 651)
• Edit and Create a New Version of an Association (p. 656)
• Viewing Association Histories (p. 660)

Create an Association
The following procedures describe how to create a State Manager association by using the AWS Systems
Manager console, AWS Command Line Interface (AWS CLI), and AWS Tools for Windows PowerShell.
Important
The following procedures are intended for creating an association with a Command or Policy
document. For information on creating an association that uses an Automation document, see
Running Automation Workflows with Triggers Using State Manager (p. 182).

When a State Manager association is created, the association immediately runs on the specified instances
or targets. After the initial execution, the association runs in intervals according to the schedule that you
defined and according to the following rules:

647
 AWS Systems Manager User Guide
Working with Associations

• Associations are only run on instances that are online when the interval starts. Offline instances are
skipped.
• State Manager attempts to run the association on all configured instances during an interval.
• If an association is not run during an interval (because, for example, a concurrency value limited the
number of instances that could process the association at one time), then State Manager attempts to
run the association during the next interval.
• State Manager records history for all skipped intervals. You can view the history on the Execution
History tab.

Create an Association (Console)

The following procedure describes how to use the Systems Manager console to create a State Manager
association.

To create a State Manager association

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager, and then choose Create association.
3. In the Name field, specify a name. This is optional, but recommended. A name
helps you remember the purpose of the association. For example, you could specify
Automatically_update_AWSPVDrivers_on_us-west-2_instances for an association with that
purpose. Spaces aren't allowed in the name.
4. In the Document list, choose the option next to a document name. You can use the numbers to the
right of the Search bar to view more documents.
5. For Parameters, specify the required input parameters.
6. For Targets, choose an option. For information about using targets, see Using Targets and Rate
Controls with State Manager Associations (p. 651).
Note
If you use tags to create an association on one or more target instances, and then you
remove the tags from an instance, that instance no longer runs the association. The
instance is disassociated from the State Manager document.
7. In the Specify schedule section, choose either On Schedule or No schedule. If you choose On
Schedule, then use the buttons provided to create a cron or rate schedule for the association.
8. In the Advanced options section:

• In Compliance severity, choose a severity level for the association. Compliance reporting indicates
whether the association state is compliant or noncompliant, along with the severity level you
indicate here. For more information, see About State Manager Association Compliance (p. 508).
9. In the Rate control section, configure options to run State Manager associations across a fleet of
managed instances. For information about using rate controls, see Using Targets and Rate Controls
with State Manager Associations (p. 651).

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the association
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the association
simultaneously.

In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors that are allowed before State Manager stops
running associations on additional targets.

648
 AWS Systems Manager User Guide
Working with Associations

• Choose percentage to enter a percentage of errors that are allowed before State Manager stops
running associations on additional targets.
10. In the Output options section, choose Enable writing output to S3 if you want to write the output
of the command to create the associations to an Amazon S3 bucket.
11. Choose Create Association.

Create an Association (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to create an association.

To create a State Manager association

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Use the following format to create a command that creates a State Manager association.

Linux

aws ssm create-association \

--targets Key=tag:TagKey,Values=TagValue \
--name document_name \
--schedule "cron_or_rate_expression" \
--parameters (if any)

Note
If you create an association by using the AWS CLI, use the --Targets parameter to
target instances for the association. Don't use the --InstanceID parameter. The --
InstanceID parameter is a legacy parameter.
Windows

aws ssm create-association ^

--targets Key=tag:TagKey,Values=TagValue ^
--name document_name ^
--schedule "cron_or_rate_expression" ^
--parameters (if any)

Note
If you create an association by using the AWS CLI, use the --Targets parameter to
target instances for the association. Don't use the --InstanceID parameter. The --
InstanceID parameter is a legacy parameter.
PowerShell

New-SSMAssociation `
-AssociationName document_name `
-Target Targets `
-ScheduleExpression "cron_or_rate_expression" `
-Parameters (if any)

Note
If you create an association by using AWS Tools for Windows PowerShell, use the -
Target parameter to target instances for the association. Don't use the -InstanceID
parameter. The -InstanceID parameter is a legacy parameter.

649
 AWS Systems Manager User Guide
Working with Associations

The following example creates an association on instances tagged with "Environment,Linux".

The association uses the AWS-UpdateSSMAgent document to update SSM Agent on the targeted
instances at 2:00 every Sunday morning. For compliance reporting, this association is assigned a
severity level of Medium.

Linux

aws ssm create-association \

--association-name Update_SSM_Agent_Linux \
--targets Key=tag:Environment,Values=Linux \
--name AWS-UpdateSSMAgent \
--compliance-severity "MEDIUM" \
--schedule "cron(0 2 ? * SUN *)"

Windows

aws ssm create-association ^

--association-name Update_SSM_Agent_Linux ^
--targets Key=tag:Environment,Values=Linux ^
--name AWS-UpdateSSMAgent ^
--compliance-severity "MEDIUM" ^
--schedule "cron(0 2 ? * SUN *)"

PowerShell

New-SSMAssociation `
-AssociationName Update_SSM_Agent_Linux `
-Name AWS-UpdateSSMAgent `
-Target @{
"Key"="tag:Environment"
"Values"="Linux"
} `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-ComplianceSeverity MEDIUM

The following example targets instance IDs by specifying a wildcard value (*). This enables Systems
Manager to create an association on all instances in the current account and AWS Region.

Linux

aws ssm create-association \

--association-name Update_SSM_Agent_Linux \
--name "AWS-UpdateSSMAgent" \
--targets "Key=instanceids,Values=*" \
--compliance-severity "MEDIUM" \
--schedule "cron(0 2 ? * SUN *)"

Windows

aws ssm create-association ^

--association-name Update_SSM_Agent_Linux ^
--name "AWS-UpdateSSMAgent" ^
--targets "Key=instanceids,Values=*" ^
--compliance-severity "MEDIUM" ^
--schedule "cron(0 2 ? * SUN *)"

650
 AWS Systems Manager User Guide
Working with Associations

PowerShell

New-SSMAssociation `
-AssociationName Update_SSM_Agent_All `
-Name AWS-UpdateSSMAgent `
-Target @{
"Key"="InstanceIds"
"Values"="*"
} `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-ComplianceSeverity MEDIUM

Note
If you use tags to create an association on one or more target instances, and then you
remove the tags from an instance, that instance no longer runs the association. The
instance is disassociated from the State Manager document.

Using Targets and Rate Controls with State Manager

Associations
AWS Systems Manager enables you to create State Manager associations on a fleet of managed instances
by using targets. Additionally, you can control the execution of these associations across your fleet
by specifying a concurrency value and an error threshold. The concurrency value specifies how many
resources are allowed to run the association simultaneously. An error threshold specifies how many
association executions can fail before Systems Manager sends a command to each instance configured
with that association. The command stops the association from running until the next scheduled
execution. The concurrency and error threshold features are collectively called rate controls.

Concurrency

Concurrency helps to limit the impact on your fleet by allowing you to specify that only a certain number
of instances can process an association at one time. You can specify either an absolute number of
instances, for example 20, or a percentage of the target set of instances, for example 10%.

State Manager concurrency has the following restrictions and limitations:

• If you choose to create an association by using targets, but you don't specify a concurrency value, then
State Manager automatically enforces a maximum concurrency of 50 instances.
• If new instances that match the target criteria come online while an association that uses concurrency
is running, then the new instances run the association if the concurrency value is not exceeded. If the
concurrency value is exceeded, then the instances are ignored during the current association execution
interval. The instances run the association during the next scheduled interval while conforming to the
concurrency requirements.
• If you update an association that uses concurrency, and one or more instances are processing that
association when it is updated, then any instance that is running the association is allowed to
complete. Those associations that haven't started are stopped. After running associations complete, all
target instances immediately run the association again because it was updated. When the association
runs again, the concurrency value is enforced.

Error Thresholds

An error threshold specifies how many association executions are allowed to fail before Systems Manager
sends a command to each instance configured with that association. The command stops the association

651
 AWS Systems Manager User Guide
Working with Associations

from running until the next scheduled execution. You can specify either an absolute number of errors, for
example 10, or a percentage of the target set, for example 10%.

If you specify an absolute number of three errors, for example, State Manager sends the stop command
when the fourth error is returned. If you specify 0, then State Manager sends the stop command after
the first error result is returned.

If you specify an error threshold of 10% for 50 associations, then State Manager sends the stop
command when the sixth error is returned. Associations that are already running when an error threshold
is reached are allowed to complete, but some of these associations might fail. To ensure that there aren't
more errors than the number specified for the error threshold, set the Concurrency value to 1 so that
associations proceed one at a time.

State Manager error thresholds have the following restrictions and limitations:

• Error thresholds are enforced for the current interval.

• Information about each error, including step-level details, is recorded in the association history.
• If you choose to create an association by using targets, but you don't specify an error threshold, then
State Manager automatically enforces a threshold of 100% failures.

Targets

You can create associations on tens, hundreds, or thousands of instances by using the targets
parameter. The targets parameter accepts a Key,Value combination based on resource tags that you
specified for your instances. When you run the request to create the association, the system locates and
attempts to create the association on all instances that match the specified criteria. After the association
is created and assigned to the instance or to a target set of instances, then State Manager immediately
runs the association.
Note
When you create an association, you specify when the schedule runs. You must specify the
schedule by using a cron or rate expression. There are many tools on the internet to help you
create these expressions. For more information about cron and rate expressions, see Cron and
Rate Expressions for Associations (p. 937).

Create an Association That Uses Targets and Rate Controls (Console)

The following procedure describes how to use the Systems Manager console to create a State Manager
association that uses targets and rate controls.
Important
The following procedure is intended for creating an association with a Command or Policy
document. For information on creating an association that uses an Automation document, see
Running Automation Workflows with Triggers Using State Manager (p. 182).

To create a State Manager association that uses targets and rate controls

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager, and then choose Create association.
3. In the Name field, specify a name. This is optional, but recommended. A name helps you
remember the purpose of the association when you created it. For example, you could specify
Automatically_update_AWSPVDrivers_on_us-west-2_instances for an association with that
purpose. Spaces aren't allowed in the name.
4. In the Document list, choose the option next to a document name. You can use the numbers to the
right of the Search bar to view more documents.
5. For Parameters, specify the required input parameters.
6. In the Targets section, choose either Selecting all managed instances in this region under this
account or Specifying tags. If you choose to target tags, then enter a tag key and a tag value.

652
 AWS Systems Manager User Guide
Working with Associations

Note
If you use tags to create an association on one or more target instances, and then you
remove the tags from an instance, that instance no longer runs the association. The
instance is disassociated from the State Manager document.
7. In the Specify schedule section, choose either On Schedule or No schedule. If you choose On
Schedule, then use the buttons provided to create a cron or rate schedule for the association.
8. In the Advanced options section:

• In Compliance severity, choose a severity level for the association. Compliance reporting indicates
whether the association state is compliant or noncompliant, along with the severity level you
indicate here. For more information, see About State Manager Association Compliance (p. 508).
9. In the Rate control section, configure options to run State Manager associations across a fleet of
managed instances.

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the association
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the association
simultaneously.

In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors that are allowed before State Manager stops
running associations on additional targets.
• Choose percentage to enter a percentage of errors that are allowed before State Manager stops
running associations on additional targets.
10. In the Output options section, choose Enable writing output to S3 if you want to write the output
of the command to create the associations to an Amazon S3 bucket.
11. Choose Create Association.

Create an Association That Uses Targets and Rate Controls (Command Line)
The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to create a State Manager association that uses targets and rate controls.

To create an association with targets and rate controls

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Use the following format to create a command that creates a State Manager association that uses
targets and rate controls.

Linux

aws ssm create-association \

--targets Key=tag:TagKey,Values=TagValue \
--name document_name \
--schedule "cron_or_rate_expression" \
--parameters (if any) \
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
--max-errors a_number_of_errors_or_a_percentage_of_target_set

653
 AWS Systems Manager User Guide
Working with Associations

Windows

aws ssm create-association ^

--targets Key=tag:TagKey,Values=TagValue ^
--name document_name ^
--schedule "cron_or_rate_expression" ^
--parameters (if any) ^
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
--max-errors a_number_of_errors_or_a_percentage_of_target_set

PowerShell

New-SSMAssociation `
-AssociationName document_name `
-Target Targets `
-ScheduleExpression "cron_or_rate_expression" `
-Parameters (if any) `
-MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
-MaxError a_number_of_errors_or_a_percentage_of_target_set

The following example creates an association on instances tagged with "Environment,Linux".

The association uses the AWS-UpdateSSMAgent document to update SSM Agent on the targeted
instances at 2:00 every Sunday morning. This association runs simultaneously on 10 instances
maximum at any given time. Also, this association stops running on more instances for a particular
execution interval if the error count exceeds 5. For compliance reporting, this association is assigned
a severity level of Medium.

Linux

aws ssm create-association \

--association-name Update_SSM_Agent_Linux \
--targets Key=tag:Environment,Values=Linux \
--name AWS-UpdateSSMAgent \
--compliance-severity "MEDIUM" \
--schedule "cron(0 2 ? * SUN *)" \
--max-errors "5" \
--max-concurrency "10"

Windows

aws ssm create-association ^

--association-name Update_SSM_Agent_Linux ^
--targets Key=tag:Environment,Values=Linux ^
--name AWS-UpdateSSMAgent ^
--compliance-severity "MEDIUM" ^
--schedule "cron(0 2 ? * SUN *)" ^
--max-errors "5" ^
--max-concurrency "10"

PowerShell

New-SSMAssociation `
-AssociationName Update_SSM_Agent_Linux `
-Name AWS-UpdateSSMAgent `
-Target @{
"Key"="tag:Environment"
"Values"="Linux"

654
 AWS Systems Manager User Guide
Working with Associations

} `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-MaxConcurrency 10 `
-MaxError 5 `
-ComplianceSeverity MEDIUM

The following example targets instance IDs by specifying a wildcard value (*). This enables Systems
Manager to create an association on all instances in the current account and AWS Region. This
association runs simultaneously on 10 instances maximum at any given time. Also, this association
stops running on more instances for a particular execution interval if the error count exceeds 5. For
compliance reporting, this association is assigned a severity level of Medium.

Linux

aws ssm create-association \

--association-name Update_SSM_Agent_Linux \
--name "AWS-UpdateSSMAgent" \
--targets "Key=instanceids,Values=*" \
--compliance-severity "MEDIUM" \
--schedule "cron(0 2 ? * SUN *)" \
--max-errors "5" \
--max-concurrency "10"

Windows

aws ssm create-association ^

--association-name Update_SSM_Agent_Linux ^
--name "AWS-UpdateSSMAgent" ^
--targets "Key=instanceids,Values=*" ^
--compliance-severity "MEDIUM" ^
--schedule "cron(0 2 ? * SUN *)" ^
--max-errors "5" ^
--max-concurrency "10"

PowerShell

New-SSMAssociation `
-AssociationName Update_SSM_Agent_All `
-Name AWS-UpdateSSMAgent `
-Target @{
"Key"="InstanceIds"
"Values"="*"
} `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-MaxConcurrency 10 `
-MaxError 5 `
-ComplianceSeverity MEDIUM

Note
If you use tags to create an association on one or more target instances, and then you
remove the tags from an instance, that instance no longer runs the association. The
instance is disassociated from the State Manager document.

655
 AWS Systems Manager User Guide
Working with Associations

Edit and Create a New Version of an Association

You can edit an association to specify a new name, schedule, severity level, or targets. You can also
choose to write the output of the command to an Amazon S3 bucket. After you edit an association,
Systems Manager creates a new version. You can view different versions after editing, as described in the
following procedures.

The following procedures describe how to edit and create a new version of an association using the AWS
Systems Manager console, AWS Command Line Interface (AWS CLI), and AWS Tools for PowerShell.

Edit and Create a New Version of an Association (Console)

The following procedure describes how to use the Systems Manager console to edit and create a new
version of an association.
Note
This procedure requires that you have write access to an existing S3 bucket. If you have not used
Amazon S3 before, be aware that you will incur charges for using Amazon S3. For information
about how to create a bucket, see Create a Bucket.

To edit a State Manager association

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose State Manager.
3. Choose the association you created in the previous procedure, and then choose Edit.
4. In the Name field, type a new name. For example, type TestHostnameAssociation2.
5. In the Specify schedule section, choose a new option. For example, choose CRON schedule builder,
and then choose Every 1 hour.
6. (Optional) To write the command output to an Amazon S3 bucket, do the following in the Output
options section:

• Choose Enable writing output to S3.

• In the S3 bucket name field, type the name of an S3 bucket you have write access to.
• (Optional) To write output to a folder in the bucket, type its name in the S3 key prefix field. If no
folder exists with the name you specify, State Manager creates it for you.
7. Choose Edit association.
8. In the Associations page, choose the name of the association you just edited, and then choose the
Versions tab. The system lists each version of the association you created and edited.
9. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.
10. Choose the name of the S3 bucket you specified for storing command output, and then choose the
folder named with the ID of the instance that ran the association. (If you chose to store output in a
folder in the bucket, open it first.)
11. Drill down several levels, through the awsrunPowerShell folder, to the stdout file.
12. Choose Open or Download to view the host name.

Edit and Create a New Version of an Association (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to edit and create a new version of an association.

656
 AWS Systems Manager User Guide
Working with Associations

To edit a State Manager association

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Use the following format to create a command to edit and create a new version of an existing State
Manager association.

Linux

aws ssm update-association \

--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE \
--association-name association_name \
--parameters (if any) \
--output-location
S3Location='{OutputS3Region=region,OutputS3BucketName=bucketname,OutputS3KeyPrefix=keyprefix}'
\
--scheduleexpression "cron_or_rate_expression"

Important
To retain existing parameter values of your association, such as association name or
compliance severity, you must specify these values when you update the association.
If you don't specify these parameter values when you update an association, the new
association version uses no values. For example, if your existing association has a cron
schedule but you don't specify --schedule-expression when updating, the new
association version will not have a schedule expression.
Windows

aws ssm update-association ^

--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE ^
--association-name association_name ^
--parameters (if any) ^
--output-location
S3Location='{OutputS3Region=region,OutputS3BucketName=bucketname,OutputS3KeyPrefix=keyprefix}'
^
--scheduleexpression "cron_or_rate_expression"

Important
To retain existing parameter values of your association, such as association name or
compliance severity, you must specify these values when you update the association.
If you don't specify these parameters when you update an association, the new
association version uses the default values (none). For example, if your existing
association has a cron schedule but you don't specify --schedule-expression when
updating, the new association version will not have a schedule expression.
PowerShell

Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName document_name `
-Parameter (if any) `
-S3Location_OutputS3BucketName bucket_name `
-S3Location_OutputS3KeyPrefix key_prefix `
-S3Location_OutputS3Region region `
-ScheduleExpression "cron_or_rate_expression"

657
 AWS Systems Manager User Guide
Working with Associations

Important
To retain existing parameter values of your association, such as association name or
compliance severity, you must specify these values when you update the association.
If you don't specify these parameters when you update an association, the new
association version uses no values. For example, if your existing association has a cron
schedule but you don't specify -ScheduleExpression when updating, the new
association version will not have a schedule expression.

The following example updates an existing association to change the name to

TestHostnameAssociation2. The new association version runs every hour and writes the output
of commands to the specified Amazon S3 bucket.

Linux

aws ssm update-association \

--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name TestHostnameAssociation2 \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-
east-1,OutputS3BucketName=statemanager,OutputS3KeyPrefix=logs}' \
--schedule-expression "cron(0 */1 * * ? *)"

Windows

aws ssm update-association ^

--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name TestHostnameAssociation2 ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-
east-1,OutputS3BucketName=statemanager,OutputS3KeyPrefix=logs}' ^
--schedule-expression "cron(0 */1 * * ? *)"

PowerShell

Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName TestHostnameAssociation2 `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName statemanager `
-S3Location_OutputS3KeyPrefix logs `
-S3Location_OutputS3Region us-east-1 `
-ScheduleExpression "cron(0 */1 * * ? *)"

3. To view the new version of the association, run the following command.

Linux

aws ssm describe-association \

--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE

Windows

aws ssm describe-association ^

--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE

658
 AWS Systems Manager User Guide
Working with Associations

PowerShell

Get-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE | Select-Object *

The system returns information like the following.

Linux

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "statemanager",
"OutputS3Region": "us-east-1"
}
},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}

Windows

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "statemanager",
"OutputS3Region": "us-east-1"
}

659
 AWS Systems Manager User Guide
Working with Associations

},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}

PowerShell

AssociationId : b85ccafe-9f02-4812-9b81-01234EXAMPLE
AssociationName : TestHostnameAssociation2
AssociationVersion : 2
AutomationTargetParameterName :
ComplianceSeverity :
Date : 5/31/2019 2:47:18 PM
DocumentVersion : $DEFAULT
InstanceId :
LastExecutionDate : 5/31/2019 3:26:40 PM
LastSuccessfulExecutionDate : 5/31/2019 3:26:40 PM
LastUpdateAssociationDate : 5/31/2019 3:26:29 PM
MaxConcurrency :
MaxErrors :
Name : AWS-RunPowerShellScript
OutputLocation :
Amazon.SimpleSystemsManagement.Model.InstanceAssociationOutputLocation
Overview :
Amazon.SimpleSystemsManagement.Model.AssociationOverview
Parameters : {[commands,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
ScheduleExpression : cron(0 */1 * * ? *)
Status :
Targets : {tag:Environment}

Viewing Association Histories

You can view all executions for a specific association ID by using the DescribeAssociationExecutions
API action. This action allows you to quickly see the status, detailed status, results, last execution time,
and more information for a State Manager association. This API action also includes filters to help you

660
 AWS Systems Manager User Guide
Working with Associations

quickly locate associations according to the criteria you specify. For example, you can specify an exact
date and time, and use a GREATER_THAN filter to view only those executions that were processed after
the specified date and time.

If, for example, an association execution failed, you can drill down into the details of a specific execution
by using the DescribeAssociationExecutionTargets API action. This action shows you the resources, such
as instance IDs, where the association ran and the various association statuses. You can then quickly
see which resource or instance failed to run an association. With the resource ID you can then view the
command execution details to see exactly which step in a command failed.

The examples in this section also include information about how to use the StartAssociationsOnce
API action to run an association immediately and only one time. You can use this API action when you
investigate failed association executions. If you see that an association failed, you can make a change on
the resource, and then immediately run the association to see if the change on the resource allows the
association to run successfully.

Viewing Association Histories (Console)

Use the following procedure to view the execution history for a specific association ID and then view
execution details for one or more resources.

To view execution history for a specific association ID

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. Choose State Manager.
3. In the Association id field, choose an association for which you want to view the history.
4. Choose the View details button.
5. Choose the Execution history tab.
6. Choose an association for which you want to view resource-level execution details. For example,
choose an association that shows a status of Failed. You can then view the execution details for the
instances that failed to run the association.
Note
Use the search box filters to locate the execution for which you want to view details.

7. Choose an execution ID. The Association execution targets page opens. This page shows all of the
resources that ran the association.
8. Choose a resource ID to view specific information about that resource.
Note
Use the search box filters to locate the resource for which you want to view details.

9. If you are investigating an association that failed to run, you can use the Apply association now
button to run an association immediately and only one time. After you made changes on the
resource where the association failed to run, choose the Association ID link in the navigation
breadcrumb.
10. Choose the Apply association now button. After the execution is complete, verify that the
association execution succeeded.

Viewing Association Histories (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for
PowerShell to view the execution history for a specific association ID. Following this, the procedure
describes how to view execution details for one or more resources.

661
 AWS Systems Manager User Guide
Working with Associations

To view execution history for a specific association ID

1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58) or Install or Upgrade the AWS Tools for
PowerShell (p. 59).
2. Run the following command to view a list of executions for a specific association ID.

Linux

aws ssm describe-association-executions \

--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN

Note
This command includes a filter to limit the results to only those executions
that occurred after a specific date and time. If you want to view all executions
for a specific association ID, remove the --filters parameter and
Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
value.
Windows

aws ssm describe-association-executions ^

--association-id ID ^
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN

Note
This command includes a filter to limit the results to only those executions
that occurred after a specific date and time. If you want to view all executions
for a specific association ID, remove the --filters parameter and
Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
value.
PowerShell

Get-SSMAssociationExecution `
-AssociationId ID `
-Filter
@{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="GREATER_THAN"}

Note
This command includes a filter to limit the results to only those executions
that occurred after a specific date and time. If you want to view all
executions for a specific association ID, remove the -Filter parameter and
@{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="GREATER_THAN"}
value.

The system returns information like the following.

Linux

{
"AssociationExecutions":[
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",

662
 AWS Systems Manager User Guide
Working with Associations

"ExecutionId":"76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"CreatedTime":1523986028.219,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"CreatedTime":1523984226.074,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"CreatedTime":1523982404.013,
"AssociationVersion":"1"
}
]
}

Windows

{
"AssociationExecutions":[
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"CreatedTime":1523986028.219,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"CreatedTime":1523984226.074,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"CreatedTime":1523982404.013,
"AssociationVersion":"1"
}
]
}

PowerShell

AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/18/2019 2:00:50 AM
DetailedStatus : Success
ExecutionId : 76a5a04f-caf6-490c-b448-92c02EXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}

663
 AWS Systems Manager User Guide
Working with Associations

Status : Success

AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/11/2019 2:00:54 AM
DetailedStatus : Success
ExecutionId : 791b72e0-f0da-4021-8b35-f95dfEXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}
Status : Success

AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/4/2019 2:01:00 AM
DetailedStatus : Success
ExecutionId : ecec60fa-6bb0-4d26-98c7-140308EXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}
Status : Success

You can limit the results by using one or more filters. The following example returns all associations
that were run before a specific date and time.

Linux

aws ssm describe-association-executions \

--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=LESS_THAN

Windows

aws ssm describe-association-executions ^

--association-id ID ^
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=LESS_THAN

PowerShell

Get-SSMAssociationExecution `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-Filter
@{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="LESS_THAN"}

The following returns all associations that were successfully run after a specific date and time.

Linux

aws ssm describe-association-executions \

--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
Key=Status,Value=Success,Type=EQUAL

Windows

aws ssm describe-association-executions ^

--association-id ID ^

664
 AWS Systems Manager User Guide
Working with Associations

--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
Key=Status,Value=Success,Type=EQUAL

PowerShell

Get-SSMAssociationExecution `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-Filter @{
"Key"="CreatedTime";
"Value"="2019-06-01T19:15:38.372Z";
"Type"="GREATER_THAN"
},
@{
"Key"="Status";
"Value"="Success";
"Type"="EQUAL"
}

3. Run the following command to view all targets where the specific execution ran.

Linux

aws ssm describe-association-execution-targets \

--association-id ID \
--execution-id ID

Windows

aws ssm describe-association-execution-targets ^

--association-id ID ^
--execution-id ID

PowerShell

Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE

You can limit the results by using one or more filters. The following example returns information
about all targets where the specific association failed to run.

Linux

aws ssm describe-association-execution-targets \

--association-id ID \
--execution-id ID \
--filters Key=Status,Value="Failed"

Windows

aws ssm describe-association-execution-targets ^

--association-id ID ^
--execution-id ID ^
--filters Key=Status,Value="Failed"

665
 AWS Systems Manager User Guide
Working with Associations

PowerShell

Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE `
-Filter @{
"Key"="Status";
"Value"="Failed"
}

The following example returns information about a specific managed instance where an association
failed to run.

Linux

aws ssm describe-association-execution-targets \

--association-id ID \
--execution-id ID \
--filters Key=Status,Value=Failed Key=ResourceId,Value="i-02573cafcfEXAMPLE"
Key=ResourceType,Value=ManagedInstance

Windows

aws ssm describe-association-execution-targets ^

--association-id ID ^
--execution-id ID ^
--filters Key=Status,Value=Failed Key=ResourceId,Value="i-02573cafcfEXAMPLE"
Key=ResourceType,Value=ManagedInstance

PowerShell

Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE `
-Filter @{
"Key"="Status";
"Value"="Success"
},
@{
"Key"="ResourceId";
"Value"="i-02573cafcfEXAMPLE"
},
@{
"Key"="ResourceType";
"Value"="ManagedInstance"
}

4. If you are investigating an association that failed to run, you can use the StartAssociationsOnce API
action to run an association immediately and only one time. After you change the resource where
the association failed to run, run the following command to run the association immediately and
only one time.

Linux

aws ssm start-associations-once \

--association-id ID

666
 AWS Systems Manager User Guide
State Manager Walkthroughs

Windows

aws ssm start-associations-once ^

--association-id ID

PowerShell

Start-SSMAssociationsOnce `
-AssociationId ID

Systems Manager State Manager Walkthroughs

The following walkthroughs demonstrate how to create and configure State Manager associations
by using the Systems Manager console or the AWS CLI. These walkthrough also demonstrate how to
automatically perform common administrative tasks by using State Manager.

Topics
• Creating Associations that Run MOF Files (p. 667)
• Creating Associations that Run Ansible Playbooks (p. 676)
• Automatically Update SSM Agent (CLI) (p. 681)
• Walkthrough: Automatically Update PV Drivers on EC2 Windows Instances (Console) (p. 682)

Creating Associations that Run MOF Files

You can run Managed Object Format (MOF) files to enforce a desired state on Windows Server managed
instances with State Manager by using the AWS-ApplyDSCMofs SSM document. The AWS-ApplyDSCMofs
document has two execution modes. With the first mode, you can configure the association to scan and
report if the managed instances are currently in the desired state defined in the specified MOF files. In
the second mode, you can run the MOF files and change the configuration of your instances based on
the resources and their values defined in the MOF files. The AWS-ApplyDSCMofs document enables you
to download and run MOF configuration files from Amazon Simple Storage Service (Amazon S3), a local
share, or from a secure web site with an HTTPS domain.

State Manager logs and reports the status of each MOF file execution during each association run. State
Manager also reports the output of each MOF file execution as a compliance event which you can view
on the AWS Systems Manager Compliance page.

MOF file execution is built on Windows PowerShell Desired State Configuration (PowerShell DSC).
PowerShell DSC is a declarative platform used for configuration, deployment, and management of
Windows systems. PowerShell DSC allows administrators to describe, in simple text documents called
DSC configurations, how they want a server to be configured. A PowerShell DSC configuration is a
specialized PowerShell script that states what to do, but not how to do it. Running the configuration
produces a MOF file. The MOF file can be applied to one or more servers to achieve the desired
configuration for those servers. PowerShell DSC resources do the actual work of enforcing configuration.
For more information, see Windows PowerShell Desired State Configuration Overview.

Topics
• Using Amazon S3 to Store Artifacts (p. 668)
• Resolving Credentials in MOF Files (p. 668)
• Using Tokens in MOF Files (p. 669)
• Prerequisites (p. 670)
• Creating an Association that Runs MOF Files (p. 670)

667
 AWS Systems Manager User Guide
State Manager Walkthroughs

• Troubleshooting (p. 673)

• Viewing DSC Resource Compliance Details (p. 675)

Using Amazon S3 to Store Artifacts

If you are using Amazon S3 to store PowerShell modules, MOF files, compliance reports, or status
reports, then the IAM role used by SSM Agent must have GetObject and ListBucket permissions on
the bucket. If you don't provide these permissions, the system returns an Access Denied error. Also note
the following important information about storing artifacts in Amazon S3.

• If the bucket is in a different AWS account, then you must create a bucket resource policy that grants
the account (or the IAM role) GetObject and ListBucket permissions.
• If you want to use custom DSC resources, you can download these resources from an Amazon S3
bucket. You can also install them automatically from the PowerShell gallery.
• If you are using Amazon S3 as a module source, then you need to upload the module as a Zip
file in the following case-sensitive format: ModuleName_ModuleVersion.zip. For example:
MyModule_1.0.0.zip.
• All files must be in the bucket root. Folder structures are not supported.

Resolving Credentials in MOF Files

Credentials are resolved by using AWS Secrets Manager or AWS Systems Manager Parameter
Store (p. 825). This allows you to set up automatic credential rotation. This also enables DSC to
automatically propagate credentials to your servers without redeploying MOFs.

To use a Secrets Manager secret in a configuration, create a PSCredential object where the Username
is the SecretId or SecretARN of the secret containing the credential. You can specify any value for the
password. The value is ignored. Here is an example:

Configuration MyConfig
{
$ss = ConvertTo-SecureString -String 'a_string' -AsPlaintext -Force
$credential = New-Object PSCredential('a_secret_or_ARN', $ss)

Node localhost
{
File file_name
{
DestinationPath = 'C:\MyFile.txt'
SourcePath = '\\FileServer\Share\MyFile.txt'
Credential = $credential
}
}
}

You must then compile your MOF using the PsAllowPlaintextPassword setting in configuration data. This
is OK because the credential only contains a label.

In Secrets Manager, ensure that the instance has GetSecretValue access in an IAM Managed Policy, and
optionally in the Secret Resource Policy if one exists. In order to work with DSC, the secret must be in the
following format:

{ 'Username': 'a_name', 'Password': 'a_password' }

The secret can have other properties (for example, properties used for rotation), but it must at least have
the username and password properties.

668
 AWS Systems Manager User Guide
State Manager Walkthroughs

We recommended that you use a multi-user rotation method, where you have two different usernames
and passwords, and the rotation AWS Lambda function flips between them. This method allows you to
have multiple active accounts while eliminating the risk of locking out a user during rotation.

Using Tokens in MOF Files

Tokens give you the ability to modify resource property values after the MOF has been compiled. This
enables you to reuse common MOF files on multiple servers that require very similar configurations.

Token substitution only works for Resource Properties of type String. However, if your resource has a
nested CIM instance property, it will also resolve tokens from String properties in that CIM instance.
You can't use token substitution for numerals or arrays.

For example, consider a scenario where you're using the xComputerManagement resource and you want
to rename the computer using DSC. Normally you would need a dedicated MOF file for that machine.
However, with token support, you can create a single MOF file and apply it to all of your instances. In
the ComputerName property, instead of hard coding the computer name into the MOF, you can use an
Instance Tag type token. The value is resolved during MOF parsing. For example:

Configuration MyConfig
{
xComputer Computer
{
ComputerName = '{tag:ComputerName}'
}
}

You then set a tag on either the managed instance in the AWS Systems Manager console, or an Amazon
EC2 tag in the EC2 console. When you run the document, the script substitutes the {tag:ComputerName}
token for the value of the instance tag.

You can also combine multiple tags into a single property, for example:

Configuration MyConfig
{
File MyFile
{
DestinationPath = '{env:TMP}\{tag:ComputerName}'
Type = 'Directory'
}
}

There are 5 different types of tokens you can use:

• tag: Amazon EC2 or managed instance tags

• tagb64: This is the same as tag, but the system use base64 to decode the value. This allows you to use
special characters in tag values.
• env: Resolves Environment variables.
• ssm: Systems Manager Parameter Store values. Only String and Secure String types are supported.
• tagssm: This is the same as tag, but if the tag is not set on the instance, the system tries to resolve
the value from an SSM Parameter with the same name. This is useful in situations when you want a
'default global value' but you want to be able to override it on a single instance (for example, one-box
deployments).

Here is Parameter Store example that uses the ssm token type.

File MyFile
{

669
 AWS Systems Manager User Guide
State Manager Walkthroughs

DestinationPath = "C:\ProgramData\ConnectionData.txt"
Content = "{ssm:%servicePath%/ConnectionData}"
}

Tokens play an important role in reducing redundant code by making MOF files generic and reusable. If
you can avoid server-specific MOF file, then there’s no need for a MOF building service. A MOF building
service increases costs, slows provisioning time, and increases the risk of configuration drift between
grouped instances due to differing module versions being installed on the build server when their MOFs
were compiled.

Prerequisites
Before you create an association that runs MOF files, verify that your managed instances have the
following prerequisites installed:

• Windows PowerShell version 5.0 or later. For more information, see Windows PowerShell System
Requirements on Microsoft.com.
• AWS Tools for Windows PowerShell version 3.3.261.0 or later.
• SSM Agent version 2.2 or later.

Creating an Association that Runs MOF Files

To create an association that runs MOF files

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager, and then choose Create association.
3. In the Name field, specify a name. This is optional, but recommended. A name can help you
understand the purpose of the association when you created it. Spaces aren't allowed in the name.
4. In the Document list, choose AWS-ApplyDSCMofs.
5. In the Parameters section, specify your choices for the required and optional input parameters.

a. Mofs To Apply: Specify one or more MOF files to run when this association runs. Use commas to
separate a list of MOF files. You can specify the following options for locating MOF file.

• An Amazon S3 bucket name. Bucket names must use lowercase letters. Specify this
information by using the following format:

s3:bucket_name:MOF_file_name.mof

If you want to specify an AWS Region, then use the following format:

s3:bucket_Region:bucket_name:MOF_file_name.mof

• A secure web site. Specify this information by using the following format:

https://domain_name/MOF_file_name.mof

Here is an example:

https://AWS.Amazon.com/TestMOF.mof

• A file system on a local share. Specify this information by using the following format:

\server_name\shared_folder_name\MOF_file_name.mof

670
 AWS Systems Manager User Guide
State Manager Walkthroughs

Here is an example:

\StateManagerAssociationsBox\MOFs_folder\MyMof.mof

b. Service Path: (Optional) A service path is either an Amazon S3 bucket prefix where you want to
write reports and status information. Or, a service path is a path for Parameter Store parameter-
based tags. When resolving parameter-based tags, the system uses {ssm:%servicePath
%/parameter_name} to inject the servicePath value into the parameter name. For example,
if your service path is "WebServers/Production" then the systems resolves the parameter as:
WebServers/Production/parameter_name. This is useful for when you are running multiple
environments in the same account.
c. Report Bucket Name: (Optional) Enter the name of an Amazon S3 bucket where you want to
write compliance data. Reports are saved in this bucket in JSON format.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an
example: us-west-2:MyMOFBucket. If you are using a proxy for Amazon S3 endpoints
in a specific region that does not include us-east-1, then you must prefix the bucket
name with a region. If the bucket name is not prefixed, it will automatically discover the
bucket region using the us-east-1 endpoint.
d. Mof Operation Mode: Choose State Manager behavior when running the AWS-ApplyDSCMofs
association:

• Apply: Correct instance configurations that aren't compliant.

• ReportOnly: Don't correct instance configurations, but instead log all compliance data and
report instances that aren't compliant.
e. Status Bucket Name: (Optional) Enter the name of an Amazon S3 bucket where you want to
write MOF execution status information. These status reports are singleton summaries of the
most recent compliance run of an instance. This means that the report is overwritten the next
time the association runs MOF files.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an
example: us-west-2:MyMOFBucket. If you are using a proxy for Amazon S3 endpoints
in a specific region that does not include us-east-1, then you must prefix the bucket
name with a region. If the bucket name is not prefixed, it will automatically discover the
bucket region using the us-east-1 endpoint.
f. Module Source Bucket Name: (Optional) Enter the name of an Amazon S3 bucket that contains
PowerShell module files. If you specify None, then you must choose True for the next option,
Allow PS Gallery Module Source.
Note
You can prefix the bucket name with a Region where the bucket is located. Here's an
example: us-west-2:MyMOFBucket. If you are using a proxy for Amazon S3 endpoints
in a specific region that does not include us-east-1, then you must prefix the bucket
name with a region. If the bucket name is not prefixed, it will automatically discover the
bucket region using the us-east-1 endpoint.
g. Allow PS Gallery Module Source: (Optional) Choose True to download PowerShell modules
from https://www.powershellgallery.com/. If you choose False, then you must specify a source
for the previous option, ModuleSourceBucketName.
h. Proxy Uri: (Optional) Use this option to download MOF files from a proxy server.
i. Reboot Behavior: (Optional) Specify one of the following reboot behaviors if your MOF file
execution requires rebooting:

• AfterMof: Reboots the instance after all MOF executions are complete. Even if multiple MOF
executions request reboots, the system waits until all MOF executions are complete to reboot.

671
 AWS Systems Manager User Guide
State Manager Walkthroughs

• Immediately: Reboots the instance whenever a MOF execution requests it. If running multiple
MOF files that request reboots, then the instance will be rebooted multiple times.
• Never: Instances are not rebooted, even if the MOF execution explicitly requests a reboot.
j. Use Computer Name For Reporting: (Optional) Enable this option to use the name of the
computer when reporting compliance information. The default value is false, which means that
the system uses the instance ID when reporting compliance information.
k. Enable Verbose Logging: (Optional) We recommend that you enable verbose logging when
deploying MOF files for the first time.
Important
When enabled, verbose logging writes more data to your Amazon S3 bucket than
standard association execution logging. This can result in slower performance and
possibly higher storage charges for Amazon S3. To mitigate storage size issues, we
recommend that you enable lifecycle policies on your Amazon S3 bucket. For more
information, see How Do I Create a Lifecycle Policy for an S3 Bucket? in the Amazon
Simple Storage Service Console User Guide.
l. Enable Debug Logging: (Optional) We recommend that you enable debug logging if you need
to troubleshoot MOF failures. We also recommend that you disable this option for normal use.
Important
When enabled, debug logging writes more data to your Amazon S3 bucket than
standard association execution logging. This can result in slower performance and
possibly higher storage charges for Amazon S3. To mitigate storage size issues, we
recommend that you enable lifecycle policies on your Amazon S3 bucket. For more
information, see How Do I Create a Lifecycle Policy for an S3 Bucket? in the Amazon
Simple Storage Service Console User Guide.
m. Compliance Type: (Optional) Specify the compliance type to use when reporting compliance
information. The default compliance type is Custom:DSC. If you create multiple associations
that run MOF files, then be sure to specify a different compliance type for each association.
If you don't, each additional association that uses Custom:DSC will overwrite the existing
compliance data.
n. Pre Reboot Script: (Optional) Specify a script to run if the configuration has indicated that a
reboot is necessary. The script runs before the reboot. The script must be a single line. If you
need to add additional lines, separate lines by using semicolons.
6. In the Targets section, choose either Specifying tags or Manually Selecting Instance. If you choose
to target resources by using tags, then enter a tag key and a tag value in the fields provided. For
more information about using targets, see Using Targets and Rate Controls with State Manager
Associations (p. 651).
7. In the Specify schedule section, choose either On Schedule or No schedule. If you choose On
Schedule, then use the buttons provided to create a cron or rate schedule for the association.
8. In the Advanced options section:

• In Compliance severity, choose a severity level for the association. Compliance reporting
will indicate whether the association state is compliant or non-compliant, along with the
severity level you indicate here. For more information, see About State Manager Association
Compliance (p. 508).
9. In the Rate control section, configure options for running State Manager associations across of
fleet of managed instances. For more information about these options, see Using Targets and Rate
Controls with State Manager Associations (p. 651).

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the association
simultaneously.

672
 AWS Systems Manager User Guide
State Manager Walkthroughs

• Choose percentage to enter a percentage of the target set that can run the association
simultaneously.

In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors allowed before State Manager stops running
associations on additional targets.
• Choose percentage to enter a percentage of errors allowed before State Manager stops running
associations on additional targets.
10. In the Output options section, choose Enable writing output to S3 if you want to write the output
of the command to create the associations to an Amazon S3 bucket.
11. Choose Create Association.

State Manager creates and immediately runs the association on the specified instances or targets. After
the initial execution, the association runs in intervals according to the schedule that you defined and
according to the following rules:

• Associations are only run on instances that are online when the interval starts. Offline instances are
skipped.
• State Manager attempts to run the association on all configured instances during an interval.
• If an association is not run during an interval (because, for example, a concurrency value limited the
number of instances that could process the association at one time), then State Manager attempts to
run the association during the next interval.
• State Manager records history for all skipped intervals. You can view the history on the Execution
History tab.

Note
The AWS-ApplyDSCMofs is a Systems Manager command document. This means that you can
also run this document by using Run Command. For more information, see Running Commands
Using Systems Manager Run Command (p. 619).

Troubleshooting
This section includes information to help you troubleshoot issues creating associations that run MOF
files.

Enable Enhanced Logging

As a first step to troubleshooting, enable enhanced logging. More specifically, do the following:

• Verify that the association is configured to write command output to either Amazon S3 or Amazon
CloudWatch Logs.
• Set the Enable Verbose Logging parameter to True.
• Set the Enable Debug Logging parameter to True.

With verbose and debug logging enabled, the Stdout output file includes details about the script
execution. This output file can help you identify where the script failed. The Stderr output file contains
errors that occurred during the script execution.

Common Problems

This section includes information about common problems that can occur when creating associations
that run MOF files and steps to troubleshoot these issues.

673
 AWS Systems Manager User Guide
State Manager Walkthroughs

My MOF was not applied

If State Manager failed to apply the association to your instances, then start by reviewing the Stderr
output file. This file can help you understand the root cause of the issue. Also, verify the following:

• The instance has the required access permissions to all MOF-related Amazon S3 buckets. Specifically:
• s3:GetObject permissions: This is required for MOF files in private Amazon S3 buckets as well as
custom modules in Amazon S3 buckets.
• s3:PutObject permission: This is required to write compliance reports and compliance status to
Amazon S3 buckets.
• If you are using tags, then ensure that the instance has the required IAM policy. Using tags
requires the instance IAM role to have a policy allowing the ec2:DescribeInstances and
ssm:ListTagsForResource actions.
• Ensure that the instance has the expected tags or SSM parameters assigned.
• Ensure that the tags or SSM parameters aren't misspelled.
• Try applying the MOF locally on the instance to make sure there isn't an issue with the MOF file itself.

My MOF seemed to fail, but the Systems Manager execution was successful

If the AWS-ApplyDSCMofs document successfully ran, then the Systems Manager execution status shows
Success. This status does not reflect the compliance status of your instance against the configuration
requirements in the MOF file. To view the compliance status of your instances, view the compliance
reports. You can view a JSON report in the Amazon S3 Report Bucket. This applies to Run Command
and State Manager executions. Also, for State Manager, you can view compliance details on the Systems
Manager Compliance page.

Stderr states: Name resolution failure attempting to reach service

This error indicates that the script can't reach a remote service. Most likely, the script can't reach Amazon
S3. This issue most often occurs when the script attempts to write compliance reports or compliance
status to the Amazon S3 bucket supplied in the document parameters. Typically, this error occurs when
a computing environment uses a firewall or transparent proxy that includes a whitelist. To resolve this
issue:

• Use region-specific bucket syntax for all Amazon S3 bucket parameters. For example, the Mofs to
Apply parameter should be formatted as follows:

s3:bucket-region:bucket-name:mof-file-name.mof.

Here is an example: s3:us-west-2:my-bucket:my-mof.mof

The Report, Status, and Module Source bucket names should be formatted as follows:

bucket-region:bucket-name. Here is an example: us-west-1:my-bucket

• If region-specific syntax does not fix the problem, then make sure that the targeted instance(s) can
access Amazon S3 in the desired region. To verify this:
1. Find the endpoint name for Amazon S3 in the desired Region.
2. Log on to the target instance and run the following ping command:

ping s3.s3-region.amazonaws.com

If the ping failed, it means that either Amazon S3 is down, or a firewall/transparent proxy is
blocking access to the Amazon S3 region, or the instance can't access the internet.

674
 AWS Systems Manager User Guide
State Manager Walkthroughs

Viewing DSC Resource Compliance Details

Systems Manager captures compliance information about DSC resource failures in the Amazon Simple
Storage Service (Amazon S3) Status Bucket you specified when you ran the AWS-ApplyDSCMofs
document. Searching for information about DSC resource failures in an Amazon S3 bucket can be time
consuming. Instead, you can quickly view this information in the Systems Manager Compliance page.

The Compliance resources summary section displays a count of resources that failed. In the following
example, the ComplianceType is Custom:DSC and one resource is non-compliant.
Note
Custom:DSC is the default ComplianceType value in the AWS-ApplyDSCMofs document. This
value is customizable.

The Details overview for resources section displays information about the AWS resource with the non-
compliant DSC resource. This section also includes the MOF name, script execution steps, and (when
applicable) a View output link to view detailed status information.

The View output link displays the last 4,000 characters of the detailed status. Systems Manager
starts with the exception as the first element, and then scans back through the verbose messages
and prepends as many as it can until it reaches the 4000 character limit. This process displays the log
messages that were output prior to the exception being thrown, which are the most relevant messages
for troubleshooting.

675
 AWS Systems Manager User Guide
State Manager Walkthroughs

For information about how how to view compliance information, see AWS Systems Manager
Configuration Compliance (p. 504).

Situations that Affect Compliance Reporting

If the State Manager association fails, then no compliance data is reported. More specifically, if a MOF
fails to process, then Systems Manager doesn’t report any compliance items because the associations
fails. For example, if Systems Manager attempts to download a MOF from an Amazon S3 bucket that the
instance doesn't have permission to access, then the association fails and no compliance data is reported.

If a resource in a second MOF fails, then Systems Manager does report compliance data. For example,
if a MOF tries to create a file on a drive that doesn’t exist, then Systems Manager reports compliance
because the AWS-ApplyDSCMofs document is able to process completely, which means the association
successfully runs.

Creating Associations that Run Ansible Playbooks

You can create State Manager associations that run Ansible playbooks by using the AWS-
ApplyAnsiblePlaybooks document. This document offers the following benefits for running
playbooks:

• Support for running complex playbooks

• Support for downloading playbooks from GitHub and Amazon Simple Storage Service (Amazon S3)
• Support for compressed playbook structure
• Enhanced logging
• Ability to specify which playbook to run when playbooks are bundled

676
 AWS Systems Manager User Guide
State Manager Walkthroughs

Note
Systems Manager includes two SSM documents that enable you to create State Manager
associations that run Ansible playbooks: AWS-RunAnsiblePlaybook and AWS-
ApplyAnsiblePlaybooks. The AWS-RunAnsiblePlaybook document is deprecated. It
remains available in Systems Manager for legacy purposes. We recommend that you use the
AWS-ApplyAnsiblePlaybooks document because of the enhancements described here.

Support for running complex playbooks

The AWS-ApplyAnsiblePlaybooks document supports bundled, complex playbooks because it copies

the entire file structure to a local directory before executing the specified main playbook. You can
provide source playbooks in Zip files or in a directory structure. The Zip file or directory can be stored in
GitHub or Amazon S3.

Support for downloading playbooks from GitHub

The AWS-ApplyAnsiblePlaybooks document uses the aws:downloadContent plugin to download

playbook files. Files can be stored in GitHub in a single file or as a combined set of playbook files. To
download content from GitHub, you must specify information about your GitHub repository in JSON
format. Here is an example:

{
"owner":"TestUser",
"repository":"GitHubTest",
"path":"scripts/python/test-script",
"getOptions":"branch:master",
"tokenInfo":"{{ssm-secure:secure-string-token}}"
}

Support for downloading playbooks from Amazon S3

You can also store and download Ansible playbooks in Amazon S3 as either a single .zip file or a directory
structure. To download content from Amazon S3, you must specify the path to the file. Here are two
examples:

Example 1: Download a specific playbook file

{
"path":"https://s3.amazonaws.com/aws-execute-ansible-test/ansible/playbook.yml"
}

Example 2: Download the contents of a directory

{
"path":"https://s3.amazonaws.com/aws-execute-ansible-test/ansible/webservers/"
}

Important
If you specify Amazon S3, then the AWS Identity and Access Management (IAM) instance profile
on your managed instances must be configured with the AmazonS3ReadOnlyAccess policy.
For more information, see Create an IAM Instance Profile for Systems Manager (p. 29).

Support for compressed playbook structure

The AWS-ApplyAnsiblePlaybooks document enables you to run compressed .zip files in the
downloaded bundle. The document checks if the downloaded files contain a compressed file in .zip
format. If a .zip is found, the document automatically decompresses the file and then runs the specified
Ansible automation.

Enhanced logging

677
 AWS Systems Manager User Guide
State Manager Walkthroughs

The AWS-ApplyAnsiblePlaybooks document includes an optional parameter for specifying different

levels of logging. Specify -v for low verbosity, -vv or –vvv for medium verbosity, and -vvvv for debug
level logging. These options directly map to Ansible verbosity options.

Ability to specify which playbook to run when playbooks are bundled

The AWS-ApplyAnsiblePlaybooks document includes a required parameter for specifying which

playbook to run when multiple playbooks are bundled. This option provides flexibility for running
playbooks to support different use cases.

Installed Dependencies
If you specify True for the InstallDependencies parameter, then Systems Manager verifies that the
following dependencies are installed on your instances. If one or more of these dependencies are not
found, then Systems Manager automatically installs them.

• Ubuntu/Debian: Apt-get (Package Management), Python 3, Ansible, Unzip

• Amazon Linux: Ansible
• RHEL: Python 3, Ansible, Unzip

Create an Association that Runs Ansible Playbooks (Console)

The following procedure describes how to use the Systems Manager console to create a State Manager
association that runs Ansible playbooks by using the AWS-ApplyAnsiblePlaybooks document.

To create an association that runs Ansible playbooks (Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose State Manager, and then choose Create association.
3. For Name, specify a name that helps you remember the purpose of the association.
4. In the Document list, choose AWS-ApplyAnsiblePlaybooks.
5. In the Parameters section, for Source Type, choose either GitHub or S3.

GitHub

If you choose GitHub, enter repository information in the following format:

{
"owner":"user_name",
"repository":"name",
"path":"path_to_directory_or_playbook_to_download",
"getOptions":"branch:branch_name",
"tokenInfo":"{{(Optional)_token_information}}"
}

S3

If you choose S3, enter path information in the following format:

{
"path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download"
}

6. For Install Dependencies, choose an option.

7. (Optional) For Playbook File, enter a file name. If the playbook is contained in a Zip file, then you
must specify a relative path to the Zip file.

678
 AWS Systems Manager User Guide
State Manager Walkthroughs

8. (Optional) For Extra Variables, enter variables that you want State Manager to send to Ansible at
runtime.
9. (Optional) For Check, choose an option.
10. (Optional) For Verbose, choose an option.
11. For Targets, choose an option. For information about using targets, see Using Targets and Rate
Controls with State Manager Associations (p. 651).
12. In the Specify schedule section, choose either On schedule or No schedule. If you choose On
schedule, then use the buttons provided to create a cron or rate schedule for the association.
13. In the Advanced options section, for Compliance severity, choose a severity level for the
association. Compliance reporting indicates whether the association state is compliant or
noncompliant, along with the severity level you indicate here. For more information, see About State
Manager Association Compliance (p. 508).
14. In the Rate control section, configure options to run State Manager associations across a fleet of
managed instances. For information about using rate controls, see Using Targets and Rate Controls
with State Manager Associations (p. 651).

In the Concurrency section, choose an option:

• Choose targets to enter an absolute number of targets that can run the association
simultaneously.
• Choose percentage to enter a percentage of the target set that can run the association
simultaneously.

In the Error threshold section, choose an option:

• Choose errors to enter an absolute number of errors that are allowed before State Manager stops
running associations on additional targets.
• Choose percentage to enter a percentage of errors that are allowed before State Manager stops
running associations on additional targets.
15. In the Output options section, choose Enable writing output to S3 if you want to write the output
of the command to create the associations to an Amazon S3 bucket.
16. Choose Create Association.

Note
If you use tags to create an association on one or more target instances, and then you remove
the tags from an instance, that instance no longer runs the association. The instance is
disassociated from the State Manager document.

Create an Association that Runs Ansible Playbooks (CLI)

The following procedure describes how to use the AWS CLI to create a State Manager association that
runs Ansible playbooks by using the AWS-ApplyAnsiblePlaybooks document.

To create an association that runs Ansible playbooks (CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run one of the following commands to create an association that runs Ansible playbooks by
targeting instances using Amazon EC2 tags. Command (A) specifies GitHub as the source type.
Command (B) specifies Amazon S3 as the source type.

(A) GitHub source

679
 AWS Systems Manager User Guide
State Manager Walkthroughs

Linux

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \

--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["GitHub"],"SourceInfo":
["{\"owner\":\"owner_name\", \"repository\": \"name\",
\"getOptions\": \"branch:master\"}"],"InstallDependencies":
["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/
value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-
vvv, or -vvvv"]}' \
--association-name "name" --schedule-expression "cron_or_rate_expression"

Windows

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^

--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["GitHub"],"SourceInfo":
["{\"owner\":\"owner_name\", \"repository\": \"name\",
\"getOptions\": \"branch:master\"}"],"InstallDependencies":
["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/
value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-
vvv, or -vvvv"]}' ^
--association-name "name" --schedule-expression "cron_or_rate_expression"

Here is an example:

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \

--targets "Key=tag:OS,Values=Linux" \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":
\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\":
\"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-
playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" --schedule-expression "cron(0 2 ? * SUN *)"

(B) S3 source

Linux

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \

--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://
s3.amazonaws.com/
path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":
["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/
value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-
vvv, or -vvvv"]}' \
--association-name "name" --schedule-expression "cron_or_rate_expression"

Windows

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^

--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://
s3.amazonaws.com/
path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":
["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/
value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-
vvv, or -vvvv"]}' ^

680
 AWS Systems Manager User Guide
State Manager Walkthroughs

--association-name "name" --schedule-expression "cron_or_rate_expression"

Here is an example:

aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \

--targets "Key=tag:OS,Values= Windows" \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/
myTestBucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":
["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" --schedule-expression "cron(0 2 ? * SUN *)"

Note
State Manager associations do not support all cron and rate expressions. For more
information about creating cron and rate expressions for associations, see Reference: Cron
and Rate Expressions for Systems Manager (p. 933).

The system attempts to create the association on the instances and immediately apply the state.
3. Run the following command to view an updated status of the association you just created.

aws ssm describe-association --association-id "ID"

Automatically Update SSM Agent (CLI)

The following procedure walks you through the process of creating a State Manager association using
the AWS Command Line Interface (AWS CLI). The association automatically updates the SSM Agent
according to a schedule that you specify. For more information about the SSM Agent, see Working with
SSM Agent (p. 64).
Note
To be notified about SSM Agent updates, subscribe to the SSM Agent Release Notes page on
GitHub.

Before You Begin

Before you complete the following procedure, verify that you have at least one running Amazon EC2
instance (Linux or Windows) that is configured for Systems Manager. For more information, see Systems
Manager Prerequisites (p. 12).
Note
If you create an association by using either the AWS CLI or AWS Tools for Windows PowerShell,
use the --Targets parameter to target instances, as shown in the following example. Don't use
the --InstanceID parameter. The --InstanceID parameter is a legacy parameter.

To create an association for automatically updating SSM Agent

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create an association by targeting instances using Amazon EC2 tags.
The Schedule parameter sets a schedule to run the association every Sunday morning at 2:00 a.m.
(UTC).

aws ssm create-association --targets Key=tag:TagKey,Values=TagValue --name AWS-

UpdateSSMAgent --schedule-expression "cron(0 2 ? * SUN *)"

681
 AWS Systems Manager User Guide
State Manager Walkthroughs

Note
State Manager associations do not support all cron and rate expressions. For more
information about creating cron and rate expressions for associations, see Reference: Cron
and Rate Expressions for Systems Manager (p. 933).

If you want, you can also target multiple instances by specifying instances IDs in a comma-separated
list.

aws ssm create-association --targets

Key=instanceids,Values=InstanceID,InstanceID,InstanceID --name your document name --
schedule-expression "cron(0 2 ? * SUN *)"

The system returns information like the following.

{
"AssociationDescription": {
"ScheduleExpression": "cron(0 2 ? * SUN *)",
"Name": "AWS-UpdateSSMAgent",
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "123..............",
"DocumentVersion": "$DEFAULT",
"LastUpdateAssociationDate": 1504034257.98,
"Date": 1504034257.98,
"AssociationVersion": "1",
"Targets": [
{
"Values": [
"TagValue"
],
"Key": "tag:TagKey"
}
]
}
}

The system attempts to create the association on the instance(s) and immediately apply the state.
The association status shows Pending.
3. Run the following command to view an updated status of the association you just created.

aws ssm list-associations

Note
If your instances are currently running the most recent version of the SSM Agent, the status
shows Failed. This is expected behavior. When a new version of SSM Agent is published,
the association automatically installs the new agent, and the status shows Success.

Walkthrough: Automatically Update PV Drivers on EC2 Windows

Instances (Console)
Amazon Windows AMIs contain a set of drivers to permit access to virtualized hardware. These
drivers are used by Amazon EC2 to map instance store and Amazon EBS volumes to their devices. We
recommend that you install the latest drivers to improve stability and performance of your EC2 Windows
instances. For more information about PV drivers, see AWS PV Drivers.

682
 AWS Systems Manager User Guide
Patch Manager

The following walkthrough shows you how to configure a State Manager association to automatically
download and install new AWS PV drivers when the drivers become available.

Before You Begin

Before you complete the following procedure, verify that you have at least one Amazon EC2 Windows
instance running that is configured for Systems Manager. For more information, see Systems Manager
Prerequisites (p. 12).

To create a State Manager association that automatically updates PV drivers

1. Open the Amazon EC2 console, expand Systems Manager Services in the navigation pane, and then
choose State Manager.
2. Choose Create Association.
3. In the Association Name field, type a descriptive name.
4. In the Select Document list, choose AWS-ConfigureAWSPackage.
5. In the Select Targets by section, choose an option.
Note
If you choose to target instances by using tags, and you specify tags that map to Linux
instances, the association succeeds on the Windows instance, but fails on the Linux
instances. The overall status of the association shows Failed.
6. In the Schedule section, choose an option. Updated PV drivers are only released a few times a year,
so you can schedule the association to run once a month, if you want.
7. In the Parameters section, choose Install from the Action list.
8. For Name list, enter AWSPVDriver. You can leave the Version field empty.
9. In the Advanced section, choose Write to S3 if you want to write association details to an Amazon
S3 bucket.
10. Disregard the S3Region field. This field is deprecated. Specify the name of your bucket in the
S3Bucket Name field. If want to write output to a sub-folder, specify the sub-folder name in the
S3Key Prefix field.
11. Choose Create Association, and then choose Close. The system attempts to create the association
on the instance(s) and immediately apply the state. The association status shows Pending.
12. In the right corner of the Association page, choose the refresh button. If you created the association
on one or more EC2 Windows instances, the status changes to Success. If your instances are not
properly configured for Systems Manager, or if you inadvertently targeted Linux instances, the status
shows Failed.
13. If the status is Failed, choose the Instances tab and verify that the association was successfully
created on your EC2 Windows instances. If Windows instances show a status of Failed, verify that
SSM Agent is running on the instance, and verify that the instance is configured with an IAM role for
Systems Manager. For more information, see Systems Manager Prerequisites (p. 12).

AWS Systems Manager Patch Manager

AWS Systems Manager Patch Manager automates the process of patching managed instances with
both security related and other types of updates. You can use Patch Manager to apply patches for both
operating systems and applications. (On Windows Server, application support is limited to updates for
Microsoft applications.) You can patch fleets of Amazon EC2 instances or your on-premises servers and
virtual machines (VMs) by operating system type. This includes supported versions of Windows Server,
Ubuntu Server, Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), CentOS, Amazon
Linux, and Amazon Linux 2. You can scan instances to see only a report of missing patches, or you can
scan and automatically install all missing patches.

683
 AWS Systems Manager User Guide
Patch Manager Prerequisites

Important
AWS does not test patches for Windows or Linux before making them available in Patch
Manager.

Patch Manager uses patch baselines, which include rules for auto-approving patches within days of their
release, as well as a list of approved and rejected patches. You can install patches on a regular basis by
scheduling patching to run as a Systems Manager maintenance window task. You can also install patches
individually or to large groups of instances by using Amazon EC2 tags. (Tags are keys that help identify
and sort your resources within your organization.) You can add tags to your patch baselines themselves
when you create or update them.

Patch Manager integrates with AWS Identity and Access Management (IAM), AWS CloudTrail, and
Amazon CloudWatch Events to provide a secure patching experience that includes event notifications
and the ability to audit usage.

For information about using CloudTrail to monitor Systems Manager actions, see Logging AWS Systems
Manager API Calls with AWS CloudTrail (p. 889).

For information about using CloudWatch Events to monitor Systems Manager events, see Monitoring
Systems Manager Events with Amazon CloudWatch Events (p. 891).

Getting Started with Patch Manager

To get started with Patch Manager, complete the tasks described in the following table.

Task For More Information

Verify Systems Manager prerequisites Systems Manager Prerequisites (p. 12)

Learn how to set up and configure patching Working with Patch Manager (Console) (p. 720)

Configure permissions for Maintenance Windows Controlling Access to Maintenance

Windows (p. 445)
(Required if you intend to use this feature when
patching.)

Create patch baselines, patch groups, and a Working with Patch Manager (Console) (p. 720)
maintenance window to run patching in a test
environment

Topics
• Patch Manager Prerequisites (p. 684)
• How Patch Manager Operations Work (p. 685)
• About Patching Operations (p. 699)
• About Patch Baselines (p. 709)
• Working with Patch Manager (Console) (p. 720)
• Tutorial: Patch a Server Environment (AWS CLI) (p. 732)
• AWS CLI Commands for Patch Manager (p. 737)

Patch Manager Prerequisites

SSM Agent Version

Version 2.0.834.0 or later of SSM Agent be running on the instances you want to manage with Patch
Manager.

684
 AWS Systems Manager User Guide
How It Works

Note
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe to
the SSM Agent Release Notes page on GitHub.

Supported Operating Systems

The Patch Manager capability does not support all the same operating systems versions that are
supported by other AWS Systems Manager capabilities. For example, Patch Manager does not support
CentOS 6.3, Raspbian Stretch, or Windows Server 2003. (For the full list of Systems Manager-supported
operating systems, see Systems Manager Prerequisites (p. 12).) Therefore, ensure that the instances you
want to use with Patch Manager are running one of the operating systems listed in the following table.

Operating System Details

Linux • Amazon Linux 2012.03 - 2018.03

• Amazon Linux 2 2 - 2.0
• CentOS 6.5 - 7.6
• Red Hat Enterprise Linux (RHEL) 6.5 - 7.6
• SUSE Linux Enterprise Server (SLES) 12.0 and
later 12.x versions
• Ubuntu Server 14.04 LTS, 16.04 LTS, and 18.04
LTS

Note
Instances created from an Amazon Linux
AMI that are using a proxy must be
running a current version of the Python
requests module in order to support
Patch Manager operations. For more
information, see Upgrade the Python
Requests Module on Amazon Linux
Instances That Use a Proxy Server (p. 84).

Windows Windows Server 2008 through Windows Server

2019, including R2 versions.

How Patch Manager Operations Work

This section provides technical details that explain how Patch Manager determines which patches to
install and how it installs them on each supported operating system. For Linux operating systems, it also
provides information about specifying a source repository, in a custom patch baseline, for patches other
than the default configured on an instance. This section also provides details about how patch baseline
rules work on different distributions of the Linux operating system.

Topics
• How Security Patches Are Selected (p. 686)
• How to Specify an Alternative Patch Source Repository (Linux) (p. 688)
• How Patches Are Installed (p. 690)
• How Patch Baseline Rules Work on Linux-Based Systems (p. 693)

685
 AWS Systems Manager User Guide
How It Works

• Key Differences Between Linux and Windows Patching (p. 698)

How Security Patches Are Selected

The primary focus of Patch Manager is on installing operating systems security-related updates on
instances. By default, Patch Manager doesn't install all available patches, but rather a smaller set of
patches focused on security.
Note
On all Linux-based systems supported by Patch Manager, you can choose a different source
repository configured for the instance, typically to install nonsecurity updates. For information,
see How to Specify an Alternative Patch Source Repository (Linux) (p. 688).

The remainder of this section explains how Patch Manager selects security patches for the different
supported operating systems.

Windows

On Microsoft Windows operating systems, Patch Manager retrieves a list of available updates
that Microsoft publishes through its update services, such as Microsoft Update and Windows
Server Update Services (WSUS). Patch Manager continuously monitors for new updates in every
AWS Region. The list of available updates is refreshed in each Region at least once per day. When
the patch information from Microsoft is processed, Patch Manager removes updates that have
been replaced by later updates from its patch list . Therefore, only the most recent update is
displayed and made available for installation. For example, if KB4012214 replaces KB3135456, only
KB4012214 is made available as an update in Patch Manager.
Note
Patch Manager only makes available patches for Windows Server operating system versions
that are supported for Patch Manager. For example, Patch Manager can't be used to patch
Windows Server 2003 or Windows RT.
Amazon Linux and Amazon Linux 2

On Amazon Linux and Amazon Linux 2, the Systems Manager patch baseline service uses
preconfigured repositories on the instance. There are usually two preconfigured repositories (repos)
on an instance:

• Repo ID: amzn-main/latest

Repo name: amzn-main-Base

• Repo ID: amzn-updates/latest

Repo name: amzn-updates-Base

Note
All updates are downloaded from the remote repos configured on the instance. Therefore,
the instance must be able to connect to the repos so the patching can be performed.

Amazon Linux and Amazon Linux 2 instances use Yum as the package manager, and Yum uses
the concept of an update notice as a file named updateinfo.xml. An update notice is simply
a collection of packages that fix specific problems. All packages that are in an update notice are
considered Security by Patch Manager. Individual packages are not assigned classifications or
severity levels. For this reason, Patch Manager assigns the attributes of an update notice to the
related packages.
Note
If you select the Approved patches include non-security updates check box in the Create
patch baseline page, then packages that are not classified in an updateinfo.xml file (or

686
 AWS Systems Manager User Guide
How It Works

a package that contains a file without properly formatted Classification, Severity, and Date
values) can be included in the prefiltered list of patches. However, in order for a patch to be
applied, the patch must still meet the user-specified patch baseline rules.
RHEL

On Red Hat Enterprise Linux, the Systems Manager patch baseline service uses preconfigured
repositories (repos) on the instance. There are usually three preconfigured repos on an instance:

• Repo ID: rhui-REGION-client-config-server-7/x86_64

Repo name: Red Hat Update Infrastructure 2.0 Client Configuration Server 7
• Repo ID: rhui-REGION-rhel-server-releases/7Server/x86_64

Repo name: Red Hat Enterprise Linux Server 7 (RPMs)

• Repo ID: rhui-REGION-rhel-server-rh-common/7Server/x86_64

Repo name: Red Hat Enterprise Linux Server 7 RH Common (RPMs)

Note
All updates are downloaded from the remote repos configured on the instance. Therefore,
the instance must be able to connect to the repos so the patching can be performed.

Red Hat Enterprise Linux instances use Yum as the package manager, and Yum uses the concept
of an update notice as a file named updateinfo.xml. An update notice is simply a collection of
packages that fix specific problems. All packages that are in an update notice are considered Security
by Patch Manager. Individual packages are not assigned classifications or severity levels. For this
reason, Patch Manager assigns the attributes of an update notice to the related packages.
Note
If you select the Approved patches include non-security updates check box in the Create
patch baseline page, then packages that are not classified in an updateinfo.xml file (or
a package that contains a file without properly formatted Classification, Severity, and Date
values) can be included in the prefiltered list of patches. However, in order for a patch to be
applied, the patch must still meet the user-specified patch baseline rules.
Ubuntu

On Ubuntu Server, the Systems Manager patch baseline service uses preconfigured repositories
(repos) on the instance. These preconfigured repos are used to pull an updated list of available
package upgrades. For this, Systems Manager performs the equivalent of a sudo apt-get update
command.

Packages are then filtered from codename-security repos, where the codename is something
like trusty or xenial. For example, on Ubuntu Server 14, Patch Manager only identifies upgrades
that are part of trusty-security. On Ubuntu Server 16, only upgrades that are part of xenial-
security are identified.
SLES

On SUSE Linux Enterprise Server (SLES) instances, the ZYPP library gets the list of available patches
(a collection of packages) from the following locations:

• List of repositories: etc/zypp/repos.d/*

• Package information: /var/cache/zypp/raw/*

SLES instances use Zypper as the package manager, and Zypper uses the concept of a patch. A patch
is simply a collection of packages that fix a specific problem. Patch Manager handles all packages

687
 AWS Systems Manager User Guide
How It Works

referenced in a patch as security-related. Because individual packages aren't given classifications or

severity, Patch Manager assigns the packages the attributes of the patch that they belong to.
CentOS

On CentOS, the Systems Manager patch baseline service uses preconfigured repositories (repos) on
the instance. Here are some examples from a CentOS 6.9 Amazon Machine Image (AMI):

• Repo ID: ultra-centos-6.9-base

Repo name: UltraServe CentOS-6.9 - Base

• Repo ID: ultra-centos-6.9-extras

Repo name: UltraServe CentOS-6.9 - Extras

• Repo ID: ultra-centos-6.9-updates

Repo name: UltraServe CentOS-6.9 - Updates

• Repo ID: ultra-centos-6.x-glusterfs

Repo name: UltraServe CentOS-6.x - GlusterFS

• Repo ID: ultra-centos-6.x-ultrarepo

Repo name: UltraServe CentOS-6.x – UltraServe Repo Packages

Note
All updates are downloaded from the remote repos configured on the instance. Therefore,
the instance must be able to connect to the repos so the patching can be performed.

CentOS instances use Yum as the package manager, and Yum uses the concept of an update notice.
An update notice is simply a collection of packages that fix specific problems. All packages that are
in an update notice are considered Security packages by Patch Manager.

However, CentOS default repos aren't configured with an update notice. This means that Patch
Manager does not detect packages on a default CentOS repo. To enable Patch Manager to process
packages that aren't contained in an update notice, you must enable the EnableNonSecurity flag
in the patch baseline rules.
Note
CentOS update notices are supported. Repos with update notices can be downloaded after
launch.

How to Specify an Alternative Patch Source Repository (Linux)

When you use the default repositories configured on an instance for patching operations, Patch Manager
scans for or installs security-related patches. This is the default behavior for Patch Manager. For
complete information on how Patch Manager selects and installs security patches, see How Security
Patches Are Selected (p. 686).

On Linux systems, however, you can also use Patch Manager to install patches that are not related to
security, or that are in a different source repository than the default one configured on the instance.
You can specify alternative patch source repositories when you create a custom patch baseline. In each
custom patch baseline, you can specify patch source configurations for up to 20 versions of a supported
Linux operating system.

For example, suppose that your Ubuntu Server fleet includes both Ubuntu Server 14.04 and Ubuntu
Server 16.04 instances. In this case, you can specify alternate repositories for each version in the same

688
 AWS Systems Manager User Guide
How It Works

custom patch baseline. For each version, you provide a name, specify the operating system version
type (product), and provide a repository configuration. You can also specify a single alternative source
repository that applies to all versions of a supported operating system.

For a list of example scenarios for using this option, see Sample Uses for Alternative Patch Source
Repositories (p. 690) later in this topic.

For information about default and custom patch baselines, see About Predefined and Custom Patch
Baselines (p. 709).
Note
Running a custom patch baseline that specifies alternative patch repositories on an instance
doesn't change the default repository configured for the instance.

Using the Console

To specify alternative patch source repositories when you are working in the AWS Systems Manager
console, use the Patch sources section on the Create patch baseline page. For information about using
the Patch sources options, see Create a Custom Patch Baseline (p. 721).

Using Other Tools to Create Patch Baselines

Use the sources option with other tools when you create a patch baseline.

• AWS CLI: create-patch-baseline

• Systems Manager API: API_CreatePatchBaseline
• Systems Manager AWS Tools for Windows PowerShell: New-SSMPatchBaseline

For an example of using the --sources option with the CLI, see Create a patch baseline with custom
repositories for different OS versions (p. 738).

Topics
• Important Considerations for Alternative Repositories (p. 689)
• Sample Uses for Alternative Patch Source Repositories (p. 690)

Important Considerations for Alternative Repositories

Keep in mind the following points as you plan your patching strategy using alternative patch
repositories.

Only specified repositories are used for patching

Specifying alternative repositories doesn't mean specifying additional repositories. You can choose to
specify repositories other than those configured as defaults on an instance. However, you must also
specify the default repositories as part of the alternative patch source configuration if you want their
updates to be applied.

For example, on Amazon Linux 2 instances, the default repositories are amzn-main and amzn-update.
If you want to include the Extra Packages for Enterprise Linux (EPEL) repository in your patching
operations, you must specify all three repositories as alternative repositories.
Note
Running a custom patch baseline that specifies alternative patch repositories on an instance
doesn't change the default repository configured for the instance.

Patching behavior for YUM-based distributions depends on the updateinfo.xml manifest

689
 AWS Systems Manager User Guide
How It Works

When you specify alternative patch repositories for YUM-based distributions, such as Amazon Linux
or Amazon Linux 2, Red Hat Enterprise Linux, or CentOS, patching behavior depends on whether
the repository includes an update manifest in the form of a complete and correctly formatted
updateinfo.xml file. This file specifies the release date, classifications, and severities of the various
packages. Any of the following will affect the patching behavior:

• If you filter on Classification and Severity, but they aren't specified in updateinfo.xml, the package
will not be included by the filter. This also means that packages without an updateinfo.xml file
won't be included in patching.
• If you filter on ApprovalAfterDays, but the package release date isn't in Unix Epoch format (or has no
release date specified), the package will not be included by the filter.
• There is an exception if you select the Approved patches include non-security updates check box
in the Create patch baseline page. In this case, packages without an updateinfo.xml file (or that
contains this file without properly formatted Classification, Severity, and Date values) will be included
in the prefiltered list of patches. (They must still meet the other patch baseline rule requirements in
order to be installed.)

Sample Uses for Alternative Patch Source Repositories

Example 1 – Nonsecurity Updates for Ubuntu Server

You are already using Patch Manager to install security patches on a fleet of Ubuntu Server instances
using the AWS-provided predefined patch baseline AWS-UbuntuDefaultPatchBaseline. You can create
a new patch baseline that is based on this default, but specify in the approval rules that you want
nonsecurity related updates that are part of the default distribution to be installed as well. When this
patch baseline is run against your instances, patches for both security and nonsecurity issues are applied.
You can also choose to approve nonsecurity patches in the patch exceptions you specify for a baseline.

Example 2 - Personal Package Archives (PPA) for Ubuntu Server

Your Ubuntu Server instances are running software that is distributed through a Personal Package
Archives (PPA) for Ubuntu. In this case, you create a patch baseline that specifies a PPA repository that
you have configured on the instance as the source repository for the patching operation. Then use Run
Command to run the patch baseline document on the instances.

Example 3 – Internal Corporate Applications on Amazon Linux

You need to run some applications needed for industry regulatory compliance on your Amazon Linux
instances. You can configure a repository for these applications on the instances, use YUM to initially
install the applications, and then update or create a new patch baseline to include this new corporate
repository. After this you can use Run Command to run the AWS-RunPatchBaseline document with the
Scan option to see if the corporate package is listed among the installed packages and is up to date on
the instance. If it isn't up to date, you can run the document again using the Install option to update
the applications.

How Patches Are Installed

Patch Manager uses the appropriate built-in mechanism for an operating system type to install updates
on an instance. For example, on Windows, the Windows Update API is used, and on Amazon Linux the
yum package manager is used.

The remainder of this section explains how Patch Manager installs patches on an operating system.

Windows

When a patching operation is performed on a Windows instance, the instance requests a snapshot of
the appropriate patch baseline from Systems Manager. This snapshot contains the list of all updates

690
 AWS Systems Manager User Guide
How It Works

available in the patch baseline that have been approved for deployment. This list of updates is sent
to the Windows Update API, which determines which of the updates are applicable to the instance
and installs them as needed. If any updates are installed, the instance is rebooted afterwards,
as many times as necessary to complete all necessary patching. The summary of the patching
operation can be found in the output of the Run Command request. Additional logs can be found on
the instance in the %PROGRAMDATA%\Amazon\PatchBaselineOperations\Logs folder.

Because the Windows Update API is used to download and install patches, all Group Policy settings
for Windows Update are respected. No Group Policy settings are required to use Patch Manager, but
any settings that you have defined will be applied, such as to direct instances to a Windows Server
Update Services (WSUS) server.
Note
By default, Windows downloads all patches from Microsoft's Windows Update site because
Patch Manager uses the Windows Update API to drive the download and installation of
patches. As a result, the instance must be able to reach the Microsoft Windows Update
site or patching will fail. Alternatively, you can configure a WSUS server to serve as a patch
repository and configure your instances to target that WSUS server instead using Group
Policies.
Amazon Linux and Amazon Linux 2

On Amazon Linux and Amazon Linux 2 instances, the patch installation workflow is as follows:

1. Apply GlobalFilters as specified in the patch baseline, keeping only the qualified packages for
further processing.
2. Apply ApprovalRules as specified in the patch baseline. Each approval rule can define a package as
approved.
3. Apply ApprovedPatches as specified in the patch baseline. The approved patches are approved for
update even if they are discarded by GlobalFilters or if no approval rule specified in ApprovalRules
grants it approval.
4. Apply RejectedPatches as specified in the patch baseline. The rejected patches are removed from
the list of approved patches and will not be applied.
5. If multiple versions of a patch are approved, the latest version is applied.
6. The YUM update API is applied to approved patches as follows:
• For predefined default patch baselines provided by AWS, and for custom patch baselines where
the Approved patches include non-security updates check box is not selected, only patches
specified in updateinfo.xml are applied (security updates only).

The equivalent yum command for this workflow is:

sudo yum update-minimal --sec-severity=critical,important --bugfix

• For custom patch baselines where the Approved patches include non-security updates is
selected, both patches in updateinfo.xml and those not in updateinfo.xml are applied
(security and nonsecurity updates).

The equivalent yum command for this workflow is:

sudo yum update --security --bugfix

7. The instance is rebooted if any updates were installed.

RHEL

On Red Hat Enterprise Linux instances, the patch installation workflow is as follows:

691
 AWS Systems Manager User Guide
How It Works

1. Apply GlobalFilters as specified in the patch baseline, keeping only the qualified packages for
further processing.
2. Apply ApprovalRules as specified in the patch baseline. Each approval rule can define a package as
approved.
3. Apply ApprovedPatches as specified in the patch baseline. The approved patches are approved for
update even if they are discarded by GlobalFilters or if no approval rule specified in ApprovalRules
grants it approval.
4. Apply RejectedPatches as specified in the patch baseline. The rejected patches are removed from
the list of approved patches and will not be applied.
5. If multiple versions of a patch are approved, the latest version is applied.
6. The YUM update API is applied to approved patches as follows:
• For predefined default patch baselines provided by AWS, and for custom patch baselines where
the Approved patches include non-security updates check box is not selected, only patches
specified in updateinfo.xml are applied (security updates only).

The equivalent yum command for this workflow is:

sudo yum update-minimal --sec-severity=critical,important --bugfix

• For custom patch baselines where the Approved patches include non-security updates is
selected, both patches in updateinfo.xml and those not in updateinfo.xml are applied
(security and nonsecurity updates).

The equivalent yum command for this workflow is:

sudo yum update --security --bugfix

7. The instance is rebooted if any updates were installed.

Ubuntu

On Ubuntu Server instances, the patch installation workflow is as follows:

1. Apply GlobalFilters as specified in the patch baseline, keeping only the qualified packages for
further processing.
2. Apply ApprovalRules as specified in the patch baseline. Each approval rule can define a package
as approved. In addition, an implicit rule is applied in order to select only packages with upgrades
in security repos. For each package, the candidate version of the package (which is typically the
latest version) must be part of a security repo.
3. Apply ApprovedPatches as specified in the patch baseline. The approved patches are approved for
update even if they are discarded by GlobalFilters or if no approval rule specified in ApprovalRules
grants it approval.
4. Apply RejectedPatches as specified in the patch baseline. The rejected patches are removed from
the list of approved patches and will not be applied.
5. The APT library is used to upgrade packages.
6. The instance is rebooted if any updates were installed.

SLES

On SUSE Linux Enterprise Server (SLES) instances, the patch installation workflow is as follows:

1. Apply GlobalFilters as specified in the patch baseline, keeping only the qualified packages for
further processing.

692
 AWS Systems Manager User Guide
How It Works

2. Apply ApprovalRules as specified in the patch baseline. Each approval rule can define a package as
approved.
3. Apply ApprovedPatches as specified in the patch baseline. The approved patches are approved for
update even if they are discarded by GlobalFilters or if no approval rule specified in ApprovalRules
grants it approval.
4. Apply RejectedPatches as specified in the patch baseline. The rejected patches are removed from
the list of approved patches and won't be applied.
5. If multiple versions of a patch are approved, the latest version is applied.
6. The Zypper update API is applied to approved patches.
7. The instance is rebooted if any updates were installed.

CentOS

On CentOS instances, the patch installation workflow is as follows:

1. Apply GlobalFilters as specified in the patch baseline, keeping only the qualified packages for
further processing.
2. Apply ApprovalRules as specified in the patch baseline. Each approval rule can define a package as
approved.
3. Apply ApprovedPatches as specified in the patch baseline. The approved patches are approved for
update even if they are discarded by GlobalFilters or if no approval rule specified in ApprovalRules
grants it approval.
4. Apply RejectedPatches as specified in the patch baseline. The rejected patches are removed from
the list of approved patches and will not be applied.
5. If multiple versions of a patch are approved, the latest version is applied.
6. The YUM update API is applied to approved patches.
7. The instance is rebooted if any updates were installed.

How Patch Baseline Rules Work on Linux-Based Systems

The rules in a patch baseline for Linux distributions operate differently based on the distribution type.
Unlike patch updates on Windows instances, rules are evaluated on each instance to take the configured
repos on the instance into consideration. Patch Manager uses the native package manager to drive the
installation of patches approved by the patch baseline.

Topics
• How Patch Baseline Rules Work on Amazon Linux and Amazon Linux 2 (p. 693)
• How Patch Baseline Rules Work on RHEL (p. 695)
• How Patch Baseline Rules Work on Ubuntu Server (p. 697)
• How Patch Baseline Rules Work on SUSE Linux Enterprise Server (p. 697)

How Patch Baseline Rules Work on Amazon Linux and Amazon Linux 2
On Amazon Linux and Amazon Linux 2, the patch selection process is as follows:

1. On the instance, the YUM library accesses the updateinfo.xml file for each configured repo.
Note
If no updateinfo.xml file is found, no patch will be applied.
2. Each update notice in updateinfo.xml includes several attributes that denote the properties of the
packages in the notice, as described in the following table.

693
 AWS Systems Manager User Guide
How It Works

Update Notice Attributes

Attribute Description

type Corresponds to the value of the Classification

key attribute in the patch baseline's PatchFilter
data type. Denotes the type of package included
in the update notice.

You can view the list of supported values

by using the AWS CLI command describe-
patch-properties or the API action
DescribePatchProperties. You can also view
the list in the Approval rules area of the Create
patch baseline page or Edit patch baseline page
in the Systems Manager console.

severity Corresponds to the value of the Severity key

attribute patch baseline's PatchFilter data type.
Denotes the severity of the packages included
in the update notice. Usually only applicable for
Security update notices.

You can view the list of supported values

by using the AWS CLI command describe-
patch-properties or the API action
DescribePatchProperties. You can also view
the list in the Approval rules area of the Create
patch baseline page or Edit patch baseline page
in the Systems Manager console.

update_id Denotes the advisory ID, such as

ALAS-2017-867. The advisory ID can be used
in the ApprovedPatches or RejectedPatches
attribute in the patch baseline.

references Contains additional information about the

update notice, such as a CVE ID (format:
CVE-2017-1234567). The CVE ID can be used
in the ApprovedPatches or RejectedPatches
attribute in the patch baseline.

updated Corresponds to ApproveAfterDays in the patch

baseline. Denotes the released date (updated
date) of the packages included in the update
notice. A comparison between the current
timestamp and the value of this attribute plus
the ApproveAfterDays is used to determine if the
patch is approved for deployment.

Note
For information about accepted formats for lists of approved patches and rejected patches,
see About Package Name Formats for Approved and Rejected Patch Lists (p. 712).
3. The product of the instance is determined by SSM Agent. This attribute corresponds to the value of
the Product key attribute in the patch baseline's PatchFilter data type.
4. Packages are selected for the update according to the follow guidelines:

694
 AWS Systems Manager User Guide
How It Works

Security option Patch selection

Pre-defined default patch baselines provided For each update notice in updateinfo.xml,
by AWS and custom patch baselines where the patch baseline is used as a filter, allowing
the Approved patches include non-security only the qualified packages to be included in the
updates is not selected update. If multiple packages are applicable after
applying the patch baseline definition, the latest
version is used.

The equivalent yum command for this workflow

is:

sudo yum update-minimal --sec-

severity=critical,important --bugfix

Custom patch baselines where the Approved In addition to applying the security updates that
patches include non-security updates is have been selected from updateinfo.xml,
selected Patch Manager will apply nonsecurity updates
that otherwise meet the patch filtering rules.

The equivalent yum command for this workflow

is:

sudo yum update --security --bugfix

For information about patch compliance status values, see About Patch Compliance States (p. 708).

How Patch Baseline Rules Work on RHEL

On Red Hat Enterprise Linux, the patch selection process is as follows:

1. On the instance, the YUM library accesses the updateinfo.xml file for each configured repo.
Note
The updateinfo.xml file might not be available if the repo is not one managed by Red Hat.
If there is no updateinfo.xml found, no patch will be applied.
2. Each update notice in updateinfo.xml includes several attributes that denote the properties of the
packages in the notice, as described in the following table.

Update Notice Attributes

Attribute Description

type Corresponds to the value of the Classification

key attribute in the patch baseline's PatchFilter
data type. Denotes the type of package included
in the update notice.

You can view the list of supported values

by using the AWS CLI command describe-
patch-properties or the API action
DescribePatchProperties. You can also view
the list in the Approval rules area of the Create

695
 AWS Systems Manager User Guide
How It Works

Attribute Description
patch baseline page or Edit patch baseline page
in the Systems Manager console.

severity Corresponds to the value of the Severity key

attribute in the patch baseline's PatchFilter
data type. Denotes the severity of the packages
included in the update notice. Usually only
applicable for Security update notices.

You can view the list of supported values

by using the AWS CLI command describe-
patch-properties or the API action
DescribePatchProperties. You can also view
the list in the Approval rules area of the Create
patch baseline page or Edit patch baseline page
in the Systems Manager console.

update_id Denotes the advisory ID, such as

RHSA-2017:0864. The advisory ID can be used
in the ApprovedPatches or RejectedPatches
attribute in the patch baseline.

references Contains additional information about the

update notice, such as a CVE ID (format:
CVE-2017-1000371) or a Bugzilla ID (format:
1463241). The CVE ID and Bugzilla ID can be
used in the ApprovedPatches or RejectedPatches
attribute in the patch baseline.

updated Corresponds to ApproveAfterDays in the patch

baseline. Denotes the released date (updated
date) of the packages included in the update
notice. A comparison between the current
timestamp and the value of this attribute plus
the ApproveAfterDays is used to determine if the
patch is approved for deployment.

Note
For information about accepted formats for lists of approved patches and rejected patches,
see About Package Name Formats for Approved and Rejected Patch Lists (p. 712).
3. The product of the instance is determined by SSM Agent. This attribute corresponds to the value of
the Product key attribute in the patch baseline's PatchFilter data type.
4. Packages are selected for the update according to the follow guidelines:

Security option Patch selection

Pre-defined default patch baselines provided For each update notice in updateinfo.xml,
by AWS and custom patch baselines where the patch baseline is used as a filter, allowing
the Approved patches include non-security only the qualified packages to be included in the
updates is not selected update. If multiple packages are applicable after
applying the patch baseline definition, the latest
version is used.

696
 AWS Systems Manager User Guide
How It Works

Security option Patch selection

The equivalent yum command for this workflow
is:

sudo yum update-minimal --sec-

severity=critical,important --bugfix

Custom patch baselines where the Approved In addition to applying the security updates that
patches include non-security updates is have been selected from updateinfo.xml,
selected Patch Manager will apply nonsecurity updates
that otherwise meet the patch filtering rules.

The equivalent yum command for this workflow

is:

sudo yum update --security --bugfix

For information about patch compliance status values, see About Patch Compliance States (p. 708).

How Patch Baseline Rules Work on Ubuntu Server

On Ubuntu Server, the patch baseline service offers filtering on the Priority and Section fields. These
fields are typically present for all Ubuntu Server packages. To determine whether a patch is selected by
the patch baseline, Patch Manager does the following:

1. On Ubuntu systems, the equivalent of sudo apt-get update is run to refresh the list of available
packages. Repos are not configured and the data is pulled from repos configured in a sources list.
2. Next, the GlobalFilters, ApprovalRules, ApprovedPatches and RejectedPatches lists are applied. Only
packages with candidate versions appearing in the distribution security repo (archive) are selected. For
Ubuntu Server 14 this is repo is trusty-security. For Ubuntu Server 16, it is xenial-security.
Note
For information about accepted formats for lists of approved patches and rejected patches,
see About Package Name Formats for Approved and Rejected Patch Lists (p. 712).

To view the contents of the Priority and Section fields, run the following aptitude command:
Note
You may need to first install Aptitude on Ubuntu Server 16 systems.

aptitude search -F '%p %P %s %t %V#' '~U'

In the response to this command, all upgradable packages are reported in this format:

name, priority, section, archive, candidate version

For information about patch compliance status values, see About Patch Compliance States (p. 708).

How Patch Baseline Rules Work on SUSE Linux Enterprise Server

On SLES, each patch includes the following attributes that denote the properties of the packages in the
patch:

697
 AWS Systems Manager User Guide
How It Works

• Category: Corresponds to the value of the Classification key attribute in the patch baseline's
PatchFilter data type. Denotes the type of patch included in the update notice.

You can view the list of supported values by using the AWS CLI command describe-patch-properties
or the API action DescribePatchProperties. You can also view the list in the Approval rules area of the
Create patch baseline page or Edit patch baseline page in the Systems Manager console.
• Severity: Corresponds to the value of the Severity key attribute patch baseline's PatchFilter data type.
Denotes the severity of the patches.

You can view the list of supported values by using the AWS CLI command describe-patch-properties
or the API action DescribePatchProperties. You can also view the list in the Approval rules area of the
Create patch baseline page or Edit patch baseline page in the Systems Manager console.

The product of the instance is determined by SSM Agent. This attribute corresponds to the value of the
Product key attribute in the patch baseline's PatchFilter data type.

For each patch, the patch baseline is used as a filter, allowing only the qualified packages to be included
in the update. If multiple packages are applicable after applying the patch baseline definition, the latest
version is used.
Note
For information about accepted formats for lists of approved patches and rejected patches, see
About Package Name Formats for Approved and Rejected Patch Lists (p. 712).

Key Differences Between Linux and Windows Patching

The following table describes important differences between Linux and Windows patching.
Note
To patch Linux instances, your instances must be running SSM Agent version 2.0.834.0 or later.
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe to
the SSM Agent Release Notes page on GitHub.

Difference Details

Patch evaluation Linux

For Linux patching, Systems Manager evaluates

patch baseline rules and the list of approved
and rejected patches on each managed instance.
Systems Manager must evaluate patching on each
instance because the service retrieves the list of
known patches and updates from the repositories
that are configured on the instance.

Windows

Patch Manager uses different processes on

Windows managed instances and Linux managed
instances in order to evaluate which patches
should be present. For Windows patching,
Systems Manager evaluates patch baseline rules
and the list of approved and rejected patches
directly in the service. It can do this because

698
 AWS Systems Manager User Guide
About Patching Operations

Difference Details
Windows patches are pulled from a single
repository (Windows Update).

Not Applicable patches Due to the large number of available packages

for Linux operating systems, Systems Manager
does not report details about patches in the Not
Applicable state. A Not Not Applicable patch
is, for example, a patch for Apache software when
the instance does not have Apache installed.
Systems Manager does report the number of
Not Applicable patches in the summary, but
if you call the DescribeInstancePatches API for
an instance, the returned data does not include
patches with a state of Not Applicable. This
behavior is different from Windows.

SSM document support The AWS-ApplyPatchBaseline SSM document

doesn't support Linux instances. For applying
patch baselines to both Windows and Linux
instances, the recommended SSM document is
AWS-RunPatchBaseline. For more information,
see About SSM Documents for Patching
Instances (p. 700) and About the SSM Document
AWS-RunPatchBaseline (p. 703).

Application patches Patch Manager's primary focus is applying patches

to operating systems. However, you can also
use Patch Manager to apply patches to some
applications on your instances.

Linux

On Linux operating systems, Patch Manager uses

the configured repositories for updates, and does
not differentiate between operating systems
and application patches. You can use Patch
Manager to define which repositories to fetch
updates from. For more information, see How to
Specify an Alternative Patch Source Repository
(Linux) (p. 688).

Windows

On Windows Server instances, you can apply

approval rules, as well as Approved and Rejected
patch exceptions, for applications released
by Microsoft, such as Microsoft Word 2011
and Microsoft Exchange Server 2016. For
more information, see Create a Custom Patch
Baseline (p. 721).

About Patching Operations

The topics in this section provide information to help you understand how the Patch Manager service
works.

699
 AWS Systems Manager User Guide
About Patching Operations

Topics
• About Patching Configurations (p. 700)
• About SSM Documents for Patching Instances (p. 700)
• About Patch Compliance States (p. 708)

About Patching Configurations

A patching configuration defines a unique patching operation. The configuration specifies the instances
for patching, which patch baseline is to be applied, the schedule for patching, and typically, the
maintenance window that the configuration is to be associated with.

To create a patching configuration, use the Configure patching page. This page lets you associate a
patching configuration with an existing maintenance window, create a new maintenance window for the
configuration, or run a one-time manual patching operation on a set of instances. For more information,
see Create a Patching Configuration (Console) (p. 729).

About SSM Documents for Patching Instances

This topic describes the seven SSM documents currently available to help you keep your managed
instances patched with the latest security-related updates.

We currently recommend using just three of these documents in your patching operations. Together,
these three SSM documents provide you with a full range of patching options using AWS Systems
Manager. Two of these documents were released later than the four legacy SSM documents they replace
and represent expansions or consolidations of functionality.

The three recommended SSM documents include:

• AWS-ConfigureWindowsUpdate
• AWS-InstallWindowsUpdates
• AWS-RunPatchBaseline

The four legacy SSM documents that are still available for use, but might be deprecated in the future,
include:

• AWS-ApplyPatchBaseline
• AWS-FindWindowsUpdates
• AWS-InstallMissingWindowsUpdates
• AWS-InstallSpecificWindowsUpdates

Refer to the following sections for more information about using these SSM documents in your patching
operations.

Topics
• SSM Documents Recommended for Patching Instances (p. 700)
• Legacy SSM Documents for Patching Instances (p. 702)
• About the SSM Document AWS-RunPatchBaseline (p. 703)

SSM Documents Recommended for Patching Instances

The following three SSM documents are recommended for use in your managed instance patching
operations.

700
 AWS Systems Manager User Guide
About Patching Operations

Recommended SSM Documents

• AWS-ConfigureWindowsUpdate (p. 701)
• AWS-InstallWindowsUpdates (p. 701)
• AWS-RunPatchBaseline (p. 701)

AWS-ConfigureWindowsUpdate

Supports configuring basic Windows Update functions and using them to install updates automatically
(or to disable automatic updates). Available in all AWS Regions.

This SSM document prompts Windows Update to download and install the specified updates and reboot
instances as needed. Use this document with State Manager to ensure Windows Update maintains
its configuration. You can also run it manually using Run Command to change the Windows Update
configuration.

The available parameters in this document support specifying a category of updates to install (or
whether to disable automatic updates), as well as specifying the day of the week and time of day to run
patching operations. This SSM document is most useful if you don't need strict control over Windows
updates and don't need to collect compliance information.

Replaces legacy SSM documents:

• None

AWS-InstallWindowsUpdates

Installs updates on a Windows instance. Available in all AWS Regions.

This SSM document provides basic patching functionality in cases where you either want to install
a specific update (using the Include Kbs parameter), or want to install patches with specific
classifications or categories but don't need patch compliance information.

Replaces legacy SSM documents:

• AWS-FindWindowsUpdates
• AWS-InstallMissingWindowsUpdates
• AWS-InstallSpecificWindowsUpdates

The three legacy documents perform different functions, but you can achieve the same results by using
different parameter settings with the newer SSM document AWS-InstallWindowsUpdates. These
parameter settings are described in Legacy SSM Documents for Patching Instances (p. 702).

AWS-RunPatchBaseline

Installs patches on your instances or scans instances to determine whether any qualified patches are
missing. Available in all AWS Regions.

AWS-RunPatchBaseline enables you to control patch approvals using patch baselines. Reports patch
compliance information that you can view using the Systems Manager Compliance tools. These tools
provide you with insights on the patch compliance state of your instances, such as which instances are
missing patches and what those patches are. For Linux operating systems, compliance information
is provided for patches from both the default source repository configured on an instance and from
any alternative source repositories you specify in a custom patch baseline. For more information
about alternative source repositories, see How to Specify an Alternative Patch Source Repository
(Linux) (p. 688). For more information about the Systems Manager Compliance tools, see AWS Systems
Manager Configuration Compliance (p. 504).

701
 AWS Systems Manager User Guide
About Patching Operations

Replaces legacy documents:

• AWS-ApplyPatchBaseline

The legacy document AWS-ApplyPatchBaseline applies only to Windows instances, and does not
provide support for application patching. The newer AWS-RunPatchBaseline provides the same support
for both Windows and Linux systems. Version 2.0.834.0 or later of SSM Agent is required in order to use
the AWS-RunPatchBaseline document.

For more information about the AWS-RunPatchBaseline SSM document, see About the SSM Document
AWS-RunPatchBaseline (p. 703).

Legacy SSM Documents for Patching Instances

The following four SSM documents are still available for use in your patching operations. However,
they might be deprecated in the future, so we do not recommend their use. Instead, use the documents
described in SSM Documents Recommended for Patching Instances (p. 700).

Legacy SSM Documents

• AWS-ApplyPatchBaseline (p. 702)
• AWS-FindWindowsUpdates (p. 702)
• AWS-InstallMissingWindowsUpdates (p. 702)
• AWS-InstallSpecificWindowsUpdates (p. 703)

AWS-ApplyPatchBaseline

Supports only Windows instances, but does not include support for patching applications that is found in
its replacement, AWS-RunPatchBaseline. Not available in AWS Regions launched after August 2017.
Note
The replacement for this SSM document, AWS-RunPatchBaseline, requires version 2.0.834.0 or
a later version of SSM Agent. You can use the AWS-UpdateSSMAgent document to update your
instances to the latest version of the agent.

AWS-FindWindowsUpdates

Replaced by AWS-InstallWindowsUpdates, which can perform all the same actions. Not available in
AWS Regions launched after April 2017.

To achieve the same result that you would from this legacy SSM document, use the following parameter
configuration with the recommended replacement document, AWS-InstallWindowsUpdates:

• Action = Scan
• Allow Reboot = False

AWS-InstallMissingWindowsUpdates

Replaced by AWS-InstallWindowsUpdates, which can perform all the same actions. Not available in any
AWS Regions launched after April 2017.

To achieve the same result that you would from this legacy SSM document, use the following parameter
configuration with the recommended replacement document, AWS-InstallWindowsUpdates:

• Action = Install
• Allow Reboot = True

702
 AWS Systems Manager User Guide
About Patching Operations

AWS-InstallSpecificWindowsUpdates

Replaced by AWS-InstallWindowsUpdates, which can perform all the same actions. Not available in any
AWS Regions launched after April 2017.

To achieve the same result that you would from this legacy SSM document, use the following parameter
configuration with the recommended replacement document, AWS-InstallWindowsUpdates:

• Action = Install
• Allow Reboot = True
• Include Kbs = comma-separated list of KB articles

About the SSM Document AWS-RunPatchBaseline

AWS Systems Manager supports an SSM document for Patch Manager, AWS-RunPatchBaseline, which
performs patching operations on instances for both security related and other types of updates. You can
use the document AWS-RunPatchBaseline to apply patches for both operating systems and applications.
(On Windows Server, application support is limited to updates for Microsoft applications.)

This document supports both Linux and Windows instances, so it can be reliably run on either type of
instance when managed by Systems Manager. The document will perform the appropriate actions for
each platform.
Note
Patch Manager also supports the legacy SSM document AWS-ApplyPatchBaseline. However,
this document supports patching on Windows instances only. We encourage you to use AWS-
RunPatchBaseline instead because it supports patching on both Linux and Windows instances.
Version 2.0.834.0 or later of SSM Agent is required in order to use the AWS-RunPatchBaseline
document.

On Windows systems:

On Windows instances, the AWS-RunPatchBaseline document downloads and invokes a PowerShell

module, which in turn downloads a snapshot of the patch baseline that applies to the instance. This
patch baseline snapshot is passed to the Windows Update API, which controls downloading and
installing the approved patches as appropriate.
On Linux systems:

On Linux instances, the AWS-RunPatchBaseline document invokes a Python module, which in

turn downloads a snapshot of the patch baseline that applies to the instance. This patch baseline
snapshot uses the defined rules and lists of approved and blocked patches to drive the appropriate
package manager for each instance type:
• Amazon Linux, Amazon Linux 2, CentOS, and RHEL instances use YUM. For YUM operations, Patch
Manager requires Python 2.6 or later.
• Ubuntu Server instances use APT. For APT operations, Patch Manager requires Python 3.
• SUSE Linux Enterprise Server instances use Zypper. For Zypper operations, Patch Manager requires
Python 2.6 or later.

After all approved and applicable updates have been installed, with reboots performed as necessary,
patch compliance information is generated on an instance and reported back to Patch Manager. For
information about viewing patch compliance data, see About Patch Compliance (p. 508).

AWS-RunPatchBaseline Parameters

AWS-RunPatchBaseline supports three parameters. The Operation parameter is required. The

InstallOverrideList parameter is optional. Snapshot-ID is technically optional, but we

703
 AWS Systems Manager User Guide
About Patching Operations

recommend that you supply a custom value for it when you run AWS-RunPatchBaseline outside of a
maintenance window, and let Patch Manager supply the value automatically when the document is run
as part of a maintenance window operation.

Parameters
• Parameter name: Operation (p. 704)
• Parameter name: InstallOverrideList (p. 704)
• Parameter name: Snapshot ID (p. 707)

Parameter name: Operation

Usage: Required.

Options: Scan | Install.

Scan

When you choose the Scan option, AWS-RunPatchBaseline determines the patch compliance state
of the instance and reports this information back to Patch Manager. Scan does not prompt updates
to be installed or instances to be rebooted. Instead, the operation identifies where updates are
missing that are approved and applicable to the instance.
Install

When you choose the Install option, AWS-RunPatchBaseline attempts to install the approved
and applicable updates that are missing from the instance. Patch compliance information generated
as part of an Install operation does not list any missing updates, but might report updates that
are in a failed state if the installation of the update did not succeed for any reason. Whenever an
update is installed on an instance, the instance is rebooted to ensure the update is both installed and
active.

Parameter name: InstallOverrideList

Usage: Optional.

InstallOverrideList lets you specify an https URL or an Amazon Simple Storage Service (Amazon
S3) path-style URL to a list of patches to be installed. This patch installation list, which you maintain in
YAML format, overrides the patches specified by the current default patch baseline. This provides you
with more granular control over which patches are installed on your instances.

Be aware that compliance reports reflect patch states according to what’s specified in the patch baseline,
not what you specify in an InstallOverrideList list of patches. In other words, Scan operations
ignore the InstallOverrideList parameter. This is to ensure that compliance reports consistently
reflect patch states according to policy rather than what was approved for a specific patching operation.

Valid URL formats

• https URL format:

https://s3.amazonaws.com/my-patch-approval-lists-bucket/my-windows-override-list.yaml

• Amazon S3 path-style URL:

s3://my-patch-approval-lists-bucket/my-windows-override-list.yaml

Valid YAML content formats

704
 AWS Systems Manager User Guide
About Patching Operations

The formats you use to specify patches in your list depends on the operating system of your instance.
The general format, however, is as follows:

patches:
-
id: '{patch-d}'
title: '{patch-title}'
{additional-fields}:{values}

Although you can provide additional fields in your YAML file, they are ignored during patch operations.

In addition, we recommend verifying that the format of your YAML file is valid before adding or updating
the list in your S3 bucket. For more information about the YAML format, see yaml.org. For validation tool
options, perform a web search for "yaml format validators".

• Microsoft Windows

id

The id field is required. Use it to specify patches using Microsoft Knowledge Base IDs (for example,
KB2736693) and Microsoft Security Bulletin IDs (for example, MS17-023).

Any other fields you want to provide in a patch list for Windows are optional and are for your own
informational use only. You can use additional fields such as title, classification, severity, or anything
else for providing more detailed information about the specified patches.
• Linux

id

The id field is required. Use it to specify patches using the package name and architecture. For
example: 'dhclient.x86_64'. You can use wildcards in id to indicate multiple packages. For
example: 'dhcp*' and 'dhcp*1.*'.

title

The title field is optional, but on Linux systems it does provide additional filtering capabilities. If you
use title, it should contain the package version information in the one of the following formats:

YUM/SUSE Linux Enterprise Server (SLES):

{name}.{architecture}:{epoch}:{version}-{release}

APT

{name}.{architecture}:{version}

For Linux patch titles, you can use one or more wildcards in any position to expand the number of
package matches. For example: '*32:9.8.2-0.*.rc1.57.amzn1'.

For example:
• apt package version 1.2.25 is currently installed on your instance, but version 1.2.27 is now
available.
• You add apt.amd64 version 1.2.27 to the patch list. It depends on apt utils.amd64 version 1.2.27,
but apt-utils.amd64 version 1.2.25 is specified in the list.

In this case, apt version 1.2.27 will be blocked from installation and reported as “Failed-
NonCompliant.”

705
 AWS Systems Manager User Guide
About Patching Operations

Other fields

Any other fields you want to provide in a patch list for Linux are optional and are for your own
informational use only. You can use additional fields such as classification, severity, or anything else for
providing more detailed information about the specified patches.

Sample patch lists

• Windows

patches:
-
id: 'KB4284819'
title: '2018-06 Cumulative Update for Windows Server 2016 (1709) for x64-based
Systems (KB4284819)'
-
id: 'KB4284833'
-
id: 'KB4284835'
title: '2018-06 Cumulative Update for Windows Server 2016 (1803) for x64-based
Systems (KB4284835)'
-
id: 'KB4284880'
-
id: 'KB4338814'

• APT

patches:
-
id: 'apparmor.amd64'
title: '2.10.95-0ubuntu2.9'
-
id: 'cryptsetup.amd64'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'cryptsetup-bin.*'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'apt.amd64'
title: '*1.2.27'
-
id: 'apt-utils.amd64'
title: '*1.2.25'

• Amazon Linux

patches:
-
id: 'kernel.x86_64'
-
id: 'bind*.x86_64'
title: '32:9.8.2-0.62.rc1.57.amzn1'
-
id: 'glibc*'
-
id: 'dhclient*'
title: '*12:4.1.1-53.P1.28.amzn1'
-
id: 'dhcp*'
title: '*10:3.1.1-50.P1.26.amzn1'

• Red Hat Enterprise Linux (RHEL)

706
 AWS Systems Manager User Guide
About Patching Operations

patches:
-
id: 'NetworkManager.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'NetworkManager-*.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'audit.x86_64'
title: '*0:2.8.1-3.el7'
-
id: 'dhclient.x86_64'
title: '*.el7_5.1'
-
id: 'dhcp*.x86_64'
title: '*12:5.2.5-68.el7'

• SUSE Linux Enterprise Server (SLES)

patches:
-
id: 'amazon-ssm-agent.x86_64'
-
id: 'binutils'
title: '*0:2.26.1-9.12.1'
-
id: 'glibc*.x86_64'
title: '*2.19*'
-
id: 'dhcp*'
title: '0:4.3.3-9.1'
-
id: 'lib*'

Parameter name: Snapshot ID

Usage: Optional.

Snapshot ID is a unique ID (GUID) used by Patch Manager to ensure that a set of instances that are
patched in a single operation all have the exact same set of approved patches. Although the parameter
is defined as optional, our best practice recommendation depends on whether or not you are running
AWS-RunPatchBaseline in a maintenance window, as described in the following table.

AWS-RunPatchBaseline Best Practices

Mode Best Practice Details

Running AWS- Do not supply a Snapshot ID. If you use a maintenance

RunPatchBaseline inside a Patch Manager will supply it for window to run AWS-
maintenance window you. RunPatchBaseline, you should
not provide your own generated
Snapshot ID. In this scenario,
Systems Manager provides
a GUID value based on the
maintenance window execution
ID. This ensures that a correct ID
is used for all the invocations of
AWS-RunPatchBaseline in that
maintenance window.

707
 AWS Systems Manager User Guide
About Patching Operations

Mode Best Practice Details

If you do specify a value in this
scenario, note that the snapshot
of the patch baseline might
not remain in place for more
than 24 hours. After that, a new
snapshot will be generated even
if you specify the same ID after
the snapshot expires.

Running AWS- Generate and specify a custom When you are not using a
RunPatchBaseline outside of a GUID value for the Snapshot ID.¹ maintenance window to run
maintenance window AWS-RunPatchBaseline, we
recommend that you generate
and specify a unique Snapshot
ID for each patch baseline,
particularly if you are running
the AWS-RunPatchBaseline
document on multiple instances
in the same operation. If you do
not specify an ID in this scenario,
Systems Manager generates a
different Snapshot ID for each
instance the command is sent
to. This might result in varying
sets of patches being specified
among the instances.

For instance, say that you

are running the AWS-
RunPatchBaseline document
directly via Run Command
and targeting a group of
50 instances. Specifying a
custom Snapshot ID results
in the generation of a single
baseline snapshot that is used
to evaluate and patch all the
instances, ensuring that they
end up in a consistent state.

¹ You can use any tool capable of generating a GUID to generate a value for the Snapshot ID
parameter. For example, in PowerShell, you can use the New-Guid cmdlet to generate a GUID in the
format of 12345699-9405-4f69-bc5e-9315aEXAMPLE.

About Patch Compliance States

After you use Systems Manager Patch Manager to install patches on your instances, compliance status
information is immediately available to you in the console or in response to AWS CLI commands or
corresponding Systems Manager API actions.
Note
If you want to assign a specific patch compliance status to an instance, you can use the put-
compliance-items CLI command or the PutComplianceItems API action. Assigning compliance
status is not supported in the console.

708
 AWS Systems Manager User Guide
About Patch Baselines

Patch Compliance States

For all operating systems, the system reports one of the following compliance states for each patch:

• INSTALLED: Either the patch was already installed, or Patch Manager installed it when the AWS-
RunPatchBaseline document was run on the instance.
• INSTALLED_OTHER: The patch is not in the baseline, but it is installed on the instance. An individual
might have installed it manually.
• INSTALLED_REJECTED: The patch is installed on the instance but is specified in a rejected patches list.
This typically means the patch was installed before it was added to a list of rejected patches.
• MISSING: The patch is approved in the baseline, but it's not installed on the instance. If you configure
the AWS-RunPatchBaseline document task to scan (instead of install) the system reports this status
for patches that were located during the scan, but have not been installed.
• NOT_APPLICABLE: The patch is approved in the baseline, but the service or feature that uses the
patch is not installed on the instance. For example, a patch for Internet Information Services (IIS)
would show NOT_APPLICABLE if it was approved in the baseline, but IIS is not installed on the
instance.
Note
This compliance state is only reported on Windows operating systems.
• FAILED: The patch is approved in the baseline, but it could not be installed. To troubleshoot this
situation, review the command output for information that might help you understand the problem.

About Patch Baselines

The topics in this section provide information about how patch baselines work.

Topics
• About Predefined and Custom Patch Baselines (p. 709)
• About Package Name Formats for Approved and Rejected Patch Lists (p. 712)
• About Patch Groups (p. 714)
• About Patching Schedules Using Maintenance Windows (p. 717)
• About Patch Compliance (p. 718)
• About Patching Applications on Windows Server (p. 719)

About Predefined and Custom Patch Baselines

A patch baseline defines which patches are approved for installation on your instances. You can specify
approved or rejected patches one by one. You can also create auto-approval rules to specify that certain
types of updates (for example, critical updates) should be automatically approved. The rejected list
overrides both the rules and the approve list.

To use a list of approved patches to install specific packages, you first remove all auto-approval rules. If
you explicitly identify a patch as rejected, it will not be approved or installed, even if it matches all of the
criteria in an auto-approval rule. Also, a patch is installed on an instance only if it applies to the software
on the instance, even if the patch has otherwise been approved for the instance.

Patch Manager provides predefined patch baselines for each of the operating systems supported by
Patch Manager. You can use these baselines as they are currently configured (you can't customize them)
or you can create your own patch baselines if you want greater control over which patches are approved
or rejected for your environment.

Topics

709
 AWS Systems Manager User Guide
About Patch Baselines

• About Predefined Baselines (p. 710)

• About Custom Baselines (p. 711)

About Predefined Baselines

The following table describes the predefined patch baselines provided with Patch Manager.

For information about which versions of each operating system Patch Manager supports, see Patch
Manager Prerequisites (p. 684).

Name Supported Operating System Details

AWS- Amazon Linux Approves all operating system

AmazonLinuxDefaultPatchBaseline patches that are classified
as "Security" and that have a
severity level of "Critical" or
"Important". Patches are auto-
approved seven days after
release. Also auto-approves all
patches with a classification of
"Bugfix" seven days after release.

AWS- Amazon Linux 2 Approves all operating system

AmazonLinux2DefaultPatchBaseline patches that are classified
as "Security" and that have
a severity level of "Critical"
or "Important". Patches are
auto-approved seven days
after release. Also approves all
patches with a classification of
"Bugfix" seven days after release.

AWS- CentOS Approves all updates seven days

CentOSDefaultPatchBaseline after they become available,
including nonsecurity updates.

AWS- Red Hat Enterprise Linux (RHEL) Approves all operating system
RedHatDefaultPatchBaseline patches that are classified
as "Security" and that have
a severity level of "Critical"
or "Important". Patches are
auto-approved seven days
after release. Also approves all
patches that are classified as
"Bugfix" seven days after release.

AWS- SUSE Linux Enterprise Server Approves all operating system

SuseDefaultPatchBaseline (SLES) patches that are classified as
"Security" and with a severity of
"Critical" or "Important". Patches
are auto-approved seven days
after release.

AWS- Ubuntu Server Immediately approves all

UbuntuDefaultPatchBaseline operating system security-
related patches that have
a priority of "Required",

710
 AWS Systems Manager User Guide
About Patch Baselines

Name Supported Operating System Details

"Important", "Standard,"
"Optional," or "Extra." There is
no wait before approval because
reliable release dates are not
available in the repos.

AWS-DefaultPatchBaseline Windows Server Approves all Windows Server

operating system patches that
are classified as "CriticalUpdates"
or "SecurityUpdates" and that
have an MSRC severity of
"Critical" or "Important". Patches
are auto-approved seven days
after release.

AWS- Windows Server Approves all Windows Server

WindowsPredefinedPatchBaseline- operating system patches that
OS are classified as "CriticalUpdates"
or "SecurityUpdates" and that
have an MSRC severity of
"Critical" or "Important". Patches
are auto-approved seven days
after release.

AWS- Windows Server For the Windows Server

WindowsPredefinedPatchBaseline- operating system, approves
OS-Applications all patches that are classified
as "CriticalUpdates" or
"SecurityUpdates" and that
have an MSRC severity of
"Critical" or "Important". For
Microsoft applications, approves
all patches. Patches for both
OS and applications are auto-
approved seven days after
release.

About Custom Baselines

If you create your own patch baseline, you can choose which patches to auto-approve by using the
following categories.

• Operating system: Windows, Amazon Linux, Ubuntu Server, and so on.

• Product name (for operating systems): For example, RHEL 6.5, Amazon Linux 2014.09, Windows Server
2012, Windows Server 2012 R2, and so on.
• Product name (for Microsoft applications on Windows Server only): For example, Word 2016, BizTalk
Server, and so on.
• Classification: For example, critical updates, security updates, and so on.
• Severity: For example, critical, important, and so on.

For each auto-approval rule that you create, you can specify an auto-approval delay. This delay is the
number of days to wait after the patch was released, before the patch is automatically approved for
patching. For example, if you create a rule using the Critical Updates classification and configure it for

711
 AWS Systems Manager User Guide
About Patch Baselines

seven days auto-approval delay, then a new critical patch released on January 7 will automatically be
approved on January 14.
Note
If a Linux repository doesn’t provide release date information for packages, Systems Manager
uses the build time of the package as the auto-approval delay for Amazon Linux, Amazon Linux
2, RHEL, and CentOS. If the system isn't able to find the build time of the package, Systems
Manager treats the auto-approval delay as having a value of zero.

You can also specify a compliance severity level. If an approved patch is reported as missing,
Compliance Level is the severity of the compliance violation.

By using multiple patch baselines with different auto-approval delays, you can deploy patches at
different rates to different instances. For example, you can create separate patch baselines and auto-
approval delays for development and production environments. This enables you to test patches in your
development environment before they get deployed in your production environment.

Keep the following in mind when you create a patch baseline:

• Patch Manager provides one predefined patch baseline for each supported operating system. These
predefined patch baselines are used as the default patch baselines for each operating system type
unless you create your own patch baseline and designate it as the default for the corresponding
operating system type.
Note
For Windows Server, two predefined patch baselines are provided. The patch baseline AWS-
WindowsPredefinedPatchBaseline-OS supports only operating system updates on
the Windows operating system itself. It is used as the default patch baseline for Windows
instances unless you specify a different patch baseline. The other predefined Windows patch
baseline, AWS-WindowsPredefinedPatchBaseline-OS-Applications, can be used
to apply patches to both the Windows Server operating system and supported Microsoft
applications.
• For on-premises or non-Amazon EC2 instances, Patch Manager attempts to use your custom default
patch baseline. If no custom default patch baseline exists, the system uses the predefined patch
baseline for the corresponding operating system.
• If a patch is listed as both approved and rejected in the same patch baseline, the patch is rejected.
• An instance can have only one patch baseline defined for it.
• The formats of package names you can add to lists of approved patches and rejected patches for a
patch baseline depend on the type of operating system you are patching.

For information about accepted formats for lists of approved patches and rejected patches, see About
Package Name Formats for Approved and Rejected Patch Lists (p. 712).

For information about creating a patch baseline, see Create a Custom Patch Baseline (p. 721) and
Tutorial: Patch a Server Environment (AWS CLI) (p. 732).

About Package Name Formats for Approved and Rejected Patch

Lists
The formats of package names you can add to lists of approved patches and rejected patches depend on
the type of operating system you are patching.

Package Name Formats for Windows Operating Systems

For Windows operating systems, specify patches using Microsoft Knowledge Base IDs and Microsoft
Security Bulletin IDs; for example:

712
 AWS Systems Manager User Guide
About Patch Baselines

KB2032276,KB2124261,MS10-048

Package Name Formats for Linux Operating Systems

The formats you can specify for approved and rejected patches in your patch baseline vary by Linux type.
More specifically, the formats that are supported depend on the package manager used by the type of
Linux operating system.

Topics
• Amazon Linux, Amazon Linux 2, Red Hat Enterprise Linux (RHEL), and CentOS (p. 713)
• Ubuntu Server (p. 713)
• SUSE Linux Enterprise Server (SLES) (p. 714)

Amazon Linux, Amazon Linux 2, Red Hat Enterprise Linux (RHEL), and CentOS

Package manager: YUM

Approved patches: For approved patches, you can specify any of the following:

• Bugzilla IDs, in the format 1234567 (The system processes numbers-only strings as Bugzilla IDs.)
• CVE IDs, in the format CVE-2018-1234567
• Advisory IDs, in formats such as RHSA-2017:0864 and ALAS-2018-123
• Full package names, in formats such as:
• example-pkg-0.710.10-2.7.abcd.x86_64
• pkg-example-EE-20180914-2.2.amzn1.noarch
• Package-names with a single wildcard, in formats such as:
• example-pkg-*.abcd.x86_64
• example-pkg-*-20180914-2.2.amzn1.noarch
• example-pkg-EE-2018*.amzn1.noarch

Rejected patches: For rejected patches, you can specify any of the following:

• Full package names, in formats such as:

• example-pkg-0.710.10-2.7.abcd.x86_64
• pkg-example-EE-20180914-2.2.amzn1.noarch
• Package-names with a single wildcard, in formats such as:
• example-pkg-*.abcd.x86_64
• example-pkg-*-20180914-2.2.amzn1.noarch
• example-pkg-EE-2018*.amzn1.noarch

Ubuntu Server

Package manager: APT

Approved patches and rejected patches: For both approved and rejected patches, specify the following:

• Package names, in the format ExamplePkg33

Note
For Ubuntu Server lists, do not include elements such as architecture or versions. For example,
you specify the package name ExamplePkg33 to include all the following in a patch list:

713
 AWS Systems Manager User Guide
About Patch Baselines

• ExamplePkg33.x86.1
• ExamplePkg33.x86.2
• ExamplePkg33.x64.1
• ExamplePkg33.3.2.5-364.noarch

SUSE Linux Enterprise Server (SLES)

Package manager: Zypper

Approved patches and rejected patches: For both approved and rejected patch lists, you can specify any
of the following:

• Full package names, in formats such as:

• SUSE-SLE-Example-Package-12-2018-123
• example-pkg-2018.11.4-46.17.1.x86_64.rpm
• Package names with a single wildcard, such as:
• SUSE-SLE-Example-Package-12-2018-*
• example-pkg-2018.11.4-46.17.1.*.rpm

About Patch Groups

You can use a patch group to associate instances with a specific patch baseline. Patch groups help ensure
that you are deploying the appropriate patches, based on the associated patch baseline rules, to the
correct set of instances. Patch groups can also help you avoid deploying patches before they have
been adequately tested. For example, you can create patch groups for different environments (such as
Development, Test, and Production) and register each patch group to an appropriate patch baseline.
Note
A patch group can only be registered with one patch baseline.

When you run AWS-RunPatchBaseline, you can target managed instances using their instance ID or
tags. SSM Agent and Patch Manager then evaluate which patch baseline to use based on the patch group
value that you added to the instance.

You create a patch group by using Amazon EC2 tags. Unlike other tagging scenarios across Systems
Manager, a patch group must be defined with the tag key: Patch Group. Note that the key is case-
sensitive. You can specify any value, for example "web servers," but the key must be Patch Group.
Note
An instance can only be in one patch group.

After you create a patch group and tag instances, you can register the patch group with a patch baseline.
Registering the patch group with a patch baseline ensures that the instances within the patch group use
the rules defined in the associated patch baseline. For more information on how to create a patch group
and associate the patch group to a patch baseline, see Create a Patch Group (p. 725) and Add a Patch
Group to a Patch Baseline (p. 727).

To view an example of creating a patch baseline and patch groups by using the AWS CLI, see Tutorial:
Patch a Server Environment (AWS CLI) (p. 732). For more information about Amazon EC2 tags, see
Tagging Your Amazon EC2 Resources in the Amazon EC2 User Guide.

How It Works
When the system runs the task to apply a patch baseline to an instance, SSM Agent verifies that a patch
group value is defined for the instance. If the instance is assigned to a patch group, Patch Manager then

714
 AWS Systems Manager User Guide
About Patch Baselines

verifies which patch baseline is registered to that group. If a patch baseline is found for that group, Patch
Manager notifies SSM Agent to use the associated patch baseline. If an instance isn't configured for a
patch group, Patch Manager automatically notifies SSM Agent to use the currently configured default
patch baseline.

The following diagram shows a general example of the processes that Systems Manager performs when
sending a Run Command task to your fleet of servers to patch using Patch Manager. A similar process is
used when a maintenance window is configured to send a command to patch using Patch Manager.

In this example, we have three groups of Windows EC2 instances with the following tags applied:

EC2 Instances Group Tags

Group 1 key=OS,value=Windows

key=Patch Group,value=DEV

Group 2 key=OS,value=Windows

Group 3 key=OS,value=Windows

key=Patch Group,value=QA

For this example, we also have these two Windows patch baselines:

Patch Baseline ID Default Associated Patch Group

pb-0123456789abcdef0 Yes Default

pb-9876543210abcdef0 No DEV

Diagram 1: General Example of Patching Operations Process Flow

715
 AWS Systems Manager User Guide
About Patch Baselines

The general process to scan or install patches using Run Command and Patch Manager is as follows:

1. Send a command to patch: Use the Systems Manager console, SDK, AWS CLI, or AWS Tools for
Windows PowerShell to send a Run Command task using the document AWS-RunPatchBaseline.
The diagram shows a Run Command task to patch managed instances by targeting the tag
key=OS,value=Windows.
2. Patch baseline determination: SSM Agent verifies the patch group tags applied to the EC2 instance
and queries Patch Manager for the corresponding patch baseline.
• Matching patch group value associated with patch baseline:

1. SSM Agent, which is installed on EC2 instances in group one, receives the command issued in
Step 1 to begin a patching operation. SSM Agent validates that the EC2 instances have the
patch group tag-value DEV applied and queries Patch Manager for an associated patch baseline.

716
 AWS Systems Manager User Guide
About Patch Baselines

2. Patch Manager verifies that patch baseline pb-9876543210abcdef0 has the patch group DEV
associated and notifies SSM Agent.
3. SSM Agent retrieves a patch baseline snapshot from Patch Manager based on the approval rules
and exceptions configured in pb-9876543210abcdef0 and proceeds to the next step.
• No patch group tag added to instance:

1. SSM Agent, which is installed on EC2 instances in group two, receives the command issued in
Step 1 to begin a patching operation. SSM Agent validates that the EC2 instances don't have
a Patch Group tag applied and as a result, SSM Agent queries Patch Manager for the default
Windows patch baseline.
2. Patch Manager verifies that the default Windows patch baseline is pb-0123456789abcdef0
and notifies SSM Agent.
3. SSM Agent retrieves a patch baseline snapshot from Patch Manager based on the approval
rules and exceptions configured in the default patch baseline pb-0123456789abcdef0 and
proceeds to the next step.
• No matching patch group value associated with a patch baseline:

1. SSM Agent, which is installed on EC2 instances in group three, receives the command issued
in Step 1 to begin a patching operation. SSM Agent validates that the EC2 instances have the
patch group tag-value QA applied and queries Patch Manager for an associated patch baseline.
2. Patch Manager does not find a patch baseline that has the patch group QA associated.
3. Patch Manager notifies SSM Agent to use the default Windows patch baseline
pb-0123456789abcdef0.
4. SSM Agent retrieves a patch baseline snapshot from Patch Manager based on the approval
rules and exceptions configured in the default patch baseline pb-0123456789abcdef0 and
proceeds to the next step.
3. Patch scan or install: After determining the appropriate patch baseline to use, SSM Agent begins
either scanning for or installing patches based on the operation value specified in Step 1. The patches
that are scanned for or installed are determined by the approval rules and patch exceptions defined in
the patch baseline snapshot provided by Patch Manager.

Related Content
About Patch Compliance States (p. 708)

About Patching Schedules Using Maintenance Windows

After you configure a patch baseline (and optionally a patch group), you can apply patches to your
instance by using a maintenance window. A maintenance window can reduce the impact on server
availability by letting you specify a time to perform the patching process that doesn't interrupt business
operations. A maintenance window works like this:

1. Create a maintenance window with a schedule for your patching operations.

2. Choose the targets for the maintenance window by specifying the Patch Group tag for the tag name,
and any value for which you have defined Amazon EC2 tags, for example, "production servers".
3. Create a new maintenance window task, and specify the AWS-RunPatchBaseline document.

When you configure the task, you can choose to either scan instances or scan and install patches on the
instances. If you choose to scan instances, Patch Manager scans each instance and generates a list of
missing patches for you to review.

If you choose to scan and install patches, Patch Manager scans each instance and compares the list of
installed patches against the list of approved patches in the baseline. Patch Manager identifies missing
patches, and then downloads and installs all missing and approved patches.

717
 AWS Systems Manager User Guide
About Patch Baselines

If you want to perform a one-time scan or install to fix an issue, you can use Run Command to call the
AWS-RunPatchBaseline document directly.
Important
After installing patches, Systems Manager reboots each instance. The reboot is required to make
sure that patches are installed correctly and to ensure that the system did not leave the instance
in a potentially bad state.

About Patch Compliance

After you use Systems Manager Patch Manager to install patches on your instances, compliance status
information is immediately available to you in the console or in response to AWS CLI commands or
corresponding Systems Manager API actions.
Note
If you want to assign a specific patch compliance status to an instance, you can use the put-
compliance-items CLI command or the PutComplianceItems API action. Assigning compliance
status is not supported in the console.

Patch Compliance Values for Ubuntu Server

For Ubuntu Server, the rules for package classification into the different compliance states are as follows:

• Installed: Packages that are filtered through the patch baseline, with the candidate version appearing
in trusty-security (Ubuntu Server 14) or xenial-security (Ubuntu Server 16), and are not
upgradable.
• Missing: Packages that are filtered through the baseline, with the candidate version appearing
in trusty-security (Ubuntu Server 14) or xenial-security (Ubuntu Server 16), and are
upgradable.
• Installed Other: Packages that are not filtered through the baseline, with the candidate version
appearing in trusty-security (Ubuntu Server 14) or xenial-security (Ubuntu Server 16), and
are not upgradable. The compliance level for these packages is set to UNSPECIFIED.
• NotApplicable: Packages that are included in ApprovedPatches but are not installed on the system.
• Failed: Packages that failed to install during the patch operation.

Patch Compliance Values for Other Operating Systems

For each patch, the system reports one of the following compliance status values:

• INSTALLED: Either the patch was already installed, or Patch Manager installed it when the AWS-
RunPatchBaseline document was run on the instance.
• INSTALLED_OTHER: The patch is not in the baseline, but it is installed on the instance. An individual
might have installed it manually.
• INSTALLED_REJECTED: The patch is installed on the instance but is specified in a rejected patches list.
This typically means the patch was installed before it was added to a list of rejected patches.
• MISSING: The patch is approved in the baseline, but it's not installed on the instance. If you configure
the AWS-RunPatchBaseline document task to scan (instead of install) the system reports this status
for patches that were located during the scan, but have not been installed.
• NOT_APPLICABLE: The patch is approved in the baseline, but the service or feature that uses the
patch is not installed on the instance. For example, a patch for a web server service would show
NOT_APPLICABLE if it was approved in the baseline, but the web service is not installed on the
instance.
• FAILED: The patch is approved in the baseline, but it could not be installed. To troubleshoot this
situation, review the command output for information that might help you understand the problem.

718
 AWS Systems Manager User Guide
About Patch Baselines

About Patching Applications on Windows Server

For Windows Server, two predefined patch baselines are provided. The patch baseline AWS-
WindowsPredefinedPatchBaseline-OS supports only operating system updates on the
Windows operating system itself. It is used as the default patch baseline for Windows instances
unless you specify a different patch baseline. The other predefined Windows patch baseline, AWS-
WindowsPredefinedPatchBaseline-OS-Applications, can be used to apply patches to both the
Windows Server operating system and supported Microsoft applications.

You can also create a custom patch baseline to update Microsoft applications on Windows Server
machines.

To include Microsoft applications in your custom patch baseline, you must, at a minimum, specify
the product that you want to patch. The following AWS CLI command demonstrates the minimal
requirements to patch a product, such as Office 2016:

aws ssm create-patch-baseline --name "My-Windows-App-Baseline" --approval-rules

"PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT,Values='Office 2016'},
{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"

If you specify the Microsoft application product family, each product you specify must be a supported
member of the selected product family. For example, to patch the product "Active Directory Rights
Management Services Client 2.0," you must specify its product family as "Active Directory" and not, for
example, "Office" or "SQL Server." The following AWS CLI command demonstrates a match pairing of
product family and product:

aws ssm create-patch-baseline --name "My-Windows-App-Baseline" --approval-rules

"PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT_FAMILY,Values='Active
Directory'},{Key=PRODUCT,Values='Active Directory Rights Management Services Client 2.0'},
{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"

Troubleshooting Mismatched Product Family/Product Pairs

When you create a patch baseline in the console, you specify a product family and a product. For
example, you might choose:

• Product family: Office

Product: Office 2016

If you attempt to create a patch baseline with a mismatched product family/product pair, an error
message is displayed. The following are reasons this can occur:

• You selected a valid product family/product pair, but then removed the product family selection.
• You chose a product from the Obsolete or mismatched options sublist instead of the Available and
matching options sublist.

Items in the product Obsolete or mismatched options sublist might have been entered in error
through an SDK or AWS CLI create-patch-baseline command. This could mean a typo was
introduced or a product was assigned to the wrong product family. A product also appears in the
Obsolete or mismatched options sublist if it was specified for a previous patch baseline but currently
has no patches available from Microsoft.

To avoid this issue in the console, always choose options from the Currently available options sublists.

You can also view the products that have currently available patches by using the describe-patch-
properties command in the AWS CLI or the DescribePatchProperties API command.

719
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

Working with Patch Manager (Console)

To use Patch Manager, complete the following tasks. These tasks are described in more detail in this
section.

1. Verify that the AWS predefined patch baseline for each operating system type that you use meets
your needs. If it does not, create a patch baseline that defines a standard set of patches for that
instance type and set it as the default instead.
2. Organize instances into patch groups by using Amazon EC2 tags (optional, but recommended).
3. Schedule patching by using a maintenance window that defines which instances to patch and when to
patch them.
4. Monitor patching to verify compliance and investigate failures.

Related Content

• To view an example of how to create a patch baseline, patch groups, and a maintenance window using
the AWS CLI, see Tutorial: Patch a Server Environment (AWS CLI) (p. 732).
• For more information about maintenance windows, see AWS Systems Manager Maintenance
Windows (p. 444).
• For information about monitoring patch compliance, see About Patch Compliance (p. 508).

Topics
• View AWS Predefined Patch Baselines (p. 720)
• Create a Custom Patch Baseline (p. 721)
• Set an Existing Patch Baseline as the Default (p. 725)
• Create a Patch Group (p. 725)
• Add a Patch Group to a Patch Baseline (p. 727)
• Create a Maintenance Window for Patching (p. 727)
• Create a Patching Configuration (Console) (p. 729)
• Update or Delete a Patch Baseline (Console) (p. 731)

View AWS Predefined Patch Baselines

Patch Manager includes a predefined patch baseline for each operating system supported by Patch
Manager. You can use these patch baselines (you can't customize them), or you can create your own. The
following procedure describes how to view a predefined patch baseline to see if it meets your needs. To
learn more about patch baselines, see About Predefined and Custom Patch Baselines (p. 709).

To view AWS predefined patch baselines

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. In the patch baselines list, choose the baseline ID of one of the predefined patch baselines.
Note
For Windows Server, two predefined patch baselines are provided. The patch baseline AWS-
WindowsPredefinedPatchBaseline-OS supports only operating system updates on

720
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

the Windows operating system itself. It is used as the default patch baseline for Windows
instances unless you specify a different patch baseline. The other predefined Windows
patch baseline, AWS-WindowsPredefinedPatchBaseline-OS-Applications, can
be used to apply patches to both the Windows Server operating system and supported
Microsoft applications.
For more information, see Set an Existing Patch Baseline as the Default (p. 725).
4. Choose the Approval rules tab and review the patch baseline configuration.
5. If the configuration is acceptable for your instances, you can skip ahead to the procedure Create a
Patch Group (p. 725).

-or-

To create your own default patch baseline, continue to the topic Create a Custom Patch
Baseline (p. 721).

Create a Custom Patch Baseline

Patch Manager includes a predefined patch baseline for each operating system supported by Patch
Manager. You can use these patch baselines (you can't customize them), or you can create your own. The
following procedure describes how to create your own custom patch baseline. To learn more about patch
baselines, see About Predefined and Custom Patch Baselines (p. 709).

Depending on the type of operating system you are using, Windows or Linux, use one of the following
procedures.
Note
You can also create a patch baseline using the Amazon EC2 Systems Manager console. However,
this older version of Systems Manager lacks many current features and will be deprecated in the
future.

To create a custom patch baseline (Windows)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. Choose Create patch baseline.
4. For Name, enter a name for your new patch baseline, for example, MyWindowsPatchBaseline.
5. (Optional) Enter a description for this patch baseline.
6. For Operating system, choose Windows.
7. If you want to begin using this patch baseline as the default for Windows as soon as you create it,
select Make this the default patch baseline for Windows Server .

If you choose not to set this patch baseline for use now, you can do so later. For information, see Set
an Existing Patch Baseline as the Default (p. 725).
8. In the Approval rules for Windows Server section, use the fields to create one or more auto-
approval rules.

• Product: The version of the operating systems the approval rule applies to, such as
WindowsServer2008. The default selection is All.
• Classification: The type of patches the approval rule applies to, such as CriticalUpdates. The
default selection is All.

721
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

• Severity: The severity value of patches the rule is to apply to, such as Critical. The default
selection is All.
• Auto approval delay: The number of days to wait after a patch is released before a patch is
automatically approved. You can enter any integer from zero (0) to 100.
• (Optional) Compliance level: The severity level you want to assign to patches approved by the
baseline, such as High.
Note
If an approved patch is reported as missing, the option you choose in Compliance level,
such as Critical or Medium, determines the severity of the compliance violation.
9. In the Approval rules for Microsoft applications section, use the fields to create one or more auto-
approval rules.

• Product family: The general Microsoft product family for which you want to specify a rule, such as
Office or Exchange Server.
• Product: The version of the application the approval rule applies to, such as Office 2016 or Active
Directory Rights Management Services Client 2.0 2016. The default selection is All.
• Classification: The type of patches the approval rule applies to, such as CriticalUpdates. The
default selection is All.
• Severity: The severity value of patches the rule applies to, such as Critical. The default
selection is All.
• Auto approval delay: The number of days to wait after a patch is released before a patch is
automatically approved. You can enter any integer from zero (0) to 100.
• (Optional) Compliance level: The severity level you want to assign to patches approved by the
baseline, such as High.
Note
If an approved patch is reported as missing, the option you choose in Compliance level,
such as Critical or Medium, determines the severity of the compliance violation.
10. If you want to explicitly approve any patches in addition to those meeting your approval rules, do
the following in the Patch exceptions section:

• For Approved patches, enter a comma-separated list of the patches you want to approve.
Note
For information about accepted formats for lists of approved patches and rejected
patches, see About Package Name Formats for Approved and Rejected Patch
Lists (p. 712).
• (Optional) For Approved patches compliance level, assign a compliance level to the patches in
the list.
11. If you want to explicitly reject any patches that otherwise meet your approval rules, do the following
in the Patch exceptions section:

• For Rejected patches, enter a comma-separated list of the patches you want to reject.
Note
For information about accepted formats for lists of approved patches and rejected
patches, see About Package Name Formats for Approved and Rejected Patch
Lists (p. 712).
• For Rejected patches action, select the action for Patch Manager to take on patches included in
the Rejected patches list.
• Allow as dependency: A package in the Rejected patches list is installed only if it is a
dependency of another package. It is considered compliant with the patch baseline and its
status is reported as InstalledOther. This is the default action if no option is specified.
• Block: Packages in the Rejected patches list, and packages that include them as dependencies,
are not installed under any circumstances. If a package was installed before it was added to the

722
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

Rejected patches list, it is considered noncompliant with the patch baseline and its status is
reported as InstalledRejected.

To create a custom patch baseline (Linux)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. In the list of patch baselines, choose the name of a predefined patch baseline for the operating
system you want to patch.
4. Choose the Approval rules tab.

If the auto-approval rules are acceptable for your instances, then you can skip to the next procedure,
Create a Patch Group (p. 725).

-or-

To create a custom patch baseline, in the navigation pane, choose Patch Manager, and then choose
Create patch baseline.
5. For Name, enter a name for your new patch baseline, for example, MyRHELPatchBaseline.
6. (Optional) Enter a description for this patch baseline.
7. For Operating system, choose an operating system, for example, Red Hat Enterprise Linux.
8. If you want to begin using this patch baseline as the default for the selected operating system as
soon as you create it, check the Make this the default patch baseline for the selected operating
system box.

For information about setting an existing patch baseline as the default, see Set an Existing Patch
Baseline as the Default (p. 725).
9. In the Approval rules for operating-system section, use the fields to create one or more auto-
approval rules.

• Product: The version of the operating systems the approval rule applies to, such as
RedhatEnterpriseLinux7.4. The default selection is All.
• Classification: The type of patches the approval rule applies to, such as Security. The default
selection is All.
• Severity: The severity value of patches the rule is to apply to, such as Critical. The default
selection is All.
• Auto approval delay: The number of days to wait after a patch is released before a patch is
automatically approved. You can enter any integer from zero (0) to 100.
• (Optional) Compliance level: The severity level you want to assign to patches approved by the
baseline, such as High.
Note
If an approved patch is reported as missing, the option you choose in Compliance level,
such as Critical or Medium, determines the severity of the compliance violation.
• Include non-security updates: Select the check box to install nonsecurity Linux operating system
patches made available in the source repository, in addition to the security-related patches.
Note
For SUSE Linux Enterprise Server, (SLES) it isn't necessary to select the check box
because patches for security and nonsecurity issues are installed by default on SLES

723
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

instances. For more information, see the content for SLES in How Security Patches Are
Selected (p. 686).

For more information about working with approval rules in a custom patch baseline, see About
Custom Baselines (p. 711).
10. If you want to explicitly approve any patches in addition to those meeting your approval rules, do
the following in the Patch exceptions section:

• For Approved patches, enter a comma-separated list of the patches you want to approve.
Note
For information about accepted formats for lists of approved patches and rejected
patches, see About Package Name Formats for Approved and Rejected Patch
Lists (p. 712).
• (Optional) For Approved patches compliance level, assign a compliance level to the patches in
the list.
• If any approved patches you specify aren't related to security, select the Approved patches
include non-security updates box for these patches to be installed on your Linux operating
system as well.
11. If you want to explicitly reject any patches that otherwise meet your approval rules, do the following
in the Patch exceptions section:

• For Rejected patches, enter a comma-separated list of the patches you want to reject.
Note
For information about accepted formats for lists of approved patches and rejected
patches, see About Package Name Formats for Approved and Rejected Patch
Lists (p. 712).
• For Rejected patches action, select the action for Patch Manager to take on patches included in
the Rejected patches list.
• Allow as dependency: A package in the Rejected patches list is installed only if it is a
dependency of another package. It is considered compliant with the patch baseline and its
status is reported as InstalledOther. This is the default action if no option is specified.
• Block: Packages in the Rejected patches list, and packages that include them as dependencies,
are not installed under any circumstances. If a package was installed before it was added to the
Rejected patches list, it is considered noncompliant with the patch baseline and its status is
reported as InstalledRejected.
12. (Optional) If you want to specify alternative patch repositories for different versions of an operating
system, such as AmazonLinux2016.03 and AmazonLinux2017.09, do the following for each product
in the Patch sources section:

• In Name, enter a name to help you identify the source configuration.

• In Product, select the version of the operating systems the patch source repository is for, such as
RedhatEnterpriseLinux7.4.
• In Configuration, enter the value of the yum repository configuration to use. For example:

[main]
cachedir=/var/cache/yum/$basesearch$releasever
keepcache=0
debuglevel=2

Choose Add another source to specify a source repository for each additional operating system
version, up to a maximum of 20.

724
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

For more information about alternative source patch repositories, see How to Specify an
Alternative Patch Source Repository (Linux) (p. 688).
13. (Optional) For Manage tags, apply one or more tag key name/value pairs to the patch baseline.

Tags are optional metadata that you assign to a resource. Tags enable you to categorize a resource
in different ways, such as by purpose, owner, or environment. For example, you might want to tag a
patch baseline to identify the severity level of patches it specifies and the operating system family it
applies to. In this case, you could specify tags similar to the following key name/value pairs:

• Key=PatchSeverity,Value=Critical
• Key=OS,Value=Windows
14. Choose Create patch baseline.

Set an Existing Patch Baseline as the Default

When you create a custom patch baseline, you can set the baseline as the default for the associated
operating system type as soon as you create it. For information, see Create a Custom Patch
Baseline (p. 721).

You can also set an existing patch baseline as the default for an operating system type.

To set a patch baseline as the default

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. In the patch baselines list, choose the button of a patch baseline that is not currently set as the
default for an operating system type.
Tip
The Default baseline column indicates which baselines are currently set as the defaults.
4. In the Actions menu, choose Set default patch baseline.
5. In the confirmation dialog box, choose Set default.

Create a Patch Group

To help you organize your patching efforts, we recommend that you add instances to patch groups by
using tags. Patch groups require use of the tag key Patch Group. You can specify any value, but the tag
key must be Patch Group. For more information about patch groups, see About Patch Groups (p. 714).

After you group your instances using tags, you must add the patch group value to a patch baseline.
By registering the patch group with a patch baseline, you ensure that the correct patches are installed
during the patching operation. For more information, see the next procedure Add a Patch Group to a
Patch Baseline (p. 727).

Add EC2 Instances to a Patch Group Using Tags

For EC2 instances, you can add tags by using the AWS Systems Manager console, the Amazon EC2
console, the AWS CLI command create-tags, or the API action CreateTags.

725
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

To add EC2 instances to a patch group (AWS Systems Manager console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Managed Instances.
3. In the Managed instances list, choose a managed EC2 instance that you want to configure for
patching.
4. Choose View details.
5. Select the Tags tab, then choose Edit.
6. In the left column, type Patch Group.
7. In the right column, enter a value that helps you understand which instances will be patched.
8. Choose Save.
9. Repeat this procedure to add other managed instances to the same patch group.

To add EC2 instances to a patch group (Amazon EC2 console)

1. Open the Amazon EC2 console, and then choose Instances in the navigation pane.
2. In the list of instances, choose an instance that you want to configure for patching.
3. In the Actions menu, choose Instance Settings, Add/Edit Tags.
4. If the instance already has one or more tags applied, choose Create Tag.
5. For Key, type Patch Group.
6. For Value, enter a value that helps you understand which instances will be patched.
7. Choose Save.
8. Repeat this procedure to add other instances to the same patch group.

To add EC2 instances to a patch group (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to add the Patch Group tag to an EC2 instance.

aws ec2 create-tags --resources "i-1234567890abcdef0" --tags "Key=Patch

Group,Value=GroupValue"

Add Managed Instances to a Patch Group Using Tags

For hybrid managed instances (mi-*), you can add tags by using the AWS Systems Manager console, the
AWS CLI command add-tags-to-resource, or the API action AddTagsToResource. You cannot add
tags for hybrid managed instances using the Amazon EC2 console.

To add managed instances to a patch group (AWS Systems Manager console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Managed Instances.
3. In the Managed instances list, choose a managed instance that you want to configure for patching.
4. Choose View details.
5. Select the Tags tab, then choose Edit.
6. In the left column, type Patch Group.
7. In the right column, enter a value that helps you understand which instances will be patched.

726
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

8. Choose Save.
9. Repeat this procedure to add other managed instances to the same patch group.

To add managed instances to a patch group (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to add the Patch Group tag to a managed instance.

aws ssm add-tags-to-resource --resource-type "ManagedInstance" --resource-

id "mi-0123456789abcdefg" --tags "Key=Patch Group,Value=GroupValue"

Add a Patch Group to a Patch Baseline

To associate a specific patch baseline with your instances, you must add the patch group value to the
patch baseline. By registering the patch group with a patch baseline, you can ensure that the correct
patches are installed during a patching operation. For more information about patch groups, see About
Patch Groups (p. 714).

To add a patch group to a patch baseline (Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.
3. In the Patch Baselines list, choose the patch baseline you want to configure for your patch group.
4. Choose Actions, then Modify patch groups.
5. Enter the tag value you added to your managed instances in the previous section, then choose Add.

To add a patch group to a patch baseline (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to associate a Patch Group tag value to the specified patch baseline.

aws ssm register-patch-baseline-for-patch-group --baseline-id "pb-0123456789abcdef0" --

patch-group "Development"

The system returns information like the following:

{
"PatchGroup": "Development",
"BaselineId": "pb-0123456789abcdef0"
}

Create a Maintenance Window for Patching

Important
You can continue to use this legacy topic to create a maintenance window for patching.
However, we recommend using the Configure patching page instead. For more information, see
Create a Patching Configuration (Console) (p. 729).

727
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

To minimize the impact on your server availability, we recommend that you configure a maintenance
window to run patching during times that won't interrupt your business operations. For more
information about maintenance windows, see AWS Systems Manager Maintenance Windows (p. 444).

You must configure roles and permissions for Maintenance Windows before beginning this procedure.
For more information, see Controlling Access to Maintenance Windows (p. 445).

To create a maintenance window for patching

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Maintenance Windows.
3. Choose Create maintenance window.
4. For Name, enter a name that designates this as a maintenance window for patching critical and
important updates.
5. In the top of the Schedule section, choose the schedule options you want.
6. For Duration, type the number of hours you want the maintenance window to be active.
7. For Stop initiating tasks, type the number of hours before the maintenance window duration ends
that you want the system to stop initiating new tasks.
8. Choose Create maintenance window.
9. In the maintenance windows list, choose the maintenance window you just created, and then choose
Actions, Register targets.
10. (Optional) In the Maintenance window target details section, provide a name, a description, and
owner information (your name or alias) for this target.
11. For Targets, choose Specifying tags.
12. For Tag, enter a tag key and a tag value to identify the instances to register with the maintenance
window.
13. Choose Register target. The system creates a maintenance window target.
14. In the details page of the maintenance window you created, choose Actions, Register run command
task.
15. (Optional) For Maintenance window task details, provide a name and description for this task.
16. For Command document, choose AWS-RunPatchBaseline.
17. For Task priority, choose a priority. One is the highest priority.
18. For Targets, under Target by, choose the maintenance window target you created earlier in this
procedure.
19. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then

728
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
20. For Role, enter the ARN of an IAM role to which the AmazonSSMMaintenanceWindowRole is
attached. For more information, see Controlling Access to Maintenance Windows (p. 445).
21. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
22. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
23. For Parameters:

• For Operation, choose Scan to scan for missing patches, or choose Install to scan for and install
missing patches.
Note
The Install operation causes the instance to reboot (if patches are installed). The Scan
operations does not cause a reboot.
• You don't need to enter anything in the Snapshot Id field. This system automatically generates
and provides this parameter.
• (Optional) For Comment, enter a tracking note or reminder about this command.
• For Timeout (seconds), enter the number of seconds the system should wait for the operation to
finish before it is considered unsuccessful.
24. Choose Register run command task.

After the maintenance window task completes, you can view patch compliance details in the Amazon
EC2 console on the Managed Instances page. In the filter bar, use the AWS:PatchSummary and
AWS:ComplianceItem filters.
Note
You can save your query by bookmarking the URL after you specify the filters.

You can also drill down on a specific instance by choosing the instance in the Managed Instances
page, and then choose the Patch tab. You can also use the DescribePatchGroupState and
DescribeInstancePatchStatesForPatchGroup APIs to view compliance details. For information about
patch compliance data, see About Patch Compliance (p. 508).

Create a Patching Configuration (Console)

A patching configuration defines a unique patching operation. The configuration specifies the instances
for patching, which patch baseline is to be applied, the schedule for patching, and the maintenance
window that the configuration is to be associated with.
Note
Most patching use cases benefit from patching instances on a schedule with a maintenance
window, but you can also run a one-time patching operation manually without a maintenance
window.

To minimize the impact on your server availability, we recommend that you configure a maintenance
window to run patching during times that won't interrupt your business operations. For more
information about maintenance windows, see AWS Systems Manager Maintenance Windows (p. 444).

729
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

If you plan to add the patching configuration to a maintenance window, you must first configure roles
and permissions for Maintenance Windows before beginning this procedure. For more information, see
Controlling Access to Maintenance Windows (p. 445).

To create a patching configuration (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. Choose Configure patching.
4. In the Instances to patch section, choose one of the following:

• Enter instance tags: Enter a tag key and optional tag value to specify the tagged instance to
patch. Click Add to include additional tagged instances.
• Select a patch group: Choose the name of an existing patch group that includes the instances you
want to patch.
Note
The Select a patch group list displays only those patch groups that are attached to, or
registered with, a patch baseline. You can register a patch group with a patch baseline in
one of two ways. You can use the register-patch-baseline-for-patch-group CLI command,
or you can view a patch baseline in the Systems Manager console and select Modify
patch groups from the Actions menu.
Alternatively, to specify an existing patch group that is not registered with the patch
baseline, choose Enter instance tag, type Patch Group as the tag key and the patch
group's name as the tag value.
• Select instances manually: Select the check box next to the name of each instance you want to
patch.
5. In the Patching schedule section, choose one of the following:

• Select an existing maintenance window: From the list, select a maintenance window you have
already created, and then continue to step 7.
• Schedule in a new maintenance window: Create a new maintenance window to associate with
this patching configuration.
• Skip scheduling and patch now: Run a one-time manual patching operation without a schedule
or maintenance window. Continue to step 7.
6. If you chose Schedule in a new maintenance window in step 5, then under How do you want to
specify a patching schedule?, do the following:

• Under How do you want to specify a maintenance window schedule?, choose a schedule builder
or expression option.
• Under maintenance window run frequency, specify how frequently the maintenance window
runs. If you are specifying a CRON/Rate expression, see Reference: Cron and Rate Expressions for
Systems Manager (p. 933) for more information.
• For Maintenance window duration, specify the number of hours the maintenance window is
permitted to run before timing out.
• For Maintenance window name, enter a name to identify the maintenance window.
7. In the Patching operation area, choose whether to scan instances for missing patches and apply
them as needed, or to scan only and generate a list of missing patches.

730
 AWS Systems Manager User Guide
Working with Patch Manager (Console)

8. (Optional) In the Additional settings area, if any target instances you selected belong to a patch
group, you can change the patch baseline that is associated with the patch group. To do so, follow
these steps:

1. Choose the button next to the name of the associated patch baseline.
2. Choose Change patch baseline registration.
3. Choose the patch baselines you want to specify for this configuration by clearing and selecting
check boxes next to the patch baseline names.
4. Choose Close.

Note
For any target instances you selected that are not part of a patch group, Patch Manager
instead uses the default patch baseline for the operating system type of the instance.
9. Choose Configure patching.

If you created a new maintenance window for this patching configuration, you can add to it or make
patching configuration changes in the Maintenance Windows area of Systems Manager. For more
information, see Update or Delete a Maintenance Window (Console) (p. 460).

Update or Delete a Patch Baseline (Console)

You can update or delete a custom patch baseline that you have created. When you update a patch
baseline, you can change its name or description, its approval rules, and its exceptions for approved and
rejected patches. You can also update the tags that are applied to the patch baseline. You can't change
the operating system type that a patch baseline has been created for, and you can't make changes to a
predefined patch baseline provided by AWS.

Update or Delete a Patch Baseline (Console)

Follow these steps to update or delete a patch baseline.

To update or delete a patch baseline (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Patch Manager.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Patch Manager.
3. Choose the patch baseline that you want to update or delete, and then do one of the following:

• To remove the patch baseline from your account, choose Delete. The system prompts you to
confirm your actions.
• To make changes to the patch baseline name or description, approval rules, or patch exceptions,
choose Edit. On the Edit patch baseline page, change the values and options that you want, and
then choose Save changes.
• To add, change, or delete tags applied to the patch baseline, choose the Tags tab, and then
choose Edit tags. On the Edit patch baseline tags page, make updates to the patch baseline tags,
and then choose Save changes.

For information about the configuration choices you can make, see Create a Custom Patch
Baseline (p. 721).

731
 AWS Systems Manager User Guide
Tutorial: Patch a Server Environment (AWS CLI)

Tutorial: Patch a Server Environment (AWS CLI)

The following procedure illustrates how a user might patch a server environment by using a custom
patch baseline, patch groups, and a maintenance window.
Note
You must configure roles and permissions for the Maintenance Windows capability before you
begin. For more information, see Controlling Access to Maintenance Windows (p. 445).

For a sample of other AWS CLI commands you might use for your Patch Manager configuration tasks, see
AWS CLI Commands for Patch Manager (p. 737).

Before You Begin

Install or update the SSM Agent on your instances. To patch Linux instances, your instances must be
running SSM Agent version 2.0.834.0 or later. For information about updating the agent, see the section
titled Example: Update the SSM Agent in Running Commands from the Console (p. 619).

In addition, the following walkthrough runs patching during a maintenance window. You must configure
roles and permissions for the Maintenance Windows capability before you begin. For more information,
see Controlling Access to Maintenance Windows (p. 445).

To configure Patch Manager and patch instances (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. (Windows) Run the following command to create a patch baseline named "Production-Baseline" that
approves patches for a production environment seven days after they are released. In addition, the
patch baseline has been tagged to indicate that it is for a production environment.

aws ssm create-patch-baseline --name "Production-Baseline" --operating-

system "WINDOWS" --tags "Key=Environment,Value=Production" --approval-rules
"PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Critical,Important]},
{Key=CLASSIFICATION,Values=[SecurityUpdates,Updates,UpdateRollups,CriticalUpdates]}]},ApproveAfterD
--description "Baseline containing all updates approved for production systems"

(Linux) Run the following command to create a patch baseline named "Production-Baseline" that
approves patches for a production environment seven days after they are released, including both
security and nonsecurity patches included in the source repository. In addition, the patch baseline
has been tagged to indicate that it is for a production environment.

aws ssm create-patch-baseline --name "Production-Baseline" --operating-system

"AMAZON_LINUX_2" --tags "Key=Environment,Value=Production" --approval-rules
"PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT,Values=[AmazonLinux2,AmazonLinux2.0]},
{Key=SEVERITY,Values=[Critical,Important]},
{Key=CLASSIFICATION,Values=[Security]}]},ApproveAfterDays=7,EnableNonSecurity=true}]"
--description "Baseline containing all updates approved for production systems"

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE"
}

3. Run the following commands to register the "Production-Baseline" patch baseline for three patch
groups named "Production," "Database Servers," and "Front-End Patch Group."

732
 AWS Systems Manager User Guide
Tutorial: Patch a Server Environment (AWS CLI)

aws ssm register-patch-baseline-for-patch-group --baseline-id pb-0c10e65780EXAMPLE --

patch-group "Production"

The system returns information like the following.

{
"PatchGroup":"Production",
"BaselineId":"pb-0c10e65780EXAMPLE"
}

aws ssm register-patch-baseline-for-patch-group --baseline-id pb-0c10e65780EXAMPLE --

patch-group "Database Servers"

The system returns information like the following.

{
"PatchGroup":"Database Servers",
"BaselineId":"pb-0c10e65780EXAMPLE"
}

4. Run the following commands to create two maintenance windows for the production servers.
The first window run every Tuesday at 10 PM. The second window runs every Saturday at 10
PM. In addition, the maintenance window has been tagged to indicate that it is for a production
environment.

aws ssm create-maintenance-window --name "Production-Tuesdays" --tags

"Key=Environment,Value=Production" --schedule "cron(0 0 22 ? * TUE *)" --duration 1 --
cutoff 0 --no-allow-unassociated-targets

The system returns information like the following.

{
"WindowId":"mw-0c66948c711a3b5bd"
}

aws ssm create-maintenance-window --name "Production-Saturdays" --tags

"Key=Environment,Value=Production" --schedule "cron(0 0 22 ? * SAT *)" --duration 2 --
cutoff 0 --no-allow-unassociated-targets

The system returns information like the following.

{
"WindowId":"mw-09e2a75baadd84e85"
}

5. Run the following commands to register the Production servers with the two production
maintenance windows.

aws ssm register-target-with-maintenance-window --window-id mw-0c66948c711a3b5bd

--targets "Key=tag:Patch Group,Values=Production" --owner-information "Production
servers" --resource-type "INSTANCE"

The system returns information like the following.

733
 AWS Systems Manager User Guide
Tutorial: Patch a Server Environment (AWS CLI)

{
"WindowTargetId":"557e7b3a-bc2f-48dd-ae05-e282b5b20760"
}

aws ssm register-target-with-maintenance-window --window-id mw-0c66948c711a3b5bd --

targets "Key=tag:Patch Group,Values=Database Servers" --owner-information "Database
servers" --resource-type "INSTANCE"

The system returns information like the following.

{
"WindowTargetId":"767b6508-f4ac-445e-b6fe-758cc912e55c"
}

aws ssm register-target-with-maintenance-window --window-id mw-09e2a75baadd84e85

--targets "Key=tag:Patch Group,Values=Production" --owner-information "Production
servers" --resource-type "INSTANCE"

The system returns information like the following.

{
"WindowTargetId":"faa01c41-1d57-496c-ba77-ff9cadba4b7d"
}

aws ssm register-target-with-maintenance-window --window-id mw-09e2a75baadd84e85 --

targets "Key=tag:Patch Group,Values=Database Servers" --owner-information "Database
servers" --resource-type "INSTANCE"

The system returns information like the following.

{
"WindowTargetId":"673b5840-58a4-42ab-8b80-95749677cb2e"
}

6. Run the following commands to register a patch task that only scans the production servers for
missing updates in the first production maintenance window.

aws ssm register-task-with-maintenance-window --window-id mw-0c66948c711a3b5bd --

targets "Key=WindowTargetIds,Values=557e7b3a-bc2f-48dd-ae05-e282b5b20760" --task-arn
"AWS-RunPatchBaseline" --service-role-arn "arn:aws:iam::12345678:role/MW-Role" --task-
type "RUN_COMMAND" --max-concurrency 2 --max-errors 1 --priority 1 --task-parameters
'{\"Operation\":{\"Values\":[\"Scan\"]}}'

The system returns information like the following.

{
"WindowTaskId":"968e3b17-8591-4fb2-932a-b62389d6f635"
}

aws ssm register-task-with-maintenance-window --window-id mw-0c66948c711a3b5bd --

targets "Key=WindowTargetIds,Values=767b6508-f4ac-445e-b6fe-758cc912e55c" --task-arn
"AWS-RunPatchBaseline" --service-role-arn "arn:aws:iam::12345678:role/MW-Role" --task-

734
 AWS Systems Manager User Guide
Tutorial: Patch a Server Environment (AWS CLI)

type "RUN_COMMAND" --max-concurrency 2 --max-errors 1 --priority 5 --task-parameters

'{\"Operation\":{\"Values\":[\"Scan\"]}}'

The system returns information like the following.

{
"WindowTaskId":"09f2e873-a3a7-443f-ba0a-05cf4de5a1c7"
}

7. Run the following commands to register a patch task that installs missing updates on the
productions servers in the second maintenance window.

aws ssm register-task-with-maintenance-window --window-id mw-09e2a75baadd84e85 --

targets "Key=WindowTargetIds,Values=557e7b3a-bc2f-48dd-ae05-e282b5b20760" --task-arn
"AWS-RunPatchBaseline" --service-role-arn "arn:aws:iam::12345678:role/MW-Role" --task-
type "RUN_COMMAND" --max-concurrency 2 --max-errors 1 --priority 1 --task-parameters
'{\"Operation\":{\"Values\":[\"Install\"]}}'

The system returns information like the following.

{
"WindowTaskId":"968e3b17-8591-4fb2-932a-b62389d6f635"
}

aws ssm register-task-with-maintenance-window --window-id mw-09e2a75baadd84e85 --

targets "Key=WindowTargetIds,Values=767b6508-f4ac-445e-b6fe-758cc912e55c" --task-arn
"AWS-RunPatchBaseline" --service-role-arn "arn:aws:iam::12345678:role/MW-Role" --task-
type "RUN_COMMAND" --max-concurrency 2 --max-errors 1 --priority 5 --task-parameters
'{\"Operation\":{\"Values\":[\"Install\"]}}'

The system returns information like the following.

{
"WindowTaskId":"09f2e873-a3a7-443f-ba0a-05cf4de5a1c7"
}

8. Run the following command to get the high-level patch compliance summary for a patch group.
The high-level patch compliance summary gives you the number of instances with patches in
the following states for a patch group: "NotApplicable," "Missing," "Failed," "InstalledOther," and
"Installed."

aws ssm describe-patch-group-state --patch-group "Production"

The system returns information like the following.

{
"InstancesWithNotApplicablePatches":0,
"InstancesWithMissingPatches":0,
"InstancesWithFailedPatches":1,
"InstancesWithInstalledOtherPatches":4,
"Instances":4,
"InstancesWithInstalledPatches":3
}

9. Run the following command to get patch summary states per-instance for a patch group. The per-
instance summary gives you a number of patches in the following states per instance for a patch
group: "NotApplicable," "Missing," "Failed," "InstalledOther," and "Installed."

735
 AWS Systems Manager User Guide
Tutorial: Patch a Server Environment (AWS CLI)

aws ssm describe-instance-patch-states-for-patch-group --patch-group "Production"

The system returns information like the following.

{
"InstancePatchStates":[
{
"OperationStartTime":1481259600.0,
"FailedCount":0,
"InstanceId":"i-08ee91c0b17045407",
"OwnerInformation":"",
"NotApplicableCount":2077,
"OperationEndTime":1481259757.0,
"PatchGroup":"Production",
"InstalledOtherCount":186,
"MissingCount":7,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":72
},
{
"OperationStartTime":1481259602.0,
"FailedCount":0,
"InstanceId":"i-0fff3aab684d01b23",
"OwnerInformation":"",
"NotApplicableCount":2692,
"OperationEndTime":1481259613.0,
"PatchGroup":"Production",
"InstalledOtherCount":3,
"MissingCount":1,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":1
},
{
"OperationStartTime":1481259547.0,
"FailedCount":0,
"InstanceId":"i-0a00def7faa94f1dc",
"OwnerInformation":"",
"NotApplicableCount":1859,
"OperationEndTime":1481259592.0,
"PatchGroup":"Production",
"InstalledOtherCount":116,
"MissingCount":1,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":110
},
{
"OperationStartTime":1481259549.0,
"FailedCount":0,
"InstanceId":"i-09a618aec652973a9",
"OwnerInformation":"",
"NotApplicableCount":1637,
"OperationEndTime":1481259837.0,
"PatchGroup":"Production",
"InstalledOtherCount":388,
"MissingCount":2,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":141
}
]

736
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

AWS CLI Commands for Patch Manager

The section includes examples of CLI commands that you can use to perform Patch Manager
configuration tasks.

For an illustration of using the AWS CLI to patch a server environment by using a custom patch baseline,
see Tutorial: Patch a Server Environment (AWS CLI) (p. 732).

For more information about using the CLI for AWS Systems Manager tasks, see the AWS Systems
Manager section of the AWS CLI Command Reference.

Sample commands
• Create a patch baseline (p. 737)
• Create a patch baseline with custom repositories for different OS versions (p. 738)
• Update a patch baseline (p. 739)
• Rename a patch baseline (p. 740)
• Delete a patch baseline (p. 741)
• List all patch baselines (p. 741)
• List all AWS-provided patch baselines (p. 742)
• List my patch baselines (p. 742)
• Display a patch baseline (p. 743)
• Get the default patch baseline (p. 744)
• Set the default patch baseline (p. 744)
• Register a patch group "Web Servers" with a patch baseline (p. 744)
• Register a patch group "Backend" with the AWS-provided patch baseline (p. 744)
• Display patch group registrations (p. 744)
• Deregister a patch group from a patch baseline (p. 745)
• Get all patches defined by a patch baseline (p. 745)
• Get all patches for Windows Server 2012 that have a MSRC severity of Critical (p. 746)
• Get all available patches (p. 746)
• Tag a patch baseline (p. 748)
• List the tags for a patch baseline (p. 748)
• Remove a tag from a patch baseline (p. 748)
• Get patch summary states per-instance (p. 748)
• Get patch compliance details for an instance (p. 749)

Create a patch baseline

The following command creates a patch baseline that approves all critical and important security
updates for Windows Server 2012 R2 five days after they are released. In addition, the patch baseline has
been tagged to indicate that it is for a production environment.

aws ssm create-patch-baseline --name "Windows-Server-2012R2"

--tags "Key=Environment,Value=Production" --approval-rules
"PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Important,Critical]},
{Key=CLASSIFICATION,Values=SecurityUpdates},

737
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

{Key=PRODUCT,Values=WindowsServer2012R2}]},ApproveAfterDays=5}]" --description "Windows

Server 2012 R2, Important and Critical security updates"

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE"
}

Create a patch baseline with custom repositories for different

OS versions
Applies to Linux instances only. The following command shows how to specify the patch repository to
use for a particular version of the Amazon Linux operating system. This sample uses a source repository
enabled by default on Amazon Linux 2017.09, but could be adapted to a different source repository that
you have configured for an instance.
Note
To better demonstrate this more complex command, we are using the --cli-input-json
option with additional options stored an external JSON file.

1. Create a JSON file with a name like my-patch-repository.json and add the following content
to it:

{
"Description": "My patch repository for Amazon Linux 2017.09",
"Name": "Amazon-Linux-2017.09",
"OperatingSystem": "AMAZON_LINUX",
"ApprovalRules": {
"PatchRules": [
{
"ApproveAfterDays": 7,
"EnableNonSecurity": true,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "SEVERITY",
"Values": [
"Important",
"Critical"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"Security",
"Bugfix"
]
},
{
"Key": "PRODUCT",
"Values": [
"AmazonLinux2017.09"
]
}
]
}
}
]
},
"Sources": [

738
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

{
"Name": "My-AL2017.09",
"Products": [
"AmazonLinux2017.09"
],
"Configuration": "[amzn-main] \nname=amzn-main-Base\nmirrorlist=http://
repo./$awsregion./$awsdomain//$releasever/main/mirror.list //nmirrorlist_expire=300//
nmetadata_expire=300 \npriority=10 \nfailovermethod=priority \nfastestmirror_enabled=0
\ngpgcheck=1 \ngpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-amazon-ga \nenabled=1
\nretries=3 \ntimeout=5\nreport_instanceid=yes"
}
]
}

2. In the directory where you saved the file, run the following command:

aws ssm create-patch-baseline --cli-input-json file://my-patch-repository.json

The system returns information like the following:

{
"BaselineId": "pb-12343b962ba63wxya"
}

Update a patch baseline

The following command adds two patches as rejected and one patch as approved to an existing patch
baseline.
Note
For information about accepted formats for lists of approved patches and rejected patches, see
About Package Name Formats for Approved and Rejected Patch Lists (p. 712).

aws ssm update-patch-baseline --baseline-id pb-0c10e65780EXAMPLE --rejected-patches

"KB2032276" "MS10-048" --approved-patches "KB2124261"

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012R2",
"RejectedPatches":[
"KB2032276",
"MS10-048"
],
"GlobalFilters":{
"PatchFilters":[

]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"

739
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"
],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1481001494.035,
"CreatedDate":1480997823.81,
"ApprovedPatches":[
"KB2124261"
],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}

Rename a patch baseline

aws ssm update-patch-baseline --baseline-id pb-0c10e65780EXAMPLE --name "Windows-
Server-2012-R2-Important-and-Critical-Security-Updates"

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012-R2-Important-and-Critical-Security-Updates",
"RejectedPatches":[
"KB2032276",
"MS10-048"
],
"GlobalFilters":{
"PatchFilters":[

]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"
],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"

740
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1481001795.287,
"CreatedDate":1480997823.81,
"ApprovedPatches":[
"KB2124261"
],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}

Delete a patch baseline

aws ssm delete-patch-baseline --baseline-id "pb-0c10e65780EXAMPLE"

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE"
}

List all patch baselines

aws ssm describe-patch-baselines

The system returns information like the following.

{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/
pb-0c10e65780EXAMPLE"
},
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security
updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}

Here is another command that lists all patch baselines in a Region.

741
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

aws ssm describe-patch-baselines --region us-east-2 --filters "Key=OWNER,Values=[All]"

The system returns information like the following.

{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/
pb-0c10e65780EXAMPLE"
},
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security
updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}

List all AWS-provided patch baselines

aws ssm describe-patch-baselines --region us-east-2 --filters "Key=OWNER,Values=[AWS]"

The system returns information like the following.

{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/
pb-0c10e65780EXAMPLE"
}
]
}

List my patch baselines

aws ssm describe-patch-baselines --region us-east-2 --filters "Key=OWNER,Values=[Self]"

The system returns information like the following.

{
"BaselineIdentities":[
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security
updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}

742
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

Display a patch baseline

aws ssm get-patch-baseline --baseline-id pb-0c10e65780EXAMPLE

Note
For custom patch baselines, you can specify either the patch baseline ID or the full ARN. For
AWS-provided patch baseline, you must specify the full ARN. For example, arn:aws:ssm:us-
east-1:075727635805:patchbaseline/pb-03e3f588eec25344c.

The system returns information like the following.

{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012R2",
"PatchGroups":[
"Web Servers"
],
"RejectedPatches":[

],
"GlobalFilters":{
"PatchFilters":[

]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"
],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"
],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1480997823.81,
"CreatedDate":1480997823.81,
"ApprovedPatches":[

],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}

743
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

Get the default patch baseline

aws ssm get-default-patch-baseline --region us-east-2

The system returns information like the following.

{
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}

Set the default patch baseline

aws ssm register-default-patch-baseline --region us-east-2 --baseline-id
"pb-0c10e65780EXAMPLE"

The system returns information like the following:

{
"BaselineId":"pb-0c10e65780EXAMPLE"
}

Register a patch group "Web Servers" with a patch baseline

aws ssm register-patch-baseline-for-patch-group --baseline-id "pb-0c10e65780EXAMPLE" --
patch-group "Web Servers"

The system returns information like the following.

{
"PatchGroup":"Web Servers",
"BaselineId":"pb-0c10e65780EXAMPLE"
}

Register a patch group "Backend" with the AWS-provided patch

baseline
aws ssm register-patch-baseline-for-patch-group --region us-east-2 --baseline-id
"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE" --patch-group
"Backend"

The system returns information like the following.

{
"PatchGroup":"Backend",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}

Display patch group registrations

aws ssm describe-patch-groups --region us-east-2

The system returns information like the following.

744
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

{
"PatchGroupPatchBaselineMappings":[
{
"PatchGroup":"Backend",
"BaselineIdentity":{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":false,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/
pb-0c10e65780EXAMPLE"
}
},
{
"PatchGroup":"Web Servers",
"BaselineIdentity":{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":true,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
}
]
}

Deregister a patch group from a patch baseline

aws ssm deregister-patch-baseline-for-patch-group --region us-east-2 --patch-group
"Production" --baseline-id "arn:aws:ssm:us-east-2:111122223333:patchbaseline/
pb-0c10e65780EXAMPLE"

The system returns information like the following.

{
"PatchGroup":"Production",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}

Get all patches defined by a patch baseline

aws ssm describe-effective-patches-for-patch-baseline --region us-east-2 --baseline-id
"pb-0c10e65780EXAMPLE"

The system returns information like the following.

{
"NextToken":"--token string truncated--",
"EffectivePatches":[
{
"PatchStatus":{
"ApprovalDate":1384711200.0,
"DeploymentStatus":"APPROVED"
},
"Patch":{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2876331",
"ProductFamily":"Windows",
"Product":"WindowsServer2012R2",
"Vendor":"Microsoft",
"Description":"A security issue has been identified in a Microsoft software
product that could affect your system. You can help protect your system by installing

745
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

this update from Microsoft. For a complete listing of the issues that are included in
this update, see the associated Microsoft Knowledge Base article. After you install this
update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows Server 2012 R2 Preview (KB2876331)",
"ReleaseDate":1384279200.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2876331",
"MsrcNumber":"MS13-089",
"Id":"e74ccc76-85f0-4881-a738-59e9fc9a336d"
}
},
{
"PatchStatus":{
"ApprovalDate":1428858000.0,
"DeploymentStatus":"APPROVED"
},
"Patch":{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2919355",
"ProductFamily":"Windows",
"Product":"WindowsServer2012R2",
"Vendor":"Microsoft",
"Description":"Windows Server 2012 R2 Update is a cumulative set of security
updates, critical updates and updates. You must install Windows Server 2012 R2 Update
to ensure that your computer can continue to receive future Windows Updates, including
security updates. For a complete listing of the issues that are included in this update,
see the associated Microsoft Knowledge Base article for more information. After you
install this item, you may have to restart your computer.",
"Classification":"SecurityUpdates",
"Title":"Windows Server 2012 R2 Update (KB2919355)",
"ReleaseDate":1428426000.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2919355",
"MsrcNumber":"MS14-018",
"Id":"8452bac0-bf53-4fbd-915d-499de08c338b"
}
}
---output truncated---

Get all patches for Windows Server 2012 that have a MSRC
severity of Critical
aws ssm describe-available-patches --region us-east-2 --filters
Key=PRODUCT,Values=WindowsServer2012 Key=MSRC_SEVERITY,Values=Critical

The system returns information like the following.

{
"Patches":[
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2727528",
"ProductFamily":"Windows",
"Product":"WindowsServer2012",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could allow an
unauthenticated remote attacker to compromise your system and gain control over it. You
can help protect your system by installing this update from Microsoft. After you install
this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows Server 2012 (KB2727528)",

746
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

"ReleaseDate":1352829600.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2727528",
"MsrcNumber":"MS12-072",
"Id":"1eb507be-2040-4eeb-803d-abc55700b715"
},
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2729462",
"ProductFamily":"Windows",
"Product":"WindowsServer2012",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could allow an
unauthenticated remote attacker to compromise your system and gain control over it. You
can help protect your system by installing this update from Microsoft. After you install
this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Microsoft .NET Framework 3.5 on Windows 8 and Windows
Server 2012 for x64-based Systems (KB2729462)",
"ReleaseDate":1352829600.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2729462",
"MsrcNumber":"MS12-074",
"Id":"af873760-c97c-4088-ab7e-5219e120eab4"
}

---output truncated---

Get all available patches

aws ssm describe-available-patches --region us-east-2

The system returns information like the following.

{
"NextToken":"--token string truncated--",
"Patches":[
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2032276",
"ProductFamily":"Windows",
"Product":"WindowsServer2008R2",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could allow an
unauthenticated remote attacker to compromise your system and gain control over it. You
can help protect your system by installing this update from Microsoft. After you install
this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows Server 2008 R2 x64 Edition (KB2032276)",
"ReleaseDate":1279040400.0,
"MsrcClassification":"Important",
"Language":"All",
"KbNumber":"KB2032276",
"MsrcNumber":"MS10-043",
"Id":"8692029b-a3a2-4a87-a73b-8ea881b4b4d6"
},
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2124261",
"ProductFamily":"Windows",
"Product":"Windows7",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could allow an
unauthenticated remote attacker to compromise your system and gain control over it. You

747
 AWS Systems Manager User Guide
AWS CLI Commands for Patch Manager

can help protect your system by installing this update from Microsoft. After you install
this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows 7 (KB2124261)",
"ReleaseDate":1284483600.0,
"MsrcClassification":"Important",
"Language":"All",
"KbNumber":"KB2124261",
"MsrcNumber":"MS10-065",
"Id":"12ef1bed-0dd2-4633-b3ac-60888aa8ba33"
}
---output truncated---

Tag a patch baseline

aws ssm add-tags-to-resource --resource-type "PatchBaseline" --resource-id
"pb-0c10e65780EXAMPLE" --tags "Key=Project,Value=Testing"

List the tags for a patch baseline

aws ssm list-tags-for-resource --resource-type "PatchBaseline" --resource-id
"pb-0c10e65780EXAMPLE"

Remove a tag from a patch baseline

aws ssm remove-tags-from-resource --resource-type "PatchBaseline" --resource-id
"pb-0c10e65780EXAMPLE" --tag-keys "Project"

Get patch summary states per-instance

The per-instance summary gives you a number of patches in the following states per instance:
"NotApplicable", "Missing", "Failed", "InstalledOther" and "Installed".

aws ssm describe-instance-patch-states --instance-ids i-08ee91c0b17045407

i-09a618aec652973a9 i-0a00def7faa94f1c i-0fff3aab684d01b23

The system returns information like the following.

{
"InstancePatchStates":[
{
"OperationStartTime":"2016-12-09T05:00:00Z",
"FailedCount":0,
"InstanceId":"i-08ee91c0b17045407",
"OwnerInformation":"",
"NotApplicableCount":2077,
"OperationEndTime":"2016-12-09T05:02:37Z",
"PatchGroup":"Production",
"InstalledOtherCount":186,
"MissingCount":7,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":72
},
{
"OperationStartTime":"2016-12-09T04:59:09Z",
"FailedCount":0,

748
 AWS Systems Manager User Guide
Distributor

"InstanceId":"i-09a618aec652973a9",
"OwnerInformation":"",
"NotApplicableCount":1637,
"OperationEndTime":"2016-12-09T05:03:57Z",
"PatchGroup":"Production",
"InstalledOtherCount":388,
"MissingCount":2,
"SnapshotId":"b0e65479-79be-4288-9f88-81c96bc3ed5e",
"Operation":"Scan",
"InstalledCount":141
}
---output truncated---

Get patch compliance details for an instance

aws ssm describe-instance-patches --instance-id i-08ee91c0b17045407

The system returns information like the following.

{
"NextToken":"--token string truncated--",
"Patches":[
{
"KBId":"KB2919355",
"Severity":"Critical",
"Classification":"SecurityUpdates",
"Title":"Windows 8.1 Update for x64-based Systems (KB2919355)",
"State":"Installed",
"InstalledTime":"2014-03-18T12:00:00Z"
},
{
"KBId":"KB2977765",
"Severity":"Important",
"Classification":"SecurityUpdates",
"Title":"Security Update for Microsoft .NET Framework 4.5.1 and 4.5.2 on Windows
8.1 and Windows Server 2012 R2 x64-based Systems (KB2977765)",
"State":"Installed",
"InstalledTime":"2014-10-15T12:00:00Z"
},
{
"KBId":"KB2978126",
"Severity":"Important",
"Classification":"SecurityUpdates",
"Title":"Security Update for Microsoft .NET Framework 4.5.1 and 4.5.2 on Windows
8.1 (KB2978126)",
"State":"Installed",
"InstalledTime":"2014-11-18T12:00:00Z"
},
---output truncated---

AWS Systems Manager Distributor

AWS Systems Manager Distributor lets you package your own software—or find AWS-provided agent
software packages, such as AmazonCloudWatchAgent—to install on AWS Systems Manager managed
instances. Distributor publishes resources, such as software packages, to AWS Systems Manager
managed instances. Publishing a package advertises specific versions of the package's document—a
Systems Manager document (p. 775) that you create when you add the package in Distributor—to
managed instances that you identify by managed instance IDs, AWS account IDs, tags, or an AWS Region.

749
 AWS Systems Manager User Guide
How Can Distributor Benefit my Organization?

After you create a package in Distributor, which creates an AWS Systems Manager document, you can
install the package in one of the following ways.

• One time by using AWS Systems Manager Run Command (p. 613).
• On a schedule by using AWS Systems Manager State Manager (p. 645).

How Can Distributor Benefit my Organization?

Distributor offers these benefits:

• One package, many platforms

One document can have attached ZIP files that are installed on different operating systems (such as
Windows, Ubuntu Server, Debian, or Red Hat Enterprise Linux). For more information about supported
platforms, see Supported Package Platforms and Architectures (p. 751).
• Control package access across groups of managed instances

You can use Run Command or State Manager to control which of your managed instances get a
package and which version of that package. Managed instances can be grouped by instance IDs, AWS
account numbers, tags, or AWS Regions. You can use State Manager associations to deliver different
versions of a package to different groups of instances.
• Many AWS agent packages included and ready to use

Distributor includes many AWS agent packages that are ready for you to deploy to managed instances.
Look for packages in the Distributor Packages list page that are published by Amazon. Examples
include AmazonCloudWatchAgent and AmazonEC2HibernateAgent.
• Automate deployment

To keep your environment current, use State Manager to schedule packages for automatic deployment
on target instances when those instances are first launched.

Who Should Use Distributor?

• Any AWS customer who wants to create new or deploy existing software packages, including AWS-
published packages, to multiple AWS Systems Manager managed instances at one time.
• Software developers who create software packages.
• Administrators who are responsible for keeping AWS Systems Manager managed instances current
with the most up-to-date software packages.

What Are the Features of Distributor?

• Deployment of packages to both Windows and Linux instances

Distributor lets you deploy software packages to Amazon EC2 Windows and Linux instances. For a list
of supported instance operating system types, see the section called “Supported Package Platforms
and Architectures” (p. 751).
• Deploy packages one time, or on an automated schedule

You can choose to deploy packages one time, on a regular schedule, or whenever the default package
version is changed to a different version.
• Console, CLI, PowerShell, and SDK access to Distributor capabilities

750
 AWS Systems Manager User Guide
What Is a Package?

You can work with Distributor by using the AWS Systems Manager console, AWS CLI, AWS Tools for
PowerShell, or the AWS SDK of your choice.
• IAM access control

By using IAM policies, you can control which members of your organization can create, update,
deploy, or delete packages or package versions. For example, you might want to give an administrator
permissions to deploy packages, but not to change packages or create new package versions.
• Logging and auditing capability support

You can audit and log Distributor user actions in your AWS account through integration with other
AWS services. For more information, see Auditing and Logging Distributor Activity (p. 773).

What Is a Package?
A package is a collection of installable software or assets that includes the following.

• A ZIP file of software per target operating system platform. Each ZIP file must include the following.
• An install and an uninstall script. Windows-based instances require PowerShell scripts (scripts
named install.ps1 and uninstall.ps1). Linux-based instances require shell scripts (scripts
named install.sh and uninstall.sh). SSM Agent reads and carries out the instructions in the
install and uninstall scripts.
• An executable file. SSM Agent must find this executable to install the package on target instances.
• A JSON-formatted manifest file that describes the package contents. The manifest is not included
in the ZIP file, but it is stored in the same Amazon S3 bucket as the ZIP files that form the package.
The manifest identifies the package version and maps the ZIP files in the package to target instance
attributes, such as operating system version or architecture. For information about how to create the
manifest, see Step 2: Create the JSON Package Manifest (p. 757).

When you choose Simple package creation in the Distributor console, Distributor generates the
installation and uninstallation scripts, file hashes, and the JSON package manifest for you, based on the
software executable file name and target platforms and architectures.

Supported Package Platforms and Architectures

Distributor supports package distribution to any release version of the following platforms that is
supported as a Systems Manager managed instance. A version value must match the exact release
version of the operating system AMI that you are targeting. For more information about determining this
version, see step 4 of Step 2: Create the JSON Package Manifest (p. 757).

Platform Code Value in Manifest File Architecture

Windows Server windows x86_64 or 386

Debian debian x86_64 or 386

Ubuntu Server ubuntu x86_64 or 386

arm64 (Ubuntu Server 16 and

later, A1 instance types)

Red Hat Enterprise Linux (RHEL) redhat x86_64 or 386

arm64 (RHEL 7.6 and later, A1

instance types)

751
 AWS Systems Manager User Guide
Getting Started with Distributor

Platform Code Value in Manifest File Architecture

CentOS centos x86_64 or 386

Amazon Linux and Amazon amazon x86_64 or 386

Linux 2
arm64 (Amazon Linux 2, A1
instance types)

SUSE Linux Enterprise Server suse x86_64 or 386

(SLES)

openSUSE opensuse x86_64 or 386

openSUSE Leap opensuseleap x86_64 or 386

Topics
• Getting Started with Distributor (p. 752)
• Working with Distributor (p. 754)
• Auditing and Logging Distributor Activity (p. 773)
• Troubleshooting AWS Systems Manager Distributor (p. 773)

Getting Started with Distributor

Before you use Distributor to create, manage, and deploy software packages, follow these steps.

Topics
• Step 1: Complete Distributor Prerequisites (p. 752)
• Step 2: Verify or Create an IAM Instance Profile with Distributor Permissions (p. 753)
• Step 3: Control User Access to Packages (p. 753)
• Step 4: Create or Choose an Amazon S3 Bucket (p. 754)

Step 1: Complete Distributor Prerequisites

Before you use Distributor, be sure your environment meets the following requirements.

Distributor Prerequisites

Requirement Description

SSM Agent SSM Agent version 2.3.274.0 or later must be

installed on the instances to which you want
to deploy or from which you want to remove
packages.

To install or update SSM Agent, see Working with

SSM Agent (p. 64).

AWS CLI (Optional) To use the AWS CLI instead of the AWS
Systems Manager console to create and manage
packages, install the newest release of the AWS
CLI on your local computer.

752
 AWS Systems Manager User Guide
Getting Started with Distributor

Requirement Description
For more information about how to install or
upgrade the CLI, see Installing the AWS Command
Line Interface in the AWS Command Line Interface
User Guide.

AWS Tools for PowerShell (Optional) To use the Tools for PowerShell instead
of the AWS Systems Manager console to create
and manage packages, install the newest release
of Tools for PowerShell on your local computer.

For more information about how to install or

upgrade the Tools for PowerShell, see Setting Up
the AWS Tools for Windows PowerShell or AWS
Tools for PowerShell Core in the AWS Tools for
PowerShell User Guide.

Step 2: Verify or Create an IAM Instance Profile with Distributor

Permissions
By default, AWS Systems Manager doesn't have permission to perform actions on your instances. You
must grant access by using an IAM instance profile. An instance profile is a container that passes IAM role
information to an Amazon EC2 instance at launch. This requirement applies to permissions for all AWS
Systems Manager capabilities, not just Distributor.

If you already use other Systems Manager capabilities, such as Run Command and State Manager, an
instance profile with the required permissions for Distributor is already attached to your instances.
The simplest way to ensure that you have permissions to perform Distributor tasks is to attach the
AmazonSSMManagedInstanceCore policy to your instance profile. For more information, see Create an
IAM Instance Profile for Systems Manager (p. 29).

Step 3: Control User Access to Packages

Using IAM policies, you can control who can create, deploy, and manage packages. You also control
which Run Command and State Manager API actions they can perform on managed instances.

ARN Format

User-defined packages are associated with document ARNs and have the following format:

arn:aws:ssm:region-id:account-id:document/document-name

The following is an example.

arn:aws:ssm:us-west-1:123456789012:document/ExampleDocumentName

You can use a pair of AWS-supplied default IAM policies, one for end users and one for administrators, to
grant permissions for Distributor activities. Or you can create custom IAM policies appropriate for your
permissions requirements.

For more information about using variables in IAM policies, see IAM Policy Elements: Variables.

For information about how to create policies and attach them to IAM users or groups, see Creating IAM
Policies and Adding and Removing IAM Policies in the IAM User Guide.

753
 AWS Systems Manager User Guide
Working with Distributor

Step 4: Create or Choose an Amazon S3 Bucket

When you create a package by using the Simple workflow in the console, you choose an existing S3
bucket to which Distributor uploads your software. In the Advanced workflow, you must upload ZIP files
of your software or assets to an S3 bucket before you begin. Whether you create a package by using
the Simple or Advanced workflows in the console, or by using the API, you must have an S3 bucket
before you start creating your package. As part of the package creation process, Distributor copies your
installable software and assets from this bucket to an internal AWS Systems Manager store. Because the
assets are copied to an internal store, you can delete or repurpose your S3 bucket when package creation
is finished.

For more information about how to create a bucket, see Create a Bucket in the Amazon Simple Storage
Service Getting Started Guide. For more information about how to run an AWS CLI command to create a
bucket, see mb in the AWS CLI Command Reference.

Working with Distributor

You can use the AWS Systems Manager console, AWS CLI, or AWS Tools for PowerShell to add, manage,
or deploy packages in Distributor. Before you add a package to Distributor:

• Create and zip installable assets.

• (Optional) Create a JSON manifest file for the package. This is not required to use the Simple package
creation process in the Distributor console. Simple package creation generates a JSON manifest file for
you.

You can use the AWS Systems Manager console or a text or JSON editor to create the manifest file.
• Have an Amazon S3 bucket ready to store your installable assets or software. If you are using the
Advanced package creation process, upload your assets to the S3 bucket before you begin.
Note
You can delete or repurpose this bucket after you finish creating your package because
Distributor moves the package contents to an internal Systems Manager bucket as part of the
package creation process.

AWS-published packages are already packaged and ready for deployment. To deploy an AWS-published
package to managed instances, see Install Packages (p. 768).

Topics
• Create a Package (p. 754)
• Edit Package Permissions (Console) (p. 764)
• Edit Package Tags (Console) (p. 764)
• Add a Package Version to Distributor (p. 765)
• Install Packages (p. 768)
• Uninstall a Package (p. 771)
• Delete a Package (p. 772)

Create a Package
To create a package, prepare your installable software or assets, one file per operating system platform.
At least one file is required to create a package.

Different platforms might sometimes use the same file, but all files that you attach to your package
must be listed in the Files section of the manifest. If you are creating a package by using the simple

754
 AWS Systems Manager User Guide
Working with Distributor

workflow in the console, the manifest is generated for you. The maximum number of files that you can
attach to a single document is 20. The maximum size of each file is 1 GB. For more information about
supported platforms, see Supported Package Platforms and Architectures (p. 751).

When you create a package, you are adding a new SSM document (p. 775). The document lets you
deploy the package to managed instances.

An example package, ExamplePackage.zip, is available for you to download from our website. The
example package includes a completed JSON manifest and three ZIP files. Although you must zip each
software installable and scripts into a ZIP file to create a package in the Advanced workflow, you do not
zip installable assets in the Simple workflow.

Topics
• Create a Package (Simple) (p. 755)
• Create a Package (Advanced) (p. 756)

Create a Package (Simple)

This section describes how to create a package in Distributor by choosing the Simple package creation
workflow in the Distributor console. To create a package, prepare your installable assets, one file per
operating system platform. At least one file is required to create a package. The Simple package creation
process generates installation and uninstallation scripts, file hashes, and a JSON-formatted manifest
for you. The Simple workflow handles the process of uploading and zipping your installable files, and
creating a new package and associated SSM document (p. 775). For more information about supported
platforms, see Supported Package Platforms and Architectures (p. 751).

To create a package (simple)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose Create package, and then choose Simple.
4. On the Create package page, enter a name for your package. Package names can contain letters,
numbers, periods, dashes, and underscores. The name should be generic enough to apply to all
versions of the package attachments, but specific enough to identify the purpose of the package.
5. In Version name, enter a version name. Version names can be a maximum of 512 characters, and
cannot contain special characters.
6. For S3 bucket name, choose an existing S3 bucket from the list.
7. In S3 key prefix, enter the subfolder of the bucket where your installable assets are stored.
8. In Upload software, browse for installable software files with a suffix of .rpm, .msi, or .deb. You
can upload more than one software file in a single action.
9. For Target platform, verify that the target operating system platform shown for each installable file
is correct. If the operating system shown is not correct, choose the correct operating system from
the drop-down list.

In the Simple package creation workflow, because you upload each installable file only once, extra
steps are required to instruct Distributor to target a single file at multiple operating systems. For
example, if you upload an installable software file named Logtool_v1.1.1.rpm, you must change
some defaults in the Simple workflow to target the same software at both Amazon Linux and
Ubuntu operating systems. You can do one of the following to work around this limitation.

• Use the Advanced workflow instead, zip each installable file into a ZIP file before you begin, and
manually author the manifest so that one installable file can be targeted at multiple operating
system platforms or versions. For more information, see Create a Package (Advanced) (p. 756).

755
 AWS Systems Manager User Guide
Working with Distributor

• Manually edit the manifest file in the Simple workflow so that your ZIP file is targeted at multiple
operating system platforms or versions. For more information about how to do this, see the end of
step 4 in Step 2: Create the JSON Package Manifest (p. 757).
10. For Platform version, verify that the operating system platform version shown is either _any, or the
exact, specific operating system release version to which you want your software to apply. For more
information about specifying an operating system platform version, see step 4 in Step 2: Create the
JSON Package Manifest (p. 757).
11. For Architecture, choose the correct processor architecture for each installable file from the drop-
down list. For more information about supported processor architectures, see Supported Package
Platforms and Architectures (p. 751).
12. (Optional) Expand Installation and uninstallation scripts, and review the scripts that Distributor
generates for your installable software.
13. To add more installable software files, choose Add software. Otherwise, go to the next step.
14. (Optional) Expand Manifest, and review the JSON package manifest that Distributor generates for
your installable software. If you changed any information about your software since you began
this procedure, such as platform version or target platform, choose Generate manifest to show the
updated package manifest.

You can edit the manifest manually if you want to target a software installable at more than one
operating system, as described in step 8. For more information about editing the manifest, see Step
2: Create the JSON Package Manifest (p. 757).
15. When you finish adding software and reviewing target operating system platform, version, and
processor architecture data, choose Upload software and create package.
16. Wait for Distributor to finish uploading your software and creating your package. Distributor
shows upload status for each installable file. Depending on the number and size of packages you
are adding, this can take a few minutes. Distributor automatically redirects you to the Package
details page for the new package, but you can choose to open this page yourself after the software
is uploaded. The Package details page does not show all information about your package until
Distributor finishes the package creation process. To stop the upload and package creation process,
choose Cancel.
17. If Distributor cannot upload any of the software installable files, it displays an Upload
failed message. To retry the upload, choose Retry upload. For more information about
how to troubleshoot package creation failures, see Troubleshooting AWS Systems Manager
Distributor (p. 773).

Create a Package (Advanced)

In this section, learn about how advanced users can create a package in Distributor after uploading
installable assets zipped with installation and uninstallation scripts, and a JSON manifest file, to an
Amazon S3 bucket.

To create a package, prepare your ZIP files of installable assets, one ZIP file per operating system
platform. At least one ZIP file is required to create a package. Next, create a JSON manifest. The manifest
includes pointers to your package code files. When you have your required code files added to a folder,
and the manifest is populated with correct values, upload your package to an Amazon S3 bucket.

An example package, ExamplePackage.zip, is available for you to download from our website. The
example package includes a completed JSON manifest and three ZIP files.

Topics
• Step 1: Create the ZIP Files (p. 757)
• Step 2: Create the JSON Package Manifest (p. 757)
• Step 3: Upload the Package and Manifest to an Amazon S3 Bucket (p. 762)

756
 AWS Systems Manager User Guide
Working with Distributor

• Step 4: Add a Package to Distributor (p. 763)

Step 1: Create the ZIP Files

The foundation of your package is at least one ZIP file of software or installable assets. A package
includes one ZIP file per operating system that you want to support, unless one ZIP file can be installed
on multiple operating systems. For example, Red Hat Enterprise Linux and Amazon Linux instances can
typically run the same .RPM executable files, so you need to attach only one ZIP file to your package to
support both operating systems.

The following items are required in each ZIP file:

• An install and an uninstall script. Windows-based instances require PowerShell scripts (scripts named
install.ps1 and uninstall.ps1). Linux-based instances require shell scripts (scripts named
install.sh and uninstall.sh). SSM Agent runs the instructions in the install and uninstall
scripts.

For example, your installation scripts might run an installer, like an RPM or MSI, they might copy files,
or set configuration settings.
• An executable file, installer packages (RPM, DEB, MSI, etc.), other scripts, or configuration files, etc.

For examples of ZIP files, including sample install and uninstall scripts, download the example package,
ExamplePackage.zip.

Step 2: Create the JSON Package Manifest

After you prepare and zip your installable files, create a JSON manifest. The following is a template. The
parts of the manifest template are described in the procedure in this section. You can use a JSON editor
to create this manifest in a separate file. Alternatively, you can author the manifest in the AWS Systems
Manager console when you create a package.

{
"schemaVersion": "2.0",
"version": "your-version",
"publisher": "optional-publisher-name",
"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-3.zip"
}
}
}
},
"files": {

757
 AWS Systems Manager User Guide
Working with Distributor

"ZIP-file-name-1.zip": {
"checksums": {
"sha256": "checksum"
}
},
"ZIP-file-name-2.zip": {
"checksums": {
"sha256": "checksum"
}
}
}
}

To create a JSON package manifest

1. Add the schema version to your manifest. In this release, the schema version is always 2.0.

{ "schemaVersion": "2.0",

2. Add a user-defined package version to your manifest. This is also the value of Version name that
you specify when you add your package to Distributor. It becomes part of the AWS Systems Manager
document that Distributor creates when you add your package. You also provide this value as an
input in the AWS-ConfigureAWSPackage document to install a version of the package other than
the latest. A version value can contain letters, numbers, underscores, hyphens, and periods, and
be a maximum of 128 characters in length. We recommend that you use a human-readable package
version to make it easier for you and other administrators to specify exact package versions when
you deploy. The following is an example.

"version": "1.0.1",

3. (Optional) Add a publisher name. The following is an example.

"publisher": "MyOrganization",

4. Add packages. The "packages" section describes the platforms, release versions, and architectures
supported by the ZIP files in your package. For more information, see Supported Package Platforms
and Architectures (p. 751).

The platform-version can be the wildcard value, _any. Use it to indicate that a ZIP file supports
any release of the platform. However, a platform-version value must match the exact release
version of the operating system AMI that you are targeting. The following are suggested resources
for getting the correct value of the operating system.

• On a Windows-based instance, the release version is available as Windows Management

Instrumentation (WMI) data. You can run the following Command Prompt command on a
Windows-based instance to get version information, then parse the results for version. This
command does not show the version for Windows Server Nano; the version value for Windows
Server Nano is nano.

wmic OS get /format:list

• On a Linux-based instance, get the version by first scanning for operating system release (the
following command). Look for the value of VERSION_ID.

cat /etc/os-release

If that does not return the results that you need, run the following command to get LSB release
information from the /etc/lsb-release file, and look for the value of DISTRIB_RELEASE.

758
 AWS Systems Manager User Guide
Working with Distributor

lsb_release -a

If these methods fail, you can usually find the release based on the distribution. For example, on
Debian, you can scan the /etc/debian_version file, or on Red Hat Enterprise Linux, the /etc/
redhat-release file.

hostnamectl

"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": "ZIP-file-name-3.zip"
}
}
}
}

The following is an example. In this example, the operating system platform is amazon, the
supported release version is 2016.09, the architecture is x86_64, and the ZIP file that supports this
platform is test.zip.

{
"amazon": {
"2016.09": {
"x86_64": {
"file": "test.zip"
}
}
}
},

You can add the _any wildcard value to indicate that the package supports all versions of the parent
element. For example, to indicate that the package is supported on any release version of Amazon
Linux, your package statement should be similar to the following. You can use the _any wildcard
at the version or architecture levels to support all versions of a platform, or all architectures in a
version, or all versions and all architectures of a platform.

{
"amazon": {
"_any": {
"x86_64": {
"file": "test.zip"

759
 AWS Systems Manager User Guide
Working with Distributor

}
}
}
},

The following example adds _any to show that the first package, data1.zip, is supported for
all architectures of Amazon Linux 2016.09. The second package, data2.zip, is supported for all
releases of Amazon Linux, but only for instances with x86_64 architecture. Both the 2016.09
and _any versions are entries under amazon. There is one platform (Amazon Linux), but different
supported versions, architectures, and associated ZIP files.

{
"amazon": {
"2016.09": {
"_any": {
"file": "data1.zip"
}
},
"_any": {
"x86_64": {
"file": "data2.zip"
}
}
}
}

You can refer to a ZIP file more than once in the "packages" section of the manifest, if the ZIP file
supports more than one platform. For example, if you have a ZIP file that supports both Red Hat
Enterprise Linux and Amazon Linux, you have two entries in the "packages" section that point to
the same ZIP file, as shown in the following example.

{
"amazon": {
"2018.03": {
"x86_64": {
"file": "test.zip"
}
}
},
"redhat": {
"_any": {
"x86_64": {
"file": "test.zip"
}
}
}
},

5. Add the list of ZIP files that are part of this package from step 4. Each file entry requires the file
name and sha256 hash value checksum. Checksum values in the manifest must match the sha256
hash value in the zipped assets to prevent the package installation from failing.

To get the exact checksum from your installables, you can run the following commands. On Linux,
run cat file-name.zip | openssl dgst -sha256. On Windows, run the Get-FileHash -
Path path-to-ZIP-file cmdlet in PowerShell.

The "files" section of the manifest includes one reference to each of the ZIP files in your package.

"files": {
"test-agent-x86.deb.zip": {

760
 AWS Systems Manager User Guide
Working with Distributor

"checksums": {
"sha256":
"EXAMPLE2706223c7616ca9fb28863a233b38e5a23a8c326bb4ae241dcEXAMPLE"
}
},
"test-agent-x86_64.deb.zip": {
"checksums": {
"sha256":
"EXAMPLE572a745844618c491045f25ee6aae8a66307ea9bff0e9d1052EXAMPLE"
}
},
"test-agent-x86_64.nano.zip": {
"checksums": {
"sha256":
"EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel5-x86.nano.zip": {
"checksums": {
"sha256":
"EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
},
"test-agent-x86.msi.zip": {
"checksums": {
"sha256":
"EXAMPLE12a4abb10315aa6b8a7384cc9b5ca8ad8e9ced8ef1bf0e5478EXAMPLE"
}
},
"test-agent-x86_64.msi.zip": {
"checksums": {
"sha256":
"EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel5-x86.rpm.zip": {
"checksums": {
"sha256":
"EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
},
"test-agent-rhel5-x86_64.rpm.zip": {
"checksums": {
"sha256":
"EXAMPLE7ce8a2c471a23b5c90761a180fd157ec0469e12ed38a7094d1EXAMPLE"
}
}
}

6. After you add your package information, save and close the manifest file.

The following is an example of a completed manifest. In this example, you have a ZIP file,
NewPackage_LINUX.zip, that supports more than one platform, but is referenced in the "files"
section only once.

{
"schemaVersion": "2.0",
"version": "1.7.1",
"publisher": "Amazon Web Services",
"packages": {
"windows": {
"_any": {
"x86_64": {
"file": "NewPackage_WINDOWS.zip"

761
 AWS Systems Manager User Guide
Working with Distributor

}
}
},
"amazon": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
},
"ubuntu": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
}
},
"files": {
"NewPackage_WINDOWS.zip": {
"checksums": {
"sha256":
"EXAMPLEc2c706013cf8c68163459678f7f6daa9489cd3f91d52799331EXAMPLE"
}
},
"NewPackage_LINUX.zip": {
"checksums": {
"sha256":
"EXAMPLE2b8b9ed71e86f39f5946e837df0d38aacdd38955b4b18ffa6fEXAMPLE"
}
}
}
}

Package Example

An example package, ExamplePackage.zip, is available for you to download from our website. The
example package includes a completed JSON manifest and three ZIP files.

Step 3: Upload the Package and Manifest to an Amazon S3 Bucket

Prepare your package by copying or moving all ZIP files into a folder or directory. A valid package
requires the manifest that you created in Step 2: Create the JSON Package Manifest (p. 757) and all ZIP
files identified in the manifest file list.

To upload the package and manifest to Amazon S3

1. Copy or move all ZIP archive files that you specified in the manifest to a folder or directory.
2. Create a bucket or choose an existing bucket. For more information, see Create a Bucket in the
Amazon Simple Storage Service Getting Started Guide. For more information about how to run an
AWS CLI command to create a bucket, see mb in the AWS CLI Command Reference.
3. Upload the folder to the bucket. For more information, see Add an Object to a Bucket in the Amazon
Simple Storage Service Getting Started Guide. If you plan to paste your JSON manifest into the AWS
Systems Manager console, do not upload the manifest. For more information about how to run an
AWS CLI command to upload files to a bucket, see mv in the AWS CLI Command Reference.
4. On the bucket's home page, choose the folder that you uploaded. If you uploaded your files to a
subfolder in a bucket, be sure to note the subfolder (also known as a prefix). You need the prefix to
add your package to Distributor.

762
 AWS Systems Manager User Guide
Working with Distributor

Step 4: Add a Package to Distributor

You can use the AWS Systems Manager console or the AWS CLI to add a new package to AWS Systems
Manager Distributor. When you add a package, you are adding a new SSM document (p. 775). The
document lets you deploy the package to managed instances.

Topics
• Adding a Package (Console) (p. 763)
• Adding a Package (AWS CLI) (p. 763)

Adding a Package (Console)

You can use the AWS Systems Manager console to create a package. Have ready the name of the bucket
to which you uploaded your package in Step 3: Upload the Package and Manifest to an Amazon S3
Bucket (p. 762).

To add a package to Distributor (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose Create package, and then choose Advanced.
4. On the Create package page, enter a name for your package. Package names can contain letters,
numbers, periods, dashes, and underscores. The name should be generic enough to apply to all
versions of the package attachments, but specific enough to identify the purpose of the package.
5. In Version name, enter the exact value of the version entry in your manifest file.
6. For S3 bucket name, choose the name of the bucket to which you uploaded your ZIP files and
manifest in the section called “Step 3: Upload the Package and Manifest to an Amazon S3
Bucket” (p. 762).
7. In S3 key prefix, enter the subfolder of the bucket where your ZIP files and manifest are stored.
8. In Manifest, choose Extract from package to use a manifest that you have uploaded to the S3
bucket with your ZIP files.

(Optional) If you did not upload your JSON manifest to the S3 bucket where you stored your ZIP
files, choose New manifest. You can author or paste the entire manifest in the JSON editor field.
For more information about how to create the JSON manifest, see Step 2: Create the JSON Package
Manifest (p. 757).
9. When you are finished with the manifest, choose Create package.
10. Wait for Distributor to create your package from your ZIP files and manifest. Depending on the
number and size of packages you are adding, this can take a few minutes. Distributor automatically
redirects you to the Package details page for the new package, but you can choose to open
this page yourself after the software is uploaded. The Package details page does not show all
information about your package until Distributor finishes the package creation process. To stop the
upload and package creation process, choose Cancel.

Adding a Package (AWS CLI)

You can use the AWS CLI to create a package. Have the URL ready from the bucket to which you
uploaded your package in Step 3: Upload the Package and Manifest to an Amazon S3 Bucket (p. 762).

To add a package to Amazon S3 (AWS CLI)

1. To use the AWS CLI to create a package, run the following command, replacing package-name
with the name of your package and S3-bucket-URL-to-manifest-file with the URL of the
JSON manifest that you copied in Step 3: Upload the Package and Manifest to an Amazon S3

763
 AWS Systems Manager User Guide
Working with Distributor

Bucket (p. 762). S3-bucket-URL-of-package is the URL of the S3 bucket where the entire
package is stored. When you run the create-document command in Distributor, you specify the
Package value for --document-type.

If you did not add your manifest file to the S3 bucket, the --content parameter value is the entire
content of the JSON manifest file, in quotations.

aws ssm create-document --name "package-name" --content "S3-bucket-URL-to-manifest-

file" --attachments Key="SourceUrl",Values="S3-bucket-URL-of-package" --version-
name version-value-from-manifest --document-type Package

The following is an example.

aws ssm create-document --name ExamplePackage --content "https://s3.amazonaws.com/

mybucket/ExamplePackage/manifest.json" --attachments Key="SourceUrl",Values="https://
s3.amazonaws.com/mybucket/ExamplePackage" --version-name 1.0.1 --document-type Package

2. Verify that your package was added and show the package manifest by running the following
command, replacing package-name with the name of your package. To get a specific version of
the document (not the same as the version of a package), you can add the --document-version
parameter.

aws ssm get-document --name "package-name"

For information about other options you can use with the create-document command, see create-
document in the AWS Systems Manager section of the AWS CLI Command Reference. For information
about other options you can use with the get-document command, see get-document.

Edit Package Permissions (Console)

After you have added a package to AWS Systems Manager Distributor, you can edit the package's
permissions in the AWS Systems Manager console. You can add other AWS accounts to a package's
permissions. By default, packages are set to Private, meaning only those with access to the package
creator's AWS account can view package information and update or delete the package. If Private
permissions are acceptable, you can skip this procedure.

To edit package permissions (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Packages page, choose the package for which you want to edit permissions.
4. On the Package details tab, choose Edit permissions to change permissions.
5. In Edit permissions, choose Shared with specific accounts.
6. Under Shared with specific accounts, add AWS account numbers, one at a time. When you are
finished, choose Save.
Note
You cannot share packages with all accounts.

Edit Package Tags (Console)

After you have added a package to AWS Systems Manager Distributor, you can edit the package's tags in
the AWS Systems Manager console. These tags are applied to the package, and are not connected to tags
on the instances to which you want to deploy the package. Tags are case sensitive key and value pairs

764
 AWS Systems Manager User Guide
Working with Distributor

that can help you group and filter your packages by criteria that are relevant to your organization. If you
do not want to add tags, you are ready to install your package or add a new version.

To edit package tags (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Packages page, choose the package for which you want to edit tags.
4. On the Package details tab, in Tags, choose Edit.
5. In Add tags, enter a tag key, or a tag key and value pair, and then choose Add. Repeat if you want to
add more tags. To delete tags, choose X on the tag at the bottom of the window.
6. When you are finished adding tags to your package, choose Save.

Add a Package Version to Distributor

To add a package version, create a package (p. 754), and then use Distributor to add a package version
by adding an entry to the SSM document that already exists for older versions. To save time, update the
manifest for an older version of the package, change the value of the version entry in the manifest (for
example, from Test_1.0 to Test_2.0) and save it as the manifest for the new version. The simple Add
version workflow in the Distributor console updates the manifest file for you.

A new package version can:

• Replace at least one of the installable files attached to the current version.
• Add new installable files to support additional platforms.
• Delete files to discontinue support for specific platforms.

A newer version can use the same S3 bucket, but must have a URL with a different file name shown
at the end. You can use the AWS Systems Manager console or the AWS CLI to add the new version.
Uploading an installable file with the exact name as an existing installable file in the S3 bucket
overwrites the existing file. No installable files are copied over from the older version to the new
version; you must upload installable files from the older version to have them be part of a new version.
After Distributor is finished creating your new package version, you can delete or repurpose the S3
bucket, because Distributor copies your software to an internal Systems Manager bucket as part of the
versioning process.
Note
Each package is limited to a maximum of 25 versions. You can delete versions that are no longer
required.

Topics
• Adding a Package Version (Console) (p. 765)
• Adding a Package Version (AWS CLI) (p. 768)

Adding a Package Version (Console)

Before you perform these steps, follow the instructions in Create a Package (p. 754) to create a new
package for the version. Then, use the AWS Systems Manager console to add a new package version to
Distributor.

Adding a Package Version (Simple)

To add a package version by using the Simple workflow, prepare updated installable files or add
installables to support more platforms and architectures. Then, use Distributor to upload new and

765
 AWS Systems Manager User Guide
Working with Distributor

updated installable files and add a package version. The simplified Add version workflow in the
Distributor console updates the manifest file and associated SSM document for you.

To add a package version (simple)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose the package to which you want to add another version.
4. On the Add version page, choose Simple.
5. In Version name, enter a version name. The version name for the new version must be different
from older version names. Version names can be a maximum of 512 characters, and cannot contain
special characters.
6. For S3 bucket name, choose an existing S3 bucket from the list. This can be the same bucket that
you used to store installable files for older versions, but the installable file names must be different
to avoid overwriting existing installable files in the bucket.
7. In S3 key prefix, enter the subfolder of the bucket where your installable assets are stored.
8. In Upload software, browse for the installable software files that you want to attach to the new
version. Installable files from existing versions are not automatically copied over to a new version;
you must upload any installable files from older versions of the package if you want any of the same
installable files to be part of the new version. You can upload more than one software file in a single
action.
9. For Target platform, verify that the target operating system platform shown for each installable file
is correct. If the operating system shown is not correct, choose the correct operating system from
the drop-down list.

In the Simple versioning workflow, because you upload each installable file only once, extra steps
are required to target a single file at multiple operating systems. For example, if you upload an
installable software file named Logtool_v1.1.1.rpm, you must change some defaults in the
Simple workflow to instruct Distributor to target the same software at both Amazon Linux and
Ubuntu operating systems. You can do one of the following to work around this limitation.

• Use the Advanced versioning workflow instead, zip each installable file into a ZIP file before you
begin, and manually author the manifest so that one installable file can be targeted at multiple
operating system platforms or versions. For more information, see Adding a Package Version
(Advanced) (p. 767).
• Manually edit the manifest file in the Simple workflow so that your ZIP file is targeted at multiple
operating system platforms or versions. For more information about how to do this, see the end of
step 4 in Step 2: Create the JSON Package Manifest (p. 757).
10. For Platform version, verify that the operating system platform version shown is either _any, or the
exact, specific operating system release version to which you want your software to apply. For more
information about specifying a platform version, see step 4 in Step 2: Create the JSON Package
Manifest (p. 757).
11. For Architecture, choose the correct processor architecture for each installable file from the drop-
down list. For more information about supported architectures, see Supported Package Platforms
and Architectures (p. 751).
12. (Optional) Expand Installation and uninstallation scripts, and review the installation and
uninstallation scripts that Distributor generates for your installable software.
13. To add more installable software files to the new version, choose Add software. Otherwise, go to
the next step.
14. (Optional) Expand Manifest, and review the JSON package manifest that Distributor generates for
your installable software. If you changed any information about your installable software since you
began this procedure, such as platform version or target platform, choose Generate manifest to
show the updated package manifest.

766
 AWS Systems Manager User Guide
Working with Distributor

You can edit the manifest manually if you want to target a software installable at more than one
operating system, as described in step 9. For more information about editing the manifest, see Step
2: Create the JSON Package Manifest (p. 757).
15. When you finish adding software and reviewing the target platform, version, and architecture data,
choose Add version.
16. Wait for Distributor to finish uploading your software and creating the new package version.
Distributor shows upload status for each installable file. Depending on the number and size of
packages you are adding, this can take a few minutes. Distributor automatically redirects you to
the Package details page for the package, but you can choose to open this page yourself after the
software is uploaded. The Package details page does not show all information about your package
until Distributor finishes creating the new package version. To stop the upload and package version
creation, choose Stop upload.
17. If Distributor cannot upload any of the software installable files, it displays an Upload failed
message. To retry the upload, choose Retry upload. For more information about how to
troubleshoot package version creation failures, see Troubleshooting AWS Systems Manager
Distributor (p. 773).
18. When Distributor is finished creating the new package version, on the package's Details page, on the
Versions tab, view the new version in the list of available package versions. Set a default version of
the package by choosing a version, and then choosing Set default version.

If you do not set a default version, the newest package version is the default version.

Adding a Package Version (Advanced)

To add a package version, create a package (p. 754), and then use Distributor to add a package version
by adding an entry to the SSM document that exists for older versions. To save time, update the manifest
for an older version of the package, change the value of the version entry in the manifest (for example,
from Test_1.0 to Test_2.0) and save it as the manifest for the new version. You must have an
updated manifest to add a new package version by using the Advanced workflow.

To add a package version (advanced)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose the package to which you want to add another version, and
then choose Add version.
4. In Version name, enter the exact value that is in the version entry of your manifest file.
5. For S3 bucket name, choose an existing S3 bucket from the list. This can be the same bucket that
you used to store installable files for older versions, but the installable file names must be different
to avoid overwriting existing installable files in the bucket.
6. In S3 key prefix, enter the subfolder of the bucket where your installable assets are stored.
7. In Manifest, choose Extract from package to use a manifest that you uploaded to the S3 bucket
with your ZIP files.

(Optional) If you did not upload your revised JSON manifest to the S3 bucket where you stored your
ZIP files, choose New manifest. You can author or paste the entire manifest in the JSON editor field.
For more information about how to create the JSON manifest, see Step 2: Create the JSON Package
Manifest (p. 757).
8. When you are finished with the manifest, choose Add package version.
9. On the package's Details page, on the Versions tab, view the new version in the list of available
package versions. Set a default version of the package by choosing a version, and then choosing Set
default version.

767
 AWS Systems Manager User Guide
Working with Distributor

If you do not set a default version, the newest package version is the default version.

Adding a Package Version (AWS CLI)

You can use the AWS CLI to add a new package version to Distributor. Before you run these commands,
you must create a new package version and upload it to S3, as described at the start of this topic.

To add a package version (AWS CLI)

1. Run the following command to edit the AWS Systems Manager document with an entry for a new
package version. Replace document-name with the name of your document. Replace S3-bucket-
URL-to-manifest-file with the URL of the JSON manifest that you copied in Step 3: Upload
the Package and Manifest to an Amazon S3 Bucket (p. 762). S3-bucket-URL-of-package is the
URL of the S3 bucket where the entire package is stored. Replace version-name-from-updated-
manifest with the value of version in the manifest. Set the --document-version parameter
to $LATEST to make the document associated with this package version the latest version of the
document.

aws ssm update-document --name "document-name" --content "S3-bucket-URL-to-manifest-

file" --attachments Key="SourceUrl",Values="S3-bucket-URL-of-package" --version-
name version-name-from-updated-manifest --document-version $LATEST

The following is an example.

aws ssm update-document --name ExamplePackage --content "https://s3.amazonaws.com/

mybucket/ExamplePackage/manifest.json" --attachments Key="SourceUrl",Values="https://
s3.amazonaws.com/mybucket/ExamplePackage" --version-name 1.1.1 --document-version
$LATEST

2. Run the following command to verify that your package was updated and show the package
manifest. Replace package-name with the name of your package, and optionally, document-
version with the version number of the document (not the same as the package version) that
you updated. If this package version is associated with the latest version of the document, you can
specify $LATEST for the value of the optional --document-version parameter.

aws ssm get-document --name "package-name" --document-version "document-version"

For information about other options you can use with the update-document command, see update-
document in the AWS Systems Manager section of the AWS CLI Command Reference.

Install Packages
You can use the AWS Management Console or the AWS CLI to deploy packages to your AWS Systems
Manager managed instances by using AWS Systems Manager Distributor. You can currently deploy one
version of one package per command. You can choose to deploy a specific version or choose to always
deploy the latest version of a package for deployment.

Preference AWS Systems Manager Action More Information

Install a package immediately. Run Command Installing a Package One Time

(Console) (p. 769) or Installing
a Package One Time (AWS
CLI) (p. 770)

768
 AWS Systems Manager User Guide
Working with Distributor

Preference AWS Systems Manager Action More Information

Install a package on a schedule, State Manager Scheduling a Package

so that the installation always Installation (Console) (p. 770)
includes the default version. or Scheduling a Package
Installation (AWS CLI) (p. 771)

Automatically install a package State Manager One way to do this is to apply

on new instances that have a tags to new instances, and then
specific tag or set of tags. For specify the tags as targets in
example, installing the Amazon your State Manager association.
CloudWatch agent on new State Manager automatically
instances. installs the package in an
association on instances that
have matching tags. See Create
an Association That Uses
Targets and Rate Controls
(Console) (p. 652).

Topics
• Installing a Package One Time (Console) (p. 769)
• Scheduling a Package Installation (Console) (p. 770)
• Installing a Package One Time (AWS CLI) (p. 770)
• Scheduling a Package Installation (AWS CLI) (p. 771)

Installing a Package One Time (Console)

You can use the AWS Systems Manager console to install a package one time. When you configure a
one-time installation, Distributor uses AWS Systems Manager Run Command (p. 613) to perform the
installation.

To install a package one time (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose the package that you want to install.
4. To install the default package version, you can choose Install package from the package details
page. To install another version, choose the Versions tab, choose the version you want to install, and
then choose Install package.
5. In Install package, choose Install one time.

This command opens Systems Manager Run Command with the command document AWS-
ConfigureAWSPackage and your Distributor package already selected.
6. Keep Install as the value of Action. For Name, enter the name of the package that you want to
install.
7. For Version, enter the Version name value of the package. If you leave this field blank, Run
Command installs the default version that you selected in Distributor.
8. In Targets, choose target managed instances by specifying a tag key and values that are shared
by the managed instances, or specify instances by any of seven attributes, including instance ID,
platform, and SSM Agent version.
9. You can use the advanced options to add comments about the installation, change Concurrency
and Error threshold values in Rate control, specify output options, or configure Amazon Simple

769
 AWS Systems Manager User Guide
Working with Distributor

Notification Service (Amazon SNS) notifications. For more information, see Running Commands
from the Console in this guide.
10. When you are ready to install the package, choose Run, and then choose View results.
11. In the commands list, choose the AWS-ConfigureAWSPackage command that you ran. If the
command is still in progress, choose the refresh icon in the top-right corner of the console.
12. When the Status column shows Success or Failed, choose the Output tab.
13. Choose View output. The command output page shows the results of your command execution.

Scheduling a Package Installation (Console)

You can use the AWS Systems Manager console to schedule the installation of a package. When you
schedule package installation, Distributor uses AWS Systems Manager State Manager (p. 645) to
perform the installation.

To schedule a package installation (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose the package that you want to install.
4. To install the default package version, you can choose Install package from the package details
page. To install another version, choose the Versions tab, choose the version you want to install, and
then choose Install package. If you do not choose a version, Systems Manager installs the default
version.
5. In Install package, choose Install on a schedule.

This command opens Systems Manager State Manager to a new association that is created for you.
6. In Name, enter a name (for example, Deploy-test-agent-package). This is optional, but
recommended. Spaces aren't allowed in the name.
7. In the Command document list, the document name AWS-ConfigureAWSPackage is already
selected. Verify that the Package value is set to the name of your package. Verify that in
Parameters, for Operation, Install is already selected.
8. For Targets, choose Selecting all managed instances in this account, Specifying tags, or Manually
Selecting Instance. If you target resources by using tags, enter a tag key and a tag value in the fields
provided.
9. For Specify schedule, choose On Schedule to run the association on a regular schedule, or No
Schedule to run the association once. For more information about these options, see Create an
Association (p. 647) in this guide. Use the controls to create a cron or rate schedule for the
association.
10. For more information about advanced options, such as compliance severity, rate control, and output
options, see Create an Association (p. 647) in this guide. When you are finished editing your
association, choose Save Changes.
11. On the association's home page, choose Apply association now.

State Manager creates and immediately runs the association on the specified instances or targets.
For more information about the results of running associations, see Create an Association (p. 647)
in this guide.

Installing a Package One Time (AWS CLI)

You can run send-command in the AWS CLI to install a Distributor package one time.

770
 AWS Systems Manager User Guide
Working with Distributor

To install a package one time (AWS CLI)

• Run the following command in the AWS CLI.

aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-ids

"instance-IDs" --parameters '{"action":["Install"],"name":["package-name (in same
account) or package-ARN (shared from different account)"]}'

The following is an example.

aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-ids

"i-00000000000000" --parameters '{"action":["Install"],"name":["ExamplePackage"]}'

For information about other options you can use with the send-command command, see send-
command in the AWS Systems Manager section of the AWS CLI Command Reference.

Scheduling a Package Installation (AWS CLI)

You can run create-association in the AWS CLI to install a Distributor package on a schedule. The value
of --name, the document name, is always AWS-ConfigureAWSPackage. The following command uses
the key InstanceIds to specify target instances.

aws ssm create-association --name "AWS-ConfigureAWSPackage" --parameters '{"action":

["Install"],"name":["package-name (in same account) or package-ARN (shared from different
account)"]}' --targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance-ID1\",\"instance-
ID2\"]}]

The following is an example.

aws ssm create-association --name "AWS-ConfigureAWSPackage" --parameters '{"action":

["Install"],"name":["Test-ConfigureAWSPackage"]}' --targets [{\"Key\":\"InstanceIds\",
\"Values\":[\"i-000100010000010\",\"i-020100010000011\"]}]

For information about other options you can use with the create-association command, see create-
association in the AWS Systems Manager section of the AWS CLI Command Reference.

Uninstall a Package
You can use the AWS Management Console or the AWS CLI to uninstall Distributor packages from your
AWS Systems Manager managed instances by using Run Command. In this release, you can uninstall one
version of one package per command. You can uninstall a specific version or the default version.

Topics
• Uninstalling a Package (Console) (p. 771)
• Uninstalling a Package (AWS CLI) (p. 772)

Uninstalling a Package (Console)

You can use Run Command in the AWS Systems Manager console to uninstall a package one time.
Distributor uses AWS Systems Manager Run Command (p. 613) to uninstall packages.

To uninstall a package (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

771
 AWS Systems Manager User Guide
Working with Distributor

2. In the navigation pane, choose Run Command.

3. On the Run Command home page, choose Run command.
4. Choose the AWS-ConfigureAWSPackage command document.
5. From Action, choose Uninstall
6. For Name, enter the name of the package that you want to uninstall.
7. In Targets, choose target managed instances by specifying a tag key and values that are shared
by the managed instances, or specify instances by any of seven attributes, including instance ID,
platform, and SSM Agent version.
8. You can use the advanced options to add comments about the operation, change Concurrency
and Error threshold values in Rate control, specify output options, or configure Amazon SNS
notifications. For more information, see Running Commands from the Console in this guide.
9. When you are ready to uninstall the package, choose Run, and then choose View results.
10. In the commands list, choose the AWS-ConfigureAWSPackage command that you ran. If the
command is still in progress, choose the refresh icon in the top-right corner of the console.
11. When the Status column shows Success or Failed, choose the Output tab.
12. Choose View output. The command output page shows the results of your command execution.

Uninstalling a Package (AWS CLI)

You can use the AWS CLI to uninstall a Distributor package from managed instances by using Run
Command.

To uninstall a package (AWS CLI)

• Run the following command in the AWS CLI.

aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-ids

"instance-IDs" --parameters '{"action":["Uninstall"],"name":["package-name (in same
account) or package-ARN (shared from different account)"]}'

The following is an example.

aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-

ids "i-00000000000000" --parameters '{"action":["Uninstall"],"name":["Test-
ConfigureAWSPackage"]}'

For information about other options you can use with the send-command command, see send-
command in the AWS Systems Manager section of the AWS CLI Command Reference.

Delete a Package
Deleting a Package (Console)
You can use the AWS Systems Manager console to delete a package from Distributor. Deleting a package
deletes all versions of a package from Distributor.

To delete a package (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Distributor.
3. On the Distributor home page, choose the package that you want to delete.
4. On the package's details page, choose Delete package.

772
 AWS Systems Manager User Guide
Auditing and Logging Distributor Activity

5. When you are prompted to confirm the deletion, choose Delete package.

Deleting a Package (AWS CLI)

You can use the AWS CLI to delete a package from Distributor.

To delete a package (AWS CLI)

1. Run the following command to list documents for specific packages. In the results of this command,
look for the package that you want to delete.

aws ssm list-documents --filters [{\"Key\":\"Name\",\"Values\":[\"package-name\",

\"another-package-name\"]}]

2. Run the following command to delete a package version. Replace package-name with the package
name.

aws ssm delete-document --name "package-name"

3. Run the list-documents command again to verify that the package version was deleted. The
package version that you deleted should no longer be found.

aws ssm list-documents --filters [{\"Key\":\"Name\",\"Values\":[\"package-name\",

\"another-package-name\"]}]

For information about other options you can use with the list-documents command, see list-documents
in the AWS Systems Manager section of the AWS CLI Command Reference. For information about other
options you can use with the delete-document command, see delete-document.

Auditing and Logging Distributor Activity

For more information about auditing and logging options for AWS Systems Manager, see Monitoring
AWS Systems Manager (p. 882).

Audit Distributor Activity Using AWS CloudTrail

AWS CloudTrail captures API calls made in the Systems Manager console, the AWS CLI, and the Systems
Manager SDK. The information can be viewed in the CloudTrail console or stored in an Amazon S3
bucket. One bucket is used for all CloudTrail logs for your account.

Logs of Run Command and State Manager actions show document creation, package installation, and
package uninstallation activity. For more information about viewing and using CloudTrail logs of Systems
Manager activity, see Logging AWS Systems Manager API Calls with AWS CloudTrail (p. 889).

Troubleshooting AWS Systems Manager Distributor

The following information can help you troubleshoot problems that might occur when you use
Distributor.

Topics
• Wrong Package with the Same Name Is Installed (p. 774)
• Error: Failed to Retrieve Manifest: Could not find latest version of package (p. 774)
• Error: Failed to Retrieve Manifest: Validation exception (p. 774)

773
 AWS Systems Manager User Guide
Troubleshooting Distributor

Wrong Package with the Same Name Is Installed

Problem: You've installed a package, but AWS Systems Manager Distributor installed a different package
instead.

Cause: During installation, AWS Systems Manager finds AWS-published packages as results before user-
defined external packages. If your user-defined package name is the same as an AWS-published package
name, the AWS package is installed instead of your package.

Solution: To avoid this problem, name your package something different from the name for an AWS-
published package.

Error: Failed to Retrieve Manifest: Could not find latest version

of package
Problem: You received an error like the following:

Failed to retrieve manifest: ResourceNotFoundException: Could not find the latest version
of package
arn:aws:ssm:::package/package-name status code: 400, request id: guid

Cause: You are using a version of SSM Agent with Systems Manager Distributor that is earlier than
version 2.3.274.0.

Solution: Update the version of SSM Agent to version 2.3.274.0 or later. For more information,
see Update SSM Agent by using Run Command (p. 620) or Automatically Update SSM Agent
(CLI) (p. 681).

Error: Failed to Retrieve Manifest: Validation exception

Problem: You received an error like the following:

Failed to retrieve manifest: ValidationException: 1 validation error detected: Value

'documentArn'
at 'packageName' failed to satisfy constraint: Member must satisfy regular expression
pattern:
arn:aws:ssm:region-id:account-id:package/package-name

Cause: You are using a version of SSM Agent with Systems Manager Distributor that is earlier than
version 2.3.274.0.

Solution: Update the version of SSM Agent to version 2.3.274.0 or later. For more information,
see Update SSM Agent by using Run Command (p. 620) or Automatically Update SSM Agent
(CLI) (p. 681).

774
 AWS Systems Manager User Guide
SSM Documents

AWS Systems Manager Shared

Resources
Systems Manager uses the following shared resources for managing and configuring your AWS resources.

Topics
• AWS Systems Manager Documents (p. 775)
• AWS Systems Manager Parameter Store (p. 825)

AWS Systems Manager Documents

An AWS Systems Manager document (SSM document) defines the actions that Systems Manager
performs on your managed instances. Systems Manager includes more than a dozen pre-configured
documents that you can use by specifying parameters at runtime. Documents use JavaScript Object
Notation (JSON) or YAML, and they include steps and parameters that you specify.

Types of SSM Documents

The following table describes the different types of SSM documents.

Type Use with Details

Command document Run Command (p. 613) Run Command uses command
documents to run commands.
State Manager (p. 645) State Manager uses command
documents to apply a
Maintenance Windows (p. 444) configuration. These actions
can be run on one or more
targets at any point during
the lifecycle of an instance.
Maintenance Windows uses
command documents to apply
a configuration based on the
specified schedule.

Automation document Automation (p. 142) Use automation documents

when performing common
State Manager (p. 645) maintenance and deployment
tasks such as creating or
Maintenance Windows (p. 444) updating an Amazon Machine
Image (AMI). State Manager
uses automation documents
to apply a configuration. These
actions can be run on one or
more targets at any point during
the lifecycle of an instance.

775
 AWS Systems Manager User Guide
SSM Documents

Type Use with Details

Maintenance Windows uses
automation documents to
perform common maintenance
and deployment tasks based on
the specified schedule.

Package document Distributor (p. 749) In Distributor, a package is

represented by a Systems
Manager document. A package
document includes attached
ZIP archive files that contain
software or assets to install on
managed instances. Creating a
package in Distributor creates
the package document.

Session document Session Manager (p. 567) Session Manager uses session
documents to determine which
type of session to start, such
as a port forwarding session,
a session to run an interactive
command, or a session to create
an SSH tunnel.

Policy document State Manager (p. 645) Systems Manager

Inventory uses the AWS-
GatherSoftwareInventory policy
document with a State Manager
association to collect inventory
data from managed instances.
When creating your own
SSM documents, Automation
documents and Run Command
documents are the preferred
method for enforcing a policy on
a managed instance.

SSM Document Versions and Execution

You can create and save different versions of documents. You can then specify a default version for each
document. The default version of a document can be updated to a newer version or reverted to an older
version of the document. When you change the content of a document, Systems Manager automatically
increments the version of the document. You can retrieve and use previous versions of a document.

Customizing a Document

If you want to customize the steps and actions in a document, you can create your own. The first time
you use a document to perform an action on an instance, the system stores the document with your AWS
account. For more information about how to create a Systems Manager document, see Creating Systems
Manager Documents (p. 784).

Tagging a Document

You can tag your documents to help you quickly identify one or more documents based on the tags
you've assigned to them. For example, you can tag documents for specific environments, departments,
users, groups, or periods. You can also restrict access to documents by creating an IAM policy that

776
 AWS Systems Manager User Guide
Systems Manager Pre-Defined Documents

specifies the tags that a user or group can access. For more information, see Tagging Systems Manager
Documents (p. 787).

Sharing a Document

You can make your documents public or share them with specific AWS accounts. Sharing documents
between accounts can be useful if, for example, you want all of the Amazon EC2 instances that you
supply to customers or employees to have the same configuration. In addition to keeping applications
or patches on the instances up-to-date, you might want to restrict customer instances from certain
activities. Or you might want to ensure that the instances used by employee accounts throughout your
organization are granted access to specific internal resources. For more information, see Sharing Systems
Manager Documents (p. 790).

SSM Document Limits

For information about SSM document limits, see AWS Systems Manager Limits.

Topics
• Systems Manager Pre-Defined Documents (p. 777)
• SSM Document Schemas and Features (p. 778)
• SSM Document Syntax (p. 779)
• Creating Systems Manager Documents (p. 784)
• Tagging Systems Manager Documents (p. 787)
• Sharing Systems Manager Documents (p. 790)
• Creating Composite Documents (p. 796)
• Running Documents from Remote Locations (p. 797)
• SSM Document Plugin Reference (p. 800)

Systems Manager Pre-Defined Documents

To help you get started quickly, Systems Manager provides pre-defined documents. To view these
documents in the AWS Systems Manager console, in the left navigation, choose Documents. After you
choose a document, choose View details to view information about the document you selected.

To view these documents in the Amazon EC2 console, expand Systems Manager Shared Resources,
and then choose Documents. After you choose a document, use the tabs in the lower pane to view
information about the document you selected.

You can also use the AWS CLI and Tools for Windows PowerShell commands to view a list of documents
and get descriptions about those documents.

To view information about documents using the AWS CLI, run the following commands:

aws ssm list-documents

aws ssm describe-document --name "document_name"

To view information about documents using the Tools for Windows PowerShell, run the following
commands:

Get-SSMDocumentList

777
 AWS Systems Manager User Guide
SSM Document Schemas and Features

Get-SSMDocumentDescription -Name "document_name"

SSM Document Schemas and Features

Systems Manager documents currently use the following schema versions.

• Documents of type Command can use schema version 1.2, 2.0, and 2.2. If you are currently using
schema 1.2 documents, we recommend that you create documents that use schema version 2.2.
• Documents of type Policy must use schema version 2.0 or later.
• Documents of type Automation must use schema version 0.3.
• You can create documents in JSON or YAML.

By using the latest schema version for Command and Policy documents, you can take advantage of the
following features.

Schema Version 2.2 Document Features

Feature Details

Document editing Documents can now be updated. With version 1.2,

any update to a document required that you save
it with a different name.

Automatic versioning Any update to a document creates a new version.

This is not a schema version, but a version of the
document.

Default version If you have multiple versions of a document, you

can specify which version is the default document.

Sequencing Plugins or steps in a document run in the order

that you specified.

Cross-platform support Cross-platform support enables you to specify

different operating systems for different plugins
within the same SSM document. Cross-platform
support uses the precondition parameter
within a step.

Note
You must keep SSM Agent on your instances updated with the latest version to use new Systems
Manager features and SSM document features. For more information, see Update SSM Agent by
using Run Command (p. 620).

The following table lists the differences between major schema versions.

Version 1.2 Version 2.2 (latest version) Details

runtimeConfig mainSteps In version 2.2, the

mainSteps section replaces
runtimeConfig. The
mainSteps section enables
Systems Manager to run steps in
sequence.

778
 AWS Systems Manager User Guide
SSM Document Syntax

Version 1.2 Version 2.2 (latest version) Details

properties inputs In version 2.2, the inputs

section replaces the
properties section. The
inputs section accepts
parameters for steps.

commands runCommand In version 2.2, the inputs

section takes the runCommand
parameter instead of the
commands parameter.

id action In version 2.2, Action replaces

ID. This is just a name change.

not applicable name In version 2.2, name is any user-

defined name for a step.

Using the Precondition Parameter

With schema version 2.2 or later, you can use the precondition parameter to specify the target
operating system for each plugin. The precondition parameter supports platformType and a value
of either Windows or Linux.

For documents that use schema version 2.2 or later, if precondition is not specified, each plugin is
either run or skipped based on the plugin’s compatibility with the operating system. For documents that
use schema 2.0 or earlier, incompatible plugins throw an error.

For example, in a schema version 2.2 document, if precondition is not specified and the
aws:runShellScript plugin is listed, then the step runs on Linux instances, but the system skips it
on Windows instances because the aws:runShellScript is not compatible with Windows instances.
However, for a schema version 2.0 document, if you specify the aws:runShellScript plugin, and
then run the document on a Windows instances, the execution fails. You can see an example of the
precondition parameter in an SSM document later in this section.

SSM Document Syntax

The syntax of your document is defined by the schema version used to create it. We recommended that
you use schema version 2.2 or later. Documents that use this schema version include the following top-
level elements. For information about the properties that you can specify in these elements, see Top-
level Elements (p. 801).

• schemaVersion: The schema version to use.

• Description: Information you provide to describe the purpose of the document.
• Parameters: The parameters the document accepts. For parameters that you reference often, we
recommend that you store those parameters in Systems Manager Parameter Store and then reference
them. You can reference String and StringList Systems Manager parameters in this section
of a document. You can't reference Secure String Systems Manager parameters in this section of a
document. For more information, see AWS Systems Manager Parameter Store (p. 825).
• mainSteps: An object that can include multiple steps (plugins). Steps include one or more actions, an
optional precondition, a unique name of the action, and inputs (parameters) for those actions. For a
list of supported plugins and plugin properties, see SSM Document Plugin Reference (p. 800).
Important
The name of the action can't include a space. If a name includes a space, you will receive an
InvalidDocumentContent error.

779
 AWS Systems Manager User Guide
SSM Document Syntax

Topics
• Schema Version 2.2 (p. 780)
• Schema Version 1.2 (p. 783)

Schema Version 2.2

The following example shows the top-level elements of a schema version 2.2 document in JSON.

{
"schemaVersion":"2.2",
"description":"A description of the document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"mainSteps":[
{
"action":"plugin 1",
"name":"A name for this action.",
"inputs":{
"name":"{{ input 1 }}",
"name":"{{ input 2 }}",
"name":"{{ input 3 }}",

}
}
]
}

YAML Schema Version 2.2 Example

You can use the following YAML document with Run Command to return the hostname of one or more
instances.

---
schemaVersion: '2.2'
description: Sample document
mainSteps:
- action: aws:runPowerShellScript
name: runPowerShellScript
inputs:
runCommand:
- hostname

Schema Version 2.2 Precondition Parameter Example

Schema version 2.2 provides cross-platform support. This means that within a single SSM document
you can specify different operating systems for different plugins. Cross-platform support uses the
precondition parameter within a step, as shown in the following example.

{
"schemaVersion":"2.2",
"description":"cross-platform sample",

780
 AWS Systems Manager User Guide
SSM Document Syntax

"mainSteps":[
{
"action":"aws:runPowerShellScript",
"name":"PatchWindows",
"precondition":{
"StringEquals":[
"platformType",
"Windows"
]
},
"inputs":{
"runCommand":[
"cmds"
]
}
},
{
"action":"aws:runShellScript",
"name":"PatchLinux",
"precondition":{
"StringEquals":[
"platformType",
"Linux"
]
},
"inputs":{
"runCommand":[
"cmds"
]
}
}
]
}

Schema Version Examples 2.2

You can use the following YAML document with State Manager to download and install the ClamAV
antivirus software. State Manager enforces a specific configuration, which means that each time the
State Manager association is run, the system checks to see if the ClamAV software is installed. If not,
State Manager reruns this document.

---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav

Schema Version 2.2 YAML Inventory Example

You can use the following YAML document with State Manager to collect inventory metadata about your
instances.

---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:

781
 AWS Systems Manager User Guide
SSM Document Syntax

applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"

Schema Version 2.2 AWS-ConfigureAWSPackage Example

The following example shows the AWS-ConfigureAWSPackage document. The mainSteps section
includes the aws:configurePackage plugin in the action step.
Note
On Linux operating systems, only the AmazonCloudWatchAgent and AWSSupport-
EC2Rescue packages are supported.

782
 AWS Systems Manager User Guide
SSM Document Syntax

"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS
package.
Available packages include the following: AWSPVDriver,
AwsEnaNetworkDriver, IntelSriovDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description": "(Required) Specify whether or not to install or uninstall the package.",
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9]
[-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-
zA-Z0-9\\-_]{0,39}$|^
[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"description": "(Optional) A specific version of the package to install or uninstall. If
installing,
the system installs the latest published version, by default. If uninstalling, the
system uninstalls
the currently installed version, by default. If no installed version is found, the
latest published
version is downloaded, and the uninstall action is run.",
"type": "String",
"default": "latest"
}
},
"mainSteps": [{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}]
}

Schema Version 1.2

The following example shows the top-level elements of a schema version 1.2 document.

{
"schemaVersion":"1.2",
"description":"A description of the Systems Manager document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},

783
 AWS Systems Manager User Guide
Creating Systems Manager Documents

"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}

Schema Version 1.2 Example

The following example shows the AWS-RunShellScript Systems Manager document. The runtimeConfig
section includes the aws:runShellScript plugin.

{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before
it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7]
[0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}

Creating Systems Manager Documents

If the Systems Manager public documents limit the actions you want to perform on your managed
instances, you can create your own documents. When creating a new document, we recommend that you
use schema version 2.2 or later.

Before You Begin

784
 AWS Systems Manager User Guide
Creating Systems Manager Documents

Before you create an SSM document, we recommend that you read about the different schemas,
features, and syntax available for SSM documents. For more information, see AWS Systems Manager
Documents (p. 775).
Note
If you plan to create an SSM document for State Manager, be aware of the following details:

• You can assign multiple documents to a target by creating different State Manager
associations that use different documents.
• If you create a document with conflicting plugins (e.g., domain join and remove from domain),
the last plugin run will be the final state. State Manager does not validate the logical
sequence or rationality of the commands or plugins in your document.
• When processing documents, instance associations are applied first, and next tagged group
associations are applied. If an instance is part of multiple tagged groups, then the documents
that are part of the tagged group will not be run in any particular order. If an instance is
directly targeted through multiple documents by its instance ID, there is no particular order of
execution.
• If you change the default version of an SSM Policy document for State Manager, any
association that uses the document will start using the new default version the next time
Systems Manager applies the association to the instance.
• If you create an association using an SSM document that was shared with you, and then the
owner stops sharing the document with you, your associations no longer have access to that
document. However, if the owner shares the same SSM document with you again later, your
associations automatically remap to it.

If you create an SSM document for State Manager, you must associate the document with
your managed instances after you add it to the system. For more information, see Create an
Association (p. 647).

Topics
• Copy a Document (p. 785)
• Add a Systems Manager Document (Console) (p. 786)
• Create an SSM Document (AWS CLI) (p. 786)
• Create an SSM Document (Tools for Windows PowerShell) (p. 786)

Copy a Document
When you create a document, you specify the contents of the document in JSON or YAML. The easiest
way to get started creating SSM documents is to copy an existing sample from one of the Systems
Manager public documents. The following example shows you how to copy a JSON sample.

To copy a Systems Manager document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose a document.
4. Choose View details.
5. Choose the Content tab.

785
 AWS Systems Manager User Guide
Creating Systems Manager Documents

6. Copy the JSON to a text editor and specify the details for your custom document.
7. Save the file with a .json file extension.

After you author the content of the document, you can add it to Systems Manager using any one of the
following procedures.

• Add a Systems Manager Document (Console) (p. 786)

• Create an SSM Document (AWS CLI) (p. 786)
• Create an SSM Document (Tools for Windows PowerShell) (p. 786)

Add a Systems Manager Document (Console)

Add a Systems Manager Document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. Choose Create document.
4. Type a descriptive name for the document
5. In the Document type list, choose the type of document you want to create.
6. Delete the brackets in the Content field, and then paste the document you created earlier.
7. Choose Create document to save the document.

Create an SSM Document (AWS CLI)

1. Copy and customize an existing document, as described in Copy a Document (p. 785).
2. Add the document using the AWS CLI.

aws ssm create-document --content file://path to your file\your file --name "document
name" --document-type "Command"

Windows example

aws ssm create-document --content file://c:\temp\PowershellScript.json --name

"PowerShellScript" --document-type "Command"

Linux example

aws ssm create-document --content file:///home/ec2-user/RunShellScript.json --name

"RunShellScript" --document-type "Command"

Create an SSM Document (Tools for Windows PowerShell)

1. Copy and customize an existing document, as described in Copy a Document (p. 785).
2. Add the document using the AWS Tools for Windows PowerShell.

786
 AWS Systems Manager User Guide
Tagging Documents

$json = Get-Content C:\your file | Out-String

New-SSMDocument -DocumentType Command -Name document name -Content $json

Tagging Systems Manager Documents

You can use the Systems Manager console, the AWS CLI, the AWS Tools for Windows, or the
AddTagsToResource API to add tags to Systems Manager resources, including documents, managed
instances, maintenance windows, Parameter Store parameters, and patch baselines.

Tagging is useful when you have many resources of the same type — you can quickly identify a specific
resource based on the tags you've assigned to it. Each tag consists of a key and an optional value, both of
which you define.

For example, you can tag documents for specific environments, departments, users, groups, or periods.
After you tag a document, you can restrict access to it by creating an IAM policy that specifies the tags
that a user can access. For more information about restricting access to documents by using tags, see
Controlling Access to Documents Using Tags (p. 788).

Topics
• Tag a Document (AWS CLI) (p. 787)
• Tag a Document (AWS Tools for Windows) (p. 788)
• Tag a Document (Console) (p. 788)
• Controlling Access to Documents Using Tags (p. 788)

Tag a Document (AWS CLI)

1. At a terminal (Linux, macOS, or Unix) or command prompt (Windows), run the list-documents
command to list the documents that you can tag.

aws ssm list-documents

Note the name of a document that you want to tag.

2. Run the following command to tag a document.

aws ssm add-tags-to-resource --resource-type "Document" --resource-id "document-name"

--tags "Key=key,Value=value"

document-name the name of the Systems Manager document you want to tag.

key is the name of a custom key you supply. For example, region or quarter.

value is the custom content for the value you want to supply for that key. For example, west or
Q318.

If successful, the command has no output.

3. Run the following command to verify the document tags.

aws ssm list-tags-for-resource --resource-type "Document" --resource-id "document-name"

787
 AWS Systems Manager User Guide
Tagging Documents

Tag a Document (AWS Tools for Windows)

1. Open AWS Tools for Windows PowerShell and run the following command to list documents that
you can tag:

Get-SSMDocumentList

2. Run the following commands one at a time to tag a document:

$tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag

$tag1.Key = "key"
$tag1.Value = "value"
Add-SSMResourceTag -ResourceType "Document" -ResourceId "document-name" -Tag $tag1

document-name the name of the Systems Manager document you want to tag.

key is the name of a custom key you supply. For example, region or quarter.

value is the custom content for the value you want to supply for that key. For example, west or
Q318.

If successful, the command has no output.

3. Run the following command to verify the document tags:

Get-SSMResourceTag -ResourceType "Document" -ResourceId "document-name"

Tag a Document (Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
2. In the left navigation, choose Documents.
3. Choose the name of an existing document, and then choose the Tags tab.
4. In the first box, enter a key for the tag, such as Region.
5. In the second box, enter a value for the tag, such as West.
6. Choose Save.

Controlling Access to Documents Using Tags

After you tag a document, you can restrict access to it by creating an IAM policy that specifies the
tags the user can access. When a user attempts to use a document, the system checks the IAM policy
and the tags specified for the document. If the user does not have access to the tags assigned to the
document, the user receives an access denied error. Use the following procedure to create an IAM policy
that restricts access to documents by using tags.

Before You Begin

Create and tag documents. For more information, see Tagging Systems Manager Documents (p. 787).

To restrict a user's access to documents by using tags

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Policies, and then choose Create policy.

788
 AWS Systems Manager User Guide
Tagging Documents

3. Choose the JSON tab.

4. Copy the following sample policy and paste it into the text field, replacing the sample text. Replace
tag_key and tag_value with the key-value pair for your tag.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:GetDocument"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key":[
"tag_value"
]
}
}
}
]
}

You can specify multiple keys in the policy by using the following Condition format. Specifying
multiple keys creates an AND relationship for the keys.

"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}

You can specify multiple values in the policy by using the following Condition format. ForAnyValue
establishes an OR relationship for the values. You can also specify ForAllValues to establish an AND
relationship.

"Condition":{
"ForAnyValue:StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1",
"tag_value2"
]
}
}

5. Choose Review policy.

6. In the Name field, specify a name that identifies this as a user policy for tagged documents.
7. Enter a description.
8. Verify details of the policy in the Summary section.
9. Choose Create policy.
10. Assign the policy to IAM users or groups. For more information, see Changing Permissions for an IAM
User and Attaching a Policy to an IAM Group in the IAM User Guide.

789
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

After you attach the policy to the IAM user or group account, if a user tries to use a document and the
user's policy does not allow the user to access a tag for the document (call the GetDocument API), the
system returns an error. The error is similar to the following:

"User: user_name is not authorized to perform: ssm:GetDocument on resource: document-name with

the following command."

If a document has multiple tags, the user will still receive the Access Denied error if the user does not
have permission to access any one of those tags.

Sharing Systems Manager Documents

You can share Systems Manager documents privately or publicly. To privately share a document, you
modify the document permissions and allow specific individuals to access it according to their Amazon
Web Services (AWS) ID. To publicly share a Systems Manager document, you modify the document
permissions and specify All.
Warning
Use shared Systems Manager documents only from trusted sources. When using any shared
document, carefully review the contents of the document before using it so that you understand
how it will change the configuration of your instance. For more information about shared
document best practices, see Guidelines for Sharing and Using Shared Systems Manager
Documents (p. 790).

Limitations

As you begin working with Systems Manager documents, be aware of the following limitations.

• Only the owner can share a document.

• You must stop sharing a document before you can delete it. For more information, see Modify
Permissions for a Shared Document (p. 793).
• You can share a document with a maximum of 1000 AWS accounts. You can request an increase to
this limit in the AWS Support Center. For Limit type, choose EC2 Systems Manager and describe your
reason for the request.
• You can publicly share a maximum of five Systems Manager documents. You can request an increase to
this limit in the AWS Support Center. For Limit type, choose EC2 Systems Manager and describe your
reason for the request.

For more information about Systems Manager limits, see AWS Systems Manager Limits.

Contents
• Guidelines for Sharing and Using Shared Systems Manager Documents (p. 790)
• Share a Systems Manager Document (p. 791)
• Modify Permissions for a Shared Document (p. 793)
• Use a Shared Systems Manager Document (p. 794)

Guidelines for Sharing and Using Shared Systems Manager

Documents
Review the following guidelines before you share or use a shared document.

Remove Sensitive Information

Review your Systems Manager document carefully and remove any sensitive information. For
example, verify that the document does not include your AWS credentials. If you share a document

790
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

with specific individuals, those users can view the information in the document. If you share a
document publicly, anyone can view the information in the document.
Limit Run Command Actions Using an IAM User Trust Policy

Create a restrictive AWS Identity and Access Management (IAM) user policy for users who will have
access to the document. The IAM policy determines which Systems Manager documents a user
can see in either the Amazon EC2 console or by calling ListDocuments using the AWS CLI or
AWS Tools for Windows PowerShell. The policy also limits the actions the user can perform with
Systems Manager document. You can create a restrictive policy so that a user can only use specific
documents. For more information, see Create Non-Admin IAM Users and Groups for Systems
Manager (p. 25) and Customer Managed Policy Examples (p. 916).
Review the Contents of a Shared Document Before Using It

Review the contents of every document that is shared with you, especially public documents, to
understand the commands that will be run on your instances. A document could intentionally or
unintentionally have negative repercussions after it is run. If the document references an external
network, review the external source before you use the document.
Send Commands Using the Document Hash

When you share a document, the system creates a Sha-256 hash and assigns it to the document. The
system also saves a snapshot of the document content. When you send a command using a shared
document, you can specify the hash in your command to ensure that the following conditions are
true:
• You are running a command from the correct Systems Manager document
• The content of the document has not changed since it was shared with you.

If the hash does not match the specified document or if the content of the shared document has
changed, the command returns an InvalidDocument exception. Note: The hash cannot verify
document content from external locations.

Share a Systems Manager Document

You can share Systems Manager document by using the Amazon EC2 console, the AWS Systems Manager
console, or by programmatically calling the ModifyDocumentPermission API operation using the AWS
CLI, AWS Tools for Windows PowerShell, or the AWS SDK. Before you share a document, get the AWS
account IDs of the people with whom you want to share. You will specify these account IDs when you
share the document.

Topics
• Share a Document (Console) (p. 791)
• Share a Document (AWS CLI) (p. 792)
• Share a Document (AWS Tools for Windows PowerShell) (p. 793)

Share a Document (Console)

Share a document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.

791
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

3. In the documents list, choose the document you want to share, and then choose View details. On
the Permissions tab, verify that you are the document owner. Only a document owner can share a
document.
4. Choose Edit.
5. To share the command publicly, choose Public and then choose Save. To share the command
privately, choose Private, enter the AWS account ID, choose Add permission, and then choose Save.

Share a Document (AWS CLI)

The following procedure requires that you specify a region for your CLI session. Run Command is
currently available in the following Systems Manager regions.

1. Open the AWS CLI on your local computer and run the following command to specify your
credentials.

aws config

AWS Access Key ID: [your key]

AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
2. Use the following command to list all of the Systems Manager documents that are available for you.
The list includes documents that you created and documents that were shared with you.

aws ssm list-documents --document-filter-list key=Owner,value=all

3. Use the following command to get a specific document.

aws ssm get-document --name document name

4. Use the following command to get a description of the document.

aws ssm describe-document --name document name

5. Use the following command to view the permissions for the document.

aws ssm describe-document-permission --name document name --permission-type Share

6. Use the following command to modify the permissions for the document and share it. You must be
the owner of the document to edit the permissions. This command privately shares the document
with a specific individual, based on that person's AWS account ID.

aws ssm modify-document-permission --name document name --permission-type Share --

account-ids-to-add AWS account ID

Use the following command to share a document publicly.

aws ssm modify-document-permission --name document name --permission-type Share --

account-ids-to-add 'all'

792
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

Share a Document (AWS Tools for Windows PowerShell)

The following procedure requires that you specify a region for your PowerShell session. Run Command is
currently available in the following Systems Manager regions.

1. Open AWS Tools for Windows PowerShell on your local computer and run the following command
to specify your credentials.

Set-AWSCredentials –AccessKey your key –SecretKey your key

2. Use the following command to set the region for your PowerShell session. The example uses the us-
west-2 region.

Set-DefaultAWSRegion -Region us-west-2

3. Use the following command to list all of the Systems Manager documents available for you. The list
includes documents that you created and documents that were shared with you.

Get-SSMDocumentList -DocumentFilterList (@{"key"="Owner";"value"="All"})

4. Use the following command to get a specific document.

Get-SSMDocument –Name document name

5. Use the following command to get a description of the document.

Get-SSMDocumentDescription –Name document name

6. Use the following command to view the permissions of the document.

Get-SSMDocumentPermission –Name document name -PermissionType Share

7. Use the following command to modify the permissions for the document and share it. You must be
the owner of the document to edit the permissions. This command privately shares the document
with a specific individual, based on that person's AWS account ID.

Edit-SSMDocumentPermission –Name document name -PermissionType Share -

AccountIdsToAdd AWS account ID

Use the following command to share a document publicly.

Edit-SSMDocumentPermission -Name document name -AccountIdsToAdd ('all') -PermissionType

Share

Modify Permissions for a Shared Document

If you share a command, users can view and use that command until you either remove access to the
Systems Manager document or delete the Systems Manager document. However, you cannot delete a
document as long as it is shared. You must stop sharing it first and then delete it.

Topics
• Stop Sharing a Document (Console) (p. 794)
• Stop Sharing a Document (AWS CLI) (p. 794)
• Stop Sharing a Document (AWS Tools for Windows PowerShell) (p. 794)

793
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

Stop Sharing a Document (Console)

Stop sharing a document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Documents.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Documents in the navigation pane.
3. In the documents list, choose the document you want to stop sharing, and then choose View details.
On the Permissions tab, verify that you are the document owner. Only a document owner can stop
sharing a document.
4. Choose Edit.
5. Choose X to delete the AWS account ID that should no longer have access to the command, and then
choose Save.

Stop Sharing a Document (AWS CLI)

Open the AWS CLI on your local computer and run the following command to stop sharing a command.

aws ssm modify-document-permission --name document name --permission-type Share --account-

ids-to-remove 'AWS account ID'

Stop Sharing a Document (AWS Tools for Windows PowerShell)

Open AWS Tools for Windows PowerShell on your local computer and run the following command to
stop sharing a command.

Edit-SSMDocumentPermission -Name document name –AccountIdsToRemove AWS account ID -

PermissionType Share

Use a Shared Systems Manager Document

When you share a Systems Manager document, the system generates an Amazon Resource Name
(ARN) and assigns it to the command. If you select and run a shared document from the Amazon EC2
console, you do not see the ARN. However, if you want to run a shared Systems Manager document
from a command line application, you must specify a full ARN. You are shown the full ARN for a Systems
Manager document when you run the command to list documents.
Note
You are not required to specify ARNs for AWS public documents (documents that begin with
AWS-*) or commands that you own.

Topics
• Use a Shared Systems Manager Document (AWS CLI) (p. 794)
• Use a Shared Systems Manager Document (AWS Tools for Windows PowerShell) (p. 795)

Use a Shared Systems Manager Document (AWS CLI)

To list all public Systems Manager documents

794
 AWS Systems Manager User Guide
Sharing Systems Manager Documents

aws ssm list-documents --document-filter-list key=Owner,value=Public

To list private Systems Manager documents that have been shared with you

aws ssm list-documents --document-filter-list key=Owner,value=Private

To list all Systems Manager documents available to you

aws ssm list-documents --document-filter-list key=Owner,value=All

Run a command from a shared Systems Manager document using a full ARN

aws ssm send-command --document-name FullARN/name

For example:

aws ssm send-command --document-name arn:aws:ssm:us-east-2:12345678912:document/

highAvailabilityServerSetup --instance-ids i-12121212

Use a Shared Systems Manager Document (AWS Tools for Windows PowerShell)
To list all public Systems Manager documents

Get-SSMDocumentList -DocumentFilterList @(New-Object

Amazon.SimpleSystemsManagement.Model.DocumentFilter("Owner", "Public"))

To list private Systems Manager documents that have been shared with you

Get-SSMDocumentList -DocumentFilterList @(New-Object

Amazon.SimpleSystemsManagement.Model.DocumentFilter("Owner", "Private"))

To get information about a Systems Manager document that has been shared with you

Get-SSMDocument –Name FullARN/name

For example:

Get-SSMDocument –Name arn:aws:ssm:us-east-2:12345678912:document/

highAvailabilityServerSetup

To get a description of a Systems Manager document that has been shared with you

Get-SSMDocumentDescription –Name FullARN/name

For example:

Get-SSMDocumentDescription –Name arn:aws:ssm:us-east-2:12345678912:document/

highAvailabilityServerSetup

795
 AWS Systems Manager User Guide
Creating Composite Documents

To run a command from a shared Systems Manager document using a full ARN

Send-SSMCommand –DocumentName FullARN/name –InstanceId IDs

For example:

Send-SSMCommand –DocumentName arn:aws:ssm:us-east-2:555450671542:document/

highAvailabilityServerSetup –InstanceId @{"i-273d4e9e"}

Creating Composite Documents

A composite SSM document is a custom document that performs a series of actions by running one or
more secondary SSM documents. Composite documents promote infrastructure as code by enabling
you to create a standard set of SSM documents for common tasks such as boot-strapping software or
domain-joining instances. You can then share these documents across AWS accounts to reduce SSM
document maintenance and ensure consistency.

For example, you can create a composite document that performs the following actions:

1. Updates SSM Agent to the latest version.

2. Installs all whitelisted patches.
3. Installs antivirus software.
4. Downloads scripts from GitHub and runs them.

In this example, your custom SSM document includes the following plugins to perform these actions:

1. The aws:runDocument plugin to run the AWS-UpdateSSMAgent document, which updates SSM
Agent to the latest version.
2. The aws:runDocument plugin to run the AWS-ApplyPatchBaseline document, which installs all
whitelisted patches.
3. The aws:runDocument plugin to run the AWS-InstallApplication document, which installs the
antivirus software.
4. The aws:downloadContent plugin to download scripts from GitHub and run them.

Composite and secondary documents can be stored in Systems Manager, GitHub (public and private
repositories), or Amazon S3. Composite documents and secondary documents can be created in JSON or
YAML.
Note
Composite documents can only run to a maximum depth of three documents. This means that
a composite document can call a child document; and that child document can call one last
document.

Create a Composite Document

To create a composite document, add the aws:runDocument (p. 818) plugin in a custom SSM document
and specify the required inputs. The following is an example of a composite document that performs the
following actions:

1. Runs the aws:downloadContent (p. 813) plugin to download an SSM document from a
GitHub public repository to a local directory called bootstrap. The SSM document is called
StateManagerBootstrap.yml (a YAML document).

796
 AWS Systems Manager User Guide
Running Documents from Remote Locations

2. Runs the aws:runDocument plugin to run the StateManagerBootstrap.yml document. No parameters

are specified.
3. Runs the aws:runDocument plugin to run the AWS-ConfigureDocker pre-defined SSM document. The
specified parameters install Docker on the instance.

{
"schemaVersion": "2.2",
"description": "My composite document for bootstrapping software and installing Docker.",
"parameters": {
},
"mainSteps": [
{
"action": "aws:downloadContent",
"name": "downloadContent",
"inputs": {
"sourceType": "GitHub",
"sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", \"path\":
\"documents/bootstrap/StateManagerBootstrap.yml\"}",
"destinationPath": "bootstrap"
}
},
{
"action": "aws:runDocument",
"name": "runDocument",
"inputs": {
"documentType": "LocalPath",
"documentPath": "bootstrap",
"documentParameters": "{}"
}
},
{
"action": "aws:runDocument",
"name": "configureDocker",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "AWS-ConfigureDocker",
"documentParameters": "{\"action\":\"Install\"}"
}
}
]
}

Related Topics
• For information about rebooting servers and instances when using Run Command to call scripts, see
Rebooting Managed Instance from Scripts (p. 625).
• For more information about creating an SSM document, see Creating Systems Manager
Documents (p. 784).
• For more information about the plugins you can add to a custom SSM document, see SSM Document
Plugin Reference (p. 800).
• If you simply want to run a document from a remote location (without creating a composite
document), see Running Documents from Remote Locations (p. 797).

Running Documents from Remote Locations

You can run SSM documents from remote locations by using the AWS-RunDocument pre-defined SSM
document. This document currently supports the following remote locations:

797
 AWS Systems Manager User Guide
Running Documents from Remote Locations

• GitHub repositories (public and private)

• Amazon S3
• Documents saved in Systems Manager

The following procedure describes how to run remote SSM documents by using the console. This
procedure shows how to run the remote document by using Run Command, but you can also run remote
documents by using State Manager or Automation.

Before You Begin

Before you run a remote document, you must complete the following tasks.

• Create an SSM document and save it in a remote location. For more information, see Creating Systems
Manager Documents (p. 784)
• If you plan to run a remote document that is stored in a private GitHub repository, then you must
create a Systems Manager SecureString parameter for your GitHub security access token. You
can't access a remote document in a private GitHub repository by manually passing your token
over SSH. The access token must be passed as a Systems Manager SecureString parameter. For
more information about creating a SecureString parameter, see Creating Systems Manager
Parameters (p. 847).

Run a Remote Document (Console)

To run a remote document

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Document list, choose AWS-RunDocument.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.

798
 AWS Systems Manager User Guide
Running Documents from Remote Locations

7. In the Source Type list, choose an option.

• If you choose GitHub, specify Source Info information in the following format:

{"owner":"owner_name", "repository": "repository_name", "path": "path_to_document",

"tokenInfo":"{{ssm-secure:SecureString_parameter_name}}" }

For example:

{"owner":"TestUser1", "repository": "SSMTestDocsRepo", "path": "SSMDocs/

mySSMdoc.yml", "tokenInfo":"{{ssm-secure:myAccessTokenParam}}" }

• If you choose S3, specify Source Info information in the following format:

{"path":"URL_to_document_in_S3"}

For example:

{"path":"https://s3.amazonaws.com/aws-executecommand-test/scripts/ruby/
mySSMdoc.json"}

• If you choose SSMDocument, specify Source Info information in the following format:

{"name": "document_name"}

For example:

{"name": "mySSMdoc"}

8. In the Document Parameters field, type parameters for the remote SSM document. For example, if
you run the AWS-RunPowerShell document, you could specify:

{"commands": ["date", "echo \"Hello World\""]}

If you run the AWS-ConfigureAWSPack document, you could specify:

{
"action":"Install",
"name":"AWSPVDriver"
}

9. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
10. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.

799
 AWS Systems Manager User Guide
SSM Document Plugin Reference

• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
11. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
12. In the SNS Notifications section, if you want notifications sent about the status of the command
execution, select the Enable SNS notifications check box.

For more information about configuring Amazon SNS notifications for Run Command, see
Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893).
13. Choose Run.

Note
For information about rebooting servers and instances when using Run Command to call scripts,
see Rebooting Managed Instance from Scripts (p. 625).

SSM Document Plugin Reference

This reference describes the actions, or plugins, that you can specify in an AWS Systems Manager (SSM)
document. This reference does not include information about AWS Systems Manager Automation
document plugins. For information about Automation document plugins, see Systems Manager
Automation Actions Reference (p. 241).

Systems Manager determines the actions to perform on a managed instance by reading the contents
of a Systems Manager document. Each document includes a code-execution section. Depending on
the schema version of your document, this code-execution section can include one or more plugins
or steps. For the purpose of this Help topic, plugins and steps are called plugins. This section includes
information about each of the Systems Manager plugins. For more information about documents,
including information about creating documents and the differences between schema versions, see AWS
Systems Manager Documents (p. 775).
Note
Some of the plugins described here run only on either Windows Server instances or Linux
instances. Platform dependencies are noted for each plugin.

Contents
• Top-level Elements (p. 801)
• type Examples (p. 802)
• aws:applications (p. 803)
• aws:cloudWatch (p. 804)
• aws:configureDocker (p. 810)
• aws:configurePackage (p. 811)
• aws:domainJoin (p. 812)
• aws:downloadContent (p. 813)
• aws:psModule (p. 815)
• aws:refreshAssociation (p. 816)

800
 AWS Systems Manager User Guide
SSM Document Plugin Reference

• aws:runDockerAction (p. 816)

• aws:runDocument (p. 818)
• aws:runPowerShellScript (p. 819)
• aws:runShellScript (p. 820)
• aws:softwareInventory (p. 822)
• aws:updateAgent (p. 823)
• aws:updateSSMAgent (p. 824)

Top-level Elements
The top-level elements are common for all Systems Manager documents. Top-level elements provide the
structure of the Systems Manager document.

Properties
schemaVersion

The version of the schema.

Type: Version

Required: Yes
description

A description of the configuration.

Type: String

Required: No
parameters

parameters is a structure that contains one or more parameters to run when processing the
document. You can specify parameters at runtime, in a document, or by using Systems Manager
Parameter Store. For more information, see AWS Systems Manager Parameter Store (p. 825).

Type: Structure

The parameters structure accepts the following fields and values:

• type: (Required) Allowed values include the following: String, StringList, Boolean,
Integer, MapList, and StringMap. To view examples of each type, see type
Examples (p. 802) in the next section.
• description: (Optional) A description of the parameter.
• default: (Optional) The default value of the parameter or a reference to a parameter in
Parameter Store.
• allowedValues: (Optional) Allowed values for the parameter.
• allowedPattern: (Optional) The regular expression the parameter must match.
• displayType: (Optional) Used to display either a textfield or a textarea in the AWS console.
textfield is a single-line text box. textarea is a multi-line text area.
• minItems: (Optional) The minimum number of items allowed.
• maxItems: (Optional) The maximum number of items allowed.
• minChars: (Optional) The minimum number of parameter characters allowed.

801
 AWS Systems Manager User Guide
SSM Document Plugin Reference

• maxChars: (Optional) The maximum number of parameter characters allowed.

runtimeConfig

(Schema version 1.2 only) The configuration for the instance as applied by one or more Systems
Manager plugins. Plugins are not guaranteed to run in sequence.

Type: Dictionary<string,PluginConfiguration>

Required: No
mainSteps

(Schema version 0.3, 2.0, and 2.2 only) The configuration for the instance as applied by one or more
Systems Manager plugins. Plugins are organized as actions within steps. Steps run in sequential
order as listed in the document.

Type: Dictionary<string,PluginConfiguration>

Required: No

type Examples
This section includes examples of each parameter type.

type Description Example Example use case

String A sequence of zero "i-1234567890abcdef0"

"InstanceId":{
or more Unicode "type":"String",
characters wrapped "description":"(Required)
in double quotes. Use The target EC2
backslashes to escape. instance ID."
}

StringList A list of String items ["cd ~", "pwd"]

"commands":{
separated by commas "type":"StringList",
"description":"(Required)
Specify a shell
script or a command
to run.",
"minItems":1,
"displayType":"textarea"
},

Boolean Accepts only true or true

"canRun": {
false. Does not accept "type": "Boolean",
"true" or 0. "description": "",
"default": true,
}

Integer Integral numbers. 39 or -5

"timeout": {
Doesn't accept decimal "type": "Integer",
numbers, for example "description": "The
3.14159, or numbers type of action to
wrapped in double perform.",
quotes, for example "3". "default": 100
}

802
 AWS Systems Manager User Guide
SSM Document Plugin Reference

type Description Example Example use case

StringMap A mapping of keys

{ "notificationConfig" :
to values. A key can "NotificationType":"Command",
{
only be a string. For "NotificationEvents": "type" :
example: { "type": [ "Failed" ], "StringMap",
"object" } "NotificationArn":"$dependency.topicArn"
"description" :
} "The configuration
for events to be
notified about",
"default" : {

"NotificationType" :
"Command",

"NotificationEvents" :
["Failed"],

"NotificationArn" :
"$dependency.topicArn"
},
"maxChars" :
150
}

MapList A list of StringMap

[ "blockDeviceMappings" :
items. { {
"DeviceName" : "type" : "MapList",
"/dev/sda1", "description" :
"Ebs" : "The mappings for
{ "VolumeSize" : the create image
"50" } inputs",
}, "default" :
{ [{"DeviceName":"/
"DeviceName" : dev/sda1","Ebs":
"/dev/sdm", {"VolumeSize":"50"}},
"Ebs" : {"DeviceName":"/
{ "VolumeSize" : dev/sdm","Ebs":
"100" } { "VolumeSize":"100"}}],
} "maxItems": 2
] }

aws:applications
Install, repair, or uninstall applications on an EC2 instance. This plugin only runs on Microsoft Windows
Server operating systems. For more information, see AWS Systems Manager Documents (p. 775).

Syntax

"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}

803
 AWS Systems Manager User Guide
SSM Document Plugin Reference

]
}

Properties
action

The action to take.

Type: Enum

Valid values: Install | Repair | Uninstall

Required: Yes
parameters

The parameters for the installer.

Type: String

Required: No
source

The URL of the .msi file for the application.

Type: String

Required: Yes
sourceHash

The SHA256 hash of the .msi file.

Type: String

Required: No

aws:cloudWatch
Export data from Windows Server to Amazon CloudWatch or Amazon CloudWatch Logs and monitor the
data using CloudWatch metrics. This plugin only runs on Microsoft Windows Server operating systems.
For more information about configuring CloudWatch integration with Amazon EC2, see Sending Logs,
Events, and Performance Counters to Amazon CloudWatch. For more information about documents, see
AWS Systems Manager Documents (p. 775).
Important
The unified CloudWatch agent has replaced SSM Agent as the tool for sending log data to
Amazon CloudWatch Logs. Support for using SSM Agent to send log data will be deprecated in
the near future. We recommend using only the unified CloudWatch agent for your log collection
processes. For more information, see the following topics:

• Sending Logs to CloudWatch Logs (CloudWatch agent) (p. 884)

• Migrate Windows Server Instance Log Collection to the CloudWatch agent (p. 884)
• Collect Metrics from Amazon Elastic Compute Cloud Instances and On-Premises Servers with
the CloudWatch agent in the Amazon CloudWatch User Guide

You can export and monitor the following data types:

804
 AWS Systems Manager User Guide
SSM Document Plugin Reference

ApplicationEventLog

Sends application event log data to CloudWatch Logs.

CustomLogs

Sends any text-based log file to CloudWatch Logs. The CloudWatch plugin creates a fingerprint for
log files. The system then associates a data offset with each fingerprint. The plugin uploads files
when there are changes, records the offset, and associates the offset with a fingerprint. This method
is used to avoid a situation where a user enables the plugin, associates the service with a directory
that contains a large number of files, and the system uploads all of the files.
Warning
Be aware that if your application truncates or attempts to clean logs during polling, any
logs specified for LogDirectoryPath can lose entries. If, for example, you want to limit
log file size, create a new log file when that limit is reached, and then continue writing data
to the new file.
ETW

Sends Event Tracing for Windows (ETW) data to CloudWatch Logs. Microsoft Windows Server 2003 is
not supported.
IIS

Sends IIS log data to CloudWatch Logs.

PerformanceCounter

Sends Windows performance counters to CloudWatch. You can select different categories to
upload to CloudWatch as metrics. For each performance counter that you want to upload,
create a PerformanceCounter section with a unique ID (for example, "PerformanceCounter2",
"PerformanceCounter3", and so on) and configure its properties.
Note
If the SSM Agent or the CloudWatch plugin is stopped, performance counter data is not
logged in CloudWatch This behavior is different than custom logs or Windows Event logs.
Custom logs and Windows Event logs preserve performance counter data and upload it to
CloudWatch after SSM Agent or the CloudWatch plugin is available.
SecurityEventLog

Sends security event log data to CloudWatch Logs.

SystemEventLog

Sends system event log data to CloudWatch Logs.

You can define the following destinations for the data:

CloudWatch

The destination where your performance counter metric data is sent. You can add more sections with
unique IDs (for example, "CloudWatch2", CloudWatch3", and so on), and specify a different Region
for each new ID to send the same data to different locations.
CloudWatchLogs

The destination where your log data is sent. You can add more sections with unique IDs (for example,
"CloudWatchLogs2", CloudWatchLogs3", and so on), and specify a different Region for each new ID
to send the same data to different locations.

Syntax
"runtimeConfig":{

805
 AWS Systems Manager User Guide
SSM Document Plugin Reference

"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}

Settings and Properties

AccessKey

Your access key ID. This property is required unless you launched your instance using an IAM role.
This property cannot be used with SSM.

Type: String

Required: No
CategoryName

The performance counter category from Performance Monitor.

Type: String

Required: Yes
CounterName

The name of the performance counter from Performance Monitor.

Type: String

Required: Yes
CultureName

The locale where the timestamp is logged. If CultureName is blank, it defaults to the same locale
currently used by your Windows Server instance.

Type: String

Valid values: For a list of supported values, see National Language Support (NLS) on the Microsoft
website. Note that the div, div-MV, hu, and hu-HU values are not supported.

Required: No
DimensionName

A dimension for your Amazon CloudWatch metric. If you specify DimensionName, you must specify
DimensionValue. These parameters provide another view when listing metrics. You can use
the same dimension for multiple metrics so that you can view all metrics belonging to a specific
dimension.

Type: String

Required: No
DimensionValue

A dimension value for your Amazon CloudWatch metric.

Type: String

Required: No

806
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Encoding

The file encoding to use (for example, UTF-8). Use the encoding name, not the display name.

Type: String

Valid values: For a list of supported values, see Encoding Class in the MSDN Library.

Required: Yes
Filter

The prefix of log names. Leave this parameter blank to monitor all files.

Type: String

Valid values: For a list of supported values, see the FileSystemWatcherFilter Property in the MSDN
Library.

Required: No
Flows

Each data type to upload, along with the destination for the data (CloudWatch or
CloudWatch Logs). For example, to send a performance counter defined under "Id":
"PerformanceCounter" to the CloudWatch destination defined under "Id": "CloudWatch",
enter "PerformanceCounter,CloudWatch". Similarly, to send the custom log, ETW log,
and system log to the CloudWatch Logs destination defined under "Id": "ETW", enter
"(ETW),CloudWatchLogs". In addition, you can send the same performance counter or log file to
more than one destination. For example, to send the application log to two different destinations
that you defined under "Id": "CloudWatchLogs" and "Id": "CloudWatchLogs2", enter
"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)".

Type: String

Valid values (source): ApplicationEventLog | CustomLogs | ETW | PerformanceCounter |

SystemEventLog | SecurityEventLog

Valid values (destination): CloudWatch | CloudWatchLogs | CloudWatchn | CloudWatchLogsn

Required: Yes
FullName

The full name of the component.

Type: String

Required: Yes
Id

Identifies the data source or destination. This identifier must be unique within the configuration file.

Type: String

Required: Yes
InstanceName

The name of the performance counter instance. Do not use an asterisk (*) to indicate all instances
because each performance counter component only supports one metric. You can, however use
_Total.

Type: String

807
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Required: Yes
Levels

The types of messages to send to Amazon CloudWatch.

Type: String

Valid values:
• 1 - Only error messages uploaded.
• 2 - Only warning messages uploaded.
• 4 - Only information messages uploaded.

Note that you can add values together to include more than one type of message. For example, 3
means that error messages (1) and warning messages (2) are included. A value of 7 means that error
messages (1), warning messages (2), and informational messages (4) are included.

Required: Yes
Note
Windows Security Logs should set Levels to 7.
LineCount

The number of lines in the header to identify the log file. For example, IIS log files have virtually
identical headers. You could enter 3, which would read the first three lines of the log file's header to
identify it. In IIS log files, the third line is the date and time stamp, which is different between log
files.

Type: Integer

Required: No
LogDirectoryPath

For CustomLogs, the path where logs are stored on your Amazon EC2 instance. For IIS logs, the
folder where IIS logs are stored for an individual site (for example, C:\\inetpub\\logs\\LogFiles\
\W3SVCn). For IIS logs, only W3C log format is supported. IIS, NCSA, and Custom formats are not
supported.

Type: String

Required: Yes
LogGroup

The name for your log group. This name is displayed on the Log Groups screen in the CloudWatch
console.

Type: String

Required: Yes
LogName

The name of the log file.

1. To find the name of the log, in Event Viewer, in the navigation pane, click Applications and
Services Logs.
2. In the list of logs, right-click the log you want to upload (for example,
Microsoft>Windows>Backup>Operational), and then click Create Custom View.
3. In the Create Custom View dialog box, click the XML tab. The LogName is in the <Select Path=>
tag (for example, Microsoft-Windows-Backup). Copy this text into the LogName parameter.

808
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Type: String

Valid values: Application | Security | System | Microsoft-Windows-WinINet/Analytic

Required: Yes
LogStream

The destination log stream. If you use {instance_id}, the default, the instance ID of this instance is
used as the log stream name.

Type: String

Valid values: {instance_id} | {hostname} | {ip_address} <log_stream_name>

If you enter a log stream name that doesn't already exist, CloudWatch Logs automatically creates it
for you. You can use a literal string or predefined variables ({instance_id}, {hostname}, {ip_address},
or a combination of all three to define a log stream name.

The log stream name specified in this parameter appears on the Log Groups > Streams for
<YourLogStream> screen in the CloudWatch console.

Required: Yes
MetricName

The CloudWatch metric that you want performance data to appear under.
Note
Don't use special characters in the name. If you do, the metric and associated alarms might
not work.

Type: String

Required: Yes
NameSpace

The metric namespace where you want performance counter data to be written.

Type: String

Required: Yes
PollInterval

How many seconds must elapse before new performance counter and log data is uploaded.

Type: Integer

Valid values: Set this to 5 or more seconds. Fifteen seconds (00:00:15) is recommended.

Required: Yes
Region

The AWS Region where you want to send log data. Although you can send performance counters to
a different Region from where you send your log data, we recommend that you set this parameter to
the same Region where your instance is running.

Type: String

Valid values: Regions IDs of the AWS Regions supported by both Systems Manager and CloudWatch
Logs, such as us-east-2, eu-west-1, and ap-southeast-1. For lists of AWS Regions supported
by each service, see AWS Systems Manager and Amazon CloudWatch Logs in the AWS General
Reference.

809
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Required: Yes
SecretKey

Your secret access key. This property is required unless you launched your instance using an IAM role.

Type: String

Required: No
startType

Enable or disable CloudWatch on the instance.

Type: String

Valid values: Enabled | Disabled

Required: Yes
TimestampFormat

The timestamp format you want to use. For a list of supported values, see Custom Date and Time
Format Strings in the MSDN Library.

Type: String

Required: Yes
TimeZoneKind

Provides time zone information when no time zone information is included in your log’s timestamp.
If this parameter is left blank and if your timestamp doesn’t include time zone information,
CloudWatch Logs defaults to the local time zone. This parameter is ignored if your timestamp
already contains time zone information.

Type: String

Valid values: Local | UTC

Required: No
Unit

The appropriate unit of measure for the metric.

Type: String

Valid values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes |

Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/
Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second
| Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None

Required: Yes

aws:configureDocker
(Schema version 2.0 or later) Configure an instance to work with containers and Docker. This plugin runs
only on Microsoft Windows Server operating systems. For more information, see AWS Systems Manager
Documents (p. 775).

Syntax

"mainSteps": [

810
 AWS Systems Manager User Guide
SSM Document Plugin Reference

{
"action": "aws:configureDocker",
"name": "ConfigureDocker",
"inputs": {
"action": "{{ action }}"
}
}
]

Inputs
action

The type of action to perform.

Type: Enum

Valid values: Install | Uninstall

Required: Yes

aws:configurePackage
(Schema version 2.0 or later) Install or uninstall an AWS package. This plugin runs on Microsoft Windows
Server and Linux operating systems, but not all the available packages are supported on Linux operating
systems.

Available packages for Microsoft Windows Server include the following: AWSPVDriver,
AwsEnaNetworkDriver, IntelSriovDriver, AwsVssComponents, AmazonCloudWatchAgent, and
AWSSupport-EC2Rescue.

Available packages for Linux operating systems include the following: AmazonCloudWatchAgent and
AWSSupport-EC2Rescue.

For more information, see AWS Systems Manager Documents (p. 775).

Syntax

"mainSteps": [
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]

Inputs
name

The name of the AWS package to install or uninstall. Available packages include the
following: AWSPVDriver, AwsEnaNetworkDriver, IntelSriovDriver, AwsVssComponents, and
AmazonCloudWatchAgent.

Type: String

811
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Required: Yes
action

Install or uninstall a package.

Type: Enum

Valid values: Install | Uninstall

Required: Yes
version

A specific version of the package to install or uninstall. If installing, the system installs the latest
published version, by default. If uninstalling, the system uninstalls the currently installed version, by
default. If no installed version is found, the latest published version is downloaded, and the uninstall
action is run.

Type: String

Required: No

aws:domainJoin
Join an Amazon EC2 instance to a domain. This plugin only runs on Microsoft Windows Server operating
systems. For more information, see AWS Systems Manager Documents (p. 775).

Syntax

"runtimeConfig":{
"aws:domainJoin":{
"properties":{
"directoryId":"{{ directoryId }}",
"directoryName":"{{ directoryName }}",
"directoryOU":"{{ directoryOU }}",
"dnsIpAddresses":"{{ dnsIpAddresses }}"
}
}

Properties
directoryId

The ID of the directory.

Type: String

Required: Yes

Example: "directoryId": "d-1234567890"

directoryName

The name of the domain.

Type: String

Required: Yes

Example: "directoryName": "example.com"

812
 AWS Systems Manager User Guide
SSM Document Plugin Reference

directoryOU

The organizational unit (OU).

Type: String

Required: No

Example: "directoryOU": "OU=test,DC=example,DC=com"

dnsIpAddresses

The IP addresses of the DNS servers.

Type: Array

Required: No

Example: "dnsIpAddresses": ["198.51.100.1","198.51.100.2"]

Examples
For examples, see Joining a Windows Server Instance to an AWS Directory Service Domain in the Amazon
EC2 User Guide for Windows Instances.

aws:downloadContent
(Schema version 2.0 or later) Download SSM documents and scripts from remote locations. This plugin is
supported on Linux and Windows Server operating systems.

Syntax

"mainSteps": [
{
"action":"aws:downloadContent",
"name":"downloadContent",
"inputs":{
"sourceType":"{{ sourceType }}",
"sourceInfo":"{{ sourceInfo }}",
"destinationPath":"{{ destinationPath }}"
}
}

Inputs
sourceType

The download source. Systems Manager currently supports the following source types for
downloading scripts and SSM documents: GitHub, S3, and SSMDocument.

Type: String

Required: Yes
sourceInfo

The information required to retrieve the content from the required source.

Type: StringMap

813
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Required: Yes

For sourceType GitHub, specify the following:

• owner: The repository owner.
• repository: The name of the repository.
• path: The path to the file or directory you want to download.
• getOptions: Extra options to retrieve content from a different branch or a different commit. This
parameter uses the following format:
• branch:branch_name

The default is master.

• commitID:commitID

The default is head.

• tokenInfo: The Systems Manager parameter (a SecureString parameter) where you store your
access token information, in the format {{ssm-secure:secure-string-token}}.
Note
This tokenInfo field is the only SSM document plugin field that supports a SecureString
parameter. SecureString parameters are not supported for any other fields, nor for any
other SSM document plugins.

Example syntax:
{
"owner":"TestUser",
"repository":"GitHubTest",
"path": "scripts/python/test-script",
"getOptions" : "branch:master",
"tokenInfo":"{{ssm-secure:secure-string-token}}"
}

For sourceType S3, specify the following:

• path: The URL to the file or directory you want to download from Amazon S3.

Example syntax:
{
"path": "https://s3.amazonaws.com/aws-executecommand-test/powershell/
helloPowershell.ps1"
}

For sourceType SSMDocument, specify one of the following:

• name: The name and version of the document in the following format: name:version. Version is
optional.

Example syntax:
{
"name": "Example-RunPowerShellScript:3"
}

• name: The ARN for the document in the following format:

arn:aws:ssm:region:account_id:document/document_name

{
"name":"arn:aws:ssm:us-east-2:3344556677:document/MySharedDoc"
}

814
 AWS Systems Manager User Guide
SSM Document Plugin Reference

destinationPath

An optional local path on the instance where you want to download the file. If you don't specify a
path, the content is downloaded to a path relative to your command ID.

Type: String

Required: No

aws:psModule
Install PowerShell modules on an EC2 instance. This plugin only runs on Microsoft Windows Server
operating systems. For more information, see AWS Systems Manager Documents (p. 775).

Syntax

"runtimeConfig":{
"aws:psModule":{
"properties":[
{
"id":"0.aws:psModule",
"runCommand":"{{ commands }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]

Properties
runCommand

The PowerShell command to run after the module is installed.

Type: List or Array

Required: No
source

The URL or local path on the instance to the application .zip file.

Type: String

Required: No
sourceHash

The SHA256 hash of the .zip file.

Type: String

Required: No
timeoutSeconds

The time in seconds for a command to be completed before it is considered to have failed.

Type: String

Required: No

815
 AWS Systems Manager User Guide
SSM Document Plugin Reference

workingDirectory

The path to the working directory on your instance.

Type: String

Required: No

aws:refreshAssociation
(Schema version 2.0 or later) Refresh (force apply) an association on demand. This action will change the
system state based on what is defined in the selected association or all associations bound to the targets.
This plugin runs on Linux and Microsoft Windows Server operating systems. For more information, see
AWS Systems Manager Documents (p. 775).

Syntax

"action":"aws:refreshAssociation",
"name":"refreshAssociation",
"inputs": {
"associationIds": "{{ associationIds }}"
}

Inputs
associationIds

List of association IDs. If empty, all associations bound to the specified target are applied.

Type: StringList

Required: No

aws:runDockerAction
(Schema version 2.0 or later) Run Docker actions on containers. This plugin runs on Linux and
Microsoft Windows Server operating systems. For more information, see AWS Systems Manager
Documents (p. 775).

Syntax

"mainSteps": [
{
"action": "aws:runDockerAction",
"name": "RunDockerAction",
"inputs": {
"action": "{{ action }}",
"container": "{{ container }}",
"image": "{{ image }}",
"memory": "{{ memory }}",
"cpuShares": "{{ cpuShares }}",
"volume": "{{ volume }}",
"cmd": "{{ cmd }}",
"env": "{{ env }}",
"user": "{{ user }}",
"publish": "{{ publish }}"
}

816
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Inputs
action

The type of action to perform.

Type: String

Required: Yes
container

The Docker container ID.

Type: String

Required: No
image

The Docker image name.

Type: String

Required: No
cmd

The container command.

Type: String

Required: No
memory

The container memory limit.

Type: String

Required: No
cpuShares

The container CPU shares (relative weight).

Type: String

Required: No
volume

The container volume mounts.

Type: StringList

Required: No
env

The container environment variables.

Type: String

Required: No

817
 AWS Systems Manager User Guide
SSM Document Plugin Reference

user

The container user name.

Type: String

Required: No
publish

The container published ports.

Type: String

Required: No

aws:runDocument
(Schema version 2.0 or later) Runs SSM documents stored in Systems Manager or on a local share. You
can use this plugin with the aws:downloadContent (p. 813) plugin to download an SSM document from
a remote location to a local share, and then run it. This plugin is supported on Linux and Windows Server
operating systems.

Syntax

"mainSteps": [
{
"action":"aws:runDocument",
"name":"runDocument",
"inputs":{
"documentType":"{{ documentType }}",
"documentPath":"{{ documentPath }}",
"documentParameters":"{{ documentParameters }}"
}
}

Inputs
documentType

The document type to run. You can run local documents (LocalPath) or documents stored in
Systems Manager (SSMDocument).

Type: String

Required: Yes
documentPath

The path to the document. If documentType is LocalPath, then specify the path to the document
on the local share. If documentType is SSMDocument, then specify the name of the document.

Type: String

Required: No
documentParameters

Parameters for the document.

Type: StringMap

818
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Required: No

aws:runPowerShellScript
Run PowerShell scripts or specify the path to a script to run. This plugin runs on Microsoft Windows and
Linux operating systems. For more information, see AWS Systems Manager Documents (p. 775).

Syntax
Syntax for 1.2 SSM document

"runtimeConfig":{
"aws:runPowerShellScript":{
"properties":[
{
"id":"0.aws:runPowerShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]

Syntax for 2.2 SSM document

"mainSteps": [
{
"action":"aws:runPowerShellScript",
"name":"step name",
"inputs":{
"timeoutSeconds":"Timeout in seconds",
"runCommand":"[Command to run]"
}
}
]

Here is a schemaVersion 2.2 example:

{
"schemaVersion":"2.2",
"description":"Simple test document using the aws:runPowerShellScript plugin.",
"parameters":{
"Salutation":{
"type":"String",
"description":"(Optional) This is an optional parameter that will be displayed in
the output of the command if specified.",
"allowedPattern":"[a-zA-Z]",
"default":"World"
}
},
"mainSteps":[
{
"action":"aws:runPowerShellScript",
"name":"DisplaySalutation",
"inputs":{
"timeoutSeconds":60,
"runCommand":[
"$salutation = '{{ Salutation }}'",
"",
"if ( [String]::IsNullOrWhitespace( $salutation ) )",
"{",

819
 AWS Systems Manager User Guide
SSM Document Plugin Reference

" $salutation = 'anonymous'",

"}",
"",
"Write-Host ('Hello {0}' -f $salutation)"
]
}
}
]
}

Properties
runCommand

Specify the commands to run or the path to an existing script on the instance.

Type: List or Array

Required: Yes
timeoutSeconds

The time in seconds for a command to be completed before it is considered to have failed. When the
timeout is reached, Systems Manager stops the command execution.

Type: String

Required: No
workingDirectory

The path to the working directory on your instance.

Type: String

Required: No

aws:runShellScript
Run Linux shell scripts or specify the path to a script to run. This plugin only runs on Linux operating
systems. For more information, see AWS Systems Manager Documents (p. 775).

Syntax
Syntax for 1.2 SSM document

"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]

Syntax for 2.2 SSM document

"mainSteps": [

820
 AWS Systems Manager User Guide
SSM Document Plugin Reference

{
"action":"aws:runShellScript",
"name":"step name",
"inputs":{
"timeoutSeconds":"Timeout in seconds",
"runCommand":"[Command to run]"
}
}
]

Here is a schemaVersion 2.2 example:

{
"schemaVersion": "2.2",
"description": "Simple test document using the aws:runShellScript plugin.",
"parameters": {
"salutation": {
"type": "String",
"description": "(Optional) This is an optional parameter that will be displayed in
the output of the command if specified.",
"default": "Hello World"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "DisplaySalutation",
"inputs": {
"timeoutSeconds": 60,
"runCommand": [
"echo {{ salutation }}"
]
}
}
]
}

Properties
runCommand

Specify the commands to run or the path to an existing script on the instance.

Type: List or Array

Required: Yes
timeoutSeconds

The time in seconds for a command to be completed before it is considered to have failed. When the
timeout is reached, Systems Manager stops the command execution.

Type: String

Required: No
workingDirectory

The path to the working directory on your instance.

Type: String

Required: No

821
 AWS Systems Manager User Guide
SSM Document Plugin Reference

aws:softwareInventory
(Schema version 2.0 or later) Gather metadata about applications, files, and configurations on your
managed instances. This plugin runs on Linux and Microsoft Windows Server operating systems. For
more information about collecting inventory, see AWS Systems Manager Inventory (p. 512).

Syntax

"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"files": "{{ files }}",
"services": "{{ services }}",
"windowsRoles": "{{ windowsRoles }}",
"windowsRegistry": "{{ windowsRegistry}}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]

Inputs
applications

(Optional) Collect metadata for installed applications.

Type: String

Required: No
awsComponents

(Optional) Collect metadata for AWS components like amazon-ssm-agent.

Type: String

Required: No
files

(Optional, requires SSM Agent version 2.2.64.0 or later) Collect metadata for files, including file
names, the time files were created, the time files were last modified and accessed, and file sizes,
to name a few. For more information about collecting file inventory, see Working with File and
Windows Registry Inventory (p. 518).

Type: String

Required: No
networkConfig

(Optional) Collect metadata for network configurations.

Type: String

Required: No

822
 AWS Systems Manager User Guide
SSM Document Plugin Reference

windowsUpdates

(Optional) Collect metadata for all Windows updates.

Type: String

Required: No
instanceDetailedInformation

(Optional) Collect more instance information than is provided by the default inventory plugin
(aws:instanceInformation), including CPU model, speed, and the number of cores, to name a few.

Type: String

Required: No
services

(Optional, Windows OS only, requires SSM Agent version 2.2.64.0 or later) Collect metadata for
service configurations.

Type: String

Required: No
windowsRegistry

(Optional, Windows OS only, requires SSM Agent version 2.2.64.0 or later) Collect Windows Registry
keys and values. You can choose a key path and collect all keys and values recursively. You can also
collect a specific registry key and its value for a specific path. Inventory collects the key path, name,
type, and the value. For more information about collecting Windows Registry inventory, see Working
with File and Windows Registry Inventory (p. 518).

Type: String

Required: No
windowsRoles

(Optional, Windows OS only, requires SSM Agent version 2.2.64.0 or later) Collect metadata for
Microsoft Windows role configurations.

Type: String

Required: No
customInventory

(Optional) Collect custom inventory data. For more information about custom inventory, see
Working with Custom Inventory (p. 541)

Type: String

Required: No

aws:updateAgent
Update the EC2Config service to the latest version or specify an older version. This plugin only runs on
Microsoft Windows Server operating systems. For more information about the EC2Config service, see
Configuring a Windows Instance Using the EC2Config Service. For more information about documents,
see AWS Systems Manager Documents (p. 775).

823
 AWS Systems Manager User Guide
SSM Document Plugin Reference

Syntax

"runtimeConfig": {
"aws:updateAgent": {
"properties": {
"agentName": "Ec2Config",
"source": "https://s3.region.amazonaws.com/aws-ssm-region/manifest.json",
"allowDowngrade": "{{ allowDowngrade }}",
"targetVersion": "{{ version }}"
}
}
}

Properties
agentName

EC2Config. This is the name of the agent that runs the EC2Config service.

Type: String

Required: Yes
allowDowngrade

Allow the EC2Config service to be downgraded to an earlier version. If set to false, the service can be
upgraded to newer versions only (default). If set to true, specify the earlier version.

Type: Boolean

Required: No
source

The location where Systems Manager copies the version of EC2Config to install. You can't change
this location.

Type: String

Required: Yes
targetVersion

A specific version of the EC2Config service to install. If not specified, the service will be updated to
the latest version.

Type: String

Required: No

aws:updateSSMAgent
Update SSM Agent to the latest version or specify an older version. This plugin runs on Linux and
Windows Server operating systems. For more information, see Working with SSM Agent (p. 64). For more
information about documents, see AWS Systems Manager Documents (p. 775).

Syntax

"runtimeConfig": {
"aws:updateSsmAgent": {
"properties": [

824
 AWS Systems Manager User Guide
Parameter Store

{
"agentName": "amazon-ssm-agent",
"source": "https://s3.region.amazonaws.com/aws-ssm-region/manifest.json",
"allowDowngrade": "{{ allowDowngrade }}",
"targetVersion": "{{ version }}"
}
]
}
}

Properties
agentName

amazon-ssm-agent. This is the name of the Systems Manager agent that processes requests and
runs commands on the instance.

Type: String

Required: Yes
allowDowngrade

Allow SSM Agent to be downgraded to an earlier version. If set to false, the agent can be upgraded
to newer versions only (default). If set to true, specify the earlier version.

Type: Boolean

Required: No
source

The location where Systems Manager copies the SSM Agent version to install. You can't change this
location.

Type: String

Required: Yes
targetVersion

A specific version of SSM Agent to install. If not specified, the agent will be updated to the latest
version.

Type: String

Required: No

AWS Systems Manager Parameter Store

AWS Systems Manager Parameter Store provides secure, hierarchical storage for configuration data
management and secrets management. You can store data such as passwords, database strings, and
license codes as parameter values. You can store values as plain text or encrypted data. You can then
reference values by using the unique name that you specified when you created the parameter. Highly
scalable, available, and durable, Parameter Store is backed by the AWS Cloud.

Parameter Store offers the following benefits and features.

• Use a secure, scalable, hosted secrets management service with no servers to manage.
• Improve your security posture by separating your data from your code.

825
 AWS Systems Manager User Guide
Getting Started with Parameter Store

• Store configuration data and secure strings in hierarchies and track versions.
• Control and audit access at granular levels.
• Configure change notifications and trigger automated actions for both parameters and parameter
policies.
• Tag parameters individually, and then secure access from different levels, including operational,
parameter, Amazon EC2 tag, and path levels.
• Reference AWS Secrets Manager secrets by using Parameter Store parameters.
• Use Parameter Store parameters with other Systems Manager capabilities and AWS services to retrieve
secrets and configuration data from a central store. The growing list of AWS services that support
Parameter Store parameters includes the following:
• Amazon Elastic Compute Cloud (Amazon EC2)
• Amazon Elastic Container Service (Amazon ECS)
• AWS Lambda
• AWS CloudFormation
• AWS CodeBuild
• AWS CodeDeploy
• Configure integration with the following AWS services for encryption, notification, monitoring, and
auditing:
• AWS Key Management Service (AWS KMS)
• Amazon Simple Notification Service (Amazon SNS)
• Amazon CloudWatch
• AWS CloudTrail

Getting Started with Parameter Store

To get started with Systems Manager Parameters, refer to the following sections:

Task For More Information

Learn about different types of Systems Manager Learn More About Parameters (p. 827)
parameters.

Configure parameter access and notifications. Setting Up Parameter Store (p. 832)

Learn how to organize, create, and tag Working with Parameters (p. 839)
parameters.

Learn about creating and using Systems Manager Parameter Store Walkthroughs (p. 875)
parameters in a test environment.

Learn how Parameter Store uses AWS Key How AWS Systems Manager Parameter Store Uses
Management Service (KMS) to manage secure AWS KMS
string parameters.

Learn about the benefits of the advanced- About Advanced Parameters (p. 831)
parameter tier.

Learn how to increase the number of transactions Increasing Parameter Store Throughput (p. 866)
per second that Parameter Store can process.

Related Content

826
 AWS Systems Manager User Guide
Learn More About Parameters

The following resources provide more information about Parameter Store and how to use this capability
with other AWS services.

• AWS Systems Manager Limits in the Amazon Web Services General Reference.
• Referencing AWS Secrets Manager Secrets from Parameter Store Parameters (p. 90)
• Managing Secrets for Amazon ECS Applications Using Parameter Store and IAM Roles for Tasks
• Use Parameter Store to Securely Access Secrets and Config Data in AWS CodeDeploy
• Interesting Articles on EC2 Systems Manager Parameter Store

Learn More About Parameters

AWS Systems Manager Parameter Store provides secure, hierarchical storage for configuration data
management and secrets management.

You can store data such as passwords, database strings, and license codes as parameter values. You can
store values as plain text or encrypted data. You can reference Systems Manager parameters in your
scripts, commands, SSM documents, and configuration and automation workflows.

Parameters work with Systems Manager capabilities such as Run Command, State Manager, and
Automation. You can also reference parameters in a number of other AWS services.

Topics
• About Parameters (p. 827)
• About Advanced Parameters (p. 831)

About Parameters
A Parameter Store parameter is any piece of configuration data, such as a password or license key, that is
saved in Parameter Store. You can centrally and securely reference this data in your scripts, commands,
and SSM documents. Parameter Store provides support for three types of parameters: String, String
List, and Secure String. When you reference a parameter, you specify the parameter name by using the
following convention:

ssm:parameter-name

The following is an example of a Systems Manager parameter named DNS-IP. The value of this
parameter is simply the IP address of an instance. This example uses an AWS CLI command to echo the
parameter value.

aws ssm send-command --document-name "AWS-RunPowerShellScript" --document-version "1"

--targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" --parameters "commands='echo
{{ssm:DNS-IP}}'" --timeout-seconds 600 --max-concurrency "50" --max-errors "0" --region
us-east-2

The next example parameter uses a secure string parameter named SecurePassword. The
command commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -
WithDecryption $True).Parameters[0].Value','net user administrator $secure']
retrieves and decrypts the value of the Secure String parameter, and then resets the local administrator
password without having to pass the password in clear text.

aws ssm send-command --document-name "AWS-RunPowerShellScript" --document-

version "1" --targets "Key=instanceids,Values=i-02573cafcfEXAMPLE" --parameters
"commands=['$secure = (Get-SSMParameterValue -Names SecurePassword -WithDecryption

827
 AWS Systems Manager User Guide
Learn More About Parameters

$True).Parameters[0].Value','net user administrator $secure']" --timeout-seconds 600 --

max-concurrency "50" --max-errors "0" --region us-east-2

You can also reference Systems Manager parameters in the Parameters section of an SSM document, as
shown in the following example.

{
"schemaVersion":"2.0",
"description":"Sample version 2.0 document v2",
"parameters":{
"commands" : {
"type": "StringList",
"default": ["{{ssm:parameter_name}}"]
}
},
"mainSteps":[
{
"action":"aws:runShellScript",
"name":"runShellScript",
"inputs":{
"runCommand": "{{commands}}"
}
}
]
}

Note
The runtimeConfig section of SSM documents use similar syntax for local parameters. A local
parameter isn't the same as a Systems Manager parameter. You can distinguish local parameters
from Systems Manager parameters by the absence of the ssm: prefix.

"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"

SSM documents currently don't support references to secure string parameters. This means that to use
secure string parameters with, for example, Run Command, you have to retrieve the parameter value
before passing it to Run Command, as shown in the following examples:

AWS CLI

value=$(aws ssm get-parameters --names parameter_name --with-decryption)

aws ssm send-command –name AWS-JoinDomain –parameters password=$value –instance-

id instance-id

Tools for Windows PowerShell

$secure = (Get-SSMParameterValue -Names parameter_name -WithDecryption

$True).Parameters[0].Value | ConvertTo-SecureString -AsPlainText -Force

$cred = New-Object System.Management.Automation.PSCredential -argumentlist user_name,

$secure

828
 AWS Systems Manager User Guide
Learn More About Parameters

About Secure String Parameters

A secure string parameter is any sensitive data that needs to be stored and referenced in a secure
manner. If you have data that you don't want users to alter or reference in plain text, such as passwords
or license keys, create those parameters using the SecureString datatype. We recommend using
secure string parameters for the following scenarios.

• You want to use data/parameters across AWS services without exposing the values as plain text in
commands, functions, agent logs, or AWS CloudTrail logs.
• You want to control who has access to sensitive data.
• You want to be able to audit when sensitive data is accessed (AWS CloudTrail).
• You want to encrypt your sensitive data and you want to bring your own encryption keys to manage
access.

If you choose the SecureString datatype when you create a parameter, then Parameter Store uses an
AWS Key Management Service (KMS) customer master key (CMK) to encrypt the parameter value. KMS
uses either a customer managed CMK or an AWS-managed CMK when encrypting the parameter value.
For more information about AWS managed and customer managed CMKs, see AWS Key Management
Service Concepts in the AWS Key Management Service Developer Guide. For more information about
Parameter Store and AWS KMS encryption, see How AWS Systems Manager Parameter Store Uses AWS
KMS.
Note
To view a CMK, use the AWS KMS DescribeKey operation. This AWS CLI example uses
DescribeKey to view an AWS-managed CMK.

aws kms describe-key --key-id alias/aws/ssm

Important
Only the value of a secure string parameter is encrypted. Parameter names, descriptions, and
other properties are not encrypted.

Create a Secure String Parameter Using a KMS Customer Master Key

If you create a secure string parameter by using the AWS-managed CMK in your account and Region,
then you don't have to provide a value for the --key-id parameter.

The following AWS CLI example shows the command to create a new secure string parameter in
Parameter Store without the --key-id parameter:

aws ssm put-parameter --name parameter_name --value "parameter value" --type SecureString

Create a Secure String Parameter Using a Customer Managed CMK

To use a customer managed CMK instead of the AWS-managed CMK assigned to your account, you must
specify the key by using the --key-id parameter. The parameter supports the following KMS parameter
formats.

• Key ARN example:

arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012
• Alias ARN example:

arn:aws:kms:us-east-2:123456789012:alias/MyAliasName
• Key ID example:

12345678-1234-1234-1234-123456789012

829
 AWS Systems Manager User Guide
Learn More About Parameters

• Alias Name example:

alias/MyAliasName

You can create a customer managed CMK by using the AWS Management Console or the AWS KMS API.
The following AWS CLI commands create a customer managed key in the current Region of your AWS
account.

aws kms create-key

Use a command in the following format to create a secure string parameter using the key you just
created.

aws ssm put-parameter --name parameter_name --value "parameter value" --type SecureString
--key-id arn:aws:kms:us-east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e

Note
You can manually create a parameter with an encrypted value. In this case, because the value
is already encrypted, you don’t have to choose the SecureString data type. If you do choose
SecureString, your parameter will be doubly encrypted.

By default, all secure string values are displayed as cipher-text. To decrypt a secure string value, a
user must have permission to call the KMS Decrypt API action. For information about configuring KMS
access control, see Authentication and Access Control for AWS KMS in the AWS Key Management Service
Developer Guide.

Using Secure String Parameters With Other AWS Services

You can also use secure string parameters with other AWS services. In the following example, the AWS
Lambda function retrieves a secure string parameter by using the GetParameters API.

from __future__ import print_function

import json
import boto3
ssm = boto3.client('ssm', 'us-east-2')
def get_parameters():
response = ssm.get_parameters(
Names=['LambdaSecureString'],WithDecryption=True
)
for parameter in response['Parameters']:
return parameter['Value']

def lambda_handler(event, context):

value = get_parameters()
print("value1 = " + value)
return value # Echo back the first key value

Related topics

For an example of how to create and use a secure string parameter, see Walkthrough: Create a Secure
String Parameter and Join an Instance to a Domain (PowerShell) (p. 878). For more information about
using Systems Manager parameters with other AWS services, see the following blog posts.

• Managing Secrets for Amazon ECS Applications Using Parameter Store and IAM Roles for Tasks
• Use Parameter Store to Securely Access Secrets and Config Data in CodeDeploy
• Interesting Articles on Amazon EC2 Systems Manager Parameter Store

830
 AWS Systems Manager User Guide
Learn More About Parameters

About Advanced Parameters

AWS Systems Manager Parameter Store includes standard parameters and advanced parameters. You
individually configure parameters to use either the standard-parameter tier (the default tier) or the
advanced-parameter tier.

You can change a standard parameter to an advanced parameter at any time, but you can’t revert an
advanced parameter to a standard parameter. Reverting an advanced parameter to a standard parameter
would result in data loss because the system would truncate the size of the parameter from 8 KB to 4
KB. Reverting would also remove any policies attached to the parameter. Also, advanced parameters use
a different form of encryption than standard parameters. For more information, see How AWS Systems
Manager Parameter Store Uses AWS KMS in the AWS Key Management Service Developer Guide.

If you no longer need an advanced parameter, or if you no longer want to incur charges for an advanced
parameter, you must delete it and recreate it as a new standard parameter.

The following table describes the differences between the tiers.

  Standard Advanced

Total number of parameters 10,000 100,000

allowed

(per AWS account and Region)

Maximum size of a parameter 4 KB 8 KB

value

Parameter policies available No Yes

For more information, see

Working with Parameter
Policies (p. 841).

Cost No additional charge Charges apply

For more information, see AWS

Systems Manager Pricing.

Change a Standard Parameter to an Advanced Parameter

Use the following procedure to change an existing standard parameter to an advanced parameter.
For information about how to create a new advanced parameter, see Creating Systems Manager
Parameters (p. 847).

To change a standard parameter to an advanced parameter

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.
3. Choose a parameter, and then choose Edit.
4. For Description, enter information about this parameter.
5. Choose Advanced.
6. For Value, enter the value of this parameter. Advanced parameters have a maximum value limit of 8
KB.
7. Choose Save changes.

831
 AWS Systems Manager User Guide
Setting Up Parameter Store

Setting Up Parameter Store

To set up parameters in Systems Manager Parameter Store, you first configure AWS Identity and Access
Management (IAM) policies that provide users in your account with permission to perform the actions
you specify.

This section includes information about how to manually configure these policies using the IAM console,
and how to assign them to users and user groups. You can also create and assign policies to control
which parameter actions can be run on an instance.

This section also include information about how to create Amazon CloudWatch Events rules that let
you receive notifications about changes to Systems Manager parameters. You can also use CloudWatch
Events rules to trigger other actions in AWS based on changes in Parameter Store.

Contents
• Control Access to Systems Manager Parameters (p. 832)
• Set Up Notifications or Trigger Actions Based on Parameter Store Events (p. 836)

Control Access to Systems Manager Parameters

You control access to Systems Manager Parameters by using AWS Identity and Access Management
(IAM). More specifically, you create IAM policies that restrict access to the following API operations:

• DeleteParameter
• DeleteParameters
• DescribeParameters
• GetParameter
• GetParameters
• GetParameterHistory
• GetParametersByPath
• PutParameter

We recommend that you control access to Systems Manager parameters by creating restrictive IAM
policies. For example, the following policy allows a user to call the DescribeParameters and
GetParameters API operations for a limited set of resources. This means that the user can get
information about and use all parameters that begin with prod-*.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetParameters"
],
"Resource": "arn:aws:ssm:us-east-2:123456789012:parameter/prod-*"
}
]

832
 AWS Systems Manager User Guide
Setting Up Parameter Store

For trusted administrators, you can provide access to all Systems Manager parameter API operations by
using a policy similar to the following example. This policy gives the user full access to all production
parameters that begin with dbserver-prod-*.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ssm:PutParameter",
"ssm:DeleteParameter",
"ssm:GetParameterHistory",
"ssm:GetParametersByPath",
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:DeleteParameters"
],
"Resource": "arn:aws:ssm:region:account-id:parameter/dbserver-prod-*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "ssm:DescribeParameters",
"Resource": "*"
}
]
}

Topics
• Allowing Only Specific Parameters to Run on Instances (p. 833)
• Controlling Access to Parameters Using Tags (p. 834)

Allowing Only Specific Parameters to Run on Instances

You can control access so that instances can run only parameters that you specify.

If you choose the SecureString data type when you create your parameter, Systems Manager uses
AWS Key Management Service (KMS) to encrypt the parameter value. AWS KMS encrypts the value
by using either an AWS-managed customer master key (CMK) or a customer managed CMK. For more
information about AWS KMS and CMKs, see the AWS Key Management Service Developer Guide.

You can view the AWS-managed CMK by running the following command from the AWS CLI:

aws kms describe-key --key-id alias/aws/ssm

The following example enables instances to get a parameter value only for parameters that begin with
"prod-" If the parameter is a secure string, then the instance decrypts the string using AWS KMS.
Note
Instance policies, like in the following example, are assigned to the instance role in IAM. For
more information about configuring access to Systems Manager features, including how to
assign policies to users and instances, see Setting Up AWS Systems Manager (p. 23).

{
"Version":"2012-10-17",

833
 AWS Systems Manager User Guide
Setting Up Parameter Store

"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:GetParameters"
],
"Resource":[
"arn:aws:ssm:region:account-id:parameter/prod-*"
]
},
{
"Effect":"Allow",
"Action":[
"kms:Decrypt"
],
"Resource":[
"arn:aws:kms:region:account-id:key/CMK"
]
}
]
}

Controlling Access to Parameters Using Tags

After you tag a parameter, you can restrict access to it by creating an IAM policy that specifies the tags
the user can access. When a user attempts to use a parameter, the system checks the IAM policy and the
tags specified for the parameter. If the user does not have access to the tags assigned to the parameter,
the user receives an Access Denied error.

Currently, you can restrict access to the following Get* parameter-related API actions:

• GetParameter
• GetParameters
• GetParameterHistory

Use the following procedure to create an IAM policy that restricts access to parameters by using tags.

Before You Begin

Create and tag parameters. For more information, see Setting Up Parameter Store (p. 832).

To restrict a user's access to parameters by using tags

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Policies, and then choose Create policy.
3. Choose the JSON tab.
4. Copy the following sample policy and paste it into the text field, replacing the sample text. Replace
tag_key and tag_value with the key-value pair for your tag.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:GetParameters"
],
"Resource":"*",
"Condition":{

834
 AWS Systems Manager User Guide
Setting Up Parameter Store

"StringLike":{
"ssm:resourceTag/tag_key":[
"tag_value"
]
}
}
}
]
}

This sample policy restricts access to only the GetParameters API action. You can restrict access to
multiple API actions by using the following format in the Action block:

"Action":[
"ssm:GetParameters",
"ssm:GetParameter",
"ssm:GetParameterHistory",
],

You can specify multiple keys in the policy by using the following Condition format. Specifying
multiple keys creates an AND relationship for the keys.

"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}

You can specify multiple values in the policy by using the following Condition format. ForAnyValue
establishes an OR relationship for the values. You can also specify ForAllValues to establish an AND
relationship.

"Condition":{
"ForAnyValue:StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1",
"tag_value2"
]
}
}

5. Choose Review policy.

6. For Name, specify a name that identifies this as a user policy for tagged parameters.
7. (Optional) For Description, enter a description.
8. Verify details of the policy in the Summary section.
9. Choose Create policy.
10. Assign the policy to IAM users or groups. For more information, see Changing Permissions for an IAM
User and Attaching a Policy to an IAM Group in the IAM User Guide.

After you attach the policy to the IAM user or group account, if a user tries to use a parameter and the
user's policy does not allow the user to access a tag for the parameter (call the GetParameters API
action), the system returns an error. The error is similar to the following:

835
 AWS Systems Manager User Guide
Setting Up Parameter Store

User: user-name isn't authorized to perform: ssm:GetParameters on resource: parameter-ARN

with the following command.

If a parameter has multiple tags, the user will still receive the Access Denied error if the user does not
have permission to access any one of those tags.

Set Up Notifications or Trigger Actions Based on Parameter

Store Events
The topics in this section explain how to use Amazon CloudWatch Events and Amazon Simple
Notification Service (Amazon SNS) to notify you about changes to Systems Manager parameters. You
can create a CloudWatch rule to notify you when a parameter or a parameter label version is created,
updated, or deleted. You can be notified about changes or status related to parameter policies, such as
when a parameter expires, is going to expire, or hasn't changed for a specified period of time.
Note
Parameter policies are available for parameters that use the advanced parameters tier. Charges
apply. For more information, see Working with Parameter Policies (p. 841) and About
Advanced Parameters (p. 831).

The topics below also explain how to trigger other actions on a target for specific parameter events. For
example, you can run an AWS Lambda function to recreate a parameter automatically when it expires
or is deleted. You can set up a notification to trigger a Lambda function when your database password
is updated. The Lambda function can force your database connections to reset or reconnect with the
new password. CloudWatch Events also supports running Run Command commands and Automations
executions, and actions in many other AWS services. For more information, see the Amazon CloudWatch
Events User Guide.

Before You Begin

Create any resources you need to specify the target action for the rule you create. For example, if the
rule you create is for sending a notification, first create an Amazon SNS topic. For more information, see
Getting Started with Amazon SNS in the Amazon Simple Notification Service Developer Guide.

Topics
• Configure CloudWatch Events for Parameters (p. 836)
• Configure CloudWatch Events for Parameter Policies (p. 837)

Configure CloudWatch Events for Parameters

This topic explains how to create a CloudWatch Events rule that invokes a target based on events that
happen to one or more parameters in your AWS account.

To configure CloudWatch Events for Systems Manager parameters

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then choose Create rule.
3. Under Event Source, verify that Event Pattern is selected.
4. Above the Event Pattern Preview field, choose Edit.
Note
You are modifying sample code we provide instead of using the event pattern builder fields.
5. Replace the content in the edit box with the following:

836
 AWS Systems Manager User Guide
Setting Up Parameter Store

{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Change"
],
"detail": {
"name": [
"/parameter-1-name",
"/parameter-2-name/level-2",
"/parameter-3-name/level-2/level-3"
],
"operation": [
"Create",
"Update",
"Delete",
"LabelParameterVersion"
]
}
}

6. Modify the contents for the parameters and the operations you want to take action on.

For example, the following content means an action is taken when either of the parameters
named /Oncall and /Project/Teamlead are updated:

{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Change"
],
"detail": {
"name": [
"/Oncall",
"/Project/Teamlead"
],
"operation": [
"Update"
]
}
}

7. Choose Save.
8. For Targets, choose Add targets.
9. In the Targets list, choose a target type. For example, choose Lambda function or SNS topic.
10. Expand Configure input and choose an option. Then provide any other configuration details
required by the target type you selected.
11. Scroll to the bottom of the page, if necessary, and then choose Configure details.
12. Provide a name and (optional) description for the CloudWatch Events rule. Leave the Enabled box
selected to make the rule active immediately.
13. Choose Create rule.

Configure CloudWatch Events for Parameter Policies

This topic explains how to create CloudWatch Events rules that invoke targets based on events that
happen to one or more parameter policies in your AWS account. When you create an advanced

837
 AWS Systems Manager User Guide
Setting Up Parameter Store

parameter, you specify when a parameter expires, when to receive notification before a parameter
expires, and how long to wait before notification should be sent that a parameter hasn't changed, You
set up notification for these events using the following procedure. For more information, see Working
with Parameter Policies (p. 841) and About Advanced Parameters (p. 831).

To configure CloudWatch Events for Systems Manager parameter policies

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. In the left navigation pane, choose Events, and then choose Create rule.
3. Under Event Source, verify that Event Pattern is selected.
4. Above the Event Pattern Preview field, choose Edit.
Note
You are modifying sample code we provide instead of using the event pattern builder fields.
5. Replace the content in the edit box with the following:

{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Policy Action"
],
"detail": {
"name": [
"/parameter-1-name",
"/parameter-2-name/level-2",
"/parameter-3-name/level-2/level-3"
],
"policy-type": [
"Expiration",
"ExpirationNotification",
"NoChangeNotification"
]
}
}

6. Modify the contents for the parameters and the policy types you want to take action on.
For example, the following content means an action is taken whenever the parameter
named /OncallDuties expires and is deleted:

{
"source": [
"aws.ssm"
],
"detail-type": [
"Parameter Store Policy Action"
],
"detail": {
"name": [
"/OncallDuties"
],
"policy-type": [
"Expiration"
]
}
}

7. Choose Save.
8. For Targets, choose Add targets.

838
 AWS Systems Manager User Guide
Working with Parameters

9. In the Targets list, choose a target type. For example, choose Lambda function or SNS topic.
10. Expand Configure input and choose an option. Then provide any other configuration details
required by the target type you selected.
11. Scroll to the bottom of the page, if necessary, and then choose Configure details.
12. Provide a name and (optional) description for the CloudWatch Events rule. Leave the Enabled box
selected to make the rule active immediately.
13. Choose Create rule.

Related Information

• (Blog post) Use parameter labels for easy configuration update across environments
• Tutorial: Use CloudWatch Events to Relay Events to AWS Systems Manager Run Command in the
Amazon CloudWatch Events User Guide
• Tutorial: Set AWS Systems Manager Automation as a CloudWatch Events Target in the Amazon
CloudWatch Events User Guide

Working with Parameters

This section describes how to organize, create, and tag parameters, and how to create different versions
of parameters.

Topics
• Organizing Parameters into Hierarchies (p. 839)
• Working with Parameter Policies (p. 841)
• Requirements and Constraints for Parameter Names (p. 846)
• Creating Systems Manager Parameters (p. 847)
• Tagging Systems Manager Parameters (p. 852)
• Working with Parameter Versions (p. 854)
• Labeling Parameters (p. 855)

Organizing Parameters into Hierarchies

Managing dozens or hundreds of parameters as a flat list is time consuming and prone to errors. It can
also be difficult to identify the correct parameter for a task. This means you might accidentally use the
wrong parameter, or you might create multiple parameters that use the same configuration data.

You can use parameter hierarchies to help you organize and manage parameters. A hierarchy is a
parameter name that includes a path that you define by using forward slashes (/).

The following example uses three hierarchy levels in the name to identify the following:

/Environment/Type of computer/Application/Data

/Dev/DBServer/MySQL/db-string13

You can create a hierarchy with a maximum of 15 levels. We suggest that you create hierarchies that
reflect an existing hierarchical structure in your environment, as shown in the following examples:

• Your Continuous integration and Continuous delivery environment (CI/CD workflows)

/Dev/DBServer/MySQL/db-string

/Staging/DBServer/MySQL/db-string

839
 AWS Systems Manager User Guide
Working with Parameters

/Prod/DBServer/MySQL/db-string
• Your applications that use containers

/MyApp/.NET/Libraries/my-password

• Your business organization

/Finance/Accountants/UserList

>/Finance/Analysts/UserList

/HR/Employees/EU/UserList

Parameter hierarchies standardize the way you create parameters and make it easier to manage
parameters over time. A parameter hierarchy can also help you identify the correct parameter for a
configuration task. This helps you to avoid creating multiple parameters with the same configuration
data.

You can create a hierarchy that allows you to share parameters across different environments, as shown
in the following examples that use passwords in development and staging environment.

/DevTest/MyApp/database/my-password

You could then create a unique password for your production environment, as shown in the following
example:

/prod/MyApp/database/my-password

You are not required to specify a parameter hierarchy. You can create parameters at level one. These are
called root parameters. For backward compatibility, all parameters created in Parameter Store before
hierarchies were released are root parameters. The systems treats both of the following parameters as
root parameters.

/parameter-name

parameter-name

For an example of how to work with parameter hierarchies, see Walkthrough: Manage Parameters Using
Hierarchies (AWS CLI) (p. 880).

Querying Parameters in a Hierarchy

Another benefit of using hierarchies is the ability to query for all parameters within a hierarchy by using
the GetParametersByPath API action. For example, if you run the following command from the AWS CLI,
the system returns all parameters in the IIS level.

aws ssm get-parameters-by-path --path /Dev/Web/IIS

To view decrypted secure string parameters in a hierarchy, you specify the path and the --with-
decryption parameter, as shown in the following example.

aws ssm get-parameters-by-path --path /Prod/ERP/SAP --with-decryption

Restricting IAM Permissions Using Hierarchies

Using hierarchies and AWS Identity and Access Management (IAM) policies for Parameter Store
API actions, you can provide or restrict access to all parameters in one level of a hierarchy. The
following example policy allows all Parameter Store operations on all parameters for the AWS account

840
 AWS Systems Manager User Guide
Working with Parameters

123456789012 in the US East (Ohio) Region (us-east-2). The user can't create parameters because
the PutParameter action is explicitly denied. This policy also forbids the user from calling the
GetParametersByPath action.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:*"
],
"Resource": "arn:aws:ssm:us-east-2::parameter/*"
},
{
"Effect": "Deny",
"Action": [
"ssm:GetParametersByPath"
],
"Condition": {
"StringEquals": {
"ssm:Recursive": [
"true"
]
}
},
"Resource": "arn:aws:ssm:us-east-2:123456789012:parameter/Dev/ERP/Oracle/*"
},
{
"Effect": "Deny",
"Action": [
"ssm:PutParameter"
],
"Condition": {
"StringEquals": {
"ssm:Overwrite": [
"false"
]
}
},
"Resource": "arn:aws:ssm:us-east-2:123456789012:parameter/*"
}
]
}

Important
If a user has access to a path, then the user can access all levels of that path. For example,
if a user has permission to access path /a, then the user can also access /a/b. Even if
a user has explicitly been denied access in IAM for parameter /b, they can still call the
GetParametersByPath API action recursively and view /a/b.

Working with Parameter Policies

Parameter policies help you manage a growing set of parameters by enabling you to assign specific
criteria to a parameter such as an expiration date or time to live. Parameter policies are especially
helpful in forcing you to update or delete passwords and configuration data stored in Parameter Store.
Parameter Store offers the following types of policies: Expiration, ExpirationNotification, and
NoChangeNotification. The policies are described in more detail in this section.

Parameter Store enforces parameter policies by using asynchronous, periodic scans. After you
create a policy, you don't need to perform additional actions to enforce the policy. Parameter Store
independently performs the action defined by the policy according to the criteria you specified.

841
 AWS Systems Manager User Guide
Working with Parameters

Note
Parameter policies are available for parameters that use the advanced parameters tier. For more
information, see About Advanced Parameters (p. 831).

A parameter policy is a JSON array, as shown in the following table. You can assign a policy when you
create a new advanced parameter, or you can apply a policy by updating a parameter. Parameter Store
supports the following types of parameter policies.

Policy Details Examples

Expiration This policy deletes the

{
parameter. You can "Type":"Expiration",
specify a specific date and "Version":"1.0",
time by using either the "Attributes":{
ISO_INSTANT format or the
ISO_OFFSET_DATE_TIME "Timestamp":"2018-12-02T21:34:33.000Z"
format. To change when you }
}
want the parameter to be
deleted, you must update the
policy. Updating a parameter
does not affect the expiration
date or time of the policy
attached to it. When the
expiration date and time is
reached, Parameter Store
deletes the parameter.
Note
This example uses
the ISO_INSTANT
format. You can also
specify a date and
time by using the
ISO_OFFSET_DATE_TIME
format. Here
is an example:
2019-11-01T22:13:48.87+10:30:00
.

ExpirationNotification This policy triggers an event

{
in Amazon CloudWatch Events
that notifies you about the "Type":"ExpirationNotification",
expiration. By using this policy, "Version":"1.0",
you can receive notifications "Attributes":{
before the expiration time is "Before":"15",
reached, in units of days or "Unit":"Days"
}
hours.
}

NoChangeNotification This policy triggers an event

{
in CloudWatch if a parameter
has not been modified for a "Type":"NoChangeNotification",
specified period of time. This "Version":"1.0",
policy type is useful when, for "Attributes":{
example, a password needs to "After":"20",
be changed within a period of "Unit":"Days"
}
time.
}

842
 AWS Systems Manager User Guide
Working with Parameters

Policy Details Examples

This policy determines when to
send a notification by reading
the LastModifiedTime
attribute of the parameter.
If you change or edit a
parameter, the system resets
the notification time period
based on the new value of
LastModifiedTime.

You can assign multiple policies to a parameter. For example, you can assign Expiration and
ExpirationNotification policies so that the system triggers a CloudWatch Events event to notify
you about the impending deletion of a parameter. You can assign a maximum of ten (10) policies to a
parameter.

The following example shows a PutParameter API request that assigns four policies to a new Secure
String parameter named ProdDB3.

PutParameterRequest
{
"Name":"ProdDB3",
"Description":"Parameter with policies",
"Value":"P@ssW*rd21",
"Type":"SecureString",
"Overwrite":"True",
"Policies":[
{
"Type":"Expiration",
"Version":"1.0",
"Attributes":{
"Timestamp":"2018-12-02T21:34:33.000Z"
}
},
{
"Type":"ExpirationNotification",
"Version":"1.0",
"Attributes":{
"Before":"30",
"Unit":"Days"
}
},
{
"Type":"ExpirationNotification",
"Version":"1.0",
"Attributes":{
"Before":"15",
"Unit":"Days"
}
},
{
"Type":"NoChangeNotification",
"Version":"1.0",
"Attributes":{
"After":"20",
"Unit":"Days"
}
}
]
}

843
 AWS Systems Manager User Guide
Working with Parameters

Adding Policies to an Existing Parameter

This section includes information about how to add policies to an existing parameter by using
the AWS Systems Manager console, the AWS CLI, and AWS Tools for Windows PowerShell. For
information about how to create a new parameter that includes policies, see Creating Systems Manager
Parameters (p. 847).

Topics
• Add Policies to an Existing Parameter (Console) (p. 844)
• Add Policies to an Existing Parameter (AWS CLI) (p. 844)
• Add Policies to an Existing Parameter by Using the Tools for Windows PowerShell (p. 845)

Add Policies to an Existing Parameter (Console)

Use the following procedure to add policies to an existing parameter by using the Systems Manager
console.

To add policies to an existing parameter

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the option next to the parameter that you want to update to include policies, and then
choose Edit.
4. Choose Advanced.
5. (Optional) In the Parameter policies section, choose Enabled. You can specify an expiration date
and one or more notification policies for this parameter.
6. Choose Save changes.

Important

• Parameter Store preserves policies on a parameter until you either overwrite the policies with
new policies or remove the policies.
• To remove all policies from an existing parameter, edit the parameter and apply an empty
policy by using brackets and curly braces, as follows: [{}]
• If you add a new policy to a parameter that already has policies, then Systems Manager
overwrites the policies attached to the parameter. The existing policies are deleted. If you
want to add a new policy to a parameter that already has one or more policies, then you must
copy and paste the original policies, type the new policy, and then save your changes.

Add Policies to an Existing Parameter (AWS CLI)

Use the following procedure to add policies to an existing parameter by using the AWS CLI.

To add policies to an existing parameter

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to add policies to an existing parameter.

844
 AWS Systems Manager User Guide
Working with Parameters

aws ssm put-parameter --name "parameter_name" --value 'a value' --type parameter_type
--policies "[{policies enclosed in brackets and curly braces}]" --overwrite

Here is an example that includes an expiration policy that deletes the parameter after 15 days. The
example also includes a notification policy that generates a CloudWatch Events event five (5) days
before the parameter is deleted. Last, it includes a NoChangeNotification policy if no changes
are made to this parameter after 60 days. The example uses an obfuscated name (elixir3131)
for a password and a AWS Key Management Service (KMS) customer master key (CMK). For more
information about CMKs, see AWS Key Management Service Concepts in the AWS Key Management
Service Developer Guide.

aws ssm put-parameter --name "/Finance/Payroll/elixir3131" --value "P@sSwW)rd" --type

"SecureString" --policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes
\":{\"Timestamp\":\"2018-05-13T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification
\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":
\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":
\"Days\"}}]" --overwrite

3. Run the following command to verify the details of the parameter.

aws ssm describe-parameters --parameter-filters "Key=Name,Values=Name of the

parameter"

Important

• Parameter Store retains policies for a parameter until you either overwrite the policies with
new policies or remove the policies.
• To remove all policies from an existing parameter, edit the parameter and apply an empty
policy of brackets and curly braces. For example:

aws ssm put-parameter --name parameter_name --type type --value 'value' --

policies "[{}]"

• If you add a new policy to a parameter that already has policies, then Systems Manager
overwrites the policies attached to the parameter. The existing policies are deleted. If you
want to add a new policy to a parameter that already has one or more policies, then you must
copy and paste the original policies, type the new policy, and then save your changes.

Add Policies to an Existing Parameter by Using the Tools for Windows PowerShell

Use the following procedure to add policies to an existing parameter by using Tools for Windows
PowerShell.

To add policies to an existing parameter

1. Open AWS Tools for Windows PowerShell and run the following command to specify your
credentials. You must either have administrator privileges in Amazon EC2, or you must have
been granted the appropriate permission in IAM. For more information, see Systems Manager
Prerequisites (p. 12).

Set-AWSCredentials –AccessKey key_name –SecretKey key_name

2. Run the following command to set the Region for your PowerShell session. The example uses the US
East (Ohio) Region (us-east-2).

845
 AWS Systems Manager User Guide
Working with Parameters

Set-DefaultAWSRegion -Region us-east-2

3. Run the following command to add policies to an existing parameter.

Write-SSMParameter -Name "a name" -Value "a value" -Type "parameter type" -Policies
"[{policies enclosed in brackets and curly braces}]" -Overwrite

Here is an example that includes an expiration policy that deletes the parameter at midnight
(GMT) on May 13, 2020. The example also includes a notification policy that generates a
CloudWatch Events event five (5) days before the parameter is deleted. Last, it includes a
NoChangeNotification policy if no changes are made to this parameter after 60 days. The
example uses an obfuscated name (elixir3131) for a password and an AWS-managed customer
master key (CMK).

Write-SSMParameter -Name "/Finance/Payroll/elixir3131" -Value "P@sSwW)rd" -Type

"SecureString" -Policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes
\":{\"Timestamp\":\"2018-05-13T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification
\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":
\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":
\"Days\"}}]" -Overwrite

4. Run the following command to verify the details of the parameter.

(Get-SSMParameterValue -Name "the name you specified").Parameters

Important

• Parameter Store preserves policies on a parameter until you either overwrite the policies with
new policies or remove the policies.
• To remove all policies from an existing parameter, edit the parameter and apply an empty
policy of brackets and curly braces. For example:

Write-SSMParameter -Name "a name" -Value "a value" -Type "parameter type" -
Policies "[{}]"

• If you add a new policy to a parameter that already has policies, then Systems Manager
overwrites the policies attached to the parameter. The existing policies are deleted. If you
want to add a new policy to a parameter that already has one or more policies, then you must
copy and paste the original policies, type the new policy, and then save your changes.

Requirements and Constraints for Parameter Names

Use the information in this topic to help you specify valid values for parameter names when you create a
parameter.

This information supplements the details in the topic PutParameter in the AWS Systems Manager API
Reference, which also provides information about the values AllowedPattern, Description, KeyId,
Overwrite, Type, and Value.

The requirements and constraints for parameter names include the following:

• Case sensitivity: Parameter names are case sensitive.

• Spaces: Parameter names can't include spaces.

846
 AWS Systems Manager User Guide
Working with Parameters

• Valid characters: Parameter names can consist of the following symbols and letters only: a-zA-
Z0-9_.-/
• Length: The maximum length for the fully qualified parameter name you specify is 1011 characters.
(The maximum storage length for the parameter name field in the system is 2048 characters. However,
this length includes capacity for additional system attributes that are not part of the name.)
• Prefixes: A parameter name cannot be prefixed with "aws" or "ssm" (case-insensitive). For example,
attempts to create parameters with the following names will fail with an exception:
• awsTestParameter
• SSM-testparameter
• /aws/testparam1
Note
When you specify a parameter in an SSM document, command, or script, you do include
ssm as part of the syntax, as shown in the following examples. Note that there is no space
between brackets.
• Valid: {{ssm:parameter_name}} and {{ ssm:parameter_name }}, such as
{{ssm:addUsers}}, and {{ssm:addUsers }},
• Invalid: {{ssm:ssmAddUsers}}
• Uniqueness: A parameter name must be unique within an AWS Region. For example, Systems Manager
treats the following as separate parameters, if they exist in the same Region:
• /Test/TestParam1
• /TestParam1

The following examples are also unique:

• /Test/TestParam1/Logpath1
• /Test/TestParam1

The following examples, however, if in the same Region, are not unique:
• /TestParam1
• TestParam1
• Hierarchy depth: If you specify a parameter hierarchy, the hierarchy can have a maximum depth of
fifteen levels. You can define a parameter at any level of the hierarchy. Both of the following examples
are structurally valid:
• /Level-1/L2/L3/L4/L5/L6/L7/L8/L9/L10/L11/L12/L13/L14/parameter-name
• parameter-name

Attempting to create the following parameter would fail with a

HierarchyLevelLimitExceededException exception:
• /Level-1/L2/L3/L4/L5/L6/L7/L8/L9/L10/L11/L12/L13/L14/L15/L16/parameter-name

Important
If a user has access to a path, then the user can access all levels of that path. For example,
if a user has permission to access path /a, then the user can also access /a/b. Even if a
user has explicitly been denied access in IAM for parameter /a/b, they can still call the
GetParametersByPath API action recursively for /a and view /a/b.

Creating Systems Manager Parameters

Use the information in the following topics to help you create Systems Manager parameters using the
AWS Systems Manager console, the AWS CLI, or AWS Tools for Windows PowerShell.

Topics
• Create a Systems Manager Parameter (Console) (p. 848)

847
 AWS Systems Manager User Guide
Working with Parameters

• Create a Systems Manager Parameter (AWS CLI) (p. 849)

• Create a Systems Manager Parameter (Tools for Windows PowerShell) (p. 851)

Create a Systems Manager Parameter (Console)

You can use the AWS Systems Manager console to create a Systems Manager parameter.
Note
Parameters are only available in the AWS Region where they were created.

To create a parameter

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose Create parameter.
4. For Name, type a hierarchy and a parameter name. For example, type /Test/helloWorld.
5. In the Description box, type a description that identifies this parameter as a test parameter.
6. For Parameter tier choose either Standard or Advanced. For more information about advanced
parameters, see About Advanced Parameters (p. 831).
7. For Type, choose String, StringList, or SecureString.
Note

• If you choose SecureString, the KMS Key ID field appears. If you don't provide a
KMS customer master key (CMK) ID, a CMK ARN, an alias name, or an alias ARN, then
the system uses alias/aws/ssm, which is the AWS managed CMK for Systems
Manager. If you don't want to use this key, then you can use a customer managed
CMK. For more information about secure string parameters, see About Secure String
Parameters (p. 829). For more information about AWS managed and customer managed
CMKs, see AWS Key Management Service Concepts in the AWS Key Management Service
Developer Guide. For more information about Parameter Store and KMS encryption, see
How AWS Systems Manager Parameter Store Uses AWS KMS.
• When creating a secure string parameter in the console by using the key-id parameter
with either a customer managed CMK alias name or an alias ARN, you must specify the
prefix alias/ before the alias. Here is an ARN example:

arn:aws:kms:us-east-2:123456789012:alias/MyAliasName

Here is an alias name example:

alias/MyAliasName

8. In the Value box, type a value. For example, type MyFirstParameter. If you chose Secure String,
the value is masked as you type.
9. (Optional) In the Tags area, apply one or more tag key-value pairs to the parameter.

Tags are optional metadata that you assign to a resource. Tags enable you to categorize a resource
in different ways, such as by purpose, owner, or environment. For example, you might want to tag a
Systems Manager parameter to identify the type of resource to which it applies, the environment,

848
 AWS Systems Manager User Guide
Working with Parameters

or the type of configuration data referenced by the parameter. In this case, you could specify the
following key-value pairs:

• Key=Resource,Value=S3bucket
• Key=OS,Value=Windows
• Key=ParameterType,Value=LicenseKey
10. Choose Create parameter.
11. In the parameters list, choose the name of the parameter you just created. Verify the details on the
Overview tab. If you created a secure string parameter, choose Show to view the unencrypted value.

Note
You can’t change an advanced parameter to a standard parameter. If you no longer need an
advanced parameter, or if you no longer want to incur charges for an advanced parameter, you
must delete it and recreate it as a new standard parameter.

Create a Systems Manager Parameter (AWS CLI)

You can use the AWS CLI to create a parameter that uses the String, StringList, or SecureString
data type.

For more information about using the AWS CLI to create parameters, see Walkthrough: Create and Use a
Parameter in a Command (AWS CLI) (p. 876).
Note
Parameters are only available in the AWS Region where they were created.

Topics
• Create a String or StringList Parameter (AWS CLI) (p. 849)
• Create a Secure String Parameter (AWS CLI) (p. 850)

Create a String or StringList Parameter (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create a parameter.

aws ssm put-parameter --name "parameter_name" --value "a parameter value, or a comma-
separated list of values" --type String or StringList

If successful, the command returns the version number of the parameter.

This example adds two key-value pair tags to a parameter. (Depending on the operating system type
on your local machine, run one of the following commands. The version to run from a local Windows
machine includes the escape characters ("\") that you need to run the command from your command
line tool.)

Windows local machine:

aws ssm put-parameter --name parameter-name --value "parameter-value, or a comma-

separated-list-of-values" --type "String" --tags [{\"Key\":\"Region1\",\"Value\":
\"East1\"},{\"Key\":\"Environment1\",\"Value\":\"Production1\"}]

Linux local machine:

849
 AWS Systems Manager User Guide
Working with Parameters

aws ssm put-parameter --name parameter-name --value "parameter-value, or a comma-

separated-list-of-values" --type "String" --tags '[{"Key":"Region","Value":"East"},
{"Key":"Environment", "Value":"Production"}]'

Here is an example that uses the StringList data type.

aws ssm put-parameter --name /IAD/ERP/Oracle/addUsers --value

"Milana,Mariana,Mark,Miguel" --type StringList --tier Standard

Note

• Items in a StringList must be separated by a comma (,). You can't use other
punctuation or special character to escape items in the list. If you have a parameter value
that requires a comma, then use the String data type.
3. Run the following command to verify the details of the parameter.

aws ssm get-parameters --name "the_parameter_name_you_specified"

Here is an example that uses the name specified in the earlier example.

aws ssm get-parameters --name "/IAD/ERP/Oracle/addUsers"

Create a Secure String Parameter (AWS CLI)

Before you create a Secure String parameter, read about the requirements for this type of parameter. For
more information, see About Secure String Parameters (p. 829).

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create a parameter.

aws ssm put-parameter --name "parameter_name" --value "parameter value" --type

SecureString --key-id "a KMS CMK ID, a KMS CMK ARN, an alias name, or an alias ARN"

Note
To use the AWS Key Management Service (KMS) customer master key (CMK) assigned to
your account, remove the key-id parameter from the command. For more information
about CMKs, see AWS Key Management Service Concepts in the AWS Key Management
Service Developer Guide.

The following example uses an obfuscated name (elixir3131) for a password parameter and a
CMK.

aws ssm put-parameter --name /Finance/Payroll/elixir3131 --

value "P@sSwW)rd" --type SecureString --key-id arn:aws:kms:us-
east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e

3. Run the following command to verify the details of the parameter.

aws ssm get-parameters --name "the_parameter_name_you_specified" --with-decryption

850
 AWS Systems Manager User Guide
Working with Parameters

Note
If you don't specify the with-decryption parameter, or if you specify the no-with-
decryption parameter, the command returns an encrypted GUID.

Create a Systems Manager Parameter (Tools for Windows PowerShell)

You can use Tools for Windows PowerShell to create a parameter that uses the String, StringList, or
SecureString data type.
Note
Parameters are only available in the AWS Region where they were created.

Topics
• Create a String or StringList parameter (Tools for Windows PowerShell) (p. 851)
• Create a Secure String parameter (Tools for Windows PowerShell) (p. 852)

Create a String or StringList parameter (Tools for Windows PowerShell)

1. Open AWS Tools for Windows PowerShell and run the following command to specify your
credentials. You must either have administrator privileges in Amazon EC2, or you must have
been granted the appropriate permission in IAM. For more information, see Systems Manager
Prerequisites (p. 12).

Set-AWSCredentials –AccessKey key_name –SecretKey key_name

2. Run the following command to set the Region for your PowerShell session.

Set-DefaultAWSRegion -Region region

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
3. Run the following command to create a parameter.

Write-SSMParameter -Name "parameter_name" -Value "a parameter value, or a comma-

separated list of values" -Type "String or StringList"

If successful, the command returns the version number of the parameter.

Note
Items in a StringList must be separated by a comma (,). You can't use other punctuation
or special character to escape items in the list. If you have a parameter value that requires a
comma, then use the String data type.

Here is an example that uses a String data type.

Write-SSMParameter -Name "/IAD/Web/SQL/IPaddress" -Value "99.99.99.999" -Type "String"

4. Run the following command to verify the details of the parameter.

(Get-SSMParameterValue -Name "the_parameter_name_you_specified").Parameters

851
 AWS Systems Manager User Guide
Working with Parameters

Create a Secure String parameter (Tools for Windows PowerShell)

Before you create a secure string parameter, read about the requirements for this type of parameter. For
more information, see About Secure String Parameters (p. 829).

1. Open AWS Tools for Windows PowerShell and run the following command to specify your
credentials. You must either have administrator privileges in Amazon EC2, or you must have
been granted the appropriate permission in IAM. For more information, see Systems Manager
Prerequisites (p. 12).

Set-AWSCredentials –AccessKey key_name –SecretKey key_name

2. Run the following command to set the Region for your PowerShell session.

Set-DefaultAWSRegion -Region region

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
3. Run the following command to create a parameter.

Write-SSMParameter -Name "parameter_name" -Value "a parameter value" -Type

"SecureString" -KeyId "a KMS CMK ID, a KMS CMK ARN, an alias name, or an alias ARN"

If successful, the command returns the version number of the parameter.

Note
To use the AWS-managed customer master key (CMK) assigned to your account, remove the
-KeyId parameter from the command.

Here is an example that uses an obfuscated name (elixir3131) for a password parameter and an
AWS-managed customer master key (CMK).

Write-SSMParameter -Name "/Finance/Payroll/elixir3131" -Value "P@sSwW)rd" -Type

"SecureString"

4. Run the following command to verify the details of the parameter.

(Get-SSMParameterValue -Name "the_parameter_name_you_specified" –WithDecryption

$true).Parameters

Tagging Systems Manager Parameters

You can use the Systems Manager console, the AWS CLI, the AWS Tools for Windows, or the
AddTagsToResource API to add tags to Systems Manager resources, including documents, managed
instances, maintenance windows, Parameter Store parameters, and patch baselines.

Tags are used to organize parameters. For example, you can tag parameters for specific environments,
departments, or users and groups. After you tag a parameter, you can restrict access to it by creating an
IAM policy that specifies the tags that the user can access. For more information about restricting access
to parameters by using tags, see Controlling Access to Parameters Using Tags (p. 834).

For information about the Regions where Systems Manager is available, see regions.

Topics

852
 AWS Systems Manager User Guide
Working with Parameters

• Tag a Parameter (Console) (p. 853)

• Tag a Parameter (AWS CLI) (p. 853)
• Tag a Parameter (AWS Tools for Windows) (p. 853)

Tag a Parameter (Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.
2. In the left navigation, choose Parameter Store.
3. Choose the name of a parameter you have already created, and then choose the Tags tab.
4. In the first box, enter a key for the tag, such as Environment.
5. In the second box, enter a value for the tag, such as Test.
6. Choose Save.

Tag a Parameter (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to list parameters that you can tag.

aws ssm describe-parameters

Note the name of a parameter that you want to tag.

3. Run the following command to tag a parameter.

aws ssm add-tags-to-resource --resource-type "Parameter" --resource-id

"the_parameter_name" --tags "Key=a key, for example Environment,Value=a value, for
example TEST"

If successful, the command has no output.

4. Run the following command to verify the parameter tags.

aws ssm list-tags-for-resource --resource-type "Parameter" --resource-id

"the_parameter_name"

Tag a Parameter (AWS Tools for Windows)

1. Open AWS Tools for Windows PowerShell and run the following command to specify your
credentials. You must either have administrator privileges in Amazon EC2 or you must have
been granted the appropriate permission in IAM. For more information, see Systems Manager
Prerequisites (p. 12).

Set-AWSCredentials –AccessKey key_name –SecretKey key_name

2. Run the following command to set the Region for your PowerShell session.

Set-DefaultAWSRegion -Region region

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the

853
 AWS Systems Manager User Guide
Working with Parameters

Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.
3. Run the following command to list parameters that you can tag.

Get-SSMParameterList

4. Run the following commands to tag a parameter.

$tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag

$tag1.Key = "Environment"
$tag1.Value = "TEST"
Add-SSMResourceTag -ResourceType "Parameter" -ResourceId "parameter_name" -Tag $tag1

If successful, the command has no output.

5. Run the following command to verify the parameter tags.

Get-SSMResourceTag -ResourceType "Parameter" -ResourceId "parameter_name"

Working with Parameter Versions

When you initially create a parameter, Parameter Store assigns version 1 to that parameter. When you
edit a parameter, Parameter Store automatically iterates the version number by 1. You can specify a
parameter name and a specific version number in API calls and SSM documents. If you don't specify a
version number, the system automatically uses the latest version.

Parameter versions provide a layer of protection in the event that a parameter is accidentally changed.
You can view the details, including the values, of all versions. You can also use parameter versions to see
how many times a parameter changed over a period of time.

You can reference specific parameter versions, including older versions, in commands, API calls, and SSM
documents by using the following format: {{ssm:parameter_name:version}}. Here is an example for a
parameter named RunCommand specified in an SSM document:

{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea",
"default":"{{ssm:RunCommand:2}}"
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it
is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]
{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{

854
 AWS Systems Manager User Guide
Working with Parameters

"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}

The following procedures show you how to edit a parameter and then verify that a new version was
created.

Topics
• Create a New Parameter Version (Console) (p. 855)

Create a New Parameter Version (Console)

You can use the Amazon EC2 console or AWS Systems Manager console to create a new version of a
parameter.

To create a new parameter version

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the name of a parameter that you created earlier. For information about creating a new
parameter, see Creating Systems Manager Parameters (p. 847).
Note
Parameters are only available in the Region where they were created. If you don't see a
parameter that you want to update, then verify your Region.
4. Choose Edit.
5. In the Value box, type a new value, and then choose Save changes.
6. In the parameters list, choose the name of the parameter you just updated, and then view the
History tab. On the Overview tab, verify that the version number incremented by 1, and verify the
new value.

Labeling Parameters
A parameter label is a user-defined alias to help you manage different versions of a parameter. When
you modify a parameter, Systems Manager automatically saves a new version and increments the version
number by one. A label can help you remember the purpose of a parameter version when there are
multiple versions.

For example, let's say you have a parameter called /MyApp/DB/ConnectionString. The value of the
parameter is a connection string to a MySQL server in a local database in a test environment. After you
finish updating the application, you want the parameter to use a connection string for a production
database. You change the value of /MyApp/DB/ConnectionString. Systems Manager automatically
creates version two with the new connection string. To help you remember the purpose of each version,
you attach a label to each parameter. For version one, you attach the label Test and for version two you
attach the label Production.

855
 AWS Systems Manager User Guide
Working with Parameters

You can move labels from one version of a parameter to another version. For example, if you create
version three of the /MyApp/DB/ConnectionString parameter with a connection string for a new
production database, then you can move the Production label from parameter two to parameter three.

Parameter labels are a lightweight alternative to parameter tags. Your organization might have strict
guidelines for tags that must be applied to different AWS resources. In contrast, a label is simply a text
association for a specific version of a parameter.

Similar to tags, you can query parameters by using labels. You can view a list of specific parameter
versions that all use the same label if you query your parameter set by using the GetParametersByPath
API action, as described later in this section.

Label Requirements and Restrictions

Parameter labels have the following requirements and restrictions:

• A version of a parameter can have a maximum of 10 labels.

• You can't attach the same label to different versions of the same parameter. For example, if version 1
has the label Production, then you can't attach Production to version 2.
• You can move a label from one version of a parameter to another.
• You can't create a label when you create a new parameter. You must attach a label to a specific version
of a parameter.
• You can't delete a parameter label. If you no longer want to use a parameter label, then you must
move it to a different version of a parameter.
• A label can have a maximum of 100 characters.
• Labels can contain letters (case sensitive), numbers, periods (.), hyphens (-), or underscores (_).
• Labels can't begin with a number, "aws," or "ssm" (not case sensitive). If a label fails to meet these
requirements, then the label is not attached to the parameter version and the system displays it in the
list of InvalidLabels.

Topics
• Working With Parameter Labels (Console) (p. 856)
• Working With Parameter Labels (AWS CLI) (p. 858)

Working With Parameter Labels (Console)

This section describes how to perform the following tasks by using the AWS Systems Manager console.

• Create a New Parameter Label (p. 856)

• View Labels Attached to a Parameter (p. 857)
• Move a Parameter Label (p. 857)

Create a New Parameter Label

The following procedure describes how to attach a label to a specific version of an existing parameter by
using the Systems Manager console. You can't attach a label when you create a parameter.

To attach a label to a parameter version by using the console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

856
 AWS Systems Manager User Guide
Working with Parameters

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the name of a parameter to open the details page for that parameter.
4. Choose the History tab.
5. Choose the parameter version for which you want to attach a label.
6. Choose Attach labels.
7. Choose Add another label.
8. In the text box, enter the label. To add more labels, choose Add another label. You can attach a
maximum of ten labels.
9. When you are finished attaching labels, choose Confirm.

View Labels Attached to a Parameter

A parameter version can have a maximum of ten labels. The following procedure describes how to view
all labels attached to a parameter version by using the Systems Manager console.

To view labels attached to a parameter version by using the console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the name of a parameter to open the details page for that parameter.
4. Choose the History tab.
5. Locate the parameter version for which you want to view all attached labels. The Labels column
shows all labels attached to the parameter version.

Move a Parameter Label

You can't delete a parameter label after you create it. You can, however, move a label between versions
of a parameter. The following procedure describes how to move a parameter label to a different version
of the same parameter by using the Systems Manager console.

To move a label to a different parameter version by using the console

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the name of a parameter to open the details page for that parameter.
4. Choose the History tab.
5. Choose the parameter version for which you want to move the label.
6. Choose Attach labels.

857
 AWS Systems Manager User Guide
Working with Parameters

7. Choose Add another label.

8. In the text box, enter the label. The console notifies you of the label move.
9. When you are finished, choose Confirm.

Working With Parameter Labels (AWS CLI)

This section describes how to perform the following tasks by using the AWS CLI.

• Create a New Parameter Label (p. 858)

• View Labels for a Parameter (p. 859)
• View a List of Parameters that are Assigned a Label (p. 860)
• Move a Parameter Label (p. 861)

Create a New Parameter Label

The following procedure describes how to attach a label to a specific version of an existing parameter by
using the AWS CLI. You can't attach a label when you create a parameter.

To create a new parameter label

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to view a list of parameters for which you have permission to attach a
label.
Note
Parameters are only available in the Region where they were created. If you don't see a
parameter for which you want to attach a label, then verify your Region.

aws ssm describe-parameters

Note the name of a parameter for which you want to attach a label.
3. Run the following command to view all versions of the parameter.

aws ssm get-parameter-history --name "the_parameter_name"

Note the parameter version for which you want to attach a label.
4. Run the following command to retrieve information about a parameter by version number.

aws ssm get-parameters --names “the_parameter_name:the_version_number"

Here is an example.

aws ssm get-parameters --names “/Production/SQLConnectionString:3"

5. Run one of the following commands to attach a label to a version of a parameter. If you attach
multiple labels, then you must separate label names with a space.

Attach a label to the latest version of a parameter

aws ssm label-parameter-version --name parameter_name --labels label_name

858
 AWS Systems Manager User Guide
Working with Parameters

Attach a label to a specific version of a parameter

aws ssm label-parameter-version --name parameter_name --parameter-

version version_number --labels label_name

Here are some examples:

aws ssm label-parameter-version --name /config/endpoint --labels production east-region

finance

aws ssm label-parameter-version --name /config/endpoint --parameter-version 3 --labels

MySQL-test

Note
If the output shows the label you created in the InvalidLabels list, then the label does
not meet the requirements described earlier in this topic. Review the requirements and try
again. If the InvalidLabels list is empty, then your label was successfully applied to the
version of the parameter.
6. You can view the details of the parameter by using either a version number or a label name. Run the
following command and specify the label you created in the previous step.

aws ssm get-parameter --name parameter_name:label_name --with-decryption

The command returns information like the following:

{
"Parameter": {
"Version": version_number,
"Type": "parameter_type",
"Name": "parameter_name",
"Value": "parameter_value",
"Selector": ":label_name"
}
}

Note
Selector in the output is either the version number or the label that you specified in the
Name input field.

View Labels for a Parameter

You can use the GetParameterHistory API action to view the full history and all labels attached to a
specified parameter. Or, you can use the GetParametersByPath API action to view a list of all parameters
that are assigned a specific label.

To view labels for a parameter by using the GetParameterHistory API action

1. Run the following command to view a list of parameters for which you can view labels.
Note
Parameters are only available in the Region where they were created. If you don't see a
parameter for which you want to move a label, then verify your Region.

aws ssm describe-parameters

859
 AWS Systems Manager User Guide
Working with Parameters

Note the name of a parameter for which you want to move a label.
2. Run the following command to view all versions of the parameter.

aws ssm get-parameter-history --name parameter_name --with-decryption

The system returns information like the following:

{
"Parameters": [
{
"Name": "/Config/endpoint",
"LastModifiedDate": 1528932105.382,
"Labels": [
"Deprecated"
],
"Value": "MyTestService-June-Release.example.com",
"Version": 1,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Type": "String"
},
{
"Name": "/Config/endpoint",
"LastModifiedDate": 1528932111.222,
"Labels": [
"Current"
],
"Value": "MyTestService-July-Release.example.com",
"Version": 2,
"LastModifiedUser": "arn:aws:iam::123456789012:user/test",
"Type": "String"
}
]
}

View a List of Parameters that are Assigned a Label

You can use the GetParametersByPath API action to view a list of all parameters in a path that are
assigned a specific label.

Run the following command to view a list of parameters in a path that are assigned a specific label.

aws ssm get-parameters-by-path --path parameter_path --parameter-filters

Key=Label,Values=label_name,Option=Equals --max-results a_number --with-decryption --
recursive

The system returns information like the following. For this example, the user searched under the /Config
path:

{
"Parameters": [
{
"Version": 3,
"Type": "SecureString",
"Name": "/Config/DBpwd",
"Value": "MyS@perGr&pass33"
},
{
"Version": 2,

860
 AWS Systems Manager User Guide
Working with Public Parameters

"Type": "String",
"Name": "/Config/DBusername",
"Value": "TestUserDB"
},
{
"Version": 2,
"Type": "String",
"Name": "/Config/endpoint",
"Value": "MyTestService-July-Release.example.com"
}
]
}

Move a Parameter Label

You can't delete a parameter label after you create it. You can, however, move a label between versions
of a parameter. The following procedure describes how to move a parameter label to a different version
of the same parameter.

To move a parameter label

1. Run the following command to view all versions of the parameter.

aws ssm get-parameter-history --name "the_parameter_name"

Note the parameter version for which you want to attach a label.
2. Run the following command to assign an existing label to a different version of a parameter.

aws ssm label-parameter-version --name parameter_name --parameter-

version version_number --labels name_of_existing_label

Note
If you want to move an existing label to the latest version of a parameter, then remove --
parameter-version from the command.

Working with Public Parameters

Some AWS services publish information about common artifacts as Systems Manager public parameters.
For example, the Amazon Elastic Compute Cloud (Amazon EC2) service publishes information about
Amazon Machines Images (AMIs) as public parameters. You can call this information from your scripts
and code by using the GetParametersByPath, GetParameter, and GetParameters API actions.

This topic describes how to call public parameters by using the AWS CLI.

Contents
• Calling AMI Public Parameters (p. 861)
• Calling the ECS Optimized AMI Public Parameter (p. 863)
• Calling AWS Service, Region, and Endpoint Public Parameters (p. 864)

Calling AMI Public Parameters

Amazon EC2 AMI public parameters are available from the following paths:

• /aws/service/ami-amazon-linux-latest

861
 AWS Systems Manager User Guide
Working with Public Parameters

• /aws/service/ami-windows-latest

You can view a list of all Linux AMIs in the current AWS Region by using the following command in the
AWS CLI.

aws ssm get-parameters-by-path --path /aws/service/ami-amazon-linux-latest --query

Parameters[].Name

The command returns information like the following.

[
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-pv-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn-ami-pv-x86_64-s3",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-arm64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-arm64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-pv-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn-ami-pv-x86_64-ebs",
"/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-x86_64-ebs"
]

You can view details about these AMIs, including the AMI IDs and Amazon Resource Names (ARNs), by
using the following command.

aws ssm get-parameters-by-path --path "/aws/service/ami-amazon-linux-latest" --

region Region

The command returns information like the following. This example output has been truncated for space.

{
"Parameters": [
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-ebs",
"Type": "String",
"Value": "ami-0d75cc1d706735521",
"Version": 7,
"LastModifiedDate": 1543873943.358,
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/
amzn-ami-hvm-x86_64-ebs"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2",
"Type": "String",
"Value": "ami-0cd3dfa4e37921605",
"Version": 7,
"LastModifiedDate": 1543873943.47,
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/
amzn-ami-hvm-x86_64-gp2"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-s3",
"Type": "String",
"Value": "ami-0a0e3ff8af8d19497",
"Version": 7,

862
 AWS Systems Manager User Guide
Working with Public Parameters

"LastModifiedDate": 1543873943.576,
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/
amzn-ami-hvm-x86_64-s3"
},
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-ebs",
"Type": "String",
"Value": "ami-0786a9626196d6dac",
"Version": 7,
"LastModifiedDate": 1543873943.682,
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ami-amazon-linux-latest/
amzn-ami-minimal-hvm-x86_64-ebs"
},

You can view details of a specific AMI by using the GetParameters API action with the full AMI name,
including the path. Here is an example command.

aws ssm get-parameters --names /aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-

gp2 --region us-west-2

The command returns the following information.

{
"Parameters": [
{
"Name": "/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2",
"Type": "String",
"Value": "ami-061392db613a6357b",
"Version": 16,
"LastModifiedDate": 1552519670.776,
"ARN": "arn:aws:ssm:us-west-2::parameter/aws/service/ami-amazon-linux-latest/
amzn2-ami-hvm-x86_64-gp2"
}
],
"InvalidParameters": []
}

Calling the ECS Optimized AMI Public Parameter

The Amazon Elastic Container Service (Amazon ECS) service publishes the name of the latest Amazon
ECS optimized AMI as a public parameter. Users are encouraged to use this AMI when creating a new
Amazon EC2 cluster for Amazon ECS because the optimized AMI includes bug fixes and feature updates.
Use the following command to view the name of the latest Amazon ECS optimized AMI.

aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux/recommended

The command returns information like the following.

{
"Parameters": [
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux/recommended",
"Type": "String",
"Value": "{\"schema_version\":1,\"image_name\":\"amzn-ami-2018.03.p-
amazon-ecs-optimized\",\"image_id\":\"ami-01a82c3fce2c3ba58\",\"os\":\"Amazon Linux\",
\"ecs_runtime_version\":\"Docker version 18.06.1-ce\",\"ecs_agent_version\":\"1.27.0\"}",
"Version": 22,
"LastModifiedDate": 1555434745.425,
"ARN": "arn:aws:ssm:us-west-2::parameter/aws/service/ecs/optimized-ami/amazon-
linux/recommended"

863
 AWS Systems Manager User Guide
Working with Public Parameters

}
],
"InvalidParameters": []
}

Calling AWS Service, Region, and Endpoint Public Parameters

You can call AWS service, Region, and endpoint public parameters by using the following path.

/aws/service/global-infrastructure

You can view a list of all active AWS Regions by using the following command in the AWS CLI.

aws ssm get-parameters-by-path --path /aws/service/global-infrastructure/regions --query

Parameters[].Name

The command returns information like the following.

"/aws/service/global-infrastructure/regions/ap-northeast-1"
"/aws/service/global-infrastructure/regions/eu-central-1"
"/aws/service/global-infrastructure/regions/eu-north-1"
"/aws/service/global-infrastructure/regions/eu-west-1"
"/aws/service/global-infrastructure/regions/eu-west-3"
"/aws/service/global-infrastructure/regions/sa-east-1"
"/aws/service/global-infrastructure/regions/us-east-2"
"/aws/service/global-infrastructure/regions/us-gov-east-1"
"/aws/service/global-infrastructure/regions/us-gov-west-1"
"/aws/service/global-infrastructure/regions/us-west-1"
"/aws/service/global-infrastructure/regions/ap-northeast-2"
"/aws/service/global-infrastructure/regions/ap-northeast-3"
"/aws/service/global-infrastructure/regions/ap-south-1"
"/aws/service/global-infrastructure/regions/ap-southeast-1"
"/aws/service/global-infrastructure/regions/ap-southeast-2"
"/aws/service/global-infrastructure/regions/ca-central-1"
"/aws/service/global-infrastructure/regions/cn-north-1"
"/aws/service/global-infrastructure/regions/cn-northwest-1"
"/aws/service/global-infrastructure/regions/eu-west-2"
"/aws/service/global-infrastructure/regions/us-west-2"
"/aws/service/global-infrastructure/regions/us-east-1"

You can view a complete list of all available AWS services and sort them into alphabetical order by using
the following command. This example output has been truncated for space.

aws ssm get-parameters-by-path --path /aws/service/global-infrastructure/services --query

Parameters[].Name | sort

The command returns information like the following.

"/aws/service/global-infrastructure/services/acm-pca",
"/aws/service/global-infrastructure/services/acm",
"/aws/service/global-infrastructure/services/alexaforbusiness",
"/aws/service/global-infrastructure/services/apigateway",
"/aws/service/global-infrastructure/services/application-autoscaling",
"/aws/service/global-infrastructure/services/appmesh",
"/aws/service/global-infrastructure/services/appstream",
"/aws/service/global-infrastructure/services/appsync",
"/aws/service/global-infrastructure/services/athena",
"/aws/service/global-infrastructure/services/autoscaling-plans",

864
 AWS Systems Manager User Guide
Working with Public Parameters

"/aws/service/global-infrastructure/services/autoscaling",
"/aws/service/global-infrastructure/services/backup",
"/aws/service/global-infrastructure/services/batch",
"/aws/service/global-infrastructure/services/budgets",
"/aws/service/global-infrastructure/services/ce",
"/aws/service/global-infrastructure/services/chime",
"/aws/service/global-infrastructure/services/cloud9",
"/aws/service/global-infrastructure/services/cloudformation",
"/aws/service/global-infrastructure/services/cloudfront",
"/aws/service/global-infrastructure/services/cloudhsm",
"/aws/service/global-infrastructure/services/cloudhsmv2",
"/aws/service/global-infrastructure/services/cloudsearch",
"/aws/service/global-infrastructure/services/cloudtrail",
"/aws/service/global-infrastructure/services/cloudwatch",
"/aws/service/global-infrastructure/services/codebuild",

You can view a list of Regions where a service is available. This example uses Systems Manager (ssm).

aws ssm get-parameters-by-path --path /aws/service/global-infrastructure/services/ssm/

regions --query Parameters[].Value

The command returns information like the following.

[
"ap-east-1",
"ap-northeast-2",
"ap-south-1",
"ca-central-1",
"cn-northwest-1",
"eu-west-2",
"sa-east-1",
"us-east-2",
"us-gov-east-1",
"us-west-2",
"ap-northeast-1",
"ap-southeast-1",
"ap-southeast-2",
"cn-north-1",
"eu-central-1",
"eu-north-1",
"eu-west-1",
"us-east-1",
"us-gov-west-1",
"us-west-1",
"eu-west-3"
]

You can view a regional endpoint for a service by using the following command.

aws ssm get-parameter --name /aws/service/global-infrastructure/regions/us-west-1/services/

ssm/endpoint --query Parameter.Value

The command returns information like the following.

"ssm.us-west-1.amazonaws.com"

Related Blog Posts

• Query for AWS Regions, Endpoints, and More Using AWS Systems Manager Parameter Store

865
 AWS Systems Manager User Guide
Increasing Parameter Store Throughput

• Query for the latest Amazon Linux AMI IDs using AWS Systems Manager Parameter Store
• Query for the Latest Windows AMI Using AWS Systems Manager Parameter Store

Increasing Parameter Store Throughput

Increasing Parameter Store throughput increases the maximum number of transactions per second (TPS)
that Parameter Store can process. Increased throughput enables you to operate Parameter Store at
higher volumes to support applications and workloads that need concurrent access to a large number of
parameters. You can increase the limit to 1,000 TPS on the Settings tab. Increasing the throughput limit
incurs a charge on your AWS account. For more information, see AWS Systems Manager Pricing.
Note
The Parameter Store throughput setting applies to all transactions created by all AWS Identity
and Access Management (IAM) users in the current AWS account and Region. The throughput
setting applies to standard and advanced parameters.

Configuring Permissions to Increase Parameter Store

Throughput
Verify that you have permission in AWS Identity and Access Management (IAM) to increase Parameter
Store throughput by doing one of the following:

• Ensure that the AdministratorAccess policy is attached to your IAM user, group, or role.
• Ensure that you have permission to change the throughput service setting by using the following API
actions:
• GetServiceSetting
• UpdateServiceSetting
• ResetServiceSetting

Use the following procedure to add an inline IAM policy to a user account. This policy enables a user to
view and change the parameter-throughput setting for parameters in their account and Region.

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users.
3. In the list, choose the name of the user to attach a policy to.
4. Choose the Permissions tab.
5. On the right side of the page, under Permission policies, choose Add inline policy.
6. Choose the JSON tab.
7. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{

866
 AWS Systems Manager User Guide
Increasing Parameter Store Throughput

"Effect": "Allow",
"Action": [
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:AWS_Region:AWS_account_ID:servicesetting/ssm/
parameter-store/high-throughput-enabled"
}
]
}

8. Choose Review policy.

9. On the Review policy page, for Name, enter a name for the inline policy, such as Parameter-
Store-Throughput or another name you prefer.
10. Choose Create policy.

Administrators can specify read-only permission by assigning the following inline policy to the user's
account.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "*"
}
]
}

For more information about creating and editing IAM policies, see Creating IAM Policies in the IAM User
Guide.

Increasing Throughput (Console)

The following procedure shows how to use the Systems Manager console to increase the number of
transactions per second that Parameter Store can process for the current AWS account and Region.

To increase Parameter Store throughput

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the Settings tab.
4. Choose Set limit.

867
 AWS Systems Manager User Guide
Increasing Parameter Store Throughput

5. Review the message, and choose Accept.

If you no longer need increased throughput, or if you no longer want to incur charges, you can revert to
the standard settings. To revert your settings, repeat this procedure and choose Reset limit.

Increasing Throughput (AWS CLI)

The following procedure shows how to use the AWS Command Line Interface (AWS CLI) to increase the
number of transactions per second that Parameter Store can process for the current AWS account and
Region.

To increase Parameter Store throughput using the AWS CLI

1. Open the AWS CLI and run the following command to increase the transactions per second that
Parameter Store can process in the current AWS account and Region.

aws ssm update-service-setting --setting-id arn:aws:ssm:us-

east-1:123456789012:servicesetting/ssm/parameter-store/high-throughput-enabled --
setting-value true

There is no output if the command succeeds.

2. Run the following command to view the current throughput service settings for Parameter Store in
the current AWS account and Region.

aws ssm get-service-setting --setting-id arn:aws:ssm:us-

east-1:123456789012:servicesetting/ssm/parameter-store/high-throughput-enabled

{
"ServiceSetting": {
"SettingId": "/ssm/parameter-store/high-throughput-enabled",
"SettingValue": "true",
"LastModifiedDate": 1556551683.923,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/
Jasper",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/
high-throughput-enabled",
"Status": "Customized"
}
}

If you no longer need increased throughput, or if you no longer want to incur charges, you can revert to
the standard settings. To revert your settings, run the following command.

aws ssm reset-service-setting --setting-id arn:aws:ssm:us-

east-1:123456789012:servicesetting/ssm/parameter-store/high-throughput-enabled

{
"ServiceSetting": {
"SettingId": "/ssm/parameter-store/high-throughput-enabled",
"SettingValue": "false",
"LastModifiedDate": 1555532818.578,
"LastModifiedUser": "System",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/high-
throughput-enabled",
"Status": "Default"
}

868
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

Increasing Throughput (PowerShell)

The following procedure shows how to use the AWS Tools for Windows PowerShell to increase the
number of transactions per second that Parameter Store can process for the current AWS account and
Region.

To increase Parameter Store throughput using PowerShell

1. Increase Parameter Store throughput in the current AWS account and Region using the AWS Tools
for PowerShell.

Update-SSMServiceSetting -SettingId "arn:aws:ssm:us-east-1:123456789012:servicesetting/

ssm/parameter-store/high-throughput-enabled" -SettingValue "true" -Region us-east-1

There is no output if the command succeeds.

2. Run the following command to view the current throughput service settings for Parameter Store in
the current AWS account and Region.

Get-SSMServiceSetting -SettingId "arn:aws:ssm:us-east-2:123456789012:servicesetting/

ssm/parameter-store/high-throughput-enabled" -Region us-east-2

ARN : arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-
store/high-throughput-enabled
LastModifiedDate : 4/29/2019 3:35:44 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/Jasper
SettingId : /ssm/parameter-store/high-throughput-enabled
SettingValue : true
Status : Customized

If you no longer need increased throughput, or if you no longer want to incur charges, you can revert to
the standard settings. To revert your settings, run the following command.

Reset-SSMServiceSetting -SettingId "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/

parameter-store/high-throughput-enabled" -Region us-east-2

ARN : arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/
high-throughput-enabled
LastModifiedDate : 4/17/2019 8:26:58 PM
LastModifiedUser : System
SettingId : /ssm/parameter-store/high-throughput-enabled
SettingValue : false
Status : Default

Specifying a Default Parameter Tier

In requests to create or update a parameter (that is, the PutParameter action), you can specify the
parameter tier to use in the request. The following is an example, using the AWS CLI.

aws ssm put-parameter \

--name "default-ami" \
--type "String" \
--value "t2.micro" \

869
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

--tier "Standard"

Whenever you specify a tier in the request, Parameter Store creates or updates the parameter according
to your request. However, if you do not explicitly specify a tier in a request, the Parameter Store default
tier setting determines which tier the parameter is created in.

The default tier when you begin using Parameter Store is the standard-parameter tier. If you use the
advanced-parameter tier, you can specify one of the following as the default:

• Advanced: With this option, Parameter Store evaluates all requests as advanced parameters.
• Intelligent-Tiering: With this option, Parameter Store evaluates each request to determine if the
parameter is standard or advanced.

If the request doesn't include any options that require an advanced parameter, the parameter is
created in the standard-parameter tier. If one or more options requiring an advanced parameter are
included in the request, Parameter Store create a parameter in the advanced-parameter tier.

Benefits of Intelligent-Tiering

The following are reasons you might choose Intelligent-Tiering as the default tier.

Cost control – Intelligent-Tiering helps control your parameter-related costs by always creating standard
parameters unless an advanced parameter is absolutely necessary.

Automatic upgrade to the advanced-parameter tier – When you make a change to your code that
requires upgrading a standard parameter to an advanced parameter, Intelligent-Tiering handles the
conversion for you. You do not need to change your code to handle the upgrade.

Here are some examples of automatic upgrade:

• Your AWS CloudFormation templates provision numerous parameters when they are run. When this
process causes you to reach the 10,000 parameter limit in the standard-parameter tier, Intelligent-
Tiering automatically upgrades you to the advanced-parameter tier, and your AWS CloudFormation
processes are not interrupted.
• You store a certificate value in a parameter, rotate the certificate value regularly, and the content is
less than the 4 KB limit of the standard-parameter tier. If a replacement certificate value exceeds 4 KB,
Intelligent-Tiering automatically upgrades the parameter to the advanced-parameter tier.
• You want to associate numerous existing standard parameters to a parameter policy, which requires
the advanced-parameter tier. Instead of your having to include the option --tier Advanced in all
of the calls to update the parameters, Intelligent-Tiering automatically upgrades the parameters to
the advanced-parameter tier. The Intelligent-Tiering option upgrades parameters from standard to
advanced whenever criteria for the advanced-parameter tier are introduced.

Options that require an advanced parameter include the following:

• The content size of the parameter is more than 4 KB.

• The parameter uses a parameter policy.
• More than 10,000 parameters already exist in your AWS account in the current Region.

Default Tier Options

The tier options you can specify as the default include the following.

• Standard – The standard-parameter tier is the default tier when you begin to use Parameter Store.
Using the standard-parameter tier, you can create 10,000 parameters for each Region in an AWS
account. The content size of each parameter can equal a maximum of 4 KB. Standard parameters

870
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

do not support parameter policies. There is no additional charge to use the standard-parameter
tier. Choosing Standard as the default tier means that Parameter Store always attempts to create a
standard parameter for requests that don't specify a tier.
• Advanced – The advanced-parameter tier lets you create a maximum of 100,000 parameters for
each Region in an AWS account. The content size of each parameter can equal a maximum of 8 KB.
Advanced parameters support parameter policies. There is a charge to use the advanced-parameter
tier. For more information, see AWS Systems Manager Pricing. Choosing Advanced as the default tier
means that Parameter Store always attempts to create an advanced parameter for requests that don't
specify a tier.
Note
When you choose the advanced-parameter tier, you must explicitly authorize AWS to charge
your account for any advanced parameters you create.
• Intelligent-Tiering – The Intelligent-Tiering option lets Parameter Store determine whether to use the
standard-parameter tier or advanced-parameter tier based on the content of the request. For example,
if you run a command to create a parameter with content under 4 KB, and there are fewer than 10,000
parameters in the current Region in your AWS account, and you do not specify a parameter policy, a
standard parameter is created. If you run a command to create a parameter with more than 4 KB of
content, you already have more than 10,000 parameters in the current Region in your AWS account, or
you specify a parameter policy, an advanced parameter is created.
Note
When you choose Intelligent-Tiering, you must explicitly authorize AWS to charge your
account for any advanced parameters that are created.

You can change the Parameter Store default tier setting at any time.

Configuring Permissions to Specify a Parameter Store Default

Tier
Verify that you have permission in AWS Identity and Access Management (IAM) to change the default
parameter tier in Parameter Store by doing one of the following:

• Ensure that the AdministratorAccess policy is attached to your IAM user, group, or role.
• Ensure that you have permission to change the default tier setting by using the following API actions:
• GetServiceSetting
• UpdateServiceSetting
• ResetServiceSetting

Use the following procedure to add an inline IAM policy to a user account. This policy enables a user to
view and change the default tier setting for parameters in a specifc Region in an AWS account.

1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users.
3. In the list, choose the name of the user to attach a policy to.
4. Choose the Permissions tab.
5. On the right side of the page, under Permission policies, choose Add inline policy.
6. Choose the JSON tab.
7. Replace the default content with the following:

{
"Version": "2012-10-17",

871
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:AWS_Region:AWS_account_ID:servicesetting/ssm/
parameter-store/default-parameter-tier"
}
]
}

8. Choose Review policy.

9. On the Review policy page, for Name, enter a name for the inline policy, such as Parameter-
Store-Default-Tier or another name you prefer.
10. Choose Create policy.

Administrators can specify read-only permission by assigning the following inline policy to the user's
account.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "*"
}
]
}

For more information about creating and editing IAM policies, see Creating IAM Policies in the IAM User
Guide.

Specifying or Changing the Parameter Store Default Tier

(Console)
The following procedure shows how to use the Systems Manager console to specify or change the
default parameter tier for the current AWS account and Region.

To specify or change the Parameter Store default tier

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

872
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

2. In the navigation pane, choose Parameter Store.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Parameter Store.
3. Choose the Settings tab.
4. Choose Set default.
5. Choose one of the following options.

• Standard
• Advanced
• Intelligent-Tiering

For information about these options, see Specifying a Default Parameter Tier (p. 869).
6. Review the message, and choose Confirm.

If you want to change the default tier setting later, repeat this procedure and specify a different default
tier option.

Specifying or Changing the Parameter Store Default Tier (AWS

CLI)
The following procedure shows how to use the AWS Command Line Interface (AWS CLI) to change the
default parameter tier setting for the current AWS account and Region.

To specify or change the Parameter Store default tier using the AWS CLI

1. Open the AWS CLI and run the following command to change the default parameter tier setting for
a specific Region in an AWS account.

aws ssm update-service-setting --setting-id arn:aws:ssm:region:account-

id:servicesetting/ssm/parameter-store/default-parameter-tier --setting-value tier-
option

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

tier-option values include Standard, Advanced, and Intelligent-Tiering. For information

about these options, see Specifying a Default Parameter Tier (p. 869).

There is no output if the command succeeds.

2. Run the following command to view the current throughput service settings for Parameter Store in
the current AWS account and Region.

aws ssm get-service-setting --setting-id arn:aws:ssm:region:account-ID:servicesetting/

ssm/parameter-store/default-parameter-tier

The system returns information similar to the following:

873
 AWS Systems Manager User Guide
Specifying a Default Parameter Tier

"ServiceSetting": {
"SettingId": "/ssm/parameter-store/default-parameter-tier",
"SettingValue": "Advanced",
"LastModifiedDate": 1556551683.923,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/
Jasper",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-store/
default-parameter-tier",
"Status": "Customized"
}
}

If you want to change the default tier setting again, repeat this procedure and specify a different
SettingValue option.

Specifying or Changing the Parameter Store Default Tier

(PowerShell)
The following procedure shows how to use the AWS Tools for Windows PowerShell to change the default
parameter tier setting for a specific Region in an AWS account.

To specify or change the Parameter Store default tier using PowerShell

1. Change the Parameter Store default tier in the current AWS account and Region using the AWS Tools
for PowerShell.

Update-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/

parameter-store/default-parameter-tier" -SettingValue "tier-option" -Region region

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

tier-option values include Standard, Advanced, and Intelligent-Tiering. For information

about these options, see Specifying a Default Parameter Tier (p. 869).

There is no output if the command succeeds.

2. Run the following command to view the current throughput service settings for Parameter Store in
the current AWS account and Region.

Get-SSMServiceSetting -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/

parameter-store/default-parameter-tier" -Region region

region represents the Region identifier for an AWS Region supported by AWS Systems Manager,
such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the
Region column in the AWS Systems Manager Table of Regions and Endpoints in the AWS General
Reference.

The system returns information similar to the following:

ARN : arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/parameter-
store/default-parameter-tier
LastModifiedDate : 4/29/2019 3:35:44 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/Jasper
SettingId : /ssm/parameter-store/default-parameter-tier

874
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

SettingValue : Advanced
Status : Customized

If you want to change the default tier setting again, repeat this procedure and specify a different
SettingValue option.

Parameter Store Walkthroughs

The walkthroughs in this section show you how to create, store, and run parameters with Parameter
Store in a test environment. These walkthroughs show you how to use Parameter Store with other
Systems Manager capabilities. You can also use Parameter Store with other AWS services. For more
information, see Using Secure String Parameters With Other AWS Services (p. 830).

Contents
• Walkthrough: Create and Use a Parameter in a Command (Console) (p. 875)
• Walkthrough: Create and Use a Parameter in a Command (AWS CLI) (p. 876)
• Walkthrough: Create a Secure String Parameter and Join an Instance to a Domain
(PowerShell) (p. 878)
• Walkthrough: Manage Parameters Using Hierarchies (AWS CLI) (p. 880)

Walkthrough: Create and Use a Parameter in a Command

(Console)
The following procedure walks you through the process of creating a parameter in Parameter Store and
then running a command that uses this parameter.

To create a parameter using Parameter Store

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Parameter Store.
3. Choose Create parameter.
4. In the Name box, enter a hierarchy and a name. For example, enter /Test/helloWorld.

For more information about parameter hierarchies, see Organizing Parameters into
Hierarchies (p. 839).
5. In the Description field, enter a description that identifies this parameter as a test parameter.
6. For Type, choose String.
7. In the Value field, enter a string. For example, enter My1stParameter.
8. Choose Create parameter.
9. In the navigation pane, choose Run Command.
10. Choose Run command.
11. In the Command document list, choose AWS-RunPowershellScript (Windows) or AWS-
RunShellScript (Linux).
12. Under Target instances, choose a managed instance in your account.
13. In the Commands field, enter echo {{ssm:parameter-name}}, for example, echo {{ssm:/
Test/helloWorld}}.
14. Choose Run.

875
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

15. Scroll to the bottom of the Command ID page, select the button next to an instance ID, and then
choose View output.

Walkthrough: Create and Use a Parameter in a Command (AWS

CLI)
The following procedure walks you through the process of creating and storing a parameter using the
AWS CLI.

To create and use a parameter in a command (AWS CLI)

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create a parameter that uses the String data type. The --name
option supports hierarchies. For information about hierarchies, see Organizing Parameters into
Hierarchies (p. 839).

aws ssm put-parameter --name "parameter_name" --value "a parameter value" --type String

Here is an example that uses a parameter hierarchy in the name. For more information about
parameter hierarchies, see Organizing Parameters into Hierarchies (p. 839).

aws ssm put-parameter --name "/Test/IAD/helloWorld" --value "My1stParameter" --type

String

The command returns the version number of the parameter.

3. Run the following command to view the parameter metadata.

aws ssm describe-parameters --filters "Key=Name,Values=/Test/IAD/helloWorld"

Note
Name must be capitalized.

The system returns information like the following.

{
"Parameters": [
{
"LastModifiedUser": "arn:aws:iam::123456789012:user/User's name",
"LastModifiedDate": 1494529763.156,
"Type": "String",
"Name": "helloworld"
}
]
}

4. Run the following command to change the parameter value.

aws ssm put-parameter --name "/Test/IAD/helloWorld" --value "good day sunshine" --type
String --overwrite

The command returns the version number of the parameter.

5. Run the following command to view the latest parameter value.

876
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

aws ssm get-parameters --names "/Test/IAD/helloWorld"

The system returns information like the following.

{
"InvalidParameters": [],
"Parameters": [
{
"Type": "String",
"Name": "/Test/IAD/helloWorld",
"Value": "good day sunshine"
}
]
}

6. Run the following command to view the parameter value history.

aws ssm get-parameter-history --name "/Test/IAD/helloWorld"

7. Run the following command to use this parameter in a command.

aws ssm send-command --document-name "AWS-RunShellScript" --parameters '{"commands":

["echo {{ssm:/Test/IAD/helloWorld}}"]}' --targets "Key=instanceids,Values=instance-ids"

Use the following procedure to create a secure string parameter. For more information about secure
string parameters, see About Secure String Parameters (p. 829).

To create a secure string parameter using the AWS CLI

1. Run one of the following commands to create a parameter that uses the SecureString datatype.

Create a secure string parameter that uses a customer managed customer master key (CMK)

aws ssm put-parameter --name "parameter_name" --value "a value, for example P@ssW%rd#1"
--type "SecureString"

Create a secure string parameter that uses a custom AWS KMS key

aws ssm put-parameter --name "parameter_name" --value "a parameter value" --type
"SecureString" --key-id "your-AWS-user-account ID/the-custom-AWS KMS-key"

Here is an example that uses a customer managed CMK.

aws ssm put-parameter --name "my-password" --value "P@ssW%rd#1" --type "SecureString"

--key-id "arn:aws:kms:us-east-2:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e"

2. Run the following command to view the parameter metadata.

aws ssm describe-parameters --filters "Key=Name,Values=the_name_that_you_specified"

3. Run the following command to change the parameter value.

aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter

value" --type "SecureString" --overwrite

877
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

Updating a secure string parameter that uses a customer managed customer master key (CMK)

aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter

value" --type "SecureString" --key-id "the-CMK-ID" --overwrite

Updating a secure string parameter that uses a customer managed CMK

aws ssm put-parameter --name "the_name_that_you_specified" --value "new parameter

value" --type "SecureString" --key-id "your-AWS-user-account-alias/the-CMK-ID" --
overwrite

4. Run the following command to view the latest parameter value.

aws ssm get-parameters --names "the_name_that_you_specified" --with-decryption

5. Run the following command to view the parameter value history.

aws ssm get-parameter-history --name "the_name_that_you_specified"

Important
Only the value of a secure string parameter is encrypted. Parameter names, descriptions, and
other properties are not encrypted.

Walkthrough: Create a Secure String Parameter and Join an

Instance to a Domain (PowerShell)
This walkthrough shows how to join a Windows instance to a domain using Systems Manager secure
string parameters and Run Command. The walkthrough uses typical domain parameters, such as the
domain name and a domain user name. These values are passed as unencrypted string values. The
domain password is encrypted using an AWS-managed customer master key (CMK) and passed as a
secure string.

Prerequisites

This walkthrough assumes that you already specified your domain name and DNS server IP address in
the DHCP option set that is associated with your Amazon VPC. For information, see Working with DHCP
Options Sets in the Amazon VPC User Guide.

To create a secure string parameter and join an instance to a domain

1. Enter parameters into the system using AWS Tools for Windows PowerShell.

Write-SSMParameter -Name "domainName" -Value "DOMAIN-NAME" -Type String

Write-SSMParameter -Name "domainJoinUserName" -Value "DOMAIN\USERNAME" -Type String
Write-SSMParameter -Name "domainJoinPassword" -Value "PASSWORD" -Type SecureString

Important
Only the value of a secure string parameter is encrypted. Parameter names, descriptions,
and other properties are not encrypted.
2. Attach the following IAM policies to the IAM role permissions for your instance:

• AmazonSSMManagedInstanceCore – Required. This AWS managed policy enables a managed

instance to use Systems Manager service core functionality.

878
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

• AmazonSSMDirectoryServiceAccess – Required. This AWS managed policy allows SSM Agent

to access AWS Directory Service on your behalf for requests to join the domain by the managed
instance.
• A custom policy for Amazon S3 bucket access – Required. SSM Agent, which is on your instance
and performs Systems Manager tasks, requires access to specific Amazon-owned S3 buckets. In
the custom S3 bucket policy that you create, you also provide access to S3 buckets of your own
that are necessary for Systems Manager operations.

Examples: You can write output for Run Command commands or Session Manager sessions to an
S3 bucket, and then use this output later for auditing or troubleshooting. You store access scripts
or custom patch baseline lists in an S3 bucket, and then reference the script or list when you run a
command, or when a patch baseline is applied.

For information about creating a custom policy for Amazon S3 bucket access, see Create a Custom
S3 Bucket Policy for an Instance Profile (p. 30)
Note
Saving output log data in an S3 bucket is optional, but we recommend setting it up at the
beginning of your Systems Manager configuration process if you have decided to use it.
For more information, see Create a Bucket in the Amazon Simple Storage Service Getting
Started Guide.
• CloudWatchAgentServerPolicy – Optional. This AWS managed policy allows you to run the
CloudWatch agent on managed instances. This policy makes it possible to read information on an
instance and write it to Amazon CloudWatch. Your instance profile needs this policy only if you
will use CloudWatch features, such as CloudWatch Events or CloudWatch Logs.
Note
Using CloudWatch features is optional, but we recommend setting them up at the
beginning of your Systems Manager configuration process if you have decided to use
them. For more information, see the Amazon CloudWatch Events User Guide and the
Amazon CloudWatch Logs User Guide.
3. Edit the IAM role attached to the instance and add the following policy. This policy gives the
instance permissions to call the kms:Decrypt API.

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"kms:Decrypt"
],
"Resource":[
"arn:aws:kms:region:account-id:key/key-id"
]
}
]
}

4. Copy and paste the following json sample into a simple text editor and save
the file as JoinInstanceToDomain.json in the following location: c:\temp
\JoinInstanceToDomain.json.

{
"schemaVersion": "2.2",
"description": "Run a PowerShell script to securely domain-join a Windows
instance",
"mainSteps": [
{

879
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

"action": "aws:runPowerShellScript",
"name": "runPowerShellWithSecureString",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"$domain = (Get-SSMParameterValue -Name
domainName).Parameters[0].Value",
"$username = (Get-SSMParameterValue -Name
domainJoinUserName).Parameters[0].Value",
"$password = (Get-SSMParameterValue -Name domainJoinPassword -
WithDecryption $True).Parameters[0].Value | ConvertTo-SecureString -asPlainText -
Force",
"$credential = New-Object
System.Management.Automation.PSCredential($username,$password)",
"Add-Computer -DomainName $domain -Credential $credential -
ErrorAction Stop",
"Restart-Computer -force"
]
}
}
]
}

5. Run the following command in AWS Tools for Windows PowerShell to create a new SSM document.

$json = Get-Content C:\temp\JoinInstanceToDomain | Out-String

New-SSMDocument -Name JoinInstanceToDomain -Content $json -DocumentType Command

6. Run the following command in AWS Tools for Windows PowerShell to join the instance to the
domain

Send-SSMCommand -InstanceId instance-id -DocumentName JoinInstanceToDomain

Walkthrough: Manage Parameters Using Hierarchies (AWS CLI)

This walkthrough shows how to work with parameters and parameter hierarchies by using the AWS CLI.
For more information about parameter hierarchies, see Organizing Parameters into Hierarchies (p. 839).

To manage parameters using hierarchies

1. Install and configure the AWS CLI, if you have not already.

For information, see Install or Upgrade the AWS CLI (p. 58).
2. Run the following command to create a parameter that uses the allowedPattern parameter and
the String data type. The allowed pattern in this example means the value for the parameter must
be between 1 and 4 digits long.

aws ssm put-parameter --name "/MyService/Test/MaxConnections" --value 100 --allowed-

pattern "\d{1,4}" --type String

The command returns the version number of the parameter.

3. Run the following command to attempt to overwrite the parameter you just created with a new
value.

880
 AWS Systems Manager User Guide
Parameter Store Walkthroughs

aws ssm put-parameter --name "/MyService/Test/MaxConnections" --value 10,000 --type

String --overwrite

The system throws the following error because the new value does not meet the requirements of
the allowed pattern you specified in the previous step.

An error occurred (ParameterPatternMismatchException) when calling

the PutParameter operation: Parameter value, cannot be
validated against
allowedPattern: \d{1,4}

4. Run the following command to create a secure string parameter that uses an AWS-managed
customer master key (CMK). The allowed pattern in this example means the user can specify any
character, and the value must be between 8 and 20 characters.

aws ssm put-parameter --name "/MyService/Test/my-password" --value "p#sW*rd33" --

allowed-pattern ".{8,20}" --type SecureString

5. Run the following commands to create more parameters that use the hierarchy structure from the
previous step.

aws ssm put-parameter --name "/MyService/Test/DBname" --value "SQLDevDb" --type String

aws ssm put-parameter --name "/MyService/Test/user" --value "SA" --type String

aws ssm put-parameter --name "/MyService/Test/userType" --value "SQLuser" --type String

6. Run the following command to get the value of two parameters.

aws ssm get-parameters --names "/MyService/Test/user" "/MyService/Test/userType"

7. Run the following command to query for all parameters within a single level.

aws ssm get-parameters-by-path --path "/MyService/Test"

8. Run the following command to delete two parameters

aws ssm delete-parameters --names "/IADRegion/Dev/user" "/IADRegion/Dev/userType"

881
 AWS Systems Manager User Guide
Sending Logs to CloudWatch Logs (SSM Agent)

Monitoring AWS Systems Manager

SSM Agent writes information about executions, scheduled actions, errors, and health statuses to log
files on each instance. Manually connecting to an instance to view log files and troubleshoot an issue
with SSM Agent is time-consuming. For more efficient instance monitoring, you can configure either SSM
Agent itself or the CloudWatch agent to send this log data to Amazon CloudWatch Logs.
Important
The unified CloudWatch agent has replaced SSM Agent as the tool for sending log data to
Amazon CloudWatch Logs. Support for using SSM Agent to send log data will be deprecated in
the near future. We recommend using only the unified CloudWatch agent for your log collection
processes. For more information, see the following topics:

• Sending Logs to CloudWatch Logs (CloudWatch agent) (p. 884)

• Migrate Windows Server Instance Log Collection to the CloudWatch agent (p. 884)
• Collect Metrics from Amazon Elastic Compute Cloud Instances and On-Premises Servers with
the CloudWatch agent in the Amazon CloudWatch User Guide

Using CloudWatch Logs, you can monitor log data in real-time, search and filter log data by creating one
or more metric filters, and archive and retrieve historical data when you need it. For more information
about CloudWatch Logs, see the Amazon CloudWatch Logs User Guide.

Configuring an agent to send log data to Amazon CloudWatch Logs provides the following benefits:

• Centralized log file storage for all of your SSM Agent log files.
• Quicker access to files to investigate errors.
• Indefinite log file retention (configurable).
• Logs can be maintained and accessed regardless of the status of the instance.
• Access to other CloudWatch features such as metrics and alarms.

For information about monitoring Session Manager activity, see Auditing and Logging Session
Activity (p. 608).

Topics
• Sending Logs to CloudWatch Logs (SSM Agent) (p. 882)
• Sending Logs to CloudWatch Logs (CloudWatch agent) (p. 884)
• Logging AWS Systems Manager API Calls with AWS CloudTrail (p. 889)
• Monitoring Systems Manager Events with Amazon CloudWatch Events (p. 891)
• Configuring Amazon SNS Notifications for AWS Systems Manager (p. 893)

Sending Logs to CloudWatch Logs (SSM Agent)

AWS Systems Manager Agent (SSM Agent) is Amazon software that runs on your Amazon EC2 instances
and your hybrid instances that are configured for Systems Manager (hybrid instances). SSM Agent
processes requests from the Systems Manager service in the cloud and configures your machine as
specified in the request. For more information about SSM Agent, see Working with SSM Agent (p. 64).

In addition, following the steps below, you can configure SSM Agent to send log data to Amazon
CloudWatch Logs.

882
 AWS Systems Manager User Guide
Sending Logs to CloudWatch Logs (SSM Agent)

Important
The unified CloudWatch agent has replaced SSM Agent as the tool for sending log data to
Amazon CloudWatch Logs. Support for using SSM Agent to send log data will be deprecated in
the near future. We recommend using only the unified CloudWatch agent for your log collection
processes. For more information, see the following topics:

• Sending Logs to CloudWatch Logs (CloudWatch agent) (p. 884)

• Migrate Windows Server Instance Log Collection to the CloudWatch agent (p. 884)
• Collect Metrics from Amazon Elastic Compute Cloud Instances and On-Premises Servers with
the CloudWatch agent in the Amazon CloudWatch User Guide

Before You Begin

Create a log group in Amazon CloudWatch Logs. For more information, see Create a Log Group in
CloudWatch Logs in the Amazon CloudWatch Logs User Guide.

To configure SSM Agent to send logs to CloudWatch

1. Log into an instance and locate the following file:

On Windows: %PROGRAMFILES%\Amazon\SSM\seelog.xml.template

On Linux: /etc/amazon/ssm/seelog.xml.template
2. Change the file name from seelog.xml.template to seelog.xml.
3. Open the seelog.xml file in a text editor, and locate the following section:

<outputs formatid="fmtinfo">
<console formatid="fmtinfo"/>
<rollingfile type="size" maxrolls="5" maxsize="30000000"
filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\amazon-ssm-agent.log"/>
<filter formatid="fmterror" levels="error,critical">
<rollingfile type="size" maxrolls="5" maxsize="10000000"
filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\errors.log"/>
</filter>
</outputs>

4. Edit the file, and add the following custom name element after the closing </filter> tag, as shown in
the following example.

<seelog minlevel="info" critmsgcount="500" maxinterval="100000000"

mininterval="2000000" type="adaptive">
<exceptions>
<exception minlevel="error" filepattern="test*"/>
</exceptions>
<outputs formatid="fmtinfo">
<console formatid="fmtinfo"/>
<rollingfile type="size" maxrolls="5" maxsize="30000000"
filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\amazon-ssm-agent.log"/>
<filter formatid="fmterror" levels="error,critical">
<rollingfile type="size" maxrolls="5" maxsize="10000000"
filename="{{LOCALAPPDATA}}\Amazon\SSM\Logs\errors.log"/>
</filter>
<custom name="cloudwatch_receiver" formatid="fmtdebug" data-log-group="Your
CloudWatch Log Group Name"/>
</outputs>

5. Save your changes, and then restart SSM Agent or the instance.
6. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

883
 AWS Systems Manager User Guide
Sending Logs to CloudWatch Logs (CloudWatch agent)

7. Choose Logs, and then choose your log group. (The log stream for SSM Agent log file data is
organized by instance ID.)

Sending Logs to CloudWatch Logs (CloudWatch

agent)
You can configure and use the Amazon CloudWatch agent to collect metrics and logs from your instances
instead of using SSM Agent for these tasks. The CloudWatch agent enables you to gather more metrics
on Amazon EC2 instances than are available using SSM Agent. In addition, you can gather metrics from
on-premises servers using the CloudWatch agent.

You can also store agent configuration settings in the Systems Manager Parameter Store for use with the
CloudWatch agent.
Note
Currently, AWS Systems Manager supports migrating from SSM Agent to the CloudWatch agent
for collecting logs and metrics on 64-bit versions of Windows only. For information about
setting up the CloudWatch agent on other operating systems, and for complete information
about using the CloudWatch agent, see Collect Metrics from Amazon Elastic Compute Cloud
Instances and On-Premises Servers with the CloudWatch agent in the Amazon CloudWatch User
Guide.
You can use the CloudWatch agent on other supported operating systems, but you will not be
able to use Systems Manager to perform a tool migration.

Topics
• Migrate Windows Server Instance Log Collection to the CloudWatch agent (p. 884)
• Store CloudWatch agent Configuration Settings in Parameter Store (p. 888)
• Rolling Back to Log Collection with SSM Agent (p. 888)

Migrate Windows Server Instance Log Collection to

the CloudWatch agent
If you are currently using SSM Agent on supported Windows Server instances to send SSM Agent log
files to Amazon CloudWatch Logs, you can use Systems Manager to migrate from SSM Agent to the
CloudWatch agent as your log collection tool, as well as migrate your configuration settings.

The CloudWatch agent is not supported on 32-bit versions of Windows Server.

For 64-bit Amazon EC2 Windows instances, you can perform the migration to the CloudWatch agent
automatically or manually. For on-premises servers and virtual machines, the process must be performed
manually.
Note
During the migration process, the data sent to CloudWatch may be interrupted or duplicated.
Your metrics and log data will be recorded accurately again in CloudWatch after the migration is
completed.

We recommend testing the migration on a limited number of instances before migrating an entire fleet
to the CloudWatch agent. After migration, if you prefer log collection with SSM Agent, you can return to
using it instead.
Important
In the following cases, you won’t be able to migrate to the CloudWatch agent using the steps
described in this topic:

884
 AWS Systems Manager User Guide
Migrate Windows Server Instance Log
Collection to the CloudWatch agent

• The existing configuration for SSM Agent specifies multiple Regions.

• The existing configuration for SSM Agent specifies multiple sets of access/secret key
credentials.

In these cases, it will be necessary to disable log collection in SSM Agent and install the
CloudWatch agent without a migration process. For more information, see the following topics:

• Install the CloudWatch Agent on an Amazon EC2 Instance

• Install the CloudWatch Agent on an On-Premises Server

Before You Begin

Before you begin a migration to the CloudWatch agent for log collection, ensure that the instances on
which you will perform the migration meet these requirements:

• The OS is a 64-bit version of Windows Server.

• SSM Agent 2.2.93.0 or later is installed on the instance.
• SSM Agent is configured for monitoring on the instance.

Topics
• Automatically Migrating to the CloudWatch agent (p. 885)
• Manually Migrating to the CloudWatch agent (p. 886)

Automatically Migrating to the CloudWatch agent

For Amazon EC2 Windows instances only, you can use the AWS Systems Manager console or the AWS CLI
to automatically migrate to the CloudWatch agent as your log collection tool.
Note
Currently, AWS Systems Manager supports migrating from SSM Agent to the CloudWatch agent
for collecting logs and metrics on 64-bit versions of Windows only. For information about
setting up the CloudWatch agent on other operating systems, and for complete information
about using the CloudWatch agent, see Collect Metrics from Amazon Elastic Compute Cloud
Instances and On-Premises Servers with the CloudWatch agent in the Amazon CloudWatch User
Guide.
You can use the CloudWatch agent on other supported operating systems, but you will not be
able to use Systems Manager to perform a tool migration.

After the migration succeeds, check your results in CloudWatch to ensure you are receiving the metrics,
logs, or Windows event logs you expect. If you are satisfied with the results, you can optionally Store
CloudWatch agent Configuration Settings in Parameter Store (p. 888). If the migration is not successful
or the results are not as expected, you can Rolling Back to Log Collection with SSM Agent (p. 888).
Note
If you want to migrate a source configuration file that includes a {hostname} entry, then
be aware that the {hostname} entry can change the value of the field after the migration is
complete. For example, say that the following "LogStream": "{hostname}" entry maps to a
server named MyLogServer001.

{
"Id": "CloudWatchIISLogs",
"FullName":
"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch",
"Parameters": {

885
 AWS Systems Manager User Guide
Migrate Windows Server Instance Log
Collection to the CloudWatch agent

"AccessKey": "",
"SecretKey": "",
"Region": "us-east-1",
"LogGroup": "Production-Windows-IIS",
"LogStream": "{hostname}"
}
}

After the migration, this entry will map to a domain, such as

ip-11-1-1-11.production.ExampleCompany.com. To retain the local hostname value, specify
{local_hostname} instead of {hostname}.

To automatically migrate to the CloudWatch agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AmazonCloudWatch-MigrateCloudWatchAgent.
4. In the Targets section, choose an option and select the instances to update.
5. Choose Run.

To automatically migrate to the CloudWatch agent (AWS CLI)

• Run the following command:

aws ssm send-command --document-name AmazonCloudWatch-MigrateCloudWatchAgent --targets

Key=instanceids,Values=ID1,ID2,ID3

ID1, ID2, and ID3 represent the IDs of instances you want to update, such as i-02573cafcfEXAMPLE.

Manually Migrating to the CloudWatch agent

For on-premises Windows instances or Amazon EC2 Windows instances, follow these steps to manually
migrate log collection to the Amazon CloudWatch agent.
Note
If you want to migrate a source configuration file that includes a {hostname} entry, then
be aware that the {hostname} entry can change the value of the field after the migration is
complete. For example, say that the following "LogStream": "{hostname}" entry maps to a
server named MyLogServer001.

{
"Id": "CloudWatchIISLogs",
"FullName":
"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch",
"Parameters": {
"AccessKey": "",
"SecretKey": "",
"Region": "us-east-1",
"LogGroup": "Production-Windows-IIS",
"LogStream": "{hostname}"
}
}

After the migration, this entry will map to a domain, such as

ip-11-1-1-11.production.ExampleCompany.com. To retain the local hostname value, specify
{local_hostname} instead of {hostname}.

886
 AWS Systems Manager User Guide
Migrate Windows Server Instance Log
Collection to the CloudWatch agent

One: To install the CloudWatch Agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AWS-ConfigureAWSPackage.
4. In the Targets section, choose an option and select the instances to update.
5. In the Action list, choose Install.
6. In Name, type AmazonCloudWatchAgent.
7. In Version, type latest if it is not already provided by default.
8. Choose Run.

Two: To update config data JSON format

• To update the JSON formatting of the existing config settings for the CloudWatch agent, use AWS
Systems Manager Run Command or log into the instance directly with an RDP connection to run the
following Windows PowerShell commands on the instance, one at a time:

cd ${Env:ProgramFiles}\\Amazon\\AmazonCloudWatchAgent

.\\amazon-cloudwatch-agent-config-wizard.exe --isNonInteractiveWindowsMigration

{Env:ProgramFiles} represents the location where the Amazon folder containing the
CloudWatch agent can be found, typically C:\Program Files.

Three: To configure and start the CloudWatch Agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AWS-RunPowerShellScript.
4. In the Targets section, choose an option and select the instances to update.
5. In the Commands box, enter the following two commands:

cd ${Env:ProgramFiles}\Amazon\AmazonCloudWatchAgent

.\amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:config.json -s

{Env:ProgramFiles} represents the location where the Amazon folder containing the
CloudWatch agent can be found, typically C:\Program Files.
6. Choose Run.

Four: To disable log collection in SSM Agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AWS-ConfigurecloudWatch.
4. In the Targets section, choose an option and select the instances to update.
5. In the Status list, choose Disabled.
6. Choose Run.

887
 AWS Systems Manager User Guide
Store CloudWatch agent Configuration
Settings in Parameter Store

After completing these steps, check your logs in CloudWatch to ensure you are receiving the metrics,
logs, or Windows event logs you expect. If you are satisfied with the results, you can optionally
Store CloudWatch agent Configuration Settings in Parameter Store (p. 888). If the migration is
not successful or the results are not as expected, you can Rolling Back to Log Collection with SSM
Agent (p. 888).

Store CloudWatch agent Configuration Settings in

Parameter Store
You can store the contents of an Amazon CloudWatch agent configuration file in Parameter Store. By
maintaining this configuration data in a parameter, multiple instances can derive their configuration
settings from it, and you avoid having to create or manually update configuration files on your instances.
For example, you can use Run Command to write the contents of the parameter to configuration files
on multiple instances, or use State Manager to help avoid configuration drift in the CloudWatch agent
configuration settings across a fleet of instances.

When you run the CloudWatch agent configuration wizard, you can choose to let the wizard save your
configuration settings as a new parameter in Parameter Store. For information about running the
CloudWatch agent configuration wizard, see Create the CloudWatch agent Configuration File with the
Wizard.

If you ran the wizard but did not choose the option to save the settings as a parameter, or you created
the CloudWatch agent configuration file manually, you can retrieve the data to save as a parameter on
your instance in the following file:

${Env:ProgramFiles}\Amazon\AmazonCloudWatchAgent\config.json

{Env:ProgramFiles} represents the location where the Amazon folder containing the CloudWatch
agent can be found, typically C:\Program Files.

We recommend keeping a backup of the JSON in this file on a location other than the instance itself.

For information about creating a parameter, see Creating Systems Manager Parameters (p. 847).

For more information about the CloudWatch agent, see Collect Metrics from Amazon Elastic Compute
Cloud Instances and On-Premises Servers with the CloudWatch Agent in the Amazon CloudWatch User
Guide.

Rolling Back to Log Collection with SSM Agent

If you want to return to using SSM Agent for log collection, follow these steps.

One: To retrieve config data from SSM Agent

1. On the instance where you want to return to collecting logs with the SSM Agent, locate the contents
of the SSM Agent config file. This JSON file is typically found in the following location:

${Env:ProgramFiles}\\Amazon\\SSM\\Plugins\\awsCloudWatch\
\AWS.EC2.Windows.CloudWatch.json

{Env:ProgramFiles} represents the location where the Amazon folder can be found, typically C:
\Program Files.
2. Copy this data into a text file for use in a later step.

888
 AWS Systems Manager User Guide
Logging AWS Systems Manager
API Calls with AWS CloudTrail

We recommend storing a backup of the JSON on a location other than the instance itself.

Two: To uninstall the CloudWatch agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AWS-ConfigureAWSPackage.
4. In the Targets section, choose an option and select the instances to update.
5. In the Action list, choose Uninstall.
6. In Name, type AmazonCloudWatchAgent.
7. Choose Run.

Three: To reenable log collection in SSM Agent (console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command, and then choose Run command.
3. In the Command document list, choose AWS-ConfigureCloudWatch.
4. In the Targets section, choose an option and select the instances to update.
5. In the Status list, choose Enabled.
6. In the Properties box (AWS Systems Manager console) or Parameters box (Amazon EC2 console),
paste the contents of the old config data you saved to the text file.
7. Choose Run.

Logging AWS Systems Manager API Calls with AWS

CloudTrail
Systems Manager is integrated with AWS CloudTrail, a service that provides a record of actions taken by
a user, role, or an AWS service in Systems Manager. CloudTrail captures all API calls for Systems Manager
as events, including calls from the Systems Manager console and from code calls to the Systems Manager
APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3
bucket, including events for Systems Manager. If you don't configure a trail, you can still view the most
recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail,
you can determine the request that was made to Systems Manager, the IP address from which the
request was made, who made the request, when it was made, and additional details.

To learn more about CloudTrail, see the AWS CloudTrail User Guide.

Systems Manager Information in CloudTrail

CloudTrail is enabled on your AWS account when you create the account. When activity occurs in Systems
Manager, that activity is recorded in a CloudTrail event along with other AWS service events in Event
history. You can view, search, and download recent events in your AWS account. For more information,
see Viewing Events with CloudTrail Event History.

For an ongoing record of events in your AWS account, including events for Systems Manager, create a
trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create
a trail in the console, the trail applies to all regions. The trail logs events from all regions in the AWS
partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can

889
 AWS Systems Manager User Guide
Understanding Systems Manager Log File Entries

configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs.
For more information, see:

• Overview for Creating a Trail

• CloudTrail Supported Services and Integrations
• Configuring Amazon SNS Notifications for CloudTrail
• Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail Log Files from Multiple
Accounts

All Systems Manager actions are logged by CloudTrail and are documented in the AWS Systems Manager
API Reference. For example, calls to the CreateMaintenanceWindows, PutInventory, SendCommand,
and StartSession actions generate entries in the CloudTrail log files. (For an example of setting
up CloudTrail to monitor a Systems Manager API call, see Monitoring Session Activity Using Amazon
CloudWatch Events (Console) (p. 610).)

Every event or log entry contains information about who generated the request. The identity
information helps you determine the following:

• Whether the request was made with root or IAM user credentials.
• Whether the request was made with temporary security credentials for a role or federated user.
• Whether the request was made by another AWS service.

For more information, see the CloudTrail userIdentity Element.

Understanding Systems Manager Log File Entries

A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you
specify. CloudTrail log files contain one or more log entries. An event represents a single request from
any source and includes information about the requested action, the date and time of the action, request
parameters, and so on. CloudTrail log files are not an ordered stack trace of the public API calls, so they
do not appear in any specific order.

The following example shows a CloudTrail log entry that demonstrates the DeleteDocuments action on
a document named example-Document in the US East (Ohio) Region (us-east-2).

{
"eventVersion": "1.04",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AKIAI44QH8DHBEXAMPLE:203.0.113.11",
"arn": "arn:aws:sts::123456789012:assumed-role/example-role/203.0.113.11",
"accountId": "123456789012",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2018-03-06T20:19:16Z"
},
"sessionIssuer": {
"type": "Role",
"principalId": "AKIAI44QH8DHBEXAMPLE",
"arn": "arn:aws:iam::123456789012:role/example-role",
"accountId": "123456789012",
"userName": "example-role"
}
}
},
"eventTime": "2018-03-06T20:30:12Z",

890
 AWS Systems Manager User Guide
Monitoring with Amazon CloudWatch Events

"eventSource": "ssm.amazonaws.com",
"eventName": "DeleteDocument",
"awsRegion": "us-east-2",
"sourceIPAddress": "203.0.113.11",
"userAgent": "example-user-agent-string",
"requestParameters": {
"name": "example-Document"
},
"responseElements": null,
"requestID": "86168559-75e9-11e4-8cf8-75d18EXAMPLE",
"eventID": "832b82d5-d474-44e8-a51d-093ccEXAMPLE",
"resources": [
{
"ARN": "arn:aws:ssm:us-east-2:123456789012:document/example-Document",
"accountId": "123456789012"
}
],
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}

Monitoring Systems Manager Events with Amazon

CloudWatch Events
You can configure rules in Amazon CloudWatch Events to alert you to changes in Systems Manager
resources, and to direct CloudWatch Events to take actions based on the content of those events.
CloudWatch Events provides support for a number of events that are emitted by various Systems
Manager capabilities.
Note
For Systems Manager actions that aren't supported by CloudWatch Events, you can create an
event rule that is based on an API call, which are recorded by AWS CloudTrail. For an example,
see Monitoring Session Activity Using Amazon CloudWatch Events (Console) (p. 610).

For more information about how to get started with CloudWatch Events and set up rules, see Getting
Started with CloudWatch Events in the Amazon CloudWatch Events User Guide.

Following are lists of the Systems Manager event types with built-in monitoring support in CloudWatch
Events.

Run Command

Supported events include the following:

• Status change for a command (applies to one or more instances).
• Status change for a command invocation (applies to one instance only).

For more information, see Configuring CloudWatch Events for Run Command (p. 615).
Automation

Supported events include the following:

• Status change for an automation execution.
• Status change for a single step in an automation execution.

For more information, see Configuring CloudWatch Events for Systems Manager
Automation (p. 892).
State Manager

Supported events include the following:

891
 AWS Systems Manager User Guide
Configuring CloudWatch Events for Automation

• State change for an association

• State change for an instance association.
Configuration Compliance

Supported events include the following:

• State change for association compliance.
• State change for instance patch compliance.

For more information, see Remediating Compliance Issues (p. 510).

Maintenance Window

Supported events include the following:

• State change for a maintenance window (enabled or disabled)
• Change in a maintenance window target registration.
• Change in a maintenance window task registration.
• State change for a maintenance window execution.
• State change for a maintenance window task execution.
• State change for a maintenance window task target invocation.
Parameter Store

Supported events include the following:

• A parameter is created, updated, or deleted, or a label is attached or moved from one version to
another (detail-type: "Parameter Store Change").
• A parameter has expired or been deleted, its expiration date is approaching, or its value hasn't
been changed for a specified period of time (detail-type: "Parameter Store Policy
Action").

For more information, see Set Up Notifications or Trigger Actions Based on Parameter Store
Events (p. 836).
Inventory

Supported events include the following:

• Deletion of custom inventory item on an instance.
• Availability of a delete action summary.
• A disabled custom inventory type is detected.

For more information, see Viewing Inventory Delete Actions in CloudWatch Events (p. 549).

For more information about the Systems Manager event types that are supported by CloudWatch Events,
see the following topics in the Amazon CloudWatch Events User Guide:

• AWS Systems Manager Events

• AWS Systems Manager Configuration Compliance Events
• AWS Systems Manager Maintenance Windows Events
• AWS Systems Manager Parameter Store Events

Configuring CloudWatch Events for Systems Manager

Automation
You can configure Amazon CloudWatch Events to notify you of Systems Manager Automation events. For
example, you can configure CloudWatch Events to send notifications when an Automation step succeeds

892
 AWS Systems Manager User Guide
Amazon SNS Notifications

or fails. You can also configure CloudWatch Events to send notifications if the Automation workflow
succeeds or fails. Use the following procedure to configure CloudWatch Events to send notification about
Automation events.

To configure CloudWatch Events for Automation

1. Sign in to the AWS Management Console and open the CloudWatch console at https://
console.aws.amazon.com/cloudwatch/.
2. Choose Events in the left navigation, and then choose Create rule.
3. Under Event Source, verify that Event Pattern is selected.
4. In the Service Name field, choose EC2 Simple Systems Manager (SSM)
5. In the Event Type field, choose Automation.
6. Choose the detail types and statuses for which you want to receive notifications, and then choose
Add targets.
7. In the Select target type list, choose a target type. For information about the different types of
targets, see the corresponding AWS Help documentation.
8. Choose Configure details.
9. Specify the rule details, and then choose Create rule.

The next time you run Automation, CloudWatch Events sends event details to the target you specified.

Configuring Amazon SNS Notifications for AWS

Systems Manager
You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about
the status of commands that you send using AWS Systems Manager Run Command or AWS Systems
Manager Maintenance Windows. Amazon SNS coordinates and manages sending and delivering
notifications to clients or endpoints that are subscribed to Amazon SNS topics. You can receive a
notification whenever a command changes to a new state or to a specific state, such as Failed or Timed
Out. In cases where you send a command to multiple instances, you can receive a notification for each
copy of the command sent to a specific instance. Each copy is called an invocation.

Amazon SNS can deliver notifications as HTTP or HTTPS POST, email (SMTP, either plaintext or in
JSON format), or as a message posted to an Amazon Simple Queue Service (Amazon SQS) queue. For
more information, see What Is Amazon SNS in the Amazon Simple Notification Service Developer Guide.
For examples of the structure of the JSON data included in the Amazon SNS notification provided by
Run Command and Maintenance Windows, see Example Amazon SNS Notifications for AWS Systems
Manager (p. 899).

Configure Amazon SNS Notifications for AWS

Systems Manager
Run Command and Run Command tasks that are registered to a maintenance window can send
Amazon SNS notifications for command tasks that enter the following statuses. For information about
the conditions that cause a command to enter one of these statuses, see Understanding Command
Statuses (p. 627).

• In Progress

893
 AWS Systems Manager User Guide
Configure Amazon SNS Notifications
for AWS Systems Manager

• Success
• Failed
• Timed Out
• Canceled

Note
Commands sent using Run Command also report Canceling and Pending status. These statuses
are not captured by Amazon SNS notifications.

Command Summary Amazon SNS Notifications

If you configure Run Command or a Run Command task in your maintenance window for Amazon SNS
notifications, Amazon SNS sends summary messages that include the following information.

Field Type Description

eventTime String The time that the event was

triggered. The timestamp is
important because Amazon SNS
does not guarantee message
delivery order. Example:
2016-04-26T13:15:30Z

documentName String The name of the SSM document

used to run this command.

commandId String The ID generated by Run

Command after the command
was sent.

expiresAfter Date If this time is reached and the

command has not already
started executing, it will not run.

outputS3BucketName String The Amazon Simple Storage

Service (Amazon S3) bucket
where the responses to the
command execution should be
stored.

outputS3KeyPrefix String The Amazon S3 directory path

inside the bucket where the
responses to the command
execution should be stored.

requestedDateTime String The time and date that the

request was sent to this specific
instance.

instanceIds StringList The instances that were targeted

by the command.
Note
Instance IDs are
only included in the
summary message if
the Run Command task

894
 AWS Systems Manager User Guide
Configure Amazon SNS Notifications
for AWS Systems Manager

Field Type Description

targeted instance IDs
directly. Instance IDs
are not included in the
summary message if
the Run Command task
was issued using tag-
based targeting.

status String Command status for the

command.

Invocation-based Amazon SNS Notifications

If you send a command to multiple instances, Amazon SNS can send messages about each copy or
invocation of the command. The messages include the following information.

Field Type Description

eventTime String The time that the event was

triggered. The timestamp is
important because Amazon SNS
does not guarantee message
delivery order. Example:
2016-04-26T13:15:30Z

documentName String The name of the Systems

Manager document used to run
this command.

requestedDateTime String The time and date that the

request was sent to this specific
instance.

commandId String The ID generated by Run

Command after the command
was sent.

instanceId String The instance that was targeted

by the command.

status String Command status for this

invocation.

To set up Amazon SNS notifications when a command changes status, you must complete the following
tasks.
Note
If you are not configuring Amazon SNS notifications for your maintenance window, then you can
skip Task 5 below.

Topics
• Task 1: Create and Subscribe to an Amazon SNS Topic (p. 896)
• Task 2: Create an IAM Policy for Amazon SNS Notifications (p. 896)
• Task 3: Create an IAM Role for Amazon SNS Notifications (p. 897)

895
 AWS Systems Manager User Guide
Configure Amazon SNS Notifications
for AWS Systems Manager

• Task 4: Configure User Access (p. 897)

• Task 5: Attach the iam:PassRole Policy to Your Maintenance Window Role (p. 898)

Task 1: Create and Subscribe to an Amazon SNS Topic

An Amazon SNS topic is a communication channel that Run Command and Run Command tasks that
are registered to a maintenance window use to send notifications about the status of your commands.
Amazon SNS supports different communication protocols, including HTTP/S, email, and other AWS
services like Amazon SQS. To get started quickly, we recommend that you start with the email protocol.
For information about how to create a topic, see Create a Topic in the Amazon Simple Notification Service
Developer Guide.
Note
After you create the topic, copy or make a note of the Topic ARN. You specify this ARN when
you send a command that is configured to return status notifications.

After you create the topic, subscribe to it by specifying an Endpoint. If you chose the Email protocol,
the endpoint is the email address where you want to receive notifications. For more information about
how to subscribe to a topic, see Subscribe to a Topic in the Amazon Simple Notification Service Developer
Guide.

Amazon SNS sends a confirmation email from AWS Notifications to the email address that you specify.
Open the email and choose the Confirm subscription link.

You will receive an acknowledgement message from AWS. Amazon SNS is now configured to receive
notifications and send the notification as an email to the email address that you specified.

Task 2: Create an IAM Policy for Amazon SNS Notifications

Use the following procedure to create a custom AWS Identity and Access Management (IAM) policy that
provides permissions for triggering Amazon SNS notifications.

To create a custom IAM policy for Amazon SNS notifications

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Policies, and then choose Create policy. (If a Get Started button
appears, choose it, and then choose Create Policy.)
3. Choose the JSON tab.
4. Replace the default content with the following:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sns:Publish"
],
"Resource": "*"
}
]
}

5. Choose Review policy.

6. On the Review policy page, for Name, enter a name for the inline policy. For example:
SNSPublishPermissions.
7. (Optional) For Description, enter a description for the policy.

896
 AWS Systems Manager User Guide
Configure Amazon SNS Notifications
for AWS Systems Manager

8. Choose Create policy.

Task 3: Create an IAM Role for Amazon SNS Notifications

Use the following procedure to create an IAM role for Amazon SNS notifications. This service role is used
by Systems Manager to trigger Amazon SNS notifications.

To create an IAM service role for Amazon SNS notifications

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles, and then choose Create role.
3. On the Select type of trusted entity page, under AWS Service, choose EC2.
4. In the Select your use case section, choose EC2, and then choose Next: Permissions.
5. On the Attach permissions policies page, select the check box to the left of the name of the custom
policy you created in Task 2. For example: SNSPublishPermissions.
6. On the Review page, type a name in the Role name box, and then type a description.
7. Choose Create role. The system returns you to the Roles page.
8. On the Roles page, choose the role you just created to open the Summary page.
9. Choose the Trust Relationships tab, and then choose Edit Trust Relationship.
10. Add , "ssm.amazonaws.com" to the existing policy, as shown in the following code snippet:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"ec2.amazonaws.com",
"ssm.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}

Note
You must add a comma after the existing entry. In the preceding example, the entry is
"ec2.amazonaws.com". Otherwise, the JSON is invalid.
11. Choose Update Trust Policy.
12. Copy or make a note of the Role ARN. This Role ARN is used when you send a command that is
configured to return Amazon SNS notifications.
13. Leave the Summary page open.

Task 4: Configure User Access

If your AWS Identity and Access Management (IAM) user account, group, or role is assigned administrator
permissions, then you have access to Systems Manager Run Command and Maintenance Windows. If you
don't have administrator permissions, then an administrator must give you permission by assigning the
AmazonSSMFullAccess managed policy, or a policy that provides comparable permissions, to your IAM
account, group, or role.

897
 AWS Systems Manager User Guide
Configure Amazon SNS Notifications
for AWS Systems Manager

Use the following procedure to configure a user account to use Run Command and Maintenance
Windows. If you need to create a new user account, see Creating an IAM User in Your AWS Account in the
IAM User Guide.

To configure user access and attach the iam:PassRole policy to a user account

1. In the IAM navigation pane, choose Users, and then choose the user account that you want to
configure.
2. On the Permissions tab, in the policies list, verify that either the AmazonSSMFullAccess policy
is listed or that there is a comparable policy that gives the account permissions to access Systems
Manager.
3. Choose Add inline policy.
4. On the Create policy page, choose the Visual editor tab.
5. Choose Service, and then choose IAM.
6. Choose Select actions.
7. In the Filter actions text box, type PassRole, and then choose the PassRole option.
8. Choose Resources. Verify that Specific is selected, and then choose Add ARN.
9. In the Specify ARN for role field, paste the Amazon SNS role ARN that you copied at the end of Task
3. The system automatically populates the Account and Role name with path fields.
10. Choose Add.
11. Choose Review policy.
12. On the Review Policy page, type a name and then choose Create Policy.

Task 5: Attach the iam:PassRole Policy to Your Maintenance

Window Role
When you register a Run Command task with a maintenance window, you specify a service role Amazon
Resource Name (ARN). This service role is used by Systems Manager to run tasks registered to the
maintenance window. To configure Amazon SNS notifications for a registered Run Command task, you
must attach an iam:PassRole policy to the maintenance window service role specified. If you do not
intend to configure the registered task for Amazon SNS notifications, then this task can be skipped.

The iam:PassRole policy allows the Maintenance Windows service role to pass the SNS role created in
Task 3 to the Amazon SNS service. The following procedure shows how to attach the iam:PassRole
policy to the Maintenance Windows service role.
Note
You must use a custom service role for your maintenance window to send notifications related
to the Run Command tasks registered. For information, see Should I Use a Service-Linked Role
or a Custom Service Role to Run Maintenance Window Tasks?.
If you need to create a custom service role, see one of the following topics:

• Control Access to Maintenance Windows (Console) (p. 446)

• Control Access to Maintenance Windows (AWS CLI) (p. 449)
• Control Access to Maintenance Windows (Tools for Windows PowerShell) (p. 452)

To attach the iam:PassRole policy to your Maintenance Windows Role

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Roles and select the Amazon SNS role created in Task 3.
3. Copy or make a note of the Role ARN and return to the Roles section of the IAM console.

898
 AWS Systems Manager User Guide
Example Amazon SNS Notifications
for AWS Systems Manager

4. Select the custom Maintenance Windows service role you created (under Role name).
5. Under Permissions, verify that either the AmazonSSMMaintenanceWindowRole policy is listed or
there is a comparable policy that gives maintenance windows permission to the Systems Manager
API.
6. Choose Add inline policy.
7. On the Set Permissions page, choose Policy Generator, and then choose Select.
8. Verify that Effect is set to Allow.
9. From AWS Services choose AWS Identity and Access Management.
10. From Actions choose PassRole.
11. In the Amazon Resource Name (ARN) field, paste the ARN of the Amazon SNS IAM role created in
Task 3.
12. Choose Add Statement, and then choose Next.
13. On the Review Policy page, choose Apply Policy.

Example Amazon SNS Notifications for AWS Systems

Manager
You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about
the status of commands that you send using AWS Systems Manager Run Command or AWS Systems
Manager Maintenance Windows.
Note
This guide does not address how to configure notifications for Run Command or Maintenance
Windows. For information about configuring Run Command or Maintenance Windows to
send Amazon SNS notifications about the status of commands, see Configure Amazon SNS
Notifications for AWS Systems Manager (p. 893).

The following examples show the structure of the JSON output returned by Amazon SNS notifications
when configured for Run Command or Maintenance Windows.

Sample JSON Output for Command summary messages using instance ID targeting

{
"commandId": "a8c7e76f-15f1-4c33-9052-0123456789ab",
"documentName": "AWS-RunPowerShellScript",
"instanceIds": [
"i-1234567890abcdef0",
"i-9876543210abcdef0"
],
"requestedDateTime": "2019-04-25T17:57:09.17Z",
"expiresAfter": "2019-04-25T19:07:09.17Z",
"outputS3BucketName": "awss3bucketname",
"outputS3KeyPrefix": "runcommand",
"status": "InProgress",
"eventTime": "2019-04-25T17:57:09.236Z"
}

Sample JSON Output for Command summary messages using tag-based targeting

{
"commandId": "9e92c686-ddc7-4827-b040-0123456789ab",
"documentName": "AWS-RunPowerShellScript",
"instanceIds": [],
"requestedDateTime": "2019-04-25T18:01:03.888Z",
"expiresAfter": "2019-04-25T19:11:03.888Z",

899
 AWS Systems Manager User Guide
Use Run Command to Send a Command
that Returns Status Notifications

"outputS3BucketName": "",
"outputS3KeyPrefix": "",
"status": "InProgress",
"eventTime": "2019-04-25T18:01:05.825Z"
}

Sample JSON Output for Invocation messages

{
"commandId": "ceb96b84-16aa-4540-91e3-925a9a278b8c",
"documentName": "AWS-RunPowerShellScript",
"instanceId": "i-1234567890abcdef0",
"requestedDateTime": "2019-04-25T18:06:05.032Z",
"status": "InProgress",
"eventTime": "2019-04-25T18:06:05.099Z"
}

Use Run Command to Send a Command that Returns

Status Notifications
The following procedures show how to use the AWS Command Line Interface (AWS CLI) or AWS Systems
Manager console to send a Run Command that is configured to return status notifications.

Sending a Run Command that Returns Notifications (Console)

Use the following procedure to send a command through Run Command that is configured to return
status notifications using the Systems Manager console.

To send a command that returns notifications (Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Run Command.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Run Command.
3. Choose Run command.
4. In the Command document list, choose a Systems Manager document.
5. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
6. In the Command parameters section, specify values for required parameters.
7. For Other parameters:

• For Comment, type information about this command.

• For Timeout (seconds), specify the number of seconds for the system to wait before failing the
overall command execution.
8. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.

900
 AWS Systems Manager User Guide
Use Run Command to Send a Command
that Returns Status Notifications

Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
9. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
10. In the SNS Notifications section, choose Enable SNS notifications.
11. In the IAM role field, type or paste the SNS IAM role ARN you created in Task 3 in the topic
Configuring Amazon SNS Notifications for AWS Systems Manager.
12. In the SNS topic field, type or paste the Amazon SNS topic ARN to be used.
13. In the Notify me on field, choose the events for which you want to receive notifications.
14. In the Notify me for field, choose to receive notifications for each copy of a command sent to
multiple instances (invocations) or the command summary.
15. Choose Run.
16. Check your email for a message from Amazon SNS and open the email. Amazon SNS can take a few
minutes to send the mail.

Sending a Run Command that Returns Notifications (CLI)

Use the following procedure to send a command through Run Command that is configured to return
status notifications using the AWS CLI.

To send a command that returns notifications (CLI)

1. Open the AWS CLI.

2. Specify parameters in the following command to target based on managed instance IDs:

aws ssm send-command --instance-ids "ID-1, ID-2" --document-name "Name"

--parameters '{"commands":["input"]}' --service-role "SNSRoleARN" --
notification-config '{"NotificationArn":"SNSTopicName","NotificationEvents":
["All"],"NotificationType":"Command"}'

For example:

aws ssm send-command --instance-ids "i-02573cafcfEXAMPLE, i-0471e04240EXAMPLE"

--document-name "AWS-RunPowerShellScript" --parameters '{"commands":
["Get-Process"]}' --service-role "arn:aws:iam::111122223333:role/
SNS_Role" --notification-config '{"NotificationArn":"arn:aws:sns:us-
east-1:111122223333:SNSTopic","NotificationEvents":
["All"],"NotificationType":"Command"}'

Alternative commands

Specify parameters in the following command to target managed instances using tags:

901
 AWS Systems Manager User Guide
Use a Maintenance Window to Send a
Command that Returns Status Notifications

aws ssm send-command --targets "Key=tag:TagName,Values=TagKey" --document-name

"Name" --parameters '{"commands":["input"]}' --service-role "SNSRoleARN" --
notification-config '{"NotificationArn":"SNSTopicName","NotificationEvents":
["All"],"NotificationType":"Command"}'

For example:

aws ssm send-command --targets "Key=tag:Environment,Values=Dev" --

document-name "AWS-RunPowerShellScript" --parameters '{"commands":
["Get-Process"]}' --service-role "arn:aws:iam::111122223333:role/
SNS_Role" --notification-config '{"NotificationArn":"arn:aws:sns:us-
east-1:111122223333:SNSTopic","NotificationEvents":
["All"],"NotificationType":"Command"}'

3. Press Enter.
4. Check your email for a message from Amazon SNS and open the email. Amazon SNS can take a few
minutes to send the mail.

For more information about configuring Run Command from the command line, see Amazon EC2
Systems Manager API Reference and the Systems Manager AWS CLI Reference.

Use a Maintenance Window to Send a Command that

Returns Status Notifications
The following procedures show how to register an AWS Systems Manager Run Command task with your
maintenance window using the Systems Manager console or the AWS Command Line Interface (AWS
CLI). The procedures also describe how to configure the Run Command task to return status notifications.

Before You Begin

If you haven't created a maintenance window or registered targets, see Working with Maintenance
Windows (Console) for steps on how to create a maintenance window and register targets.

To receive notifications from the Amazon SNS service, you must attach an iam:PassRole policy to the
Maintenance Windows service role specified in the registered task. If you haven't added iam:PassRole
permissions to your Maintenance Windows service role, see Task 5: Attach the iam:PassRole Policy to
Your Maintenance Windows Role.

Registering a Run Command Task to a Maintenance Window

that Returns Notifications (Console)
Use the following procedure to register a Run Command task that is configured to return status
notifications to your maintenance window using the Systems Manager console.

To register a Run Command task with your maintenance window that returns notifications
(Console)

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Maintenance Windows.

-or-

If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the
navigation pane, and then choose Maintenance Windows.

902
 AWS Systems Manager User Guide
Use a Maintenance Window to Send a
Command that Returns Status Notifications

3. Select the maintenance window for which you would like to register a Run Command task
configured to send Amazon SNS notifications.
4. Choose Actions and then choose Register Run Command task.
5. In the Name field, enter a name for the task.
6. In the Description field, enter a description.
7. From the Document list, choose a Command document.
8. In the Task priority list, specify a priority for this task. 1 is the highest priority. Tasks in a
maintenance window are scheduled in priority order. Tasks that have the same priority are scheduled
in parallel.
9. In the Targets section, identify the instances on which you want to run this operation by specifying
tags, selecting instances manually, or specifying a resource group.
Note
If you choose to select instances manually, and an instance you expect to see is not included
in the list, see Where Are My Instances? (p. 642) for troubleshooting tips.
10. (Optional) For Rate control:

• For Concurrency, specify either a number or a percentage of instances on which to run the
command at the same time.
Note
If you selected targets by specifying tags applied to managed instances or by specifying
AWS resource groups, and you are not certain how many instances are targeted, then
limit the number of instances that can run the document at the same time by specifying a
percentage.
• For Error threshold, specify when to stop running the command on other instances after it fails
on either a number or a percentage of instances. For example, if you specify three errors, then
Systems Manager stops sending the command when the fourth error is received. Instances still
processing the command might also send errors.
11. In the IAM service role area, choose the Maintenance Windows service role that has iam:PassRole
permissions to the SNS role.
Note
You must add iam:PassRole permissions to the Maintenance Windows role to
enable Systems Manager to pass the SNS role to Amazon SNS. If you haven't added
iam:PassRole permissions, see Task 5 in the topic Configuring Amazon SNS Notifications
for AWS Systems Manager.
12. In the Output options section, if you want to save the command output to a file, select the Write
command output to an Amazon S3 bucket. Type the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the
instance profile assigned to the instance, not those of the IAM user performing this task. For
more information, see Create an IAM Instance Profile for Systems Manager (p. 29).
13. In the SNS notifications section, choose Enable SNS Notifications.
14. In the IAM role section, choose the SNS role to trigger Amazon SNS notifications.
15. In the SNS topic section, type or paste the Amazon SNS topic ARN to be used.
16. In the Event type section, choose the events for which you want to receive notifications.
17. In the Notification type section, choose to receive notifications for each copy of a command sent to
multiple instances (invocations) or the command summary.
18. In the Input Parameters section, enter the required parameters based on the Command document
you chose.
19. Choose Register Run Command task.

903
 AWS Systems Manager User Guide
Use a Maintenance Window to Send a
Command that Returns Status Notifications

20. After the next execution of your maintenance window, check your email for a message from Amazon
SNS and open the email. Amazon SNS can take a few minutes to send the mail.

Registering a Run Command Task to a Maintenance Window

that Returns Notifications (CLI)
Use the following procedure to register a Run Command task that is configured to return status
notifications to your maintenance window using the AWS CLI.

To register a Run Command task with your maintenance window that returns notifications
(CLI)
Note
To better manage your task options, this procedure uses the command option --cli-input-
json, with option values stored in a JSON file.

1. On your local machine, create a file named RunCommandTask.json.

2. Paste the following contents into the file:

{
"Name": "Name",
"Description": "Description",
"WindowId": "mw-0c50858d01EXAMPLE",
"ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowIAMRole",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Priority": 3,
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskType": "RUN_COMMAND",
"TaskArn": "CommandDocumentName",
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "Comment",
"TimeoutSeconds": 3600,
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:region:123456789012:SNSTopicName",
"NotificationEvents": [
"All"
],
"NotificationType": "Command"
},
"ServiceRoleArn": "arn:aws:iam::123456789012:role/SNSIAMRole"
}
}
}

3. Replace the example values with information about your own resources. For more information, see
Required Values for the 'register-task-with-maintenance-window' Command.
Note
You can also restore options we have omitted from this example if you want to use them.
For example, you can save command output to an S3 bucket. For more information, see
Optional Values for the 'register-task-with-maintenance-window' Command.

904
 AWS Systems Manager User Guide
Use a Maintenance Window to Send a
Command that Returns Status Notifications

4. Save the file.

5. In the directory on your local machine where you saved the file, run the following command:

aws ssm register-task-with-maintenance-window --cli-input-json file://

RunCommandTask.json
Important
Be sure to include file:// before the file name. It is required in this command.

If successful, the command returns information similar to the following:

{
"WindowTaskId": "j2l8d5b5c-mw66-tk4d-r3g9-1d4d1EXAMPLE"
}

6. After the next execution of your maintenance window, check your email for a message from Amazon
SNS and open the email. Amazon SNS can take a few minutes to send the mail.

For more information about registering tasks for maintenance window from the command line, see
Amazon EC2 Systems Manager API Reference and the Systems Manager AWS CLI Reference.

905
 AWS Systems Manager User Guide
Authentication

Authentication and Access Control

for AWS Systems Manager
Access to AWS Systems Manager requires credentials. Those credentials must have permissions to access
AWS resources for tasks such as creating or updating documents and registering tasks and targets with
maintenance windows. The following sections provide details on how you can use AWS Identity and
Access Management (IAM) and Systems Manager to help secure access to your resources:

• Authentication (p. 906)

• Access Control (p. 907)

For more information about configuring access to AWS Systems Manager, see Create Non-Admin IAM
Users and Groups for Systems Manager (p. 25).

For information about the Amazon Simple Storage Service (Amazon S3) buckets that resources might
need to access to perform Systems Manager operations, see About Minimum S3 Bucket Permissions for
SSM Agent (p. 87).

Authentication
You can access AWS as any of the following types of identities:

• AWS account root user – When you first create an AWS account, you begin with a single sign-in
identity that has complete access to all AWS services and resources in the account. This identity is
called the AWS account root user and is accessed by signing in with the email address and password
that you used to create the account. We strongly recommend that you do not use the root user for
your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the
root user only to create your first IAM user. Then securely lock away the root user credentials and use
them to perform only a few account and service management tasks.
• IAM user – An IAM user is an identity within your AWS account that has specific custom permissions
(for example, permissions to create document in Systems Manager). You can use an IAM user name
and password to sign in to secure AWS webpages like the AWS Management Console, AWS Discussion
Forums, or the AWS Support Center.

In addition to a user name and password, you can also generate access keys for each user. You can
use these keys when you access AWS services programmatically, either through one of the several
SDKs or by using the AWS Command Line Interface (CLI). The SDK and CLI tools use the access keys
to cryptographically sign your request. If you don’t use AWS tools, you must sign the request yourself.
Systems Manager supports Signature Version 4, a protocol for authenticating inbound API requests. For
more information about authenticating requests, see Signature Version 4 Signing Process in the AWS
General Reference.

 
• IAM role – An IAM role is an IAM identity that you can create in your account that has specific
permissions. An IAM role is similar to an IAM user in that it is an AWS identity with permissions policies
that determine what the identity can and cannot do in AWS. However, instead of being uniquely

906
 AWS Systems Manager User Guide
Access Control

associated with one person, a role is intended to be assumable by anyone who needs it. Also, a role
does not have standard long-term credentials such as a password or access keys associated with it.
Instead, when you assume a role, it provides you with temporary security credentials for your role
session. IAM roles with temporary credentials are useful in the following situations:

 
• Federated user access – Instead of creating an IAM user, you can use existing identities from AWS
Directory Service, your enterprise user directory, or a web identity provider. These are known as
federated users. AWS assigns a role to a federated user when access is requested through an identity
provider. For more information about federated users, see Federated Users and Roles in the IAM User
Guide.

 
• AWS service access – A service role is an IAM role that a service assumes to perform actions in your
account on your behalf. When you set up some AWS service environments, you must define a role
for the service to assume. This service role must include all the permissions that are required for
the service to access the AWS resources that it needs. Service roles vary from service to service, but
many allow you to choose your permissions as long as you meet the documented requirements
for that service. Service roles provide access only within your account and cannot be used to grant
access to services in other accounts. You can create, modify, and delete a service role from within
IAM. For example, you can create a role that allows Amazon Redshift to access an Amazon S3 bucket
on your behalf and then load data from that bucket into an Amazon Redshift cluster. For more
information, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

 
• Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentials
for applications that are running on an EC2 instance and making AWS CLI or AWS API requests. This
is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2 instance
and make it available to all of its applications, you create an instance profile that is attached to
the instance. An instance profile contains the role and enables programs that are running on the
EC2 instance to get temporary credentials. For more information, see Using an IAM Role to Grant
Permissions to Applications Running on Amazon EC2 Instances in the IAM User Guide.

Access Control
You can have valid credentials to authenticate your requests, but unless you have permissions you cannot
create or access Systems Manager resources. For example, you must have permissions to create, view,
or delete activations, associations, documents, and maintenance windows; to register or deregister
instances and patch baselines; and so on.

The following sections describe how to manage permissions for Systems Manager. We recommend that
you read the overview first.

• Overview of Managing Access Permissions to Your AWS Systems Manager Resources (p. 907)
• Using Identity-based Policies (IAM Policies) for AWS Systems Manager (p. 914)
• AWS Systems Manager Permissions Reference (p. 921)

Overview of Managing Access Permissions to Your

AWS Systems Manager Resources
Every AWS resource is owned by an AWS account, and permissions to create or access a resource are
governed by permissions policies. An account administrator can attach permissions policies to IAM

907
 AWS Systems Manager User Guide
Resources and Operations

identities (that is, users, groups, and roles). Some services—such as AWS Lambda, Amazon Simple
Notification Service (Amazon SNS), and Amazon Simple Storage Service (Amazon S3)—also support
attaching permissions policies to resources.
Note
An account administrator (or administrator user) is a user with administrator privileges. For more
information, see IAM Best Practices in the IAM User Guide.

When granting permissions, the account administrator decides who gets the permissions, the resources
that they get permissions for, and the specific actions that you want to allow on those resources.

Topics
• AWS Systems Manager Resources and Operations (p. 908)
• Understanding Resource Ownership (p. 910)
• Managing Access to Resources (p. 911)
• Specifying Policy Elements: Resources, Actions, Effects, and Principals (p. 913)
• Specifying Conditions in a Policy (p. 913)

AWS Systems Manager Resources and Operations

Systems Manager includes several primary resources:

• Association
• Automation definition
• Automation execution
• Document
• Maintenance window
• Managed instance
• Managed instance inventory
• Parameter
• Patch baseline
• Resource data sync
• Session

For automation definitions, Systems Manager supports a second-level resource, version ID. In AWS, these
second-level resources are, known as subresources. Specifying a version subresource for an automation
definition resource lets you provide access to certain versions of an automation definition. For example,
you might want to ensure that only the latest version of an automation definition is used in your
instance management.

To organize and manage parameters, you can create names for parameters with a hierarchical
construction. With hierarchical construction, a parameter name can include a path that you define by
using forward slashes. You can name a parameter resource with a maximum of five levels. We suggest
that you create hierarchies that reflect an existing hierarchical structure in your environment. For more
information, see Creating Systems Manager Parameters (p. 847).

Each resource has a unique Amazon Resource Names (ARNs). In a policy, you identify the resource that a
policy applies to by using its ARN. For more information about ARNs, see Amazon Resource Names (ARN)
and AWS Service Namespaces in the Amazon Web Services General Reference.

The following table shows the structure of the ARN format for each resource type in Systems Manager:

908
 AWS Systems Manager User Guide
Resources and Operations

Resource Type ARN Format

Association arn:aws:ssm:region:account-id:association/association-id

Automation execution arn:aws:ssm:region:account-id:automation-execution/automation-

execution-id

Automation definition arn:aws:ssm:region:account-id:automation-definition/automation-

(with version subresource) definition-id:version-id

Document arn:aws:ssm:region:account-id:document/document-name

Maintenance window arn:aws:ssm:region:account-id:maintenancewindow/window-id

Managed instance arn:aws:ssm:region:account-id:managed-instance/managed-

instance-id

Managed instance arn:aws:ssm:region:account-id:managed-instance-

inventory inventory/managed-instance-id

Parameter A one-level parameter:

• arn:aws:ssm:region:account-id:parameter/parameter-name/

A parameter named with a hierarchical construction:

• arn:aws:ssm:region:account-id:parameter/parameter-name-
root/level-2/level-3/level-4/level-5

Patch baseline arn:aws:ssm:region:account-id:patchbaseline/patch-baseline-id

Session arn:aws:ssm:region:account-id:session/session-id
Note
In most cases, the session ID is constructed using the ID of the
account user who started the session, plus an alphanumeric
suffix. For example:

arn:aws:us-east-2:111122223333:session/
JohnDoe-1a2b3c4sEXAMPLE

However, if the user ID is not available, the ARN is contructed this

way instead:

arn:aws:us-east-2:111122223333:session/
session-1a2b3c4sEXAMPLE

All Systems Manager arn:aws:ssm:*

resources

All Systems Manager arn:aws:ssm:region:account-id:*

resources owned by the
specified account in the
specified region

909
 AWS Systems Manager User Guide
Understanding Resource Ownership

Note
Most AWS services treat a colon (:) or a forward slash (/) as the same character in ARNs.
However, Systems Manager requires an exact match in resource patterns and rules. When
creating event patterns, be sure to use the correct ARN characters so that they match the
resource's ARN.

For example, you can indicate a specific document (myDocument) in your statement using its ARN as
follows:

"Resource": "arn:aws:ssm:us-west-2:123456789012:document/myDocument"

You can specify all documents that belong to a specific account by using the wildcard character (*) as
follows:

"Resource": "arn:aws:ssm:us-west-2:123456789012:document/*"

For Parameter Store API actions, you can provide or restrict access to all parameters in one level
of a hierarchy by using hierarchical names and AWS Identity and Access Management (IAM) policies as
follows:

"Resource": "arn:aws:ssm:us-west-2:123456789012:parameter/Dev/ERP/Oracle/*"

To specify all resources, or when a specific API action does not support ARNs, use the wildcard character
(*) in the Resource element as follows:

"Resource": "*"

Some Systems Manager API actions accept multiple resources. To specify multiple resources in a single
statement, separate their ARNs with commas as follows:

"Resource": ["arn1", "arn2"]

For a list of Systems Manager operations that work with these resource types, see AWS Systems Manager
Permissions Reference (p. 921).

Understanding Resource Ownership

A resource owner is the AWS account that created the resource, regardless of who in the account created
the resources. Specifically, the resource owner is the AWS account of the principal entity (the root
account, an IAM user, or an IAM role) that authenticates the resource creation request. The following
examples illustrate how this works:

• If you use the root account credentials of your AWS account to create a rule, your AWS account is the
owner of the Systems Manager resource.
• If you create an IAM user in your AWS account and grant permissions to create Systems Manager
resources to that user, the user can create Systems Manager resources. However, your AWS account, to
which the user belongs, owns the Systems Manager resources.
• If you create an IAM role in your AWS account with permissions to create Systems Manager resources,
anyone who can assume the role can create Systems Manager resources. Your AWS account, to which
the role belongs, owns the Systems Manager resources.

910
 AWS Systems Manager User Guide
Managing Access to Resources

Managing Access to Resources

A permissions policy describes who has access to what. The following section explains the available
options for creating permissions policies.
Note
This section discusses using IAM in the context of Systems Manager. It doesn't provide detailed
information about the IAM service. For complete IAM documentation, see What Is IAM? in the
IAM User Guide. For information about IAM policy syntax and descriptions, see IAM JSON Policy
Reference in the IAM User Guide.

Policies attached to an IAM identity are referred to as identity-based policies (IAM policies). Policies
attached to a resource are referred to as resource-based policies. Systems Manager supports only
identity-based policies.

Topics
• Identity-Based Policies (IAM Policies) (p. 911)
• Resource-Based Policies (p. 912)

Identity-Based Policies (IAM Policies)

You can attach policies to IAM identities. By creating identity-based IAM policies, you can restrict the
calls and resources that users in your account have access to, and then attach those policies to IAM users.
For more information about how to create IAM roles and to explore example IAM policy statements
for Systems Manager, see Overview of Managing Access Permissions to Your AWS Systems Manager
Resources (p. 907). For example, you can do the following:

• Attach a permissions policy to a user or a group in your account – To grant a user permissions to
view applications, deployment groups, and other Systems Manager resources in the AWS Systems
Manager console, you can attach a permissions policy to a user or a group that the user belongs to.
• Attach a permissions policy to a role (grant cross-account permissions) – To grant cross-account
permissions, you can attach an identity-based permissions policy to an IAM role. For example, the
administrator in Account A can create a role to grant cross-account permissions to another AWS
account (for example, Account B) or an AWS service as follows:

 
1. Account A administrator creates an IAM role and attaches a permissions policy to the role that
grants permissions on resources in Account A.

 
2. Account A administrator attaches a trust policy to the role identifying Account B as the principal
who can assume the role.

 
3. Account B administrator can then delegate permissions to assume the role to any users in Account
B. Doing this allows users in Account B to create or access resources in Account A. If you want to
grant an AWS service permissions to assume the role, the principal in the trust policy can also be an
AWS service principal.

For more information about using IAM to delegate permissions, see Access Management in the IAM
User Guide.

911
 AWS Systems Manager User Guide
Managing Access to Resources

The types of actions that you can control access to with resource-based policies vary depending on the
resource type, as outlined in the following table:

Resource types Action types

All View and list details about resources

Association Create

Delete

Start

Update

Automation definition Start

Stop

Document Create

Maintenance window Delete

Parameter Update

Managed instance Deregister

Register

Managed instance inventory Create

Update

Patch baseline Create

Delete

Deregister

Register

Update

Resource data sync Create

Delete

Session Start

Terminate

Resource-Based Policies
Other AWS services, such as Amazon Simple Storage Service, also support resource-based permissions
policies. For example, you can attach a permissions policy to an S3 bucket to manage access permissions
to that bucket. Systems Manager doesn't support resource-based policies.

912
 AWS Systems Manager User Guide
Specifying Policy Elements: Resources,
Actions, Effects, and Principals

Specifying Policy Elements: Resources, Actions,

Effects, and Principals
For each Systems Manager resource, Systems Manager defines a set of applicable API operations. To
allow you to grant permissions for these API operations, Systems Manager defines a set of actions that
you can specify in a policy. Some API operations can require permissions for more than one action.
For more information about resources and API operations, see AWS Systems Manager Resources and
Operations (p. 908) and AWS Systems Manager Permissions Reference (p. 921). For a list of actions,
see AWS Systems Manager Resources and Operations (p. 908) Actions.

The following are the basic policy elements:

• Resource – You use an Amazon Resource Name (ARN) to identify the resource that the policy applies
to. For Systems Manager resources, you can, use the wildcard character (*) in IAMpolicies. For more
information, see AWS Systems Manager Resources and Operations (p. 908).
• Action – You use action keywords to identify resource operations that you want to allow or deny.
For example, the ssm:GetDocument permission allows the user permissions to perform the
GetDocument operation.
• Effect – You specify the effect that occurs when the user requests the specific action, either allow or
deny. If you don't explicitly grant access to (allow) a resource, access is implicitly denied. You can also
explicitly deny access to a resource, which you might do to make sure that a user cannot access it, even
if a different policy grants access.
• Principal – In identity-based policies (IAM policies), the user that the policy is attached to is the
implicit principal. For resource-based policies, you specify the user, account, service, or other entity
that you want to receive permissions. Systems Manager supports only identity-based policies.

To learn more about IAM policy syntax and descriptions, see IAM JSON Policy Reference in the IAM User
Guide.

For a table showing all of the Systems Manager API actions and the resources that they apply to, see
AWS Systems Manager Permissions Reference (p. 921).

Specifying Conditions in a Policy

When you grant permissions, you can use the language in the access policy to specify the conditions
under which a policy should take effect. For example, you might want a policy to be applied only after
a specific date. For more information about specifying conditions in a policy language, see IAM JSON
Policy Elements: Condition in the IAM User Guide.

To express conditions, you use predefined condition keys.

AWS Systems Manager supports the following condition keys:

• ssm:resourceTag/*
• ssm:Recursive
• ssm:Overwrite

For information about using the ssm:resourceTag/* condition key, see the following topics:

• Restrict Access to Root-Level Commands Through SSM Agent (p. 85)

• Restricting Run Command Access Based on Instance Tags (p. 616)
• Restrict Session Access Based on Instance Tags (p. 585)

913
 AWS Systems Manager User Guide
Using Identity-Based Policies (IAM Policies)

• Controlling Access to Documents Using Tags (p. 788)

• Controlling Access to Parameters Using Tags (p. 834)

For information about using the ssm:Recursive and ssm:Overwrite condition keys, see Organizing
Parameters into Hierarchies (p. 839).

For a list of condition keys supported by each AWS service, see Actions, Resources, and Condition Keys
for AWS Services in the IAM User Guide. For a list of condition keys that can be used in multiple AWS
services, see AWS Global Condition Context Keys in the IAM User Guide.

Using Identity-based Policies (IAM Policies) for

AWS Systems Manager
The following examples of identity-based policies demonstrate how an account administrator can attach
permissions policies to IAM identities (that is, users, groups, and roles) and thereby grant permissions to
perform operations on Systems Manager resources.
Important
We recommend that you first review the introductory topics that explain the basic concepts
and options available to manage access to your Systems Manager resources. For more
information, see Overview of Managing Access Permissions to Your AWS Systems Manager
Resources (p. 907).

Topics
• Permissions Required to Use the AWS Systems Manager Console (p. 914)
• AWS Managed Policies for AWS Systems Manager (p. 915)
• Customer Managed Policy Examples (p. 916)

The following is an example of a permissions policy that allows a user to delete documents with names
that begin with MyDocument- in the us-west-2 region:

{
"Version": "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"ssm:DeleteDocument"
],
"Resource" : [
"arn:aws:ssm:us-west-2:123456789012:document/MyDocument-*"
]
}
]
}

Permissions Required to Use the AWS Systems

Manager Console
To use the AWS Systems Manager console, a user must have a minimum set of permissions that allows
the user to describe other AWS resources for their AWS account. To fully use Systems Manager in the
Systems Manager console, you must have permissions from the following services:

914
 AWS Systems Manager User Guide
AWS Managed Policies for AWS Systems Manager

• AWS Systems Manager

• Amazon Elastic Compute Cloud (Amazon EC2)
• AWS Identity and Access Management (IAM)

You can grant the required permissions with the following policy statement:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:*",
"ec2:describeInstances",
"iam:PassRole",
"iam:ListRoles"
],
"Resource": "*"
}
]
}

If you create an IAM policy that is more restrictive than the minimum required permissions, the console
won't function as intended for users with that IAM policy. To ensure that those users can use the Systems
Manager console, also attach the AmazonSSMReadOnlyAccess managed policy to the user, as described
in AWS Managed Policies for AWS Systems Manager (p. 915).

You don't need to allow minimum console permissions for users that are making calls only to the AWS
CLI or the Systems Manager API.

AWS Managed Policies for AWS Systems Manager

AWS addresses many common use cases by providing standalone IAM policies that are created and
administered by AWS. These AWS managed policies grant necessary permissions for common use cases so
you can avoid having to investigate which permissions are needed. (You can also create your own custom
IAM policies to allow permissions for Systems Manager actions and resources.) For more information, see
AWS Managed Policies in the IAM User Guide.

The following AWS managed policies, which you can attach to users in your account, are specific to AWS
Systems Manager:

• AmazonSSMFullAccess – User trust policy that grants full access to the Systems Manager API and
documents.
• AmazonSSMReadOnlyAccess – User trust policy that grants access to Systems Manager read-only API
actions, such as Get* and List*.
• AmazonSSMAutomationApproverAccess – User trust policy that enables access to view automation
executions and send approval decisions to automation that is waiting for approval.
• AmazonSSMAutomationRole – Service role policy that provides permissions for the AWS Systems
Manager automation service to run activities defined within automation documents. Assign this policy
to administrators and trusted power users.
• AmazonSSMMaintenanceWindowRole – Service role policy for Systems Manager Maintenance
Windows.
• AmazonSSMDirectoryServiceAccess – Instance trust policy that allows SSM Agent to access AWS
Directory Service on behalf of the user for requests to join the domain by the managed instance.
• AmazonSSMManagedInstanceCore – Instance trust policy that enables an instance to use AWS
Systems Manager service core functionality.

915
 AWS Systems Manager User Guide
Customer Managed Policy Examples

• AmazonSSMServiceRolePolicy – Service role policy that provides access to AWS resources managed or
used by AWS Systems Manager.
• AWSResourceAccessManagerServiceRolePolicy – Service role policy containing read-only AWS
Resource Access Manager access to the account's AWS Organizations structure. It also contains IAM
permissions to self-delete the role.
• AmazonEC2RoleforSSM – This policy will be deprecated soon. In its place, use the
AmazonSSMManagedInstanceCore policy to enable AWS Systems Manager service core functionality
on Amazon EC2 instances. For information, see Create an IAM Instance Profile for Systems
Manager (p. 29).

Note
In a hybrid environment, you need an additional IAM role that allows servers and VMs to
communicate with the Systems Manager service. This is the IAM service role for Systems
Manager. This role grants AWS Security Token Service (AWS STS) AssumeRole trust to the
Systems Manager service. The AssumeRole action returns a set of temporary security
credentials (consisting of an access key ID, a secret access key, and a security token). You use
these temporary credentials to access AWS resources that you might not normally have access
to. For more information, see Create an IAM Service Role for a Hybrid Environment (p. 42) and
AssumeRole in AWS Security Token Service API Reference.

Customer Managed Policy Examples

You can create standalone policies that you administer in your own AWS account. We refer to these
as customer managed policies. You can attach these policies to multiple principal entities in your AWS
account. When you attach a policy to a principal entity, you give the entity the permissions that are
defined in the policy. For more information, see Customer Managed Policies in IAM User Guide.

The following examples of user policies grant permissions for various AWS Systems Manager actions.
Use them to limit the Systems Manager access for your IAM users and roles. These policies work when
performing actions in the Systems Manager API, AWS SDKs, or the AWS CLI. For users who use the
console, you need to grant additional permissions specific to the console. For more information, see
Permissions Required to Use the AWS Systems Manager Console (p. 914).
Note
All examples use the US West (Oregon) Region (us-west-2) and contain fictitious account IDs.

Examples

• Example 1: Allow a User to Perform Systems Manager Operations in a Single Region (p. 916)
• Example 2: Allow a User to List Documents for a Single Region (p. 917)

Example 1: Allow a User to Perform Systems Manager

Operations in a Single Region
The following example grants permissions to perform AWS Systems Manager operations only in the us-
west-2 Region:

{
"Version": "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"ssm:*"
],

916
 AWS Systems Manager User Guide
Customer Managed Policy Examples

"Resource" : [
"arn:aws::aws:ssm:us-west-2:111222333444:*"
]
}
]
}

Example 2: Allow a User to List Documents for a Single Region

The following example grants permissions to list all document names that begin with Update in the us-
west-2 Region:

{
"Version": "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"ssm:ListDocuments"
],
"Resource" : [
"arn:aws:ssm:us-west-2:111222333444:document/Update*"
]
}
]
}

Example 3: Allow a User to Use a Specific SSM Document to Run

Commands on Specific Instances
The following example IAM policy allows a user to do the following.

• List Systems Manager documents and document versions.

• View details about documents.
• Send a command using the document specified in the policy. The name of the document is determined
by this entry:

arn:aws:ssm:us-east-2:*:document/SSM-document-name

• Send a command to three instances. The instances are determined by the following entries in the
second Resource section:

"arn:aws:ec2:us-east-2:*:instance/i-02573cafcfEXAMPLE",
"arn:aws:ec2:us-east-2:*:instance/i-0471e04240EXAMPLE",
"arn:aws:ec2:us-east-2:*:instance/i-07782c72faEXAMPLE"

• View details about a command after it has been sent.

• Start and stop Automation executions.
• Get information about Automation executions.

If you want to give a user permission to use this document to send commands on any instance for which
the user currently has access (as determined by their AWS user account), you could specify the following
entry in the Resource section and remove the other instance entries.

"arn:aws:ec2:us-east-2:*:instance/*"

917
 AWS Systems Manager User Guide
Customer Managed Policy Examples

Note that the Resource section includes an Amazon S3 ARN entry:

arn:aws:s3:::S3-bucket-name

You can also format this entry as follows:

arn:aws:s3:::S3-bucket-name/*

-or-

arn:aws:s3:::S3-bucket-name/S3-prefix-name

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ssm:ListDocuments",
"ssm:ListDocumentsVersions",
"ssm:DescribeDocument",
"ssm:GetDocument",
"ssm:DescribeInstanceInformation",
"ssm:DescribeDocumentParameters",
"ssm:DescribeInstanceProperties"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": "ssm:SendCommand",
"Effect": "Allow",
"Resource": [
"arn:aws:ec2:us-east-2:*:instance/i-02573cafcfEXAMPLE",
"arn:aws:ec2:us-east-2:*:instance/i-0471e04240EXAMPLE",
"arn:aws:ec2:us-east-2:*:instance/i-07782c72faEXAMPLE",
"arn:aws:s3:::bucket_name",
"arn:aws:ssm:us-east-2:*:document/SSM-document-name"
]
},
{
"Action": [
"ssm:CancelCommand",
"ssm:ListCommands",
"ssm:ListCommandInvocations"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": "ec2:DescribeInstanceStatus",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": "ssm:StartAutomationExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:::automation-definition/"
]
},
{
"Action": "ssm:DescribeAutomationExecutions ",
"Effect": "Allow",

918
 AWS Systems Manager User Guide
Using Service-Linked Roles

"Resource": [
"*"
]
},
{
"Action": [
"ssm:StopAutomationExecution",
"ssm:GetAutomationExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:::automation-execution/"
]
}
]
}

Using Service-Linked Roles for Systems Manager

AWS Systems Manager uses AWS Identity and Access Management (IAM) service-linked roles. A service-
linked role is a unique type of IAM role that is linked directly to Systems Manager. Service-linked roles
are predefined by Systems Manager and include all the permissions that the service requires to call other
AWS services on your behalf.

A service-linked role makes setting up Systems Manager easier because you don’t have to manually add
the necessary permissions. Systems Manager defines the permissions of its service-linked roles, and
unless defined otherwise, only Systems Manager can assume its roles. The defined permissions include
the trust policy and the permissions policy, and that permissions policy can't be attached to any other
IAM entity.

For information about other services that support service-linked roles, see AWS Services That Work with
IAM and look for the services that have Yes in the Service-Linked Role column. Choose a Yes with a link
to view the service-linked role documentation for that service.

Service-Linked Role Permissions for Systems Manager

Systems Manager uses the service-linked role named AWSServiceRoleForAmazonSSM – AWS Systems
Manager uses this IAM service role to manage AWS resources on your behalf.

The AWSServiceRoleForAmazonSSM service-linked role trusts only ssm.amazonaws.com to assume this

role.

Currently, only two Systems Manager capabilities use the service-linked role:

• Inventory requires a service-linked role. The role enables the system to collect Inventory metadata
from tags and Resource Groups.
• The Maintenance Windows capability can optionally use the service-linked role. The role enables the
Maintenance Windows service to run maintenance tasks on target instances. Note that the service-
linked role for Systems Manager doesn't provide the permissions needed for all scenarios. For more
information, see Should I Use a Service-Linked Role or a Custom Service Role to Run Maintenance
Window Tasks? (p. 445)

The AWSServiceRoleForAmazonSSM service-linked role permissions policy allows Systems Manager to

complete the following actions on all related resources:

• ssm:CancelCommand

919
 AWS Systems Manager User Guide
Creating a Service-Linked Role for Systems Manager

• ssm:GetCommandInvocation
• ssm:ListCommandInvocations
• ssm:ListCommands
• ssm:SendCommand
• ssm:GetAutomationExecution
• ssm:GetParameters
• ssm:StartAutomationExecution
• iam:PassRole
• ec2:DescribeInstanceAttribute
• ec2:DescribeInstanceStatus
• ec2:DescribeInstances
• lambda:InvokeFunction
• resource-groups:ListGroups
• resource-groups:ListGroupResources
• states:DescribeExecution
• states:StartExecution
• tag:GetResources

Creating a Service-Linked Role for Systems Manager

You can use the IAM console to create a service-linked role with the AWS Service Role for AWS Systems
Manager use cases (Inventory and Maintenance Windows). In the IAM CLI or the IAM API, create a
service-linked role with the ssm.amazonaws.com service name. For more information, see Creating a
Service-Linked Role in the IAM User Guide.

For maintenance windows only, you don't need to manually create a service-linked role. When you create
a maintenance window task in the AWS Management Console, the AWS CLI, or the Systems Manager API,
Systems Manager creates the service-linked role for you if you choose not to provide a custom service
role.

If you delete this service-linked role, and then need to create it again, you can use the same process to
recreate the role in your account.

Editing a Service-Linked Role for Systems Manager

Systems Manager does not allow you to edit the AWSServiceRoleForAmazonSSM service-linked
role. After you create a service-linked role, you cannot change the name of the role because various
entities might reference the role. However, you can edit the description of the role using IAM. For more
information, see Editing a Service-Linked Role in the IAM User Guide.

Deleting a Service-Linked Role for Systems Manager

If you no longer need to use any feature or service that requires a service-linked role, then we
recommend that you delete that role. That way you don’t have an unused entity that is not actively
monitored or maintained. You can use the IAM console, the IAM CLI, or the IAM API to manually delete
the service-linked role. To do this, you must first manually clean up the resources for your service-linked
role, and then you can manually delete it.

Because the Systems Manager service-linked role can be used by both the Inventory and Maintenance
Windows capabilities, ensure that neither is using the role before attempting to delete it.

920
 AWS Systems Manager User Guide
Supported Regions for Systems
Manager Service-Linked Roles

• Inventory: If you delete the service-linked role used by Systems Manager Inventory, then the Inventory
data for tags and Resource Groups will no longer be synchronized. You must clean up the resources for
your service-linked role before you can manually delete it.
• Maintenance Windows: You can't delete the service-linked role if any maintenance window tasks
currently rely on the role. You must first remove the service-linked role from the tasks before you can
delete the role.

Note
If the Systems Manager service is using the role when you try to delete the tags, Resource
Groups, or maintenance window tasks, then the deletion might fail. If that happens, wait for a
few minutes and try the operation again.

To delete Systems Manager resources used by the AWSServiceRoleForAmazonSSM

1. To delete tags, see Adding and Deleting Tags on an Individual Resource.

2. To delete Resource Groups, see Delete Groups from AWS Resource Groups.
3. For information about how to delete maintenance window tasks, see Update or Delete Maintenance
Window Tasks (Console) (p. 461).

To manually delete the service-linked role using IAM

Use the IAM console, the IAM CLI, or the IAM API to delete the AWSServiceRoleForAmazonSSM service-
linked role. For more information, see Deleting a Service-Linked Role in the IAM User Guide.

Supported Regions for Systems Manager Service-

Linked Roles
Systems Manager supports using service-linked roles in all of the regions where the service is available.
For more information, see AWS Regions and Endpoints for Systems Manager.

AWS Systems Manager Permissions Reference

The following table lists the AWS Systems Manager API operations and their corresponding actions for
which you can grant permissions. Use this table as a reference when setting up Access Control (p. 907)
and writing permissions policies to attach to an IAM identity (identity-based policies). . You specify
the actions in the policy's Action field. To specify an action, use the ssm: prefix followed by the
API operation name (for example, ssm:GetDocument and ssm:CreateDocument. To specify
multiple actions in a single statement, separate them with commas (for example, "Action":
["ssm:action1", "ssm:action2"]). For the resource value in the policy's Resource field, you
specify an ARN. To specify multiple actions or resources, use a wildcard character (*) in your ARN. For
example, ssm:* specifies all of the Systems Manager actions, and ssm:Get* specifies all of the Systems
Manager actions that begin with the word Get. The following example grants access to all documents
with names that begin with West:

arn:aws:ssm:us-west-2:111222333444:document:West*

For more information about wildcards, see IAM Identifiers in IAM User Guide. For a list of Systems
Manager resources with the ARN format, see AWS Systems Manager Resources and Operations (p. 908).

To express conditions, use AWS-wide condition keys in your Systems Manager policies. For a complete list
of AWS-wide keys, see AWS Global Condition Context Keys in the IAM User Guide.

921
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Specifying multiple actions or resources

Systems Manager API Operations and Required Permissions for Actions

AddTagsToResource

Action: ssm:AddTagsToResource

Required to add or overwrite tags for a specified resource.

CancelCommand

Action: ssm:CancelCommand

Required to attempt to cancel the command with the specified command ID.
CancelMaintenanceWindowExecution

Action: ssm:CancelMaintenanceWindowExecution

Required to stop a maintenance window execution that is already in progress.

CreateActivation

Action: ssm:CreateActivation

Required to register an on-premises server or virtual machine with Amazon EC2 so that it can be
managed using Run Command.
CreateAssociation

Action: ssm:CreateAssociation

Required to associate a Systems Manager document with the specified instances or targets.
CreateAssociationBatch

Action: ssm:CreateAssociationBatch

Required to associate multiple Systems Manager documents with the specified instances or targets.
CreateDocument

Action: ssm:CreateDocument

Required to create a Systems Manager document.

CreateMaintenanceWindow

Action: ssm:CreateMaintenanceWindow

Required to create a maintenance window.

CreateOpsItem

Action: ssm:CreateOpsItem

Required to create an OpsItem.

CreatePatchBaseline

Action: ssm:CreatePatchBaseline

Required to create a patch baseline.

CreateResourceDataSync

Action: ssm:CreateResourceDataSync

922
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Required to create a resource data sync configuration for a single Amazon S3 bucket.
DeleteActivation

Action: ssm:DeleteActivation

Required to delete an activation.

DeleteAssociation

Action: ssm:DeleteAssociation

Required to disassociate the specified Systems Manager document from the specified instance.
DeleteDocument

Action: ssm:DeleteDocument

Required to delete a Systems Manager document and all instance associations to the document.
DeleteInventory

Action: ssm:DeleteInventory

Required to delete a custom inventory type, or the data associated with a custom Inventory type.
DeleteMaintenanceWindow

Action: ssm:DeleteMaintenanceWindow

Required to delete a maintenance window.

DeleteParameter

Action: ssm:DeleteParameter

Required to delete a parameter from the system.

DeleteParameters

Action: ssm:DeleteParameters

Required to delete one or more parameters from the system.

DeletePatchBaseline

Action: ssm:DeletePatchBaseline

Required to delete a patch baseline.

DeleteResourceDataSync

Action: ssm:DeleteResourceDataSync

Required to delete a resource data sync configuration.

DeregisterManagedInstance

Action: ssm:DeregisterManagedInstance

Required to remove a server or virtual machine from the list of registered servers.
DeregisterPatchBaselineForPatchGroup

Action: ssm:DeregisterPatchBaselineForPatchGroup

Required to remove a patch group from a patch baseline.

DeregisterTargetFromMaintenanceWindow

Action: ssm:DeregisterTargetFromMaintenanceWindow

923
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Required to remove a target from a maintenance window.

DeregisterTaskFromMaintenanceWindow

Action: ssm:DeregisterTaskFromMaintenanceWindow

Required to remove a task from a maintenance window.

DescribeActivations

Action: ssm:DescribeActivations

Required to view details about an activation, such as the date and time the activation was created,
the expiration date, and the IAM role assigned to the instances in the activation.
DescribeAssociation

Action: ssm:DescribeAssociation

Required to view the associations for the specified Systems Manager document or instance.
DescribeAssociationExecutions

Action: ssm:DescribeAssociationExecutions

Required to view all executions for a specific association ID.

DescribeAssociationExecutionTargets

Action: ssm:DescribeAssociationExecutionTargets

Required to view information about a specific execution of a specific association.

DescribeAutomationExecutions

Action: ssm:DescribeAutomationExecutions

Required to view information about all active and terminated Automation executions.
DescribeAutomationStepExecutions

Action: ssm:DescribeAutomationStepExecutions

Required to view information about all active and terminated step executions in an Automation
workflow.
DescribeAvailablePatches

Action: ssm:DescribeAvailablePatches

Required to view information about patches that could be included in a patch baseline.
DescribeDocument

Action: ssm:DescribeDocument

Required to view information about the specified Systems Manager document.

DescribeDocumentPermission

Action: ssm:DescribeDocumentPermission

Required to view the permissions for a Systems Manager document.

DescribeEffectiveInstanceAssociations

Action: ssm:DescribeEffectiveInstanceAssociations

Required to view information about assocations for one or more instances.

924
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

DescribeEffectivePatchesForPatchBaseline

Action: ssm:DescribeEffectivePatchesForPatchBaseline

Required to view information about the current effective patches (the patch and the approval state)
for the specified patch baseline. Applies only to Windows Server patch baselines.
DescribeInstanceAssociationsStatus

Action: ssm:DescribeInstanceAssociationsStatus

Required to view the status of the associations for one or more instances.
DescribeInstanceInformation

Action: ssm:DescribeInstanceInformation

Required to view information about one or more instances.

DescribeInstancePatches

Action: ssm:DescribeInstancePatches

Required to view information about the patches on a specified instance and their state relative to
the patch baseline being used for the instance.
DescribeInstancePatchStates

Action: ssm:DescribeInstancePatchStates

Required to view information about the high-level patch state of one or more instances.
DescribeInstancePatchStatesForPatchGroup

Action: ssm:DescribeInstancePatchStatesForPatchGroup

Required to view the high-level patch state for the instances in a specified patch group.
DescribeInventoryDeletions

Action: ssm:DescribeInventoryDeletions

Required to describe a specific delete inventory operation.

DescribeMaintenanceWindowExecutions

Action: ssm:DescribeMaintenanceWindowExecutions

Required to view information about the execution of a maintenance window. This includes details
about when the maintenance window was scheduled to be active and information about tasks
registered and run with the maintenance window.
DescribeMaintenanceWindowExecutionTaskInvocations

Action: ssm:DescribeMaintenanceWindowExecutionTaskInvocations

Required to retrieve information about the individual task executions (one per target) for a particular
task run as part of a maintenance window execution.
DescribeMaintenanceWindowExecutionTasks

Action: ssm:DescribeMaintenanceWindowExecutionTasks

Required to view information about the tasks that have been run for a specified maintenance
window execution.
DescribeMaintenanceWindows

Action: ssm:DescribeMaintenanceWindows

925
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Required to view information about the maintenance windows created in an AWS account.
DescribeMaintenanceWindowSchedule

Action: ssm:DescribeMaintenanceWindowSchedule

Required to retrieve information about upcoming executions of a maintenance window.

DescribeMaintenanceWindowsForTarget

Action: ssm:DescribeMaintenanceWindowsForTarget

Required to retrieve information about the maintenance window targets or tasks that an instance is
associated with.
DescribeMaintenanceWindowTargets

Action: ssm:DescribeMaintenanceWindowTargets

Required to view information about the targets registered with a specified maintenance window.
DescribeMaintenanceWindowTasks

Action: ssm:DescribeMaintenanceWindowTasks

Required to view information about the tasks in a specified maintenance window.

DescribeOpsItems

Action: ssm:DescribeOpsItems

Required to query a set of OpsItems.

DescribeParameters

Action: ssm:DescribeParameters

Required to view information about one or more parameters.

DescribePatchBaselines

Action: ssm:DescribePatchBaselines

Required to view information about the patch baselines in an AWS account.

DescribePatchGroups

Action: ssm:DescribePatchGroups

Required to view information about all patch groups that have been registered with patch baselines.
DescribePatchGroupState

Action: ssm:DescribePatchGroupState

Required to view information about the high-level aggregated patch compliance state for a patch
group.
DescribePatchProperties

Action: ssm:DescribePatchProperties

Required to view information about the properties of available patches.

DescribeSessions

Action: ssm:DescribeSessions

Required to retrieve a list of all active sessions (both connected and disconnected) or terminated
Session Manager sessions.

926
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

GetAutomationExecution

Action: ssm:GetAutomationExecution

Required to view detailed information about a particular Automation execution.

GetCommandInvocation

Action: ssm:GetCommandInvocation

Required to view detailed information about command execution for an invocation or plugin.
GetConnectionStatus

Action: ssm:GetConnectionStatus

Required to retrieve the Session Manager connection status for an instance to determine whether it
is connected and ready to receive Session Manager connections.
GetDefaultPatchBaseline

Action: ssm:GetDefaultPatchBaseline

Required to view information about the default patch baseline.

GetDeployablePatchSnapshotForInstance

Action: ssm:GetDeployablePatchSnapshotForInstance

Required to view the current snapshot for the patch baseline used by the instance. Used primarily by
the AWS-RunPatchBaseline Systems Manager document.
GetDocument

Action: ssm:GetDocument

Required to view the contents of a specified Systems Manager document.

GetInventory

Action: ssm:GetInventory

Required to view information about inventory items.

GetInventorySchema

Action: ssm:GetInventorySchema

Required to view inventory type names for the account, or to return a list of attribute names for a
specific inventory item type.
GetMaintenanceWindow

Action: ssm:GetMaintenanceWindow

Required to view information about a specified maintenance window.

GetMaintenanceWindowExecution

Action: ssm:GetMaintenanceWindowExecution

Required to view information about a specific task run as part of a maintenance window execution.
GetMaintenanceWindowExecutionTask

Action: ssm:GetMaintenanceWindowExecutionTask

Required to view information about a specific task run as part of a maintenance window execution.

927
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

GetMaintenanceWindowExecutionTaskInvocation

Action: ssm:GetMaintenanceWindowExecutionTaskInvocation

Required to retrieve a task invocation, which is a specific task running on a specific target.
GetMaintenanceWindowTask

Action: ssm:GetMaintenanceWindowTask

Required to list the tasks in a maintenance window.

GetOpsItem

Action: ssm:GetOpsItem

Required to view information about an OpsItem by using the ID.

GetOpsSummary

Action: ssm:GetOpsSummary

Required to view a summary of OpsItems based on specified filters and aggregators.

GetParameter

Action: ssm:GetParameter

Required to view information about a specified parameter, including the parameter name, type, and
value.
GetParameterHistory

Action: ssm:GetParameterHistory

Required to view historical information about a specified parameter. In addition to parameter name,
type, and value, returns the parameter description, query key ID, last modified date, and ARN of the
AWS user who last modified the parameter.
GetParameters

Action: ssm:GetParameters

Required to view information about parameters.

GetParametersByPath

Action: ssm:GetParametersByPath

Required to view information about parameters in a hierarchical structure.

GetPatchBaseline

Action: ssm:GetPatchBaseline

Required to view information about a patch baseline.

GetPatchBaselineForPatchGroup

Action: ssm:GetPatchBaselineForPatchGroup

Required to view information about the patch baseline that should be used for a specified patch
group.
GetServiceSetting

Action: ssm:GetServiceSetting

928
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Required to query the current account-level setting for an AWS service. The service setting defines
how a user interacts with or uses a service or a feature of a service.
LabelParameterVersion

Action: ssm:LabelParameterVersion

Required to attach labels to a parameter version.

ListAssociations

Action: ssm:ListAssociations

Required to view the associations for the specified Systems Manager document or instance.
ListAssociationVersions

Action: ssm:ListAssociationVersions

Required to retrieve all versions of an association for a specific association ID.

ListCommandInvocations

Action: ssm:ListCommandInvocations

Required to view a list of invocations, or copies of commands sent to a specific instance.

ListCommands

Action: ssm:ListCommands

Required to view a list of commands requested by users of the AWS account.

ListComplianceItems

Action: ssm:ListComplianceItems

Required to retrieve a list of compliance statuses for different resource types for a specific resource
ID.
ListComplianceSummaries

Action: ssm:ListComplianceSummaries

Required to retrieve a summary count of compliant and non-compliant resources for a compliance
type.
ListDocuments

Action: ssm:ListDocuments

Required to view a list of Systems Manager documents.

ListDocumentVersions

Action: ssm:ListDocumentVersions

Required to view information about the versions of a document.

ListInventoryEntries

Action: ssm:ListInventoryEntries

Required to view information about inventory items on an instance.

ListResourceComplianceSummaries

Action: ssm:ListResourceComplianceSummaries

929
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

Required to retrieve a resource-level summary count, including information about compliant and
non-compliant statuses.
ListResourceDataSync

Action: ssm:ListResourceDataSync

Required to view information about resource data sync configurations, including when a sync last
attempted to start, the last sync status, and the last time a sync completed successfully.
ListTagsForResource

Action: ssm:ListTagsForResource

Required to view a list of tags assigned to a specified resource.

ModifyDocumentPermission

Action: ssm:ModifyDocumentPermission

Required to shared a Systems Manager document publicly or privately.

PutComplianceItems

Action: ssm:PutComplianceItems

Required to register a compliance type and other compliance details on a designated resource.
PutInventory

Action: ssm:PutInventory

Required to add or update custom inventory items on one or more instances.

PutParameter

Action: ssm:PutParameter

Required to add one or more parameters to the system.

RegisterDefaultPatchBaseline

Action: ssm:RegisterDefaultPatchBaseline

Required to define the default patch baseline.

RegisterPatchBaselineForPatchGroup

Action: ssm:RegisterPatchBaselineForPatchGroup

Required to register a patch baseline for a patch group.

RegisterTargetWithMaintenanceWindow

Action: ssm:RegisterTargetWithMaintenanceWindow

Required to register a target with a maintenance window.

RegisterTaskWithMaintenanceWindow

Action: ssm:RegisterTaskWithMaintenanceWindow

Required to register a task with a maintenance window.

RemoveTagsFromResource

Action: ssm:RemoveTagsFromResource

Required to remove tags from a specified resource.

930
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

ResetServiceSetting

Action: ssm:ResetServiceSetting

Required to reset the service setting for the account to the default value as provisioned by the AWS
service team.
ResumeSession

Action: ssm:ResumeSession

Required to reconnect a session to an instance after it has been disconnected. This command is for
use by client machines to automatically reconnect during intermittent network issues only.
SendAutomationSignal

Action: ssm:SendAutomationSignal

Required to send a signal to an Automation execution to change the current behavior or status of
the execution.
SendCommand

Action: ssm:SendCommand

Required to run commands on one or more managed instances.

StartAssociationsOnce

Action: ssm:StartAssociationsOnce

Required to run an association immediately and only one time, which can be helpful when
troubleshooting associations.
StartAutomationExecution

Action: ssm:StartAutomationExecution

Required to start running an Automation document.

StartSession

Action: ssm:StartSession

Required to initiate a connection to a target (for example, an instance) for a Session Manager
session.
StopAutomationExecution

Action: ssm:StopAutomationExecution

Required to start running an Automation document..

TerminateSession

Action: ssm:TerminateSession

Required to permanently end a session and close the data connection between the Session Manager
client and SSM Agent on the instance.
UpdateAssociation

Action: ssm:UpdateAssociation

Required to update an association. Updates can be made only to the document version, schedule,
parameters, and Amazon S3 output of an association.

931
 AWS Systems Manager User Guide
AWS Systems Manager Permissions Reference

UpdateAssociationStatus

Action: ssm:UpdateAssociationStatus

Required to update the status of the Systems Manager document associated with a specified
instance.
UpdateDocument

Action: ssm:UpdateDocument

Required to update the content, version, or name of a document.

UpdateDocumentDefaultVersion

Action: ssm:UpdateDocumentDefaultVersion

Required to set the default version of a document.

UpdateMaintenanceWindow

Action: ssm:UpdateMaintenanceWindow

Required to update one or more parameters in a maintenance window.

UpdateMaintenanceWindowTarget

Action: ssm:UpdateMaintenanceWindowTarget

Required to modify the target of an existing maintenance window.

UpdateMaintenanceWindowTask

Action: ssm:UpdateMaintenanceWindowTask

Required to modify the task assigned to a maintenance window.

UpdateManagedInstanceRole

Action: ssm:UpdateManagedInstanceRole

Required to assign an Amazon Identity and Access Management (IAM) role to a managed instance, or
to change the assigned IAM role.
UpdateOpsItem

Action: ssm:UpdateOpsItem

Required to edit or change an OpsItem.

UpdatePatchBaseline

Action: ssm:UpdatePatchBaseline

Required to update one or more fields in an existing patch baseline.

UpdateServiceSetting

Action: ssm:UpdateServiceSetting

Required to update the service setting for the account.

932
 AWS Systems Manager User Guide
Cron and Rate Expressions

AWS Systems Manager Reference

The following information and topics can help you better implement Systems Manager solutions.

Principal

In AWS Identity and Access Management (IAM), you can grant or deny a service access to resources
using the Principal policy element. The Principal policy element value for Systems Manager is
ssm.amazonaws.com.
Supported Regions and Endpoints

See AWS Systems Manager in the Amazon Web Services General Reference.
Service Limits

See AWS Systems Manager in the Amazon Web Services General Reference.
API Reference Guide

See AWS Systems Manager API Reference.

CLI Command Reference

See AWS Systems Manager section of the AWS CLI Command Reference.
AWS Tools for PowerShell Cmdlet Reference

See AWS Systems Manager section of the AWS Tools for PowerShell Cmdlet Reference.
SSM Agent Repository on GitHub

See aws/amazon-ssm-agent.
Ask a Question

AWS Systems Manager Developer Forum

AWS News Blog

Management Tools

More Reference Topics

• Reference: Cron and Rate Expressions for Systems Manager (p. 933)
• Reference: Maintenance Windows Scheduling and Active Period Options (p. 939)
• Reference: ec2messages, ssmmessages, and Other API Calls (p. 941)

Reference: Cron and Rate Expressions for Systems

Manager
When you create an AWS Systems Manager maintenance window or a State Manager association, you
specify a schedule for when the window or the association should run. You can specify a schedule in
the form of either a time-based entry, called a cron expression, or a frequency-based entry, called a rate
expression. For maintenance windows, you can also specify a time stamp in Coordinated Universal Time
(UTC) format when you create a maintenance window so that it runs once at the specified time.

When you create either type of resource programmatically or by using a command line tool such as the
AWS CLI, you must specify a schedule parameter with a valid cron or rate expression (or time stamp for
maintenance windows) in the correct format.

933
 AWS Systems Manager User Guide
General Information About Cron and Rate Expressions

When you use the AWS Systems Manager console to create a maintenance window or association, you
can specify a schedule using a valid cron or rate expression. You can also use tools in the user interface
that simplify the process of creating your schedule.

Maintenance Window Examples

To create maintenance windows using the AWS CLI, you include the --schedule parameter with a cron or
rate expression or a time stamp. For example:

aws ssm create-maintenance-window --name "My-Cron-Maintenance-Window" --schedule

"cron(0 16 ? * TUE *)" --schedule-timezone "America/Los_Angeles" --start-date
2019-01-01T00:00:00-08:00 --end-date 2019-06-30T00:00:00-08:00 --duration 4 --cutoff 1

aws ssm create-maintenance-window --name "My-Rate-Maintenance-Window" --schedule "rate(7

days)" --duration 4 --schedule-timezone "America/Los_Angeles" --cutoff 1

aws ssm create-maintenance-window --name "My-TimeStamp-Maintenance-Window" --schedule

"at(2019-07-07T13:15:30)" --duration 4 --schedule-timezone "America/Los_Angeles" --cutoff
1

Association Examples

To create State Manager associations using the AWS CLI, you include the --schedule-expression
parameter with a cron or rate expression. For example:

aws ssm create-association --association-name "My-Cron-Association" --schedule-expression

"cron(0 0 2 ? * SUN *)" --targets Key=tag:ServerRole,Values=WebServer --name AWS-
UpdateSSMAgent

aws ssm create-association --association-name "My-Rate-Association" --schedule-expression

"rate(7 days)" --targets Key=tag:ServerRole,Values=WebServer --name AWS-UpdateSSMAgent

Topics
• General Information About Cron and Rate Expressions (p. 934)
• Cron and Rate Expressions for Associations (p. 937)
• Cron and Rate Expressions for Maintenance Windows (p. 938)

General Information About Cron and Rate

Expressions
Cron expressions for Systems Manager have six required fields. A seventh field, the Seconds field (the
first in a cron expression), is optional. Fields are separated by a space.

Cron Expression Examples

Minutes Hours Day of Month Day of week Year Meaning

month

0 10 * * ? * Run at 10:00
am (UTC)
every day

934
 AWS Systems Manager User Guide
General Information About Cron and Rate Expressions

Minutes Hours Day of Month Day of week Year Meaning

month

15 12 * * ? * Run at 12:15
PM (UTC)
every day

0 18 ? * MON-FRI * Run at
6:00 PM
(UTC) every
Monday
through
Friday

0 8 1 * ? * Run at 8:00
AM (UTC)
every 1st
day of the
month

0/15 * * * ? * Run every

15 minutes

0/10 * ? * MON-FRI * Run every

10 minutes
Monday
through
Friday

0/5 8-17 ? * MON-FRI * Run every

5 minutes
Monday
through
Friday
between
8:00 AM
and 5:55 PM
(UTC)

Supported Values

The following table shows supported values for required cron entries.
Note
Cron expressions for associations do not support all these values. For information, see Cron and
Rate Expressions for Associations (p. 937).

Supported Values for Cron Expressions

Field Values Wildcards

Minutes 0-59 ,-*/

Hours 0-23 ,-*/

Day-of-month 1-31 ,-*?/LW

Month 1-12 or JAN-DEC ,-*/

935
 AWS Systems Manager User Guide
General Information About Cron and Rate Expressions

Field Values Wildcards

Day-of-week 1-7 or SUN-SAT ,-*?/L

Year 1970-2199 ,-*/

Note
You cannot specify a value in the Day-of-month and in the Day-of-week fields in the same cron
expression. If you specify a value in one of the fields, you must use a ? (question mark) in the
other field.

Wildcards

The following table shows the wildcard values that cron expressions support.

Supported Wildcards for Cron Expressions

Wildcard Description

, The , (comma) wildcard includes additional values.

In the Month field, JAN,FEB,MAR would include
January, February, and March.

- The - (dash) wildcard specifies ranges. In the Day

field, 1-15 would include days 1 through 15 of the
specified month.

* The * (asterisk) wildcard includes all values in the

field. In the Hours field, * would include every
hour.

/ The / (forward slash) wildcard specifies

increments. In the Minutes field, you could enter
1/10 to specify every tenth minute, starting from
the first minute of the hour. So 1/10 specifies the
first, 11th, 21st, and 31st minute, and so on.

? The ? (question mark) wildcard specifies one or

another. In the Day-of-month field you could
enter 7 and if you didn't care what day of the
week the 7th was, you could enter ? in the Day-of-
week field.

L The L wildcard in the Day-of-month or Day-of-

week fields specifies the last day of the month or
week.

W The W wildcard in the Day-of-month field

specifies a weekday. In the Day-of-month field,
3W specifies the day closest to the third weekday
of the month.

Note
Cron expressions that lead to rates faster than five (5) minute are not supported. Support for
specifying both a day-of-week and a day-of-month value is not complete. You must currently
use the question mark (?) character in one of these fields.

For more information about cron expressions, see CRON expression at the Wikipedia website.

936
 AWS Systems Manager User Guide
Cron and Rate Expressions for Associations

Rate Expressions

Rate expressions have the following two required fields. Fields are separated by white space.

Required Fields for Rate Expressions

Field Values

Value positive number, such as 1 or 15

Unit minute

minutes

hour

hours

day

days

If the value is equal to 1, then the unit must be singular. Similarly, for values greater than 1, the unit
must be plural. For example, rate(1 hours) and rate(5 hour) are not valid, but rate(1 hour)
and rate(5 hours) are valid.

Cron and Rate Expressions for Associations

This section includes examples of cron and rate expressions for State Manager associations. Before you
create one of these expressions, be aware of the following restrictions.

• Associations only support the following cron expressions: every 1/2, 1, 2, 4, 8, or 12 hours; every day
or every week at a specific time.
• Associations only support the following rate expressions: intervals of 30 minutes or greater and less
than 31 days.
• If you specify the optional Seconds field, its value can only be 0 (zero). For example: cron(0 */30 *
* * ? *)

The following table presents cron examples for associations using the required six fields.

Cron Examples for Associations

Example Details

cron(0/30 * * * ? *) Every 30 minutes

cron(0 0/1 * * ? *) Every hour

cron(0 0/2 * * ? *) Every 2 hours

cron(0 0/4 * * ? *) Every 4 hours

cron(0 0/8 * * ? *) Every 8 hours

cron(0 0/12 * * ? *) Every 12 hours

cron(15 13 ? * * *) Every day at 1:15 PM

cron(15 13 ? * MON *) Every Monday at 1:15 PM

937
 AWS Systems Manager User Guide
Cron and Rate Expressions for Maintenance Windows

Here are some rate examples for associations.

Rate Examples for Associations

Example Details

rate(30 minutes) Every 30 minutes

rate(1 hour) Every hour

rate(5 hours) Every 5 hours

rate(15 days) Every 15 days

Cron and Rate Expressions for Maintenance Windows

This section includes examples of cron and rate expressions for maintenance windows.

Unlike State Manager associations, maintenance windows support all cron and rate expressions,
including values other than 0 (zero) in the seconds field.

For example, the following 6-field cron expression runs a maintenance window at 9:30 AM every day:

cron(30 09 ? * * *)

By adding a value to the Seconds field, the following 7-field cron expression runs a maintenance
window at 9:30:24 AM every day:

cron(24 30 09 ? * * *)

The following table provides additional 6-field cron examples for maintenance windows.

Cron Examples for Maintenance Windows

Example Details

cron(0 2 ? * THU#3 *) 02:00 AM the third Thursday of every month

cron(15 10 ? * * *) 10:15 AM every day

cron(15 10 ? * MON-FRI *) 10:15 AM every Monday, Tuesday, Wednesday,

Thursday and Friday

cron(0 2 L * ? *) 02:00 AM on the last day of every month

cron(15 10 ? * 6L *) 10:15 AM on the last Friday of every month

The following table provides rate examples for maintenance windows.

Rate Examples for Maintenance Windows

Example Details

rate(30 minutes) Every 30 minutes

rate(1 hour) Every hour

938
 AWS Systems Manager User Guide
Maintenance Windows Scheduling
and Active Period Options

Example Details

rate(5 hours) Every 5 hours

rate(25 days) Every 25 days

Reference: Maintenance Windows Scheduling and

Active Period Options
When you create a maintenance window, you must specify how often the maintenance window runs
by using a Cron or Rate expression (p. 933). Optionally, you can specify a date range during which
the maintenance window can run on its regular schedule, as well as a time zone on which to base that
regular schedule.

Be aware, however, that the time zone option and the start date/end date options do not influence each
other. Any start date and end date times that you specify (with or without an offset for your time zone)
determine only the valid period during which the maintenance window can run on its schedule. A time
zone option determines the international time zone that the maintenance window schedule is based on
during its valid period.
Note
You specify start and end dates in ISO-8601 timestamp format. For example:
2019-04-07T14:29:00-08:00
You specify time zones in Internet Assigned Numbers Authority (IANA) format. For example:
America/Chicago, Europe/Berlin or Asia/Tokyo

Examples
• Example 1: Specify a maintenance window start date (p. 939)
• Example 2: Specify a maintenance window start date and end date (p. 940)
• Example 3: Create a maintenance window that runs only once (p. 940)

Example 1: Specify a maintenance window start date

Say that you use the AWS CLI to create a maintenance window with the following options:

• --start-date 2019-01-01T00:00:00-05:00
• --schedule-timezone "America/Los_Angeles"
• --schedule "cron(0 09 ? * FRI *)"

For example:

aws ssm create-maintenance-window --name "My-LAX-Maintenance-Window" --start-date

2019-01-01T00:00:00-08:00 --schedule-timezone "America/Los_Angeles" --schedule "cron(0
09 ? * FRI *)"

This means that the maintenance window won't run until after its specified start date and time, which
is at Midnight US Eastern Time on Tuesday, January 1, 2019. (This time zone is five hours behind UTC
time.) Taken together, the --schedule-timezone and --schedule values mean that the maintenance
window runs at 9 AM every Friday in the US Pacific Time Zone (represented by "America/Los Angeles" in
IANA format). The first execution in the enabled period will be on Friday, January 4th, 2019, at 9 AM US
Pacific Time.

939
 AWS Systems Manager User Guide
Example 2: Specify a maintenance
window start date and end date

Example 2: Specify a maintenance window start date

and end date
Suppose that next you create a maintenance window with these options:

• --start-date 2019-01-01T00:03:15+09:00
• --end-date 2019-06-30T00:06:15+09:00
• --schedule-timezone "Asia/Tokyo"
• --schedule "rate(7 days)"

For example:

aws ssm create-maintenance-window --name "My-NRT-Maintenance-Window" --start-date

2019-01-01T00:03:15+09:00 --end-date 2019-06-30T00:06:15+09:00 --schedule-timezone "Asia/
Tokyo" --schedule "rate(7 days)""

The enabled period for this maintenance window begins at 3:15 AM Japan Standard Time on January 1,
2019. The valid period for this maintenance window ends at 6:15 AM Japan Standard Time on Sunday,
June 30, 2019. (This time zone is nine hours ahead of UTC time.) Taken together, the --schedule-
timezone and --schedule values mean that the maintenance window runs at 3:15 AM every Tuesday
in the Japan Standard Time Zone (represented by "Asia/Tokyo" in IANA format). This is because the
maintenance window runs every seven days, and it becomes active at 3:15 AM on Tuesday, January 1st.
The last execution is at 3:15 AM Japan Standard Time on Tuesday, June 25, 2019. This is the last Tuesday
before the enabled maintenance window period ends five days later.

Example 3: Create a maintenance window that runs

only once
Now you create a maintenance window with this option:

• --schedule "at(2020-07-07T15:55:00)"

For example:

aws ssm create-maintenance-window --name "My-One-Time-Maintenance-Window --schedule

"at(2020-07-07T15:55:00)" --duration 5 --cutoff 2 --allow-unassociated-targets

This maintenance window runs just once, at 3:55 PM UTC time on July 7, 2020. The maintenance window
is enabled to run up to five hours, as needed, but new tasks are prevented from starting two hours
before the end of the maintenance window period.

Related Content

• Reference: Cron and Rate Expressions for Systems Manager (p. 933)
• Create a Maintenance Window (Console) (p. 456)
• Tutorial: Create and Configure a Maintenance Window (AWS CLI) (p. 463)
• CreateMaintenanceWindow in the AWS Systems Manager API Reference
• create-maintenance-window in the AWS Systems Manager section of the AWS CLI Command Reference
• Time Zone Database on the IANA website

940
 AWS Systems Manager User Guide
ec2messages, ssmmessages, and Other API Calls

Reference: ec2messages, ssmmessages, and Other

API Calls
If you monitor API calls, you might see calls to the following APIs.

• ec2messages:AcknowledgeMessage
• ec2messages:DeleteMessage
• ec2messages:FailMessage
• ec2messages:GetEndpoint
• ec2messages:GetMessages
• ec2messages:SendReply
• ssmmessages:CreateControlChannel
• ssmmessages:CreateDataChannel
• ssmmessages:OpenControlChannel
• ssmmessages:OpenDataChannel
• ssm:UpdateInstanceInformation
• ssm:ListInstanceAssociations
• ssm:DescribeInstanceProperties
• ssm:DescribeDocumentParameters

These special calls are used by Systems Manager for various operations.

ec2messages API calls

Calls to ec2messages:* APIs are calls to the Amazon Message Delivery Service endpoint. Systems
Manager uses this endpoint to make calls from SSM Agent to the Systems Manager service in the cloud.
This endpoint is required to send and receive commands. For more information, see Actions, Resources,
and Condition Keys for Amazon Message Delivery Service

ssmmessages API calls

Systems Manager uses the ssmmessages endpoint to make calls from SSM Agent to the Session
Manager service in the cloud. This endpoint is required to create and delete session channels with the
Session Manager service in the cloud.

Instance-related API calls

UpdateInstanceInformation: SSM Agent calls the Systems Manager service in the cloud every five
minutes to provide heartbeat information. This call is necessary to maintain a heartbeat with the agent
so that the service knows the agent is functioning as expected.

ListInstanceAssociations: The agent calls this API to see if a new Systems Manager State Manager
association is available. This API is required for State Manager to function.

DescribeInstanceProperties and DescribeDocumentParameters: Systems Manager calls these

APIs to render specific nodes in the Amazon EC2 console. The DescribeInstanceProperties API
displays the Managed Instances node in the left navigation. The DescribeDocumentParameters API
displays the Documents node in the left navigation.

941
 AWS Systems Manager User Guide

Use Cases and Best Practices

This topic lists common use cases and best practices for AWS Systems Manager capabilities. If available,
this topic also includes links to relevant blog posts and technical documentation.
Note
The title of each section here is an active link to the corresponding section in the technical
documentation.

Automation (p. 142)

• Create self-service runbooks for infrastructure as Automation documents.

• Use Automation to simplify creating AMIs from the AWS Marketplace or custom AMIs, using public
SSM documents or by authoring your own workflows.
• Build and maintain AMIs (p. 400) using the AWS-UpdateLinuxAmi and AWS-UpdateWindowsAmi
Automation documents, or using custom Automation documents that you create.

Inventory (p. 512)

• Use Systems Manager Inventory with AWS Config to audit your application configurations over time.

Maintenance Windows (p. 444)

• Define a schedule to perform potentially disruptive actions on your instances such as OS patching,
driver updates, or software installations.

Parameter Store (p. 825)

• Use Parameter Store to centrally manage global configuration settings.

• Use Parameter Store to encrypt and manage secrets by using AWS KMS (p. 875).
• Use Parameter Store with ECS task definitions to store secrets.

Patch Manager (p. 683)

• Use patch manager to rollout patches at scale and increase fleet compliance visibility across your
instances.

Run Command (p. 613)

• Manage Instances at Scale without SSH Access Using EC2 Run Command.
• Audit all API calls made by on or on behalf of Run Command using AWS CloudTrail.
• Use the targets and rate control features in Run Command to perform a staged command
execution (p. 622).
• Use fine-grained access permissions for Run Command (and all Systems Manager capabilities) by using
AWS Identity and Access Management (IAM) policies (p. 916).

State Manager (p. 645)

• Update SSM Agent at least once a month using the pre-configured AWS-UpdateSSMAgent
document (p. 681).

942
 AWS Systems Manager User Guide

• Bootstrap EC2 Instances on launch using EC2Config for Windows

• (Windows) Upload the PowerShell or DSC module to Amazon S3, and use AWS-
InstallPowerShellModule.
• Use Amazon EC2 tags to create application groups for your instances. And then target instances using
the Targets parameter instead of specifying individual instance IDs.
• Automatically remediate findings generated by Amazon Inspector by using Systems Manager.
• Use a centralized configuration repository for all of your SSM documents, and share documents across
your organization (p. 790).

Managed Instances (p. 563)

• Systems Manager requires accurate time references in order to perform its operations. If your
instance's date and time are not set correctly, they may not match the signature date of your API
requests. In some cases, this will lead to errors or incomplete functionality. For example, instances with
incorrect time settings will not be included in your lists of managed instances.

For information on setting the time on your instances, see the following topics:
• Setting the Time for Your Linux Instance
• Setting the Time for a Windows Instance

943
 AWS Systems Manager User Guide

Document History
The following table describes the important changes to the documentation since the last release of AWS
Systems Manager. For notification about updates to this documentation, you can subscribe to an RSS
feed.
Important
An updated version of SSM Agent is released whenever new capabilities are added to Systems
Manager or updates are made to existing capabilities. If an older version of the agent is running
on an instance, some SSM Agent processes can fail. For that reason, we recommend that you
automate the process of keeping SSM Agent up-to-date on your instances. For information, see
Automate Updates to SSM Agent (p. 86). To be notified about SSM Agent updates, subscribe to
the SSM Agent Release Notes page on GitHub.

• API version: 2014-11-06

update-history-change update-history-description update-history-date

New Ansible SSM Document: You can create State Manager September 24, 2019
AWS-ApplyAnsiblePlaybooks associations that run Ansible
(p. 944) Playbooks by using the AWS-
ApplyAnsiblePlaybooks
document. This document
offers the following benefits for
running Playbooks:

• Support for running complex

Playbooks
• Support for downloading
Playbooks from GitHub and
Amazon Simple Storage
Service (Amazon S3)
• Support for compressed
Playbook structure
• Enhanced logging
• Ability to specify which
Playbook to run when
Playbooks are bundled

For more information, see

Creating Associations that Run
Ansible Playbooks

Port forwarding support for Session Manager now supports August 29, 2019
Session Manager (p. 944) port forwarding sessions.
Port forwarding allows you to
securely create tunnels between
your instances deployed in
private subnets, without the
need to start the SSH service
on the server, to open the SSH
port in the security group, or to
use a bastion host. Similar to

944
 AWS Systems Manager User Guide

SSH tunnels, port forwarding

allows you to forward traffic
between your laptop to open
ports on your instance. Once
port forwarding is configured,
you can connect to the local port
and access the server application
running inside the instance.
For more information, see the
following topics:

• Port Forwarding Using AWS

Systems Manager Session
Manager on the AWS News
Blog
• Starting a Session (Port
Forwarding)

Specify a default parameter You can now specify a default August 27, 2019
tier or automate tier parameter tier to use for
selection (p. 944) requests to create or update a
parameter that do not specify
a tier. You can set the default
tier to standard parameters,
advanced parameters, or a
new option, Intelligent-Tiering.
Intelligent-Tiering evaluates
each PutParameter request and
creates an advanced parameter
only when required. (Advanced
parameters are required if the
size of the parameter value is
more than 4 KB, a parameter
policy is associated with the
parameter, or the maximum
10,000 parameters supported
for the standard tier are already
created.) For more information
about specifying a default tier
and using Intelligent-Tiering, see
Specifying a Default Parameter
Tier.

Working with Associations The Working with Associations August 26, 2019
section updated with CLI and section has been updated
PowerShell procedures (p. 944) to include procedural
documentation for managing
associations using the AWS CLI
or AWS Tools for PowerShell.
For information see, Working
with Associations in Systems
Manager.

945
 AWS Systems Manager User Guide

Working with Automation The Working with Automation August 20, 2019
Executions section updated Executions section has been
with CLI and PowerShell updated to include procedural
procedures (p. 944) documentation for running
Automation workflows using
the AWS CLI or AWS Tools for
PowerShell. For information
see, Working with Automation
Executions.

OpsCenter integrates with OpsCenter integrates with August 7, 2019

Application Insights (p. 944) Amazon CloudWatch Application
Insights for .NET and SQL
Server. This means you can
automatically create OpsItems
for problems detected in your
applications. For information
about how to configure
Application Insights to create
OpsItems, see Setting Up Your
Application in the Amazon
CloudWatch User Guide.

New console feature: AWS Quick Setup is a new feature in August 7, 2019
Systems Manager Quick the Systems Manager console
Setup (p. 944) that helps you quickly configure
several Systems Manager
components on your Amazon
EC2 instances. Specifically, Quick
Setup helps you configure the
following components on the
instances you choose or target
by using tags:

• An AWS Identity and Access

Management (IAM) instance
profile role for Systems
Manager.
• A scheduled, bi-monthly
update of SSM Agent.
• A scheduled collection of
Inventory metadata every 30
minutes.
• A daily scan of your instances
to identify missing patches.
• A one-time installation and
configuration of the Amazon
CloudWatch agent.
• A scheduled, monthly update
of the CloudWatch agent.

For more information, see AWS

Systems Manager Quick Setup.

946
 AWS Systems Manager User Guide

Register a resource group In addition to registering July 23, 2019

as a maintenance window managed instances as the target
target (p. 944) of a maintenance window, you
can now register a resource
group as a maintenance window
target. Maintenance Windows
supports all the AWS resource
types that are supported
by AWS Resource Groups
including AWS::EC2::Instance,
AWS::DynamoDB::Table,
AWS::OpsWorks::Instance,
AWS::Redshift::Cluster, and
more. With this release you
can also send commands to a
resource group, for example
by using the Run Command
console or the AWS CLI send-
command command. For more
information, see the following
topics:

• Assign Targets to a
Maintenance Window
(Console)
• Examples: Register Targets
with a Maintenance Window
• Using Targets and Rate
Controls to Send Commands
to a Fleet

Simplified package creation and Distributor has a new, simplified July 22, 2019
versioning with AWS Systems package creation workflow
Manager Distributor (p. 944) that can generate a package
manifest, scripts, and file hashes
for you. You can also use the
simplified workflow when you
add a version to an existing
package.

New Document categories Systems Manager includes a new July 18, 2019
pane for Systems Manager Document categories pane when
Automation (p. 944) you run an Automation in the
console. Use this pane to filter
Automation documents based
on their purpose.

947
 AWS Systems Manager User Guide

Verify user permissions to When a user in your account July 9, 2019

access the default Session uses the AWS CLI to start
Manager configuration a Session Manager session
document (p. 944) and doesn't specify a
configuration document
in the command, Systems
Manager uses the default
configuration document SSM-
SessionManagerRunShell.
You can now verify that the user
has been granted permission
to access this document by
adding a condition element for
ssm:SessionDocumentAccessCheck
to the IAM user's policy. For
information, see Enforce
Document Permission Check for
Default CLI Scenario.

Support for starting Session By default, Session Manager July 9, 2019

Manager sessions using sessions are launched using
operating system user the credentials of a system-
credentials (p. 944) generated ssm-user account
that is created on a managed
instance. On Linux machines,
you can now instead launch
sessions using the credentials
of an operating system account.
For information, see Enable Run
As Support for Linux Instances.

Support for starting Session You can now use the AWS CLI July 9, 2019
Manager sessions using to start an SSH session on a
SSH (p. 944) managed instance using Session
Manager. For information about
enabling SSH sessions with
Session Manager, see (Optional)
Enable SSH Session Manager
Sessions. For information about
starting an SSH session using
Session Manager, see Starting a
Session (SSH).

Support for changing passwords You can now reset passwords July 9, 2019
on managed instances (p. 944) on machines that you manage
using Systems Manager
(managed instances). You can
reset the password using the
Systems Manager console or
the AWS CLI. For information,
see Resetting Passwords on
Managed Instances.

948
 AWS Systems Manager User Guide

Revisions to "What is AWS The introductory content in June 10, 2019

Systems Manager?" (p. 944) What is AWS Systems Manager?
has been expanded to provide
a broader introduction to the
service and reflect Systems
Manager capabilities that
have been released recently.
In addition, other content in
the section has been moved
into individual topics for better
discoverability.

New Systems Manager OpsCenter provides a central June 6, 2019

capability: OpsCenter (p. 944) location where operations
engineers and IT professionals
can view, investigate, and
resolve operational work
items (OpsItems) related to
AWS resources. OpsCenter is
designed to reduce mean time to
resolution for issues impacting
AWS resources. This Systems
Manager capability aggregates
and standardizes OpsItems
across services while providing
contextual investigation data
about each OpsItem, related
OpsItems, and related resources.
OpsCenter also provides Systems
Manager Automation documents
(runbooks) that you can use
to quickly resolve issues. You
can specify searchable, custom
data for each OpsItem. You
can also view automatically-
generated summary reports
about OpsItems by status and
source. For more information,
see AWS Systems Manager
OpsCenter.

Changes to Systems Manager The Systems Manager left June 6, 2019

left navigation pane in the AWS navigation pane in the AWS
Management Console (p. 944) Management Console includes
new headings, including a new
heading for Ops Center, that
provide a more logical grouping
of Systems Manager capabilities.

949
 AWS Systems Manager User Guide

Revised tutorial for creating Tutorial: Create and Configure May 31, 2019
and configuring a maintenance a Maintenance Window (AWS
window using the AWS CLI) has been overhauled to
CLI (p. 944) provide a simple path through
the practice steps. You create
a single maintenance window,
identify a single target, and
set up a simple task for the
maintenance window to run.
Along the way, we provide
information and examples you
can use to create your own
task registration commands,
including information for using
pseduo parameters such as
{{TARGET_ID}}. For additional
information and examples, see
the following topics:

• Examples: Register Targets

with a Maintenance Window
• Examples: Register Tasks with
a Maintenance Window
• About register-task-with-
maintenance-windows
Options
• About Pseudo Parameters

Notifications about SSM Agent To be notified about SSM Agent May 24, 2019
updates (p. 944) updates, subscribe to the SSM
Agent Release Notes page on
GitHub.

Receive notifications or trigger The topic Set Up Notifications May 22, 2019
actions based on changes in or Trigger Actions Based on
Parameter Store (p. 944) Parameter Store Events now
helps you set up Amazon
CloudWatch Events rules
to respond to changes in
Parameter Store. You can
receive notifications or trigger
other actions when any of the
following occur:

• A parameter is created,
updated, or deleted.
• A parameter label version is
created, updated, or deleted.
• A parameter expires, is going
to expire, or hasn't changed in
a specified period of time.

950
 AWS Systems Manager User Guide

Major revisions to Setting We have expanded and May 15, 2019

Up and Getting Started reorganized the Setting Up
content (p. 944) and Getting Started content
in the AWS Systems Manager
User Guide. Setting Up content
has been divided into two
sections. One section focuses
on tasks for setting up Systems
Manager to configure and
manage your Amazon EC2
instances. The other focuses
on tasks for setting up Systems
Manager to configure and
manage your on-premises
servers and virtual machines
(VMs) in a hybrid environment.
Both sections now present all
setup topics as major numbered
steps, in the recommended
order of completion. A new
Getting Started chapter focuses
on helping end-users get
started with Systems Manager
after account and service
configuration tasks have been
completed.

• Setting Up AWS Systems

Manager
• Setting Up AWS Systems
Manager for Hybrid
Environments
• Getting Started with AWS
Systems Manager

951
 AWS Systems Manager User Guide

Include patches for Microsoft Patch Manager now supports May 7, 2019
applications in patch baselines patch updates for Microsoft
(Windows) (p. 944) applications on Windows
Server instances. Previously,
only patches for the Windows
Server operating system
were supported. Patch
Manager provides two
predefined patch baselines
for Windows Server instances.
The patch baseline AWS-
WindowsPredefinedPatchBaseline-
OS applies to operating
system patches only. AWS-
WindowsPredefinedPatchBaseline-
OS-Applications applies
to both the Windows Server
operating system and Microsoft
applications on Windows. For
information about creating a
custom patch baseline that
includes patches for Microsoft
applications, see the first
procedure in Create a Custom
Patch Baseline. Also, as part
of this update, the names of
AWS-provided predefined patch
baselines are being changed.
For more information, see
Predefined Baselines.

Examples for registering The new topic Examples: May 3, 2019

maintenance window targets Register Targets with a
using the AWS CLI (p. 944) Maintenance Window provides
three sample commands to
demonstrate different ways you
can specify the targets for a
maintenance window when you
use the AWS CLI. The topic also
explains the best use case for
each of the sample commands.

952
 AWS Systems Manager User Guide

Updates to Patch Group The topic About Patch Groups May 1, 2019
topics (p. 944) has been updated to include
a section on how managed
instances determine the
appropriate patch baseline to
use during patching operations.
Additionally, instructions have
been added for using the AWS
CLI or Systems Manager console
to add Patch Group tags to your
managed instances and how to
add a Patch Group to a patch
baseline. For more information
see Create a Patch Group and
Add a Patch Group to a Patch
Baseline.

953
 AWS Systems Manager User Guide

New Parameter Store Parameter Store offers the April 25, 2019
features (p. 944) following new features:

• Advanced parameters:
Parameter Store now enables
you to individually configure
parameters to use either a
standard-parameter tier (the
default tier) or an advanced-
parameter tier. Advanced
parameters offer a larger size
limit for the parameter value,
a higher limit for the number
of parameters you can create
per account and Region, and
the ability to use parameter
policies. For more information
about advanced parameters,
see About Systems Manager
Advanced Parameters.
• Parameter policies:
Parameter policies help you
manage a growing set of
parameters by enabling you
to assign specific criteria
to a parameter, such as an
expiration date or time to
live. Parameter policies are
especially helpful in forcing
you to update or delete
passwords and configuration
data stored in Parameter
Store. Parameter policies are
only available for parameters
that use the advanced-
parameter tier. For more
information, see Working with
Parameter Policies.
• Higher throughput: You can
now increase the Parameter
Store throughput limit
to a maximum of 1,000
transactions per second.
For more information, see
Increasing Parameter Store
Throughput.

954
 AWS Systems Manager User Guide

Updates to the Automation The Automation section has April 17, 2019
section (p. 944) been updated for improved
discoverability. In addition, four
new topics have been added to
the Automation section:

• Running an Automation
Workflow Manually (p. 154)
• Running an Automation
Workflow with
Approvers (p. 160)
• Running Automation
Workflows Based on
Triggers (p. 177)
• Sharing a Systems
Manager Automation
Document (p. 238)

Encrypt session data using an By default, Session Manager April 4, 2019

AWS KMS key (p. 944) uses TLS 1.2 to encrypt session
data transmitted between the
local machines of users in your
account and your Amazon EC2
instances. Now you can choose
to further encrypt that data
using a customer master key
(CMK) that has been created in
AWS Key Management Service.
You can use a key that has been
created in your AWS account or
one that has been shared with
you from another account. For
information about specifying a
CMK to encrypt session data, see
Enable AWS KMS Key Encryption
of Session Data (Console), Create
Session Manager Preferences
(AWS CLI), or Update Session
Manager Preferences (AWS CLI).

Configuring Amazon SNS Added instructions for using March 6, 2019

Notifications for AWS Systems the AWS CLI or Systems
Manager (p. 944) Manager console to configure
Amazon SNS notifications
for Run Command and Run
Command tasks registered to a
maintenance window. For more
information see Configuring
Amazon SNS Notifications for
AWS Systems Manager.

955
 AWS Systems Manager User Guide

Advanced instances for AWS Systems Manager offers March 4, 2019

servers and VMs in hybrid a standard-instances tier and
environments (p. 944) an advanced-instances tier for
servers and VMs in your hybrid
environment. The standard-
instances tier enables you to
register a maximum of 1,000
servers or VMs per AWS account
per AWS Region. If you need to
register more than 1,000 servers
or VMs in a single account and
Region, then use the advanced-
instances tier. You can create as
many instances as you like in the
advanced-instances tier, but all
instances configured for Systems
Manager are available on a
pay-per-use basis. Advanced
instances also enable you to
connect to your hybrid machines
by using AWS Systems Manager
Session Manager. Session
Manager provides interactive
shell access to your instances.
For more information about
enabling advanced instances, see
Using the Advanced-Instances
Tier.

Create State Manager You can create State Manager February 28, 2019
associations that use shared SSM associations that use SSM
documents (p. 944) Command and Automation
documents shared from
other AWS accounts. Creating
associations by using shared
SSM documents helps to keep
your Amazon EC2 and hybrid
infrastructure in a consistent
state even when instances are
not in the same account. For
information about sharing
SSM documents, see AWS
Systems Manager Documents.
For information about creating
a State Manager association, see
Create an Association.

View lists of Systems Manager The new topic Monitoring February 25, 2019
events supported for Systems Manager Events with
Amazon CloudWatch Events Amazon CloudWatch Events
rules (p. 944) provides a summary of the
various events emitted by
Systems Manager for which you
can set up event monitoring
rules in CloudWatch Events.

956
 AWS Systems Manager User Guide

Add tags when you Systems Manager now supports February 24, 2019
create Systems Manager the ability to add tags to certain
resources (p. 944) resource types when you create
them. The resources you can
tag when you create them
with the AWS CLI or an SDK
include maintenance windows,
patch baselines, Parameter
Store parameters, and SSM
documents. You can also assign
tags to a managed instance
when you create an activation
for it. When you use the Systems
Manager console, you can add
tags to maintenance windows,
patch baselines, and parameters.

Automatic IAM role creation Previously you had to create February 14, 2019
for Systems Manager an AWS Identity and Access
Inventory (p. 944) Management (IAM) role and
attach separate policies to this
role to view inventory data on
the Inventory Detail View page
in the console. You no longer
need to create this role or attach
policies to it. When you choose
a Remote Data Sync on the
Inventory Detail View page,
Systems Manager automatically
creates the Amazon-
GlueServicePolicyForSSM
role and assigns the Amazon-
GlueServicePolicyForSSM-
{Amazon S3 bucket
name} policy and the
AWSGlueServiceRole policy to
it. For more information, see
Querying Inventory Data from
Multiple Regions and Accounts.

Maintenance Windows Added two new walkthroughs February 11, 2019

walkthroughs to update SSM to the Maintenance Windows
Agent (p. 944) documentation. The
walkthroughs detail how to
use the Systems Manager
console or the AWS CLI to
create a maintenance window
that keeps SSM Agent up-to-
date automatically. For more
information, see Maintenance
Windows Walkthroughs.

Using Parameter Store public Added short section describing January 31, 2019
parameters (p. 944) Parameter Store public
parameters. For more
information, see Using Systems
Manager Public Parameters.

957
 AWS Systems Manager User Guide

Use the AWS CLI to Added instructions for using January 22, 2019
Create Session Manager the AWS CLI to create Session
Preferences (p. 944) Manager preferences, such as
CloudWatch Logs, Amazon S3
bucket logging options, and
session encryption settings.
For more information, see Use
the AWS CLI to Create Session
Manager Preferences.

Executing Systems Manager AWS Systems Manager State January 22, 2019
Automations by using State Manager now supports creating
Manager (p. 944) associations that use SSM
Automation documents. State
Manager previously supported
only command and policy
documents, which meant
that you could only create
associations that targeted
managed instances. With
support for SSM Automation
documents, you can now create
associations that target different
types of AWS resources. For
more information, see Executing
Systems Manager Automations
by using State Manager.

Reference updates for Cron The reference topic Cron and December 6, 2018
and Rate expressions and Rate Expressions for Systems
maintenance window scheduling Manager has been revised.
options (p. 944) The new version provides
more examples and improved
explanations of how to use
cron and rate expressions to
schedule your maintenance
windows and State Manager
associations. In addition, the
new topic Maintenance Windows
Scheduling and Active Period
Options explains how the
various schedule-related options
for maintenance windows (Start
date, End date, Time zone,
Schedule frequency) relate to
one another.

Updates to the Systems Manager The Systems Manager December 4, 2018

Prerequisites topic (p. 944) Prerequisites topic has been
updated to provide information
about supported operating
system versions in a more
detailed tabular format, along
with other changes in the page
for improved readability.

958
 AWS Systems Manager User Guide

Enable SSM Agent debug You can enable SSM Agent November 30, 2018
logging (p. 944) debug logging by editing the
seelog.xml.template file on the
managed instance. For more
information, see Enable SSM
Agent Debug Logging.

Support for ARM64 processor AWS Systems Manager now November 26, 2018
architectures (p. 944) supports ARM64 versions of
the Amazon Linux 2, Red Hat
Enterprise Linux 7.6, and Ubuntu
Server (18.04 LTS and 16.04 LTS)
operating systems. For more
information, see the instructions
for installing Amazon Linux
2, RHEL, and Ubuntu Server
18.04 and 16.04 LTS with Snap
packages. For more information
about the A1 instance type, see
General Purpose Instances in the
Amazon EC2 User Guide for Linux
Instances.

Create and deploy packages by AWS Systems Manager November 20, 2018
using AWS Systems Manager Distributor lets you package
Distributor (p. 944) your own software—or
find AWS-provided agent
software packages, such as
AmazonCloudWatchAgent—to
install on AWS Systems Manager
managed instances. Distributor
publishes resources, such as
software packages, to AWS
Systems Manager managed
instances. Publishing a package
advertises specific versions of
the package's document—a
Systems Manager document
that you create when you add
the package in Distributor—
to managed instances that you
identify by managed instance
IDs, AWS account IDs, tags,
or an AWS Region. For more
information, see AWS Systems
Manager Distributor.

959
 AWS Systems Manager User Guide

Concurrently run AWS Systems You can concurrently run AWS November 19, 2018
Manager Automations across Systems Manager Automations
multiple AWS Regions and across multiple AWS Regions
AWS accounts from a central and AWS accounts or AWS
account (p. 944) Organizational Units (OUs) from
an Automation management
account. Concurrently executing
Automations in multiple Regions
and accounts or OUs reduces
the time required to administer
your AWS resources while
enhancing the security of your
computing environment. For
more information see Executing
Automations in Multiple AWS
Regions and Accounts.

Query inventory data from Systems Manager Inventory November 15, 2018
multiple AWS Regions and integrates with Amazon Athena
accounts (p. 944) to help you query inventory data
from multiple AWS Regions and
accounts. Athena integration
uses Resource Data Sync so
that you can view inventory
data from all of your managed
instances on the Inventory
Detail View page in the AWS
Systems Manager console. For
more information see Querying
Inventory Data from Multiple
Regions and Accounts.

960
 AWS Systems Manager User Guide

Create State Manager You can run Managed Object November 15, 2018
associations that run MOF Format (MOF) files to enforce
files (p. 944) a desired state on Windows
Server managed instances
with State Manager by using
the AWS-ApplyDSCMofs
SSM document. The AWS-
ApplyDSCMofs document has
two execution modes. With the
first mode, you can configure
the association to scan and
report if the managed instances
are currently in the desired
state defined in the specified
MOF files. In the second mode,
you can run the MOF files and
change the configuration of
your instances based on the
resources and their values
defined in the MOF files. The
AWS-ApplyDSCMofs document
enables you to download and
run MOF configuration files
from Amazon Simple Storage
Service (Amazon S3), a local
share, or from a secure web
site with an HTTPS domain. For
more information, see Creating
Associations that Run MOF Files.

Restrict administrative Session Manager sessions are November 13, 2018

access in Session Manager launched using the credentials
sessions (p. 944) of a user account that is
created with default root or
administrator privileges called
ssm-user. Information about
restricting administrative control
for this account is now available
in the topic Disable or Enable
ssm-user Account Administrative
Permissions.

YAML examples in Automation The Automations Actions October 31, 2018

Actions Reference (p. 944) Reference now includes a YAML
sample for each action that
already includes a JSON sample.

961
 AWS Systems Manager User Guide

Assign compliance severity levels You can now assign compliance October 26, 2018
to associations (p. 944) severity levels to State Manager
associations. These severity
levels are reported in the
Compliance Dashboard and
can also be used to filter your
compliance reports. The severity
levels you can assign include
Critical, High, Medium, Low,
and Unspecified. For more
information, see Create an
Association (Console).

Use targets and rate controls Control the execution of October 23, 2018
with Automation and State Automations and State Manager
Manager (p. 944) associations across your
fleet of resources by using
targets, concurrency, and
error thresholds. For more
information see Using Targets
and Rate Controls to Run
Automation Workflows on a
Fleet and Using Targets and Rate
Controls with State Manager
Associations.

Specify active time ranges and You can also specify dates that October 9, 2018
international time zones for a maintenance window should
maintenance windows (p. 944) not run before or after (start
date and end date), and you
can specify the international
time zone on which to base
the maintenance window
schedule. For more information
see Create a Maintenance
Window (Console) and Update a
Maintenance Window (AWS CLI).

Maintain a custom list of patches The new 'InstallOverrideList' October 5, 2018

for your patch baseline in an S3 parameter in the SSM document
bucket (p. 944) 'AWS-RunPatchBaseline' lets
you specify an https URL or an
Amazon Simple Storage Service
(Amazon S3) path-style URL to
a list of patches to be installed.
This patch installation list, which
you maintain in an S3 bucket
in YAML format, overrides
the patches specified by the
default patch baseline. For more
information, see Parameter
name: InstallOverrideList.

962
 AWS Systems Manager User Guide

Expanded control over whether Previously, if a patch in your October 5, 2018

patch dependencies are Rejected patches list was
installed (p. 944) identified as a dependency
of another patch, it would
still be installed. Now you can
choose whether to install these
dependencies or block them
from being installed. For more
information, see Create a Patch
Baseline.

Create dynamic Automation The aws:branch Automation September 26, 2018

workflows with conditional action enables you to create a
branching (p. 944) dynamic Automation workflow
that evaluates multiple choices
in a single step and then
jumps to a different step in the
Automation document based on
the results of that evaluation.
For more information, see
Creating Dynamic Automation
Workflows with Conditional
Branching.

Use the AWS CLI to Instructions for using the CLI September 25, 2018
Update Session Manager to update Session Manager
Preferences (p. 944) preferences, such as CloudWatch
Logs and Amazon S3 bucket
logging options, have been
added to the AWS Systems
Manager User Guide. For
information, see Use the AWS
CLI to Update Session Manager
Preferences.

Set up patching options more Patch Manager has been September 22, 2018
easily with the new 'Configure updated with a new system
patching' page (p. 944) for setting up patching
configurations. On the
Configure patching page,
you can specify multiple
patching options in a single
location, including associating
a maintenance window with
a patching configuration and
changing the patch baseline
associated with a patch group.
For more information, see About
Patching Configurations and
Create a Patching Configuration.

Updated SSM Agent Session Manager now requires September 17, 2018
requirement for Session SSM Agent version 2.3.68.0
Manager (p. 944) or later. For more information
about Session Manager
prerequisites, see Complete
Session Manager Prerequisites.

963
 AWS Systems Manager User Guide

Manage instances without Now available, Session Manager September 11, 2018
opening inbound ports or is a fully managed AWS Systems
maintaining bastion hosts using Manager capability that lets
Session Manager (p. 944) you manage your Amazon
EC2 instances through an
interactive one-click browser-
based shell or through the AWS
CLI. Session Manager provides
secure and auditable instance
management without the need
to open inbound ports, maintain
bastion hosts, or manage SSH
keys. Session Manager also
makes it easy to comply with
corporate policies that require
controlled access to instances,
strict security practices, and
fully auditable logs with
instance access details, while still
providing end users with simple
one-click cross-platform access
to your Amazon EC2 instances.
For more information, see Learn
More About Session Manager.

Invoking other AWS Services You can invoke other AWS August 28, 2018
from a Systems Manager services and other Systems
Automation Workflow (p. 944) Manager capabilities in your
Automation workflow by
using three new Automation
actions (or plugins) in your
Automation documents. For
more information, see For more
information, see Invoking other
AWS Services from a Systems
Manager Automation Workflow.

Use Systems Manager- The topic Specifying Conditions August 18, 2018
specific condition keys in IAM in a Policy has been updated to
policies (p. 944) list the IAM condition keys for
Systems Manager that you can
incorporate in policies. You can
use these keys to specify the
conditions under which a policy
should take effect. The topic
also includes links to example
policies and other related topics.

964
 AWS Systems Manager User Guide

Aggregate Inventory data with Groups enable you to quickly August 16, 2018
groups to see which instances see a count of which managed
are and aren't configured instances are and aren’t
to collect an Inventory configured to collect one or
type (p. 944) more Inventory types. With
groups, you specify one or more
Inventory types and a filter
that uses the exists operator.
For more information, see
Aggregating Inventory Data.

View history and change You can now view history August 9, 2018
tracking for Inventory and change tracking for
and Configuration Inventory collected from your
Compliance (p. 944) managed instances. You can also
viewing history and changing
tracking for Patch Manager
patching and State Manager
associations reported by
Configuration Compliance. For
more information, see Viewing
Inventory History and Change
Tracking.

Systems Manager service- The Maintenance Windows August 2, 2018

linked role extends support service requires a set of IAM
for maintenance window permissions in order to run
tasks (p. 944) maintenance window tasks on
your instances. Previously, the
only option was to create a
custom IAM role to supply these
permissions. The service-linked
role for Systems Manager has
now been enhanced to provide
these permissions, giving you
two IAM role options. For more
information, see Should I Use a
Service-Linked Role or a Custom
Service Role to Run Maintenance
Windows Tasks?

965
 AWS Systems Manager User Guide

Parameter Store integrates with Parameter Store is now July 26, 2018
Secrets Manager (p. 944) integrated with AWS Secrets
Manager so that you can retrieve
Secrets Manager secrets when
using other AWS services that
already support references to
Parameter Store parameters.
These services include Amazon
EC2, Amazon Elastic Container
Service, AWS Lambda,
AWS CloudFormation, AWS
CodeBuild, AWS CodeDeploy,
and other Systems Manager
capabilities. By using Parameter
Store to reference Secrets
Manager secrets, you create
a consistent and secure
process for calling and using
secrets and reference data in
your code and configuration
scripts. For information, see
Referencing AWS Secrets
Manager Secrets from Parameter
Store Parameters.

Attach labels to Parameter Store A parameter label is a user- July 26, 2018
parameters (p. 944) defined alias to help you
manage different versions
of a parameter. When you
modify a parameter, Systems
Manager automatically saves
a new version and increments
the version number by one. A
label can help you remember
the purpose of a parameter
version when there are multiple
versions. For information, see
Labeling Parameters.

Create dynamic Automation By default, the steps (or July 18, 2018
workflows (p. 944) actions) that you define in
the mainSteps section of an
Automation document run
in sequential order. After
one action completes, the
next action specified in the
mainSteps section begins.
With this release, you can now
create Automation workflows
that perform conditional
branching. This means that
you can create Automation
workflows that dynamically
respond to condition changes
and jump to a specified step.
For information, see Creating
Dynamic Automation Workflows.

966
 AWS Systems Manager User Guide

SSM Agent now pre-installed on Beginning with instances created July 7, 2018
Ubuntu Server 16.04 AMIs using from Ubuntu Server 16.04 AMIs
Snap (p. 944) identified with 20180627, the
SSM Agent is pre-installed using
Snap packages. On instances
created from earlier AMIs,
you should continue using
deb installer packages. For
information, see About SSM
Agent installations on 64-bit
Ubuntu Server 16.04 instances.

Review minimum S3 permissions The new topic Minimum S3 July 5, 2018

required by SSM Agent (p. 944) Bucket Permissions for SSM
Agent provides information
about the Amazon Simple
Storage Service (Amazon S3)
buckets that resources might
need to access to perform
Systems Manager operations.
You can specify these buckets
in a custom policy if you want
to limit Amazon S3 bucket
access for an instance profile or
VPC endpoint to the minimum
required to use Systems
Manager.

View complete execution history The new topic Viewing July 2, 2018
for a specific State Manager Association Histories describes
association ID (p. 944) how to view all executions for a
specific association ID and then
view execution details for one or
more resources.

Patch Manager introduces You can now use Patch Manager June 26, 2018
support for Amazon Linux to apply patches to Amazon
2 (p. 944) Linux 2 instances. For general
information about Patch
Manager operating system
support, see Patch Manager
Prerequisites. For information
about the supported key-value
pairs for Amazon Linux 2 when
defining a patch filter, see
PatchFilter in the AWS Systems
Manager API Reference.

Send command output The new topic Configuring June 18, 2018
to Amazon CloudWatch Amazon CloudWatch Logs for
Logs (p. 944) Run Command describes how to
send Run Command output to
CloudWatch Logs.

967
 AWS Systems Manager User Guide
Earlier Updates

Quickly create or delete You can use AWS June 11, 2018
Resource Data Sync for CloudFormation to create
Inventory by using AWS or delete a Resource Data
CloudFormation (p. 944) Sync for Systems Manager
Inventory. To use AWS
CloudFormation, add the
AWS::SSM::ResourceDataSync
resource to your AWS
CloudFormation template. For
more information, see Working
with AWS CloudFormation
Templates in the AWS
CloudFormation User Guide.
You can also manually create
a Resource Data Sync for
Inventory as described in
Configuring Resource Data Sync
for Inventory.

AWS Systems Manager User The HTML version of the June 6, 2018
Guide update notifications now Systems Manager User Guide
available through RSS (p. 944) now supports an RSS feed of
updates that are documented
in the Systems Manager
Documentation Update History
page. The RSS feed includes
updates made in June, 2018,
and later. Previously announced
updates are still available
in the Systems Manager
Documentation Update History
page. Use the RSS button in the
top menu panel to subscribe to
the feed.

Specify an exit code in The new topic Rebooting June 3, 2018

scripts to reboot managed Managed Instance from Scripts
instances (p. 944) describes how to instruct
Systems Manager to reboot
managed instances by specifying
an exit code in scripts that you
run with Run Command.

Create an event in Amazon The new topic Viewing Inventory June 1, 2018
CloudWatch Events whenever Delete Actions in CloudWatch
custom Inventory is deleted Events describes how to
configure Amazon CloudWatch
Events to create an event
anytime a user deletes custom
Inventory.

Earlier Updates
The following table describes important changes in each release of the AWS Systems Manager User Guide
before June 2018.

968
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Inventory all You can easily inventory all managed instances in your AWS May 3, 2018
managed instances in account by creating a global inventory association. For more
your AWS account information, see Inventory All Managed Instances in Your AWS
Account (p. 524).
Note
Global inventory associations are available
in SSM Agent version 2.0.790.0 or later. For
information about how to update SSM Agent on
your instances, see Update SSM Agent by using Run
Command (p. 620).

SSM Agent installed SSM Agent is installed, by default, on Ubuntu Server 18.04 May 2, 2018
by default on Ubuntu LTS 64-bit and 32-bit AMIs.
Server 18

New topic The new topic Sending Commands that Use the Document May 1, 2018
Version Parameter (p. 622) describes how to use the
document-version parameter to specify which version of an
SSM document to use when the command runs.

New topic The new topic Deleting Custom Inventory (p. 543) describes April 19,
how to delete custom Inventory data from Amazon S3 by 2018
using the AWS CLI. The topic also describes how to use the
SchemaDeleteOption to manage custom inventory by
disabling or deleting a custom inventory type. This new
feature uses the DeleteInventory API action.

Amazon SNS You can subscribe to an Amazon SNS topic to receive April 9, 2018
notifications for SSM notifications when a new version of SSM Agent is available.
Agent For more information, see Subscribe to SSM Agent
Notifications (p. 86).

CentOS patching Systems Manager now supports patching CentOS instances. March 29,
support For information about supported CentOS versions, see Patch 2018
Manager Prerequisites (p. 684). For more information about
how patching works, see How Patch Manager Operations
Work (p. 685).

New section To provide a single source for reference information in March 15,
the AWS Systems Manager User Guide, a new section has 2018
been introduced, AWS Systems Manager Reference (p. 933).
Additional content will be added to this section as it becomes
available.

New topic The new topic About Package Name Formats for Approved March 9,
and Rejected Patch Lists (p. 712) details the package name 2018
formats you can enter in the lists of approved patches and
rejected patches for a custom patch baseline. Sample formats
are provided for each operating system type supported by
Patch Manager.

New topic Systems Manager now integrates with Chef InSpec. InSpec March 7,
is an open-source, runtime framework that enables you to 2018
create human-readable profiles on GitHub or Amazon S3.
Then you can use Systems Manager to run compliance scans
and view compliant and noncompliant instances. For more

969
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

information, see Using Chef InSpec Profiles with Systems
Manager Compliance (p. 105).

New topic The new topic Using Service-Linked Roles for Systems February 27,
Manager (p. 919) describes how to use an AWS Identity and 2018
Access Management (IAM) service-linked role with Systems
Manager. Currently, service-linked roles are only required
when using Systems Manager Inventory to collect metadata
about tags and Resource Groups.

New and updated You can now use Patch Manager to install patches that are in a February 6,
topics different source repository than the default one configured on 2018
the instance. This is useful for patching instances with updates
not related to security; with the content of Personal Package
Archives (PPA) for Ubuntu Server; with updates for internal
corporate applications; and so on. You specify alternative
patch source repositories when you create a custom patch
baseline. For more information, see the following topics:

• How to Specify an Alternative Patch Source Repository

(Linux) (p. 688)
• Create a Custom Patch Baseline (p. 721)
• Create a patch baseline with custom repositories for
different OS versions (p. 738)

In addition, you can now use Patch Manager to patch

SUSE Linux Enterprise Server instances. Patch Manager
supports patching SLES 12.* versions (64-bit only). For
more information, see the SLES-specific information in the
following topics:

• How Security Patches Are Selected (p. 686)

• How Patches Are Installed (p. 690)
• How Patch Baseline Rules Work on SUSE Linux Enterprise
Server (p. 697)

New topic The new topic Upgrade the Python Requests Module on January 12,
Amazon Linux Instances That Use a Proxy Server (p. 84) 2018
provides instructions for ensuring that instances created
using an Amazon Linux AMI have been updated with a current
version of the Python requests module. This requirement is
to ensure compatibility with Patch Manager.

New topic The new topic About SSM Documents for Patching January 10,
Instances (p. 700) describes the seven SSM documents 2018
currently available to help you keep your managed instances
patched with the latest security-related updates.

970
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Important updates Updated various topics with the following information: January 9,
regarding Linux 2018
support • SSM Agent is installed, by default, on Amazon Linux base
AMIs dated 2017.09 and later.
• You must manually install SSM Agent on other versions
of Linux, including non-base images like Amazon ECS-
Optimized AMIs.

New topic A new topic, About the SSM Document AWS- January 5,
RunPatchBaseline (p. 703), provides details of how this SSM 2018
document operates on both Windows and Linux systems. It
also provides information about the two available parameters
in the AWS-RunPatchBaseline document, Operation and
Snapshot ID.

New topics A new section, How Patch Manager Operations Work (p. 685), January 2,
provides technical details that explain how Patch Manager 2018
determines which security patches to install and how it installs
them on each supported operating system. It also provides
information about how patch baseline rules work on different
distributions of the Linux operating system

Retitled and moved Based on customer feedback, the Automation Actions December 20,
the Systems Manager Reference is now called the Systems Manager Automation 2017
Automation Actions Document Reference. Furthermore, we moved the reference
Reference into the Shared Resources > Documents node so it is closer
to the SSM Document Plugin Reference (p. 800). For more
information, see Systems Manager Automation Actions
Reference (p. 241).

New Monitoring A new chapter, Monitoring AWS Systems Manager (p. 882), December 14,
chapter and content provides instructions for sending metrics and log data to 2017
Amazon CloudWatch Logs. A new topic, Sending Logs to
CloudWatch Logs (CloudWatch agent) (p. 884), provides
instructions for migrating on-instance monitoring tasks, on
64-bit Windows Server instances only, from SSM Agent to the
CloudWatch agent.

New chapter A new chapter, Authentication and Access Control for December 11,
AWS Systems Manager (p. 906), provides comprehensive 2017
information about using AWS Identity and Access
Management (IAM) and AWS Systems Manager to help secure
access to your resources through the use of credentials. These
credentials provide the permissions required to access AWS
resources, such as accessing data stored in Amazon S3 buckets
and sending commands to and reading the tags on Amazon
EC2 instances.

Changes to the left We changed the headings in the left navigation of this December 8,
navigation user guide to match the headings in the new AWS Systems 2017
Manager console.

971
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Multiple changes for • Official launch of AWS Systems Manager: AWS Systems November 29,
re:Invent 2017 Manager (formerly Amazon EC2 Systems Manager) is 2017
a unified interface that allows you to easily centralize
operational data and automate tasks across your AWS
resources. You can access the new AWS Systems Manager
console here. For more information, see What Is AWS
Systems Manager? (p. 1)
• YAML Support: You can create SSM documents in
YAML. For more information, see AWS Systems Manager
Documents (p. 775).

Using Run Command Using Run Command, you can take application-consistent November 20,
to Take VSS-Enabled snapshots of all Amazon Elastic Block Store (Amazon EBS) 2017
Snapshots of EBS volumes attached to your Amazon EC2 Windows instances.
Volumes The snapshot process uses the Windows Volume Shadow
Copy Service (VSS) to take image-level backups of VSS-
aware applications, including data from pending transactions
between these applications and the disk. Furthermore, you
don't need to shut down your instances or disconnect them
when you need to back up all attached volumes. For more
information, see Using Run Command to Take VSS-Enabled
Snapshots of EBS Volumes in the Amazon EC2 User Guide for
Windows Instances.

Enhanced Systems You can improve the security posture of your managed November 7,
Manager Security instances (including managed instances in your hybrid 2017
Available By Using environment) by configuring Systems Manager to use an
VPC Endpoints interface VPC endpoint. Interface endpoints are powered by
PrivateLink, a technology that enables you to privately access
Amazon EC2 and Systems Manager APIs by using private IP
addresses. PrivateLink restricts all network traffic between
your managed instances, Systems Manager, and EC2 to the
Amazon network (managed instances don't have access to
the Internet). Also, you don't need an Internet gateway, a NAT
device, or a virtual private gateway. For more information, see
(Optional) Create a Virtual Private Cloud Endpoint (p. 36).

972
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Inventory Support SSM Inventory now supports gathering the following November 6,
for Files, Services, information from your managed instances. 2017
Windows Roles, and
the Windows Registry • Files: Name, size, version, installed date, modification and
last accessed times, etc.
• Services: Name, display name, status, dependent services,
service type, start type, etc.
• Windows Registry: Registry key path, value name, value
type, and value.
• Windows roles: Name, display name, path, feature type,
installed state, etc.

Before you attempt to collect information for these inventory

types, update SSM Agent on the instances you want to
inventory. By running the latest version of SSM Agent, you
ensure that you can collect metadata for all supported
inventory types. For information about how to update SSM
Agent by using State Manager, see Automatically Update SSM
Agent (CLI) (p. 681).

For more information Inventory, see Learn More About

Systems Manager Inventory (p. 515).

Updates to Fixed several issues in the information about setting up and October 31,
Automation configuring access for Systems Manager Automation. For more 2017
documenation information, see Getting Started with Automation (p. 144).

973
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

GitHub and Amazon Run remote scripts: Systems Manager now supports October 26,
S3 Integration downloading and running scripts from a private or public 2017
GitHub repository, and from Amazon S3. Using either the
AWS-RunRemoteScript pre-defined SSM document or the
aws:downloadContent plugin in a custom SSM document,
you can run Ansible Playbooks and scripts in Python, Ruby, or
PowerShell, to name a few. These changes further enhance
infrastructure as code when you use Systems Manager to
automate configuration and deployment of Amazon EC2
instances and on-premises managed instances in your hybrid
environment. For more information, see Partner and Product
Integration (p. 90).

Create composite SSM documents: Systems Manager now

supports running one or more secondary SSM documents
from a primary SSM document. These primary documents
that run other documents are called composite documents.
Composite documents enable you to create and share a
standard set of secondary SSM documents across AWS
accounts for common tasks such as boot-strapping anti-virus
software or domain-joining instances. You can run composite
and secondary documents stored in Systems Manager, GitHub,
or Amazon S3. After you create a composite document, you
can run it by using the AWS-RunDocument pre-defined SSM
document. For more information, see Creating Composite
Documents (p. 796) and Running Documents from Remote
Locations (p. 797).

SSM document plugin reference: For easier access, we

moved the SSM Plugin Reference for SSM documents out
of the Systems Manager API Reference and into the User
Guide. For more information, see SSM Document Plugin
Reference (p. 800).

Support for When you edit a parameter, Parameter Store now October 24,
Parameter Versions in automatically iterates the version number by 1. You can 2017
Parameter Store specify a parameter name and a specific version number in
API calls and SSM documents. If you don't specify a version
number, the system automatically uses the latest version.

Parameter versions provide a layer of protection in the

event that a parameter is accidentally changed. You can
view the values of all versions, and reference older versions
if necessary. You can also use parameter versions to see
how many times a parameter changed over a period of
time. For more information, see Working with Parameter
Versions (p. 854).

974
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Support for Tagging You can now use the AddTagsToResource API, the AWS CLI, October 3,
Systems Manager or the AWS Tools for Windows to tag Systems Manager 2017
Documents documents with key-value pairs. Tagging helps you quickly
identify specific resources based on the tags you've assigned
to them. This is in addition to existing tagging support for
managed instances, maintenance windows, Parameter Store
parameters, and patch baselines. New topics include Tagging
Systems Manager Documents (p. 787) and Controlling Access
to Documents Using Tags (p. 788).

Various • Updated Setting Up AWS Systems Manager for Hybrid October 2,

Documentation Environments (p. 41) with information for Raspbian Linux. 2017
Updates to Fix Errors • Updated Setting Up AWS Systems Manager (p. 23) with
or Update Content new requirement for Windows instances. SSM Agent
Based on Feedback requires Windows PowerShell 3.0 or later to run certain SSM
Documents on Windows instances (for example, the AWS-
ApplyPatchBaseline document). Verify that your Windows
instances are running Windows Management Framework
3.0 or later. The framework includes PowerShell. For more
information, see Windows Management Framework 3.0.

Troubleshoot EC2Rescue can help you diagnose and troubleshoot problems September
Unreachable on Amazon EC2 Windows Server instances. You can run 29, 2017
Windows Instances by the tool as a Systems Manager Automation workflow by
Using the EC2Rescue using the AWSSupport-ExecuteEC2Rescue document. The
Automation Workflow AWSSupport-ExecuteEC2Rescue document is designed to
perform a combination of Systems Manager actions, AWS
CloudFormation actions, and Lambda functions that automate
the steps normally required to use EC2Rescue. For more
information, see Run the EC2Rescue Tool on Unreachable
Instances (p. 422).

SSM Agent Installed SSM Agent is installed, by default, on Amazon Linux September
By Default on AMIs dated 2017.09 and later. You must manually install 27, 2017
Amazon Linux SSM Agent on other versions of Linux, as described in
Installing and Configuring SSM Agent on Amazon EC2 Linux
Instances (p. 68).

Run Command Run Command includes the following enhancements. September

Enhancements 12, 2017
• You can restrict command execution to specific instances
by creating an IAM user policy that includes a condition
that the user can only run commands on instances that
are tagged with specific Amazon EC2 tags. For more
information, see Restricting Run Command Access Based on
Instance Tags (p. 616).
• You have more options for targeting instances by using
Amazon EC2 tags. You can now specify multiple tag keys
and multiple tag values when sending commands. For more
information, see Using Targets and Rate Controls to Send
Commands to a Fleet (p. 622).

Systems Manager Systems Manager can now run on Raspbian Jessie and September 7,
Supported on Raspbian Stretch devices, including Raspberry Pi (32-Bit). For 2017
Raspbian more information, see Raspbian (p. 80).

975
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Automatically Send You can now make a simple configuration change on your September 7,
SSM Agent Logs to instances to have SSM Agent send log files to CloudWatch. For 2017
Amazon CloudWatch more information, see Sending Logs to CloudWatch Logs (SSM
Logs Agent) (p. 882).

Encrypt Resource Systems Manager Resource Data Sync lets you aggregate September 1,
Data Sync Inventory data collected on dozens or hundreds of managed 2017
instance in a central Amazon S3 bucket. You can now encrypt
Resource Data Sync by using an AWS Key Management Service
key. For more information, see Walkthrough: Use Resource
Data Sync to Aggregate Inventory Data (p. 556).

New State Manager Added two new walkthroughs to the State Manager August 31,
Walkthroughs documentation: 2017

Automatically Update SSM Agent (CLI) (p. 681)

Walkthrough: Automatically Update PV Drivers on EC2

Windows Instances (Console) (p. 682)

Systems Manager Use Configuration Compliance to scan your fleet of August 28,
Configuration managed instances for patch compliance and configuration 2017
Compliance inconsistencies. You can collect and aggregate data
from multiple AWS accounts and Regions, and then drill
down into specific resources that aren’t compliant. By
default, Configuration Compliance displays compliance
data about Patch Manager patching and State Manager
associations. You can also customize the service and create
your own compliance types based on your IT or business
requirements. For more information, see AWS Systems
Manager Configuration Compliance (p. 504).

New Automation Runs a secondary Automation workflow by calling a August 22,

Action: secondary Automation document. With this action, you 2017
aws:executeAutomation can create Automation documents for your most common
workflows, and reference those documents during an
Automation execution. This action can simplify your
Automation documents by removing the need to duplicate
steps across similar documents. For more information, see
aws:executeAutomation (p. 267).

Automation as You can start an Automation workflow by specifying August 21,

the Target of a an Automation document as the target of an Amazon 2017
CloudWatch Event CloudWatch event. You can start workflows according to a
schedule, or when a specific AWS system event occurs. For
more information, see Running Automation Workflows with
Triggers using CloudWatch Events (p. 177).

State Manager You can now create different State Manager association August 21,
Association versions. There is a limit of 1,000 versions for each association. 2017
Versioning and You can also specify names for your associations. Also,
General Updates the State Manager documentation has been updated
to address outdated information and inconsistencies.
For more information, see AWS Systems Manager State
Manager (p. 645).

976
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Changes to Maintenance Windows include the following changes or August 16,

Maintenance enhancements: 2017
Windows
• Previously, Maintenance Windows could only perform tasks
by using Run Command. You can now perform tasks by
using Systems Manager Automation, AWS Lambda, and
AWS Step Functions.
• You can edit the targets of a maintenance window, specify a
target name, description, and owner.
• You can edit tasks in a maintenance window, including
specifying a new SSM document for Run Command and
Automation tasks.
• All Run Command parameters are now supported, including
DocumentHash, DocumentHashType, TimeoutSeconds,
Comment, and NotificationConfig.
• You can now use a safe flag when you attempt to
deregister a target. If enabled, the system returns an error if
the target is referenced by any task.

For more information, see AWS Systems Manager

Maintenance Windows (p. 444).

New Automation This new action for Automation documents temporarily August 10,
Action: aws:approve pauses an Automation execution until designated principals 2017
either approve or reject the action. After the required number
of approvals is reached, the Automation execution resumes.

For more information, see Systems Manager Automation

Actions Reference (p. 241).

Automation Assume Automation previously required that you specify a service role August 3,
Role No Longer (or assume role) so that the service had permission to perform 2017
Required actions on your behalf. Automation no longer requires this
role because the service now operates by using the context of
the user who invoked the execution.

However, the following situations still require that you specify

a service role for Automation:

• When you want to restrict a user's privileges on a resource,

but you want the user to run an Automation workflow that
requires elevated privileges. In this scenario, you can create
a service role with elevated privileges and allow the user to
run the workflow.
• Operations that you expect to run longer than 12 hours
require a service role.

For more information, see Getting Started with

Automation (p. 144).

977
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Configuration Use Amazon EC2 Systems Manager Configuration Compliance August 8,

Compliance to scan your fleet of managed instances for patch compliance 2017
and configuration inconsistencies. You can collect and
aggregate data from multiple AWS accounts and Regions,
and then drill down into specific resources that aren’t
compliant. For more information, see AWS Systems Manager
Configuration Compliance (p. 504).

SSM Document SSM Command and Policy documents now offer cross- July 12, 2017
Enhancements platform support. This means that a single SSM document
can process plugins for Windows and Linux operating systems.
Cross-platform suppport enables you to consolidate the
number of documents you manage. Cross-platform support
is offered in SSM documents that use schema version 2.2 or
later.

SSM Command documents that use schema version 2.0 or

later can now include multiple plugins of the same type. For
example, you can create a Command document that calls the
aws:runRunShellScript plugin multiple times.

For more information about schema version 2.2 changes,

see AWS Systems Manager Documents (p. 775). For more
information about SSM plugins, see Systems Manager Plugins.

Linux Patching Patch Manager can now patch the following Linux July 6, 2017
distributions:

64-Bit and 32-Bit Systems

• Amazon Linux 2014.03, 2014.09, or later

• Ubuntu Server 16.04 LTS, 14.04 LTS, or 12.04 LTS
• Red Hat Enterprise Linux (RHEL) 6.5 or later

64-Bit Systems Only

• Amazon Linux 2015.03, 2015.09, or later

• Red Hat Enterprise Linux (RHEL) 7.x or later

For more information, see AWS Systems Manager Patch

Manager (p. 683).
Note

• To patch Linux instances, your instances must

be running SSM Agent version 2.0.834.0 or later.
For information about updating the agent, see
the section titled Example: Update SSM Agent in
Running Commands from the Console (p. 619).
• The AWS-ApplyPatchBaseline SSM document is
being replaced by the AWS-RunPatchBaseline
document.

978
 AWS Systems Manager User Guide
Earlier Updates

Change Description Release Date

Resource Data Sync You can use Systems Manager Resource Data Sync to send June 29,
Inventory data collected from all of your managed instances 2017
to a single Amazon S3 bucket. Resource Data Sync then
automatically updates the centralized data when new
Inventory data is collected. With all Inventory data stored in
a target Amazon S3 bucket, you can use services like Amazon
Athena and Amazon QuickSight to query and analyze the
aggregated data.For more information, see Configuring
Resource Data Sync for Inventory (p. 520). For an example of
how to work with Resource Data Sync, see Walkthrough: Use
Resource Data Sync to Aggregate Inventory Data (p. 556).

Systems Manager Managing dozens or hundreds of Systems Manager June 22,

Parameter Hierarchies parameters as a flat list is time-consuming and prone to 2017
errors. You can use parameter hierarchies to help you organize
and manage Systems Manager parameters. A hierarchy is a
parameter name that includes a path that you define by using
forward slashes. Here is an example that uses three hierarchy
levels in the name to identify the following:

/Environment/Type of computer/Application/Data

/Dev/DBServer/MySQL/db-string13

For more information, see Organizing Parameters into

Hierarchies (p. 839). For an example of how to work with
parameter hierarchies, see Walkthrough: Manage Parameters
Using Hierarchies (AWS CLI) (p. 880).

SSM Agent Support You can install SSM Agent on 64-bit SUSE Linux Enterprise June 14,
for SUSE Linux Server (SLES). For more information, see Installing 2017
Enterprise Server and Configuring SSM Agent on Amazon EC2 Linux
Instances (p. 68).

979
 AWS Systems Manager User Guide

AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.

980