SSM Command document for patching: AWS-RunPatchBaseline

AWS Systems Manager supports AWS-RunPatchBaseline, a Systems Manager document (SSM document) for Patch Manager, a capability of 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.

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.

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 1, Amazon Linux 2, CentOS, 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.10).

• RHEL 8 managed nodes use DNF. For DNF operations, Patch Manager requires a supported version of Python 2 or Python 3 (2.6 - 3.10). (Neither version is installed by default on RHEL 8. You must install one or the other manually.)

• Debian Server, Raspberry Pi OS, and Ubuntu Server instances use APT. For APT operations, Patch Manager requires a supported version of Python 3 (3.0 - 3.10).

• SUSE Linux Enterprise Server managed nodes use Zypper. For Zypper operations, Patch Manager requires Python 2.6 or a later supported version (2.6 - 3.10).

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 get-deployable-patch-snapshot-for-instance 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.

For information about viewing patch compliance data, see About patch compliance.

AWS-RunPatchBaseline parameters

AWS-RunPatchBaseline supports five 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.

Parameter name: Operation

Usage: Required.

Options: Scan | Install.

Parameter name: AssociationId

Usage: Optional.

AssociationId is the ID of an existing association in State Manager, a capability of 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.

If you don't already have an association you want to use, you can create one by running create-association 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.

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.

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.

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.

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.

Valid URL formats

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. 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 {package_name} format.

Sample patch lists

Parameter name: RebootOption

Usage: Optional.

Options: RebootIfNeeded | NoReboot

Default: RebootIfNeeded

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.

This tracking file is stored in the following locations on your managed nodes:

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

For more information about how to use the BaselineOverride parameter, see Using the BaselineOverride parameter.