public interface AWSSimpleSystemsManagement
This is the Amazon Simple Systems Manager (SSM) API Reference. SSM enables you to remotely manage the configuration of your Amazon EC2 instance using scripts or commands with either an on-demand solution called SSM Run Command or a lightweight instance configuration solution called SSM Config.
This references is intended to be used with the SSM User Guide for Linux or Windows.
Run Command
Run Command provides an on-demand experience for executing commands. You can use pre-defined Amazon SSM documents to perform the actions listed later in this section, or you can create your own documents. With these documents, you can remotely configure your instances by sending commands using the Commands page in the Amazon EC2 console, AWS Tools for Windows PowerShell, the AWS CLI, or AWS SDKs.
Run Command reports the status of the command execution for each instance targeted by a command. You can also audit the command execution to understand who executed commands, when, and what changes were made. By switching between different SSM documents, you can quickly configure your instances with different types of commands. To get started with Run Command, verify that your environment meets the prerequisites for remotely running commands on EC2 instances (Linux or Windows).
SSM Config
SSM Config is a lightweight instance configuration solution. SSM Config is currently only available for Windows instances. With SSM Config, you can specify a setup configuration for your instances. SSM Config is similar to EC2 User Data, which is another way of running one-time scripts or applying settings during instance launch. SSM Config is an extension of this capability. Using SSM documents, you can specify which actions the system should perform on your instances, including which applications to install, which AWS Directory Service directory to join, which Microsoft PowerShell modules to install, etc. If an instance is missing one or more of these configurations, the system makes those changes. By default, the system checks every five minutes to see if there is a new configuration to apply as defined in a new SSM document. If so, the system updates the instances accordingly. In this way, you can remotely maintain a consistent configuration baseline on your instances. SSM Config is available using the AWS CLI or the AWS Tools for Windows PowerShell. For more information, see Managing Windows Instance Configuration.
SSM Config and SSM Run Command include the following pre-defined documents.
Linux
AWS-RunShellScript to run shell scripts
AWS-UpdateSSMAgent to update the Amazon SSM agent
Windows
AWS-JoinDirectoryServiceDomain to join an AWS Directory
AWS-RunPowerShellScript to run PowerShell commands or scripts
AWS-UpdateEC2Config to update the EC2Config service
AWS-ConfigureWindowsUpdate to configure Windows Update settings
AWS-InstallApplication to install, repair, or uninstall software using an MSI package
AWS-InstallPowerShellModule to install PowerShell modules
AWS-ConfigureCloudWatch to configure Amazon CloudWatch Logs to monitor applications and systems
AWS-ListWindowsInventory to collect information about an EC2 instance running in Windows.
AWS-FindWindowsUpdates to scan an instance and determines which updates are missing.
AWS-InstallMissingWindowsUpdates to install missing updates on your EC2 instance.
AWS-InstallSpecificWindowsUpdates to install one or more specific updates.
The commands or scripts specified in SSM documents run with administrative privilege on your instances because the Amazon SSM agent runs as root on Linux and the EC2Config service runs in the Local System account on Windows. If a user has permission to execute any of the pre-defined SSM documents (any document that begins with AWS-*) then that user also has administrator access to the instance. Delegate access to SSM and Run Command judiciously. This becomes extremely important if you create your own SSM documents. Amazon Web Services does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command at your own risk. As a security best practice, we recommend that you assign access to "AWS-*" documents, especially the AWS-RunShellScript document on Linux and the AWS-RunPowerShellScript document on Windows, to trusted administrators only. You can create SSM documents for specific tasks and delegate access to non-administrators.
For information about creating and sharing SSM documents, see the following topics in the SSM User Guide:
Creating SSM Documents and Sharing SSM Documents (Linux)
Creating SSM Documents and Sharing SSM Documents (Windows)
Modifier and Type | Method and Description |
---|---|
CancelCommandResult |
cancelCommand(CancelCommandRequest cancelCommandRequest)
Attempts to cancel the command specified by the Command ID.
|
CreateAssociationResult |
createAssociation(CreateAssociationRequest createAssociationRequest)
Associates the specified SSM document with the specified instance.
|
CreateAssociationBatchResult |
createAssociationBatch(CreateAssociationBatchRequest createAssociationBatchRequest)
Associates the specified SSM document with the specified instances.
|
CreateDocumentResult |
createDocument(CreateDocumentRequest createDocumentRequest)
Creates an SSM document.
|
DeleteAssociationResult |
deleteAssociation(DeleteAssociationRequest deleteAssociationRequest)
Disassociates the specified SSM document from the specified instance.
|
DeleteDocumentResult |
deleteDocument(DeleteDocumentRequest deleteDocumentRequest)
Deletes the SSM document and all instance associations to the document.
|
DescribeAssociationResult |
describeAssociation(DescribeAssociationRequest describeAssociationRequest)
Describes the associations for the specified SSM document or instance.
|
DescribeDocumentResult |
describeDocument(DescribeDocumentRequest describeDocumentRequest)
Describes the specified SSM document.
|
DescribeDocumentPermissionResult |
describeDocumentPermission(DescribeDocumentPermissionRequest describeDocumentPermissionRequest)
Describes the permissions for an SSM document.
|
DescribeInstanceInformationResult |
describeInstanceInformation(DescribeInstanceInformationRequest describeInstanceInformationRequest)
Describes one or more of your instances.
|
ResponseMetadata |
getCachedResponseMetadata(AmazonWebServiceRequest request)
Returns additional metadata for a previously executed successful request,
typically used for debugging issues where a service isn't acting as
expected.
|
GetDocumentResult |
getDocument(GetDocumentRequest getDocumentRequest)
Gets the contents of the specified SSM document.
|
ListAssociationsResult |
listAssociations(ListAssociationsRequest listAssociationsRequest)
Lists the associations for the specified SSM document or instance.
|
ListCommandInvocationsResult |
listCommandInvocations(ListCommandInvocationsRequest listCommandInvocationsRequest)
An invocation is copy of a command sent to a specific instance.
|
ListCommandsResult |
listCommands(ListCommandsRequest listCommandsRequest)
Lists the commands requested by users of the AWS account.
|
ListDocumentsResult |
listDocuments()
Simplified method form for invoking the ListDocuments operation.
|
ListDocumentsResult |
listDocuments(ListDocumentsRequest listDocumentsRequest)
Describes one or more of your SSM documents.
|
ModifyDocumentPermissionResult |
modifyDocumentPermission(ModifyDocumentPermissionRequest modifyDocumentPermissionRequest)
Share a document publicly or privately.
|
SendCommandResult |
sendCommand(SendCommandRequest sendCommandRequest)
Executes commands on one or more remote instances.
|
void |
setEndpoint(String endpoint)
Overrides the default endpoint for this client
("https://ssm.us-east-1.amazonaws.com").
|
void |
setRegion(Region region)
An alternative to
setEndpoint(String) ,
sets the regional endpoint for this client's service calls. |
void |
shutdown()
Shuts down this client object, releasing any resources that might be held
open.
|
UpdateAssociationStatusResult |
updateAssociationStatus(UpdateAssociationStatusRequest updateAssociationStatusRequest)
Updates the status of the SSM document associated with the specified
instance.
|
void setEndpoint(String endpoint)
Callers can pass in just the endpoint (ex: "ssm.us-east-1.amazonaws.com")
or a full URL, including the protocol (ex:
"https://ssm.us-east-1.amazonaws.com"). If the protocol is not specified
here, the default protocol from this client's ClientConfiguration
will be used, which by default is HTTPS.
For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID= 3912
This method is not threadsafe. An endpoint should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
endpoint
- The endpoint (ex: "ssm.us-east-1.amazonaws.com") or a full URL,
including the protocol (ex: "https://ssm.us-east-1.amazonaws.com")
of the region specific AWS endpoint this client will communicate
with.void setRegion(Region region)
setEndpoint(String)
,
sets the regional endpoint for this client's service calls. Callers can
use this method to control which AWS region they want to work with.
By default, all service endpoints in all regions use the https protocol.
To use http instead, specify it in the ClientConfiguration
supplied at construction.
This method is not threadsafe. A region should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
region
- The region this client will communicate with. See
Region.getRegion(com.amazonaws.regions.Regions)
for
accessing a given region. Must not be null and must be a region
where the service is available.Region.getRegion(com.amazonaws.regions.Regions)
,
Region.createClient(Class,
com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
,
Region.isServiceSupported(String)
CancelCommandResult cancelCommand(CancelCommandRequest cancelCommandRequest)
Attempts to cancel the command specified by the Command ID. There is no guarantee that the command will be terminated and the underlying process stopped.
cancelCommandRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidCommandIdException
InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.DuplicateInstanceIdException
- You cannot specify an instance ID in more than one association.CreateAssociationResult createAssociation(CreateAssociationRequest createAssociationRequest)
Associates the specified SSM document with the specified instance.
When you associate an SSM document with an instance, the configuration agent on the instance processes the document and configures the instance as specified.
If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.
createAssociationRequest
- AssociationAlreadyExistsException
- The specified association already exists.AssociationLimitExceededException
- You can have at most 2,000 active associations.InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.UnsupportedPlatformTypeException
- The document does not support the platform type of the given
instance ID(s). For example, you sent an SSM document for a
Windows instance to a Linux instance.InvalidParametersException
- You must specify values for all required parameters in the SSM
document. You can only supply values to parameters defined in the
SSM document.CreateAssociationBatchResult createAssociationBatch(CreateAssociationBatchRequest createAssociationBatchRequest)
Associates the specified SSM document with the specified instances.
When you associate an SSM document with an instance, the configuration agent on the instance processes the document and configures the instance as specified.
If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.
createAssociationBatchRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidParametersException
- You must specify values for all required parameters in the SSM
document. You can only supply values to parameters defined in the
SSM document.DuplicateInstanceIdException
- You cannot specify an instance ID in more than one association.AssociationLimitExceededException
- You can have at most 2,000 active associations.UnsupportedPlatformTypeException
- The document does not support the platform type of the given
instance ID(s). For example, you sent an SSM document for a
Windows instance to a Linux instance.CreateDocumentResult createDocument(CreateDocumentRequest createDocumentRequest)
Creates an SSM document.
After you create an SSM document, you can use CreateAssociation to associate it with one or more running instances.
createDocumentRequest
- DocumentAlreadyExistsException
- The specified SSM document already exists.MaxDocumentSizeExceededException
- The size limit of an SSM document is 64 KB.InternalServerErrorException
- An error occurred on the server side.InvalidDocumentContentException
- The content for the SSM document is not valid.DocumentLimitExceededException
- You can have at most 100 active SSM documents.DeleteAssociationResult deleteAssociation(DeleteAssociationRequest deleteAssociationRequest)
Disassociates the specified SSM document from the specified instance.
When you disassociate an SSM document from an instance, it does not change the configuration of the instance. To change the configuration state of an instance after you disassociate a document, you must create a new document with the desired configuration and associate it with the instance.
deleteAssociationRequest
- AssociationDoesNotExistException
- The specified association does not exist.InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.TooManyUpdatesException
- There are concurrent updates for a resource that supports one
update at a time.DeleteDocumentResult deleteDocument(DeleteDocumentRequest deleteDocumentRequest)
Deletes the SSM document and all instance associations to the document.
Before you delete the SSM document, we recommend that you use DeleteAssociation to disassociate all instances that are associated with the document.
deleteDocumentRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidDocumentOperationException
- You attempted to delete a document while it is still shared. You
must stop sharing the document before you can delete it.AssociatedInstancesException
- You must disassociate an SSM document from all instances before
you can delete it.DescribeAssociationResult describeAssociation(DescribeAssociationRequest describeAssociationRequest)
Describes the associations for the specified SSM document or instance.
describeAssociationRequest
- AssociationDoesNotExistException
- The specified association does not exist.InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.DescribeDocumentResult describeDocument(DescribeDocumentRequest describeDocumentRequest)
Describes the specified SSM document.
describeDocumentRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.DescribeDocumentPermissionResult describeDocumentPermission(DescribeDocumentPermissionRequest describeDocumentPermissionRequest)
Describes the permissions for an SSM document. If you created the document, you are the owner. If a document is shared, it can either be shared privately (by specifying a user’s AWS account ID) or publicly (All).
describeDocumentPermissionRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidPermissionTypeException
- The permission type is not supported. Share is the only
supported permission type.DescribeInstanceInformationResult describeInstanceInformation(DescribeInstanceInformationRequest describeInstanceInformationRequest)
Describes one or more of your instances. You can use this to get information about instances like the operating system platform, the SSM agent version, status etc. If you specify one or more instance IDs, it returns information for those instances. If you do not specify instance IDs, it returns information for all your instances. If you specify an instance ID that is not valid or an instance that you do not own, you receive an error.
describeInstanceInformationRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidNextTokenException
- The specified token is not valid.InvalidInstanceInformationFilterValueException
- The specified filter value is not valid.InvalidFilterKeyException
- The specified key is not valid.GetDocumentResult getDocument(GetDocumentRequest getDocumentRequest)
Gets the contents of the specified SSM document.
getDocumentRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.ListAssociationsResult listAssociations(ListAssociationsRequest listAssociationsRequest)
Lists the associations for the specified SSM document or instance.
listAssociationsRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidNextTokenException
- The specified token is not valid.ListCommandInvocationsResult listCommandInvocations(ListCommandInvocationsRequest listCommandInvocationsRequest)
An invocation is copy of a command sent to a specific instance. A command can apply to one or more instances. A command invocation applies to one instance. For example, if a user executes SendCommand against three instances, then a command invocation is created for each requested instance ID. ListCommandInvocations provide status about command execution.
listCommandInvocationsRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidCommandIdException
InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidFilterKeyException
- The specified key is not valid.InvalidNextTokenException
- The specified token is not valid.ListCommandsResult listCommands(ListCommandsRequest listCommandsRequest)
Lists the commands requested by users of the AWS account.
listCommandsRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidCommandIdException
InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidFilterKeyException
- The specified key is not valid.InvalidNextTokenException
- The specified token is not valid.ListDocumentsResult listDocuments(ListDocumentsRequest listDocumentsRequest)
Describes one or more of your SSM documents.
listDocumentsRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidNextTokenException
- The specified token is not valid.InvalidFilterKeyException
- The specified key is not valid.ListDocumentsResult listDocuments()
listDocuments(ListDocumentsRequest)
ModifyDocumentPermissionResult modifyDocumentPermission(ModifyDocumentPermissionRequest modifyDocumentPermissionRequest)
Share a document publicly or privately. If you share a document privately, you must specify the AWS user account IDs for those people who can use the document. If you share a document publicly, you must specify All as the account ID.
modifyDocumentPermissionRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidDocumentException
- The specified document does not exist.InvalidPermissionTypeException
- The permission type is not supported. Share is the only
supported permission type.DocumentPermissionLimitException
- The document cannot be shared with more AWS user accounts. You
can share a document with a maximum of 20 accounts. You can
publicly share up to five documents. If you need to increase this
limit, contact AWS Support.DocumentLimitExceededException
- You can have at most 100 active SSM documents.SendCommandResult sendCommand(SendCommandRequest sendCommandRequest)
Executes commands on one or more remote instances.
sendCommandRequest
- DuplicateInstanceIdException
- You cannot specify an instance ID in more than one association.InternalServerErrorException
- An error occurred on the server side.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidDocumentException
- The specified document does not exist.InvalidOutputFolderException
- The S3 bucket does not exist.InvalidParametersException
- You must specify values for all required parameters in the SSM
document. You can only supply values to parameters defined in the
SSM document.UnsupportedPlatformTypeException
- The document does not support the platform type of the given
instance ID(s). For example, you sent an SSM document for a
Windows instance to a Linux instance.MaxDocumentSizeExceededException
- The size limit of an SSM document is 64 KB.UpdateAssociationStatusResult updateAssociationStatus(UpdateAssociationStatusRequest updateAssociationStatusRequest)
Updates the status of the SSM document associated with the specified instance.
updateAssociationStatusRequest
- InternalServerErrorException
- An error occurred on the server side.InvalidInstanceIdException
- The instance is not in valid state. Valid states are: Running,
Pending, Stopped, Stopping. Invalid states are: Shutting-down and
Terminated.InvalidDocumentException
- The specified document does not exist.AssociationDoesNotExistException
- The specified association does not exist.StatusUnchangedException
- The updated status is the same as the current status.TooManyUpdatesException
- There are concurrent updates for a resource that supports one
update at a time.void shutdown()
ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)
Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic information for an executed request, you should use this method to retrieve it as soon as possible after executing a request.
request
- The originally executed request.Copyright © 2018. All rights reserved.