• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# 用于修补的 SSM 命令文档：`AWS-RunPatchBaselineWithHooks`
AWS Systems Manager 支持 `AWS-RunPatchBaselineWithHooks`，这是Patch Manager（AWS Systems Manager 中的一项工具）的 Systems Manager 文档（SSM 文档）。此 SSM 文档在托管式节点上为安全性相关更新和其他类型的更新执行修补操作。
`AWS-RunPatchBaselineWithHooks` 与 `AWS-RunPatchBaseline` 存在以下差异：
+ **包装文档**– `AWS-RunPatchBaselineWithHooks` 是 `AWS-RunPatchBaseline` 的包装器并依赖 `AWS-RunPatchBaseline` 进行一些操作。
+ **`Install` 操作** – `AWS-RunPatchBaselineWithHooks` 支持托管式节点修补期间在指定点运行的生命周期钩子。由于补丁安装有时需要重启托管式节点，修补操作分为两个事件，共有三个支持自定义功能的钩子。第一个钩子先于 `Install with NoReboot` 操作。第二个钩子后于 `Install with NoReboot` 操作。托管式节点重启后，即可使用第三个钩子。
+ **不支持自定义补丁列表**– `AWS-RunPatchBaselineWithHooks` 不支持 `InstallOverrideList` 参数。
+ **SSM Agent 支持** – `AWS-RunPatchBaselineWithHooks` 要求 SSM Agent 3.0.502 或更高版本需安装在托管式节点上才能进行修补。
运行文档时，如果未指定补丁组，则使用当前指定为操作系统类型的 “默认” 补丁基准。否则，它将使用与补丁组关联的补丁基准。有关补丁组的更多信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
您可以使用文档 `AWS-RunPatchBaselineWithHooks` 为操作系统和应用程序应用补丁。（在 Windows Server 上，应用程序支持仅限于更新 Microsoft 发布的应用程序。）
本文档支持 Linux 和 Windows Server 托管式节点。此文档将为每个平台执行适当的操作。
**注意**
`AWS-RunPatchBaselineWithHooks` 在 macOS 上不受支持。
------
#### [ Linux ]
在 Linux 托管式节点上，`AWS-RunPatchBaselineWithHooks` 文档调用 Python 模块，然后该模块下载适用于托管式节点的补丁基准快照。此补丁基准快照使用已定义规则及已批准和已阻止补丁列表驱动每个节点类型相应的软件包管理器：
+ Amazon Linux 2、Oracle Linux 和 RHEL 7 托管节点使用 YUM。对于 YUM 操作，Patch Manager 需要使用 `Python 2.6` 或受支持的更高版本（2.6 – 3.12）。Amazon Linux 2023 使用 DNF。对于 DNF 操作，Patch Manager 需要使用受支持版本的 `Python 2` 或 `Python 3`（2.6 – 3.12）。
+ RHEL 8 托管式节点使用 DNF。对于 DNF 操作，Patch Manager 需要使用受支持版本的 `Python 2` 或 `Python 3`（2.6 – 3.12）。（默认情况下，RHEL 8 上不安装其中任一版本。您必须手动安装其中一个版本。）
+ Debian Server 和 Ubuntu Server 实例使用 APT。对于 APT 操作，Patch Manager 需要使用受支持版本的 `Python 3`（3.0 – 3.12）。
------
#### [ Windows Server ]
在 Windows Server 托管式节点上，`AWS-RunPatchBaselineWithHooks` 文档下载并调用 PowerShell 模块，然后该模块下载适用于托管式节点的补丁基准快照。此补丁基准快照包含已批准的补丁列表，这些补丁通过查询 Windows 服务器更新服务 (WSUS) 服务器的补丁基准进行编译。将此列表传递给 Windows Update API，Windows Update API 控制相应的已批准补丁的下载和安装。
------
每个快照都特定于一个 AWS 账户、补丁组、操作系统和快照 ID。快照通过预签名的 Amazon Simple Storage Service (Amazon S3) URL 传送，该 URL 在快照创建 24 小时后过期。但是，在 URL 过期后，如果要将相同的快照内容应用于其他托管式节点，您可以在创建快照后最久三天内生成新的预签名 Amazon S3 URL。为此，请使用 [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) 命令。
安装完所有已批准和适用的更新后，根据需要执行重启，然后在托管式节点上生成补丁合规性信息，并向 Patch Manager 报告。
如果在 `AWS-RunPatchBaselineWithHooks` 文档中将 `RebootOption` 参数设置为 `NoReboot`，在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。
**重要**
尽管 `NoReboot` 选项可以阻止操作系统重启，但无法阻止某些软件包更新时可能发生的服务级别重启。例如，在更新 Docker 等软件包时，即使已指定 `NoReboot`，仍可能会自动重启依赖服务（例如容器编排服务）。
有关查看补丁合规性数据的信息，请参阅 [关于补丁合规性](compliance-about.md#compliance-monitor-patch)。
## `AWS-RunPatchBaselineWithHooks` 操作步骤
当 `AWS-RunPatchBaselineWithHooks` 运行时，将执行以下步骤：
1. **扫描** - `Scan` 操作使用 `AWS-RunPatchBaseline` 在托管式节点上运行，并生成和上传合规性报告。
1. **验证本地补丁状态** - 运行脚本以确定根据所选操作和步骤 1 的 `Scan` 结果将执行哪些步骤。
1. 如果选定的操作为 `Scan`，则操作将被标记为完成。操作结束。
1. 如果选定的 操作为 `Install`，则 Patch Manager 评估步骤1的 `Scan` 结果，以确定接下来要运行的内容：
1. 如果未检测到缺少的补丁，并且不需要暂挂重启，则操作直接进行到最后一步（步骤 8），其中包括您提供的钩子。跳过两者之间的任何步骤。
1. 如果未检测到缺少补丁，但需要挂起重新引导，并且选定的重启选项为 `NoReboot`，则操作直接进行到最后一步（步骤 8），其中包括您提供的钩子。跳过两者之间的任何步骤。
1. 否则，操作将继续下一步。
1. **预修补钩子操作** – 为第一个生命周期钩子提供的 SSM 文档 `PreInstallHookDocName` 在托管式节点上运行。
1. **使用 NoReboot 安装** – `Install` 操作，重启选项为 `NoReboot`，使用 `AWS-RunPatchBaseline` 在托管式节点上运行，生成并上传合规性报告。
1. **安装后钩子操作** – 为第二个生命周期钩子提供的 SSM 文档 `PostInstallHookDocName` 在托管式节点上运行。
1. **验证重启** – 运行脚本以确定托管式节点是否需要重启以及要运行哪些步骤：
1. 如果选定的重启选项为 `NoReboot`，则操作直接进行到最后一步（步骤 8），其中包括您提供的钩子。跳过两者之间的任何步骤。
1. 如果选定的重启选项为 `RebootIfNeeded`、Patch Manager 检查是否需要在步骤 4 中收集的库存中进行任何暂挂重启。这意味着在以下任一情况下，操作会继续执行步骤 7，并且托管式节点将重新启动：
1. Patch Manager 安装了一个或多个补丁。（Patch Manager 不会评估补丁是否需要重启系统。即使补丁不需要重启，系统也会重启。）
1. 在安装操作期间，Patch Manager 检测到一个或多个状态为 `INSTALLED_PENDING_REBOOT` 的补丁。`INSTALLED_PENDING_REBOOT` 状态可能表示上次运行安装操作时选择了选项 `NoReboot`，或者是自上次重新启动托管式节点以来在 Patch Manager 外部安装了补丁。
如果未找到符合标准的补丁，则托管式节点修补操作完成，操作直接进入最后一个步骤（步骤 8），该步骤包含您提供的挂钩。跳过两者之间的任何步骤。
1. **重启并报告** – 带有重启选项 `RebootIfNeeded` 的安装操作，使用 `AWS-RunPatchBaseline` 在托管式节点上运行，生成并上传合规性报告。
1. **重启后钩子操作** – 为第三个生命周期钩子提供的 SSM 文档 `OnExitHookDocName` 在托管式节点上运行。
对于 `Scan` 操作，如果步骤 1 失败，则运行文档的进程将停止，并将该步骤报告为失败，尽管后续步骤报告为成功。
对于 `Install` 操作，如果任一 `aws:runDocument` 步骤在操作期间失败，则这些步骤将被报告为失败，操作直接进行到最后一步（步骤 8），其中包括您提供的钩子。跳过两者之间的任何步骤。此步骤被报告为失败，最后一步报告其操作结果的状态，其间的所有步骤均报告为成功。
## `AWS-RunPatchBaselineWithHooks` 参数
`AWS-RunPatchBaselineWithHooks` 支持六个参数。
`Operation` 参数是必需的。
`RebootOption`、 `PreInstallHookDocName`、 `PostInstallHookDocName` 和 `OnExitHookDocName` 参数可选。
`Snapshot-ID` 在技术上是可选的，但是我们建议您在维护时段以外运行 `AWS-RunPatchBaselineWithHooks` 时为其提供自定义值。让 Patch Manager 在维护时段操作期间运行文档时自动提供值。
**Topics**
+ [参数名称: `Operation`](#patch-manager-aws-runpatchbaseline-parameters-operation)
+ [参数名称: `Snapshot ID`](#patch-manager-aws-runpatchbaselinewithhook-parameters-snapshot-id)
+ [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-norebootoption)
+ [参数名称: `PreInstallHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-preinstallhookdocname)
+ [参数名称: `PostInstallHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-postinstallhookdocname)
+ [参数名称: `OnExitHookDocName`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-onexithookdocname)
### 参数名称: `Operation`
**用法**：必需。
**选项**：`Scan` \$1 `Install`。
Scan
选择 `Scan` 选项时，系统使用 `AWS-RunPatchBaseline` 文档确定托管式节点的补丁合规性状态并向 Patch Manager 报告此信息。`Scan` 不提示要安装的更新或要重启的托管式节点。相反，该操作会标识哪些地方缺少已批准并且适用于节点的更新。
安装
选择 `Install` 选项时，`AWS-RunPatchBaselineWithHooks` 会尝试安装托管式节点中缺失并已批准的适用更新。在 `Install` 操作中生成的补丁合规性信息不会列出任何缺失的更新。但是，如果更新的安装因任何原因失败，它会报告处于失败状态的更新。一旦在托管式节点上安装了更新，就一定会重启节点，以确保正常安装和激活更新。（例外：如果将 `AWS-RunPatchBaselineWithHooks` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaselinewithhooks-parameters-norebootoption)。）
如果在 Patch Manager 更新托管式节点*之前*安装了基准规则指定的补丁，则系统可能无法按预期重启。当补丁是由用户手动安装或由其他程序（例如 Ubuntu Server 上的 `unattended-upgrades` 程序包）自动安装时，可能会发生这种情况。
### 参数名称: `Snapshot ID`
**用法**：可选。
`Snapshot ID` 是 Patch Manager 使用的唯一 ID (GUID)，用于确保在单一操作中修补的一组托管式节点均具有完全相同的一组已批准补丁。尽管它定义为可选参数，根据是否在维护时段中运行 `AWS-RunPatchBaselineWithHooks`，我们还是提供了不同的最佳实践建议，如下表所述。
**`AWS-RunPatchBaselineWithHooks` 最佳实践**
| Mode | 最佳实践 | Details |
| --- | --- | --- |
| 正在维护时段内运行 AWS-RunPatchBaselineWithHooks | 不要提供快照 ID，Patch Manager 将为您提供。 | 如果使用维护时段运行 `AWS-RunPatchBaselineWithHooks`，则不应提供自己生成的快照 ID。这种情况下，Systems Manager 基于维护时段执行 ID 提供 GUID 值。这可确保在维护时段中为 `AWS-RunPatchBaselineWithHooks` 的所有调用使用正确的 ID。 如果在这种情况下您指定值，请注意，补丁基准的快照最多保留 3 天。之后，即使您在快照到期后指定相同的 ID，也将生成新的快照。 |
| 正在在维护时段以外运行 AWS-RunPatchBaselineWithHooks | 为快照 ID¹ 生成和指定自定义 GUID 值。 | 如果您不使用维护时段运行 `AWS-RunPatchBaselineWithHooks`，我们建议您为每个补丁基准生成并指定一个唯一的快照 ID，特别是于同一操作中在多个托管式节点上运行 `AWS-RunPatchBaselineWithHooks` 文档时。如果在这种情况下不指定 ID，Systems Manager 会为向其发送命令的每个托管式节点生成不同的快照 ID。这会导致在节点间指定不同的补丁集。 例如，假设您正在直接通过 Run Command（AWS Systems Manager 中的一项工具）运行 `AWS-RunPatchBaselineWithHooks` 文档，并以一组 50 个的托管式节点为目标。指定自定义快照 ID 将生成单一基准快照，用于评估和修补所有托管式节点，从而确保所有托管式节点最终处于一致状态。 |
| ¹ 您可以使用任何能够生成 GUID 的工具为快照 ID 参数生成值。例如，在 PowerShell 中，可以使用 `New-Guid` cmdlet 生成格式为 `12345699-9405-4f69-bc5e-9315aEXAMPLE` 的 GUID。 |
### 参数名称: `RebootOption`
**用法**：可选。
**选项**：`RebootIfNeeded` \$1 `NoReboot`
**默认值**：`RebootIfNeeded`
**警告**
默认选项是 `RebootIfNeeded`。务必为应用场景选择正确的选项。例如，如果您的托管式节点必须立即重启才能完成配置过程，请选择 `RebootIfNeeded`。或者，如果您需要在计划的重启时间之前保持托管式节点可用，请选择 `NoReboot`。
**重要**
我们不建议使用 Patch Manager 在 Amazon EMR（原 Amazon Elastic MapReduce）中修补集群实例。特别是，不要为 `RebootOption` 参数选择 `RebootIfNeeded` 选项。（此选项在 SSM 命令文档中可用，用于修补 `AWS-RunPatchBaseline`、`AWS-RunPatchBaselineAssociation` 和 `AWS-RunPatchBaselineWithHooks`。）
使用 Patch Manager 进行修补的底层命令使用 `yum` 和 `dnf` 命令。因此，由于软件包的安装方式，这些操作会导致不兼容。有关在 Amazon EMR 集群上更新软件的首选方法的信息，请参阅《Amazon EMR Management Guide》**中的 [Using the default AMI for Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-default-ami.html)。
RebootIfNeeded
选择 `RebootIfNeeded` 选项时，托管式节点将在以下任一情况下重启：
+ Patch Manager 已安装一个或多个补丁。
Patch Manager 不评估补丁是否*必需*重启。即使补丁不需要重启，系统也会重启。
+ Patch Manager 检测 `Install` 操作期间的一个或多个状态为 `INSTALLED_PENDING_REBOOT` 的补丁。
`INSTALLED_PENDING_REBOOT` 状态可能表示在上次运行 `Install` 操作时选择了选项 `NoReboot`，或者是自上次重新启动托管式节点以来在 Patch Manager 外部安装了补丁。
在这两种情况下重启托管式节点，可确保从内存中刷新更新的软件包，并在所有操作系统中保持修补和重启行为一致。
NoReboot
选择 `NoReboot` 选项时，即使托管式节点在 `Install` 操作期间安装了补丁，Patch Manager 也不会重启托管式节点。如果您知道托管式节点在应用补丁后不需要重启，或者应用程序或进程在节点上运行，但不应因修补操作重启而中断，则此选项有用。当您希望更多地控制托管式节点的重启时间（例如，使用维护时段来控制）时，该选项也很有用。
如果选择 `NoReboot` 选项并安装了补丁，则会为该补丁分配状态 `InstalledPendingReboot`。但托管式节点本身将被标记为 `Non-Compliant`。重启并运行 `Scan` 操作后，节点状态将更新为 `Compliant`。
**补丁安装跟踪文件**：为跟踪补丁安装，特别是自上次系统重启以来安装的补丁，Systems Manager 会在托管式节点上维护一个文件。
**重要**
请勿删除或修改该跟踪文件。如果删除或损坏此文件，托管式节点的补丁合规性报告则不准确。如果发生这种情况，请重启节点并运行补丁扫描操作以还原此文件。
此跟踪文件存储在托管式节点上的以下位置：
+ Linux 操作系统：
+ `/var/log/amazon/ssm/patch-configuration/patch-states-configuration.json`
+ `/var/log/amazon/ssm/patch-configuration/patch-inventory-from-last-operation.json`
+ Windows Server 操作系统:
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchStatesConfiguration.json`
+ `C:\ProgramData\Amazon\PatchBaselineOperations\State\PatchInventoryFromLastOperation.json`
### 参数名称: `PreInstallHookDocName`
**用法**：可选。
**默认值**：`AWS-Noop`。
要提供的值 `PreInstallHookDocName` 参数是您选择的 SSM 文档的名称或 Amazon Resource Name (ARN)。您可以在中提供 AWS 托管文档的名称，或者您已创建或已与您共享的自定义 SSM 文档的名称或 ARN。（对于来自不同的 AWS 账户 的已与您共享的 SSM 文档，则必须指定完整的资源 ARN，例如 `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`。）
指定的 SSM 文档在 `Install` 操作之前运行并执行 SSM Agent 支持的任何操作，例如，在托管式节点上执行修补之前检查应用程序运行状况检查的 shell 脚本。（有关操作列表，请参阅 [命令文档插件参考](documents-command-ssm-plugin-reference.md)）。默认 SSM 文档名称为 `AWS-Noop`，不会对托管式节点执行任何操作。
有关创建自定义 SSM 文档的信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。
### 参数名称: `PostInstallHookDocName`
**用法**：可选。
**默认值**：`AWS-Noop`。
要提供的值 `PostInstallHookDocName` 参数是您选择的 SSM 文档的名称或 Amazon Resource Name (ARN)。您可以在中提供 AWS 托管文档的名称，或者您已创建或已与您共享的自定义 SSM 文档的名称或 ARN。（对于来自不同 AWS 账户 的已与您共享的 SSM 文档，必须指定完整资源 ARN，例如 `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`。）
在 `Install with NoReboot` 操作之后运行您指定的 SSM 文档，并执行 SSM Agent 支持的任一操作，例如，用于在重启之前安装第三方更新的 shell 脚本。（有关操作列表，请参阅 [命令文档插件参考](documents-command-ssm-plugin-reference.md)）。默认 SSM 文档名称为 `AWS-Noop`，不会对托管式节点执行任何操作。
有关创建自定义 SSM 文档的信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。
### 参数名称: `OnExitHookDocName`
**用法**：可选。
**默认值**：`AWS-Noop`。
要提供的值 `OnExitHookDocName` 参数是您选择的 SSM 文档的名称或 Amazon Resource Name (ARN)。您可以在中提供 AWS 托管文档的名称，或者您已创建或已与您共享的自定义 SSM 文档的名称或 ARN。（对于来自不同的 AWS 账户 的已与您共享的 SSM 文档，则必须指定完整的资源 ARN，例如 `arn:aws:ssm:us-east-2:123456789012:document/MySharedDocument`。）
指定的 SSM 文档在托管式节点重启操作后运行并执行 SSM Agent 支持的任何操作，例如，在修补操作完成后验证节点运行状况的 shell 脚本。（有关操作列表，请参阅 [命令文档插件参考](documents-command-ssm-plugin-reference.md)）。默认 SSM 文档名称为 `AWS-Noop`，不会对托管式节点执行任何操作。
有关创建自定义 SSM 文档的信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。