aws-elixir v0.3.0 AWS.SSM

This is the Amazon Simple Systems Manager (SSM) API Reference. SSM enables you to remotely manage the configuration of your on-premises servers and virtual machines (VMs) and your Amazon EC2 instances using scripts, commands, or the Amazon EC2 console. SSM includes an on-demand solution called Amazon EC2 Run Command and a lightweight instance configuration solution called SSM Config.

This references is intended to be used with the EC2 Run Command User Guide for Linux or Windows.

You must register your on-premises servers and VMs through an activation process before you can configure them using Run Command. Registered servers and VMs are called *managed instances*. For more information, see [Setting Up Run Command On Managed Instances (On-Premises Servers and VMs) on Linux](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/managed-instances.html) or [Setting Up Run Command On Managed Instances (On-Premises Servers and VMs) on Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/managed-instances.html). **Run Command**

Run Command provides an on-demand experience for executing commands. You can use pre-defined 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 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 Run Command and SSM Config 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](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-ssm-doc.html) and [Sharing SSM Documents](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssm-sharing.html) (Linux)
  • [Creating SSM Documents](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/create-ssm-doc.html) and [Sharing SSM Documents](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ssm-sharing.html) (Windows)

Summary

Functions

Adds or overwrites one or more tags for the specified resource. Tags are metadata that you assign to your managed instances. Tags enable you to categorize your managed instances in different ways, for example, by purpose, owner, or environment. Each tag consists of a key and an optional value, both of which you define. For example, you could define a set of tags for your account’s managed instances that helps you track each instance’s owner and stack level. For example: Key=Owner and Value=DbAdmin, SysAdmin, or Dev. Or Key=Stack and Value=Production, Pre-Production, or Test. Each resource can have a maximum of 10 tags

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

Registers your on-premises server or virtual machine with Amazon EC2 so that you can manage these resources using Run Command. An on-premises server or virtual machine that has been registered with EC2 is called a managed instance. For more information about activations, see Setting Up Managed Instances (Linux) or Setting Up Managed Instances (Windows) in the Amazon EC2 User Guide

Associates the specified SSM document with the specified instance

Associates the specified SSM document with the specified instances

Deletes an activation. You are not required to delete an activation. If you delete an activation, you can no longer use it to register additional managed instances. Deleting an activation does not de-register managed instances. You must manually de-register managed instances

Disassociates the specified SSM document from the specified instance

Deletes the SSM document and all instance associations to the document

Removes the server or virtual machine from the list of registered servers. You can reregister the instance again at any time. If you don’t plan to use Run Command on the server, we suggest uninstalling the SSM agent first

Details about the activation, including: the date and time the activation was created, the expiration date, the IAM role assigned to the instances in the activation, and the number of instances activated by this registration

Describes the associations for the specified SSM document or instance

Describes the specified SSM document

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)

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

Gets the contents of the specified SSM document

Lists the associations for the specified SSM document or instance

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

Lists the commands requested by users of the AWS account

Describes one or more of your SSM documents

Returns a list of the tags assigned to the specified resource

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

Removes all tags from the specified resource

Executes commands on one or more remote instances

Updates the status of the SSM document associated with the specified instance

Assigns or changes an Amazon Identity and Access Management (IAM) role to the managed instance

Functions

add_tags_to_resource(client, input, options \\ [])

Adds or overwrites one or more tags for the specified resource. Tags are metadata that you assign to your managed instances. Tags enable you to categorize your managed instances in different ways, for example, by purpose, owner, or environment. Each tag consists of a key and an optional value, both of which you define. For example, you could define a set of tags for your account’s managed instances that helps you track each instance’s owner and stack level. For example: Key=Owner and Value=DbAdmin, SysAdmin, or Dev. Or Key=Stack and Value=Production, Pre-Production, or Test. Each resource can have a maximum of 10 tags.

We recommend that you devise a set of tag keys that meets your needs for each resource type. Using a consistent set of tag keys makes it easier for you to manage your resources. You can search and filter the resources based on the tags you add. Tags don’t have any semantic meaning to Amazon EC2 and are interpreted strictly as a string of characters.

For more information about tags, see Tagging Your Amazon EC2 Resources in the Amazon EC2 User Guide.

cancel_command(client, input, options \\ [])

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.

create_activation(client, input, options \\ [])

Registers your on-premises server or virtual machine with Amazon EC2 so that you can manage these resources using Run Command. An on-premises server or virtual machine that has been registered with EC2 is called a managed instance. For more information about activations, see Setting Up Managed Instances (Linux) or Setting Up Managed Instances (Windows) in the Amazon EC2 User Guide.

create_association(client, input, options \\ [])

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.

create_association_batch(client, input, options \\ [])

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.

create_document(client, input, options \\ [])

Creates an SSM document.

After you create an SSM document, you can use CreateAssociation to associate it with one or more running instances.

delete_activation(client, input, options \\ [])

Deletes an activation. You are not required to delete an activation. If you delete an activation, you can no longer use it to register additional managed instances. Deleting an activation does not de-register managed instances. You must manually de-register managed instances.

delete_association(client, input, options \\ [])

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.

delete_document(client, input, options \\ [])

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.

deregister_managed_instance(client, input, options \\ [])

Removes the server or virtual machine from the list of registered servers. You can reregister the instance again at any time. If you don’t plan to use Run Command on the server, we suggest uninstalling the SSM agent first.

describe_activations(client, input, options \\ [])

Details about the activation, including: the date and time the activation was created, the expiration date, the IAM role assigned to the instances in the activation, and the number of instances activated by this registration.

describe_association(client, input, options \\ [])

Describes the associations for the specified SSM document or instance.

describe_document(client, input, options \\ [])

Describes the specified SSM document.

describe_document_permission(client, input, options \\ [])

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).

describe_instance_information(client, input, options \\ [])

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.

get_document(client, input, options \\ [])

Gets the contents of the specified SSM document.

list_associations(client, input, options \\ [])

Lists the associations for the specified SSM document or instance.

list_command_invocations(client, input, options \\ [])

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.

list_commands(client, input, options \\ [])

Lists the commands requested by users of the AWS account.

list_documents(client, input, options \\ [])

Describes one or more of your SSM documents.

list_tags_for_resource(client, input, options \\ [])

Returns a list of the tags assigned to the specified resource.

modify_document_permission(client, input, options \\ [])

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.

remove_tags_from_resource(client, input, options \\ [])

Removes all tags from the specified resource.

send_command(client, input, options \\ [])

Executes commands on one or more remote instances.

update_association_status(client, input, options \\ [])

Updates the status of the SSM document associated with the specified instance.

update_managed_instance_role(client, input, options \\ [])

Assigns or changes an Amazon Identity and Access Management (IAM) role to the managed instance.