用于修补的 SSM 命令文档：AWS-RunPatchBaseline - Amazon Systems Manager
AWS-RunPatchBaseline 参数
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

用于修补的 SSM 命令文档：AWS-RunPatchBaseline

Amazon Systems Manager 支持 AWS-RunPatchBaseline，这是Patch Manager（Amazon Systems Manager 中的一项工具）的 Systems Manager 文档（SSM 文档）。此 SSM 文档在托管式节点上为安全性相关更新和其他类型的更新执行修补操作。运行文档时，如果未指定补丁组，则使用为操作系统类型指定的“默认”的补丁基准。否则，它将使用与补丁组关联的补丁基准。有关补丁组的信息，请参阅 补丁组。

您可以使用文档 AWS-RunPatchBaseline 为操作系统和应用程序应用补丁。（在 Windows Server 上，应用程序支持仅限于更新 Microsoft 发布的应用程序。）

本文档支持 Linux、macOS和 Windows Server 托管式节点。此文档将为每个平台执行适当的操作。

注意

Patch Manager 还支持传统 SSM 文档 AWS-ApplyPatchBaseline。但是，此文档仅支持在 Windows 托管式节点上进行修补。建议改用 AWS-RunPatchBaseline，因为其同时支持在 Linux、macOS 和 Windows Server 托管式节点上进行修补。要使用 AWS-RunPatchBaseline 文档，需要版本 2.0.834.0 或 SSM Agent 的更高版本。

Windows Server

在 Windows Server 托管式节点上，AWS-RunPatchBaseline 文档下载并调用 PowerShell 模块，然后该模块下载适用于托管式节点的补丁基准快照。此补丁基准快照包含已批准的补丁列表，这些补丁通过查询 Windows 服务器更新服务 (WSUS) 服务器的补丁基准进行编译。将此列表传递给 Windows Update API，Windows Update API 根据需要控制已批准的补丁的下载和安装。

Linux

在 Linux 托管式节点上，AWS-RunPatchBaseline 文档调用 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）。

macOS

