• 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).
# Working with documents
This section includes information about how to use and work with SSM documents.
**Topics**
+ [
# Compare SSM document versions
](comparing-versions.md)
+ [
# Create an SSM document
](create-ssm-console.md)
+ [
# Deleting custom SSM documents
](deleting-documents.md)
+ [
# Running documents from remote locations
](documents-running-remote-github-s3.md)
+ [
# Sharing SSM documents
](documents-ssm-sharing.md)
+ [
# Searching for SSM documents
](ssm-documents-searching.md)
# Compare SSM document versions
You can compare the differences in content between versions of AWS Systems Manager (SSM) documents in the Systems Manager Documents console. When comparing versions of an SSM document, differences between the content of the versions are highlighted.
**To compare SSM document content (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 **Documents**.
1. In the documents list, choose the document whose content you want to compare.
1. On the **Content** tab, select **Compare versions**, and choose the version of the document you want to compare the content to.
# Create an SSM document
After you create the content for your custom SSM document, as described in [Writing SSM document content](documents-creating-content.md#writing-ssm-doc-content), you can use the Systems Manager console to create an SSM document using your content.
**To create an SSM document**
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 **Documents**.
1. Choose **Create command or session**.
1. Enter a descriptive name for the document.
1. (Optional) For **Target type**, specify the type of resources the document can run on.
1. In the **Document type** list, choose the type of document you want to create.
1. Delete the brackets in the **Content** field, and then paste the document content you created earlier.
1. (Optional) In the **Document tags** section, apply one or more tag key name/value pairs to the document.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag a document to identify the type of tasks it runs, the type of operating systems it targets, and the environment it runs in. In this case, you could specify the following key name/value pairs:
+ `Key=TaskType,Value=MyConfigurationUpdate`
+ `Key=OS,Value=AMAZON_LINUX_2`
+ `Key=Environment,Value=Production`
1. Choose **Create document** to save the document.
# Deleting custom SSM documents
If you no longer want to use a custom SSM document, you can delete it using the AWS Systems Manager console.
**To delete an SSM document**
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 **Documents**.
1. Select the document you want to delete.
1. Select **Delete**. When prompted to delete the document, select **Delete**.
For examples using command line tools or SDKs to delete SSM documents, see [Use `DeleteDocument` with an AWS SDK or CLI](example_ssm_DeleteDocument_section.md).
# Running documents from remote locations
You can run AWS Systems Manager (SSM) documents from remote locations by using the `AWS-RunDocument` pre-defined SSM document. This document supports running SSM documents stored in the following locations:
+ Public and private GitHub repositories (GitHub Enterprise is not supported)
+ Amazon S3 buckets
+ Systems Manager
While you can also run remote documents by using State Manager or Automation, tools in AWS Systems Manager, the following procedure describes only how to run remote SSM documents by using AWS Systems Manager Run Command in the Systems Manager console.
**Note**
`AWS-RunDocument` can be used to run only command-type SSM documents, not other types such as Automation runbooks. The `AWS-RunDocument` uses the `aws:downloadContent` plugin. For more information about the `aws:downloadContent` plugin, see [`aws:downloadContent`](documents-command-ssm-plugin-reference.md#aws-downloadContent).
**Warning**
`AWS-RunDocument` can execute document content from various sources (SSM documents, GitHub, S3, URLs). When executing remote documents, the IAM permissions evaluated are for `ssm:GetDocument` on the remote document and `ssm:SendCommand` on `AWS-RunDocument`. If you have IAM policies that deny access to specific SSM documents, users with `AWS-RunDocument` permissions can still execute those denied documents by passing the document content as parameters, which may not be subject to the same document-specific IAM restrictions.
To properly restrict document execution, use one of these approaches:
**Allowlist approved sources**: If you need to use nested document execution, restrict access to only approved sources using appropriate controls for each source type: IAM policies to control `ssm:GetDocument` for SSM document sources, IAM and Amazon S3 bucket policies for Amazon S3 sources, and network settings (such as VPC endpoints or security groups) for public Internet sources.
**Restrict access to AWS-RunDocument**: Deny `ssm:SendCommand` on `AWS-RunDocument` and any other documents that use the `aws:runDocument` plugin in your IAM policies to prevent nested document execution.
**Use permission boundaries**: Implement IAM permission boundaries to set maximum permissions for users, preventing them from executing unauthorized documents regardless of the execution method.
For more information about IAM best practices and permission boundaries, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *AWS Identity and Access Management User Guide*.
**Before you begin**
Before you run a remote document, you must complete the following tasks.
+ Create an SSM Command document and save it in a remote location. For more information, see [Creating SSM document content](documents-creating-content.md)
+ If you plan to run a remote document that is stored in a private GitHub repository, then you must create a Systems Manager `SecureString` parameter for your GitHub security access token. You can't access a remote document in a private GitHub repository by manually passing your token over SSH. The access token must be passed as a Systems Manager `SecureString` parameter. For more information about creating a `SecureString` parameter, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md).
## Run a remote document (console)
**To run a remote document**
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 **Document** list, choose **`AWS-RunDocument`**.
1. In **Command parameters**, for **Source Type**, choose an option.
+ If you choose **GitHub**, specify **Source Info** information in the following format:
```
{
"owner": "owner_name",
"repository": "repository_name",
"path": "path_to_document",
"getOptions":"branch:branch_name",
"tokenInfo": "{{ssm-secure:secure-string-token}}"
}
```
For example:
```
{
"owner":"TestUser",
"repository":"GitHubTestExamples",
"path":"scripts/python/test-script",
"getOptions":"branch:exampleBranch",
"tokenInfo":"{{ssm-secure:my-secure-string-token}}"
}
```
**Note**
`getOptions` are extra options to retrieve content from a branch other than master, or from a specific commit in the repository. `getOptions` can be omitted if you are using the latest commit in the master branch. The `branch` parameter is required only if your SSM document is stored in a branch other than `master`.
To use the version of your SSM document in a particular *commit* in your repository, use `commitID` with `getOptions` instead of `branch`. For example:
```
"getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
```
+ If you choose **S3**, specify **Source Info** information in the following format:
```
{"path":"URL_to_document_in_S3"}
```
For example:
```
{"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/scripts/ruby/mySSMdoc.json"}
```
+ If you choose **SSMDocument**, specify **Source Info** information in the following format:
```
{"name": "document_name"}
```
For example:
```
{"name": "mySSMdoc"}
```
1. In the **Document Parameters** field, enter parameters for the remote SSM document. For example, if you run the `AWS-RunPowerShell` document, you could specify:
```
{"commands": ["date", "echo \"Hello World\""]}
```
If you run the `AWS-ConfigureAWSPack` document, you could specify:
```
{
"action":"Install",
"name":"AWSPVDriver"
}
```
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**.
**Note**
For information about rebooting servers and instances when using Run Command to call scripts, see [Handling reboots when running commands](send-commands-reboot.md).
# Sharing SSM documents
You can share AWS Systems Manager (SSM) documents privately or publicly with accounts in the same AWS Region. To privately share a document, you modify the document permissions and allow specific individuals to access it according to their AWS account ID. To publicly share an SSM document, you modify the document permissions and specify `All`. Documents can't be simultaneously shared publicly and privately.
**Warning**
Use shared SSM documents only from trusted sources. When using any shared document, carefully review the contents of the document before using it so that you understand how it will change the configuration of your instance. For more information about shared document best practices, see [Best practices for shared SSM documents](#best-practices-shared).
**Limitations**
As you begin working with SSM documents, be aware of the following limitations.
+ Only the owner can share a document.
+ You must stop sharing a document before you can delete it. For more information, see [Modify permissions for a shared SSM document](#modify-permissions-shared).
+ You can share a document with a maximum of 1000 AWS accounts. You can request an increase to this limit in the [Support Center](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase). For **Limit type**, choose *EC2 Systems Manager* and describe your reason for the request.
+ You can publicly share a maximum of five SSM documents. You can request an increase to this limit in the [Support Center](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase). For **Limit type**, choose *EC2 Systems Manager* and describe your reason for the request.
+ Documents can be shared with other accounts in the same AWS Region only. Cross-Region sharing isn't supported.
**Important**
In Systems Manager, an *Amazon-owned* SSM document is a document created and managed by Amazon Web Services itself. *Amazon-owned* documents include a prefix like `AWS-*` in the document name. The owner of the document is considered to be Amazon, not a specific user account within AWS. These documents are publicly available for all to use.
For more information about Systems Manager service quotas, see [AWS Systems Manager Service Quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm).
**Topics**
+ [
## Best practices for shared SSM documents
](#best-practices-shared)
+ [
## Block public sharing for SSM documents
](#block-public-access)
+ [
## Share an SSM document
](#ssm-how-to-share)
+ [
## Modify permissions for a shared SSM document
](#modify-permissions-shared)
+ [
## Using shared SSM documents
](#using-shared-documents)
## Best practices for shared SSM documents
Review the following guidelines before you share or use a shared document.
**Remove sensitive information**
Review your AWS Systems Manager (SSM) document carefully and remove any sensitive information. For example, verify that the document doesn't include your AWS credentials. If you share a document with specific individuals, those users can view the information in the document. If you share a document publicly, anyone can view the information in the document.
**Block public sharing for documents**
Review all publicly shared SSM documents in your account and confirm whether you want to continue sharing them. To stop sharing a document with the public, you must modify the document permission setting as described in the [Modify permissions for a shared SSM document](#modify-permissions-shared) section of this topic. Turning on the block public sharing setting doesn't affect any documents you're currently sharing with the public. Unless your use case requires you to share documents with the public, we recommend turning on the block public sharing setting for your SSM documents in the **Preferences** section of the Systems Manager Documents console. Turning on this setting prevents unwanted access to your SSM documents. The block public sharing setting is an account level setting that can differ for each AWS Region.
**Restrict Run Command actions using an IAM trust policy**
Create a restrictive AWS Identity and Access Management (IAM) policy for users who will have access to the document. The IAM policy determines which SSM documents a user can see in either the Amazon Elastic Compute Cloud (Amazon EC2) console or by calling `ListDocuments` using the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell. The policy also restricts the actions the user can perform with SSM documents. You can create a restrictive policy so that a user can only use specific documents. For more information, see [Customer managed policy examples](security_iam_id-based-policy-examples.md#customer-managed-policies).
**Use caution when using shared SSM documents**
Review the contents of every document that is shared with you, especially public documents, to understand the commands that will be run on your instances. A document could intentionally or unintentionally have negative repercussions after it's run. If the document references an external network, review the external source before you use the document.
**Send commands using the document hash**
When you share a document, the system creates a Sha-256 hash and assigns it to the document. The system also saves a snapshot of the document content. When you send a command using a shared document, you can specify the hash in your command to ensure that the following conditions are true:
+ You're running a command from the correct Systems Manager document
+ The content of the document hasn't changed since it was shared with you.
If the hash doesn't match the specified document or if the content of the shared document has changed, the command returns an `InvalidDocument` exception. The hash can't verify document content from external locations.
**Use the interpolation parameter to improve security**
For `String` type parameters in your SSM documents, use the parameter and value `interpolationType": "ENV_VAR` to improve security against command injection attacks by treating parameter inputs as string literals rather than potentially executable commands. In this case, the agent creates an environment variable named `SSM_parameter-name` with the parameter's value. We recommend updating all your existing SSM documents that include `String` type parameters to include `"interpolationType": "ENV_VAR"`. For more information, see [Writing SSM document content](documents-creating-content.md#writing-ssm-doc-content).
## Block public sharing for SSM documents
Before you begin, review all publicly shared SSM documents in your AWS account and confirm whether you want to continue sharing them. To stop sharing an SSM document with the public, you must modify the document permission setting as described in the [Modify permissions for a shared SSM document](#modify-permissions-shared) section of this topic. Turning on the block public sharing setting doesn't affect any SSM documents you're currently sharing with the public. With the block public sharing setting enabled, you won’t be able to share any additional SSM documents with the public.
Unless your use case requires you to share documents with the public, we recommend turning on the block public sharing setting for your SSM documents. Turning on this setting prevents unwanted access to your SSM documents. The block public sharing setting is an account level setting that can differ for each AWS Region. Complete the following tasks to block public sharing for any SSM documents you're not currently sharing.
### Block public sharing (console)
**To block public sharing of your SSM documents**
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 **Documents**.
1. Choose **Preferences**, and then choose **Edit** in the **Block public sharing** section.
1. Select the **Block public sharing** check box, and then choose **Save**.
### Block public sharing (command line)
Open the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell on your local computer and run the following command to block public sharing of your SSM documents.
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id /ssm/documents/console/public-sharing-permission \
--setting-value Disable \
--region 'The AWS Region you want to block public sharing in'
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id /ssm/documents/console/public-sharing-permission ^
--setting-value Disable ^
--region "The AWS Region you want to block public sharing in"
```
------
#### [ PowerShell ]
```
Update-SSMServiceSetting `
-SettingId /ssm/documents/console/public-sharing-permission `
-SettingValue Disable `
–Region The AWS Region you want to block public sharing in
```
------
Confirm the setting value was updated using the following command.
------
#### [ Linux & macOS ]
```
aws ssm get-service-setting \
--setting-id /ssm/documents/console/public-sharing-permission \
--region The AWS Region you blocked public sharing in
```
------
#### [ Windows ]
```
aws ssm get-service-setting ^
--setting-id /ssm/documents/console/public-sharing-permission ^
--region "The AWS Region you blocked public sharing in"
```
------
#### [ PowerShell ]
```
Get-SSMServiceSetting `
-SettingId /ssm/documents/console/public-sharing-permission `
-Region The AWS Region you blocked public sharing in
```
------
### Restricting access to block public sharing with IAM
You can create AWS Identity and Access Management (IAM) policies that restrict users from modifying the block public sharing setting. This prevents users from allowing unwanted access to your SSM documents.
The following is an example of an IAM policy that prevents users from updating the block public sharing setting. To use this example, you must replace the example Amazon Web Services account ID with your own account ID.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:UpdateServiceSetting",
"Resource": "arn:aws:ssm:*:444455556666:servicesetting/ssm/documents/console/public-sharing-permission"
}
]
}
```
------
## Share an SSM document
You can share AWS Systems Manager (SSM) documents by using the Systems Manager console. When sharing documents from the console, only the default version of the document can be shared. You can also share SSM documents programmatically by calling the `ModifyDocumentPermission` API operation using the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or the AWS SDK. Before you share a document, get the AWS account IDs of the people with whom you want to share. You will specify these account IDs when you share the document.
### Share a document (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 **Documents**.
1. In the documents list, choose the document you want to share, and then choose **View details**. On the **Permissions** tab, verify that you're the document owner. Only a document owner can share a document.
1. Choose **Edit**.
1. To share the command publicly, choose **Public** and then choose **Save**. To share the command privately, choose **Private**, enter the AWS account ID, choose **Add permission**, and then choose **Save**.
### Share a document (command line)
The following procedure requires that you specify an AWS Region for your command line session.
1. Open the AWS CLI or AWS Tools for Windows PowerShell on your local computer and run the following command to specify your credentials.
In the following command, replace *region* with your own information. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*.
------
#### [ Linux & macOS ]
```
aws config
AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
```
------
#### [ Windows ]
```
aws config
AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
```
------
#### [ PowerShell ]
```
Set-AWSCredentials –AccessKey your key –SecretKey your key
Set-DefaultAWSRegion -Region region
```
------
1. Use the following command to list all of the SSM documents that are available for you. The list includes documents that you created and documents that were shared with you.
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
1. Use the following command to get a specific document.
------
#### [ Linux & macOS ]
```
aws ssm get-document \
--name document name
```
------
#### [ Windows ]
```
aws ssm get-document ^
--name document name
```
------
#### [ PowerShell ]
```
Get-SSMDocument `
–Name document name
```
------
1. Use the following command to get a description of the document.
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name document name
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name document name
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
–Name document name
```
------
1. Use the following command to view the permissions for the document.
------
#### [ Linux & macOS ]
```
aws ssm describe-document-permission \
--name document name \
--permission-type Share
```
------
#### [ Windows ]
```
aws ssm describe-document-permission ^
--name document name ^
--permission-type Share
```
------
#### [ PowerShell ]
```
Get-SSMDocumentPermission `
–Name document name `
-PermissionType Share
```
------
1. Use the following command to modify the permissions for the document and share it. You must be the owner of the document to edit the permissions. Optionally, for documents shared with specific AWS account IDs, you can specify a version of the document you want to share using the `--shared-document-version` parameter. If you don't specify a version, the system shares the `Default` version of the document. If you share a document publicly (with `all`), all versions of the specified document are shared by default. The following example command privately shares the document with a specific individual, based on that person's AWS account ID.
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-add AWS account ID
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-add AWS account ID
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
–Name document name `
-PermissionType Share `
-AccountIdsToAdd AWS account ID
```
------
1. Use the following command to share a document publicly.
**Note**
If you share a document publicly (with `all`), all versions of the specified document are shared by default.
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-add 'all'
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-add "all"
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
-Name document name `
-PermissionType Share `
-AccountIdsToAdd ('all')
```
------
## Modify permissions for a shared SSM document
If you share a command, users can view and use that command until you either remove access to the AWS Systems Manager (SSM) document or delete the SSM document. However, you can't delete a document as long as it's shared. You must stop sharing it first and then delete it.
### Stop sharing a document (console)
**Stop sharing a document**
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 **Documents**.
1. In the documents list, choose the document you want to stop sharing, and then choose the **Details**. In the **Permissions** section, verify that you're the document owner. Only a document owner can stop sharing a document.
1. Choose **Edit**.
1. Choose **X** to delete the AWS account ID that should no longer have access to the command, and then choose **Save**.
### Stop sharing a document (command line)
Open the AWS CLI or AWS Tools for Windows PowerShell on your local computer and run the following command to stop sharing a command.
------
#### [ Linux & macOS ]
```
aws ssm modify-document-permission \
--name document name \
--permission-type Share \
--account-ids-to-remove 'AWS account ID'
```
------
#### [ Windows ]
```
aws ssm modify-document-permission ^
--name document name ^
--permission-type Share ^
--account-ids-to-remove "AWS account ID"
```
------
#### [ PowerShell ]
```
Edit-SSMDocumentPermission `
-Name document name `
-PermissionType Share `
–AccountIdsToRemove AWS account ID
```
------
## Using shared SSM documents
When you share an AWS Systems Manager (SSM) document, the system generates an Amazon Resource Name (ARN) and assigns it to the command. If you select and run a shared document from the Systems Manager console, you don't see the ARN. However, if you want to run a shared SSM document using a method other than the Systems Manager console, you must specify the full ARN of the document for the `DocumentName` request parameter. You're shown the full ARN for an SSM document when you run the command to list documents.
**Note**
You aren't required to specify ARNs for AWS public documents (documents that begin with `AWS-*`) or documents that you own.
### Use a shared SSM document (command line)
**To list all public SSM documents**
------
#### [ Linux & macOS ]
```
aws ssm list-documents \
--filters Key=Owner,Values=Public
```
------
#### [ Windows ]
```
aws ssm list-documents ^
--filters Key=Owner,Values=Public
```
------
#### [ PowerShell ]
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Public"
Get-SSMDocumentList `
-Filters @($filter)
```
------
**To list private SSM documents that have been shared with you**
------
#### [ Linux & macOS ]
```
aws ssm list-documents \
--filters Key=Owner,Values=Private
```
------
#### [ Windows ]
```
aws ssm list-documents ^
--filters Key=Owner,Values=Private
```
------
#### [ PowerShell ]
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Private"
Get-SSMDocumentList `
-Filters @($filter)
```
------
**To list all SSM documents available to you**
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
**To get information about an SSM document that has been shared with you**
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
–Name arn:aws:ssm:us-east-2:12345678912:document/documentName
```
------
**To run a shared SSM document**
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name arn:aws:ssm:us-east-2:12345678912:document/documentName \
--instance-ids ID
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name arn:aws:ssm:us-east-2:12345678912:document/documentName ^
--instance-ids ID
```
------
#### [ PowerShell ]
```
Send-SSMCommand `
–DocumentName arn:aws:ssm:us-east-2:12345678912:document/documentName `
–InstanceIds ID
```
------
# Searching for SSM documents
You can search the AWS Systems Manager (SSM) document store for SSM documents by using either free text search or a filter-based search. You can also favorite documents to help you find frequently used SSM documents. The following sections describes how to use these features.
## Using free text search
The search box on the Systems Manager **Documents** page supports free text search. Free text search compares the search term or terms that you enter against the document name in each SSM document. If you enter a single search term, for example **ansible**, then Systems Manager returns all SSM documents where this term was discovered. If you enter multiple search terms, then Systems Manager searches by using an `OR` statement. For example, if you specify **ansible** and **linux**, then search returns all documents with *either* keyword in their name.
If you enter a free text search term and choose a search option, such as **Platform type**, then search uses an `AND` statement and returns all documents with the keyword in their name and the specified platform type.
**Note**
Note the following details about free text search.
Free text search is *not* case sensitive.
Search terms require a minimum of three characters and have a maximum of 20 characters.
Free text search accepts up to five search terms.
If you enter a space between search terms, the system includes the space when searching.
You can combine free text search with other search options such as **Document type** or **Platform type**.
The **Document Name Prefix** filter and free text search can't be used together. they're mutually exclusive.
**To search for an SSM document**
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 **Documents**.
1. Enter your search terms in the search box, and press Enter.
### Performing free text document search by using the AWS CLI
**To perform a free text document search by using the 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. To perform free text document search with a single term, run the following command. In this command, replace *search\$1term* with your own information.
```
aws ssm list-documents --filters Key="SearchKeyword",Values="search_term"
```
Here's an example.
```
aws ssm list-documents --filters Key="SearchKeyword",Values="aws-asg" --region us-east-2
```
To search using multiple terms that create an `AND` statement, run the following command. In this command, replace *search\$1term\$11* and *search\$1term\$12* with your own information.
```
aws ssm list-documents --filters Key="SearchKeyword",Values="search_term_1","search_term_2","search_term_3" --region us-east-2
```
Here's an example.
```
aws ssm list-documents --filters Key="SearchKeyword",Values="aws-asg","aws-ec2","restart" --region us-east-2
```
## Using filters
The Systems Manager **Documents** page automatically displays the following filters when you choose the search box.
+ Document name prefix
+ Platform types
+ Document type
+ Tag key
![\[Filter options on SSM Documents page.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/ssm-documents-filters-1.png)
You can search for SSM documents by using a single filter. If you want to return a more specific set of SSM documents, you can apply multiple filters. Here is an example of a search that uses the **Platform types** and the **Document name prefix** filters.
![\[Applying multiple filter options on the SSM Documents page.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/ssm-documents-filters-2.png)
If you apply multiple filters, Systems Manager creates different search statements based on the filters you choose:
+ If you apply the *same* filter multiple times, for example **Document name prefix**, then Systems Manager searches by using an `OR` statement. For example, if you specify one filter of **Document name prefix**=**AWS** and a second filter of **Document name prefix**=**Lambda**, then search returns all documents with the prefix "`AWS`" and all documents with the prefix "`Lambda`".
+ If you apply *different* filters, for example **Document name prefix** and **Platform types**, then Systems Manager searches by using an `AND` statement. For example, if you specify a **Document name prefix**=**AWS** filter and a **Platform types**=**Linux** filter, then search returns all documents with the prefix "`AWS`" that are specific to the Linux platform.
**Note**
Searches that use filters are case sensitive.
## Adding documents to your favorites
To help you find frequently used SSM documents, add documents to your favorites. You can favorite up to 20 documents per document type, per AWS account and AWS Region. You can choose, modify, and view your favorites from the documents AWS Management Console. The following procedures describe how to choose, modify, and view your favorites.
**To favorite an SSM document**
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 **Documents**.
1. Select the star icon next to the document name you want to favorite.
**To remove an SSM document from your favorites**
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 **Documents**.
1. Deselect the star icon next to the document name you want to remove from your favorites.
**To view your favorites from the documents AWS Management 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 **Documents**.
1. Select the **Favorites** tab.