• 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). # AWS Systems Manager Run Command Using Run Command, a tool in AWS Systems Manager, you can remotely and securely manage the configuration of your managed nodes. A *managed node* is any Amazon Elastic Compute Cloud (Amazon EC2) instance or non-EC2 machine in your [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment that has been configured for Systems Manager. Run Command allows you to automate common administrative tasks and perform one-time configuration changes at scale. You can use Run Command from the AWS Management Console, the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or the AWS SDKs. Run Command is offered at no additional cost. To get started with Run Command, open the [Systems Manager console](https://console.aws.amazon.com//systems-manager/run-command). In the navigation pane, choose **Run Command**. Administrators use Run Command to install or bootstrap applications, build a deployment pipeline, capture log files when an instance is removed from an Auto Scaling group, join instances to a Windows domain, and more. The Run Command API follows an eventual consistency model, due to the distributed nature of the system supporting the API. This means that the result of an API command you run that affects your resources might not be immediately visible to all subsequent commands you run. You should keep this in mind when you carry out an API command that immediately follows a previous API command. **Getting Started** The following table includes information to help you get started with Run Command. **** | Topic | Details | | --- | --- | | [Setting up managed nodes for AWS Systems Manager](systems-manager-setting-up-nodes.md) | Verify that you have completed the setup requirements for your Amazon Elastic Compute Cloud (Amazon EC2) instances and non-EC2 machines in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. | | [Managing nodes in hybrid and multicloud environments with Systems Manager](systems-manager-hybrid-multicloud.md) | (Optional) Register on-premises servers and VMs with AWS so you can manage them using Run Command. | | [Managing edge devices with Systems Manager](systems-manager-setting-up-edge-devices.md) | (Optional) Configure edge devices so you can manage them using Run Command. | | [Running commands on managed nodes](running-commands.md) | Learn how to run a command that targets one or more managed nodes by using the AWS Management Console. | | [Run Command walkthroughs](run-command-walkthroughs.md) | Learn how to run commands using either Tools for Windows PowerShell or the AWS CLI. | **EventBridge support** This Systems Manager tool is supported as both an *event* type and a *target* type in Amazon EventBridge rules. For information, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md) and [Reference: Amazon EventBridge event patterns and types for Systems Manager](reference-eventbridge-events.md). **More info** + [Remotely Run Command on an EC2 Instance (10 minute tutorial)](https://aws.amazon.com/getting-started/hands-on/remotely-run-commands-ec2-instance-systems-manager/) + [Systems Manager service quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) in the *Amazon Web Services General Reference* + [AWS Systems Manager API Reference](https://docs.aws.amazon.com/systems-manager/latest/APIReference/) **Topics** + [ # Setting up Run Command ](run-command-setting-up.md) + [ # Running commands on managed nodes ](running-commands.md) + [ # Using exit codes in commands ](run-command-handle-exit-status.md) + [ # Understanding command statuses ](monitor-commands.md) + [ # Run Command walkthroughs ](run-command-walkthroughs.md) + [ # Troubleshooting Systems Manager Run Command ](troubleshooting-remote-commands.md) # Setting up Run Command Before you can manage nodes by using Run Command, a tool in AWS Systems Manager, configure an AWS Identity and Access Management (IAM) policy for any user who will run commands. If you use any global condition keys for the `SendCommand` action in your IAM policies, you must include the `aws:ViaAWSService` condition key and set the boolean value to `true`. The following is an example. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:SendCommand" ], "Resource": [ "arn:aws:ssm:us-east-1:111122223333:document/YourDocument" ], "Condition": { "StringEquals": { "aws:SourceVpce": [ "vpce-1234567890abcdef0" ] } } }, { "Effect": "Allow", "Action": [ "ssm:SendCommand" ], "Resource": [ "arn:aws:ssm:us-east-1:111122223333:document/YourDocument" ], "Condition": { "Bool": { "aws:ViaAWSService": "true" } } } ] } ``` ------ You must also configure your nodes for Systems Manager. For more information, see [Setting up managed nodes for AWS Systems Manager](systems-manager-setting-up-nodes.md). We recommend completing the following optional setup tasks to help minimize the security posture and day-to-day management of your managed nodes. Monitor command executions using Amazon EventBridge You can use EventBridge 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 an EventBridge event occurs. For more information, see [Configuring EventBridge for Systems Manager events](monitoring-systems-manager-events.md). Monitor command executions using Amazon CloudWatch Logs You can configure Run Command to periodically send all command output and error logs to an Amazon CloudWatch log group. You can monitor these 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](sysman-rc-setting-up-cwlogs.md). Restrict Run Command access to specific managed nodes You can restrict a user's ability to run commands on managed nodes by using AWS Identity and Access Management (IAM). Specifically, you can create an IAM policy with a condition that the user can only run commands on managed nodes that are tagged with specific tags. For more information, see [Restricting Run Command access based on tags](#tag-based-access). ## Restricting Run Command access based on tags This section describes how to restrict a user's ability to run commands on managed nodes by specifying a tag condition in an IAM policy. Managed nodes include Amazon EC2 instances and non-EC2 nodes in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment that are configured for Systems Manager. Though the information is not explicitly presented, you can also restrict access to managed AWS IoT Greengrass core devices. To get started, you must tag your AWS IoT Greengrass devices. For more information, see [Tag your AWS IoT Greengrass Version 2 resources](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. You can restrict command execution to specific managed nodes by creating an IAM policy that includes a condition that the user can only run commands on nodes with specific 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 node (`Resource: arn:aws:ec2:*:*:instance/*`) with the condition that the node is a Finance WebServer (`ssm:resourceTag/Finance: WebServer`). If the user sends a command to a node that isn't tagged or that has any tag other than `Finance: WebServer`, the execution results show `AccessDenied`. ------ #### [ JSON ] **** ``` { "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 allow a user to run commands on managed nodes that are tagged with multiple tags. The following policy allows the user to run commands on managed nodes that have two tags. If a user sends a command to a node that isn't tagged with both of these tags, the execution results show `AccessDenied`. ------ #### [ JSON ] **** ``` { "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" ] } } }, { "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 allows a user to run commands on multiple groups of tagged managed nodes. The following example policy allows the user to run commands on either group of tagged nodes, or both groups. ------ #### [ JSON ] **** ``` { "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":[ "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 policies, see [Managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html) in the *IAM User Guide*. For more information about tagging managed nodes, see [Tag Editor](https://docs.aws.amazon.com/ARG/latest/userguide/tag-editor.html) in the *AWS Resource Groups User Guide*. # Running commands on managed nodes This section includes information about how to send commands from the AWS Systems Manager console to managed nodes. This section also includes information about how to cancel a command. Note that if your node is configured with the `noexec` mount option for the var directory, Run Command is unable to successfuly run commands. **Important** When you send a command using Run Command, don't include sensitive information formatted as plaintext, such as passwords, configuration data, or other secrets. All Systems Manager API activity in your account is logged in an S3 bucket for AWS CloudTrail logs. This means that any user with access to S3 bucket can view the plaintext values of those secrets. For this reason, we recommend creating and using `SecureString` parameters to encrypt sensitive data you use in your Systems Manager operations. For more information, see [Restricting access to Parameter Store parameters using IAM policies](sysman-paramstore-access.md). **Execution history retention** The history of each command is available for up to 30 days. In addition, you can store a copy of all log files in Amazon Simple Storage Service or have an audit trail of all API calls in AWS CloudTrail. **Related information** For information about sending commands using other tools, see the following topics: + [Walkthrough: Use the AWS Tools for Windows PowerShell with Run Command](walkthrough-powershell.md) or the examples in the [AWS Systems Manager section of the AWS Tools for PowerShell Cmdlet Reference](https://docs.aws.amazon.com/powershell/latest/reference/items/AWS_Systems_Manager_cmdlets.html). + [Walkthrough: Use the AWS CLI with Run Command](walkthrough-cli.md) or the examples in the [SSM CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/ssm/) **Topics** + [ # Running commands from the console ](running-commands-console.md) + [ # Running commands using a specific document version ](run-command-version.md) + [ # Run commands at scale ](send-commands-multiple.md) + [ # Canceling a command ](cancel-run-command.md) # Running commands from the console You can use Run Command, a tool in AWS Systems Manager, from the AWS Management Console to configure managed nodes without having to log into them. This topic includes an example that shows how to [update SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample) on a managed node by using Run Command. **Before you begin** Before you send a command using Run Command, verify that your managed nodes meet all Systems Manager [setup requirements](systems-manager-setting-up-nodes.md). **To send a command using Run Command** 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) Choose a CloudWatch alarm to apply to your command for monitoring. To attach a CloudWatch alarm to your command, the IAM principal that runs the command must have permission for the `iam:createServiceLinkedRole` action. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). Note that if your alarm activates, any pending command invocations do not run. 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, 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 [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. For information about canceling a command, see [Canceling a command](cancel-run-command.md). ## Rerunning commands Systems Manager includes two options to help you rerun a command from the **Run Command** page in the Systems Manager console. + **Rerun**: This button allows you to run the same command without making changes to it. + **Copy to new**: This button copies the settings of one command to a new command and gives you the option to edit those settings before you run it. **To rerun a command** 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 a command to rerun. You can rerun a command immediately after executing it from the command details page. Or, you can choose a command that you previously ran from the **Command history** tab. 1. Choose either **Rerun** to run the same command without changes, or choose **Copy to new** to edit the command settings before you run it. # Running commands using a specific document version You can use the document version parameter to specify which version of an AWS Systems Manager document to use when the command runs. You can specify one of the following options for this parameter: + \$1DEFAULT + \$1LATEST + Version number Run the following procedure to run a command using the document version parameter. ------ #### [ Linux ] **To run commands using the AWS CLI on local Linux machines** 1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 1. List all available documents This command lists all of the documents available for your account based on AWS Identity and Access Management (IAM) permissions. ``` aws ssm list-documents ``` 1. Run the following command to view the different versions of a document. Replace *document name* with your own information. ``` aws ssm list-document-versions \ --name "document name" ``` 1. Run the following command to run a command that uses an SSM document version. Replace each *example resource placeholder* with your own information. ``` aws ssm send-command \ --document-name "AWS-RunShellScript" \ --parameters commands="echo Hello" \ --instance-ids instance-ID \ --document-version '$LATEST' ``` ------ #### [ Windows ] **To run commands using the AWS CLI on local Windows machines** 1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 1. List all available documents This command lists all of the documents available for your account based on AWS Identity and Access Management (IAM) permissions. ``` aws ssm list-documents ``` 1. Run the following command to view the different versions of a document. Replace *document name* with your own information. ``` aws ssm list-document-versions ^ --name "document name" ``` 1. Run the following command to run a command that uses an SSM document version. Replace each *example resource placeholder* with your own information. ``` aws ssm send-command ^ --document-name "AWS-RunShellScript" ^ --parameters commands="echo Hello" ^ --instance-ids instance-ID ^ --document-version "$LATEST" ``` ------ #### [ PowerShell ] **To run commands using the Tools for PowerShell** 1. Install and configure the AWS Tools for PowerShell (Tools for Windows PowerShell), if you haven't already. For information, see [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html). 1. List all available documents This command lists all of the documents available for your account based on AWS Identity and Access Management (IAM) permissions. ``` Get-SSMDocumentList ``` 1. Run the following command to view the different versions of a document. Replace *document name* with your own information. ``` Get-SSMDocumentVersionList ` -Name "document name" ``` 1. Run the following command to run a command that uses an SSM document version. Replace each *example resource placeholder* with your own information. ``` Send-SSMCommand ` -DocumentName "AWS-RunShellScript" ` -Parameter @{commands = "echo helloWorld"} ` -InstanceIds "instance-ID" ` -DocumentVersion $LATEST ``` ------ # Run commands at scale You can use Run Command, a tool in AWS Systems Manager, to run commands on a fleet of managed nodes by using the `targets`. The `targets` parameter accepts a `Key,Value` combination based on tags that you specified for your managed nodes. When you run the command, the system locates and attempts to run the command on all managed nodes that match the specified tags. For more information about tagging managed instances, see [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html) in the *Tagging AWS Resources User Guide*. For information about tagging your managed IoT devices, see [Tag your AWS IoT Greengrass Version 2 resources](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. You can also use the `targets` parameter to target a list of specific managed node IDs, as described in the next section. To control how commands run across hundreds or thousands of managed nodes, Run Command also includes parameters for restricting how many nodes can simultaneously process a request and how many errors can be thrown by a command before the command is canceled. **Topics** + [ ## Targeting multiple managed nodes ](#send-commands-targeting) + [ ## Using rate controls ](#send-commands-rate) ## Targeting multiple managed nodes You can run a command and target managed nodes by specifying tags, AWS resource group names, or managed node IDs. The following examples show the command format when using Run Command from the AWS Command Line Interface (AWS CLI ). Replace each *example resource placeholder* with your own information. Sample commands in this section are truncated using `[...]`. **Example 1: Targeting tags** ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:tag-name,Values=tag-value \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:tag-name,Values=tag-value ^ [...] ``` ------ **Example 2: Targeting an AWS resource group by name** 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 AWS Identity and Access Management (IAM) permissions to list or view the resources that belong to that group. For more information, see [Set up permissions](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions) in the *AWS Resource Groups User Guide*. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=resource-groups:Name,Values=resource-group-name \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=resource-groups:Name,Values=resource-group-name ^ [...] ``` ------ **Example 3: Targeting an AWS resource group by resource type** You can specify a maximum of five resource group types 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](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions) in the *AWS Resource Groups User Guide*. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 ^ [...] ``` ------ **Example 4: Targeting instance IDs** The following examples show how to target managed nodes by using the `instanceids` key with the `targets` parameter. You can use this key to target managed AWS IoT Greengrass core devices because each device is assigned an mi-*ID\$1number*. You can view device IDs in Fleet Manager, a tool in AWS Systems Manager. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 ^ [...] ``` ------ If you tagged managed nodes 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 managed nodes in *one* of these environments by using the `targets` parameter with the following syntax. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Environment,Values=Development \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Environment,Values=Development ^ [...] ``` ------ You could target additional managed nodes in other environments by adding to the `Values` list. Separate items using commas. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Environment,Values=Development,Test,Pre-production \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Environment,Values=Development,Test,Pre-production ^ [...] ``` ------ **Variation**: 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 managed nodes that meet *all* of the criteria. The following command targets all managed nodes tagged for the Finance Department *and* tagged for the database server role. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database ^ [...] ``` ------ **Variation**: 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. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^ [...] ``` ------ **Variation**: Targeting tagged managed nodes using multiple `Values` criteria If you tagged managed nodes for different environments using a `Key` named `Department` and `Values` of `Sales` and `Finance`, then you could send a command to all of the nodes in these environments by using the `targets` parameter with the following syntax. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values=Sales,Finance \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values=Sales,Finance ^ [...] ``` ------ You can specify a maximum of five keys, and five values for each key. If either a tag key (the tag name) or a tag value includes spaces, enclose the tag key or the value in quotation marks, as shown in the following examples. **Example**: Spaces in `Value` tag ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:OS,Values="Windows Server 2016" \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:OS,Values="Windows Server 2016" ^ [...] ``` ------ **Example**: Spaces in `tag` key and `Value` ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key="tag:Operating System",Values="Windows Server 2016" \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key="tag:Operating System",Values="Windows Server 2016" ^ [...] ``` ------ **Example**: Spaces in one item in a list of `Values` ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" ^ [...] ``` ------ ## Using rate controls You can control the rate at which commands are sent to managed nodes in a group by using *concurrency controls *and *error controls*. **Topics** + [ ### Using concurrency controls ](#send-commands-velocity) + [ ### Using error controls ](#send-commands-maxerrors) ### Using concurrency controls You can control the number of managed nodes that run a command simultaneously by using the `max-concurrency` parameter (the **Concurrency** options in the **Run a command** page). You can specify either an absolute number of managed nodes, for example **10**, or a percentage of the target set, for example **10%**. The queueing system delivers the command to a single node and waits until the system acknowledges the initial invocation before sending the command to two more nodes. The system exponentially sends commands to more nodes until the system meets the value of `max-concurrency`. The default for value `max-concurrency` is 50. The following examples show you how to specify values for the `max-concurrency` parameter. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --max-concurrency 10 \ --targets Key=tag:Environment,Values=Development \ [...] ``` ``` aws ssm send-command \ --document-name document-name \ --max-concurrency 10% \ --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --max-concurrency 10 ^ --targets Key=tag:Environment,Values=Development ^ [...] ``` ``` aws ssm send-command ^ --document-name document-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 managed nodes by setting an error limit using the `max-errors` parameters (the **Error threshold** field in the **Run a command** page). The parameter specifies how many errors are allowed before the system stops sending the command to additional managed nodes. 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 managed nodes after the first error result is returned. If you send a command to 50 managed nodes and set `max-errors` to **10%**, then the system stops sending the command to additional nodes 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 might 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. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name document-name \ --max-errors 10 \ --targets Key=tag:Database,Values=Development \ [...] ``` ``` aws ssm send-command \ --document-name document-name \ --max-errors 10% \ --targets Key=tag:Environment,Values=Development \ [...] ``` ``` aws ssm send-command \ --document-name document-name \ --max-concurrency 1 \ --max-errors 1 \ --targets Key=tag:Environment,Values=Production \ [...] ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name document-name ^ --max-errors 10 ^ --targets Key=tag:Database,Values=Development ^ [...] ``` ``` aws ssm send-command ^ --document-name document-name ^ --max-errors 10% ^ --targets Key=tag:Environment,Values=Development ^ [...] ``` ``` aws ssm send-command ^ --document-name document-name ^ --max-concurrency 1 ^ --max-errors 1 ^ --targets Key=tag:Environment,Values=Production ^ [...] ``` ------ # Canceling a command You can attempt to cancel a command as long as the service shows that it's in either a Pending or Executing state. However, even if a command is still in one of these states, we can't guarantee that the command will be canceled 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/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**. 1. Select the command invocation that you want to cancel. 1. Choose **Cancel command**. **To cancel a command using the AWS CLI** Run the following command. Replace each *example resource placeholder* with your own information. ------ #### [ Linux & macOS ] ``` aws ssm cancel-command \ --command-id "command-ID" \ --instance-ids "instance-ID" ``` ------ #### [ Windows ] ``` aws ssm cancel-command ^ --command-id "command-ID" ^ --instance-ids "instance-ID" ``` ------ For information about the status of a canceled command, see [Understanding command statuses](monitor-commands.md). # Using exit codes in commands In some cases, you might need to manage how your commands are handled by using exit codes. ## Specify exit codes in commands Using Run Command, a tool in AWS Systems Manager, you can specify exit codes to determine how commands are handled. By default, the exit code of the last command run in a script is reported as the exit code for the entire script. For example, you have a script that contains three commands. The first one fails but the following ones succeed. Because the final command succeeded, the status of the execution is reported as `succeeded`. **Shell scripts** To fail the entire script at the first command failure, you can include a shell conditional statement to exit the script if any command before the final one fails. Use the following approach. ``` if [ $? != 0 ] then exit fi ``` In the following example, the entire script fails if the first command fails. ``` cd /test if [ $? != 0 ] then echo "Failed" exit 1 fi date ``` **PowerShell scripts** PowerShell requires that you call `exit` explicitly in your scripts for Run Command to successfully capture the exit code. ``` if ($?) {} else {exit } exit ``` Here is an example: ``` cd C:\ if ($?) {echo "Success"} else {exit 1} date ``` # Handling reboots when running commands If you use Run Command, a tool in AWS Systems Manager, to run scripts that reboot managed nodes, we recommend that you specify an exit code in your script. If you attempt to reboot a node from a script by using some other mechanism, the script execution status might not be updated correctly, even if the reboot is the last step in your script. For Windows managed nodes, you specify `exit 3010` in your script. For Linux and macOS managed nodes, you specify `exit 194`. The exit code instructs AWS Systems Manager Agent (SSM Agent) to reboot the managed node, 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. **Note** The reboot script can't be part of an `aws:runDocument` plugin. If a document contains the reboot script and another document tries to run that document through the `aws:runDocument` plugin, SSM Agent returns an error. **Create idempotent scripts** When developing scripts that reboot managed nodes, 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's only intended to run once. Here is an outline example of an idempotent script that reboots a managed node 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 } ``` **Examples** The following script samples use exit codes to restart managed nodes. The Linux example installs package updates on Amazon Linux, and then restarts the node. The Windows Server example installs the Telnet-Client on the node, and then restarts it. ------ #### [ Amazon Linux 2 ] ``` #!/bin/bash yum -y update needs-restarting -r if [ $? -eq 1 ] then exit 194 else exit 0 fi ``` ------ #### [ Windows ] ``` $telnet = Get-WindowsFeature -Name Telnet-Client if (-not $telnet.Installed) { # Install Telnet and then send a reboot request to SSM Agent. Install-WindowsFeature -Name "Telnet-Client" exit 3010 } ``` ------ # Understanding command statuses Run Command, a tool in AWS Systems Manager, reports detailed status information about the different states a command experiences during processing and for each managed node that processed the command. You can monitor command statuses using the following methods: + Choose the **Refresh** icon on the **Commands** tab in the Run Command console interface. + Call [list-commands](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-commands.html) or [list-command-invocations](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-command-invocations.html) using the AWS Command Line Interface (AWS CLI). Or call [Get-SSMCommand](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommand.html) or [Get-SSMCommandInvocation](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommandInvocation.html) using AWS Tools for Windows PowerShell. + Configure Amazon EventBridge to respond to state or status changes. + Configure Amazon Simple Notification Service (Amazon SNS) to send notifications for all status changes or specific statuses such as `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 SSM document. For more information about plugins, see [Command document plugin reference](documents-command-ssm-plugin-reference.md). When you send a command to multiple managed nodes at the same time, each copy of the command targeting each node is a *command invocation*. For example, if you use the `AWS-RunShellScript` document and send an `ifconfig` command to 20 Linux 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. **Note** If you run commands to large numbers of managed nodes 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 [Run commands at scale](send-commands-multiple.md). **Detailed status for command plugins and invocations** | Status | Details | | --- | --- | | Pending | The command hasn't yet been sent to the managed node or hasn't been received by SSM Agent. If the command isn't received by the agent before the length of time passes that is equal to the sum of the Timeout (seconds) parameter and the Execution timeout parameter, the status changes to Delivery Timed Out. | | InProgress | Systems Manager is attempting to send the command to the managed node, or the command was received by SSM Agent and has started running on the instance. Depending on the result of all command plugins, the status changes to Success, Failed, Delivery Timed Out, or Execution Timed Out. Exception: If the agent isn't running or available on the node, the command status remains at In Progress until the agent is available again, or until the execution timeout limit is reached. The status then changes to a terminal state. | | Delayed | The system attempted to send the command to the managed node but wasn't successful. The system retries again. | | Success | This status is returned under a variety of conditions. This status doesn't mean the command was processed on the node. For example, the command can be received by SSM Agent on the managed node and return an exit code of zero as a result of your PowerShell ExecutionPolicy preventing the command from running. This is a terminal state. Conditions that result in a command returning a Success status are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/monitor-commands.html) The same conditions apply when targeting resource groups. 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). | | DeliveryTimedOut | The command wasn't delivered to the managed node before the total timeout expired. Total timeouts don't count against the parent command’s max-errors limit, but they do contribute to whether the parent command status is Success, Incomplete, or Delivery Timed Out. This is a terminal state. | | ExecutionTimedOut | Command automation started on the managed node, but the command wasn’t completed before the execution timeout expired. Execution timeouts count as a failure, which will send a non-zero reply and Systems Manager will exit the attempt to run the command automation, and report a failure status. | | Failed | The command wasn't successful on the managed node. For a plugin, this indicates that the result code wasn't zero. For a command invocation, this indicates that the result code for one or more plugins wasn't zero. Invocation failures count against the max-errors limit of the parent command. This is a terminal state. | | Cancelled | The command was canceled before it was completed. This is a terminal state. | | Undeliverable | The command can't be delivered to the managed node. The node might not exist or it might not be responding. Undeliverable invocations don't count against the parent command’s max-errors limit, but they do contribute to whether the parent command status is Success or Incomplete. For example, if all invocations in a command have the status Undeliverable, then the command status returned is Failed. However, if a command has five invocations, four of which return the status Undeliverable and one of which returns the status Success, then the parent command's status is Success. 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. | | InvalidPlatform | The command was sent to a managed node that didn't match the required platforms specified by the chosen document. Invalid Platform doesn't count against the parent command’s max-errors limit, but it does contribute to whether the parent command status is Success or Failed. For example, if all invocations in a command have the status Invalid Platform, then the command status returned is Failed. However, if a command has five invocations, four of which return the status Invalid Platform and one of which returns the status Success, then the parent command's status is Success. This is a terminal state. | | AccessDenied | The AWS Identity and Access Management (IAM) user or role initiating the command doesn't have access to the targeted managed node. Access Denied doesn't count against the parent command’s max-errors limit, but it does contribute to whether the parent command status is Success or Failed. For example, if all invocations in a command have the status Access Denied, then the command status returned is Failed. However, if a command has five invocations, four of which return the status Access Denied and one 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 wasn't yet received by an agent on any managed nodes. | | InProgress | The command has been sent to at least one managed node but hasn't reached a final state on all nodes. | | Delayed | The system attempted to send the command to the node but wasn't successful. The system retries again. | | Success | The command was received by SSM Agent on all specified or targeted managed nodes and returned an exit code of zero. All command invocations have reached a terminal state, and the value of max-errors wasn't reached. This status doesn't mean the command was successfully processed on all specified or targeted managed nodes. This is a terminal state. 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). | | DeliveryTimedOut | The command wasn't delivered to the managed node before the total timeout expired. The value of max-errors or more command invocations shows a status of Delivery Timed Out. This is a terminal state. | | Failed | The command wasn't successful on the managed node. 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 managed nodes and one or more of the invocations doesn't have a value of Success. However, not enough invocations failed for the status to be Failed. This is a terminal state. | | Cancelled | The command was canceled before it was completed. This is a terminal state. | | RateExceeded | The number of managed nodes targeted by the command exceeded the account quota for pending invocations. The system has canceled the command before executing it on any node. This is a terminal state. | | AccessDenied | The user or role initiating the command doesn't have access to the targeted resource group. AccessDenied doesn't 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 doesn't match any managed nodes. This is a terminal state. | ## Understanding command timeout values Systems Manager enforces the following timeout values when running commands. **Total Timeout** In the Systems Manager console, you specify the timeout value in the **Timeout (seconds)** field. After a command is sent, Run Command checks whether the command has expired or not. If a command reaches the command expiration limit (total timeout), it changes status to `DeliveryTimedOut` for all invocations that have the status `InProgress`, `Pending` or `Delayed`. ![\[The Timeout (seconds) field in the Systems Manager console\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/run-command-delivery-time-out-time-out-seconds.png) On a more technical level, total timeout (**Timeout (seconds)**) is a combination of two timeout values, as shown here: `Total timeout = "Timeout(seconds)" from the console + "timeoutSeconds": "{{ executionTimeout }}" from your SSM document` For example, the default value of **Timeout (seconds)** in the Systems Manager console is 600 seconds. If you run a command by using the `AWS-RunShellScript` SSM document, the default value of **"timeoutSeconds": "\$1\$1 executionTimeout \$1\$1"** is 3600 seconds, as shown in the following document sample: ``` "executionTimeout": { "type": "String", "default": "3600", "runtimeConfig": { "aws:runShellScript": { "properties": [ { "timeoutSeconds": "{{ executionTimeout }}" ``` This means the command runs for 4,200 seconds (70 minutes) before the system sets the command status to `DeliveryTimedOut`. **Execution Timeout** In the Systems Manager console, you specify the execution timeout value in the **Execution Timeout** field, if available. Not all SSM documents require that you specify an execution timeout. The **Execution Timeout** field is only displayed when a corresponding input parameter has been defined in the SSM document. If specified, the command must complete within this time period. **Note** Run Command relies on the SSM Agent document terminal response to determine whether or not the command was delivered to the agent. SSM Agent must send an `ExecutionTimedOut` signal for an invocation or command to be marked as `ExecutionTimedOut`. ![\[The Execution Timeout field in the Systems Manager console\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/run-command-execution-timeout-console.png) **Default Execution Timeout** If a SSM document doesn't require that you explicitly specify an execution timeout value, then Systems Manager enforces the hard-coded default execution timeout. **How Systems Manager reports timeouts** If Systems Manager receives an `execution timeout` reply from SSM Agent on a target, then Systems Manager marks the command invocation as `executionTimeout`. If Run Command doesn't receive a document terminal response from SSM Agent, the command invocation is marked as `deliveryTimeout`. To determine timeout status on a target, SSM Agent combines all parameters and the content of the SSM document to calculate for `executionTimeout`. When SSM Agent determines that a command has timed out, it sends `executionTimeout` to the service. The default for **Timeout (seconds)** is 3600 seconds. The default for **Execution Timeout** is also 3600 seconds. Therefore, the total default timeout for a command is 7200 seconds. **Note** SSM Agent processes `executionTimeout` differently depending on the type of SSM document and the document version. # Run Command walkthroughs The walkthroughs in this section show you how to run commands with Run Command, a tool in AWS Systems Manager, using either the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell. **Topics** + [ # Updating software using Run Command ](run-command-tutorial-update-software.md) + [ # Walkthrough: Use the AWS CLI with Run Command ](walkthrough-cli.md) + [ # Walkthrough: Use the AWS Tools for Windows PowerShell with Run Command ](walkthrough-powershell.md) You can also view sample commands in the following references. + [Systems Manager AWS CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/ssm/) + [AWS Tools for Windows PowerShell - AWS Systems Manager](https://docs.aws.amazon.com/powershell/latest/reference/items/SimpleSystemsManagement_cmdlets.html) # Updating software using Run Command The following procedures describe how to update software on your managed nodes. ## Updating the SSM Agent using Run Command The following procedure describes how to update the SSM Agent running on your managed nodes. You can update to either the latest version of SSM Agent or downgrade to an older version. When 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** If an instance is running macOS version 13.0 (Ventura) or later, the instance must have the SSM Agent version 3.1.941.0 or higher to run the AWS-UpdateSSMAgent document. If the instance is running a version of SSM Agent released before 3.1.941.0, you can update your SSM Agent to run the AWS-UpdateSSMAgent document by running `brew update` and `brew upgrade amazon-ssm-agent` commands. To be notified about SSM Agent updates, subscribe to the [SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) 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/](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 **`AWS-UpdateSSMAgent`**. 1. In the **Command parameters** section, specify values for the following parameters, if you want: 1. (Optional) For **Version**, enter the version of SSM Agent to install. You can install [older versions](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) of the agent. If you don't specify a version, the service installs the latest version. 1. (Optional) For **Allow Downgrade**, choose **true** to install an earlier version of SSM Agent. If you choose this option, specify the [earlier](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md) version number. Choose **false** to install only the newest version of the service. 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, 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 [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. ## Updating PowerShell using Run Command The following procedure describes how to update PowerShell to version 5.1 on your Windows Server 2012 and 2012 R2 managed nodes. The script provided in this procedure downloads the Windows Management Framework (WMF) version 5.1 update, and starts the installation of the update. The node reboots during this process because this is required when installing WMF 5.1. The download and installation of the update takes approximately five minutes to complete. **To update PowerShell using Run Command** 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 **`AWS-RunPowerShellScript`**. 1. In the **Commands** section, paste the following commands for your operating system. ------ #### [ Windows Server 2012 R2 ] ``` Set-Location -Path "C:\Windows\Temp" Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839516" -OutFile "Win8.1AndW2K12R2-KB3191564-x64.msu" Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('Win8.1AndW2K12R2-KB3191564-x64.msu', '/quiet') ``` ------ #### [ Windows Server 2012 ] ``` Set-Location -Path "C:\Windows\Temp" Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839513" -OutFile "W2K12-KB3191565-x64.msu" Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('W2K12-KB3191565-x64.msu', '/quiet') ``` ------ 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, 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 [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. After the managed node reboots and the installation of the update is complete, connect to your node to confirm that PowerShell successfully upgraded to version 5.1. To check the version of PowerShell on your node, open PowerShell and enter `$PSVersionTable`. The `PSVersion` value in the output table shows 5.1 if the upgrade was successful. If the `PSVersion` value is different than 5.1, for example 3.0 or 4.0, review the **Setup** logs in Event Viewer under **Windows Logs**. These logs indicate why the update installation failed. # Walkthrough: Use the AWS CLI with Run Command The following sample walkthrough shows you how to use the AWS Command Line Interface (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 AWS Systems Manager pre-configured documents shown in this topic. The commands or scripts specified in Systems Manager documents run with administrative permissions on your managed nodes. 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 node. For all other users, you should create restrictive documents and share them with specific users. **Topics** + [ ## Step 1: Getting started ](#walkthrough-cli-settings) + [ ## Step 2: Run shell scripts to view resource details ](#walkthrough-cli-run-scripts) + [ ## Step 3: Send simple commands using the `AWS-RunShellScript` document ](#walkthrough-cli-example-1) + [ ## Step 4: Run a simple Python script using Run Command ](#walkthrough-cli-example-2) + [ ## Step 5: Run a Bash script using Run Command ](#walkthrough-cli-example-3) ## Step 1: Getting started You must either have administrator permissions on the managed node you want to configure or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM). Also note, this example uses the US East (Ohio) Region (us-east-2). Run Command is available in the AWS Regions listed in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. For more information, see [Setting up managed nodes for AWS Systems Manager](systems-manager-setting-up-nodes.md). **To run commands using the AWS CLI** 1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 1. List all available documents. This command lists all of the documents available for your account based on IAM permissions. ``` aws ssm list-documents ``` 1. Verify that an managed node is ready to receive commands. The output of the following command shows if managed nodes are online. ------ #### [ Linux & macOS ] ``` aws ssm describe-instance-information \ --output text --query "InstanceInformationList[*]" ``` ------ #### [ Windows ] ``` aws ssm describe-instance-information ^ --output text --query "InstanceInformationList[*]" ``` ------ 1. Run the following command to view details about a particular managed node. **Note** To run the commands in this walkthrough, replace the instance and command IDs. For managed AWS IoT Greengrass core devices, use the mi-*ID\$1number* for instance ID. The command ID is returned as a response to **send-command**. Instance IDs are available from Fleet Manager, a tool in AWS Systems Manager.. ------ #### [ Linux & macOS ] ``` aws ssm describe-instance-information \ --instance-information-filter-list key=InstanceIds,valueSet=instance-ID ``` ------ #### [ Windows ] ``` aws ssm describe-instance-information ^ --instance-information-filter-list key=InstanceIds,valueSet=instance-ID ``` ------ ## Step 2: Run shell scripts to view resource details Using Run Command and the `AWS-RunShellScript` document, you can run any command or script on a managed node as if you were logged on locally. **View the description and available parameters** Run the following command to view a description of the Systems Manager JSON document. ------ #### [ Linux & macOS ] ``` aws ssm describe-document \ --name "AWS-RunShellScript" \ --query "[Document.Name,Document.Description]" ``` ------ #### [ Windows ] ``` aws ssm describe-document ^ --name "AWS-RunShellScript" ^ --query "[Document.Name,Document.Description]" ``` ------ Run the following command to view the available parameters and details about those parameters. ------ #### [ Linux & macOS ] ``` aws ssm describe-document \ --name "AWS-RunShellScript" \ --query "Document.Parameters[*]" ``` ------ #### [ Windows ] ``` aws ssm describe-document ^ --name "AWS-RunShellScript" ^ --query "Document.Parameters[*]" ``` ------ ## Step 3: Send simple commands using the `AWS-RunShellScript` document Run the following command to get IP information for a Linux managed node. If you're targeting a Windows Server managed node, change the `document-name` to `AWS-RunPowerShellScript` and change the `command` from `ifconfig` to `ipconfig`. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --instance-ids "instance-ID" \ --document-name "AWS-RunShellScript" \ --comment "IP config" \ --parameters commands=ifconfig \ --output text ``` ------ #### [ Windows ] ``` 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 run this command again to see the response data. ------ #### [ Linux & macOS ] ``` aws ssm list-command-invocations \ --command-id $sh-command-id \ --details ``` ------ #### [ Windows ] ``` aws ssm list-command-invocations ^ --command-id $sh-command-id ^ --details ``` ------ **Identify user** The following command displays the default user running the commands. ------ #### [ Linux & macOS ] ``` sh_command_id=$(aws ssm send-command \ --instance-ids "instance-ID" \ --document-name "AWS-RunShellScript" \ --comment "Demo run shell script on Linux managed node" \ --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 managed node. This example uses the Command ID that was returned in the previous command. ------ #### [ Linux & macOS ] ``` aws ssm list-commands \ --command-id "command-ID" ``` ------ #### [ Windows ] ``` 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 managed node basis. ------ #### [ Linux & macOS ] ``` aws ssm list-command-invocations \ --command-id "command-ID" \ --details ``` ------ #### [ Windows ] ``` aws ssm list-command-invocations ^ --command-id "command-ID" ^ --details ``` ------ **Get command information with response data for a specific managed node** The following command returns the output of the original `aws ssm send-command` request for a specific managed node. ------ #### [ Linux & macOS ] ``` aws ssm list-command-invocations \ --instance-id instance-ID \ --command-id "command-ID" \ --details ``` ------ #### [ Windows ] ``` aws ssm list-command-invocations ^ --instance-id instance-ID ^ --command-id "command-ID" ^ --details ``` ------ **Display Python version** The following command returns the version of Python running on a node. ------ #### [ Linux & macOS ] ``` 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='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}"' ``` ------ ## Step 4: Run a simple Python script using Run Command The following command runs a simple Python "Hello World" script using Run Command. ------ #### [ Linux & macOS ] ``` 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}"' ``` ------ ## Step 5: Run a Bash script using Run Command The examples in this section demonstrate how to run the following bash script using Run Command. For examples of using Run Command to run scripts stored in remote locations, see [Running scripts from Amazon S3](integration-s3.md) and [Running scripts from GitHub](integration-remote-scripts.md). ``` #!/bin/bash yum -y update yum install -y ruby cd /home/ec2-user curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install chmod +x ./install ./install auto ``` This script installs the AWS CodeDeploy agent on Amazon Linux and Red Hat Enterprise Linux (RHEL) instances, as described in [Create an Amazon EC2 instance for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/instances-ec2-create.html) in the *AWS CodeDeploy User Guide*. The script installs the CodeDeploy agent from an AWS managed S3 bucket in thee US East (Ohio) Region (us-east-2), `aws-codedeploy-us-east-2`. **Run a bash script in an AWS CLI command** The following sample demonstrates how to include the bash script in a CLI command using the `--parameters` option. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name "AWS-RunShellScript" \ --targets '[{"Key":"InstanceIds","Values":["instance-id"]}]' \ --parameters '{"commands":["#!/bin/bash","yum -y update","yum install -y ruby","cd /home/ec2-user","curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install","chmod +x ./install","./install auto"]}' ``` ------ **Run a bash script in a JSON file** In the following example, the content of the bash script is stored in a JSON file, and the file is included in the command using the `--cli-input-json` option. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --document-name "AWS-RunShellScript" \ --targets "Key=InstanceIds,Values=instance-id" \ --cli-input-json file://installCodeDeployAgent.json ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name "AWS-RunShellScript" ^ --targets "Key=InstanceIds,Values=instance-id" ^ --cli-input-json file://installCodeDeployAgent.json ``` ------ The contents of the referenced `installCodeDeployAgent.json` file is shown in the following example. ``` { "Parameters": { "commands": [ "#!/bin/bash", "yum -y update", "yum install -y ruby", "cd /home/ec2-user", "curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install", "chmod +x ./install", "./install auto" ] } } ``` # Walkthrough: Use the AWS Tools for Windows PowerShell with Run Command The following examples show how to use the AWS 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 AWS 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 permission on your managed nodes. If a user has permission to run any of the predefined Systems Manager documents (any document that begins with AWS), then that user also has administrator access to the node. For all other users, you should create restrictive documents and share them with specific users. **Topics** + [ ## Configure AWS Tools for Windows PowerShell session settings ](#walkthrough-powershell-settings) + [ ## List all available documents ](#walkthrough-powershell-all-documents) + [ ## Run PowerShell commands or scripts ](#walkthrough-powershell-run-script) + [ ## Install an application using the `AWS-InstallApplication` document ](#walkthrough-powershell-install-application) + [ ## Install a PowerShell module using the `AWS-InstallPowerShellModule` JSON document ](#walkthrough-powershell-install-module) + [ ## Join a managed node to a Domain using the `AWS-JoinDirectoryServiceDomain` JSON document ](#walkthrough-powershell-domain-join) + [ ## Send Windows metrics to Amazon CloudWatch Logs using the `AWS-ConfigureCloudWatch` document ](#walkthrough-powershell-windows-metrics) + [ ## Turn on or turn off Windows automatic update using the `AWS-ConfigureWindowsUpdate` document ](#walkthrough-powershell-enable-windows-update) + [ ## Manage Windows updates using Run Command ](#walkthough-powershell-windows-updates) ## Configure AWS Tools for Windows PowerShell session settings **Specify your credentials** Open **Tools for Windows PowerShell** on your local computer and run the following command to specify your credentials. You must either have administrator permissions on the managed nodes you want to configure or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM). For more information, see [Setting up managed nodes for AWS Systems Manager](systems-manager-setting-up-nodes.md). ``` 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 available in the AWS Regions listed in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. ``` Set-DefaultAWSRegion ` -Region us-east-2 ``` ## List all available documents This command lists all 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 a managed node as if you were logged on locally. You can issue commands or enter a path to a local script to run the command. **Note** For information about rebooting managed nodes when using Run Command to call scripts, see [Handling reboots when running commands](send-commands-reboot.md). **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 managed nodes. ``` $runPSCommand = Send-SSMCommand ` -InstanceIds @("instance-ID-1", "instance-ID-2") ` -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 `CommandId` to get the status of the command execution on both managed nodes. This example uses the `CommandId` 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 managed node** The following command uses the `CommandId` from the previous command to get the status of the command execution on a per managed node basis. ``` Get-SSMCommandInvocation ` -CommandId $runPSCommand.CommandId ``` **Get command information with response data for a specific managed node** The following command returns the output of the original `Send-SSMCommand` for a specific managed node. ``` 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. ``` $cancelCommand = Send-SSMCommand ` -InstanceIds @("instance-ID-1","instance-ID-2") ` -DocumentName "AWS-RunPowerShellScript" ` -Comment "Demo AWS-RunPowerShellScript with two instances" ` -Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'} Stop-SSMCommand -CommandId $cancelCommand.CommandId ``` **Check the command status** The following command checks the status of the `Cancel` command. ``` Get-SSMCommand ` -CommandId $cancelCommand.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 managed nodes. The command requires the path or address to an MSI. **Note** For information about rebooting managed nodes when using Run Command to call scripts, see [Handling reboots when running commands](send-commands-reboot.md). **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 managed node 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 managed node** The following command uses the `CommandId` to get the status of the command execution. ``` Get-SSMCommandInvocation ` -CommandId $installAppCommand.CommandId ` -Details $true ``` **Get command information with response data for a specific managed node** 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 managed nodes. For more information about PowerShell modules, see [Windows PowerShell Modules](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_modules?view=powershell-6). **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 S3 bucket named "amzn-s3-demo-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 amzn-s3-demo-bucket ``` **Get command information per managed node** The following command uses the `CommandId` to get the status of the command execution. ``` Get-SSMCommandInvocation ` -CommandId $installPSCommand.CommandId ` -Details $true ``` **Get command information with response data for the managed node** The following command returns the output of the original `Send-SSMCommand` for the specific `CommandId`. ``` Get-SSMCommandInvocation ` -CommandId $installPSCommand.CommandId ` -Details $true | Select -ExpandProperty CommandPlugins ``` ## Join a managed node to a Domain using the `AWS-JoinDirectoryServiceDomain` JSON document Using Run Command, you can quickly join a managed node to an AWS Directory Service domain. Before executing this command, [create a directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_create_directory.html). We also recommend that you learn more about the Directory Service. For more information, see the [AWS Directory Service Administration Guide](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/). You can only join a managed node to a domain. You can't remove a node from a domain. **Note** For information about managed nodes when using Run Command to call scripts, see [Handling reboots when running commands](send-commands-reboot.md). **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 a managed node to a domain The following command joins a managed node to the given Directory Service domain and uploads any generated output to the example Amazon Simple Storage Service (Amazon S3) bucket. ``` $domainJoinCommand = Send-SSMCommand ` -InstanceId instance-ID ` -DocumentName "AWS-JoinDirectoryServiceDomain" ` -Parameter @{'directoryId'='d-example01'; 'directoryName'='ssm.example.com'; 'dnsIpAddresses'=@('192.168.10.195', '192.168.20.97')} ` -OutputS3BucketName amzn-s3-demo-bucket ``` **Get command information per managed node** The following command uses the `CommandId` to get the status of the command execution. ``` Get-SSMCommandInvocation ` -CommandId $domainJoinCommand.CommandId ` -Details $true ``` **Get command information with response data for the managed node** This command returns the output of the original `Send-SSMCommand` for the specific `CommandId`. ``` Get-SSMCommandInvocation ` -CommandId $domainJoinCommand.CommandId ` -Details $true | Select -ExpandProperty CommandPlugins ``` ## Send Windows metrics to Amazon CloudWatch Logs 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 allow 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 aren't included. If you turn off logging and then later turn logging back on, 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 CloudWatch Logs. If you previously turned on CloudWatch integration in EC2Config, the Systems Manager settings override any settings stored locally on the managed node 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 a single managed node, see [Collecting metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) in the *Amazon CloudWatch User Guide*. **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 managed node 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":"region", "LogGroup":"my-log-group", "LogStream":"instance-id"}}], "Flows":{"Flows":["ApplicationEventLog,CloudWatch"]}}}'} ``` **Get command information per managed node** The following command uses the `CommandId` to get the status of the command execution. ``` Get-SSMCommandInvocation ` -CommandId $cloudWatchCommand.CommandId ` -Details $true ``` **Get command information with response data for a specific managed node** 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*. ``` $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,AWS.EC2.Windows.CloudWatch", "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":"region", "NameSpace":"Windows-Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'} ``` ## Turn on or turn off Windows automatic update using the `AWS-ConfigureWindowsUpdate` document Using Run Command and the `AWS-ConfigureWindowsUpdate` document, you can turn on or turn off automatic Windows updates on your Windows Server managed nodes. 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 managed node 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 officially supported on Windows Server 2012 and later versions. **View the description and available parameters** ``` Get-SSMDocumentDescription ` –Name "AWS-ConfigureWindowsUpdate" ``` **View more information about parameters** ``` Get-SSMDocumentDescription ` -Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters ``` ### Turn on 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'} ``` **View command status for allowing Windows automatic update** The following command uses the `CommandId` to get the status of the command execution for allowing Windows automatic update. ``` Get-SSMCommandInvocation ` -Details $true ` -CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins ``` ### Turn off Windows automatic update The following command lowers the Windows Update notification level so the system checks for updates but doesn't automatically update the managed node. ``` $configureWindowsUpdateCommand = Send-SSMCommand ` -InstanceId instance-ID ` -DocumentName "AWS-ConfigureWindowsUpdate" ` -Parameters @{'updateLevel'='NeverCheckForUpdates'} ``` **View command status for turning off Windows automatic update** The following command uses the `CommandId` to get the status of the command execution for turning off 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 Windows Server managed nodes. This command scans for or installs missing updates on your managed nodes 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 managed nodes when using Run Command to call scripts, see [Handling reboots when running commands](send-commands-reboot.md). 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'='kb-ID-1,kb-ID-2,kb-ID-3';'AllowReboot'='True'} ``` ### Install important missing Windows updates ``` Send-SSMCommand ` -InstanceId instance-ID ` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'} ``` ### Install missing Windows updates with specific exclusions ``` Send-SSMCommand ` -InstanceId instance-ID ` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Install';'ExcludeKbs'='kb-ID-1,kb-ID-2';'AllowReboot'='True'} ``` # Troubleshooting Systems Manager Run Command Run Command, a tool in AWS Systems Manager, provides status details with each command execution. For more information about the details of command statuses, see [Understanding command statuses](monitor-commands.md). You can also use the information in this topic to help troubleshoot problems with Run Command. **Topics** + [ ## Some of my managed nodes are missing ](#where-are-instances) + [ ## A step in my script failed, but the overall status is 'succeeded' ](#ts-exit-codes) + [ ## SSM Agent isn't running properly ](#ts-ssmagent-linux) ## Some of my managed nodes are missing 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 managed nodes you can choose to run the command on. 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. After you create, activate, reboot, or restart a managed node, install Run Command on a node, or attach an AWS Identity and Access Management (IAM) instance profile to a node, it can take a few minutes for the managed node to be added to the list. ## A step in my script failed, but the overall status is 'succeeded' Using Run Command, you can define how your scripts handle exit codes. By default, the exit code of the last command run in a script is reported as the exit code for the entire script. You can, however, include a conditional statement to exit the script if any command before the final one fails. For information and examples, see [Specify exit codes in commands](run-command-handle-exit-status.md#command-exit-codes). ## SSM Agent isn't running properly If you experience problems running commands using Run Command, there might be a problem with the SSM Agent. For information about investigating issues with SSM Agent, see [Troubleshooting SSM Agent](troubleshooting-ssm-agent.md).