在 macOS 托管式节点上，AWS-RunPatchBaseline 文档调用 Python 模块，然后该模块下载适用于托管式节点的补丁基准快照。接下来，Python 子进程在节点上调用 Amazon Command Line Interface (Amazon CLI），以检索指定软件包管理器的安装和更新信息，并为每个更新软件包驱动适当的软件包管理器。

每个快照都专用于一个 Amazon Web Services 账户、补丁组、操作系统和快照 ID。快照通过预签名的 Amazon Simple Storage Service (Amazon S3) URL 传送，该 URL 在快照创建 24 小时后过期。但是，在 URL 过期后，如果要将相同的快照内容应用于其他托管式节点，您可以在创建快照后最久 3 天内生成新的预签名 Amazon S3 URL。为此，请使用 get-deployable-patch-snapshot-for-instance 命令。

安装完所有已批准和适用的更新后，根据需要执行重启，然后在托管式节点上生成补丁合规性信息，并向 Patch Manager 报告。

注意

如果在 AWS-RunPatchBaseline 文档中将 RebootOption 参数设置为 NoReboot，在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 参数名称: RebootOption。

有关查看补丁合规性数据的信息，请参阅 关于补丁合规性。

AWS-RunPatchBaseline 参数

AWS-RunPatchBaseline 支持六个参数。Operation 参数是必需的。InstallOverrideList 、 BaselineOverride 和 RebootOption 参数是可选的。从技术上讲，Snapshot-ID 是可选的，但我们建议在维护时段之外运行 AWS-RunPatchBaseline 时为其提供一个自定义值，而在维护时段操作中运行此文档时，让 Patch Manager 自动提供该值。

参数名称: Operation

用法：必需。

选项：Scan | Install。

Scan

选择 Scan 选项时，AWS-RunPatchBaseline 确定托管式节点的补丁合规性状态并向 Patch Manager 报告此信息。Scan 不提示要安装的更新或要重启的托管式节点。相反，该操作会标识哪些地方缺少已批准并且适用于节点的更新。

安装

选择 Install 选项时，AWS-RunPatchBaseline 会尝试安装托管式节点中缺失并已批准的适用更新。在 Install 操作中生成的补丁合规性信息不会列出任何缺失的更新。但是，如果更新的安装因任何原因失败，它会报告处于失败状态的更新。一旦在托管式节点上安装了更新，就一定会重启节点，以确保正常安装和激活更新。（例外：如果将 AWS-RunPatchBaseline 文档中的 RebootOption 参数设置为 NoReboot，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 参数名称: RebootOption。）

注意

如果在 Patch Manager 更新托管式节点之前安装了基准规则指定的补丁，则系统可能无法按预期重启。当补丁是由用户手动安装或由其他程序（例如 unattended-upgrades 上的 Ubuntu Server 程序包）自动安装时，可能会发生这种情况。

参数名称: AssociationId

用法：可选。

AssociationId 是State Manager（Amazon Systems Manager 中的一项工具）中现有关联的 ID。Patch Manager 使用它来将合规性数据添加到指定的关联上。此关联与在 Quick Setup 的补丁策略中设置的修补操作有关。

注意

使用 AWS-RunPatchBaseline 时，如果在补丁策略基准覆盖的同时提供了一个 AssociationId 值，系统将以 PatchPolicy 操作来完成修补，AWS:ComplianceItem 中报告的 ExecutionType 值也是 PatchPolicy。如果未提供任何 AssociationId 值，系统将以 Command 操作来完成修补，提交的 AWS:ComplianceItem 中报告的 ExecutionType 值也是 Command。

如果您还没有要使用的关联，可以通过运行 create-association 命令来创建关联。

参数名称: Snapshot ID

用法：可选。

Snapshot ID 是 Patch Manager 使用的唯一 ID (GUID)，用于确保在单一操作中修补的一组托管式节点均具有完全相同的一组已批准补丁。尽管它定义为可选参数，根据是否在维护时段中运行 AWS-RunPatchBaseline，我们还是提供了不同的最佳实践建议，如下表所述。

AWS-RunPatchBaseline 最佳实践
Mode 最佳实践 详细信息
正在维护时段内运行 AWS-RunPatchBaseline 不要提供快照 ID，Patch Manager 将为您提供。

如果使用维护时段运行 AWS-RunPatchBaseline，则不应提供自己生成的快照 ID。这种情况下，Systems Manager 基于维护时段执行 ID 提供 GUID 值。这可确保在维护时段中为 AWS-RunPatchBaseline 的所有调用使用正确的 ID。

如果在这种情况下您指定值，请注意，补丁基准的快照最多保留 3 天。之后，即使您在快照到期后指定相同的 ID，也将生成新的快照。
正在在维护时段以外运行 AWS-RunPatchBaseline 为快照 ID¹ 生成和指定自定义 GUID 值。

如果您不使用维护时段运行 AWS-RunPatchBaseline，我们建议您为每个补丁基准生成并指定一个唯一的快照 ID，特别是于同一操作中在多个托管式节点上运行 AWS-RunPatchBaseline 文档时。如果在这种情况下不指定 ID，Systems Manager 会为向其发送命令的每个托管式节点生成不同的快照 ID。这可能会导致在托管式节点间指定不同的补丁集。

例如，假设您正在直接通过 Run Command（Amazon Systems Manager 中的一项工具）运行 AWS-RunPatchBaseline 文档，并以一组 50 个的托管式节点为目标。指定自定义快照 ID 将生成单一基准快照，用于评估和修补所有节点，从而确保所有节点最终处于一致状态。

¹ 您可以使用任何能够生成 GUID 的工具为快照 ID 参数生成值。例如，在 PowerShell 中，可以使用 New-Guid cmdlet 生成格式为 12345699-9405-4f69-bc5e-9315aEXAMPLE 的 GUID。

参数名称: InstallOverrideList

用法：可选。

使用 InstallOverrideList，可以指定一个到要安装的补丁列表的 https URL 或 Amazon S3 路径样式 URL。此补丁安装列表（以 YAML 格式维护）会覆盖当前的默认补丁基准指定的补丁。这样，您可以更精细地控制在托管式节点上安装哪些补丁。

重要

InstallOverrideList 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 ($)。

使用 InstallOverrideList 参数时的修补操作行为在 Linux 和 macOS 托管式节点以及 Windows Server 托管式节点之间有所不同。在 Linux 和 macOS 上，Patch Manager 尝试应用 InstallOverrideList 补丁列表中包含的补丁（存在于节点上启用的任何存储库中），无论补丁是否符合补丁基准规则。不过，在 Windows Server 节点上，只有当 InstallOverrideList 补丁列表中的补丁也符合补丁基准规则时，才会应用补丁列表中的补丁。

请注意，合规性根据补丁基准中指定的内容而不是您在补丁的 InstallOverrideList 列表中指定的内容反映补丁状态。也就是说，Scan 操作会忽略 InstallOverrideList 参数。这是为了确保合规性报告根据策略而不是针对特定修补操作批准的内容持续反映补丁状态。

注意

当您修补仅使用 IPv6 的节点时，请确保提供的 URL 可从该节点访问。如果将 SSM Agent 配置选项 UseDualStackEndpoint 设置为 true，则在提供 S3 URL 时将使用双堆栈 S3 客户端。有关将代理配置为使用双堆栈的更多信息，请参阅 教程：在仅支持 IPv6 的环境中修补服务器。

有关如何使用 InstallOverrideList 参数按不同维护时段计划将不同类型的补丁应用到目标组，同时仍使用单个补丁基准的说明，请参阅 在 AWS-RunPatchBaseline 或 AWS-RunPatchBaselineAssociation 中使用 InstallOverrideList 参数的示例场景。

有效的 URL 格式

注意

如果您的文件存储在公开可用的存储桶中，您可以指定 https URL 格式或 Amazon S3 路径样式的 URL。如果您的文件存储在私有存储桶中，则必须指定 Amazon S3 路径样式的 URL。

  • https URL 格式：

    https://s3.aws-api-domain/amzn-s3-demo-bucket/my-windows-override-list.yaml

  • Amazon S3 路径样式 URL：

    s3://amzn-s3-demo-bucket/my-windows-override-list.yaml

有效的 YAML 内容格式

用于在列表中指定补丁的格式取决于托管式节点的操作系统。但是，一般格式如下所示：

patches:
    - 
        id: '{patch-d}'
        title: '{patch-title}'
        {additional-fields}:{values}

尽管可以在 YAML 中提供额外字段，但是补丁操作会将其忽略。

此外，建议在 S3 存储桶中添加或更新列表之前验证 YAML 文件格式是否有效。有关 YAML 格式的更多信息，请参阅 yaml.org。对于验证工具选项，请在 Web 中搜索“yaml 格式验证程序”。

Linux
id

id 字段是必需的。它用来使用软件包名称和架构指定补丁。例如：'dhclient.x86_64'。您可以在 id 中使用通配符来指示多个软件包。例如：'dhcp*' 和 'dhcp*1.*'。

标题

title 字段是可选的，但它在 Linux 系统上提供额外的筛选功能。如果使用 title，它应包含以下格式之一的软件包版本信息：

YUM/SUSE Linux Enterprise Server (SLES)：

{name}.{architecture}:{epoch}:{version}-{release}

APT

{name}.{architecture}:{version}

对于 Linux 补丁标题，您可以在任意位置使用一个或多个通配符来扩展匹配软件包的数量。例如：'*32:9.8.2-0.*.rc1.57.amzn1'。

例如：

  • 托管式节点上目前安装了 apt 软件包版本 1.2.25，但版本 1.2.27 现已可用。

  • 将 apt.amd64 版本 1.2.27 添加到补丁列表中。它依赖于 apt utils.amd64 版本 1.2.27，但在列表中指定了 apt-utils.amd64 版本 1.2.25。

在这种情况下，将阻止安装 apt 版本 1.2.27 并报告为“Failed-NonCompliant.”。

Windows Server
id

id 字段是必需的。它用来使用 Microsoft 知识库 ID（例如 KB2736693）和 Microsoft 安全公告 ID（例如 MS17-023）指定补丁。

您在 Windows 补丁列表中提供的任何其他字段都是可选的，仅供您自己参考。您可以使用其他字段，如 title、classification、severity 等来提供关于指定补丁的更详细信息。

macOS
id

id 字段是必需的。id 字段的值可以使用 {package-name}.{package-version} 格式或 {软件包名称} 格式。

示例补丁列表

  • 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'

参数名称: RebootOption

用法：可选。

选项：RebootIfNeeded |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。

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。

重要

NoReboot 选项仅阻止操作系统级别的重启，服务级别的重启仍可作为修补过程的一部分进行。例如，当 Docker 更新时，即使启用了 NoReboot，Amazon Elastic Container Service 等依赖服务也可能会自动重启。要使关键服务不被中断，可考虑采取其他措施，例如暂时将实例从服务中删除或在维护时段内安排修补。

补丁安装跟踪文件：为跟踪补丁安装，特别是自上次系统重启以来安装的补丁，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

参数名称: BaselineOverride

用法：可选。

您可以在运行时使用 BaselineOverride 参数来定义修补首选项。此基准覆盖在 S3 存储桶中以 JSON 对象的形式进行维护。它确保修补操作使用的所提供的基准与主机的操作系统相匹配，而不是应用默认补丁基准中的规则

重要

BaselineOverride 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 ($)。

有关如何使用 BaselineOverride 参数的更多信息，请参阅 使用基准覆盖参数。

参数名称: StepTimeoutSeconds

用法：必需。

命令在被视为失败前将会运行的时间（以秒为单位），介于 1 至 36000 秒（10 小时）之间。