• 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).
# AWS Systems Manager Distributor
Distributor, a tool in AWS Systems Manager, helps you package and publish software to AWS Systems Manager managed nodes. You can package and publish your own software or use Distributor to find and publish AWS-provided agent software packages, such as **AmazonCloudWatchAgent**, or third-party packages such as **Trend Micro. **Publishing a package advertises specific versions of the package's document to managed nodes that you identify using node IDs, AWS account IDs, tags, or an AWS Region. To get started with Distributor, open the [Systems Manager console](https://console.aws.amazon.com//systems-manager/distributor). In the navigation pane, choose **Distributor**.
After you create a package in Distributor, you can install the package in one of the following ways:
+ One time by using [AWS Systems Manager Run Command](run-command.md)
+ On a schedule by using [AWS Systems Manager State Manager](systems-manager-state.md)
**Important**
Packages distributed by third-party sellers are not managed by AWS and are published by the vendor of the package. We encourage you to conduct additional due diligence to ensure compliance with your internal security controls. Security is a shared responsibility between AWS and you. This is described as the shared responsibility model. To learn more, see the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/).
## How can Distributor benefit my organization?
Distributor offers these benefits:
+ **One package, many platforms**
When you create a package in Distributor, the system creates an AWS Systems Manager document (SSM document). You can attach .zip files to this document. When you run Distributor, the system processes the instructions in the SSM document and installs the software package in the .zip file on the specified targets. Distributor supports multiple operating systems, including Windows, Ubuntu Server, Debian Server, and Red Hat Enterprise Linux. For more information about supported platforms, see [Supported package platforms and architectures](#what-is-a-package-platforms).
+ **Control package access across groups of managed instances**
You can use Run Command or State Manager to control which of your managed nodes get a package and which version of that package. Run Command and State Manager are tools in AWS Systems Manager. Managed nodes can be grouped by instance or device IDs, AWS account numbers, tags, or AWS Regions. You can use State Manager associations to deliver different versions of a package to different groups of instances.
+ **Many AWS agent packages included and ready to use**
Distributor includes many AWS agent packages that are ready for you to deploy to managed nodes. Look for packages in the Distributor `Packages` list page that are published by `Amazon`. Examples include `AmazonCloudWatchAgent` and `AWSPVDriver`.
+ **Automate deployment **
To keep your environment current, use State Manager to schedule packages for automatic deployment on target managed nodes when those machines are first launched.
## Who should use Distributor?
+ Any AWS customer who wants to create new or deploy existing software packages, including AWS published packages, to multiple Systems Manager managed nodes at one time.
+ Software developers who create software packages.
+ Administrators who are responsible for keeping Systems Manager managed nodes current with the most up-to-date software packages.
## What are the features of Distributor?
+ **Deployment of packages to both Windows and Linux instances**
With Distributor, you can deploy software packages to Amazon Elastic Compute Cloud (Amazon EC2) instances and AWS IoT Greengrass core devices for Linux and Windows Server. For a list of supported instance operating system types, see [Supported package platforms and architectures](#what-is-a-package-platforms).
**Note**
Distributor isn't supported on the macOS operating system.
+ **Deploy packages one time, or on an automated schedule**
You can choose to deploy packages one time, on a regular schedule, or whenever the default package version is changed to a different version.
+ **Completely reinstall packages, or perform in-place updates**
To install a new package version, you can completely uninstall the current version and install a new one in its place, or only update the current version with new and updated components, according to an *update script* that you provide. Your package application is unavailable during a reinstallation, but can remain available during an in-place update. In-place updates are especially useful for security monitoring applications or other scenarios where you need to avoid application downtime.
+ **Console, CLI, PowerShell, and SDK access to Distributor capabilities**
You can work with Distributor by using the Systems Manager console, AWS Command Line Interface (AWS CLI), AWS Tools for PowerShell, or the AWS SDK of your choice.
+ **IAM access control**
By using AWS Identity and Access Management (IAM) policies, you can control which members of your organization can create, update, deploy, or delete packages or package versions. For example, you might want to give an administrator permissions to deploy packages, but not to change packages or create new package versions.
+ **Logging and auditing capability support**
You can audit and log Distributor user actions in your AWS account through integration with other AWS services. For more information, see [Auditing and logging Distributor activity](distributor-logging-auditing.md).
## What is a package in Distributor?
A *package* is a collection of installable software or assets that includes the following.
+ A .zip file of software per target operating system platform. Each .zip file must include the following.
+ An **install** and an **uninstall** script. Windows Server-based managed nodes require PowerShell scripts (scripts named `install.ps1` and `uninstall.ps1`). Linux-based managed nodes require shell scripts (scripts named `install.sh` and `uninstall.sh`). AWS Systems Manager SSM Agent reads and carries out the instructions in the **install** and **uninstall** scripts.
+ An executable file. SSM Agent must find this executable to install the package on target managed nodes.
+ A JSON-formatted manifest file that describes the package contents. The manifest isn't included in the .zip file, but it's stored in the same Amazon Simple Storage Service (Amazon S3) bucket as the .zip files that form the package. The manifest identifies the package version and maps the .zip files in the package to target managed node attributes, such as operating system version or architecture. For information about how to create the manifest, see [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
When you choose **Simple** package creation in the Distributor console, Distributor generates the installation and uninstallation scripts, file hashes, and the JSON package manifest for you, based on the software executable file name and target platforms and architectures.
### Supported package platforms and architectures
You can use Distributor to publish packages to the following Systems Manager managed node platforms. A version value must match the exact release version of the operating system Amazon Machine Image (AMI) that you're targeting. For more information about determining this version, see step 4 of [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
**Note**
Systems Manager doesn't support all of the following operating systems for AWS IoT Greengrass core devices. For more information, see [Setting up AWS IoT Greengrass core devices](https://docs.aws.amazon.com/greengrass/v2/developerguide/setting-up.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
| Platform | Code value in manifest file | Supported architectures |
| --- | --- | --- |
| AlmaLinux | almalinux | x86\$164 ARM64 |
| Amazon Linux 2 and Amazon Linux 2023 | `amazon` | x86\$164 or x86 ARM64 (Amazon Linux 2 and AL2023, A1 instance types) |
| Debian Server | `debian` | x86\$164 or x86 |
| openSUSE | `opensuse` | x86\$164 |
| openSUSE Leap | `opensuseleap` | x86\$164 |
| Oracle Linux | `oracle` | x86\$164 |
| Red Hat Enterprise Linux (RHEL) | `redhat` | x86\$164 ARM64 (RHEL 7.6 and later, A1 instance types) |
| Rocky Linux | rocky | x86\$164 ARM64 |
| SUSE Linux Enterprise Server (SLES) | `suse` | x86\$164 |
| Ubuntu Server | `ubuntu` | x86\$164 or x86 ARM64 (Ubuntu Server 16 and later, A1 instance types) |
| Windows Server | `windows` | x86\$164 |
**Topics**
+ [How can Distributor benefit my organization?](#distributor-benefits)
+ [Who should use Distributor?](#distributor-who)
+ [What are the features of Distributor?](#distributor-features)
+ [What is a package in Distributor?](#what-is-a-package)
+ [Setting up Distributor](distributor-getting-started.md)
+ [Working with Distributor packages](distributor-working-with.md)
+ [Auditing and logging Distributor activity](distributor-logging-auditing.md)
+ [Troubleshooting AWS Systems Manager Distributor](distributor-troubleshooting.md)
# Setting up Distributor
Before you use Distributor, a tool in AWS Systems Manager, to create, manage, and deploy software packages, follow these steps.
## Complete Distributor prerequisites
Before you use Distributor, a tool in AWS Systems Manager, be sure your environment meets the following requirements.
**Distributor prerequisites**
| Requirement | Description |
| --- | --- |
| SSM Agent | AWS Systems Manager SSM Agent version 2.3.274.0 or later must be installed on the managed nodes on which you want to deploy or from which you want to remove packages. To install or update SSM Agent, see [Working with SSM Agent](ssm-agent.md). |
| AWS CLI | (Optional) To use the AWS Command Line Interface (AWS CLI) instead of the Systems Manager console to create and manage packages, install the newest release of the AWS CLI on your local computer. For more information about how to install or upgrade the CLI, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) in the *AWS Command Line Interface User Guide*. |
| AWS Tools for PowerShell | (Optional) To use the Tools for PowerShell instead of the Systems Manager console to create and manage packages, install the newest release of Tools for PowerShell on your local computer. For more information about how to install or upgrade the Tools for PowerShell, see [Setting up the AWS Tools for Windows PowerShell or AWS Tools for PowerShell Core](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html) in the *AWS Tools for PowerShell User Guide*. |
**Note**
Systems Manager doesn't support distributing packages to Oracle Linux managed nodes by using Distributor.
## Verify or create an IAM instance profile with Distributor permissions
By default, AWS Systems Manager doesn't have permission to perform actions on your instances. You must grant access by using an AWS Identity and Access Management (IAM) instance profile. An instance profile is a container that passes IAM role information to an Amazon Elastic Compute Cloud (Amazon EC2) instance at launch. This requirement applies to permissions for all Systems Manager tools, not just Distributor.
**Note**
When you configure your edge devices to run AWS IoT Greengrass Core software and SSM Agent, you specify an IAM service role that enables Systems Manager to peform actions on it. You don't need to configure managed edge devices with an instance profile.
If you already use other Systems Manager tools, such as Run Command and State Manager, an instance profile with the required permissions for Distributor is already attached to your instances. The simplest way to ensure that you have permissions to perform Distributor tasks is to attach the **AmazonSSMManagedInstanceCore** policy to your instance profile. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).
## Control user access to packages
Using AWS Identity and Access Management (IAM) policies, you can control who can create, deploy, and manage packages. You also control which Run Command and State Manager API operations they can perform on managed nodes. Like Distributor, both Run Command and State Manager, are tools in AWS Systems Manager.
**ARN Format**
User-defined packages are associated with document Amazon Resource Names (ARNs) and have the following format.
```
arn:aws:ssm:region:account-id:document/document-name
```
The following is an example.
```
arn:aws:ssm:us-west-1:123456789012:document/ExampleDocumentName
```
You can use a pair of AWS supplied default IAM policies, one for end users and one for administrators, to grant permissions for Distributor activities. Or you can create custom IAM policies appropriate for your permissions requirements.
For more information about using variables in IAM policies, see [IAM Policy Elements: Variables](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html).
For information about how to create policies and attach them to users or groups, see [Creating IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) and [Adding and Removing IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *IAM User Guide*.
## Create or choose an Amazon S3 bucket to store Distributor packages
When you create a package by using the **Simple** workflow in the AWS Systems Manager console, you choose an existing Amazon Simple Storage Service (Amazon S3) bucket to which Distributor uploads your software. Distributor is a tool in AWS Systems Manager. In the **Advanced** workflow, you must upload .zip files of your software or assets to an Amazon S3 bucket before you begin. Whether you create a package by using the **Simple** or **Advanced** workflows in the console, or by using the API, you must have an Amazon S3 bucket before you start creating your package. As part of the package creation process, Distributor copies your installable software and assets from this bucket to an internal Systems Manager store. Because the assets are copied to an internal store, you can delete or repurpose your Amazon S3 bucket when package creation is finished.
For more information about how to create a bucket, see [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service Getting Started Guide*. For more information about how to run an AWS CLI command to create a bucket, see [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) in the *AWS CLI Command Reference*.
# Working with Distributor packages
You can use the AWS Systems Manager console, AWS command line tools (AWS CLI and AWS Tools for PowerShell), and AWS SDKs to add, manage, or deploy packages in Distributor. Distributor is a tool in AWS Systems Manager. Before you add a package to Distributor:
+ Create and zip installable assets.
+ (Optional) Create a JSON manifest file for the package. This isn't required to use the **Simple** package creation process in the Distributor console. Simple package creation generates a JSON manifest file for you.
You can use the AWS Systems Manager console or a text or JSON editor to create the manifest file.
+ Have an Amazon Simple Storage Service (Amazon S3) bucket ready to store your installable assets or software. If you're using the **Advanced** package creation process, upload your assets to the Amazon S3 bucket before you begin.
**Note**
You can delete or repurpose this bucket after you finish creating your package because Distributor moves the package contents to an internal Systems Manager bucket as part of the package creation process.
AWS published packages are already packaged and ready for deployment. To deploy an AWS-published package to managed nodes, see [Install or update Distributor packages](distributor-working-with-packages-deploy.md).
You can share Distributor packages between AWS accounts. When using a package shared from another account in AWS CLI commands use the package Amazon Resource Name (ARN) instead of the package name.
**Topics**
+ [View packages in Distributor](distributor-view-packages.md)
+ [Create a package in Distributor](distributor-working-with-packages-create.md)
+ [Edit Distributor package permissions in the console](distributor-working-with-packages-ep.md)
+ [Edit Distributor package tags in the console](distributor-working-with-packages-tags.md)
+ [Add a version to a Distributor package](distributor-working-with-packages-version.md)
+ [Install or update Distributor packages](distributor-working-with-packages-deploy.md)
+ [Uninstall a Distributor package](distributor-working-with-packages-uninstall.md)
+ [Delete a Distributor package](distributor-working-with-packages-dpkg.md)
# View packages in Distributor
To view packages that are available for installation, you can use the AWS Systems Manager console or your preferred AWS command line tool. Distributor is a tool in AWS Systems Manager. To access Distributor, open the AWS Systems Manager console and choose **Distributor** in the left navigation pane. You will see all of the packages available to you.
The following section describes how you can view Distributor packages using your preferred command line tool.
## View packages using the command line
This section contains information about how you can use your preferred command line tool to view Distributor packages using the provided commands.
------
#### [ Linux & macOS ]
**To view packages using the AWS CLI on Linux**
+ To view all packages, excluding shared packages, run the following command.
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package
```
+ To view all packages owned by Amazon, run the following command.
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package Key=Owner,Values=Amazon
```
+ To view all packages owned by third parties, run the following command.
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package Key=Owner,Values=ThirdParty
```
------
#### [ Windows ]
**To view packages using the AWS CLI on Windows**
+ To view all packages, excluding shared packages, run the following command.
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package
```
+ To view all packages owned by Amazon, run the following command.
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package Key=Owner,Values=Amazon
```
+ To view all packages owned by third parties, run the following command.
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package Key=Owner,Values=ThirdParty
```
------
#### [ PowerShell ]
**To view packages using the Tools for PowerShell**
+ To view all packages, excluding shared packages, run the following command.
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "DocumentType"
$filter.Values = "Package"
Get-SSMDocumentList `
-Filters @($filter)
```
+ To view all packages owned by Amazon, run the following command.
```
$typeFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$typeFilter.Key = "DocumentType"
$typeFilter.Values = "Package"
$ownerFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$ownerFilter.Key = "Owner"
$ownerFilter.Values = "Amazon"
Get-SSMDocumentList `
-Filters @($typeFilter,$ownerFilter)
```
+ To view all packages owned by third parties, run the following command.
```
$typeFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$typeFilter.Key = "DocumentType"
$typeFilter.Values = "Package"
$ownerFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$ownerFilter.Key = "Owner"
$ownerFilter.Values = "ThirdParty"
Get-SSMDocumentList `
-Filters @($typeFilter,$ownerFilter)
```
------
# Create a package in Distributor
To create a package, prepare your installable software or assets, one file per operating system platform. At least one file is required to create a package.
Different platforms might sometimes use the same file, but all files that you attach to your package must be listed in the `Files` section of the manifest. If you're creating a package by using the simple workflow in the console, the manifest is generated for you. The maximum number of files that you can attach to a single document is 20. The maximum size of each file is 1 GB. For more information about supported platforms, see [Supported package platforms and architectures](distributor.md#what-is-a-package-platforms).
When you create a package, the system creates a new [SSM document](documents.md). This document allows you to deploy the package to managed nodes.
For demonstration purposes only, an example package, [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip), is available for you to download from our website. The example package includes a completed JSON manifest and three .zip files containing installers for PowerShell v7.0.0. The installation and uninstallation scripts don't contain valid commands. Although you must zip each software installable and scripts into a .zip file to create a package in the **Advanced** workflow, you don't zip installable assets in the **Simple** workflow.
**Topics**
+ [Create a package using the Simple workflow](#distributor-working-with-packages-create-simple)
+ [Create a package using the Advanced workflow](#distributor-working-with-packages-create-adv)
## Create a package using the Simple workflow
This section describes how to create a package in Distributor by choosing the **Simple** package creation workflow in the Distributor console. Distributor is a tool in AWS Systems Manager. To create a package, prepare your installable assets, one file per operating system platform. At least one file is required to create a package. The **Simple** package creation process generates installation and uninstallation scripts, file hashes, and a JSON-formatted manifest for you. The **Simple** workflow handles the process of uploading and zipping your installable files, and creating a new package and associated [SSM document](documents.md). For more information about supported platforms, see [Supported package platforms and architectures](distributor.md#what-is-a-package-platforms).
When you use the Simple method to create a package, Distributor creates `install` and `uninstall` scripts for you. However, when you create a package for an in-place update, you must provide your own `update` script content on the **Update script** tab. When you add input commands for an `update` script, Distributor includes this script in the .zip package it creates for you, along with the `install` and `uninstall` scripts.
**Note**
Use the `In-place` update option to add new or updated files to an existing package installation without taking the associated application offline.
**To create a package using the Simple workflow**
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 **Distributor**.
1. On the Distributor home page, choose **Create package**, and then choose **Simple**.
1. On the **Create package** page, enter a name for your package. Package names can contain letters, numbers, periods, dashes, and underscores. The name should be generic enough to apply to all versions of the package attachments, but specific enough to identify the purpose of the package.
1. (Optional) For **Version name**, enter a version name. Version names can be a maximum of 512 characters, and can't contain special characters.
1. For **Location**, choose a bucket by using the bucket name and prefix or by using the bucket URL.
1. For **Upload software**, choose **Add software**, and then navigate to installable software files with `.rpm`, `.msi`, or `.deb` extensions. If the file name contains spaces, the upload fails. You can upload more than one software file in a single action.
1. For **Target platform**, verify that the target operating system platform shown for each installable file is correct. If the operating system shown isn't correct, choose the correct operating system from the dropdown list.
For the **Simple** package creation workflow, because you upload each installable file only once, extra steps are required to instruct Distributor to target a single file at multiple operating systems. For example, if you upload an installable software file named `Logtool_v1.1.1.rpm`, you must change some defaults in the **Simple** workflow to target the same software on supported versions of both Amazon Linux and Ubuntu Server operating systems. When targeting multiple platforms, do one of the following.
+ Use the **Advanced** workflow instead, zip each installable file into a .zip file before you begin, and manually author the manifest so that one installable file can be targeted at multiple operating system platforms or versions. For more information, see [Create a package using the Advanced workflow](#distributor-working-with-packages-create-adv).
+ Manually edit the manifest file in the **Simple** workflow so that your .zip file is targeted at multiple operating system platforms or versions. For more information about how to do this, see the end of step 4 in [Step 2: Create the JSON package manifest](#packages-manifest).
1. For **Platform version**, verify that the operating system platform version shown is either **\$1any**, a major release version followed by a wildcard (7.\$1), or the exact operating system release version to which you want your software to apply. For more information about specifying an operating system platform version, see step 4 in [Step 2: Create the JSON package manifest](#packages-manifest).
1. For **Architecture**, choose the correct processor architecture for each installable file from the dropdown list. For more information about supported processor architectures, see [Supported package platforms and architectures](distributor.md#what-is-a-package-platforms).
1. (Optional) Expand **Scripts**, and review the scripts that Distributor generates for your installable software.
1. (Optional) To provide an update script for use with in-place updates, expand **Scripts**, choose the **Update script** tab, and enter your update script commands.
Systems Manager doesn't generate update scripts on your behalf.
1. To add more installable software files, choose **Add software**. Otherwise, go to the next step.
1. (Optional) Expand **Manifest**, and review the JSON package manifest that Distributor generates for your installable software. If you changed any information about your software since you began this procedure, such as platform version or target platform, choose **Generate manifest** to show the updated package manifest.
You can edit the manifest manually if you want to target a software installable at more than one operating system, as described in step 8. For more information about editing the manifest, see [Step 2: Create the JSON package manifest](#packages-manifest).
1. Choose **Create package**.
Wait for Distributor to finish uploading your software and creating your package. Distributor shows upload status for each installable file. Depending on the number and size of packages you're adding, this can take a few minutes. Distributor automatically redirects you to the **Package details** page for the new package, but you can choose to open this page yourself after the software is uploaded. The **Package details** page doesn't show all information about your package until Distributor finishes the package creation process. To stop the upload and package creation process, choose **Cancel**.
If Distributor can't upload any of the software installable files, it displays an **Upload failed** message. To retry the upload, choose **Retry upload**. For more information about how to troubleshoot package creation failures, see [Troubleshooting AWS Systems Manager Distributor](distributor-troubleshooting.md).
## Create a package using the Advanced workflow
In this section, learn about how advanced users can create a package in Distributor after uploading installable assets zipped with installation and uninstallation scripts, and a JSON manifest file, to an Amazon S3 bucket.
To create a package, prepare your .zip files of installable assets, one .zip file per operating system platform. At least one .zip file is required to create a package. Next, create a JSON manifest. The manifest includes pointers to your package code files. When you have your required code files added to a folder or directory, and the manifest is populated with correct values, upload your package to an S3 bucket.
An example package, [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip), is available for you to download from our website. The example package includes a completed JSON manifest and three .zip files.
**Topics**
+ [Step 1: Create the ZIP files](#packages-zip)
+ [Step 2: Create the JSON package manifest](#packages-manifest)
+ [Step 3: Upload the package and manifest to an Amazon S3 bucket](#packages-upload-s3)
+ [Step 4: Add a package to Distributor](#distributor-working-with-packages-add)
### Step 1: Create the ZIP files
The foundation of your package is at least one .zip file of software or installable assets. A package includes one .zip file per operating system that you want to support, unless one .zip file can be installed on multiple operating systems. For example, supported versions of Red Hat Enterprise Linux and Amazon Linux instances can typically run the same .RPM executable files, so you need to attach only one .zip file to your package to support both operating systems.
**Required files**
The following items are required in each .zip file:
+ An **install** and an **uninstall** script. Windows Server-based managed nodes require PowerShell scripts (scripts named `install.ps1` and `uninstall.ps1`). Linux-based managed nodes require shell scripts (scripts named `install.sh` and `uninstall.sh`). SSM Agent runs the instructions in the **install** and **uninstall** scripts.
For example, your installation scripts might run an installer (such as .rpm or .msi), they might copy files, or they might set configurations.
+ An executable file, installer packages (.rpm, .deb, .msi, etc.), other scripts, or configuration files.
**Optional files**
The following item is optional in each .zip file:
+ An **update** script. Providing an update script makes it possible for you to use the `In-place update` option to install a package. When you want to add new or updated files to an existing package installation, the `In-place update` option doesn't take the package application offline while the update is performed. Windows Server-based managed nodes require a PowerShell script (script named `update.ps1`). Linux-based managed nodes require a shell script (script named `update.sh`). SSM Agent runs the instructions in the **update** script.
For more information about installing or updating packages, see [Install or update Distributor packages](distributor-working-with-packages-deploy.md).
For examples of .zip files, including sample **install** and **uninstall** scripts, download the example package, [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip).
### Step 2: Create the JSON package manifest
After you prepare and zip your installable files, create a JSON manifest. The following is a template. The parts of the manifest template are described in the procedure in this section. You can use a JSON editor to create this manifest in a separate file. Alternatively, you can author the manifest in the AWS Systems Manager console when you create a package.
```
{
"schemaVersion": "2.0",
"version": "your-version",
"publisher": "optional-publisher-name",
"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-3.zip"
}
}
}
},
"files": {
".zip-file-name-1.zip": {
"checksums": {
"sha256": "checksum"
}
},
".zip-file-name-2.zip": {
"checksums": {
"sha256": "checksum"
}
}
}
}
```
**To create a JSON package manifest**
1. Add the schema version to your manifest. In this release, the schema version is always `2.0`.
```
{ "schemaVersion": "2.0",
```
1. Add a user-defined package version to your manifest. This is also the value of **Version name** that you specify when you add your package to Distributor. It becomes part of the AWS Systems Manager document that Distributor creates when you add your package. You also provide this value as an input in the `AWS-ConfigureAWSPackage` document to install a version of the package other than the latest. A `version` value can contain letters, numbers, underscores, hyphens, and periods, and be a maximum of 128 characters in length. We recommend that you use a human-readable package version to make it easier for you and other administrators to specify exact package versions when you deploy. The following is an example.
```
"version": "1.0.1",
```
1. (Optional) Add a publisher name. The following is an example.
```
"publisher": "MyOrganization",
```
1. Add packages. The `"packages"` section describes the platforms, release versions, and architectures supported by the .zip files in your package. For more information, see [Supported package platforms and architectures](distributor.md#what-is-a-package-platforms).
The *platform-version* can be the wildcard value, `_any`. Use it to indicate that a .zip file supports any release of the platform. You can also specify a major release version followed by a wildcard so all minor versions are supported, for example 7.\$1. If you choose to specify a *platform-version* value for a specific operating system version, be sure that it matches the exact release version of the operating system AMI that you're targeting. The following are suggested resources for getting the correct value of the operating system.
+ On a Windows Server-based managed nodes, the release version is available as Windows Management Instrumentation (WMI) data. You can run the following command from a command prompt to get version information, then parse the results for `version`.
```
wmic OS get /format:list
```
+ On a Linux-based managed node, get the version by first scanning for operating system release (the following command). Look for the value of `VERSION_ID`.
```
cat /etc/os-release
```
If that doesn't return the results that you need, run the following command to get LSB release information from the `/etc/lsb-release` file, and look for the value of `DISTRIB_RELEASE`.
```
lsb_release -a
```
If these methods fail, you can usually find the release based on the distribution. For example, on Debian Server, you can scan the `/etc/debian_version` file, or on Red Hat Enterprise Linux, the `/etc/redhat-release` file.
```
hostnamectl
```
```
"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-3.zip"
}
}
}
}
```
The following is an example. In this example, the operating system platform is `amazon`, the supported release version is `2016.09`, the architecture is `x86_64`, and the .zip file that supports this platform is `test.zip`.
```
{
"amazon": {
"2016.09": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
You can add the `_any` wildcard value to indicate that the package supports all versions of the parent element. For example, to indicate that the package is supported on any release version of Amazon Linux, your package statement should be similar to the following. You can use the `_any` wildcard at the version or architecture levels to support all versions of a platform, or all architectures in a version, or all versions and all architectures of a platform.
```
{
"amazon": {
"_any": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
The following example adds `_any` to show that the first package, `data1.zip`, is supported for all architectures of Amazon Linux 2016.09. The second package, `data2.zip`, is supported for all releases of Amazon Linux, but only for managed nodes with `x86_64` architecture. Both the `2023.8` and `_any` versions are entries under `amazon`. There is one platform (Amazon Linux), but different supported versions, architectures, and associated .zip files.
```
{
"amazon": {
"2023.8": {
"_any": {
"file": "data1.zip"
}
},
"_any": {
"x86_64": {
"file": "data2.zip"
}
}
}
}
```
You can refer to a .zip file more than once in the `"packages"` section of the manifest, if the .zip file supports more than one platform. For example, if you have a .zip file that supports both Red Hat Enterprise Linux 8.x versions and Amazon Linux, you have two entries in the `"packages"` section that point to the same .zip file, as shown in the following example.
```
{
"amazon": {
"2023.8.20250715 ": {
"x86_64": {
"file": "test.zip"
}
}
},
"redhat": {
"8.*": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
1. Add the list of .zip files that are part of this package from step 4. Each file entry requires the file name and `sha256` hash value checksum. Checksum values in the manifest must match the `sha256` hash value in the zipped assets to prevent the package installation from failing.
To get the exact checksum from your installables, you can run the following commands. On Linux, run `shasum -a 256 file-name.zip` or `openssl dgst -sha256 file-name.zip`. On Windows, run the `Get-FileHash -Path path-to-.zip-file` cmdlet in [PowerShell](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-filehash?view=powershell-6).
The `"files"` section of the manifest includes one reference to each of the .zip files in your package.
```
"files": {
"test-agent-x86.deb.zip": {
"checksums": {
"sha256": "EXAMPLE2706223c7616ca9fb28863a233b38e5a23a8c326bb4ae241dcEXAMPLE"
}
},
"test-agent-x86_64.deb.zip": {
"checksums": {
"sha256": "EXAMPLE572a745844618c491045f25ee6aae8a66307ea9bff0e9d1052EXAMPLE"
}
},
"test-agent-x86_64.nano.zip": {
"checksums": {
"sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel8-x86.nano.zip": {
"checksums": {
"sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
},
"test-agent-x86.msi.zip": {
"checksums": {
"sha256": "EXAMPLE12a4abb10315aa6b8a7384cc9b5ca8ad8e9ced8ef1bf0e5478EXAMPLE"
}
},
"test-agent-x86_64.msi.zip": {
"checksums": {
"sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel8-x86.rpm.zip": {
"checksums": {
"sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
}
}
```
1. After you add your package information, save and close the manifest file.
The following is an example of a completed manifest. In this example, you have a .zip file, `NewPackage_LINUX.zip`, that supports more than one platform, but is referenced in the `"files"` section only once.
```
{
"schemaVersion": "2.0",
"version": "1.7.1",
"publisher": "Amazon Web Services",
"packages": {
"windows": {
"_any": {
"x86_64": {
"file": "NewPackage_WINDOWS.zip"
}
}
},
"amazon": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
},
"ubuntu": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
}
},
"files": {
"NewPackage_WINDOWS.zip": {
"checksums": {
"sha256": "EXAMPLEc2c706013cf8c68163459678f7f6daa9489cd3f91d52799331EXAMPLE"
}
},
"NewPackage_LINUX.zip": {
"checksums": {
"sha256": "EXAMPLE2b8b9ed71e86f39f5946e837df0d38aacdd38955b4b18ffa6fEXAMPLE"
}
}
}
}
```
#### Package example
An example package, [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip), is available for you to download from our website. The example package includes a completed JSON manifest and three .zip files.
### Step 3: Upload the package and manifest to an Amazon S3 bucket
Prepare your package by copying or moving all .zip files into a folder or directory. A valid package requires the manifest that you created in [Step 2: Create the JSON package manifest](#packages-manifest) and all .zip files identified in the manifest file list.
**To upload the package and manifest to Amazon S3**
1. Copy or move all .zip archive files that you specified in the manifest to a folder or directory. Don't zip the folder or directory you move your .zip archive files and manifest file to.
1. Create a bucket or choose an existing bucket. For more information, see [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service Getting Started Guide*. For more information about how to run an AWS CLI command to create a bucket, see [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) in the *AWS CLI Command Reference*.
1. Upload the folder or directory to the bucket. For more information, see [Add an Object to a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PuttingAnObjectInABucket.html) in the *Amazon Simple Storage Service Getting Started Guide*. If you plan to paste your JSON manifest into the AWS Systems Manager console, don't upload the manifest. For more information about how to run an AWS CLI command to upload files to a bucket, see [https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html) in the *AWS CLI Command Reference*.
1. On the bucket's home page, choose the folder or directory that you uploaded. If you uploaded your files to a subfolder in a bucket, be sure to note the subfolder (also known as a *prefix*). You need the prefix to add your package to Distributor.
### Step 4: Add a package to Distributor
You can use the AWS Systems Manager console, AWS command line tools (AWS CLI and AWS Tools for PowerShell), or AWS SDKs to add a new package to Distributor. When you add a package, you're adding a new [SSM document](documents.md). The document allows you to deploy the package to managed nodes.
**Topics**
+ [Add a package using the console](#create-pkg-console)
+ [Add a package using the AWS CLI](#create-pkg-cli)
#### Add a package using the console
You can use the AWS Systems Manager console to create a package. Have ready the name of the bucket to which you uploaded your package in [Step 3: Upload the package and manifest to an Amazon S3 bucket](#packages-upload-s3).
**To add a package to Distributor (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 **Distributor**.
1. On the Distributor home page, choose **Create package**, and then choose **Advanced**.
1. On the **Create package** page, enter a name for your package. Package names can contain letters, numbers, periods, dashes, and underscores. The name should be generic enough to apply to all versions of the package attachments, but specific enough to identify the purpose of the package.
1. For **Version name**, enter the exact value of the `version` entry in your manifest file.
1. For **S3 bucket name**, choose the name of the bucket to which you uploaded your .zip files and manifest in [Step 3: Upload the package and manifest to an Amazon S3 bucket](#packages-upload-s3).
1. For **S3 key prefix**, enter the subfolder of the bucket where your .zip files and manifest are stored.
1. For **Manifest**, choose **Extract from package** to use a manifest that you have uploaded to the Amazon S3 bucket with your .zip files.
(Optional) If you didn't upload your JSON manifest to the S3 bucket where you stored your .zip files, choose **New manifest**. You can author or paste the entire manifest in the JSON editor field. For more information about how to create the JSON manifest, see [Step 2: Create the JSON package manifest](#packages-manifest).
1. When you're finished with the manifest, choose **Create package**.
1. Wait for Distributor to create your package from your .zip files and manifest. Depending on the number and size of packages you are adding, this can take a few minutes. Distributor automatically redirects you to the **Package details** page for the new package, but you can choose to open this page yourself after the software is uploaded. The **Package details** page doesn't show all information about your package until Distributor finishes the package creation process. To stop the upload and package creation process, choose **Cancel**.
#### Add a package using the AWS CLI
You can use the AWS CLI to create a package. Have the URL ready from the bucket to which you uploaded your package in [Step 3: Upload the package and manifest to an Amazon S3 bucket](#packages-upload-s3).
**To add a package to Amazon S3 using the AWS CLI**
1. To use the AWS CLI to create a package, run the following command, replacing *package-name* with the name of your package and *path-to-manifest-file* with the file path for your JSON manifest file. amzn-s3-demo-bucket is the URL of the Amazon S3 bucket where the entire package is stored. When you run the **create-document** command in Distributor, you specify the `Package` value for `--document-type`.
If you didn't add your manifest file to the Amazon S3 bucket, the `--content` parameter value is the file path to the JSON manifest file.
```
aws ssm create-document \
--name "package-name" \
--content file://path-to-manifest-file \
--attachments Key="SourceUrl",Values="amzn-s3-demo-bucket" \
--version-name version-value-from-manifest \
--document-type Package
```
The following is an example.
```
aws ssm create-document \
--name "ExamplePackage" \
--content file://path-to-manifest-file \
--attachments Key="SourceUrl",Values="https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage" \
--version-name 1.0.1 \
--document-type Package
```
1. Verify that your package was added and show the package manifest by running the following command, replacing *package-name* with the name of your package. To get a specific version of the document (not the same as the version of a package), you can add the `--document-version` parameter.
```
aws ssm get-document \
--name "package-name"
```
For information about other options you can use with the **create-document** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*. For information about other options you can use with the **get-document** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-document.html).
# Edit Distributor package permissions in the console
After you add a package to Distributor, a tool in AWS Systems Manager, you can edit the package's permissions in the Systems Manager console. You can add other AWS accounts to a package's permissions. Packages can be shared with other accounts in the same AWS Region only. Cross-Region sharing isn't supported. By default, packages are set to **Private**, meaning only those with access to the package creator's AWS account can view package information and update or delete the package. If **Private** permissions are acceptable, you can skip this procedure.
**Note**
You can update the permissions of packages that are shared with 20 or fewer accounts.
**To edit package permissions in the 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 **Distributor**.
1. On the **Packages** page, choose the package for which you want to edit permissions.
1. On the **Package details** tab, choose **Edit permissions** to change permissions.
1. For **Edit permissions**, choose **Shared with specific accounts**.
1. Under **Shared with specific accounts**, add AWS account numbers, one at a time. When you're finished, choose **Save**.
# Edit Distributor package tags in the console
After you have added a package to Distributor, a tool in AWS Systems Manager, you can edit the package's tags in the Systems Manager console. These tags are applied to the package, and aren't connected to tags on the managed node on which you want to deploy the package. Tags are case sensitive key and value pairs that can help you group and filter your packages by criteria that are relevant to your organization. If you don't want to add tags, you're ready to install your package or add a new version.
**To edit package tags in the 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 **Distributor**.
1. On the **Packages** page, choose the package for which you want to edit tags.
1. On the **Package details** tab, in **Tags**, choose **Edit**.
1. For **Add tags**, enter a tag key, or a tag key and value pair, and then choose **Add**. Repeat if you want to add more tags. To delete tags, choose **X** on the tag at the bottom of the window.
1. When you're finished adding tags to your package, choose **Save**.
# Add a version to a Distributor package
To add a package version, [create a package](distributor-working-with-packages-create.md), and then use Distributor to add a package version by adding an entry to the AWS Systems Manager (SSM) document that already exists for older versions. Distributor is a tool in AWS Systems Manager. To save time, update the manifest for an older version of the package, change the value of the `version` entry in the manifest (for example, from `Test_1.0` to `Test_2.0`) and save it as the manifest for the new version. The simple **Add version** workflow in the Distributor console updates the manifest file for you.
A new package version can:
+ Replace at least one of the installable files attached to the current version.
+ Add new installable files to support additional platforms.
+ Delete files to discontinue support for specific platforms.
A newer version can use the same Amazon Simple Storage Service (Amazon S3) bucket, but must have a URL with a different file name shown at the end. You can use the Systems Manager console or the AWS Command Line Interface (AWS CLI) to add the new version. Uploading an installable file with the exact name as an existing installable file in the Amazon S3 bucket overwrites the existing file. No installable files are copied over from the older version to the new version; you must upload installable files from the older version to have them be part of a new version. After Distributor is finished creating your new package version, you can delete or repurpose the Amazon S3 bucket, because Distributor copies your software to an internal Systems Manager bucket as part of the versioning process.
**Note**
Each package is held to a maximum of 25 versions. You can delete versions that are no longer required.
**Topics**
+ [Adding a package version using the console](#add-pkg-version)
+ [Adding a package version using the AWS CLI](#add-pkg-version-cli)
## Adding a package version using the console
Before you perform these steps, follow the instructions in [Create a package in Distributor](distributor-working-with-packages-create.md) to create a new package for the version. Then, use the Systems Manager console to add a new package version to Distributor.
### Adding a package version using the Simple workflow
To add a package version by using the **Simple** workflow, prepare updated installable files or add installable files to support more platforms and architectures. Then, use Distributor to upload new and updated installable files and add a package version. The simplified **Add version** workflow in the Distributor console updates the manifest file and associated SSM document for you.
**To add a package version using the Simple workflow**
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 **Distributor**.
1. On the Distributor home page, choose the package to which you want to add another version.
1. On the **Add version** page, choose **Simple**.
1. For **Version name**, enter a version name. The version name for the new version must be different from older version names. Version names can be a maximum of 512 characters, and can't contain special characters.
1. For **S3 bucket name**, choose an existing S3 bucket from the list. This can be the same bucket that you used to store installable files for older versions, but the installable file names must be different to avoid overwriting existing installable files in the bucket.
1. For **S3 key prefix**, enter the subfolder of the bucket where your installable assets are stored.
1. For **Upload software**, navigate to the installable software files that you want to attach to the new version. Installable files from existing versions aren't automatically copied over to a new version; you must upload any installable files from older versions of the package if you want any of the same installable files to be part of the new version. You can upload more than one software file in a single action.
1. For **Target platform**, verify that the target operating system platform shown for each installable file is correct. If the operating system shown isn't correct, choose the correct operating system from the dropdown list.
In the **Simple** versioning workflow, because you upload each installable file only once, extra steps are required to target a single file at multiple operating systems. For example, if you upload an installable software file named `Logtool_v1.1.1.rpm`, you must change some defaults in the **Simple** workflow to instruct Distributor to target the same software at both Amazon Linux and Ubuntu Server operating systems. You can do one of the following to work around this limitation.
+ Use the **Advanced** versioning workflow instead, zip each installable file into a .zip file before you begin, and manually author the manifest so that one installable file can be targeted at multiple operating system platforms or versions. For more information, see [Adding a package version using the Advanced workflow](#add-pkg-version-adv).
+ Manually edit the manifest file in the **Simple** workflow so that your .zip file is targeted at multiple operating system platforms or versions. For more information about how to do this, see the end of step 4 in [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
1. For **Platform version**, verify that the operating system platform version shown is either **\$1any**, a major release version followed by a wildcard (8.\$1), or the exact operating system release version to which you want your software to apply. For more information about specifying a platform version, see step 4 in [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
1. For **Architecture**, choose the correct processor architecture for each installable file from the drop-down list. For more information about supported architectures, see [Supported package platforms and architectures](distributor.md#what-is-a-package-platforms).
1. (Optional) Expand **Scripts**, and review the installation and uninstallation scripts that Distributor generates for your installable software.
1. To add more installable software files to the new version, choose **Add software**. Otherwise, go to the next step.
1. (Optional) Expand **Manifest**, and review the JSON package manifest that Distributor generates for your installable software. If you changed any information about your installable software since you began this procedure, such as platform version or target platform, choose **Generate manifest** to show the updated package manifest.
You can edit the manifest manually if you want to target a software installable at more than one operating system, as described in step 9. For more information about editing the manifest, see [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
1. When you finish adding software and reviewing the target platform, version, and architecture data, choose **Add version**.
1. Wait for Distributor to finish uploading your software and creating the new package version. Distributor shows upload status for each installable file. Depending on the number and size of packages you are adding, this can take a few minutes. Distributor automatically redirects you to the **Package details** page for the package, but you can choose to open this page yourself after the software is uploaded. The **Package details** page doesn't show all information about your package until Distributor finishes creating the new package version. To stop the upload and package version creation, choose **Stop upload**.
1. If Distributor can't upload any of the software installable files, it displays an **Upload failed** message. To retry the upload, choose **Retry upload**. For more information about how to troubleshoot package version creation failures, see [Troubleshooting AWS Systems Manager Distributor](distributor-troubleshooting.md).
1. When Distributor is finished creating the new package version, on the package's **Details** page, on the **Versions** tab, view the new version in the list of available package versions. Set a default version of the package by choosing a version, and then choosing **Set default version**.
If you don't set a default version, the newest package version is the default version.
### Adding a package version using the Advanced workflow
To add a package version, [create a package](distributor-working-with-packages-create.md), and then use Distributor to add a package version by adding an entry to the SSM document that exists for older versions. To save time, update the manifest for an older version of the package, change the value of the `version` entry in the manifest (for example, from `Test_1.0` to `Test_2.0`) and save it as the manifest for the new version. You must have an updated manifest to add a new package version by using the **Advanced** workflow.
**To add a package version using the Advanced workflow**
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 **Distributor**.
1. On the Distributor home page, choose the package to which you want to add another version, and then choose **Add version**.
1. For **Version name**, enter the exact value that is in the `version` entry of your manifest file.
1. For **S3 bucket name**, choose an existing S3 bucket from the list. This can be the same bucket that you used to store installable files for older versions, but the installable file names must be different to avoid overwriting existing installable files in the bucket.
1. For **S3 key prefix**, enter the subfolder of the bucket where your installable assets are stored.
1. For **Manifest**, choose **Extract from package** to use a manifest that you uploaded to the S3 bucket with your .zip files.
(Optional) If you didn't upload your revised JSON manifest to the Amazon S3 bucket where you stored your .zip files, choose **New manifest**. You can author or paste the entire manifest in the JSON editor field. For more information about how to create the JSON manifest, see [Step 2: Create the JSON package manifest](distributor-working-with-packages-create.md#packages-manifest).
1. When you're finished with the manifest, choose **Add package version**.
1. On the package's **Details** page, on the **Versions** tab, view the new version in the list of available package versions. Set a default version of the package by choosing a version, and then choosing **Set default version**.
If you don't set a default version, the newest package version is the default version.
## Adding a package version using the AWS CLI
You can use the AWS CLI to add a new package version to Distributor. Before you run these commands, you must create a new package version and upload it to S3, as described at the start of this topic.
**To add a package version using the AWS CLI**
1. Run the following command to edit the AWS Systems Manager document with an entry for a new package version. Replace *document-name* with the name of your document. Replace *amzn-s3-demo-bucket* with the URL of the JSON manifest that you copied in [Step 3: Upload the package and manifest to an Amazon S3 bucket](distributor-working-with-packages-create.md#packages-upload-s3). *S3-bucket-URL-of-package* is the URL of the Amazon S3 bucket where the entire package is stored. Replace *version-name-from-updated-manifest* with the value of `version` in the manifest. Set the `--document-version` parameter to `$LATEST` to make the document associated with this package version the latest version of the document.
```
aws ssm update-document \
--name "document-name" \
--content "S3-bucket-URL-to-manifest-file" \
--attachments Key="SourceUrl",Values="amzn-s3-demo-bucket" \
--version-name version-name-from-updated-manifest \
--document-version $LATEST
```
The following is an example.
```
aws ssm update-document \
--name ExamplePackage \
--content "https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage/manifest.json" \
--attachments Key="SourceUrl",Values="https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage" \
--version-name 1.1.1 \
--document-version $LATEST
```
1. Run the following command to verify that your package was updated and show the package manifest. Replace *package-name* with the name of your package, and optionally, *document-version* with the version number of the document (not the same as the package version) that you updated. If this package version is associated with the latest version of the document, you can specify `$LATEST` for the value of the optional `--document-version` parameter.
```
aws ssm get-document \
--name "package-name" \
--document-version "document-version"
```
For information about other options you can use with the **update-document** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
# Install or update Distributor packages
You can deploy packages to your AWS Systems Manager managed nodes by using Distributor, a tool in AWS Systems Manager. To deploy the packages, use either the AWS Management Console or AWS Command Line Interface (AWS CLI). You can deploy one version of one package per command. You can install new packages or update existing installations in place. You can choose to deploy a specific version or choose to always deploy the latest version of a package for deployment. We recommend using State Manager, a tool in AWS Systems Manager, to install packages. Using State Manager helps ensure that your managed nodes are always running the most up-to-date version of your package.
**Important**
Packages that you install using Distributor should be uninstalled only by using Distributor. Otherwise, Systems Manager can still register the application as `INSTALLED` and lead to other unintended results.
| Preference | AWS Systems Manager action | More info |
| --- | --- | --- |
| Install or update a package immediately. | Run Command | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html) |
| Install or update a package on a schedule, so that the installation always includes the default version. | State Manager | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html) |
| Automatically install a package on new managed nodes that have a specific tag or set of tags. For example, installing the Amazon CloudWatch agent on new instances. | State Manager | One way to do this is to apply tags to new managed nodes, and then specify the tags as targets in your State Manager association. State Manager automatically installs the package in an association on managed nodes that have matching tags. See [Understanding targets and rate controls in State Manager associations](systems-manager-state-manager-targets-and-rate-controls.md). |
**Topics**
+ [Installing or updating a package one time using the console](#distributor-deploy-pkg-console)
+ [Scheduling a package installation or update using the console](#distributor-deploy-sm-pkg-console)
+ [Installing a package one time using the AWS CLI](#distributor-deploy-pkg-cli)
+ [Updating a package one time using the AWS CLI](#distributor-update-pkg-cli)
+ [Scheduling a package installation using the AWS CLI](#distributor-smdeploy-pkg-cli)
+ [Scheduling a package update using the AWS CLI](#distributor-smupdate-pkg-cli)
## Installing or updating a package one time using the console
You can use the AWS Systems Manager console to install or update a package one time. When you configure a one-time installation, Distributor uses [AWS Systems Manager Run Command](run-command.md), a tool in AWS Systems Manager, to perform the installation.
**To install or update a package one time using the 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 **Distributor**.
1. On the Distributor home page, choose the package that you want to install.
1. Choose **Install one time**.
This command opens Run Command with the command document `AWS-ConfigureAWSPackage` and your Distributor package already selected.
1. For **Document version**, select the version of the `AWS-ConfigureAWSPackage` document that you want to run.
1. For **Action**, choose **Install**.
1. For **Installation type**, choose one of the following:
+ **Uninstall and reinstall**: The package is completely uninstalled, and then reinstalled. The application is unavailable until the reinstallation is complete.
+ **In-place update**: Only new or changed files are added to the existing installation according to instructions you provide in an `update` script. The application remains available throughout the update process. This option isn't supported for AWS published packages except the `AWSEC2Launch-Agent` package.
1. For **Name**, verify that the name of the package you selected is entered.
1. (Optional) For **Version**, enter the version name value of the package. If you leave this field blank, Run Command installs the default version that you selected in Distributor.
1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or devices manually, or by specifying a resource group.
**Note**
If you don't see a managed node in the list, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md).
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 targets on which to run the command at the same time.
**Note**
If you selected targets by specifying tags or 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 targets after it fails on either a number or a percentage of managed 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. When you're ready to install the package, choose **Run**.
1. The **Command status** area reports the progress of the execution. If the command is still in progress, choose the refresh icon in the top-left corner of the console until the **Overall status** or **Detailed status** column shows **Success** or **Failed**.
1. In the **Targets and outputs** area, choose the button next to a managed node name, and then choose **View output**.
The command output page shows the results of your command execution.
1. (Optional) If you chose to write command output to an Amazon S3 bucket, choose **Amazon S3** to view the output log data.
## Scheduling a package installation or update using the console
You can use the AWS Systems Manager console to schedule the installation or update of a package. When you schedule package installation or update, Distributor uses [AWS Systems Manager State Manager](systems-manager-state.md) to install or update.
**To schedule a package installation using the 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 **Distributor**.
1. On the Distributor home page, choose the package that you want to install or update.
1. For **Package**, choose **Install on a schedule**.
This command opens State Manager to a new association that is created for you.
1. For **Name**, enter a name (for example, **Deploy-test-agent-package**). This is optional, but recommended. Spaces aren't allowed in the name.
1. In the **Document** list, the document name `AWS-ConfigureAWSPackage` is already selected.
1. For **Action**, verify that **Install** is selected.
1. For **Installation type**, choose one of the following:
+ **Uninstall and reinstall**: The package is completely uninstalled, and then reinstalled. The application is unavailable until the reinstallation is complete.
+ **In-place update**: Only new or changed files are added to the existing installation according to instructions you provide in an `update` script. The application remains available throughout the update process.
1. For **Name**, verify that the name of your package is entered.
1. For **Version**, if you to want to install a package version other than the latest published version, enter the version identifier.
1. For **Targets**, choose **Selecting all managed instances in this account**, **Specifying tags**, or **Manually Selecting Instance**. If you target resources by using tags, enter a tag key and a tag value in the fields provided.
**Note**
You can choose managed AWS IoT Greengrass core devices by choosing either **Selecting all managed instances in this account** or **Manually Selecting Instance**.
1. For **Specify schedule**, choose **On Schedule** to run the association on a regular schedule, or **No Schedule** to run the association once. For more information about these options, see [Working with associations in Systems Manager](state-manager-associations.md). Use the controls to create a `cron` or rate schedule for the association.
1. Choose **Create Association**.
1. On the **Association** page, choose the button next to the association you created, and then choose **Apply association now**.
State Manager creates and immediately runs the association on the specified targets. For more information about the results of running associations, see [Working with associations in Systems Manager](state-manager-associations.md) in this guide.
For more information about working with the options in **Advanced options**, **Rate control**, and **Output options**, see [Working with associations in Systems Manager](state-manager-associations.md).
## Installing a package one time using the AWS CLI
You can run **send-command** in the AWS CLI to install a Distributor package one time. If the package is already installed, the application will be taken offline while the package is uninstalled and the new version installed in its place.
**To install a package one time using the AWS CLI**
+ Run the following command in the AWS CLI.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
**Note**
The default behavior for `installationType` is `Uninstall and reinstall`. You can omit `"installationType":["Uninstall and reinstall"]` from this command when you're installing a complete package.
The following is an example.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-00000000000000" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["ExamplePackage"]}'
```
For information about other options you can use with the **send-command** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
## Updating a package one time using the AWS CLI
You can run **send-command** in the AWS CLI to update a Distributor package without taking the associated application offline. Only new or updated files in the package are replaced.
**To update a package one time using the AWS CLI**
+ Run the following command in the AWS CLI.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
**Note**
When you add new or changed files, you must include `"installationType":["In-place update"]` in the command.
The following is an example.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-02573cafcfEXAMPLE" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["ExamplePackage"]}'
```
For information about other options you can use with the **send-command** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
## Scheduling a package installation using the AWS CLI
You can run **create-association** in the AWS CLI to install a Distributor package on a schedule. The value of `--name`, the document name, is always `AWS-ConfigureAWSPackage`. The following command uses the key `InstanceIds` to specify target managed nodes. If the package is already installed, the application will be taken offline while the package is uninstalled and the new version installed in its place.
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance-ID1\",\"instance-ID2\"]}]
```
**Note**
The default behavior for `installationType` is `Uninstall and reinstall`. You can omit `"installationType":["Uninstall and reinstall"]` from this command when you're installing a complete package.
The following is an example.
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["Test-ConfigureAWSPackage"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"i-02573cafcfEXAMPLE\",\"i-0471e04240EXAMPLE\"]}]
```
For information about other options you can use with the **create-association** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
## Scheduling a package update using the AWS CLI
You can run **create-association** in the AWS CLI to update a Distributor package on a schedule without taking the associated application offline. Only new or updated files in the package are replaced. The value of `--name`, the document name, is always `AWS-ConfigureAWSPackage`. The following command uses the key `InstanceIds` to specify target instances.
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance-ID1\",\"instance-ID2\"]}]
```
**Note**
When you add new or changed files, you must include `"installationType":["In-place update"]` in the command.
The following is an example.
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["Test-ConfigureAWSPackage"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"i-02573cafcfEXAMPLE\",\"i-0471e04240EXAMPLE\"]}]
```
For information about other options you can use with the **create-association** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
# Uninstall a Distributor package
You can use the AWS Management Console or the AWS Command Line Interface (AWS CLI) to uninstall Distributor packages from your AWS Systems Manager managed nodes by using Run Command. Distributor and Run Command are tools in AWS Systems Manager. In this release, you can uninstall one version of one package per command. You can uninstall a specific version or the default version.
**Important**
Packages that you install using Distributor should be uninstalled only by using Distributor. Otherwise, Systems Manager can still register the application as `INSTALLED` and lead to other unintended results.
**Topics**
+ [Uninstalling a package using the console](#distributor-pkg-uninstall-console)
+ [Uninstalling a package using the AWS CLI](#distributor-pkg-uninstall-cli)
## Uninstalling a package using the console
You can use Run Command in the Systems Manager console to uninstall a package one time. Distributor uses [AWS Systems Manager Run Command](run-command.md) to uninstall packages.
**To uninstall a package using the 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 **Run Command**.
1. On the Run Command home page, choose **Run command**.
1. Choose the `AWS-ConfigureAWSPackage` command document.
1. From **Action**, choose **Uninstall**
1. For **Name**, enter the name of the package that you want to uninstall.
1. For **Targets**, choose how you want to target your managed nodes. You can specify a tag key and values that are shared by the targets. You can also specify targets by choosing attributes, such as an ID, platform, and SSM Agent version.
1. You can use the advanced options to add comments about the operation, change **Concurrency** and **Error threshold** values in **Rate control**, specify output options, or configure Amazon Simple Notification Service (Amazon SNS) notifications. For more information, see [Running Commands from the Console](https://docs.aws.amazon.com/systems-manager/latest/userguide/rc-console.html) in this guide.
1. When you're ready to uninstall the package, choose **Run**, and then choose **View results**.
1. In the commands list, choose the `AWS-ConfigureAWSPackage` command that you ran. If the command is still in progress, choose the refresh icon in the top-right corner of the console.
1. When the **Status** column shows **Success** or **Failed**, choose the **Output** tab.
1. Choose **View output**. The command output page shows the results of your command execution.
## Uninstalling a package using the AWS CLI
You can use the AWS CLI to uninstall a Distributor package from managed nodes by using Run Command.
**To uninstall a package using the AWS CLI**
+ Run the following command in the AWS CLI.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Uninstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
The following is an example.
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-02573cafcfEXAMPLE" \
--parameters '{"action":["Uninstall"],"name":["Test-ConfigureAWSPackage"]}'
```
For information about other options you can use with the **send-command** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*.
# Delete a Distributor package
This section describes how to a delete a package. You can't delete a version of a package, only the entire package.
## Deleting a package using the console
You can use the AWS Systems Manager console to delete a package or a package version from Distributor, a tool in AWS Systems Manager. Deleting a package deletes all versions of a package from Distributor.
**To delete a package using the 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 **Distributor**.
1. On the **Distributor** home page, choose the package that you want to delete.
1. On the package's details page, choose **Delete package**.
1. When you're prompted to confirm the deletion, choose **Delete package**.
## Deleting a package version using the console
You can use the Systems Manager console to delete a package version from Distributor.
**To delete a package version using the 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 **Distributor**.
1. On the **Distributor** home page, choose the package that you want to delete a version of.
1. On the versions page for the package, choose the version to delete and choose **Delete version**.
1. When you're prompted to confirm the deletion, choose **Delete package version**.
## Deleting a package using the command line
You can use your preferred command line tool to delete a package from Distributor.
------
#### [ Linux & macOS ]
**To delete a package using the AWS CLI**
1. Run the following command to list documents for specific packages. In the results of this command, look for the package that you want to delete.
```
aws ssm list-documents \
--filters Key=Name,Values=package-name
```
1. Run the following command to delete a package. Replace *package-name* with the package name.
```
aws ssm delete-document \
--name "package-name"
```
1. Run the **list-documents** command again to verify that the package was deleted. The package you deleted shouldn't be included in the list.
```
aws ssm list-documents \
--filters Key=Name,Values=package-name
```
------
#### [ Windows ]
**To delete a package using the AWS CLI**
1. Run the following command to list documents for specific packages. In the results of this command, look for the package that you want to delete.
```
aws ssm list-documents ^
--filters Key=Name,Values=package-name
```
1. Run the following command to delete a package. Replace *package-name* with the package name.
```
aws ssm delete-document ^
--name "package-name"
```
1. Run the **list-documents** command again to verify that the package was deleted. The package you deleted shouldn't be included in the list.
```
aws ssm list-documents ^
--filters Key=Name,Values=package-name
```
------
#### [ PowerShell ]
**To delete a package using Tools for PowerShell**
1. Run the following command to list documents for specific packages. In the results of this command, look for the package that you want to delete.
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Name"
$filter.Values = "package-name"
Get-SSMDocumentList `
-Filters @($filter)
```
1. Run the following command to delete a package. Replace *package-name* with the package name.
```
Remove-SSMDocument `
-Name "package-name"
```
1. Run the **Get-SSMDocumentList** command again to verify that the package was deleted. The package you deleted shouldn't be included in the list.
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Name"
$filter.Values = "package-name"
Get-SSMDocumentList `
-Filters @($filter)
```
------
## Deleting a package version using the command line
You can use your preferred command line tool to delete a package version from Distributor.
------
#### [ Linux & macOS ]
**To delete a package version using the AWS CLI**
1. Run the following command to list the versions of your package. In the results of this command, look for the package version that you want to delete.
```
aws ssm list-document-versions \
--name "package-name"
```
1. Run the following command to delete a package version. Replace *package-name* with the package name and *version* with the version number.
```
aws ssm delete-document \
--name "package-name" \
--document-version version
```
1. Run the **list-document-versions** command to verify that the version of the package was deleted. The package version that you deleted shouldn't be found.
```
aws ssm list-document-versions \
--name "package-name"
```
------
#### [ Windows ]
**To delete a package version using the AWS CLI**
1. Run the following command to list the versions of your package. In the results of this command, look for the package version that you want to delete.
```
aws ssm list-document-versions ^
--name "package-name"
```
1. Run the following command to delete a package version. Replace *package-name* with the package name and *version* with the version number.
```
aws ssm delete-document ^
--name "package-name" ^
--document-version version
```
1. Run the **list-document-versions** command to verify that the version of the package was deleted. The package version that you deleted shouldn't be found.
```
aws ssm list-document-versions ^
--name "package-name"
```
------
#### [ PowerShell ]
**To delete a package version using Tools for PowerShell**
1. Run the following command to list the versions of your package. In the results of this command, look for the package version that you want to delete.
```
Get-SSMDocumentVersionList `
-Name "package-name"
```
1. Run the following command to delete a package version. Replace *package-name* with the package name and *version* with the version number.
```
Remove-SSMDocument `
-Name "package-name" `
-DocumentVersion version
```
1. Run the **Get-SSMDocumentVersionList** command to verify that the version of the package was deleted. The package version that you deleted shouldn't be found.
```
Get-SSMDocumentVersionList `
-Name "package-name"
```
------
For information about other options you can use with the **list-documents** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/list-documents.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-documents.html) in the AWS Systems Manager section of the *AWS CLI Command Reference*. For information about other options you can use with the **delete-document** command, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-document.html).
# Auditing and logging Distributor activity
You can use AWS CloudTrail to audit activity related to Distributor, a tool in AWS Systems Manager. For more information about auditing and logging options for Systems Manager, see [Logging and monitoring in AWS Systems Manager](monitoring.md).
## Audit Distributor activity using CloudTrail
CloudTrail captures API calls made in the AWS Systems Manager console, the AWS Command Line Interface (AWS CLI), and the Systems Manager SDK. The information can be viewed in the CloudTrail console or stored in an Amazon Simple Storage Service (Amazon S3) bucket. One bucket is used for all CloudTrail logs for your account.
Logs of Run Command and State Manager actions show document creation, package installation, and package uninstallation activity. Run Command and State Manager are tools in AWS Systems Manager. For more information about viewing and using CloudTrail logs of Systems Manager activity, see [Logging AWS Systems Manager API calls with AWS CloudTrail](monitoring-cloudtrail-logs.md).
# Troubleshooting AWS Systems Manager Distributor
The following information can help you troubleshoot problems that might occur when you use Distributor, a tool in AWS Systems Manager.
**Topics**
+ [Wrong package with the same name is installed](#distributor-tshoot-1)
+ [Error: Failed to retrieve manifest: Could not find latest version of package](#distributor-tshoot-2)
+ [Error: Failed to retrieve manifest: Validation exception](#distributor-tshoot-3)
+ [Package isn't supported (package is missing install action)](#distributor-tshoot-4)
+ [Error: Failed to download manifest : Document with name does not exist](#distributor-tshoot-5)
+ [Upload failed.](#distributor-tshoot-6)
+ [Error: Failed to find platform: no manifest found for platform: oracle, version 8.9, architecture x86\$164](#distributor-tshoot-7)
## Wrong package with the same name is installed
**Problem:** You've installed a package, but Distributor installed a different package instead.
**Cause:** During installation, Systems Manager finds AWS published packages as results before user-defined external packages. If your user-defined package name is the same as an AWS published package name, the AWS package is installed instead of your package.
**Solution:** To avoid this problem, name your package something different from the name for an AWS published package.
## Error: Failed to retrieve manifest: Could not find latest version of package
**Problem:** You received an error like the following.
```
Failed to retrieve manifest: ResourceNotFoundException: Could not find the latest version of package
arn:aws:ssm:::package/package-name status code: 400, request id: guid
```
**Cause:** You're using a version of SSM Agent with Distributor that is earlier than version 2.3.274.0.
**Solution:** Update the version of SSM Agent to version 2.3.274.0 or later. For more information, see [Updating the SSM Agent using Run Command](run-command-tutorial-update-software.md#rc-console-agentexample) or [Walkthrough: Automatically update SSM Agent with the AWS CLI](state-manager-update-ssm-agent-cli.md).
## Error: Failed to retrieve manifest: Validation exception
**Problem:** You received an error like the following.
```
Failed to retrieve manifest: ValidationException: 1 validation error detected: Value 'documentArn'
at 'packageName' failed to satisfy constraint: Member must satisfy regular expression pattern:
arn:aws:ssm:region-id:account-id:package/package-name
```
**Cause:** You're using a version of SSM Agent with Distributor that is earlier than version 2.3.274.0.
**Solution:** Update the version of SSM Agent to version 2.3.274.0 or later. For more information, see [Updating the SSM Agent using Run Command](run-command-tutorial-update-software.md#rc-console-agentexample) or [Walkthrough: Automatically update SSM Agent with the AWS CLI](state-manager-update-ssm-agent-cli.md).
## Package isn't supported (package is missing install action)
**Problem:** You received an error like the following.
```
Package is not supported (package is missing install action)
```
**Cause:** The package directory structure is incorrect.
**Solution:** Don't zip a parent directory containing the software and required scripts. Instead, create a `.zip` file of all the required contents directly in the absolute path. To verify the `.zip` file was created correctly, unzip the target platform directory and review the directory structure. For example, the install script absolute path should be `/ExamplePackage_targetPlatform/install.sh`.
## Error: Failed to download manifest : Document with name does not exist
**Problem:** You received an error like the following.
```
Failed to download manifest - failed to retrieve package document description: InvalidDocument: Document with name filename does not exist.
```
**Cause 1:** Distributor can't find the package by the package name when sharing a Distributor package from another account.
**Solution 1:** When sharing a package from another account, use the full Amazon Resource Name (ARN) for the package and not just its name.
**Cause 2:** When using a VPC, you haven't provided your IAM instance profile with access to the AWS managed S3 bucket that contains the document `AWS-ConfigureAWSPackage` for the AWS Region you are targeting.
**Solution 2:** Ensure that your IAM instance profile provides SSM Agent with access to the AWS managed S3 bucket that contains the document `AWS-ConfigureAWSPackage` for the AWS Region you are targeting, as explained in [SSM Agent communications with AWS managed S3 buckets](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions).
## Upload failed.
**Problem:** You received an error like the following.
```
Upload failed. At least one of your files was not successfully uploaded to your S3 bucket.
```
**Cause:** The name of your software package includes a space. For example, `Hello World.msi` would fail to upload.
## Error: Failed to find platform: no manifest found for platform: oracle, version 8.9, architecture x86\$164
**Problem:** You received an error like the following.
```
Failed to find platform: no manifest found for platform: oracle, version 8.9, architecture x86_64
```
**Cause:** The error means that the JSON package manifest does not have any definition for that platform, in this case, Oracle Linux..
**Solution:** Download the package you want to distribute from the [Trend Micro Deep Security Software](https://help.deepsecurity.trendmicro.com/software.html) site. Create an `.rpm` software package using the [Create a package using the Simple workflow](distributor-working-with-packages-create.md#distributor-working-with-packages-create-simple). Set the following values for the package and complete the upload software package using Distributor:
```
Platform version: _any
Target platform: oracle
Architecture: x86_64
```