SSM Command document
for patching: AWS-RunPatchBaselineWithHooks
Amazon Systems Manager supports AWS-RunPatchBaselineWithHooks
, a Systems Manager document
(SSM document) for Patch Manager, a capability of Amazon 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 forAWS-RunPatchBaseline
and relies onAWS-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 theInstall with NoReboot
operation. The second hook is after theInstall 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 theInstallOverrideList
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.
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.
Each snapshot is specific to an Amazon Web Services 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 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 an managed node and reported back to Patch Manager.
Note
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.
For information about viewing patch compliance data, see About patch compliance.
AWS-RunPatchBaselineWithHooks
operational steps
When the AWS-RunPatchBaselineWithHooks
runs, the following steps
are performed:
-
Scan - A
Scan
operation usingAWS-RunPatchBaseline
is run on the managed node, and a compliance report is generated and uploaded. -
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.-
If the selected operation is
Scan
, the operation is marked complete. The operation concludes. -
If the selected operation is
Install
, Patch Manager evaluates theScan
result from Step 1 to determine what to run next:-
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.
-
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. -
Otherwise, the operation proceeds to the next step.
-
-
-
Pre-patch hook operation - The SSM document you have provided for the first lifecycle hook,
PreInstallHookDocName
, is run on the managed node. -
Install with NoReboot - An
Install
operation with the reboot option ofNoReboot
usingAWS-RunPatchBaseline
is run on the managed node, and a compliance report is generated and uploaded. -
Post-install hook operation - The SSM document you have provided for the second lifecycle hook,
PostInstallHookDocName
, is run on the managed node. -
Verify reboot - A script runs to determine whether a reboot is needed for the managed node and what steps to run:
-
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. -
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:-
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. TheINSTALLED_PENDING_REBOOT
status can mean that the optionNoReboot
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.
-
-
-
Reboot and report - An installation operation with the reboot option of
RebootIfNeeded
runs on the managed node usingAWS-RunPatchBaseline
, and a compliance report is generated and uploaded. -
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.
Parameters
Parameter name: Operation
Usage: Required.
Options: Scan
|
Install
.
- Scan
-
When you choose the
Scan
option, the systems uses theAWS-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 anInstall
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 theRebootOption
parameter is set toNoReboot
in theAWS-RunPatchBaselineWithHooks
document, the managed node isn't rebooted after Patch Manager runs. For more information, see Parameter name: RebootOption.)Note
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
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
For instance, say that you're running the
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
¹ 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
|
Parameter name: RebootOption
Usage: Optional.
Options: RebootIfNeeded
|
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 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 theInstall
operation.The
INSTALLED_PENDING_REBOOT
status can mean that the optionNoReboot
was selected the last time theInstall
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 theInstall
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.Note
If you choose the
NoReboot
option and a patch is installed, the patch is assigned a status ofInstalledPendingReboot
. The managed node itself, however, is marked asNon-Compliant
. After a reboot occurs and aScan
operation is run, the node status is updated toCompliant
.
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 Amazon 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 Amazon Web Services 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). 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.
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 Amazon 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 Amazon Web Services 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). 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.
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 Amazon 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
Amazon Web Services 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). 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.