Menu
AWS Systems Manager
API Reference (API Version 2014-11-06)

SendCommand

Executes commands on one or more managed instances.

Request Syntax

{
   "Comment": "string",
   "DocumentHash": "string",
   "DocumentHashType": "string",
   "DocumentName": "string",
   "InstanceIds": [ "string" ],
   "MaxConcurrency": "string",
   "MaxErrors": "string",
   "NotificationConfig": { 
      "NotificationArn": "string",
      "NotificationEvents": [ "string" ],
      "NotificationType": "string"
   },
   "OutputS3BucketName": "string",
   "OutputS3KeyPrefix": "string",
   "OutputS3Region": "string",
   "Parameters": { 
      "string" : [ "string" ]
   },
   "ServiceRoleArn": "string",
   "Targets": [ 
      { 
         "Key": "string",
         "Values": [ "string" ]
      }
   ],
   "TimeoutSeconds": number
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Comment

User-specified information about the command, such as a brief description of what the command should do.

Type: String

Length Constraints: Maximum length of 100.

Required: No

DocumentHash

The Sha256 or Sha1 hash created by the system when the document was created.

Note

Sha1 hashes have been deprecated.

Type: String

Length Constraints: Maximum length of 256.

Required: No

DocumentHashType

Sha256 or Sha1.

Note

Sha1 hashes have been deprecated.

Type: String

Valid Values: Sha256 | Sha1

Required: No

DocumentName

Required. The name of the Systems Manager document to execute. This can be a public document or a custom document.

Type: String

Pattern: ^[a-zA-Z0-9_\-.:/]{3,128}$

Required: Yes

InstanceIds

The instance IDs where the command should execute. You can specify a maximum of 50 IDs. If you prefer not to list individual instance IDs, you can instead send commands to a fleet of instances using the Targets parameter, which accepts EC2 tags. For more information about how to use Targets, see Sending Commands to a Fleet.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Pattern: (^i-(\w{8}|\w{17})$)|(^mi-\w{17}$)

Required: No

MaxConcurrency

(Optional) The maximum number of instances that are allowed to execute the command at the same time. You can specify a number such as 10 or a percentage such as 10%. The default value is 50. For more information about how to use MaxConcurrency, see Using Concurrency Controls.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7.

Pattern: ^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$

Required: No

MaxErrors

The maximum number of errors allowed without the command failing. When the command fails one more time beyond the value of MaxErrors, the systems stops sending the command to additional targets. You can specify a number like 10 or a percentage like 10%. The default value is 50. For more information about how to use MaxErrors, see Using Error Controls.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 7.

Pattern: ^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$

Required: No

NotificationConfig

Configurations for sending notifications.

Type: NotificationConfig object

Required: No

OutputS3BucketName

The name of the S3 bucket where command execution responses should be stored.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 63.

Required: No

OutputS3KeyPrefix

The directory structure within the S3 bucket where the responses should be stored.

Type: String

Length Constraints: Maximum length of 500.

Required: No

OutputS3Region

(Deprecated) You can no longer specify this parameter. The system ignores it. Instead, Systems Manager automatically determines the Amazon S3 bucket region.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 20.

Required: No

Parameters

The required and optional parameters specified in the document being executed.

Type: String to array of strings map

Required: No

ServiceRoleArn

The IAM role that Systems Manager uses to send notifications.

Type: String

Required: No

Targets

(Optional) An array of search criteria that targets instances using a Key,Value combination that you specify. Targets is required if you don't provide one or more instance IDs in the call. For more information about how to use Targets, see Sending Commands to a Fleet.

Type: Array of Target objects

Array Members: Minimum number of 0 items. Maximum number of 5 items.

Required: No

TimeoutSeconds

If this time is reached and the command has not already started executing, it will not execute.

Type: Integer

Valid Range: Minimum value of 30. Maximum value of 2592000.

Required: No

Response Syntax

{
   "Command": { 
      "CommandId": "string",
      "Comment": "string",
      "CompletedCount": number,
      "DocumentName": "string",
      "ErrorCount": number,
      "ExpiresAfter": number,
      "InstanceIds": [ "string" ],
      "MaxConcurrency": "string",
      "MaxErrors": "string",
      "NotificationConfig": { 
         "NotificationArn": "string",
         "NotificationEvents": [ "string" ],
         "NotificationType": "string"
      },
      "OutputS3BucketName": "string",
      "OutputS3KeyPrefix": "string",
      "OutputS3Region": "string",
      "Parameters": { 
         "string" : [ "string" ]
      },
      "RequestedDateTime": number,
      "ServiceRole": "string",
      "Status": "string",
      "StatusDetails": "string",
      "TargetCount": number,
      "Targets": [ 
         { 
            "Key": "string",
            "Values": [ "string" ]
         }
      ]
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Command

The request as it was received by Systems Manager. Also provides the command ID which can be used future references to this request.

Type: Command object

Errors

For information about the errors that are common to all actions, see Common Errors.

DuplicateInstanceId

You cannot specify an instance ID in more than one association.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 400

InvalidDocument

The specified document does not exist.

HTTP Status Code: 400

InvalidInstanceId

The following problems can cause this exception:

You do not have permission to access the instance.

The SSM Agent is not running. On managed instances and Linux instances, verify that the SSM Agent is running. On EC2 Windows instances, verify that the EC2Config service is running.

The SSM Agent or EC2Config service is not registered to the SSM endpoint. Try reinstalling the SSM Agent or EC2Config service.

The instance is not in valid state. Valid states are: Running, Pending, Stopped, Stopping. Invalid states are: Shutting-down and Terminated.

HTTP Status Code: 400

InvalidNotificationConfig

One or more configuration items is not valid. Verify that a valid Amazon Resource Name (ARN) was provided for an Amazon SNS topic.

HTTP Status Code: 400

InvalidOutputFolder

The S3 bucket does not exist.

HTTP Status Code: 400

InvalidParameters

You must specify values for all required parameters in the Systems Manager document. You can only supply values to parameters defined in the Systems Manager document.

HTTP Status Code: 400

InvalidRole

The role name can't contain invalid characters. Also verify that you specified an IAM role for notifications that includes the required trust policy. For information about configuring the IAM role for Run Command notifications, see Configuring Amazon SNS Notifications for Run Command in the AWS Systems Manager User Guide.

HTTP Status Code: 400

MaxDocumentSizeExceeded

The size limit of a document is 64 KB.

HTTP Status Code: 400

UnsupportedPlatformType

The document does not support the platform type of the given instance ID(s). For example, you sent an document for a Windows instance to a Linux instance.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: