• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # Monitoring Systems Manager status changes using Amazon SNS notifications You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands that you send using Run Command or Maintenance Windows, which are tools in AWS Systems Manager. 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 nodes, you can receive a notification for each copy of the command sent to a specific node. 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](https://docs.aws.amazon.com/sns/latest/dg/) 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](monitoring-sns-examples.md). **Important** Note the following important information. Amazon Simple Notification Service FIFO topics aren't supported. Amazon Q Developer in chat applications isn't supported for monitoring Systems Manager with Amazon SNS. If you wish to use Amazon Q Developer in chat applications to monitor Systems Manager, you must use it with Amazon EventBridge. For information about monitoring Systems Manager using EventBridge, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md). For information about Amazon EventBridge and Amazon Q Developer in chat applications, see [Tutorial: Creating an EventBridge rule that sends notifications to Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/create-eventbridge-rule.html) in the *Amazon Q Developer in chat applications Administrator Guide*. ## Configure Amazon SNS notifications for AWS Systems Manager Run Command and Maintenance Windows tasks that are registered to a maintenance window can send Amazon SNS notifications for command tasks that enter the following statuses: + In Progress + Success + Failed + Timed Out + Cancelled For information about the conditions that cause a command to enter one of these statuses, see [Understanding command statuses](monitor-commands.md). **Note** Commands sent using Run Command also report Canceling and Pending status. These statuses aren't 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 initiated. The timestamp is important because Amazon SNS doesn't 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 hasn't already started executing, it won't 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 node. | | instanceIds | StringList | The nodes that were targeted by the command. Instance IDs are only included in the summary message if the Run Command task targeted instance IDs directly. Instance IDs aren't 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 nodes, 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 initiated. The timestamp is important because Amazon SNS doesn't guarantee message delivery order. Example: 2016-04-26T13:15:30Z | | documentName | String | The name of the Systems Manager document (SSM document) used to run this command. | | requestedDateTime | String | The time and date that the request was sent to this specific node. | | 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, complete the following tasks. **Note** If you aren't configuring Amazon SNS notifications for your maintenance window, then you can skip Task 5 later in this topic. **Topics** + [ ### Command summary Amazon SNS notifications ](#monitoring-sns-configure-summary) + [ ### Invocation-based Amazon SNS notifications ](#monitoring-sns-configure-invocation) + [ ### Task 1: Create and subscribe to an Amazon SNS topic ](#monitoring-configure-sns) + [ ### Task 2: Create an IAM policy for Amazon SNS notifications ](#monitoring-iam-policy) + [ ### Task 3: Create an IAM role for Amazon SNS notifications ](#monitoring-iam-notifications) + [ ### Task 4: Configure user access ](#monitoring-sns-passpolicy) + [ ### Task 5: Attach the iam:PassRole policy to your maintenance window role ](#monitoring-sns-passpolicy-mw) ### 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 Simple Queue Service (Amazon SQS). To get started, we recommend that you start with the email protocol. For information about how to create a topic, see [Creating an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) 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 [Subscribing to an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) 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 inititating 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/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**, and then choose **Create Policy**. (If a **Get Started** button is shown, choose it, and then choose **Create Policy**.) 1. Choose the **JSON** tab. 1. Replace the default content with one of the following, depending on whether the Amazon SNS topic uses AWS KMS encryption: ------ #### [ SNS topic not encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" } ] } ``` ------ *region* represents the 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 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. ------ #### [ SNS topic encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" }, { "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/kms-key-id" } ] } ``` ------ *region* represents the 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 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. *kms-key-id* represents the ID of the symmetric encryption KMS key in AWS KMS to use for encrypting and decrypting the topic, in the format `1234abcd-12ab-34cd-56ef-12345EXAMPLE`. **Note** There is a charge for using AWS KMS encryption. For more information, see [Managing Amazon SNS encryption keys and costs](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) in the *AWS Key Management Service Developer Guide*. ------ 1. Choose **Next: Tags**. 1. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy. 1. Choose **Next: Review**. 1. On the **Review policy** page, for **Name**, enter a name for the inline policy. For example: **my-sns-publish-permissions**. 1. (Optional) For **Description**, enter a description for the policy. 1. 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 initiate Amazon SNS notifications. In all subsequent procedures, this role is referred to as the Amazon SNS IAM role. **To create an IAM service role for Amazon SNS notifications** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**. 1. Choose the **AWS service** role type, and then choose Systems Manager. 1. Choose the Systems Manager use case. Then, choose **Next**. 1. On the **Attach permissions policies** page, select the box to the left of the name of the custom policy you created in Task 2. For example: **my-sns-publish-permissions**. 1. (Optional) Set a [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html). This is an advanced feature that is available for service roles, but not service-linked roles. Expand the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions boundary or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. After you create the policy, close that tab and return to your original tab to select the policy to use for the permissions boundary. 1. Choose **Next**. 1. If possible, enter a role name or role name suffix to help you identify the purpose of this role. Role names must be unique within your AWS account. They are not distinguished by case. For example, you cannot create roles named both **PRODROLE** and **prodrole**. Because various entities might reference the role, you cannot edit the name of the role after it has been created. 1. (Optional) For **Description**, enter a description for the new role. 1. Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Select permissions** sections to edit the use cases and permissions for the role. 1. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*. 1. Review the role and then choose **Create role**. 1. Choose the name of the role, and then copy or make a note of the **Role ARN** value. This Amazon Resource Name (ARN) for the role is used when you send a command that is configured to return Amazon SNS notifications. 1. Keep the **Summary** page open. ### Task 4: Configure user access If an IAM entity (user, role, or group) is assigned administrator permissions, then the user or role has access to Run Command and Maintenance Windows, tools in AWS Systems Manager. For entities without administrator permissions, an administrator must grant the following permissions to the IAM entity: + The `AmazonSSMFullAccess` managed policy, or a policy that provides comparable permissions. + `iam:PassRole` permissions for the role created in [Task 3: Create an IAM role for Amazon SNS notifications](#monitoring-iam-notifications). For example: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::111122223333:role/sns-role-name", "Condition": { "StringEquals": { "iam:PassedToService": "ssm.amazonaws.com" } } } ] } ``` ------ To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + Users managed in IAM through an identity provider: Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*. + IAM users: + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*. + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 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. 1. 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. 1. Choose **Add inline policy**. 1. On the **Create policy** page, choose the **Visual editor** tab. 1. Choose **Choose a service**, and then choose ** IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, verify that **Specific** is selected, and then choose **Add ARN**. 1. In the **Specify ARN for role** field, paste the Amazon SNS IAM role ARN that you copied at the end of Task 3. The system automatically populates the **Account** and **Role name with path** fields. 1. Choose **Add**. 1. Choose **Review policy**. 1. On the **Review Policy** page, enter 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, attach an `iam:PassRole` policy to the maintenance window service role specified. If you don't intend to configure the registered task for Amazon SNS notifications, then you can skip this task. The `iam:PassRole` policy allows the Maintenance Windows service role to pass the Amazon SNS IAM 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** Use a custom service role for your maintenance window to send notifications related to the Run Command tasks registered. For information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md). If you need to create a custom service role for maintenance window tasks, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md). **To attach the`iam:PassRole` policy to your Maintenance Windows role** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** and select the Amazon SNS IAM role created in Task 3. 1. Copy or make a note of the **Role ARN** and return to the **Roles** section of the IAM console. 1. Select the custom Maintenance Windows service role you created from the **Role name** list. 1. On the **Permissions** tab, verify that either the `AmazonSSMMaintenanceWindowRole` policy is listed or there is a comparable policy that gives maintenance windows permission to the Systems Manager API. If it is not, choose **Add permissions, Attach policies** to attach it. 1. Choose **Add permissions, Create inline policy**. 1. Choose the **Visual editor** tab. 1. For **Service**, choose **IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, choose **Specific**, and then choose **Add ARN**. 1. In the **Specify ARN for role** box, paste the ARN of the Amazon SNS IAM role created in Task 3, and then choose **Add**. 1. Choose **Review policy**. 1. On the **Review policy** page, specify a name for the `PassRole` policy, and then choose **Create 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 Run Command or Maintenance Windows, which are tools in AWS Systems Manager. **Note** This guide doesn't 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](monitoring-sns-notifications.md#monitoring-sns-configure). 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": "amzn-s3-demo-bucket", "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", "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 command through Run Command, a tool in AWS Systems Manager, 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/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**. 1. Choose **Run command**. 1. In the **Command document** list, choose a Systems Manager document. 1. In the **Command parameters** section, specify values for required parameters. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Other parameters**: + For **Comment**, enter information about this command. + For **Timeout (seconds)**, specify the number of seconds for the system to wait before failing the overall command execution. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets 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 managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter 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 (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS Notifications** section, choose **Enable SNS notifications**. 1. For **IAM role**, choose the Amazon SNS IAM role ARN you created in Task 3 in [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. For **SNS topic**, enter the Amazon SNS topic ARN to be used. 1. For **Event notifications**, choose the events for which you want to receive notifications. 1. For **Change notifications**, choose to receive notifications for the command summary only (**Command status changes**) or for each copy of a command sent to multiple nodes (**Command status on each instance changes**) . 1. Choose **Run**. 1. Check your email for a message from Amazon SNS and open the email message. Amazon SNS can take several minutes to send the email message. ## 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. 1. Specify parameters in the following command to target based on managed node 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"}' ``` Following is an 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. ``` 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"}' ``` Following is an 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"}' ``` 1. Press **Enter**. 1. Check your email for a message from Amazon SNS and open the email message. Amazon SNS can take several minutes to send the email message. For more information, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) in the *AWS CLI Command Reference*. # Use a maintenance window to send a command that returns status notifications The following procedures show how to register a Run Command task with your maintenance window using the AWS Systems Manager console or the AWS Command Line Interface (AWS CLI). Run Command is a tool in AWS Systems Manager. 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 [Create and manage maintenance windows using the console](sysman-maintenance-working.md) for steps on how to create a maintenance window and register targets. To receive notifications from the Amazon Simple Notification Service (Amazon SNS) service, 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 window role](monitoring-sns-notifications.md#monitoring-sns-passpolicy-mw). ## 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/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Maintenance Windows**. 1. Select the maintenance window for which you would like to register a Run Command task configured to send Amazon Simple Notification Service (Amazon SNS) notifications. 1. Choose **Actions** and then choose **Register Run command task**. 1. (Optional) In the **Name** field, enter a name for the task. 1. (Optional) In the **Description** field, enter a description. 1. For **Command document**, choose a Command document. 1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order. Tasks that have the same priority are scheduled in parallel. 1. In the **Targets** section, select a registered target group or select unregistered targets. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets 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 managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. In the ** IAM service role** area, choose the Maintenance Windows service role that has `iam:PassRole` permissions to the SNS role. **Note** Add `iam:PassRole` permissions to the Maintenance Windows role to allow Systems Manager to pass the SNS role to Amazon SNS. If you haven't added `iam:PassRole` permissions, see Task 5 in the topic [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. (Optional) For **Output options**, to save the command output to a file, select the **Enable writing output to S3** box. Enter 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 managed node, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, do the following: + Choose **Enable SNS Notifications**. + For **IAM role**, choose the Amazon SNS IAM role Amazon Resource Name (ARN) you created in Task 3 in [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md) to initiate Amazon SNS. + For **SNS topic**, enter the Amazon SNS topic ARN to be used. + For **Event type**, choose the events for which you want to receive notifications. + For **Notification type**, choose to receive notifications for each copy of a command sent to multiple nodes (invocations) or the command summary. 1. In the **Parameters** section, enter the required parameters based on the Command document you chose. 1. Choose **Register Run command task**. 1. After the next time your maintenance window runs, check your email for a message from Amazon SNS and open the email message. Amazon SNS can take a few minutes to send the email message. ## 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`. 1. Paste the following contents into the file. ``` { "Name": "Name", "Description": "Description", "WindowId": "mw-0c50858d01EXAMPLE", "ServiceRoleArn": "arn:aws:iam::account-id: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:account-id:SNSTopicName", "NotificationEvents": [ "All" ], "NotificationType": "Command" }, "ServiceRoleArn": "arn:aws:iam::account-id:role/SNSIAMRole" } } } ``` 1. Replace the example values with information about your own resources. You can also restore options we've 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 [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html) in the *AWS CLI Command Reference*. 1. Save the file. 1. 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's required in this command. If successful, the command returns information similar to the following. ``` { "WindowTaskId": "j2l8d5b5c-mw66-tk4d-r3g9-1d4d1EXAMPLE" } ``` 1. After the next execution of your maintenance window, check your email for a message from Amazon SNS and open the email message. Amazon SNS can take a few minutes to send the email message. For more information about registering tasks for a maintenance window from the command line, see [Register tasks with the maintenance window](mw-cli-tutorial-tasks.md).