• 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-RunPatchBaselineAssociation`
就像 `AWS-RunPatchBaseline` 文档，`AWS-RunPatchBaselineAssociation` 对安全相关更新及其他更新类型执行修补操作。您也可以使用文档 `AWS-RunPatchBaselineAssociation` 为操作系统和应用程序应用补丁。（在 Windows Server 上，应用程序支持仅限于更新 Microsoft 发布的应用程序。）
此文档为 Linux、macOS 和 Windows Server 支持 Amazon Elastic Compute Cloud (Amazon EC2) 实例。它不支持[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 节点。此文档将为每个平台执行相应的操作，在 Linux 上调用 Python 模块和 macOS 实例，以及在 Windows 实例上调用 PowerShell 模块。
但是，`AWS-RunPatchBaselineAssociation` 与 `AWS-RunPatchBaseline` 存在以下差异：
+ `AWS-RunPatchBaselineAssociation` 主要用于使用[Quick Setup](systems-manager-quick-setup.md)（AWS Systems Manager 中的一项工具）创建的State Manager关联。具体来说，当使用 Quick Setup 主机管理配置类型时，如果选择**每天扫描实例以查找缺少的补丁**选项，系统将使用 `AWS-RunPatchBaselineAssociation` 进行操作。
但是，在大多数情况下，在设置自己的修补操作时，应选择 [`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md) 或者 [`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md)，而非 `AWS-RunPatchBaselineAssociation`。
+ 在使用 `AWS-RunPatchBaselineAssociation` 文档时，您可以在该文档的 `BaselineTags` 参数字段中指定标签键对。如果您 AWS 账户中的自定义补丁基准共享这些标签，则Patch Manager（AWS Systems Manager 中的一项工具）会在目标实例上运行时使用该标记的基准，而不是当前为操作系统类型指定的“默认”补丁基准。
**注意**
如果您选择在修补操作中使用 `AWS-RunPatchBaselineAssociation`，而不是使用 Quick Setup 设置的内容，并且您想要使用其可选的 `BaselineTags` 参数时，您必须为[实例配置文件](setup-instance-permissions.md)提供一些额外权限，以用于 Amazon Elastic Compute Cloud (Amazon EC2) 实例。有关更多信息，请参阅 [参数名称: `BaselineTags`](#patch-manager-aws-runpatchbaselineassociation-parameters-baselinetags)。
以下两种格式都适用于 `BaselineTags` 参数：
`Key=tag-key,Values=tag-value`
`Key=tag-key,Values=tag-value1,tag-value2,tag-value3`
**重要**
标签键和值不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
+ 在运行 `AWS-RunPatchBaselineAssociation` 时，其收集的补丁合规性数据将使用 `PutComplianceItems` API 命令而不是 `PutInventory` 命令 （该命令被 `AWS-RunPatchBaseline` 使用）来记录。这种差异意味着，所存储和报告的补丁合规性信息是依据特定*关联*的。在此关联之外生成的补丁合规性数据不会被覆盖。
+ 运行 `AWS-RunPatchBaselineAssociation` 后所报告的补丁合规性信息显示某个实例是否符合规定。它不包括补丁级别的详细信息，如以下 AWS Command Line Interface (AWS CLI) 命令的输出所显示的那样。命令筛选 `Association` 作为合规性类型：
```
aws ssm list-compliance-items \
--resource-ids "i-02573cafcfEXAMPLE" \
--resource-types "ManagedInstance" \
--filters "Key=ComplianceType,Values=Association,Type=EQUAL" \
--region us-east-2
```
系统将返回类似于以下内容的信息。
```
{
"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"
}
]
}
```
如果已将标签键对值指定为 `AWS-RunPatchBaselineAssociation` 文档的参数，则 Patch Manager 会搜索自定义补丁基准，该基准与操作系统类型匹配且已使用相同标签键对做了标记。此搜索不限于当前指定的默认补丁程序基准或分配给补丁组的基准。如果未找到具有指定标签的基准，下一步 Patch Manager 会查找补丁组（如果在运行 `AWS-RunPatchBaselineAssociation` 的命令中已经指定了）。如果没有匹配的补丁组，Patch Manager 将回退到操作系统账户的当前默认补丁基准。
如果找到多个具有 `AWS-RunPatchBaselineAssociation` 文档中的指定标签的补丁基准，则 Patch Manager 返回一条错误消息，指示只能使用该键值对标记一个补丁基准，以便继续执行操作。
**注意**
在 Linux 节点上，每种节点类型的相应软件包管理器被用来安装软件包：
Amazon Linux 2、Oracle Linux 和 RHEL 实例使用 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）
Debian Server 和 Ubuntu Server 实例使用 APT。对于 APT 操作，Patch Manager 需要使用受支持版本的 `Python 3`（3.0 – 3.12）。
在扫描完毕，或者所有已批准和适用的更新安装完毕后，根据需要执行重启，然后在实例上生成补丁合规性信息，并向 Patch Compliance 服务报告。
**注意**
如果在 `AWS-RunPatchBaselineAssociation` 文档中将 `RebootOption` 参数设置为 `NoReboot`，在 Patch Manager 运行后不会重启实例。有关更多信息，请参阅 [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption)。
有关查看补丁合规性数据的信息，请参阅 [关于补丁合规性](compliance-about.md#compliance-monitor-patch)。
## `AWS-RunPatchBaselineAssociation` 参数
`AWS-RunPatchBaselineAssociation` 支持五个参数。`Operation` 和 `AssociationId` 参数是必需的。`InstallOverrideList`、 `RebootOption` 和 `BaselineTags` 参数可选。
**Topics**
+ [参数名称: `Operation`](#patch-manager-aws-runpatchbaselineassociation-parameters-operation)
+ [参数名称: `BaselineTags`](#patch-manager-aws-runpatchbaselineassociation-parameters-baselinetags)
+ [参数名称: `AssociationId`](#patch-manager-aws-runpatchbaselineassociation-parameters-association-id)
+ [参数名称: `InstallOverrideList`](#patch-manager-aws-runpatchbaselineassociation-parameters-installoverridelist)
+ [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption)
### 参数名称: `Operation`
**用法**：必需。
**选项**：`Scan` \$1 `Install`。
Scan
选择 `Scan` 选项时，`AWS-RunPatchBaselineAssociation` 确定实例的补丁合规性状态，并向 Patch Manager 报告此信息。`Scan` 不提示要安装的更新或要重启的实例。相反，此操作会标识缺少哪些已批准并且适用于此实例的更新。
安装
选择 `Install` 选项时，`AWS-RunPatchBaselineAssociation` 尝试安装实例中缺失的已批准并且适用的更新。在 `Install` 操作中生成的补丁合规性信息不会列出任何缺失的更新。但是，如果更新的安装因任何原因失败，它会报告处于失败状态的更新。只要在实例上安装了更新，就一定会重启实例，以确保更新正常安装和激活。（例外：如果将 `AWS-RunPatchBaselineAssociation` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启实例。有关更多信息，请参阅 [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaselineassociation-parameters-norebootoption)。）
如果在 Patch Manager 更新实例*之前* 安装了基准规则指定的补丁，则系统可能无法按预期重启。当补丁是由用户手动安装或由其他程序（例如 Ubuntu Server 上的 `unattended-upgrades` 程序包）自动安装时，可能会发生这种情况。
### 参数名称: `BaselineTags`
**用法**：可选。
`BaselineTags` 是您选择并分配给单个自定义补丁基准的唯一标签键值对。可以为此参数指定一个或多个值。以下两种格式均为有效：
`Key=tag-key,Values=tag-value`
`Key=tag-key,Values=tag-value1,tag-value2,tag-value3`
**重要**
标签键和值不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
`BaselineTags` 值是 Patch Manager 使用的值，用于确保在单一操作中修补的一组实例都具有完全相同的一组已批准补丁。当执行修补操作时，Patch Manager 检查操作系统类型的补丁基准是否使用为 `BaselineTags` 指定的相同键值对进行了标记。如果存在匹配项，则使用此自定义补丁基准。如果不匹配，则根据为修补操作指定的任何补丁组来标识补丁基准。如果没有，AWS 使用该操作系统的托管预定义补丁基准。
**其他权限要求**
如果您在修补操作中使用 `AWS-RunPatchBaselineAssociation`，而不是使用 Quick Setup 设置的内容，并且您想要使用可选的 `BaselineTags` 参数，则必须将以下权限添加到[实例配置文件](setup-instance-permissions.md)，以用于 Amazon Elastic Compute Cloud (Amazon EC2) 实例。
**注意**
Quick Setup 和 `AWS-RunPatchBaselineAssociation` 不支持本地服务器和虚拟机 (VM)。
```
{
"Effect": "Allow",
"Action": [
"ssm:DescribePatchBaselines",
"tag:GetResources"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:GetPatchBaseline",
"ssm:DescribeEffectivePatchesForPatchBaseline"
],
"Resource": "patch-baseline-arn"
}
```
将*补丁基准 ARN* 替换为使用要提供访问权限的补丁基准的 Amazon Resource Name (ARN)，格式为 `arn:aws:ssm:us-east-2:123456789012:patchbaseline/pb-0c10e65780EXAMPLE`。
### 参数名称: `AssociationId`
**用法**：必需。
`AssociationId` 是State Manager（AWS Systems Manager 中的一项工具）中现有关联的 ID。Patch Manager 使用它来将合规性数据添加到指定的关联上。此关联与[在 Quick Setup 中创建的主机管理配置](quick-setup-host-management.md)中启用的补丁 `Scan` 操作有关。通过将修补结果作为关联合规性数据而不是库存合规性数据发送，您的实例的现有库存合规性信息不会在修补操作后被覆盖，同样，也不会覆盖其他关联 ID 的信息。如果您还没有要使用的关联，可以通过运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) 命令来创建关联。例如：
------
#### [ 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
```
------
### 参数名称: `InstallOverrideList`
**用法**：可选。
使用 `InstallOverrideList`，为要安装的补丁列表指定 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL。此补丁安装列表（以 YAML 格式维护）会覆盖当前的默认补丁基准指定的补丁。这样，您可以更精细地控制实例上安装的补丁。
**重要**
`InstallOverrideList` 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
使用 `InstallOverrideList` 参数时的修补操作行为在 Linux 和 macOS 托管式节点以及 Windows Server 托管式节点之间有所不同。在 Linux 和 macOS 上，Patch Manager 尝试应用 `InstallOverrideList` 补丁列表中包含的补丁（存在于节点上启用的任何存储库中），无论补丁是否符合补丁基准规则。不过，在 Windows Server 节点上，只有当 `InstallOverrideList` 补丁列表中的补丁也符合补丁基准规则时，*才*会应用补丁列表中的补丁。
请注意，合规性根据补丁基准中指定的内容而不是您在补丁的 `InstallOverrideList` 列表中指定的内容反映补丁状态。也就是说，Scan 操作会忽略 `InstallOverrideList` 参数。这是为了确保合规性报告根据策略而不是针对特定修补操作批准的内容持续反映补丁状态。
**有效的 URL 格式**
**注意**
如果您的文件存储在公开可用的存储桶中，您可以指定 https URL 格式或 Amazon S3 路径样式的 URL。如果您的文件存储在私有存储桶中，则必须指定 Amazon S3 路径样式的 URL。
+ **https URL 格式示例**：
```
https://s3.amazonaws.com/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](http://www.yaml.org)。对于验证工具选项，请在 Web 中搜索“yaml 格式验证程序”。
+ Microsoft Windows
**id**
**id** 字段是必需的。它用来使用 Microsoft 知识库 ID（例如 KB2736693）和 Microsoft 安全公告 ID（例如 MS17-023）指定补丁。
您在 Windows 补丁列表中提供的任何其他字段都是可选的，仅供您自己参考。您可以使用其他字段，如 **title**、**classification**、**severity** 等来提供关于指定补丁的更详细信息。
+ Linux
**id**
**id** 字段是必需的。它用来使用软件包名称和架构指定补丁。例如：`'dhclient.x86_64'`。您可以在 id 中使用通配符来指示多个软件包。例如：`'dhcp*'` 和 `'dhcp*1.*'`。
**删除实例快照**
**title** 字段是可选的，但它在 Linux 系统上提供额外的筛选功能。如果使用 **title**，它应包含以下格式之一的软件包版本信息：
YUM/Red Hat Enterprise Linux (RHEL)：
```
{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.”。
**其他字段**
您在 Linux 补丁列表中提供的任何其他字段都是可选的，仅供您自己参考。您可以使用其他字段，如 **classification**、**severity** 等来提供关于指定补丁的更详细信息。
**示例补丁列表**
+ **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'
```
### 参数名称: `RebootOption`
**用法**：可选。
**选项**：`RebootIfNeeded` \$1 `NoReboot`
**默认值**：`RebootIfNeeded`
**警告**
默认选项是 `RebootIfNeeded`。务必为应用场景选择正确的选项。例如，如果您的实例必须立即重启才能完成配置过程，请选择 `RebootIfNeeded`。或者，如果您需要在计划的重启时间之前保持实例可用，请选择 `NoReboot`。
**重要**
`NoReboot` 选项仅阻止操作系统级别的重启，服务级别的重启仍可作为修补过程的一部分进行。例如，当 Docker 更新时，即使启用了 `NoReboot`，Amazon Elastic Container Service 等依赖服务也可能会自动重启。要使关键服务不被中断，可考虑采取其他措施，例如暂时将实例从服务中删除或在维护时段内安排修补。
**重要**
我们不建议使用 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 也不会重启实例。如果您知道您的实例在应用补丁后不需要重启，或者您的应用程序或进程在实例上运行，但不应因修补操作重启而中断，则此选项有用。当您希望更多地控制实例重启的时间（例如，使用维护时段）时，该选项也很有用。
**补丁安装跟踪文件**：为了跟踪补丁安装，特别是自上次重启系统以来安装的补丁，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`