• 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).
# SSM Command documents for patching managed nodes
This topic describes the nine Systems Manager documents (SSM documents) available to help you keep your managed nodes patched with the latest security-related updates.
We recommend using just five of these documents in your patching operations. Together, these five SSM documents provide you with a full range of patching options using AWS Systems Manager. Four of these documents were released later than the four legacy SSM documents they replace and represent expansions or consolidations of functionality.
**Recommended SSM documents for patching**
We recommend using the following five SSM documents in your patching operations.
+ `AWS-ConfigureWindowsUpdate`
+ `AWS-InstallWindowsUpdates`
+ `AWS-RunPatchBaseline`
+ `AWS-RunPatchBaselineAssociation`
+ `AWS-RunPatchBaselineWithHooks`
**Legacy SSM documents for patching**
The following four legacy SSM documents remain available in some AWS Regions but are no longer updated or supported. These documents aren't guaranteed to work in IPv6 environments and support only IPv4. They can't be guaranteed to work in all scenarios and might lose support in the future. We recommend that you don't use these documents for patching operations.
+ `AWS-ApplyPatchBaseline`
+ `AWS-FindWindowsUpdates`
+ `AWS-InstallMissingWindowsUpdates`
+ `AWS-InstallSpecificWindowsUpdates`
For steps to set up patching operations in an environment that supportsonly IPv6, see [Tutorial: Patching a server in an IPv6 only environment](patch-manager-server-patching-iPv6-tutorial.md).
Refer to the following sections for more information about using these SSM documents in your patching operations.
**Topics**
+ [SSM documents recommended for patching managed nodes](#patch-manager-ssm-documents-recommended)
+ [Legacy SSM documents for patching managed nodes](#patch-manager-ssm-documents-legacy)
+ [Known limitations of the SSM documents for patching managed nodes](#patch-manager-ssm-documents-known-limitations)
+ [SSM Command document for patching: `AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)
+ [SSM Command document for patching: `AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md)
+ [SSM Command document for patching: `AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md)
+ [Sample scenario for using the InstallOverrideList parameter in `AWS-RunPatchBaseline` or `AWS-RunPatchBaselineAssociation`](patch-manager-override-lists.md)
+ [Using the BaselineOverride parameter](patch-manager-baselineoverride-parameter.md)
## SSM documents recommended for patching managed nodes
The following five SSM documents are recommended for use in your managed node patching operations.
**Topics**
+ [`AWS-ConfigureWindowsUpdate`](#patch-manager-ssm-documents-recommended-AWS-ConfigureWindowsUpdate)
+ [`AWS-InstallWindowsUpdates`](#patch-manager-ssm-documents-recommended-AWS-InstallWindowsUpdates)
+ [`AWS-RunPatchBaseline`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaseline)
+ [`AWS-RunPatchBaselineAssociation`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaselineAssociation)
+ [`AWS-RunPatchBaselineWithHooks`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaselineWithHooks)
### `AWS-ConfigureWindowsUpdate`
Supports configuring basic Windows Update functions and using them to install updates automatically (or to turn off automatic updates). Available in all AWS Regions.
This SSM document prompts Windows Update to download and install the specified updates and reboot managed nodes as needed. Use this document with State Manager, a tool in AWS Systems Manager, to ensure Windows Update maintains its configuration. You can also run it manually using Run Command, a tool in AWS Systems Manager, to change the Windows Update configuration.
The available parameters in this document support specifying a category of updates to install (or whether to turn off automatic updates), as well as specifying the day of the week and time of day to run patching operations. This SSM document is most useful if you don't need strict control over Windows updates and don't need to collect compliance information.
**Replaces legacy SSM documents: **
+ *None*
### `AWS-InstallWindowsUpdates`
Installs updates on a Windows Server managed node. Available in all AWS Regions.
This SSM document provides basic patching functionality in cases where you either want to install a specific update (using the `Include Kbs` parameter), or want to install patches with specific classifications or categories but don't need patch compliance information.
**Replaces legacy SSM documents:**
+ `AWS-FindWindowsUpdates`
+ `AWS-InstallMissingWindowsUpdates`
+ `AWS-InstallSpecificWindowsUpdates`
The three legacy documents perform different functions, but you can achieve the same results by using different parameter settings with the newer SSM document `AWS-InstallWindowsUpdates`. These parameter settings are described in [Legacy SSM documents for patching managed nodes](#patch-manager-ssm-documents-legacy).
### `AWS-RunPatchBaseline`
Installs patches on your managed nodes or scans nodes to determine whether any qualified patches are missing. Available in all AWS Regions.
`AWS-RunPatchBaseline` allows you to control patch approvals using the patch baseline specified as the "default" for an operating system type. Reports patch compliance information that you can view using the Systems Manager Compliance tools. These tools provide you with insights on the patch compliance state of your managed nodes, such as which nodes are missing patches and what those patches are. When you use `AWS-RunPatchBaseline`, patch compliance information is recorded using the `PutInventory` API command. For Linux operating systems, compliance information is provided for patches from both the default source repository configured on a managed node and from any alternative source repositories you specify in a custom patch baseline. For more information about alternative source repositories, see [How to specify an alternative patch source repository (Linux)](patch-manager-alternative-source-repository.md). For more information about the Systems Manager Compliance tools, see [AWS Systems Manager Compliance](systems-manager-compliance.md).
**Replaces legacy documents:**
+ `AWS-ApplyPatchBaseline`
The legacy document `AWS-ApplyPatchBaseline` applies only to Windows Server managed nodes, and doesn't provide support for application patching. The newer `AWS-RunPatchBaseline` provides the same support for both Windows and Linux systems. Version 2.0.834.0 or later of SSM Agent is required in order to use the `AWS-RunPatchBaseline` document.
For more information about the `AWS-RunPatchBaseline` SSM document, see [SSM Command document for patching: `AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md).
### `AWS-RunPatchBaselineAssociation`
Installs patches on your instances or scans instances to determine whether any qualified patches are missing. Available in all commercial AWS Regions.
`AWS-RunPatchBaselineAssociation` differs from `AWS-RunPatchBaseline` in a few important ways:
+ `AWS-RunPatchBaselineAssociation` is intended for use primarily with State Manager associations created using Quick Setup, a tool in AWS Systems Manager. Specifically, when you use the Quick Setup Host Management configuration type, if you choose the option **Scan instances for missing patches daily**, the system uses `AWS-RunPatchBaselineAssociation` for the operation.
In most cases, however, when setting up your own patching operations, you should choose [`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md) or [`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md) instead of `AWS-RunPatchBaselineAssociation`.
For more information, see the following topics:
+ [AWS Systems Manager Quick Setup](systems-manager-quick-setup.md)
+ [SSM Command document for patching: `AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md)
+ `AWS-RunPatchBaselineAssociation` supports the use of tags to identify which patch baseline to use with a set of targets when it runs.
+ For patching operations that use `AWS-RunPatchBaselineAssociation`, patch compliance data is compiled in terms of a specific State Manager association. The patch compliance data collected when `AWS-RunPatchBaselineAssociation` runs is recorded using the `PutComplianceItems` API command instead of the `PutInventory` command. This prevents compliance data that isn't associated with this particular association from being overwritten.
For Linux operating systems, compliance information is provided for patches from both the default source repository configured on an instance and from any alternative source repositories you specify in a custom patch baseline. For more information about alternative source repositories, see [How to specify an alternative patch source repository (Linux)](patch-manager-alternative-source-repository.md). For more information about the Systems Manager Compliance tools, see [AWS Systems Manager Compliance](systems-manager-compliance.md).
**Replaces legacy documents:**
+ **None**
For more information about the `AWS-RunPatchBaselineAssociation` SSM document, see [SSM Command document for patching: `AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md).
### `AWS-RunPatchBaselineWithHooks`
Installs patches on your managed nodes or scans nodes to determine whether any qualified patches are missing, with optional hooks you can use to run SSM documents at three points during the patching cycle. Available in all commercial AWS Regions. Not supported on macOS.
`AWS-RunPatchBaselineWithHooks` differs from `AWS-RunPatchBaseline` in its `Install` operation.
`AWS-RunPatchBaselineWithHooks` supports lifecycle hooks that run at designated points during managed node patching. Because patch installations sometimes require managed nodes to reboot, the patching operation is divided into two events, for a total of three hooks that support custom functionality. The first hook is before the `Install with NoReboot` operation. The second hook is after the `Install with NoReboot` operation. The third hook is available after the reboot of the node.
**Replaces legacy documents:**
+ **None**
For more information about the `AWS-RunPatchBaselineWithHooks` SSM document, see [SSM Command document for patching: `AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md).
## Legacy SSM documents for patching managed nodes
The following four SSM documents are still available in some AWS Regions. However, they are no longer updated and might be no longer supported in the future, so we don't recommend their use. Instead, use the documents described in [SSM documents recommended for patching managed nodes](#patch-manager-ssm-documents-recommended).
**Topics**
+ [`AWS-ApplyPatchBaseline`](#patch-manager-ssm-documents-legacy-AWS-ApplyPatchBaseline)
+ [`AWS-FindWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-AWS-FindWindowsUpdates)
+ [`AWS-InstallMissingWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-InstallMissingWindowsUpdates)
+ [`AWS-InstallSpecificWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-InstallSpecificWindowsUpdates)
### `AWS-ApplyPatchBaseline`
Supports only Windows Server managed nodes, but doesn't include support for patching applications that is found in its replacement, `AWS-RunPatchBaseline`. Not available in AWS Regions launched after August 2017.
**Note**
The replacement for this SSM document, `AWS-RunPatchBaseline`, requires version 2.0.834.0 or a later version of SSM Agent. You can use the `AWS-UpdateSSMAgent` document to update your managed nodes to the latest version of the agent.
### `AWS-FindWindowsUpdates`
Replaced by `AWS-InstallWindowsUpdates`, which can perform all the same actions. Not available in AWS Regions launched after April 2017.
To achieve the same result that you would from this legacy SSM document, use the following parameter configuration with the recommended replacement document, `AWS-InstallWindowsUpdates`:
+ `Action` = `Scan`
+ `Allow Reboot` = `False`
### `AWS-InstallMissingWindowsUpdates`
Replaced by `AWS-InstallWindowsUpdates`, which can perform all the same actions. Not available in any AWS Regions launched after April 2017.
To achieve the same result that you would from this legacy SSM document, use the following parameter configuration with the recommended replacement document, `AWS-InstallWindowsUpdates`:
+ `Action` = `Install`
+ `Allow Reboot` = `True`
### `AWS-InstallSpecificWindowsUpdates`
Replaced by `AWS-InstallWindowsUpdates`, which can perform all the same actions. Not available in any AWS Regions launched after April 2017.
To achieve the same result that you would from this legacy SSM document, use the following parameter configuration with the recommended replacement document, `AWS-InstallWindowsUpdates`:
+ `Action` = `Install`
+ `Allow Reboot` = `True`
+ `Include Kbs` = *comma-separated list of KB articles*
## Known limitations of the SSM documents for patching managed nodes
### External reboot interruptions
If a reboot is initiated by the system on the node during patch installation (for example, to apply updates to firmware or features like SecureBoot), the patching document execution may be interrupted and marked as failed even though patches were successfully installed. This occurs because the SSM Agent cannot persist and resume the document execution state across external reboots.
To verify patch installation status after a failed execution, run a `Scan` patching operation, then check the patch compliance data in Patch Manager to assess the current compliance state.
# SSM Command document for patching: `AWS-RunPatchBaseline`
AWS Systems Manager supports `AWS-RunPatchBaseline`, a Systems Manager document (SSM document) for Patch Manager, a tool in AWS Systems Manager. This SSM document performs patching operations on managed nodes for both security related and other types of updates. When the document is run, it uses the patch baseline specified as the "default" for an operating system type if no patch group is specified. Otherwise, it uses the patch baseline that is associated with the patch group. For information about patch groups, see [Patch groups](patch-manager-patch-groups.md).
You can use the document `AWS-RunPatchBaseline` to apply patches for both operating systems and applications. (On Windows Server, application support is limited to updates for applications released by Microsoft.)
This document supports Linux, macOS, and Windows Server managed nodes. The document will perform the appropriate actions for each platform.
**Note**
Patch Manager also supports the legacy SSM document `AWS-ApplyPatchBaseline`. However, this document supports patching on Windows managed nodes only. We encourage you to use `AWS-RunPatchBaseline` instead because it supports patching on Linux, macOS, and Windows Server managed nodes. Version 2.0.834.0 or later of SSM Agent is required in order to use the `AWS-RunPatchBaseline` document.
------
#### [ Windows Server ]
On Windows Server managed nodes, the `AWS-RunPatchBaseline` document downloads and invokes a PowerShell module, which in turn downloads a snapshot of the patch baseline that applies to the managed node. This patch baseline snapshot contains a list of approved patches that is compiled by querying the patch baseline against a Windows Server Update Services (WSUS) server. This list is passed to the Windows Update API, which controls downloading and installing the approved patches as appropriate.
------
#### [ Linux ]
On Linux managed nodes, the `AWS-RunPatchBaseline` document invokes a Python module, which in turn downloads a snapshot of the patch baseline that applies to the managed node. This patch baseline snapshot uses the defined rules and lists of approved and blocked patches to drive the appropriate package manager for each node type:
+ Amazon Linux 2, Oracle Linux, and RHEL 7 managed nodes use YUM. For YUM operations, Patch Manager requires `Python 2.6` or a later supported version (2.6 - 3.12). Amazon Linux 2023 uses DNF. For DNF operations, Patch Manager requires a supported version of `Python 2` or `Python 3` (2.6 - 3.12).
+ RHEL 8 managed nodes use DNF. For DNF operations, Patch Manager requires a supported version of `Python 2` or `Python 3` (2.6 - 3.12). (Neither version is installed by default on RHEL 8. You must install one or the other manually.)
+ Debian Server, and Ubuntu Server instances use APT. For APT operations, Patch Manager requires a supported version of `Python 3` (3.0 - 3.12).
------
#### [ macOS ]
On macOS managed nodes, the `AWS-RunPatchBaseline` document invokes a Python module, which in turn downloads a snapshot of the patch baseline that applies to the managed node. Next, a Python subprocess invokes the AWS Command Line Interface (AWS CLI) on the node to retrieve the installation and update information for the specified package managers and to drive the appropriate package manager for each update package.
------
Each snapshot is specific to an AWS account, patch group, operating system, and snapshot ID. The snapshot is delivered through a presigned Amazon Simple Storage Service (Amazon S3) URL, which expires 24 hours after the snapshot is created. After the URL expires, however, if you want to apply the same snapshot content to other managed nodes, you can generate a new presigned Amazon S3 URL up to 3 days after the snapshot was created. To do this, use the [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-deployable-patch-snapshot-for-instance.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-deployable-patch-snapshot-for-instance.html) command.
After all approved and applicable updates have been installed, with reboots performed as necessary, patch compliance information is generated on a managed node and reported back to Patch Manager.
**Note**
If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaseline` document, the managed node isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption).
For information about viewing patch compliance data, see [About patch compliance](compliance-about.md#compliance-monitor-patch).
## `AWS-RunPatchBaseline` parameters
`AWS-RunPatchBaseline` supports six parameters. The `Operation` parameter is required. The `InstallOverrideList`, `BaselineOverride`, and `RebootOption` parameters are optional. `Snapshot-ID` is technically optional, but we recommend that you supply a custom value for it when you run `AWS-RunPatchBaseline` outside of a maintenance window. Patch Manager can supply the custom value automatically when the document is run as part of a maintenance window operation.
**Topics**
+ [Parameter name: `Operation`](#patch-manager-aws-runpatchbaseline-parameters-operation)
+ [Parameter name: `AssociationId`](#patch-manager-aws-runpatchbaseline-parameters-association-id)
+ [Parameter name: `Snapshot ID`](#patch-manager-aws-runpatchbaseline-parameters-snapshot-id)
+ [Parameter name: `InstallOverrideList`](#patch-manager-aws-runpatchbaseline-parameters-installoverridelist)
+ [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption)
+ [Parameter name: `BaselineOverride`](#patch-manager-aws-runpatchbaseline-parameters-baselineoverride)
+ [Parameter name: `StepTimeoutSeconds`](#patch-manager-aws-runpatchbaseline-parameters-steptimeoutseconds)
### Parameter name: `Operation`
**Usage**: Required.
**Options**: `Scan` \$1 `Install`.
Scan
When you choose the `Scan` option, `AWS-RunPatchBaseline` determines the patch compliance state of the managed node and reports this information back to Patch Manager. `Scan` doesn't prompt updates to be installed or managed nodes to be rebooted. Instead, the operation identifies where updates are missing that are approved and applicable to the node.
Install
When you choose the `Install` option, `AWS-RunPatchBaseline` attempts to install the approved and applicable updates that are missing from the managed node. Patch compliance information generated as part of an `Install` operation doesn't list any missing updates, but might report updates that are in a failed state if the installation of the update didn't succeed for any reason. Whenever an update is installed on a managed node, the node is rebooted to ensure the update is both installed and active. (Exception: If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaseline` document, the managed node isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption).)
If a patch specified by the baseline rules is installed *before* Patch Manager updates the managed node, the system might not reboot as expected. This can happen when a patch is installed manually by a user or installed automatically by another program, such as the `unattended-upgrades` package on Ubuntu Server.
### Parameter name: `AssociationId`
**Usage**: Optional.
`AssociationId` is the ID of an existing association in State Manager, a tool in AWS Systems Manager. It's used by Patch Manager to add compliance data to a specified association. This association is related to a patching operation that's [set up in a patch policy in Quick Setup](quick-setup-patch-manager.md).
**Note**
With the `AWS-RunPatchBaseline`, if an `AssociationId` value is provided along with a patch policy baseline override, patching is done as a `PatchPolicy` operation and the `ExecutionType` value reported in `AWS:ComplianceItem` is also `PatchPolicy`. If no `AssociationId` value is provided, patching is done as a `Command` operation and the `ExecutionType` value report in on the `AWS:ComplianceItem` submitted is also `Command`.
If you don't already have an association you want to use, you can create one by running [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) the command.
### Parameter name: `Snapshot ID`
**Usage**: Optional.
`Snapshot ID` is a unique ID (GUID) used by Patch Manager to ensure that a set of managed nodes that are patched in a single operation all have the exact same set of approved patches. Although the parameter is defined as optional, our best practice recommendation depends on whether or not you're running `AWS-RunPatchBaseline` in a maintenance window, as described in the following table.
**`AWS-RunPatchBaseline` best practices**
| Mode | Best practice | Details |
| --- | --- | --- |
| Running AWS-RunPatchBaseline inside a maintenance window | Don't supply a Snapshot ID. Patch Manager will supply it for you. | If you use a maintenance window to run `AWS-RunPatchBaseline`, you shouldn't provide your own generated Snapshot ID. In this scenario, Systems Manager provides a GUID value based on the maintenance window execution ID. This ensures that a correct ID is used for all the invocations of `AWS-RunPatchBaseline` in that maintenance window. If you do specify a value in this scenario, note that the snapshot of the patch baseline might not remain in place for more than 3 days. After that, a new snapshot will be generated even if you specify the same ID after the snapshot expires. |
| Running AWS-RunPatchBaseline outside of a maintenance window | Generate and specify a custom GUID value for the Snapshot ID.¹ | When you aren't using a maintenance window to run `AWS-RunPatchBaseline`, we recommend that you generate and specify a unique Snapshot ID for each patch baseline, particularly if you're running the `AWS-RunPatchBaseline` document on multiple managed nodes in the same operation. If you don't specify an ID in this scenario, Systems Manager generates a different Snapshot ID for each managed node the command is sent to. This might result in varying sets of patches being specified among the managed nodes. For instance, say that you're running the `AWS-RunPatchBaseline` document directly through Run Command, a tool in AWS Systems Manager, and targeting a group of 50 managed nodes. Specifying a custom Snapshot ID results in the generation of a single baseline snapshot that is used to evaluate and patch all the nodes, ensuring that they end up in a consistent state. |
| ¹ You can use any tool capable of generating a GUID to generate a value for the Snapshot ID parameter. For example, in PowerShell, you can use the `New-Guid` cmdlet to generate a GUID in the format of `12345699-9405-4f69-bc5e-9315aEXAMPLE`. |
### Parameter name: `InstallOverrideList`
**Usage**: Optional.
Using `InstallOverrideList`, you specify an https URL or an Amazon S3 path-style URL to a list of patches to be installed. This patch installation list, which you maintain in YAML format, overrides the patches specified by the current default patch baseline. This provides you with more granular control over which patches are installed on your managed nodes.
**Important**
The `InstallOverrideList` file name can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
The patching operation behavior when using the `InstallOverrideList` parameter differs between Linux & macOS managed nodes and Windows Server managed nodes. On Linux & macOS, Patch Manager attempts to apply patches included in the `InstallOverrideList` patch list that are present in any repository enabled on the node, whether or not the patches match the patch baseline rules. On Windows Server nodes, however, patches in the `InstallOverrideList` patch list are applied *only* if they also match the patch baseline rules.
On Linux & macOS managed nodes, patches specified in the `InstallOverrideList` are applied only as updates to packages that are already installed on the node. If the `InstallOverrideList` includes patches for packages that are not currently installed on the node, those patches are not installed.
Be aware that compliance reports reflect patch states according to what’s specified in the patch baseline, not what you specify in an `InstallOverrideList` list of patches. In other words, Scan operations ignore the `InstallOverrideList` parameter. This is to ensure that compliance reports consistently reflect patch states according to policy rather than what was approved for a specific patching operation.
**Note**
When you're patching a node that only uses IPv6, ensure that the provided URL is reachable from the node. If the SSM Agent config option `UseDualStackEndpoint` is set to `true`, then a dualstack S3 client is used when an S3 URL is provided. See [Tutorial: Patching a server in an IPv6 only environment](patch-manager-server-patching-iPv6-tutorial.md) for more information on configuring the agent to use dualstack.
For a description of how you might use the `InstallOverrideList` parameter to apply different types of patches to a target group, on different maintenance window schedules, while still using a single patch baseline, see [Sample scenario for using the InstallOverrideList parameter in `AWS-RunPatchBaseline` or `AWS-RunPatchBaselineAssociation`](patch-manager-override-lists.md).
**Valid URL formats**
**Note**
If your file is stored in a publicly available bucket, you can specify either an https URL format or an Amazon S3 path-style URL. If your file is stored in a private bucket, you must specify an Amazon S3 path-style URL.
+ **https URL format**:
```
https://s3.aws-api-domain/amzn-s3-demo-bucket/my-windows-override-list.yaml
```
+ **Amazon S3 path-style URL**:
```
s3://amzn-s3-demo-bucket/my-windows-override-list.yaml
```
**Valid YAML content formats**
The formats you use to specify patches in your list depends on the operating system of your managed node. The general format, however, is as follows:
```
patches:
-
id: '{patch-d}'
title: '{patch-title}'
{additional-fields}:{values}
```
Although you can provide additional fields in your YAML file, they're ignored during patch operations.
In addition, we recommend verifying that the format of your YAML file is valid before adding or updating the list in your S3 bucket. For more information about the YAML format, see [yaml.org](http://www.yaml.org). For validation tool options, perform a web search for "yaml format validators".
------
#### [ Linux ]
**id**
The **id** field is required. Use it to specify patches using the package name and architecture. For example: `'dhclient.x86_64'`. You can use wildcards in id to indicate multiple packages. For example: `'dhcp*'` and `'dhcp*1.*'`.
**Title**
The **title** field is optional, but on Linux systems it does provide additional filtering capabilities. If you use **title**, it should contain the package version information in the one of the following formats:
YUM/SUSE Linux Enterprise Server (SLES):
```
{name}.{architecture}:{epoch}:{version}-{release}
```
APT
```
{name}.{architecture}:{version}
```
For Linux patch titles, you can use one or more wildcards in any position to expand the number of package matches. For example: `'*32:9.8.2-0.*.rc1.57.amzn1'`.
For example:
+ apt package version 1.2.25 is currently installed on your managed node, but version 1.2.27 is now available.
+ You add apt.amd64 version 1.2.27 to the patch list. It depends on apt utils.amd64 version 1.2.27, but apt-utils.amd64 version 1.2.25 is specified in the list.
In this case, apt version 1.2.27 will be blocked from installation and reported as “Failed-NonCompliant.”
------
#### [ Windows Server ]
**id**
The **id** field is required. Use it to specify patches using Microsoft Knowledge Base IDs (for example, KB2736693) and Microsoft Security Bulletin IDs (for example, MS17-023).
Any other fields you want to provide in a patch list for Windows are optional and are for your own informational use only. You can use additional fields such as **title**, **classification**, **severity**, or anything else for providing more detailed information about the specified patches.
------
#### [ macOS ]
**id**
The **id** field is required. The value for the **id** field can be supplied using either a `{package-name}.{package-version}` format or a \$1package\$1name\$1 format.
------
**Sample patch lists**
+ **Amazon Linux 2**
```
patches:
-
id: 'kernel.x86_64'
-
id: 'bind*.x86_64'
title: '39.11.4-26.P2.amzn2.5.2'
id: 'glibc*'
-
id: 'dhclient*'
title: '*4.2.5-58.amzn2'
-
id: 'dhcp*'
title: '*4.2.5-77.amzn2'
```
+ **Debian Server**
```
patches:
-
id: 'apparmor.amd64'
title: '2.10.95-0ubuntu2.9'
-
id: 'cryptsetup.amd64'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'cryptsetup-bin.*'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'apt.amd64'
title: '*1.2.27'
-
id: 'apt-utils.amd64'
title: '*1.2.25'
```
+ **macOS**
```
patches:
-
id: 'XProtectPlistConfigData'
-
id: 'MRTConfigData.1.61'
-
id: 'Command Line Tools for Xcode.11.5'
-
id: 'Gatekeeper Configuration Data'
```
+ **Oracle Linux**
```
patches:
-
id: 'audit-libs.x86_64'
title: '*2.8.5-4.el7'
-
id: 'curl.x86_64'
title: '*.el7'
-
id: 'grub2.x86_64'
title: 'grub2.x86_64:1:2.02-0.81.0.1.el7'
-
id: 'grub2.x86_64'
title: 'grub2.x86_64:1:*-0.81.0.1.el7'
```
+ **Red Hat Enterprise Linux (RHEL)**
```
patches:
-
id: 'NetworkManager.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'NetworkManager-*.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'audit.x86_64'
title: '*0:2.8.1-3.el7'
-
id: 'dhclient.x86_64'
title: '*.el7_5.1'
-
id: 'dhcp*.x86_64'
title: '*12:5.2.5-68.el7'
```
+ **SUSE Linux Enterprise Server (SLES)**
```
patches:
-
id: 'amazon-ssm-agent.x86_64'
-
id: 'binutils'
title: '*0:2.26.1-9.12.1'
-
id: 'glibc*.x86_64'
title: '*2.19*'
-
id: 'dhcp*'
title: '0:4.3.3-9.1'
-
id: 'lib*'
```
+ **Ubuntu Server **
```
patches:
-
id: 'apparmor.amd64'
title: '2.10.95-0ubuntu2.9'
-
id: 'cryptsetup.amd64'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'cryptsetup-bin.*'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'apt.amd64'
title: '*1.2.27'
-
id: 'apt-utils.amd64'
title: '*1.2.25'
```
+ **Windows**
```
patches:
-
id: 'KB4284819'
title: '2018-06 Cumulative Update for Windows Server 2016 (1709) for x64-based Systems (KB4284819)'
-
id: 'KB4284833'
-
id: 'KB4284835'
title: '2018-06 Cumulative Update for Windows Server 2016 (1803) for x64-based Systems (KB4284835)'
-
id: 'KB4284880'
-
id: 'KB4338814'
```
### Parameter name: `RebootOption`
**Usage**: Optional.
**Options**: `RebootIfNeeded` \$1 `NoReboot`
**Default**: `RebootIfNeeded`
**Warning**
The default option is `RebootIfNeeded`. Be sure to select the correct option for your use case. For example, if your managed nodes must reboot immediately to complete a configuration process, choose `RebootIfNeeded`. Or, if you need to maintain managed node availability until a scheduled reboot time, choose `NoReboot`.
**Important**
We don’t recommend using Patch Manager for patching cluster instances in Amazon EMR (previously called Amazon Elastic MapReduce). In particular, don’t select the `RebootIfNeeded` option for the `RebootOption` parameter. (This option is available in the SSM Command documents for patching `AWS-RunPatchBaseline`, `AWS-RunPatchBaselineAssociation`, and `AWS-RunPatchBaselineWithHooks`.)
The underlying commands for patching using Patch Manager use `yum` and `dnf` commands. Therefore, the operations result in incompatibilities because of how packages are installed. For information about the preferred methods for updating software on Amazon EMR clusters, see [Using the default AMI for Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-default-ami.html) in the *Amazon EMR Management Guide*.
RebootIfNeeded
When you choose the `RebootIfNeeded` option, the managed node is rebooted in either of the following cases:
+ Patch Manager installed one or more patches.
Patch Manager doesn't evaluate whether a reboot is *required* by the patch. The system is rebooted even if the patch doesn't require a reboot.
+ Patch Manager detects one or more patches with a status of `INSTALLED_PENDING_REBOOT` during the `Install` operation.
The `INSTALLED_PENDING_REBOOT` status can mean that the option `NoReboot` was selected the last time the `Install` operation was run, or that a patch was installed outside of Patch Manager since the last time the managed node was rebooted.
Rebooting managed nodes in these two cases ensures that updated packages are flushed from memory and keeps patching and rebooting behavior consistent across all operating systems.
NoReboot
When you choose the `NoReboot` option, Patch Manager doesn't reboot a managed node even if it installed patches during the `Install` operation. This option is useful if you know that your managed nodes don't require rebooting after patches are applied, or you have applications or processes running on a node that shouldn't be disrupted by a patching operation reboot. It's also useful when you want more control over the timing of managed node reboots, such as by using a maintenance window.
If you choose the `NoReboot` option and a patch is installed, the patch is assigned a status of `InstalledPendingReboot`. The managed node itself, however, is marked as `Non-Compliant`. After a reboot occurs and a `Scan` operation is run, the managed node status is updated to `Compliant`.
The `NoReboot` option only prevents operating system-level restarts. Service-level restarts can still occur as part of the patching process. For example, when Docker is updated, dependent services such as Amazon Elastic Container Service might automatically restart even with `NoReboot` enabled. If you have critical services that must not be disrupted, consider additional measures such as temporarily removing instances from service or scheduling patching during maintenance windows.
**Patch installation tracking file**: To track patch installation, especially patches that were installed since the last system reboot, Systems Manager maintains a file on the managed node.
**Important**
Don't delete or modify the tracking file. If this file is deleted or corrupted, the patch compliance report for the managed node is inaccurate. If this happens, reboot the node and run a patch Scan operation to restore the file.
This tracking file is stored in the following locations on your managed nodes:
+ Linux operating systems:
+ `/var/log/amazon/ssm/patch-configuration/patch-states-configuration.json`
+ `/var/log/amazon/ssm/patch-configuration/patch-inventory-from-last-operation.json`
+ Windows Server operating system:
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchStatesConfiguration.json`
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchInventoryFromLastOperation.json`
### Parameter name: `BaselineOverride`
**Usage**: Optional.
You can define patching preferences at runtime using the `BaselineOverride` parameter. This baseline override is maintained as a JSON object in an S3 bucket. It ensures patching operations use the provided baselines that match the host operating system instead of applying the rules from the default patch baseline
**Important**
The `BaselineOverride` file name can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
For more information about how to use the `BaselineOverride` parameter, see [Using the BaselineOverride parameter](patch-manager-baselineoverride-parameter.md).
### Parameter name: `StepTimeoutSeconds`
**Usage**: Required.
The time in seconds—between 1 and 36000 seconds (10 hours)—for a command to be completed before it is considered to have failed.
# SSM Command document for patching: `AWS-RunPatchBaselineAssociation`
Like the `AWS-RunPatchBaseline` document, `AWS-RunPatchBaselineAssociation` performs patching operations on instances for both security related and other types of updates. You can also use the document `AWS-RunPatchBaselineAssociation` to apply patches for both operating systems and applications. (On Windows Server, application support is limited to updates for applications released by Microsoft.)
This document supports Amazon Elastic Compute Cloud (Amazon EC2) instances for Linux, macOS, and Windows Server. It does not support non-EC2 nodes in a [hybrid and multicloud](operating-systems-and-machine-types.md#supported-machine-types) environment. The document will perform the appropriate actions for each platform, invoking a Python module on Linux and macOS instances, and a PowerShell module on Windows instances.
`AWS-RunPatchBaselineAssociation`, however, differs from `AWS-RunPatchBaseline` in the following ways:
+ `AWS-RunPatchBaselineAssociation` is intended for use primarily with State Manager associations created using [Quick Setup](systems-manager-quick-setup.md), a tool in AWS Systems Manager. Specifically, when you use the Quick Setup Host Management configuration type, if you choose the option **Scan instances for missing patches daily**, the system uses `AWS-RunPatchBaselineAssociation` for the operation.
In most cases, however, when setting up your own patching operations, you should choose [`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md) or [`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md) instead of `AWS-RunPatchBaselineAssociation`.
+ When you use the `AWS-RunPatchBaselineAssociation` document, you can specify a tag key pair in the document's `BaselineTags` parameter field. If a custom patch baseline in your AWS account shares these tags, Patch Manager, a tool in AWS Systems Manager, uses that tagged baseline when it runs on the target instances instead of the currently specified "default" patch baseline for the operating system type.
**Note**
If you choose to use `AWS-RunPatchBaselineAssociation` in patching operations other than those set up using Quick Setup, and you want to use its optional `BaselineTags` parameter, you must provide some additional permissions to the [instance profile](setup-instance-permissions.md) for Amazon Elastic Compute Cloud (Amazon EC2) instances. For more information, see [Parameter name: `BaselineTags`](#patch-manager-aws-runpatchbaselineassociation-parameters-baselinetags).
Both of the following formats are valid for your `BaselineTags` parameter:
`Key=tag-key,Values=tag-value`
`Key=tag-key,Values=tag-value1,tag-value2,tag-value3`
**Important**
Tag keys and values can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
+ When `AWS-RunPatchBaselineAssociation` runs, the patch compliance data it collects is recorded using the `PutComplianceItems` API command instead of the `PutInventory` command, which is used by `AWS-RunPatchBaseline`. This difference means that the patch compliance information that is stored and reported per a specific *association*. Patch compliance data generated outside of this association isn't overwritten.
+ The patch compliance information reported after running `AWS-RunPatchBaselineAssociation` indicates whether or not an instance is in compliance. It doesn't include patch-level details, as demonstrated by the output of the following AWS Command Line Interface (AWS CLI) command. The command filters on `Association` as the compliance type:
```
aws ssm list-compliance-items \
--resource-ids "i-02573cafcfEXAMPLE" \
--resource-types "ManagedInstance" \
--filters "Key=ComplianceType,Values=Association,Type=EQUAL" \
--region us-east-2
```
The system returns information like the following.
```
{
"ComplianceItems": [
{
"Status": "NON_COMPLIANT",
"Severity": "UNSPECIFIED",
"Title": "MyPatchAssociation",
"ResourceType": "ManagedInstance",
"ResourceId": "i-02573cafcfEXAMPLE",
"ComplianceType": "Association",
"Details": {
"DocumentName": "AWS-RunPatchBaselineAssociation",
"PatchBaselineId": "pb-0c10e65780EXAMPLE",
"DocumentVersion": "1"
},
"ExecutionSummary": {
"ExecutionTime": 1590698771.0
},
"Id": "3e5d5694-cd07-40f0-bbea-040e6EXAMPLE"
}
]
}
```
If a tag key pair value has been specified as a parameter for the `AWS-RunPatchBaselineAssociation` document, Patch Manager searches for a custom patch baseline that matches the operating system type and has been tagged with that same tag-key pair. This search isn't limited to the current specified default patch baseline or the baseline assigned to a patch group. If no baseline is found with the specified tags, Patch Manager next looks for a patch group, if one was specified in the command that runs `AWS-RunPatchBaselineAssociation`. If no patch group is matched, Patch Manager falls back to the current default patch baseline for the operating system account.
If more than one patch baseline is found with the tags specified in the `AWS-RunPatchBaselineAssociation` document, Patch Manager returns an error message indicating that only one patch baseline can be tagged with that key-value pair in order for the operation to proceed.
**Note**
On Linux nodes, the appropriate package manager for each node type is used to install packages:
Amazon Linux 2, Oracle Linux, and RHEL instances use YUM. For YUM operations, Patch Manager requires `Python 2.6` or a later supported version (2.6 - 3.12). Amazon Linux 2023 uses DNF. For DNF operations, Patch Manager requires a supported version of `Python 2` or `Python 3` (2.6 - 3.12)
Debian Server and Ubuntu Server instances use APT. For APT operations, Patch Manager requires a supported version of `Python 3` (3.0 - 3.12).
After a scan is complete, or after all approved and applicable updates have been installed, with reboots performed as necessary, patch compliance information is generated on an instance and reported back to the Patch Compliance service.
**Note**
If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaselineAssociation` document, the instance isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption).
For information about viewing patch compliance data, see [About patch compliance](compliance-about.md#compliance-monitor-patch).
## `AWS-RunPatchBaselineAssociation` parameters
`AWS-RunPatchBaselineAssociation` supports five parameters. The `Operation` and `AssociationId` parameters are required. The `InstallOverrideList`, `RebootOption`, and `BaselineTags` parameters are optional.
**Topics**
+ [Parameter name: `Operation`](#patch-manager-aws-runpatchbaselineassociation-parameters-operation)
+ [Parameter name: `BaselineTags`](#patch-manager-aws-runpatchbaselineassociation-parameters-baselinetags)
+ [Parameter name: `AssociationId`](#patch-manager-aws-runpatchbaselineassociation-parameters-association-id)
+ [Parameter name: `InstallOverrideList`](#patch-manager-aws-runpatchbaselineassociation-parameters-installoverridelist)
+ [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption)
### Parameter name: `Operation`
**Usage**: Required.
**Options**: `Scan` \$1 `Install`.
Scan
When you choose the `Scan` option, `AWS-RunPatchBaselineAssociation` determines the patch compliance state of the instance and reports this information back to Patch Manager. `Scan` doesn't prompt updates to be installed or instances to be rebooted. Instead, the operation identifies where updates are missing that are approved and applicable to the instance.
Install
When you choose the `Install` option, `AWS-RunPatchBaselineAssociation` attempts to install the approved and applicable updates that are missing from the instance. Patch compliance information generated as part of an `Install` operation doesn't list any missing updates, but might report updates that are in a failed state if the installation of the update didn't succeed for any reason. Whenever an update is installed on an instance, the instance is rebooted to ensure the update is both installed and active. (Exception: If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaselineAssociation` document, the instance isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption).)
If a patch specified by the baseline rules is installed *before* Patch Manager updates the instance, the system might not reboot as expected. This can happen when a patch is installed manually by a user or installed automatically by another program, such as the `unattended-upgrades` package on Ubuntu Server.
### Parameter name: `BaselineTags`
**Usage**: Optional.
`BaselineTags` is a unique tag key-value pair that you choose and assign to an individual custom patch baseline. You can specify one or more values for this parameter. Both of the following formats are valid:
`Key=tag-key,Values=tag-value`
`Key=tag-key,Values=tag-value1,tag-value2,tag-value3`
**Important**
Tag keys and values can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
The `BaselineTags` value is used by Patch Manager to ensure that a set of instances that are patched in a single operation all have the exact same set of approved patches. When the patching operation runs, Patch Manager checks to see if a patch baseline for the operating system type is tagged with the same key-value pair you specify for `BaselineTags`. If there is a match, this custom patch baseline is used. If there isn't a match, a patch baseline is identified according to any patch group specified for the patching operating. If there is none, the AWS managed predefined patch baseline for that operating system is used.
**Additional permission requirements**
If you use `AWS-RunPatchBaselineAssociation` in patching operations other than those set up using Quick Setup, and you want to use the optional `BaselineTags` parameter, you must add the following permissions to the [instance profile](setup-instance-permissions.md) for Amazon Elastic Compute Cloud (Amazon EC2) instances.
**Note**
Quick Setup and `AWS-RunPatchBaselineAssociation` don't support on-premises servers and virtual machines (VMs).
```
{
"Effect": "Allow",
"Action": [
"ssm:DescribePatchBaselines",
"tag:GetResources"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetPatchBaseline",
"ssm:DescribeEffectivePatchesForPatchBaseline"
],
"Resource": "patch-baseline-arn"
}
```
Replace *patch-baseline-arn* with the Amazon Resource Name (ARN) of the patch baseline to which you want to provide access, in the format `arn:aws:ssm:us-east-2:123456789012:patchbaseline/pb-0c10e65780EXAMPLE`.
### Parameter name: `AssociationId`
**Usage**: Required.
`AssociationId` is the ID of an existing association in State Manager, a tool in AWS Systems Manager. It's used by Patch Manager to add compliance data to a specified association. This association is related to a patch `Scan` operation enabled in a [Host Management configuration created in Quick Setup](quick-setup-host-management.md). By sending patching results as association compliance data instead of inventory compliance data, existing inventory compliance information for your instances isn't overwritten after a patching operation, nor for other association IDs. If you don't already have an association you want to use, you can create one by running [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) the command. For example:
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name "AWS-RunPatchBaselineAssociation" \
--association-name "MyPatchHostConfigAssociation" \
--targets "Key=instanceids,Values=[i-02573cafcfEXAMPLE,i-07782c72faEXAMPLE,i-07782c72faEXAMPLE]" \
--parameters "Operation=Scan" \
--schedule-expression "cron(0 */30 * * * ? *)" \
--sync-compliance "MANUAL" \
--region us-east-2
```
------
#### [ Windows Server ]
```
aws ssm create-association ^
--name "AWS-RunPatchBaselineAssociation" ^
--association-name "MyPatchHostConfigAssociation" ^
--targets "Key=instanceids,Values=[i-02573cafcfEXAMPLE,i-07782c72faEXAMPLE,i-07782c72faEXAMPLE]" ^
--parameters "Operation=Scan" ^
--schedule-expression "cron(0 */30 * * * ? *)" ^
--sync-compliance "MANUAL" ^
--region us-east-2
```
------
### Parameter name: `InstallOverrideList`
**Usage**: Optional.
Using `InstallOverrideList`, you specify an https URL or an Amazon Simple Storage Service (Amazon S3) path-style URL to a list of patches to be installed. This patch installation list, which you maintain in YAML format, overrides the patches specified by the current default patch baseline. This provides you with more granular control over which patches are installed on your instances.
**Important**
The `InstallOverrideList` file name can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
The patching operation behavior when using the `InstallOverrideList` parameter differs between Linux & macOS managed nodes and Windows Server managed nodes. On Linux & macOS, Patch Manager attempts to apply patches included in the `InstallOverrideList` patch list that are present in any repository enabled on the node, whether or not the patches match the patch baseline rules. On Windows Server nodes, however, patches in the `InstallOverrideList` patch list are applied *only* if they also match the patch baseline rules.
On Linux & macOS managed nodes, patches specified in the `InstallOverrideList` are applied only as updates to packages that are already installed on the node. If the `InstallOverrideList` includes patches for packages that are not currently installed on the node, those patches are not installed.
Be aware that compliance reports reflect patch states according to what’s specified in the patch baseline, not what you specify in an `InstallOverrideList` list of patches. In other words, Scan operations ignore the `InstallOverrideList` parameter. This is to ensure that compliance reports consistently reflect patch states according to policy rather than what was approved for a specific patching operation.
**Valid URL formats**
**Note**
If your file is stored in a publicly available bucket, you can specify either an https URL format or an Amazon S3 path-style URL. If your file is stored in a private bucket, you must specify an Amazon S3 path-style URL.
+ **https URL format example**:
```
https://s3.amazonaws.com/amzn-s3-demo-bucket/my-windows-override-list.yaml
```
+ **Amazon S3 path-style URL example**:
```
s3://amzn-s3-demo-bucket/my-windows-override-list.yaml
```
**Valid YAML content formats**
The formats you use to specify patches in your list depends on the operating system of your instance. The general format, however, is as follows:
```
patches:
-
id: '{patch-d}'
title: '{patch-title}'
{additional-fields}:{values}
```
Although you can provide additional fields in your YAML file, they're ignored during patch operations.
In addition, we recommend verifying that the format of your YAML file is valid before adding or updating the list in your S3 bucket. For more information about the YAML format, see [yaml.org](http://www.yaml.org). For validation tool options, perform a web search for "yaml format validators".
+ Microsoft Windows
**id**
The **id** field is required. Use it to specify patches using Microsoft Knowledge Base IDs (for example, KB2736693) and Microsoft Security Bulletin IDs (for example, MS17-023).
Any other fields you want to provide in a patch list for Windows are optional and are for your own informational use only. You can use additional fields such as **title**, **classification**, **severity**, or anything else for providing more detailed information about the specified patches.
+ Linux
**id**
The **id** field is required. Use it to specify patches using the package name and architecture. For example: `'dhclient.x86_64'`. You can use wildcards in id to indicate multiple packages. For example: `'dhcp*'` and `'dhcp*1.*'`.
**title**
The **title** field is optional, but on Linux systems it does provide additional filtering capabilities. If you use **title**, it should contain the package version information in the one of the following formats:
YUM/Red Hat Enterprise Linux (RHEL):
```
{name}.{architecture}:{epoch}:{version}-{release}
```
APT
```
{name}.{architecture}:{version}
```
For Linux patch titles, you can use one or more wildcards in any position to expand the number of package matches. For example: `'*32:9.8.2-0.*.rc1.57.amzn1'`.
For example:
+ apt package version 1.2.25 is currently installed on your instance, but version 1.2.27 is now available.
+ You add apt.amd64 version 1.2.27 to the patch list. It depends on apt utils.amd64 version 1.2.27, but apt-utils.amd64 version 1.2.25 is specified in the list.
In this case, apt version 1.2.27 will be blocked from installation and reported as “Failed-NonCompliant.”
**Other fields**
Any other fields you want to provide in a patch list for Linux are optional and are for your own informational use only. You can use additional fields such as **classification**, **severity**, or anything else for providing more detailed information about the specified patches.
**Sample patch lists**
+ **Windows**
```
patches:
-
id: 'KB4284819'
title: '2018-06 Cumulative Update for Windows Server 2016 (1709) for x64-based Systems (KB4284819)'
-
id: 'KB4284833'
-
id: 'KB4284835'
title: '2018-06 Cumulative Update for Windows Server 2016 (1803) for x64-based Systems (KB4284835)'
-
id: 'KB4284880'
-
id: 'KB4338814'
```
+ **APT**
```
patches:
-
id: 'apparmor.amd64'
title: '2.10.95-0ubuntu2.9'
-
id: 'cryptsetup.amd64'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'cryptsetup-bin.*'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'apt.amd64'
title: '*1.2.27'
-
id: 'apt-utils.amd64'
title: '*1.2.25'
```
+ **Amazon Linux 2**
```
patches:
-
id: 'kernel.x86_64'
-
id: 'bind*.x86_64'
title: '39.11.4-26.P2.amzn2.5.2'
id: 'glibc*'
-
id: 'dhclient*'
title: '*4.2.5-58.amzn2'
-
id: 'dhcp*'
title: '*4.2.5-77.amzn2'
```
+ **Red Hat Enterprise Linux (RHEL)**
```
patches:
-
id: 'NetworkManager.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'NetworkManager-*.x86_64'
title: '*1:1.10.2-14.el7_5'
-
id: 'audit.x86_64'
title: '*0:2.8.1-3.el7'
-
id: 'dhclient.x86_64'
title: '*.el7_5.1'
-
id: 'dhcp*.x86_64'
title: '*12:5.2.5-68.el7'
```
+ **SUSE Linux Enterprise Server (SLES)**
```
patches:
-
id: 'amazon-ssm-agent.x86_64'
-
id: 'binutils'
title: '*0:2.26.1-9.12.1'
-
id: 'glibc*.x86_64'
title: '*2.19*'
-
id: 'dhcp*'
title: '0:4.3.3-9.1'
-
id: 'lib*'
```
+ **Ubuntu Server **
```
patches:
-
id: 'apparmor.amd64'
title: '2.10.95-0ubuntu2.9'
-
id: 'cryptsetup.amd64'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'cryptsetup-bin.*'
title: '*2:1.6.6-5ubuntu2.1'
-
id: 'apt.amd64'
title: '*1.2.27'
-
id: 'apt-utils.amd64'
title: '*1.2.25'
```
+ **Windows**
```
patches:
-
id: 'KB4284819'
title: '2018-06 Cumulative Update for Windows Server 2016 (1709) for x64-based Systems (KB4284819)'
-
id: 'KB4284833'
-
id: 'KB4284835'
title: '2018-06 Cumulative Update for Windows Server 2016 (1803) for x64-based Systems (KB4284835)'
-
id: 'KB4284880'
-
id: 'KB4338814'
```
### Parameter name: `RebootOption`
**Usage**: Optional.
**Options**: `RebootIfNeeded` \$1 `NoReboot`
**Default**: `RebootIfNeeded`
**Warning**
The default option is `RebootIfNeeded`. Be sure to select the correct option for your use case. For example, if your instances must reboot immediately to complete a configuration process, choose `RebootIfNeeded`. Or, if you need to maintain instances availability until a scheduled reboot time, choose `NoReboot`.
**Important**
The `NoReboot` option only prevents operating system-level restarts. Service-level restarts can still occur as part of the patching process. For example, when Docker is updated, dependent services such as Amazon Elastic Container Service might automatically restart even with `NoReboot` enabled. If you have critical services that must not be disrupted, consider additional measures such as temporarily removing instances from service or scheduling patching during maintenance windows.
**Important**
We don’t recommend using Patch Manager for patching cluster instances in Amazon EMR (previously called Amazon Elastic MapReduce). In particular, don’t select the `RebootIfNeeded` option for the `RebootOption` parameter. (This option is available in the SSM Command documents for patching `AWS-RunPatchBaseline`, `AWS-RunPatchBaselineAssociation`, and `AWS-RunPatchBaselineWithHooks`.)
The underlying commands for patching using Patch Manager use `yum` and `dnf` commands. Therefore, the operations result in incompatibilities because of how packages are installed. For information about the preferred methods for updating software on Amazon EMR clusters, see [Using the default AMI for Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-default-ami.html) in the *Amazon EMR Management Guide*.
RebootIfNeeded
When you choose the `RebootIfNeeded` option, the instance is rebooted in either of the following cases:
+ Patch Manager installed one or more patches.
Patch Manager doesn't evaluate whether a reboot is *required* by the patch. The system is rebooted even if the patch doesn't require a reboot.
+ Patch Manager detects one or more patches with a status of `INSTALLED_PENDING_REBOOT` during the `Install` operation.
The `INSTALLED_PENDING_REBOOT` status can mean that the option `NoReboot` was selected the last time the `Install` operation was run, or that a patch was installed outside of Patch Manager since the last time the managed node was rebooted.
Rebooting instances in these two cases ensures that updated packages are flushed from memory and keeps patching and rebooting behavior consistent across all operating systems.
NoReboot
When you choose the `NoReboot` option, Patch Manager doesn't reboot an instance even if it installed patches during the `Install` operation. This option is useful if you know that your instances don't require rebooting after patches are applied, or you have applications or processes running on an instance that shouldn't be disrupted by a patching operation reboot. It's also useful when you want more control over the timing of instance reboots, such as by using a maintenance window.
**Patch installation tracking file**: To track patch installation, especially patches that have been installed since the last system reboot, Systems Manager maintains a file on the managed instance.
**Important**
Don't delete or modify the tracking file. If this file is deleted or corrupted, the patch compliance report for the instance is inaccurate. If this happens, reboot the instance and run a patch Scan operation to restore the file.
This tracking file is stored in the following locations on your managed instances:
+ Linux operating systems:
+ `/var/log/amazon/ssm/patch-configuration/patch-states-configuration.json`
+ `/var/log/amazon/ssm/patch-configuration/patch-inventory-from-last-operation.json`
+ Windows Server operating system:
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchStatesConfiguration.json`
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchInventoryFromLastOperation.json`
# SSM Command document for patching: `AWS-RunPatchBaselineWithHooks`
AWS Systems Manager supports `AWS-RunPatchBaselineWithHooks`, a Systems Manager document (SSM document) for Patch Manager, a tool in AWS Systems Manager. This SSM document performs patching operations on managed nodes for both security related and other types of updates.
`AWS-RunPatchBaselineWithHooks` differs from `AWS-RunPatchBaseline` in the following ways:
+ **A wrapper document** – `AWS-RunPatchBaselineWithHooks` is a wrapper for `AWS-RunPatchBaseline` and relies on `AWS-RunPatchBaseline` for some of its operations.
+ **The `Install` operation** – `AWS-RunPatchBaselineWithHooks` supports lifecycle hooks that run at designated points during managed node patching. Because patch installations sometimes require managed nodes to reboot, the patching operation is divided into two events, for a total of three hooks that support custom functionality. The first hook is before the `Install with NoReboot` operation. The second hook is after the `Install with NoReboot` operation. The third hook is available after the reboot of the managed node.
+ **No custom patch list support** – `AWS-RunPatchBaselineWithHooks` doesn't support the `InstallOverrideList` parameter.
+ **SSM Agent support** – `AWS-RunPatchBaselineWithHooks` requires that SSM Agent 3.0.502 or later be installed on the managed node to patch.
When the document is run, it uses the patch baseline currently specified as the "default" for an operating system type if no patch group is specified. Otherwise, it uses the patch baselines that is associated with the patch group. For information about patch groups, see [Patch groups](patch-manager-patch-groups.md).
You can use the document `AWS-RunPatchBaselineWithHooks` to apply patches for both operating systems and applications. (On Windows Server, application support is limited to updates for applications released by Microsoft.)
This document supports Linux and Windows Server managed nodes. The document will perform the appropriate actions for each platform.
**Note**
`AWS-RunPatchBaselineWithHooks` isn't supported on macOS.
------
#### [ Linux ]
On Linux managed nodes, the `AWS-RunPatchBaselineWithHooks` document invokes a Python module, which in turn downloads a snapshot of the patch baseline that applies to the managed node. This patch baseline snapshot uses the defined rules and lists of approved and blocked patches to drive the appropriate package manager for each node type:
+ Amazon Linux 2, Oracle Linux, and RHEL 7 managed nodes use YUM. For YUM operations, Patch Manager requires `Python 2.6` or a later supported version (2.6 - 3.12). Amazon Linux 2023 uses DNF. For DNF operations, Patch Manager requires a supported version of `Python 2` or `Python 3` (2.6 - 3.12).
+ RHEL 8 managed nodes use DNF. For DNF operations, Patch Manager requires a supported version of `Python 2` or `Python 3` (2.6 - 3.12). (Neither version is installed by default on RHEL 8. You must install one or the other manually.)
+ Debian Server and Ubuntu Server instances use APT. For APT operations, Patch Manager requires a supported version of `Python 3` (3.0 - 3.12).
------
#### [ Windows Server ]
On Windows Server managed nodes, the `AWS-RunPatchBaselineWithHooks` document downloads and invokes a PowerShell module, which in turn downloads a snapshot of the patch baseline that applies to the managed node. This patch baseline snapshot contains a list of approved patches that is compiled by querying the patch baseline against a Windows Server Update Services (WSUS) server. This list is passed to the Windows Update API, which controls downloading and installing the approved patches as appropriate.
------
Each snapshot is specific to an AWS account, patch group, operating system, and snapshot ID. The snapshot is delivered through a presigned Amazon Simple Storage Service (Amazon S3) URL, which expires 24 hours after the snapshot is created. After the URL expires, however, if you want to apply the same snapshot content to other managed nodes, you can generate a new presigned Amazon S3 URL up to three days after the snapshot was created. To do this, use the [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-deployable-patch-snapshot-for-instance.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-deployable-patch-snapshot-for-instance.html) command.
After all approved and applicable updates have been installed, with reboots performed as necessary, patch compliance information is generated on an managed node and reported back to Patch Manager.
If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaselineWithHooks` document, the managed node isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption).
**Important**
While the `NoReboot` option prevents operating system restarts, it does not prevent service-level restarts that might occur when certain packages are updated. For example, updating packages like Docker may trigger automatic restarts of dependent services (such as container orchestration services) even when `NoReboot` is specified.
For information about viewing patch compliance data, see [About patch compliance](compliance-about.md#compliance-monitor-patch).
## `AWS-RunPatchBaselineWithHooks` operational steps
When the `AWS-RunPatchBaselineWithHooks` runs, the following steps are performed:
1. **Scan** - A `Scan` operation using `AWS-RunPatchBaseline` is run on the managed node, and a compliance report is generated and uploaded.
1. **Verify local patch states** - A script is run to determine what steps will be performed based on the selected operation and `Scan` result from Step 1.
1. If the selected operation is `Scan`, the operation is marked complete. The operation concludes.
1. If the selected operation is `Install`, Patch Manager evaluates the `Scan` result from Step 1 to determine what to run next:
1. If no missing patches are detected, and no pending reboots required, the operation proceeds directly to the final step (Step 8), which includes a hook you have provided. Any steps in between are skipped.
1. If no missing patches are detected, but there are pending reboots required and the selected reboot option is `NoReboot`, the operation proceeds directly to the final step (Step 8), which includes a hook you have provided. Any steps in between are skipped.
1. Otherwise, the operation proceeds to the next step.
1. **Pre-patch hook operation** - The SSM document you have provided for the first lifecycle hook, `PreInstallHookDocName`, is run on the managed node.
1. **Install with NoReboot** - An `Install` operation with the reboot option of `NoReboot` using `AWS-RunPatchBaseline` is run on the managed node, and a compliance report is generated and uploaded.
1. **Post-install hook operation** - The SSM document you have provided for the second lifecycle hook, `PostInstallHookDocName`, is run on the managed node.
1. **Verify reboot** - A script runs to determine whether a reboot is needed for the managed node and what steps to run:
1. If the selected reboot option is `NoReboot`, the operation proceeds directly to the final step (Step 8), which includes a hook you have provided. Any steps in between are skipped.
1. If the selected reboot option is `RebootIfNeeded`, Patch Manager checks whether there are any pending reboots required from the inventory collected in Step 4. This means that the operation continues to Step 7 and the managed node is rebooted in either of the following cases:
1. Patch Manager installed one or more patches. (Patch Manager doesn't evaluate whether a reboot is required by the patch. The system is rebooted even if the patch doesn't require a reboot.)
1. Patch Manager detects one or more patches with a status of `INSTALLED_PENDING_REBOOT` during the Install operation. The `INSTALLED_PENDING_REBOOT` status can mean that the option `NoReboot` was selected the last time the Install operation was run, or that a patch was installed outside of Patch Manager since the last time the managed node was rebooted.
If no patches meeting these criteria are found, the managed node patching operation is complete, and the operation proceeds directly to the final step (Step 8), which includes a hook you have provided. Any steps in between are skipped.
1. **Reboot and report** - An installation operation with the reboot option of `RebootIfNeeded` runs on the managed node using `AWS-RunPatchBaseline`, and a compliance report is generated and uploaded.
1. **Post-reboot hook operation** - The SSM document you have provided for the third lifecycle hook, `OnExitHookDocName`, is run on the managed node.
For a `Scan` operation, if Step 1 fails, the process of running the document stops and the step is reported as failed, although subsequent steps are reported as successful.
For an `Install` operation, if any of the `aws:runDocument` steps fail during the operation, those steps are reported as failed, and the operation proceeds directly to the final step (Step 8), which includes a hook you have provided. Any steps in between are skipped. This step is reported as failed, the last step reports the status of its operation result, and all steps in between are reported as successful.
## `AWS-RunPatchBaselineWithHooks` parameters
`AWS-RunPatchBaselineWithHooks` supports six parameters.
The `Operation` parameter is required.
The `RebootOption`, `PreInstallHookDocName`, `PostInstallHookDocName`, and `OnExitHookDocName` parameters are optional.
`Snapshot-ID` is technically optional, but we recommend that you supply a custom value for it when you run `AWS-RunPatchBaselineWithHooks` outside of a maintenance window. Let Patch Manager supply the value automatically when the document is run as part of a maintenance window operation.
**Topics**
+ [Parameter name: `Operation`](#patch-manager-aws-runpatchbaseline-parameters-operation)
+ [Parameter name: `Snapshot ID`](#patch-manager-aws-runpatchbaselinewithhook-parameters-snapshot-id)
+ [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-norebootoption)
+ [Parameter name: `PreInstallHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-preinstallhookdocname)
+ [Parameter name: `PostInstallHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-postinstallhookdocname)
+ [Parameter name: `OnExitHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-onexithookdocname)
### Parameter name: `Operation`
**Usage**: Required.
**Options**: `Scan` \$1 `Install`.
Scan
When you choose the `Scan` option, the systems uses the `AWS-RunPatchBaseline` document to determine the patch compliance state of the managed node and reports this information back to Patch Manager. `Scan` doesn't prompt updates to be installed or managed nodes to be rebooted. Instead, the operation identifies where updates are missing that are approved and applicable to the node.
Install
When you choose the `Install` option, `AWS-RunPatchBaselineWithHooks` attempts to install the approved and applicable updates that are missing from the managed node. Patch compliance information generated as part of an `Install` operation doesn't list any missing updates, but might report updates that are in a failed state if the installation of the update didn't succeed for any reason. Whenever an update is installed on a managed node, the node is rebooted to ensure the update is both installed and active. (Exception: If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaselineWithHooks` document, the managed node isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-norebootoption).)
If a patch specified by the baseline rules is installed *before* Patch Manager updates the managed node, the system might not reboot as expected. This can happen when a patch is installed manually by a user or installed automatically by another program, such as the `unattended-upgrades` package on Ubuntu Server.
### Parameter name: `Snapshot ID`
**Usage**: Optional.
`Snapshot ID` is a unique ID (GUID) used by Patch Manager to ensure that a set of managed nodes that are patched in a single operation all have the exact same set of approved patches. Although the parameter is defined as optional, our best practice recommendation depends on whether or not you're running `AWS-RunPatchBaselineWithHooks` in a maintenance window, as described in the following table.
**`AWS-RunPatchBaselineWithHooks` best practices**
| Mode | Best practice | Details |
| --- | --- | --- |
| Running AWS-RunPatchBaselineWithHooks inside a maintenance window | Don't supply a Snapshot ID. Patch Manager will supply it for you. | If you use a maintenance window to run `AWS-RunPatchBaselineWithHooks`, you shouldn't provide your own generated Snapshot ID. In this scenario, Systems Manager provides a GUID value based on the maintenance window execution ID. This ensures that a correct ID is used for all the invocations of `AWS-RunPatchBaselineWithHooks` in that maintenance window. If you do specify a value in this scenario, note that the snapshot of the patch baseline might not remain in place for more than 3 days. After that, a new snapshot will be generated even if you specify the same ID after the snapshot expires. |
| Running AWS-RunPatchBaselineWithHooks outside of a maintenance window | Generate and specify a custom GUID value for the Snapshot ID.¹ | When you aren't using a maintenance window to run `AWS-RunPatchBaselineWithHooks`, we recommend that you generate and specify a unique Snapshot ID for each patch baseline, particularly if you're running the `AWS-RunPatchBaselineWithHooks` document on multiple managed nodes in the same operation. If you don't specify an ID in this scenario, Systems Manager generates a different Snapshot ID for each managed node the command is sent to. This might result in varying sets of patches being specified among the nodes. For instance, say that you're running the `AWS-RunPatchBaselineWithHooks` document directly through Run Command, a tool inAWS Systems Manager, and targeting a group of 50 managed nodes. Specifying a custom Snapshot ID results in the generation of a single baseline snapshot that is used to evaluate and patch all the managed nodes, ensuring that they end up in a consistent state. |
| ¹ You can use any tool capable of generating a GUID to generate a value for the Snapshot ID parameter. For example, in PowerShell, you can use the `New-Guid` cmdlet to generate a GUID in the format of `12345699-9405-4f69-bc5e-9315aEXAMPLE`. |
### Parameter name: `RebootOption`
**Usage**: Optional.
**Options**: `RebootIfNeeded` \$1 `NoReboot`
**Default**: `RebootIfNeeded`
**Warning**
The default option is `RebootIfNeeded`. Be sure to select the correct option for your use case. For example, if your managed nodes must reboot immediately to complete a configuration process, choose `RebootIfNeeded`. Or, if you need to maintain managed node availability until a scheduled reboot time, choose `NoReboot`.
**Important**
We don’t recommend using Patch Manager for patching cluster instances in Amazon EMR (previously called Amazon Elastic MapReduce). In particular, don’t select the `RebootIfNeeded` option for the `RebootOption` parameter. (This option is available in the SSM Command documents for patching `AWS-RunPatchBaseline`, `AWS-RunPatchBaselineAssociation`, and `AWS-RunPatchBaselineWithHooks`.)
The underlying commands for patching using Patch Manager use `yum` and `dnf` commands. Therefore, the operations result in incompatibilities because of how packages are installed. For information about the preferred methods for updating software on Amazon EMR clusters, see [Using the default AMI for Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-default-ami.html) in the *Amazon EMR Management Guide*.
RebootIfNeeded
When you choose the `RebootIfNeeded` option, the managed node is rebooted in either of the following cases:
+ Patch Manager installed one or more patches.
Patch Manager doesn't evaluate whether a reboot is *required* by the patch. The system is rebooted even if the patch doesn't require a reboot.
+ Patch Manager detects one or more patches with a status of `INSTALLED_PENDING_REBOOT` during the `Install` operation.
The `INSTALLED_PENDING_REBOOT` status can mean that the option `NoReboot` was selected the last time the `Install` operation was run, or that a patch was installed outside of Patch Manager since the last time the managed node was rebooted.
Rebooting managed nodes in these two cases ensures that updated packages are flushed from memory and keeps patching and rebooting behavior consistent across all operating systems.
NoReboot
When you choose the `NoReboot` option, Patch Manager doesn't reboot a managed node even if it installed patches during the `Install` operation. This option is useful if you know that your managed nodes don't require rebooting after patches are applied, or you have applications or processes running on a node that shouldn't be disrupted by a patching operation reboot. It's also useful when you want more control over the timing of managed node reboots, such as by using a maintenance window.
If you choose the `NoReboot` option and a patch is installed, the patch is assigned a status of `InstalledPendingReboot`. The managed node itself, however, is marked as `Non-Compliant`. After a reboot occurs and a `Scan` operation is run, the node status is updated to `Compliant`.
**Patch installation tracking file**: To track patch installation, especially patches that were installed since the last system reboot, Systems Manager maintains a file on the managed node.
**Important**
Don't delete or modify the tracking file. If this file is deleted or corrupted, the patch compliance report for the managed node is inaccurate. If this happens, reboot the node and run a patch Scan operation to restore the file.
This tracking file is stored in the following locations on your managed nodes:
+ Linux operating systems:
+ `/var/log/amazon/ssm/patch-configuration/patch-states-configuration.json`
+ `/var/log/amazon/ssm/patch-configuration/patch-inventory-from-last-operation.json`
+ Windows Server operating system:
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchStatesConfiguration.json`
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchInventoryFromLastOperation.json`
### Parameter name: `PreInstallHookDocName`
**Usage**: Optional.
**Default**: `AWS-Noop`.
The value to provide for the `PreInstallHookDocName` parameter is the name or Amazon Resource Name (ARN) of an SSM document of your choice. You can provide the name of an AWS managed document or the name or ARN of a custom SSM document that you have created or that has been shared with you. (For an SSM document that has been shared with you from a different AWS account, you must specify the full resource ARN, such as `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`.)
The SSM document you specify is run before the `Install` operation and performs any actions supported by SSM Agent, such as a shell script to check application health check before patching is performed on the managed node. (For a list of actions, see [Command document plugin reference](documents-command-ssm-plugin-reference.md)). The default SSM document name is `AWS-Noop`, which doesn't perform any operation on the managed node.
For information about creating a custom SSM document, see [Creating SSM document content](documents-creating-content.md).
### Parameter name: `PostInstallHookDocName`
**Usage**: Optional.
**Default**: `AWS-Noop`.
The value to provide for the `PostInstallHookDocName` parameter is the name or Amazon Resource Name (ARN) of an SSM document of your choice. You can provide the name of an AWS managed document or the name or ARN of a custom SSM document that you have created or that has been shared with you. (For an SSM document that has been shared with you from a different AWS account, you must specify the full resource ARN, such as `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`.)
The SSM document you specify is run after the `Install with NoReboot` operation and performs any actions supported by SSM Agent, such as a shell script for installing third party updates before reboot. (For a list of actions, see [Command document plugin reference](documents-command-ssm-plugin-reference.md)). The default SSM document name is `AWS-Noop`, which doesn't perform any operation on the managed node.
For information about creating a custom SSM document, see [Creating SSM document content](documents-creating-content.md).
### Parameter name: `OnExitHookDocName`
**Usage**: Optional.
**Default**: `AWS-Noop`.
The value to provide for the `OnExitHookDocName` parameter is the name or Amazon Resource Name (ARN) of an SSM document of your choice. You can provide the name of an AWS managed document or the name or ARN of a custom SSM document that you have created or that has been shared with you. (For an SSM document that has been shared with you from a different AWS account, you must specify the full resource ARN, such as `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`.)
The SSM document you specify is run after the managed node reboot operation and performs any actions supported by SSM Agent, such as a shell script to verify node health after the patching operation is complete. (For a list of actions, see [Command document plugin reference](documents-command-ssm-plugin-reference.md)). The default SSM document name is `AWS-Noop`, which doesn't perform any operation on the managed node.
For information about creating a custom SSM document, see [Creating SSM document content](documents-creating-content.md).
# Sample scenario for using the InstallOverrideList parameter in `AWS-RunPatchBaseline` or `AWS-RunPatchBaselineAssociation`
You can use the `InstallOverrideList` parameter when you want to override the patches specified by the current default patch baseline in Patch Manager, a tool in AWS Systems Manager. This topic provides examples that show how to use this parameter to achieve the following:
+ Apply different sets of patches to a target group of managed nodes.
+ Apply these patch sets on different frequencies.
+ Use the same patch baseline for both operations.
Say that you want to install two different categories of patches on your Amazon Linux 2 managed nodes. You want to install these patches on different schedules using maintenance windows. You want one maintenance window to run every week and install all `Security` patches. You want another maintenance window to run once a month and install all available patches, or categories of patches other than `Security`.
However, only one patch baseline at a time can be defined as the default for an operating system. This requirement helps avoid situations where one patch baseline approves a patch while another blocks it, which can lead to issues between conflicting versions.
With the following strategy, you use the `InstallOverrideList` parameter to apply different types of patches to a target group, on different schedules, while still using the same patch baseline:
1. In the default patch baseline, ensure that only `Security` updates are specified.
1. Create a maintenance window that runs `AWS-RunPatchBaseline` or `AWS-RunPatchBaselineAssociation` each week. Don't specify an override list.
1. Create an override list of the patches of all types that you want to apply on a monthly basis and store it in an Amazon Simple Storage Service (Amazon S3) bucket.
1. Create a second maintenance window that runs once a month. However, for the Run Command task you register for this maintenance window, specify the location of your override list.
The result: Only `Security` patches, as defined in your default patch baseline, are installed each week. All available patches, or whatever subset of patches you define, are installed each month.
**Note**
When you're patching a node that only uses IPv6, ensure that the provided URL is reachable from the node. If the SSM Agent config option `UseDualStackEndpoint` is set to `true`, then a dualstack S3 client is used when an S3 URL is provided. See [Tutorial: Patching a server in an IPv6 only environment](patch-manager-server-patching-iPv6-tutorial.md) for more information on configuring the agent to use dualstack.
For more information and sample lists, see [Parameter name: `InstallOverrideList`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-installoverridelist).
# Using the BaselineOverride parameter
You can define patching preferences at runtime using the baseline override feature in Patch Manager, a tool in AWS Systems Manager. Do this by specifying an Amazon Simple Storage Service (Amazon S3) bucket containing a JSON object with a list of patch baselines. The patching operation uses the baselines provided in the JSON object that match the host operating system instead of applying the rules from the default patch baseline.
**Important**
The `BaselineOverride` file name can't contain the following characters: backtick (`), single quote ('), double quote ("), and dollar sign (\$1).
Except when a patching operation uses a patch policy, using the `BaselineOverride` parameter doesn't overwrite the patch compliance of the baseline provided in the parameter. The output results are recorded in the Stdout logs from Run Command, a tool in AWS Systems Manager. The results only print out packages that are marked as `NON_COMPLIANT`. This means the package is marked as `Missing`, `Failed`, `InstalledRejected`, or `InstalledPendingReboot`.
When a patch operation uses a patch policy, however, the system passes the override parameter from the associated S3 bucket, and the compliance value is updated for the managed node. For more information about patch policy behaviors, see [Patch policy configurations in Quick Setup](patch-manager-policies.md).
**Note**
When you're patching a node that only uses IPv6, ensure that the provided URL is reachable from the node. If the SSM Agent config option `UseDualStackEndpoint` is set to `true`, then a dualstack S3 client is used when an S3 URL is provided. See [Tutorial: Patching a server in an IPv6 only environment](patch-manager-server-patching-iPv6-tutorial.md) for more information on configuring the agent to use dualstack.
## Using the patch baseline override with Snapshot Id or Install Override List parameters
There are two cases where the patch baseline override has noteworthy behavior.
**Using baseline override and Snapshot Id at the same time**
Snapshot Ids ensure that all managed nodes in a particular patching command all apply the same thing. For example, if you patch 1,000 nodes at one time, the patches will be the same.
When using both a Snapshot Id and a patch baseline override, the Snapshot Id takes precedence over the patch baseline override. The baseline override rules will still be used, but they will only be evaluated once. In the earlier example, the patches across your 1,000 managed nodes will still always be the same. If, midway through the patching operation, you changed the JSON file in the referenced S3 bucket to be something different, the patches applied will still be the same. This is because the Snapshot Id was provided.
**Using baseline override and Install Override List at the same time**
You can't use these two parameters at the same time. The patching document fails if both parameters are supplied, and it doesn't perform any scans or installs on the managed node.
## Code examples
The following code example for Python shows how to generate the patch baseline override.
```
import boto3
import json
ssm = boto3.client('ssm')
s3 = boto3.resource('s3')
s3_bucket_name = 'my-baseline-override-bucket'
s3_file_name = 'MyBaselineOverride.json'
baseline_ids_to_export = ['pb-0000000000000000', 'pb-0000000000000001']
baseline_overrides = []
for baseline_id in baseline_ids_to_export:
baseline_overrides.append(ssm.get_patch_baseline(
BaselineId=baseline_id
))
json_content = json.dumps(baseline_overrides, indent=4, sort_keys=True, default=str)
s3.Object(bucket_name=s3_bucket_name, key=s3_file_name).put(Body=json_content)
```
This produces a patch baseline override like the following.
```
[
{
"ApprovalRules": {
"PatchRules": [
{
"ApproveAfterDays": 0,
"ComplianceLevel": "UNSPECIFIED",
"EnableNonSecurity": false,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"*"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"*"
]
},
{
"Key": "SEVERITY",
"Values": [
"*"
]
}
]
}
}
]
},
"ApprovedPatches": [],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"GlobalFilters": {
"PatchFilters": []
},
"OperatingSystem": "AMAZON_LINUX_2",
"RejectedPatches": [],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"Sources": []
},
{
"ApprovalRules": {
"PatchRules": [
{
"ApproveUntilDate": "2021-01-06",
"ComplianceLevel": "UNSPECIFIED",
"EnableNonSecurity": true,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"*"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"*"
]
},
{
"Key": "SEVERITY",
"Values": [
"*"
]
}
]
}
}
]
},
"ApprovedPatches": [
"open-ssl*"
],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"GlobalFilters": {
"PatchFilters": []
},
"OperatingSystem": "SUSE",
"RejectedPatches": [
"python*"
],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"Sources": []
}
]
```