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

2. In the navigation pane, choose Documents.

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

2. To perform free text document search with a single term, run the following command. In this command, replace search_term 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_term_1 and search_term_2 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

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.

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

2. In the navigation pane, choose Documents.

3. 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/.

2. In the navigation pane, choose Documents.

3. 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/.

2. In the navigation pane, choose Documents.

3. Select the Favorites tab.