• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# AWS Systems Manager 节点工具
AWS Systems Manager 可提供以下工具，用于访问、管理和配置*托管式节点*。托管节点是指在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中配置与 Systems Manager 一起使用的任何计算机。
**Topics**
+ [AWS Systems Manager Compliance](systems-manager-compliance.md)
+ [AWS Systems Manager Distributor](distributor.md)
+ [AWS Systems Manager Fleet Manager](fleet-manager.md)
+ [AWS Systems Manager 混合激活](activations.md)
+ [AWS Systems Manager 清单](systems-manager-inventory.md)
+ [AWS Systems Manager Patch Manager](patch-manager.md)
+ [AWS Systems Manager Run Command](run-command.md)
+ [AWS Systems Manager Session Manager](session-manager.md)
+ [AWS Systems Manager State Manager](systems-manager-state.md)
# AWS Systems Manager Compliance
您可以使用 Compliance（AWS Systems Manager 中的一项工具）扫描托管式节点实例集，了解补丁合规性和配置不一致性。您可以从多个 AWS 账户 和区域中收集并聚合数据，然后深入了解不合规的特定资源。预设情况下，Compliance 会显示关于Patch Manager中的修补以及State Manager中的关联的当前合规性数据。（Patch Manager 和State Manager也都是 AWS Systems Manager 中的工具。） 要开始使用 Compliance，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/compliance)。在导航窗格中，选择 **合规性**。
可将来自 Patch Manager 的补丁合规性数据发送到 AWS Security Hub CSPM。Security Hub CSPM 能让您全面了解高优先级安全警报和合规性状态。它还监控您的实例集的修补状态。有关更多信息，请参阅 [将 Patch Manager 与 AWS Security Hub CSPM 集成](patch-manager-security-hub-integration.md)。
Compliance 具备以下额外优势和功能：
+ 使用 AWS Config 查看 Patch Manager 修补数据和 State Manager 关联的合规性历史记录及变更跟踪。
+ 自定义 Compliance 以根据 IT 或业务要求创建您自己的合规性类型。
+ 使用 Run Command（AWS Systems Manager 中的另一项工具）、State Manager或 Amazon EventBridge 修复问题。
+ 将数据移植到 Amazon Athena 和 Amazon Quick 以生成整个实例集的报告。
**EventBridge 支持**
支持此 Systems Manager 工具作为 Amazon EventBridge 规则中的一个*事件*类型。有关更多信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md) 和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
**Chef InSpec 集成**
Systems Manager 与 [https://www.chef.io/inspec/](https://www.chef.io/inspec/) 集成在一起。InSpec 是一个开源的运行时框架，您可以使用该框架在 GitHub 或 Amazon Simple Storage Service（Amazon S3）上创建人类可读的配置文件。然后您可以使用 Systems Manager 运行合规性扫描，并查看合规和不合规的托管式节点。有关更多信息，请参阅 [将 Chef InSpec 配置文件与 Systems Manager Compliance 结合使用](integration-chef-inspec.md)。
**定价**
Compliance 不另外收取费用。您仅需为实际使用的 AWS 资源付费。
**Topics**
+ [开始使用 Compliance](compliance-prerequisites.md)
+ [配置合规性权限](compliance-permissions.md)
+ [为 Compliance 创建资源数据同步](compliance-datasync-create.md)
+ [了解有关合规性的详细信息](compliance-about.md)
+ [删除用于 Compliance 的资源数据同步](systems-manager-compliance-delete-RDS.md)
+ [使用 EventBridge 修复合规性问题](compliance-fixing.md)
+ [使用 AWS CLI 分配自定义合规性元数据](compliance-custom-metadata-cli.md)
# 开始使用 Compliance
要开始使用 Compliance（AWS Systems Manager 中的一项工具），请完成以下任务。
****
| Task | 有关更多信息 |
| --- | --- |
| Compliance 适用于Patch Manager中的补丁数据和State Manager中的关联。（Patch Manager和State Manager都是 AWS Systems Manager 中的工具。） Compliance 还适用于使用 Systems Manager 管理的托管式节点上的自定义合规性类型。验证您是否已在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中完成 Amazon Elastic Compute Cloud（Amazon EC2）实例以及非 EC2 计算机的设置要求。 | [为组织设置 Systems Manager 统一控制台](systems-manager-setting-up-organizations.md) |
| 更新托管式节点使用的 AWS Identity and Access Management（IAM）角色以限制合规性权限。 | [配置合规性权限](compliance-permissions.md) |
| 如果您计划监控补丁合规性，请验证您是否已配置 Patch Manager。您必须使用 Patch Manager 执行修补操作，然后 Compliance 才能显示补丁合规性数据。 | [AWS Systems Manager Patch Manager](patch-manager.md) |
| 如果您计划监控关联合规性，请验证您是否已创建 State Manager 关联。您必须创建关联，然后 Compliance 才能显示关联合规性数据。 | [AWS Systems Manager State Manager](systems-manager-state.md) |
| （可选）配置系统以查看合规性历史记录和变更跟踪。 | [查看合规性配置历史记录和变更跟踪](compliance-about.md#compliance-history) |
| （可选）创建自定义合规性类型。 | [使用 AWS CLI 分配自定义合规性元数据](compliance-custom-metadata-cli.md) |
| （可选）创建资源数据同步以将所有合规性数据聚合在一个目标 Amazon Simple Storage Service (Amazon S3) 存储桶。 | [为 Compliance 创建资源数据同步](compliance-datasync-create.md) |
# 配置合规性权限
作为最佳安全实践，建议您使用以下权限来更新托管式节点使用的 AWS Identity and Access Management（IAM）角色，以限制该节点使用 [PutComplianceItems](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutComplianceItems.html) API 操作的功能。该 API 操作会在指定资源（例如 Amazon EC2 实例或托管式节点）上注册合规性类型及其他合规性详细信息。
如果节点是 Amazon EC2 实例，则必须使用以下权限来更新该实例使用的 IAM 实例配置文件。有关 Systems Manager 托管的 EC2 实例的实例配置文件的更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。对于其他类型的托管式节点，请使用以下权限来更新节点使用的 IAM 角色。有关更多信息，请参阅《IAM 用户指南》**中的[更新角色的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutComplianceItems"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:SourceInstanceARN": "${ec2:SourceInstanceARN}"
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:PutComplianceItems"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ssm:SourceInstanceARN": "${ssm:SourceInstanceARN}"
}
}
}
]
}
```
------
# 为 Compliance 创建资源数据同步
您可以使用 AWS Systems Manager 中的资源数据同步功能，将来自所有托管式节点的合规性数据发送到目标 Amazon Simple Storage Service (Amazon S3) 存储桶。在创建同步时，可以指定来自多个 AWS 账户、AWS 区域 和[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境的托管式节点。收集新的合规性数据后，资源数据同步自动更新集中式数据。所有合规性数据存储在目标 Amazon S3 存储桶中后，可以使用 Amazon Athena 和 Amazon Quick 等服务查询和分析聚合数据。为 Compliance 配置资源数据同步是一次性操作。
通过使用 AWS 管理控制台，使用以下过程为 Compliance 创建资源数据同步。
**创建和配置一个 S3 存储桶用于资源数据同步（控制台）**
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 创建用来存储聚合合规性数据的存储桶。有关更多信息，请参阅 [Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)中的*创建存储桶*。请记下存储桶名称和创建此存储桶的 AWS 区域。
1. 打开存储桶，选择 **Permissions (权限)** 选项卡，然后选择 **Bucket Policy (存储桶策略)**。
1. 将下面的存储桶策略复制并粘贴到策略编辑器中。将 amzn-s3-demo-bucket 和 *Account-ID* 分别替换为您创建的 S3 存储桶的名称和有效的 AWS 账户 ID。或者，使用 Amazon S3 前缀（子目录）的名称替换 *Bucket-Prefix*。如果您未创建前缀，则从该策略的 ARN 中删除 *Bucket-Prefix*/。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SSMBucketPermissionsCheck",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
},
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": ["arn:aws:s3:::amzn-s3-demo-bucket/Bucket-Prefix/*/accountid=111122223333/*"],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control"
}
}
}
]
}
```
------
**创建资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择 **Account management (账户管理)**、**Resource Data Syncs (资源数据同步)**，然后选择 **Create resource data sync (创建资源数据同步)**。
1. 在 **Sync name (同步名称)** 字段中，输入同步配置的名称。
1. 在 **Bucket name (存储桶名称)** 字段中，输入您在此过程开始时创建的 Amazon S3 存储桶的名称。
1. （可选）在**存储桶前缀**字段中，输入 S3 存储桶前缀（子目录）的名称。
1. 在**存储桶区域**字段中，如果您创建的 S3 存储桶位于当前的 AWS 区域 中，请选择**此区域**。如果存储桶位于其他 AWS 区域 中，则请选择**其他区域**，然后输入该区域的名称。
**注意**
如果同步和目标 S3 存储桶位于不同区域，您可能需要支付数据传输价格。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。
1. 选择**创建**。
# 了解有关合规性的详细信息
Compliance 是 AWS Systems Manager 中的一项工具，可收集和报告与Patch Manager修补中修补状态和State Manager中关联有关的数据。（Patch Manager 和State Manager也都是 AWS Systems Manager 中的工具。） Compliance 还可报告有关您为托管式节点指定的自定义合规性类型的信息。本节包含有关每个合规性类型以及如何查看 Systems Manager 合规性数据的详细信息。本节还包含有关如何查看合规性历史记录和变更跟踪的信息。
**注意**
Systems Manager 与 [https://www.chef.io/inspec/](https://www.chef.io/inspec/) 集成在一起。InSpec 是一个开源的运行时框架，您可以使用该框架在 GitHub 或 Amazon Simple Storage Service（Amazon S3）上创建人类可读的配置文件。然后，您可以使用 Systems Manager 运行合规性扫描并查看合规和不合规的实例。有关更多信息，请参阅 [将 Chef InSpec 配置文件与 Systems Manager Compliance 结合使用](integration-chef-inspec.md)。
## 关于补丁合规性
使用 Patch Manager 在实例上安装补丁之后，控制台、AWS Command Line Interface (AWS CLI) 命令响应或相应 Systems Manager API 操作的响应中将立即出现合规性状态信息。
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 关于 State Manager 关联合规性
创建一个或多个 State Manager 关联之后，控制台、AWS CLI 命令响应或相应 Systems Manager API 操作的响应中将立即出现合规性状态信息。对于关联，Compliance 显示 `Compliant` 或 `Non-compliant` 的状态和分配给关联的严重性级别，如 `Critical` 或 `Medium`。
State Manager 在托管节点上执行关联时会触发合规聚合过程，该过程会更新该节点上所有关联的合规状态。合规报告中的 `ExecutionTime` 值表示 Systems Manager 捕获合规状态的时间，而非在托管节点上执行关联的时间。这意味着多个关联即使在不同时间执行，也可能显示相同的 `ExecutionTime` 值。要确定关联的实际执行时间，请使用 AWS CLI 命令 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-association-execution-targets.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-association-execution-targets.html) 来参阅关联执行历史记录，或在控制台中查看执行详细信息。
## 关于自定义合规性
您可以将合规性元数据分配给托管式节点。然后此元数据可以与用于合规性报告目的的其他合规性数据聚合。例如，假设您的企业在您的托管式节点上运行软件 X 的版本 2.0、3.0 和 4.0。公司希望在版本 4.0 上实现标准化，这意味着运行版本 2.0 和 3.0 的实例将不合规。您可以使用 [PutComplianceItems](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutComplianceItems.html) API 操作显式注释哪些托管式节点在运行软件 X 的较旧版本。您只能使用 AWS CLI、AWS Tools for Windows PowerShell 或软件开发工具包分配合规性元数据。以下 CLI 示例命令会将合规性元数据分配给一个托管实例并以要求的格式 `Custom:` 指定合规性类型。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm put-compliance-items \
--resource-id i-1234567890abcdef0 \
--resource-type ManagedInstance \
--compliance-type Custom:SoftwareXCheck \
--execution-summary ExecutionTime=AnyStringToDenoteTimeOrDate \
--items Id=Version2.0,Title=SoftwareXVersion,Severity=CRITICAL,Status=NON_COMPLIANT
```
------
#### [ Windows ]
```
aws ssm put-compliance-items ^
--resource-id i-1234567890abcdef0 ^
--resource-type ManagedInstance ^
--compliance-type Custom:SoftwareXCheck ^
--execution-summary ExecutionTime=AnyStringToDenoteTimeOrDate ^
--items Id=Version2.0,Title=SoftwareXVersion,Severity=CRITICAL,Status=NON_COMPLIANT
```
------
**注意**
`ResourceType` 参数仅支持 `ManagedInstance`。如果您将自定义合规性添加到托管式 AWS IoT Greengrass 核心设备，则必须指定 `ManagedInstance` 的 `ResourceType`。
然后合规经理可以查看摘要，或创建有关哪些托管式节点合规或不合规的报告。您可将最多 10 个不同的自定义合规性类型分配给一个托管式节点。
有关如何创建自定义合规性类型并查看合规性数据的示例，请参阅 [使用 AWS CLI 分配自定义合规性元数据](compliance-custom-metadata-cli.md)。
## 查看当前合规性数据
本节介绍如何在 Systems Manager 控制台中以及如何使用 AWS CLI 查看合规性数据。有关如何查看补丁和关联合规性历史记录和变更跟踪的信息，请参阅 [查看合规性配置历史记录和变更跟踪](#compliance-history)。
**Topics**
+ [查看当前合规性数据（控制台）](#compliance-view-results-console)
+ [查看当前合规性数据 (AWS CLI)](#compliance-view-data-cli)
### 查看当前合规性数据（控制台）
使用以下过程在 Systems Manager 控制台中查看合规性数据。
**在 Systems Manager 控制台中查看合规性报告**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **合规性**。
1. 在 **Compliance dashboard filtering**（合规性控制面板筛选）部分中，选择一个选项来筛选合规性数据。**Compliance resources summary**（合规性资源摘要）部分会根据您选择的筛选条件显示合规性数据的计数。
1. 要深入了解资源以获取更多信息，请向下滚动至 **Details overview for resources**（资源详细信息概览）区域，然后选择托管式节点的 ID。
1. 在 **Instance ID**（实例 ID）或 **Name**（名称）详细信息页面上，选择 **Configuration compliance**（配置合规性）选项卡以查看详细的托管式节点配置合规性报告。
**注意**
有关修复合规性问题的信息，请参阅 [使用 EventBridge 修复合规性问题](compliance-fixing.md)。
### 查看当前合规性数据 (AWS CLI)
可以通过使用以下 AWS CLI 命令，在 AWS CLI 中查看修补、关联和自定义合规性类型的合规性数据摘要。
[https://docs.aws.amazon.com/cli/latest/reference/ssm/list-compliance-summaries.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-compliance-summaries.html)
根据您指定的筛选条件返回合规和不合规关联状态的摘要计数。（API：[ListComplianceSummaries](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ListComplianceSummaries.html)）
[https://docs.aws.amazon.com/cli/latest/reference/ssm/list-resource-compliance-summaries.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-resource-compliance-summaries.html)
返回资源级摘要计数。根据您指定的筛选条件，摘要包括有关合规和不合规状态的信息，以及详细的合规性项目严重性计数。（API：[ListResourceComplianceSummaries](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ListResourceComplianceSummaries.html)）
可以使用以下 AWS CLI 命令查看修补的其他合规性数据。
[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-group-state.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-group-state.html)
返回补丁组的高级聚合补丁合规性状态。（API：[DescribePatchGroupState](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchGroupState.html)）
[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-patch-states-for-patch-group.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-patch-states-for-patch-group.html)
返回指定补丁组中实例的高级补丁状态。（API：[DescribeInstancePatchStatesForPatchGroup](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatchStatesForPatchGroup.html)）
**注意**
有关如何使用 AWS CLI 配置修补和查看补丁合规性详细信息的说明，请参阅 [教程：使用 AWS CLI 修补服务器环境](patch-manager-patch-servers-using-the-aws-cli.md)。
## 查看合规性配置历史记录和变更跟踪
Systems Manager Compliance 显示您的托管式节点的*最新*修补和关联合规性数据。您可以使用 [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/) 查看修补和关联合规性历史记录和变更追踪。AWS Config 提供关于 AWS 账户中 AWS 资源配置的详细视图。这些信息包括资源之间的关联方式以及资源以前的配置方式，让您了解资源的配置和关系如何随着的时间的推移而更改。要查看修补和关联合规性历史记录和变更跟踪，您必须在 AWS Config 中打开以下资源：
+ `SSM:PatchCompliance`
+ `SSM:AssociationCompliance`
有关如何在 AWS Config 中选择和配置这些特定资源的信息，请参阅 *AWS Config Developer Guide* 中的[选择哪些资源 AWS Config 记录](https://docs.aws.amazon.com/config/latest/developerguide/select-resources.html)。
**注意**
有关 AWS Config 定价的信息，请参阅 [ 定价](https://aws.amazon.com/config/pricing/)。
# 删除用于 Compliance 的资源数据同步
如果您不再需要使用 AWS Systems Manager Compliance 查看合规性数据，那么我们建议删除用于 Compliance 数据收集的资源数据同步。
**删除 Compliance 资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择 **Account management (账户管理)**、**Resource data syncs (资源数据同步)**。
1. 在列表中，选择一个同步。
**重要**
确保您选择了用于 Compliance 的同步。Systems Manager 可为多项工具的资源数据同步提供支持。如果选择的同步错误，则可能会导致 Systems Manager Explorer 或 Systems Manager Inventory 的数据聚合中断。
1. 选择**删除**。
1. 删除存储数据的 Amazon Simple Storage Service (Amazon S3) 存储桶。有关删除 S3 存储桶的信息，请参阅[删除存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html)。
# 使用 EventBridge 修复合规性问题
您可以使用 Run Command（AWS Systems Manager 中的一项工具）快速修复补丁和关联合规性问题。您可以将实例、AWS IoT Greengrass 核心设备 ID 或标签设为目标，并运行 `AWS-RunPatchBaseline` 文档或 `AWS-RefreshAssociation` 文档。如果刷新关联或重新运行补丁基准也未能解决合规性问题，则需要调查您的关联、补丁基准或实例配置，以了解 Run Command 操作未能解决问题的原因。
有关修补的更多信息，请参阅 [AWS Systems Manager Patch Manager](patch-manager.md) 和[用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
有关关联的更多信息，请参阅 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
有关运行命令的更多信息，请参阅 [AWS Systems Manager Run Command](run-command.md)。
**将 Compliance 指定为 EventBridge 事件的目标**
您也可以将 Amazon EventBridge 配置为执行操作以响应 Systems Manager Compliance 事件。例如，如果一个或多个托管式节点未能安装重要补丁更新或运行安装反病毒软件的关联，则您可以将 EventBridge 配置为在 Compliance 事件发生时运行 `AWS-RunPatchBaseline` 文档或 `AWS-RefreshAssocation` 文档。
使用以下过程将 Compliance 配置为 EventBridge 事件的目标。
**将 Compliance 配置为 EventBridge 事件的目标（控制台）**
1. 访问 [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/)，打开 Amazon EventBridge 控制台。
1. 在导航窗格中，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。
规则不能与同一 AWS 区域中和同一事件总线上的另一条规则的名称相同。
1. 对于**事件总线**，请选择要与此规则关联的事件总线。如果您希望此规则响应来自您自己的 AWS 账户的匹配事件，请选择 **defaul**（默认）。当您账户中的某个 AWS 服务发出一个事件时，它始终会发送到您账户的默认事件总线。
1. 对于**规则类型**，选择**具有事件模式的规则**。
1. 选择**下一步**。
1. 对于**事件源**，选择**AWS 事件或 EventBridge 合作伙伴事件**。
1. 在 **Event pattern**（事件模式）部分，选择 **Event pattern form**（事件模式表单）。
1. 对于**事件源**，选择**AWS 服务**。
1. 对于 ** service**（AWS 服务），选择 **Systems Manager**。
1. 在 **Event type (事件类型)** 字段中，选择 **Configuration Compliance (配置合规性)**。
1. 对于 **Specific detail type(s)**（具体详细信息类型），选择 **Configuration Compliance State Change**（配置合规性状态更改）。
1. 选择**下一步**。
1. 对于**目标类型**，选择**AWS 服务**。
1. 对于 **Select a target**（选择一个目标），选择 **Systems Manager Run Command**。
1. 在 **Document (文档)** 列表中，选择在调用目标时要运行的 Systems Manager 文档（SSM 文档）。例如，对于不合规补丁事件选择 `AWS-RunPatchBaseline`，对于不合规关联事件选择 `AWS-RefreshAssociation`。
1. 指定其余字段和参数的信息。
**注意**
必填字段和参数的名称旁有一个星号 (\$1)。要创建目标，您必须为每个必填参数或字段指定一个值。如果不指定，系统虽然会创建规则，但该规则不会运行。
1. 选择**下一步**。
1. （可选）为规则输入一个或多个标签。有关更多信息，请参阅 *Amazon EventBridge 用户指南*中的[标记 Amazon EventBridge 资源](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html)。
1. 选择 **Next（下一步）**。
1. 查看规则详细信息并选择**创建规则**。
# 使用 AWS CLI 分配自定义合规性元数据
以下步骤为您演示了使用 AWS Command Line Interface (AWS CLI) 调用 AWS Systems Manager [PutComplianceItems](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutComplianceItems.html) API 操作将自定义合规性元数据分配给某个资源的过程。您也可以使用此 API 操作将补丁或关联合规性元数据手动分配给某个托管式节点，如以下演练中所示。有关自定义合规性的更多信息，请参阅 [关于自定义合规性](compliance-about.md#compliance-custom)。
**将自定义合规性元数据分配给某个托管实例 (AWS CLI)**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令，将自定义合规性元数据分配给某个托管式节点。将每个*示例资源占位符*替换为您自己的信息。`ResourceType` 参数仅支持 `ManagedInstance` 的值。即使您将自定义合规性元数据分配给托管式 AWS IoT Greengrass 核心设备，也请指定此值。
------
#### [ Linux & macOS ]
```
aws ssm put-compliance-items \
--resource-id instance_ID \
--resource-type ManagedInstance \
--compliance-type Custom:user-defined_string \
--execution-summary ExecutionTime=user-defined_time_and/or_date_value \
--items Id=user-defined_ID,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT
```
------
#### [ Windows ]
```
aws ssm put-compliance-items ^
--resource-id instance_ID ^
--resource-type ManagedInstance ^
--compliance-type Custom:user-defined_string ^
--execution-summary ExecutionTime=user-defined_time_and/or_date_value ^
--items Id=user-defined_ID,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT
```
------
1. 重复上一步以将其他自定义合规性元数据分配给一个或多个节点。您也可以使用以下命令，将补丁或关联合规性元数据手动分配给托管式节点：
关联合规性元数据
------
#### [ Linux & macOS ]
```
aws ssm put-compliance-items \
--resource-id instance_ID \
--resource-type ManagedInstance \
--compliance-type Association \
--execution-summary ExecutionTime=user-defined_time_and/or_date_value \
--items Id=user-defined_ID,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT
```
------
#### [ Windows ]
```
aws ssm put-compliance-items ^
--resource-id instance_ID ^
--resource-type ManagedInstance ^
--compliance-type Association ^
--execution-summary ExecutionTime=user-defined_time_and/or_date_value ^
--items Id=user-defined_ID,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT
```
------
补丁合规性元数据
------
#### [ Linux & macOS ]
```
aws ssm put-compliance-items \
--resource-id instance_ID \
--resource-type ManagedInstance \
--compliance-type Patch \
--execution-summary ExecutionTime=user-defined_time_and/or_date_value,ExecutionId=user-defined_ID,ExecutionType=Command \
--items Id=for_example, KB12345,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT,Details="{PatchGroup=name_of_group,PatchSeverity=the_patch_severity, for example, CRITICAL}"
```
------
#### [ Windows ]
```
aws ssm put-compliance-items ^
--resource-id instance_ID ^
--resource-type ManagedInstance ^
--compliance-type Patch ^
--execution-summary ExecutionTime=user-defined_time_and/or_date_value,ExecutionId=user-defined_ID,ExecutionType=Command ^
--items Id=for_example, KB12345,Title=user-defined_title,Severity=one_or_more_comma-separated_severities:CRITICAL, MAJOR, MINOR,INFORMATIONAL, or UNSPECIFIED,Status=COMPLIANT or NON_COMPLIANT,Details="{PatchGroup=name_of_group,PatchSeverity=the_patch_severity, for example, CRITICAL}"
```
------
1. 运行以下命令，查看特定托管式节点的合规性项目列表。使用筛选条件深入了解特定合规性数据。
------
#### [ Linux & macOS ]
```
aws ssm list-compliance-items \
--resource-ids instance_ID \
--resource-types ManagedInstance \
--filters one_or_more_filters
```
------
#### [ Windows ]
```
aws ssm list-compliance-items ^
--resource-ids instance_ID ^
--resource-types ManagedInstance ^
--filters one_or_more_filters
```
------
以下示例向您演示如何将此命令与筛选条件结合使用。
------
#### [ Linux & macOS ]
```
aws ssm list-compliance-items \
--resource-ids i-02573cafcfEXAMPLE \
--resource-type ManagedInstance \
--filters Key=DocumentName,Values=AWS-RunPowerShellScript Key=Status,Values=NON_COMPLIANT,Type=NotEqual Key=Id,Values=cee20ae7-6388-488e-8be1-a88ccEXAMPLE Key=Severity,Values=UNSPECIFIED
```
------
#### [ Windows ]
```
aws ssm list-compliance-items ^
--resource-ids i-02573cafcfEXAMPLE ^
--resource-type ManagedInstance ^
--filters Key=DocumentName,Values=AWS-RunPowerShellScript Key=Status,Values=NON_COMPLIANT,Type=NotEqual Key=Id,Values=cee20ae7-6388-488e-8be1-a88ccEXAMPLE Key=Severity,Values=UNSPECIFIED
```
------
------
#### [ Linux & macOS ]
```
aws ssm list-resource-compliance-summaries \
--filters Key=OverallSeverity,Values=UNSPECIFIED
```
------
#### [ Windows ]
```
aws ssm list-resource-compliance-summaries ^
--filters Key=OverallSeverity,Values=UNSPECIFIED
```
------
------
#### [ Linux & macOS ]
```
aws ssm list-resource-compliance-summaries \
--filters Key=OverallSeverity,Values=UNSPECIFIED Key=ComplianceType,Values=Association Key=InstanceId,Values=i-02573cafcfEXAMPLE
```
------
#### [ Windows ]
```
aws ssm list-resource-compliance-summaries ^
--filters Key=OverallSeverity,Values=UNSPECIFIED Key=ComplianceType,Values=Association Key=InstanceId,Values=i-02573cafcfEXAMPLE
```
------
1. 运行以下命令查看合规性状态的摘要。使用筛选条件深入了解特定合规性数据。
```
aws ssm list-resource-compliance-summaries --filters One or more filters.
```
以下示例向您演示如何将此命令与筛选条件结合使用。
------
#### [ Linux & macOS ]
```
aws ssm list-resource-compliance-summaries \
--filters Key=ExecutionType,Values=Command
```
------
#### [ Windows ]
```
aws ssm list-resource-compliance-summaries ^
--filters Key=ExecutionType,Values=Command
```
------
------
#### [ Linux & macOS ]
```
aws ssm list-resource-compliance-summaries \
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=OverallSeverity,Values=CRITICAL
```
------
#### [ Windows ]
```
aws ssm list-resource-compliance-summaries ^
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=OverallSeverity,Values=CRITICAL
```
------
1. 运行以下命令查看某个合规性类型的合规资源和不合规资源的摘要计数。使用筛选条件深入了解特定合规性数据。
```
aws ssm list-compliance-summaries --filters One or more filters.
```
以下示例向您演示如何将此命令与筛选条件结合使用。
------
#### [ Linux & macOS ]
```
aws ssm list-compliance-summaries \
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=PatchGroup,Values=TestGroup
```
------
#### [ Windows ]
```
aws ssm list-compliance-summaries ^
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=PatchGroup,Values=TestGroup
```
------
------
#### [ Linux & macOS ]
```
aws ssm list-compliance-summaries \
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=ExecutionId,Values=4adf0526-6aed-4694-97a5-14522EXAMPLE
```
------
#### [ Windows ]
```
aws ssm list-compliance-summaries ^
--filters Key=AWS:InstanceInformation.PlatformType,Values=Windows Key=ExecutionId,Values=4adf0526-6aed-4694-97a5-14522EXAMPLE
```
------
# AWS Systems Manager Distributor
Distributor 是 AWS Systems Manager 中的一项工具，可以帮助您将软件打包并发布到 AWS Systems Manager 托管式节点。您可以打包和发布自己的软件，也可以使用 Distributor 查找和发布 **AmazonCloudWatchAgent** 等 AWS 提供的代理软件包，或者 **Trend Micro** 等第三方软件包。发布软件包会将特定版本的软件包文档公布给通过节点 ID、AWS 账户 ID、标签或 AWS 区域 标识的托管式节点。要开始使用 Distributor，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/distributor)。在导航窗格中，请选择 **Distributor**。
在 Distributor 中创建软件包后，可以使用以下方式之一安装该软件包：
+ 使用 [AWS Systems Manager Run Command](run-command.md) 进行一次性安装
+ 使用 [AWS Systems Manager State Manager](systems-manager-state.md) 按计划执行安装
**重要**
第三方卖家分发的程序包不由 AWS 管理，而是由程序包供应商发布。建议开展额外的尽职调查，确保遵守您的内部安全控制措施。安全性是 AWS 和您的共同责任。这被描述为责任共担共担模式。要了解更多信息，请参阅[责任共担模式](https://aws.amazon.com/compliance/shared-responsibility-model/)。
## 我的组织如何从 Distributor 获益？
Distributor 具备下列优势：
+ **一个软件包，多个平台**
在 Distributor 中创建软件包时，系统会创建 AWS Systems Manager 文档（SSM 文档）。您可以将 .zip 格式文件附加到此文档中。运行 Distributor 时，系统会处理 SSM 文档中的指令，并将.zip 格式文件中的软件包安装到指定目标上。Distributor 支持 Windows、Ubuntu Server、Debian Server 和 Red Hat Enterprise Linux 等多种操作系统。有关支持的平台的更多信息，请参阅 [支持的软件包平台和架构](#what-is-a-package-platforms)。
+ **跨托管实例组控制软件包访问权限**
您可以使用 Run Command 或State Manager控制哪些托管式节点能够获取软件包，以及获取该软件包的哪个版本。Run Command 和State Manager都是 AWS Systems Manager 中的工具。托管式节点可以按实例或设备 ID、AWS 账户 账号、标签或 AWS 区域 进行分组。您可以使用 State Manager 关联向不同的实例组提供不同版本的软件包。
+ **包含众多 AWS 代理软件包并且随时可用**
Distributor 包含许多可供您随时部署到托管式节点的 AWS 代理软件包。可以在 Distributor `Packages` 列表页面中查找 `Amazon` 发布的软件包。示例包括 `AmazonCloudWatchAgent` 和 `AWSPVDriver`。
+ **自动部署**
要使您的环境保持最新，请使用 State Manager，在首次启动这些计算机时，安排要在目标托管式节点上自动部署的软件包。
## 谁应该使用 Distributor？
+ 希望创建新软件包或将现有软件包（包括 AWS 发布的软件包）同时部署到多个 Systems Manager 托管式节点的任何 AWS 客户。
+ 创建软件包的软件开发人员。
+ 负责保持 Systems Manager 托管式节点始终使用最新软件包的管理员。
## Distributor 具有哪些功能？
+ **将软件包部署到 Windows 和 Linux 实例**
借助 Distributor，您可以将软件包部署到适用于 Linux 和 Windows Server 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例和 AWS IoT Greengrass 核心设备。有关支持的实例操作系统类型的列表，请参阅 [支持的软件包平台和架构](#what-is-a-package-platforms)。
**注意**
Distributor 在 macOS 操作系统上不受支持。
+ **一次性或按计划自动部署软件包**
您可以选择一次性、定期或每当默认软件包版本更改为其他版本时部署软件包。
+ **完全重新安装软件包或执行就地更新**
要安装新的软件包版本，可以根据您提供的*更新脚本* 完全卸载当前版本并在其位置安装新版本，或者仅使用新组件和更新的组件更新当前版本。软件包应用程序在重新安装期间不可用，但在就地更新期间保持可用。对于安全监控应用程序或需要避免应用程序停机的其他情况，就地更新是特别有用的。
+ **支持通过控制台、CLI、PowerShell 和开发工具包等方式访问 Distributor 功能**
您可以通过 Systems Manager 控制台、AWS Command Line Interface (AWS CLI)、AWS Tools for PowerShell 或您选择的 AWS 开发工具包来使用 Distributor。
+ **IAM 访问控制**
通过使用 AWS Identity and Access Management (IAM) 策略，您可以控制组织的哪些成员能够创建、更新、部署或删除软件包或软件包版本。例如，您可能需要授予管理员部署软件包但不能更改软件包或创建新软件包版本的权限。
+ **支持日志记录和审计功能**
您可以通过与其他 AWS 服务集成来审计和记录您的 AWS 账户中的 Distributor 用户操作日志。有关更多信息，请参阅 [审计和记录 Distributor 活动](distributor-logging-auditing.md)。
## Distributor 中的软件包是什么？
*软件包* 是包含以下内容的可安装软件或资产的集合。
+ 每个目标操作系统平台的软件 .zip 文件。每个 .zip 文件必须包含以下内容。
+ **install** 和 **uninstall** 脚本。基于 Windows Server 的托管式节点需要使用 PowerShell 脚本（名为 `install.ps1` 和 `uninstall.ps1` 的脚本）。基于 Linux 的托管式节点需要使用 Shell 脚本（名为 `install.sh` 和 `uninstall.sh` 的脚本）。AWS Systems Manager SSM Agent 读取并执行 **install** 和 **uninstall** 脚本中的指令。
+ 可执行文件。SSM Agent 必须找到此可执行文件才能在目标托管式节点上安装软件包。
+ 用于描述软件包内容的 JSON 格式的清单文件。清单不包含在 .zip 文件中，而是存储在与构成软件包的 .zip 文件相同的 Amazon Simple Storage Service (Amazon S3) 存储桶中。该清单指定软件包版本，并将软件包中的 .zip 格式文件映射到目标托管式节点属性，例如操作系统版本或架构。有关如何创建清单的信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest)。
当您在 Distributor 控制台中选择 **Simple (简单)** 软件包创建时，Distributor 将根据软件可执行文件名称以及目标平台和架构，为您生成安装和卸载脚本、文件哈希以及 JSON 软件包清单。
### 支持的软件包平台和架构
您可以使用 Distributor 将软件包发布到以下 Systems Manager 托管式节点平台。版本值必须与您设定为目标的操作系统 Amazon Machine Image (AMI) 的发行版本完全匹配。有关确定此版本的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest) 的步骤 4。
**注意**
Systems Manager 不支持 AWS IoT Greengrass 核心设备的以下所有操作系统。有关更多信息，请参阅 [AWS IoT Greengrass 开发人员指南](https://docs.aws.amazon.com/greengrass/v2/developerguide/setting-up.html)中的*设置 AWS IoT Greengrass Version 2 核心设备*。
| 平台 | 清单文件中的代码值 | 支持的架构 |
| --- | --- | --- |
| AlmaLinux | almalinux | x86\$164 ARM64 |
| Amazon Linux 2 和 Amazon Linux 2023 | `amazon` | x86\$164 或 x86 ARM64（Amazon Linux 2 和 AL2023、A1 实例类型） |
| Debian Server | `debian` | x86\$164 或 x86 |
| openSUSE | `opensuse` | x86\$164 |
| openSUSE Leap | `opensuseleap` | x86\$164 |
| Oracle Linux | `oracle` | x86\$164 |
| Red Hat Enterprise Linux (RHEL) | `redhat` | x86\$164 ARM64（RHEL 7.6 及更高版本，A1 实例类型） |
| Rocky Linux | rocky | x86\$164 ARM64 |
| SUSE Linux Enterprise Server (SLES) | `suse` | x86\$164 |
| Ubuntu Server | `ubuntu` | x86\$164 或 x86 ARM64（Ubuntu Server 16 及更高版本，A1 实例类型） |
| Windows Server | `windows` | x86\$164 |
**Topics**
+ [我的组织如何从 Distributor 获益？](#distributor-benefits)
+ [谁应该使用 Distributor？](#distributor-who)
+ [Distributor 具有哪些功能？](#distributor-features)
+ [Distributor 中的软件包是什么？](#what-is-a-package)
+ [设置 Distributor](distributor-getting-started.md)
+ [处理 Distributor 程序包](distributor-working-with.md)
+ [审计和记录 Distributor 活动](distributor-logging-auditing.md)
+ [AWS Systems Manager Distributor 故障排除](distributor-troubleshooting.md)
# 设置 Distributor
在使用 Distributor（AWS Systems Manager 中的一项工具）创建、管理和部署软件包之前，请按照以下步骤操作。
## 满足 Distributor 先决条件
在开始使用 Distributor（AWS Systems Manager 中的一项工具）之前，请确保环境满足以下要求。
**Distributor 先决条件**
| 要求 | 说明 |
| --- | --- |
| SSM Agent | 必须在要部署软件包或从中删除软件包的托管式节点上安装 AWS Systems Manager SSM Agent 版本 2.3.274.0 或更高版本。 要安装或更新 SSM Agent，请参阅 [使用 SSM Agent](ssm-agent.md)。 |
| AWS CLI | （可选）要使用 AWS Command Line Interface (AWS CLI) 而不是 Systems Manager 控制台创建和管理软件包，请在本地计算机上安装最新版本的 AWS CLI。 有关如何安装或升级 CLI 的更多信息，请参阅 *AWS Command Line Interface 用户指南*中的[安装 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)。 |
| AWS Tools for PowerShell | （可选）要使用 Tools for PowerShell 而不是 Systems Manager 控制台创建和管理软件包，请在本地计算机上安装最新版本的 Tools for PowerShell。 要详细了解如何安装或升级 Tools for PowerShell，请参阅《AWS Tools for PowerShell 用户指南》中的[设置 AWS Tools for Windows PowerShell 或 AWS Tools for PowerShell Core](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。 |
**注意**
Systems Manager 不支持通过使用 Distributor 将软件包分发到 Oracle Linux 托管式节点。
## 验证或创建具有 Distributor 权限的 IAM 实例配置文件
默认情况下，AWS Systems Manager 没有在您的实例上执行操作的权限。您必须通过使用 AWS Identity and Access Management (IAM) 实例配置文件来授予访问权限。实例配置文件是一个容器，可在启动时将 IAM 角色信息传递给 Amazon Elastic Compute Cloud (Amazon EC2) 实例。此要求适用于所有 Systems Manager 工具的权限，而不仅仅是 Distributor 的权限。
**注意**
配置边缘设备以运行 AWS IoT Greengrass Core 软件和 SSM Agent 时，请指定一个 IAM 服务角色，以便 Systems Manager 对其执行操作。您无需使用实例配置文件配置托管式边缘设备。
如果您已使用其他 Systems Manager 工具（例如 Run Command 和State Manager），说明已将具有 Distributor 所需权限的实例配置文件附加到实例。确保您有权执行 Distributor 任务的最简单方法是，将 **AmazonSSMManagedInstanceCore** 策略附加到实例配置文件。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
## 控制用户对程序包的访问
使用 AWS Identity and Access Management (IAM) policy，可以控制哪些用户能够创建、部署和管理软件包。您还可以控制他们能在托管式节点上执行哪些 Run Command 和 State Manager API 操作。与 Distributor 一样，Run Command 和State Manager也都是 AWS Systems Manager 中的工具。
**ARN 格式**
用户定义的软件包与文档 Amazon Resource Name (ARNs) 相关联，其格式如下。
```
arn:aws:ssm:region:account-id:document/document-name
```
示例如下：
```
arn:aws:ssm:us-west-1:123456789012:document/ExampleDocumentName
```
您可以使用 AWS 提供的一对默认 IAM policy（一个用于终端用户，一个用于管理员）授予对 Distributor 活动的权限。或者，您也可以创建适合您的权限要求的自定义 IAM policy。
有关在 IAM policy 中使用变量的更多信息，请参阅 [IAM policy 元素：变量](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html)。
有关如何创建策略并将策略附加到用户或组的信息，请参阅**《IAM 用户指南》中的[创建 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) 及[添加和移除 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
## 创建或选择 Amazon S3 存储桶来存储 Distributor 软件包
在 AWS Systems Manager 控制台中使用**简单**工作流创建软件包时，您可以选择 Distributor 会将软件上载到的现有 Amazon Simple Storage Service（Amazon S3）存储桶。Distributor 是 AWS Systems Manager 中的一项工具。在 **Advanced (高级)** 工作流中，您必须在开始之前将软件或资产的 .zip 文件上载到 Amazon S3 存储桶中。无论在控制台中是使用 **Simple (简单)** 还是 **Advanced (高级)** 工作流或是使用 API 来创建软件包，在开始创建软件包之前，您都必须具有 Amazon S3 存储桶。作为软件包创建过程的一部分，Distributor 将可安装的软件和资产从此存储桶复制到内部 Systems Manager 存储。由于资产已复制到内部存储，因此您可以在软件包创建完成时删除 Amazon S3 存储桶或调整其用途。
有关如何创建存储桶的更多信息，请参阅 *Amazon Simple Storage Service 入门指南*中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)。有关如何运行 AWS CLI 命令创建存储桶的更多信息，请参阅 *AWS CLI 命令参考*中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html)。
# 处理 Distributor 程序包
您可以使用 AWS Systems Manager 控制台、AWS 命令行工具（AWS CLI 和 AWS Tools for PowerShell）及 AWS SDK，在 Distributor 中添加、管理或部署软件包。Distributor 是 AWS Systems Manager 中的一项工具。在将软件包添加到 Distributor 之前，请：
+ 创建和压缩可安装资产。
+ （可选）为软件包创建 JSON 清单文件。使用 Distributor 控制台中的 **Simple (简单)** 软件包创建过程不需要执行此操作。简单软件包创建会生成一个 JSON 清单文件。
您可以使用 AWS Systems Manager 控制台或文本或 JSON 编辑器来创建清单文件。
+ 让 Amazon Simple Storage Service (Amazon S3) 存储桶准备好存储可安装的资产或软件。如果您使用 **Advanced (高级)** 软件包创建过程，在开始之前，请先将资产上载到您的 Amazon S3 存储桶。
**注意**
完成软件包创建后，您可以删除此存储桶或调整其用途，因为 Distributor 会在软件包创建过程中将软件包内容移动到内部 Systems Manager 存储桶。
AWS 发布的软件包已打包，可随时进行部署。要将 AWS 发布的软件包部署到托管式节点，请参阅 [安装或更新 Distributor 软件包](distributor-working-with-packages-deploy.md)。
您可以共享 AWS 账户 之间的 Distributor 软件包。在 AWS CLI 命令中使用从另一个账户共享的软件包时，请使用该软件包的 Amazon Resource Name (ARN)，而不是软件包名称。
**Topics**
+ [在 Distributor 中查看软件包](distributor-view-packages.md)
+ [在 Distributor 中创建软件包](distributor-working-with-packages-create.md)
+ [在控制台中编辑 Distributor 软件包权限](distributor-working-with-packages-ep.md)
+ [在控制台中编辑 Distributor 软件包标签](distributor-working-with-packages-tags.md)
+ [为 Distributor 软件包添加版本](distributor-working-with-packages-version.md)
+ [安装或更新 Distributor 软件包](distributor-working-with-packages-deploy.md)
+ [卸载 Distributor 软件包](distributor-working-with-packages-uninstall.md)
+ [删除 Distributor 软件包](distributor-working-with-packages-dpkg.md)
# 在 Distributor 中查看软件包
要查看可用于安装的软件包，可以使用 AWS Systems Manager 控制台或您的首选 AWS 命令行工具。Distributor 是 AWS Systems Manager 中的一项工具。要访问 Distributor，请打开 AWS Systems Manager 控制台，然后在左侧导航窗格中选择 **Distributor**。您将看到可供您使用的所有软件包。
以下小节介绍如何使用您的首选命令行工具查看 Distributor 软件包。
## 使用命令行查看软件包
本节包含有关如何使用您的首选命令行工具查看使用提供的命令的 Distributor 软件包的信息。
------
#### [ Linux & macOS ]
**在 Linux 上使用 AWS CLI 查看软件包**
+ 要查看所有软件包（不包含共享软件包），请运行以下命令。
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package
```
+ 要查看 Amazon 拥有的所有软件包，请运行以下命令。
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package Key=Owner,Values=Amazon
```
+ 要查看第三方拥有的所有软件包，请运行以下命令。
```
aws ssm list-documents \
--filters Key=DocumentType,Values=Package Key=Owner,Values=ThirdParty
```
------
#### [ Windows ]
**在 Windows 上使用 AWS CLI 查看软件包**
+ 要查看所有软件包（不包含共享软件包），请运行以下命令。
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package
```
+ 要查看 Amazon 拥有的所有软件包，请运行以下命令。
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package Key=Owner,Values=Amazon
```
+ 要查看第三方拥有的所有软件包，请运行以下命令。
```
aws ssm list-documents ^
--filters Key=DocumentType,Values=Package Key=Owner,Values=ThirdParty
```
------
#### [ PowerShell ]
**使用 Tools for PowerShell 查看软件包**
+ 要查看所有软件包（不包含共享软件包），请运行以下命令。
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "DocumentType"
$filter.Values = "Package"
Get-SSMDocumentList `
-Filters @($filter)
```
+ 要查看 Amazon 拥有的所有软件包，请运行以下命令。
```
$typeFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$typeFilter.Key = "DocumentType"
$typeFilter.Values = "Package"
$ownerFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$ownerFilter.Key = "Owner"
$ownerFilter.Values = "Amazon"
Get-SSMDocumentList `
-Filters @($typeFilter,$ownerFilter)
```
+ 要查看第三方拥有的所有软件包，请运行以下命令。
```
$typeFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$typeFilter.Key = "DocumentType"
$typeFilter.Values = "Package"
$ownerFilter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$ownerFilter.Key = "Owner"
$ownerFilter.Values = "ThirdParty"
Get-SSMDocumentList `
-Filters @($typeFilter,$ownerFilter)
```
------
# 在 Distributor 中创建软件包
要创建软件包，请准备您的可安装软件或资产，每个操作系统平台一个文件。需要至少一个文件才能创建软件包。
有时，不同的平台可以使用同一个文件，但附加到软件包的所有文件都必须列在清单的 `Files` 部分中。如果您在控制台中使用简单工作流创建软件包，则会为您生成清单。最多可以向一个文档附加 20 个文件。每个文件的最大大小为 1 GB。有关支持的平台的更多信息，请参阅 [支持的软件包平台和架构](distributor.md#what-is-a-package-platforms)。
创建软件包时，系统会创建新的 [SSM 文档](documents.md)。借助此文档，您可以将该软件包部署到托管式节点。
仅出于演示目的，您可以从我们的网站下载示例软件包 [ExplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip)。在示例软件包中包括一个完整 JSON 清单和三个 .zip 文件，这些文件包含 PowerShell v7.0.0 的安装程序。安装和卸载脚本不包含有效命令。虽然您必须在 **Advanced (高级)** 工作流中将每个软件可安装文件和脚本压缩为 .zip 文件以创建软件包，但您不会在 **Simple (简单)** 工作流中压缩可安装资产。
**Topics**
+ [使用简单工作流创建软件包](#distributor-working-with-packages-create-simple)
+ [使用高级工作流创建软件包](#distributor-working-with-packages-create-adv)
## 使用简单工作流创建软件包
本节介绍如何通过在 Distributor 控制台中选择**简单**软件包创建工作流在 Distributor 中创建软件包。Distributor 是 AWS Systems Manager 中的一项工具。要创建软件包，请准备您的可安装资产，每个操作系统平台一个文件。需要至少一个文件才能创建软件包。**简单**软件包创建过程为您生成安装和卸载脚本、文件哈希以及 JSON 格式的清单。**简单**工作流处理上传和压缩可安装文件以及创建新软件包和关联的 [SSM 文档](documents.md)的过程。有关支持的平台的更多信息，请参阅 [支持的软件包平台和架构](distributor.md#what-is-a-package-platforms)。
在使用简单方法创建软件包时，Distributor 将为您创建 `install` 和 `uninstall` 脚本。但是，当您为就地更新创建软件包时，您必须在 **Update script (更新脚本)** 选项卡上提供自己的 `update` 脚本内容。在为 `update` 脚本添加输入命令时，Distributor 将该脚本与 `install` 和 `uninstall` 脚本一起包含在它创建的 .zip 包中。
**注意**
使用 `In-place` 更新选项，可将新文件或更新的文件添加到现有的软件包安装中，而无需使关联的应用程序离线。
**若要使用简单工作流创建软件包**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择 **Create package (创建软件包)**，然后选择**简单**。
1. 在 **Create package (创建软件包)** 页面上，输入软件包的名称。软件包名称可以包含字母、数字、句点、短划线和下划线。名称应足够通用，以适用于所有版本的软件包附件，但又足够具体，可用于识别软件包的用途。
1. （可选）对于 **Version name (版本名称)**，请输入版本名称。版本名称最多可以包含 512 个字符，并且不能包含特殊字符。
1. 对于 **Location (位置)**，请使用存储桶名称和前缀或存储桶 URL 选择一个存储桶。
1. 对于 **Upload software**（上载软件），选择 **Add software**（添加软件），然后导航到具有 `.rpm`、`.msi` 或 `.deb` 扩展名的可安装软件文件。如果文件名包含空格，则上载将失败。您可以在单个操作中上传多个软件文件。
1. 对于**目标平台**，请验证为每个可安装文件显示的目标操作系统平台是否正确。如果显示的操作系统不正确，请从下拉列表中选择正确的操作系统。
对于**简单**软件包创建工作流中，由于您仅将每个可安装文件上传一次，因此，需要使用额外的步骤以指示 Distributor 在多个操作系统上将单个文件指定为目标。例如，如果您上传名为 `Logtool_v1.1.1.rpm` 的可安装软件文件，则必须更改**简单**工作流中的某些默认值，以同时在受支持的 Amazon Linux 和 Ubuntu Server 操作系统版本上将相同的软件指定为目标。在针对多个平台时，请执行以下操作之一。
+ 改用**高级**工作流，在开始之前将每个可安装文件压缩为 .zip 文件，然后手动编写清单，以便在多个操作系统平台或版本中将一个可安装文件指定为目标。有关更多信息，请参阅 [使用高级工作流创建软件包](#distributor-working-with-packages-create-adv)。
+ 在**简单**工作流中手动编辑清单文件，以便在多个操作系统平台或版本中将 .zip 文件指定为目标。有关如何执行此操作的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](#packages-manifest) 中步骤 4 的末尾。
1. 对于 **Platform version (平台版本)**，验证并确保所显示的操作系统平台版本是 **\$1any**（主要发行版本后跟一个通配符 (7.\$1)），或您希望软件适用于的确切操作系统发行版本。有关指定操作系统平台版本的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](#packages-manifest) 中的步骤 4。
1. 对于 **Architecture (架构)**，请从下拉列表中为每个可安装文件选择正确的处理器架构。有关支持的处理器架构的更多信息，请参阅 [支持的软件包平台和架构](distributor.md#what-is-a-package-platforms)。
1. （可选）展开 **Scripts (脚本)**，然后查看 Distributor 为可安装软件生成的脚本。
1. （可选）要提供用于就地更新的更新脚本，请展开 **Scripts（脚本）**，选择 **Update script（更新脚本）**选项卡，然后输入更新脚本命令。
Systems Manager 不会代表您生成更新脚本。
1. 要添加更多可安装的软件文件，请选择 **Add software (添加软件)**。否则，转到下一步。
1. （可选）展开**清单**，然后审核 Distributor 为您的可安装软件包生成的 JSON 清单。如果您在开始此过程后更改了有关软件的任何信息（例如平台版本或目标平台），请选择 **Generate manifest (生成清单)** 以显示更新的软件包清单。
如果要将可在多个操作系统上安装的软件指定为目标，则可以手动编辑清单，如步骤 8 中所述。有关编辑该清单的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](#packages-manifest)。
1. 选择 **Create package (创建软件包)**。
等待 Distributor 完成上传软件和创建软件包。 Distributor 显示每个可安装文件的上传状态。根据要添加的软件包的数量和大小，这可能需要几分钟时间。Distributor 会自动将您重定向到新软件包的 **Package details (软件包详细信息)** 页面，但您可以选择在上载软件之后自行打开此页面。**Package details (软件包详细信息)** 页面不会显示有关软件包的所有信息，直到 Distributor 完成软件包创建过程为止。要停止上传和软件包创建过程，请选择**取消**。
如果 Distributor 无法上载任何软件可安装文件，它会显示 **Upload failed (上载失败)** 消息。要重试上传，请选择 **Retry upload (重试上传)**。有关如何排除软件包创建失败的更多信息，请参阅 [AWS Systems Manager Distributor 故障排除](distributor-troubleshooting.md)。
## 使用高级工作流创建软件包
在本节中，了解高级用户在将压缩有安装和卸载脚本的可安装资产以及 JSON 清单文件上载到 Amazon S3 存储桶后，如何能在 Distributor 中创建软件包。
要创建软件包，请准备可安装资产的 .zip 文件（每个操作系统平台一个 .zip 文件）。需要具有至少一个 .zip 文件才能创建软件包。接下来，创建 JSON 清单。清单包含指向软件包代码文件的指针。在将所需的代码文件添加到一个文件夹或目录，并为清单填充正确的值后，将软件包上载到 Amazon S3 存储桶。
您可以从我们的网站下载示例软件包 [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip)。在示例软件包中包含一个完整 JSON 清单和三个 .zip 文件。
**Topics**
+ [步骤 1：创建 ZIP 文件](#packages-zip)
+ [步骤 2：创建 JSON 软件包清单](#packages-manifest)
+ [步骤 3：将软件包和清单上载到 Amazon S3 存储桶](#packages-upload-s3)
+ [步骤 4：将软件包添加到 Distributor](#distributor-working-with-packages-add)
### 步骤 1：创建 ZIP 文件
软件包至少包含软件或可安装资产的一个 .zip 文件。对于要支持的每个操作系统，软件包包含一个 .zip 文件，除非可以在多个操作系统上安装一个 .zip 文件。例如，受支持的 Red Hat Enterprise Linux 和 Amazon Linux 实例版本通常可以运行相同的 .RPM 可执行文件。因此，只需在软件包中附加一个 .zip 文件即可支持这两种操作系统。
**所需的文件**
需要在每个 .zip 文件中包含以下项目：
+ **install** 和 **uninstall** 脚本。基于 Windows Server 的托管式节点需要使用 PowerShell 脚本（名为 `install.ps1` 和 `uninstall.ps1` 的脚本）。基于 Linux 的托管式节点需要使用 Shell 脚本（名为 `install.sh` 和 `uninstall.sh` 的脚本）。SSM Agent 运行 **install** 和 **uninstall** 脚本中的指令。
例如，安装脚本可能会运行安装程序（例如 .rpm 或 .msi），它们可能会复制文件，或者它们可能会设置配置。
+ 可执行文件、安装程序软件包（.rpm、.deb、.msi 等）、其他脚本或配置文件。
**可选的文件**
以下项目在每个 .zip 文件中是可选的：
+ **update** 脚本。通过提供更新脚本，您可以使用 `In-place update` 选项安装软件包。如果要将新文件或更新的文件添加到现有的软件包安装中，`In-place update` 选项不会在执行更新时使软件包应用程序离线。基于 Windows Server 的托管式节点需要使用 PowerShell 脚本（名为 `update.ps1` 的脚本）。基于 Linux 的托管式节点需要使用 shell 脚本（名为 `update.sh` 的脚本）。SSM Agent 运行 **update** 脚本中的指令。
有关安装或更新软件包的更多信息，请参阅 [安装或更新 Distributor 软件包](distributor-working-with-packages-deploy.md)。
有关 .zip 文件的示例（包括示例 **install** 和 **uninstall** 脚本），请下载示例软件包 [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip)。
### 步骤 2：创建 JSON 软件包清单
准备并压缩可安装文件后，需要创建一个 JSON 清单。模板如下。本节中的过程将对清单模板的各个部分进行说明。您可以使用 JSON 编辑器在单独的文件中创建此清单。或者，也可以在创建软件包时在 AWS Systems Manager 控制台中创建清单。
```
{
"schemaVersion": "2.0",
"version": "your-version",
"publisher": "optional-publisher-name",
"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-3.zip"
}
}
}
},
"files": {
".zip-file-name-1.zip": {
"checksums": {
"sha256": "checksum"
}
},
".zip-file-name-2.zip": {
"checksums": {
"sha256": "checksum"
}
}
}
}
```
**创建 JSON 软件包清单**
1. 将架构版本添加到清单。在此版本中，架构版本始终为 `2.0`。
```
{ "schemaVersion": "2.0",
```
1. 将用户定义的软件包版本添加到清单。这也是您在将软件包添加到 Distributor 时指定的 **Version name (版本名称)** 的值。添加软件包时，它将成为 Distributor 创建的 AWS Systems Manager 文档的一部分。您还可以在 `AWS-ConfigureAWSPackage` 文档中将此值作为输入提供，以安装除最新版本以外的软件包版本。`version` 值可以包含字母、数字、下划线、连字符和句点，最大长度为 128 个字符。建议使用易读的软件包版本，以便您和其他管理员在部署时更轻松地指定确切的软件包版本。示例如下：
```
"version": "1.0.1",
```
1. （可选）添加发布者名称。示例如下：
```
"publisher": "MyOrganization",
```
1. 添加软件包。`"packages"` 部分描述软件包中的 .zip 文件支持的平台、发行版本和架构。有关更多信息，请参阅 [支持的软件包平台和架构](distributor.md#what-is-a-package-platforms)。
*platform-version* 可以是通配符值 `_any`。可以使用它指示 .zip 文件支持任何平台版本。您还可以指定一个主要发行版本，后跟通配符，以使所有次要版本受到支持，例如 7.\$1。如果您选择为某一特定操作系统版本指定 *platform-version* 值，请确保它与您设为目标的操作系统 AMI 的确切发行版本匹配。以下是用于获取正确的操作系统值的推荐资源。
+ 在基于 Windows Server 的托管式节点上，发行版本可用作 Windows Management Instrumentation (WMI) 数据。您可以运行以下命令提示符命令来获取版本信息，然后解析 `version` 的结果。
```
wmic OS get /format:list
```
+ 在基于 Linux 的托管式节点上，可以通过先扫描操作系统版本（下面的命令）来获取版本。然后查找 `VERSION_ID` 的值。
```
cat /etc/os-release
```
如果这未返回您需要的结果，请运行下面的命令，以从 `/etc/lsb-release` 文件获取 LSB 版本信息，并查找 `DISTRIB_RELEASE` 的值。
```
lsb_release -a
```
如果上述方法都不奏效，您通常可以根据分发软件包查找版本。例如，在 Debian Server 上，您可以扫描 `/etc/debian_version` 文件；在 Red Hat Enterprise Linux 上，则可以扫描 `/etc/redhat-release` 文件。
```
hostnamectl
```
```
"packages": {
"platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-1.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-2.zip"
}
}
},
"another-platform": {
"platform-version": {
"architecture": {
"file": ".zip-file-name-3.zip"
}
}
}
}
```
示例如下：在该示例中，操作系统平台为 `amazon`，支持的发行版本为 `2016.09`，架构为 `x86_64`，支持该平台的 .zip 文件为 `test.zip`。
```
{
"amazon": {
"2016.09": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
您可以添加通配符值 `_any` 来指示此软件包支持父元素的所有版本。例如，要指示 Amazon Linux 的任何发行版本都支持此软件包，您的软件包语句应与以下内容相似。您可以在版本或架构级别使用 `_any` 通配符来支持平台的所有版本、某个版本的所有架构或某个平台的所有版本和所有架构。
```
{
"amazon": {
"_any": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
以下示例添加 `_any` 来表明 Amazon Linux 2016.09 的所有架构都支持第一个软件包 `data1.zip`。Amazon Linux 的所有版本都支持第二个软件包 `data2.zip`，但此软件包仅适用于采用 `x86_64` 架构的托管式节点。`2023.8` 和 `_any` 版本都是 `amazon` 下的条目。具有一个平台 (Amazon Linux)，但支持的版本、架构和关联的 .zip 文件不同。
```
{
"amazon": {
"2023.8": {
"_any": {
"file": "data1.zip"
}
},
"_any": {
"x86_64": {
"file": "data2.zip"
}
}
}
}
```
如果 .zip 文件支持多个平台，您可以在清单的 `"packages"` 部分中多次引用该 .zip 文件。例如，如果您有一个同时支持 Red Hat Enterprise Linux 8.x 版本和 Amazon Linux 的 .zip 文件，您可以在 `"packages"` 部分中包含两个指向相同 .zip 文件的条目，如以下示例中所示。
```
{
"amazon": {
"2023.8.20250715 ": {
"x86_64": {
"file": "test.zip"
}
}
},
"redhat": {
"8.*": {
"x86_64": {
"file": "test.zip"
}
}
}
},
```
1. 添加属于步骤 4 中的软件包的 .zip 文件列表。每个文件条目都需要文件名和 `sha256` 哈希值校验和。清单中的校验和值必须与压缩资产中的 `sha256` 哈希值匹配，以防软件包安装失败。
要从可安装资产获取确切的校验和，可以运行以下命令。在 Linux 上，运行 `shasum -a 256 file-name.zip` 或 `openssl dgst -sha256 file-name.zip`。在 Windows 上，在 [PowerShell](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-filehash?view=powershell-6) 中运行 `Get-FileHash -Path path-to-.zip-file` cmdlet。
清单的 `"files"` 部分包含对软件包中的每个 .zip 文件的引用。
```
"files": {
"test-agent-x86.deb.zip": {
"checksums": {
"sha256": "EXAMPLE2706223c7616ca9fb28863a233b38e5a23a8c326bb4ae241dcEXAMPLE"
}
},
"test-agent-x86_64.deb.zip": {
"checksums": {
"sha256": "EXAMPLE572a745844618c491045f25ee6aae8a66307ea9bff0e9d1052EXAMPLE"
}
},
"test-agent-x86_64.nano.zip": {
"checksums": {
"sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel8-x86.nano.zip": {
"checksums": {
"sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
},
"test-agent-x86.msi.zip": {
"checksums": {
"sha256": "EXAMPLE12a4abb10315aa6b8a7384cc9b5ca8ad8e9ced8ef1bf0e5478EXAMPLE"
}
},
"test-agent-x86_64.msi.zip": {
"checksums": {
"sha256": "EXAMPLE63ccb86e830b63dfef46995af6b32b3c52ce72241b5e80c995EXAMPLE"
}
},
"test-agent-rhel8-x86.rpm.zip": {
"checksums": {
"sha256": "EXAMPLE13df60aa3219bf117638167e5bae0a55467e947a363fff0a51EXAMPLE"
}
}
}
```
1. 添加软件包信息后，保存并关闭清单文件。
下面是一个已完成的清单的示例。在该示例中，您具有一个 .zip 文件 `NewPackage_LINUX.zip`，它支持多个平台，但仅在 `"files"` 部分中引用一次。
```
{
"schemaVersion": "2.0",
"version": "1.7.1",
"publisher": "Amazon Web Services",
"packages": {
"windows": {
"_any": {
"x86_64": {
"file": "NewPackage_WINDOWS.zip"
}
}
},
"amazon": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
},
"ubuntu": {
"_any": {
"x86_64": {
"file": "NewPackage_LINUX.zip"
}
}
}
},
"files": {
"NewPackage_WINDOWS.zip": {
"checksums": {
"sha256": "EXAMPLEc2c706013cf8c68163459678f7f6daa9489cd3f91d52799331EXAMPLE"
}
},
"NewPackage_LINUX.zip": {
"checksums": {
"sha256": "EXAMPLE2b8b9ed71e86f39f5946e837df0d38aacdd38955b4b18ffa6fEXAMPLE"
}
}
}
}
```
#### 软件包示例
您可以从我们的网站下载示例软件包 [ExamplePackage.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/ExamplePackage.zip)。在示例软件包中包含一个完整 JSON 清单和三个 .zip 文件。
### 步骤 3：将软件包和清单上载到 Amazon S3 存储桶
将所有 .zip 文件复制或移动到一个文件夹或目录以准备软件包。有效的软件包需要具有在[步骤 2：创建 JSON 软件包清单](#packages-manifest)中创建的清单以及在清单文件列表中指定的所有 .zip 文件。
**将软件包和清单上载到 Amazon S3**
1. 将清单中指定的所有 .zip 存档文件复制或移动到一个文件夹或目录中。不要压缩您要将 .zip 归档文件和清单文件移动到的文件夹或目录。
1. 创建存储桶或选择现有的存储桶。有关更多信息，请参阅 *Amazon Simple Storage Service 入门指南*中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)。有关如何运行 AWS CLI 命令创建存储桶的更多信息，请参阅 *AWS CLI 命令参考*中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html)。
1. 将此文件夹或目录上载到存储桶。有关更多信息，请参阅 *Amazon Simple Storage Service 入门指南*中的[向存储桶添加对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PuttingAnObjectInABucket.html)。如果打算将 JSON 清单粘贴到 AWS Systems Manager 控制台，请不要上载该清单。有关如何运行 AWS CLI 命令以将文件上载到存储桶的更多信息，请参阅 *AWS CLI 命令参考*中的 [https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html](https://docs.aws.amazon.com/cli/latest/reference/s3/mv.html)。
1. 在存储桶的主页上，选择您上载的文件夹或目录。如果您将文件上传到存储桶中的子文件夹，请务必记下子文件夹（也称为*前缀*）。您需要此前缀以将软件包添加到 Distributor。
### 步骤 4：将软件包添加到 Distributor
您可以使用 AWS Systems Manager 控制台、AWS 命令行工具（AWS CLI 和 AWS Tools for PowerShell）或 AWS 开发工具包将新软件包添加到 Distributor。添加软件包时，您将添加一个新的 [SSM 文档](documents.md)。使用此文档，可以将该软件包部署到托管式节点。
**Topics**
+ [使用控制台添加软件包](#create-pkg-console)
+ [使用 AWS CLI 添加软件包](#create-pkg-cli)
#### 使用控制台添加软件包
可使用 AWS Systems Manager 控制台创建软件包。准备好您在[步骤 3：将软件包和清单上载到 Amazon S3 存储桶](#packages-upload-s3)中将软件包上传到的存储桶的名称。
**将软件包添加到 Distributor（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择 **Create package (创建软件包)**，然后选择**高级**。
1. 在 **Create package (创建软件包)** 页面上，输入软件包的名称。软件包名称可以包含字母、数字、句点、短划线和下划线。名称应足够通用，以适用于所有版本的软件包附件，但又足够具体，可用于识别软件包的用途。
1. 对于 **Version name (版本名称)**，请输入清单文件中的 `version` 条目的确切值。
1. 对于 **S3 bucket name (S3 存储桶名称)**，请选择在[步骤 3：将软件包和清单上载到 Amazon S3 存储桶](#packages-upload-s3)中将 .zip 文件和清单上传到的存储桶的名称。
1. 对于 **S3 key prefix (S3 键前缀)**，请输入存储 .zip 文件和清单的存储桶子文件夹。
1. 对于 **Manifest (清单)**，请选择 **Extract from package (从软件包提取)** 以使用随 .zip 文件上载到 Amazon S3 存储桶的清单。
（可选）如果未将 JSON 清单上载到存储 .zip 文件的 Amazon S3 存储桶，请选择 **New manifest (新建清单)**。您可以在 JSON 编辑器字段中编写或粘贴整个清单。有关如何创建 JSON 清单的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](#packages-manifest)。
1. 当您处理完清单后，选择 **Create package (创建软件包)**。
1. 等待 Distributor 从 .zip 文件和清单中创建软件包。根据要添加的软件包的数量和大小，这可能需要几分钟时间。Distributor 会自动将您重定向到新软件包的 **Package details (软件包详细信息)** 页面，但您可以选择在上传软件之后自行打开此页面。**Package details (软件包详细信息)** 页面不会显示有关软件包的所有信息，直到 Distributor 完成软件包创建过程为止。要停止上传和软件包创建过程，请选择**取消**。
#### 使用 AWS CLI 添加软件包
可使用 AWS CLI 创建软件包。准备好您在[步骤 3：将软件包和清单上载到 Amazon S3 存储桶](#packages-upload-s3)中将软件包上传到的存储桶的 URL。
**若要使用 AWS CLI 将软件包添加到 Amazon S3**
1. 要使用 AWS CLI 创建软件包，请运行以下命令，将 *package-name* 替换为您的软件包名称，将 *path-to-manifest-file* 替换为 JSON 清单文件的文件路径。amzn-s3-demo-bucket 是存储整个软件包的 Amazon S3 存储桶的 URL。在 Distributor 中运行 **create-document** 命令时，为 `--document-type` 指定 `Package` 值。
如果未将清单文件添加到 Amazon S3 存储桶，则 `--content` 参数值将是 JSON 清单文件的文件路径。
```
aws ssm create-document \
--name "package-name" \
--content file://path-to-manifest-file \
--attachments Key="SourceUrl",Values="amzn-s3-demo-bucket" \
--version-name version-value-from-manifest \
--document-type Package
```
示例如下：
```
aws ssm create-document \
--name "ExamplePackage" \
--content file://path-to-manifest-file \
--attachments Key="SourceUrl",Values="https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage" \
--version-name 1.0.1 \
--document-type Package
```
1. 通过运行以下命令验证软件包是否已添加并显示软件包清单，将 *package-name* 替换为您的软件包名称。要获取文档的特定版本（不同于软件包的版本），可以添加 `--document-version` 参数。
```
aws ssm get-document \
--name "package-name"
```
有关可以与 **create-document** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html)。有关可以与 **get-document** 命令配合使用的其他选项的信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-document.html)。
# 在控制台中编辑 Distributor 软件包权限
在将软件包添加到 Distributor（AWS Systems Manager 中的一项工具）后，即可在 Systems Manager 控制台中编辑该软件包的权限。您可以将其他 AWS 账户添加到软件包的权限中。程序包只能与同一个 AWS 区域中的其他账户共享。不支持跨区域共享。预设情况下，软件包设置为 **Private (私有)**，表示只有有权访问软件包创建者的 AWS 账户的用户才能查看该软件包的软件包信息，以及更新或删除该软件包。如果接受 **Private (私有)** 权限，则可以跳过此过程。
**注意**
您可以更新与 20 个或以下账户共享的软件包的权限。
**若要在控制台中编辑软件包权限**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 **Packages (软件包)** 页面上，选择要编辑其权限的软件包。
1. 在 **Package details (软件包详细信息)** 选项卡上，选择 **Edit permissions (编辑权限)** 更改权限。
1. 对于 **Edit permissions (编辑权限)**，请选择 **Shared with specific accounts (与特定账户共享)**。
1. 在 **Shared with specific accounts (与特定账户共享)** 下，添加 AWS 账户 账号，每次添加一个。完成后，选择**保存**。
# 在控制台中编辑 Distributor 软件包标签
将软件包添加到 Distributor（AWS Systems Manager 中的一项工具）后，即可在 Systems Manager 控制台中编辑该软件包的标签。这些标签将应用于该软件包，并且不与要部署该软件包的托管式节点上的标签相关联。标签是区分大小写的键值对，可帮助您按照组织相关标准对软件包进行分组和筛选。如果不希望添加标签，则要准备好安装软件包或添加新版本。
**若要在控制台中编辑软件包标签**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 **Packages (软件包)** 页面上，选择要编辑其标签的软件包。
1. 在 **Package details (软件包详细信息)** 选项卡上的 **Tags (标签)** 中，选择 **Edit (编辑)**。
1. 对于 **Add tags (添加标签)**，请输入一个标签键或标签键值对，然后选择 **Add (添加)**。如果要添加更多标签，请重复此操作。要删除标签，请选择窗口底部标签上的 **X**。
1. 为软件包添加完标签后，选择 **Save (保存)**。
# 为 Distributor 软件包添加版本
要添加软件包版本，您需要[创建软件包](distributor-working-with-packages-create.md)，然后使用 Distributor 通过向旧版本已存在的 AWS Systems Manager（SSM）文档中添加条目来添加软件包版本。Distributor 是 AWS Systems Manager 中的一项工具。为了节省时间，可以更新旧版本包的清单，更改清单中 `version` 条目的值（例如，从 `Test_1.0` 更改为 `Test_2.0`），并将其保存为新版本的清单。Distributor 控制台中的简单 **Add version (添加版本)** 工作流将为您更新清单文件。
新的软件包版本可以：
+ 替换附加到当前版本的至少一个可安装文件。
+ 添加新的可安装文件以支持其他平台。
+ 删除文件以停止对特定平台的支持。
较新的版本可以使用相同的 Amazon Simple Storage Service (Amazon S3) 存储桶，但必须具有末尾显示不同文件名的 URL。您可以使用 Systems Manager 控制台或 AWS Command Line Interface (AWS CLI) 来添加新版本。将具有确切名称的可安装文件上载为 Amazon S3 存储桶中的现有可安装文件将覆盖现有文件。没有可安装的文件从旧版本复制到新版本；您必须从旧版本上传可安装文件才能使它们成为新版本的一部分。在 Distributor 完成创建新软件包版本后，您可以删除 Amazon S3 存储桶或调整其用途，因为 Distributor 在版本控制过程中会将软件复制到内部 Systems Manager 存储桶。
**注意**
每个软件包限制为最多 25 个版本。您可以删除不再需要的版本。
**Topics**
+ [使用控制台添加软件包版本](#add-pkg-version)
+ [使用 AWS CLI 添加软件包版本](#add-pkg-version-cli)
## 使用控制台添加软件包版本
在执行以下步骤前，请按照[在 Distributor 中创建软件包](distributor-working-with-packages-create.md)中的说明执行操作，为此版本创建一个新的软件包。然后，使用 Systems Manager 控制台将新的软件包版本添加到 Distributor。
### 使用简单工作流添加软件包版本
要使用 **Simple (简单)** 工作流程添加软件包版本，请准备更新的可安装文件或添加可安装文件，以支持更多平台和架构。然后，使用 Distributor 上传新的和更新的可安装文件并添加软件包版本。Distributor 控制台中的简化 **Add version (添加版本)** 工作流程将为您更新清单文件和关联的 SSM 文档。
**若要使用简单工作流添加软件包版本**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择要为其添加其他版本的软件包。
1. 在 **Add version (添加版本)** 页面上，选择 **Simple (简单)**。
1. 对于 **Version name (版本名称)**，请输入版本名称。新版本的版本名称必须与旧版本名称不同。版本名称最多可以包含 512 个字符，并且不能包含特殊字符。
1. 对于 **S3 存储桶名称**，从列表中选择现有的 S3 存储桶。这可以是用于存储旧版本的可安装文件的同一个存储桶，但可安装文件名必须不同，以避免覆盖存储桶中的现有可安装文件。
1. 对于 **S3 key prefix (S3 键前缀)**，请输入存储可安装资产的存储桶子文件夹。
1. 对于 **Upload software (上载软件)**，请导航到要附加到新版本的可安装软件文件。现有版本中的可安装文件不会自动复制到新版本；如果您希望任何相同的可安装文件成为新版本的一部分，则必须上载旧版软件包中的任何可安装文件。您可以在单个操作中上传多个软件文件。
1. 对于**目标平台**，请验证为每个可安装文件显示的目标操作系统平台是否正确。如果显示的操作系统不正确，请从下拉列表中选择正确的操作系统。
在**简单**版本控制工作流程中，由于您只上传每个可安装文件一次，因此需要额外的步骤在多个操作系统上将单个文件指定为目标。例如，如果您上传名为 `Logtool_v1.1.1.rpm` 的可安装软件文件，则必须更改**简单**工作流程中的某些默认值，以指示 Distributor 同时在 Amazon Linux 和 Ubuntu Server 操作系统上将相同的软件指定为目标。您可以执行以下操作之一来解决此限制。
+ 改用**高级**版本控制工作流程，在开始之前将每个可安装文件压缩为 .zip 文件，然后手动编写清单，以便在多个操作系统平台或版本中将一个可安装文件指定为目标。有关更多信息，请参阅 [使用高级工作流添加软件包版本](#add-pkg-version-adv)。
+ 在**简单**工作流中手动编辑清单文件，以便在多个操作系统平台或版本中将 .zip 文件指定为目标。有关如何执行此操作的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest) 中步骤 4 的末尾。
1. 对于**平台版本**，验证并确保所显示的操作系统平台版本是 **\$1any**（主要发行版本后跟一个通配符 (8.\$1)），或您希望软件适用于的确切操作系统发行版本。有关指定平台版本的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest) 中的步骤 4。
1. 对于**架构**，请从下拉列表中为每个可安装文件选择正确的处理器架构。有关支持的架构的更多信息，请参阅 [支持的软件包平台和架构](distributor.md#what-is-a-package-platforms)。
1. （可选）展开 **Scripts (脚本)**，然后查看 Distributor 为可安装软件生成的安装和卸载脚本。
1. 要向新版本添加更多可安装的软件文件，请选择 **Add software (添加软件)**。否则，转到下一步。
1. （可选）展开**清单**，然后审核 Distributor 为您的可安装软件包生成的 JSON 清单。如果您在开始此过程后更改了有关可安装软件的任何信息（例如平台版本或目标平台），请选择**生成清单**以显示更新的软件包清单。
如果要将可在多个操作系统上安装的软件指定为目标，则可以手动编辑清单，如步骤 9 中所述。有关编辑该清单的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest)。
1. 完成添加软件和审核目标平台、版本和架构数据时，请选择 **Add version (添加版本)**。
1. 等待 Distributor 完成上传软件和创建新的软件包版本。Distributor 显示每个可安装文件的上传状态。根据要添加的软件包的数量和大小，这可能需要几分钟时间。Distributor 会自动将您重定向到软件包的 **Package details (软件包详细信息)** 页面，但您可以选择在上传软件之后自行打开此页面。**Package details (软件包详细信息)** 页面不会显示有关软件包的所有信息，直到 Distributor 完成创建新的软件包版本为止。要停止上传和软件包版本创建，请选择 **Stop upload (停止上传)**。
1. 如果 Distributor 无法上载任何软件可安装文件，它会显示 **Upload failed (上载失败)** 消息。要重试上传，请选择 **Retry upload (重试上传)**。有关如何排除软件包版本创建失败的更多信息，请参阅 [AWS Systems Manager Distributor 故障排除](distributor-troubleshooting.md)。
1. 在 Distributor 完成创建新的软件包版本后，在软件包的 **Details (详细信息)** 页面的 **Versions (版本)** 选项卡上，在可用软件包版本列表中查看新版本。通过以下方式设置软件包的默认版本：选择一个版本，然后选择 **Set default version (设置默认版本)**。
如果不设置默认版本，则最新的软件包版本即为默认版本。
### 使用高级工作流添加软件包版本
要添加软件包版本，您需要[创建软件包](distributor-working-with-packages-create.md)，然后使用 Distributor 通过向旧版本存在的 SSM 文档中添加条目来添加软件包版本。为了节省时间，可以更新旧版本包的清单，更改清单中 `version` 条目的值（例如，从 `Test_1.0` 更改为 `Test_2.0`），并将其保存为新版本的清单。您必须具有更新的清单才能使用**高级**工作流程添加新的软件包版本。
**若要使用高级工作流添加软件包版本**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择要向其添加其他版本的软件包，然后选择 **Add version (添加版本)**。
1. 对于 **Version name (版本名称)**，请输入位于清单文件的 `version` 条目中的确切值。
1. 对于 **S3 存储桶名称**，从列表中选择现有的 S3 存储桶。这可以是用于存储旧版本的可安装文件的同一个存储桶，但可安装文件名必须不同，以避免覆盖存储桶中的现有可安装文件。
1. 对于 **S3 key prefix (S3 键前缀)**，请输入存储可安装资产的存储桶子文件夹。
1. 对于 **Manifest (清单)**，请选择 **Extract from package (从软件包提取)** 以使用随 .zip 文件上传到 S3 存储桶的清单。
（可选）如果未将修订的 JSON 清单上载到存储 .zip 文件的 Amazon S3 存储桶，请选择 **New manifest (新建清单)**。您可以在 JSON 编辑器字段中编写或粘贴整个清单。有关如何创建 JSON 清单的更多信息，请参阅 [步骤 2：创建 JSON 软件包清单](distributor-working-with-packages-create.md#packages-manifest)。
1. 当您完成处理清单后，选择 **Add package version (添加软件包版本)**。
1. 在软件包的 **Details (详细信息)** 页面的 **Versions (版本)** 选项卡上，在可用软件包版本列表中查看新版本。通过以下方式设置软件包的默认版本：选择一个版本，然后选择 **Set default version (设置默认版本)**。
如果不设置默认版本，则最新的软件包版本即为默认版本。
## 使用 AWS CLI 添加软件包版本
您可以使用 AWS CLI 将新的软件包版本添加到 Distributor。在运行以下命令前，必须创建新的软件包版本并将其上传到 S3，如本主题开头所述。
**若要使用 AWS CLI 添加软件包版本**
1. 运行下面的命令并附上新软件包版本的条目来编辑 AWS Systems Manager 文档。将 *document-name* 替换为您的文档的名称。将 *amzn-s3-demo-bucket* 替换为您在 [步骤 3：将软件包和清单上载到 Amazon S3 存储桶](distributor-working-with-packages-create.md#packages-upload-s3) 中复制的 JSON 清单的 URL。*S3-bucket-URL-of-package* 是存储整个软件包的 Amazon S3 存储桶的 URL。将 *version-name-from-updated-manifest* 替换为清单中 `version` 的值。将 `--document-version` 参数设置为 `$LATEST`，以使与此软件包版本关联的文档成为文档的最新版本。
```
aws ssm update-document \
--name "document-name" \
--content "S3-bucket-URL-to-manifest-file" \
--attachments Key="SourceUrl",Values="amzn-s3-demo-bucket" \
--version-name version-name-from-updated-manifest \
--document-version $LATEST
```
示例如下：
```
aws ssm update-document \
--name ExamplePackage \
--content "https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage/manifest.json" \
--attachments Key="SourceUrl",Values="https://s3.amazonaws.com/amzn-s3-demo-bucket/ExamplePackage" \
--version-name 1.1.1 \
--document-version $LATEST
```
1. 运行以下命令来验证软件包已更新并显示包清单。将 *package-name* 替换为您的软件包名称，（可选）将 *document-version* 替换为更新的文档的版本号（不同于软件包的版本）。如果此软件包版本与文档的最新版本关联，则可以为可选的 `--document-version` 参数的值指定 `$LATEST`。
```
aws ssm get-document \
--name "package-name" \
--document-version "document-version"
```
有关可以与 **update-document** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-document.html)。
# 安装或更新 Distributor 软件包
您可以使用 Distributor（AWS Systems Manager 中的一项工具）将软件包部署到 AWS Systems Manager 托管式节点。要部署软件包，请使用 AWS 管理控制台 或 AWS Command Line Interface (AWS CLI)。一条命令只能部署一个软件包的一个版本。您可以安装新软件包或就地更新现有的安装。您可以选择部署软件包的特定版本，也可以选择始终部署软件包的最新版本。建议使用State Manager（AWS Systems Manager 中的一项工具）来安装软件包。使用 State Manager 有助于确保您的托管式节点始终运行最新版本的软件包。
**重要**
使用 Distributor 安装的软件包只能通过 Distributor 卸载。否则，Systems Manager 仍可能将应用程序注册为 `INSTALLED`，导致其他意外结果。
| Preference | AWS Systems Manager 操作 | 更多信息 |
| --- | --- | --- |
| 立即安装或更新软件包。 | Run Command | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html) |
| 按计划安装或更新软件包，以便安装始终包含默认版本。 | State Manager | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html) |
| 在具有特定标签或标签集的新托管式节点上自动安装软件包。例如，在新实例上安装 Amazon CloudWatch 代理。 | State Manager | 执行此操作的一种方法是向新托管式节点应用标签，然后在 State Manager 关联中将这些标签指定为目标。State Manager 会自动将关联中的软件包安装到具有匹配标签的托管式节点上。请参阅[了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。 |
**Topics**
+ [使用控制台一次性安装或更新软件包](#distributor-deploy-pkg-console)
+ [使用控制台计划软件包安装或更新](#distributor-deploy-sm-pkg-console)
+ [使用 AWS CLI 一次性安装软件包](#distributor-deploy-pkg-cli)
+ [使用 AWS CLI 一次性更新软件包](#distributor-update-pkg-cli)
+ [使用 AWS CLI 计划软件包安装](#distributor-smdeploy-pkg-cli)
+ [使用 AWS CLI 计划软件包更新](#distributor-smupdate-pkg-cli)
## 使用控制台一次性安装或更新软件包
您可以使用 AWS Systems Manager 控制台一次性安装或更新软件包。在配置一次性安装时，Distributor 使用 [AWS Systems Manager Run Command](run-command.md)（AWS Systems Manager 中的一项工具）来执行安装。
**若要使用控制台一次性安装或更新软件包**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择要安装的软件包。
1. 选择 **Install one time (一次性安装)**。
此命令将打开 Run Command，并选中命令文档 `AWS-ConfigureAWSPackage` 和 Distributor 软件包。
1. 对于 **Document version （文档版本）**，请选择要运行的 `AWS-ConfigureAWSPackage` 文档版本。
1. 对于**操作**，选择**安装**。
1. 对于 **Installation type (安装类型)**，请选择以下选项之一：
+ **Uninstall and reinstall (卸载并重新安装)**：完全卸载软件包，然后重新安装。在重新安装完成之前，应用程序不可用。
+ **In-place update (就地更新)**：根据您在 `update` 脚本中提供的指令，仅将新文件或更改的文件添加到现有安装中。应用程序在整个更新过程中保持可用。对于 AWS 已发布软件包，除 `AWSEC2Launch-Agent` 软件包外，不支持此选项。
1. 对于 **Name (名称)**，请确认输入了选定的软件包的名称。
1. （可选）对于 **Version (版本)**，请输入软件包的版本名称值。如果将此字段留空，Run Command 将安装在 Distributor 中选择的默认版本。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或设备或指定资源组，选择要在其上运行此操作的托管式节点。
**注意**
如果列表没有显示托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate Control**（速率控制）：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的目标数或百分比。
**注意**
如果您通过指定标签或资源组来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的托管式节点上失败后，何时在其他目标上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 在准备好安装软件包时，请选择 **Run (运行)**。
1. **Command status (命令状态)** 区域报告执行进度。如果命令仍在执行，请选择控制台左上角的刷新图标，直到 **Overall status (总体状态)** 或 **Detailed status (详细状态)** 列显示 **Success (成功)** 或 **Failed (失败)**。
1. 在 **Targets and outputs**（目标和输出）区域中，选择托管式节点名称旁边的按钮，然后选择 **View output**（查看输出）。
命令输出页面将显示命令执行的结果。
1. （可选）如果您选择将命令输出写入到 Amazon S3 存储桶，请选择 **Amazon S3** 以查看输出日志数据。
## 使用控制台计划软件包安装或更新
您可以使用 AWS Systems Manager 控制台计划安装或更新软件包。在计划安装或更新软件包时，Distributor 使用 [AWS Systems Manager State Manager](systems-manager-state.md) 进行安装或更新。
**若要使用控制台计划软件包安装**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 Distributor 主页上，选择要安装或更新的软件包。
1. 对于 **Package (软件包)**，请选择 **Install on a schedule (按计划安装)**。
此命令将打开 State Manager 并跳转到为您创建的新关联。
1. 对于 **Name (名称)**，请输入名称（例如，**Deploy-test-agent-package**）。您可以自由选择，但我们建议您这样做。名称不得包含空格。
1. 在 **Document (文档)** 列表中，已选定文档名称 `AWS-ConfigureAWSPackage`。
1. 对于 **Action (操作)**，请确认选择了 **Install (安装)**。
1. 对于 **Installation type (安装类型)**，请选择以下选项之一：
+ **Uninstall and reinstall (卸载并重新安装)**：完全卸载软件包，然后重新安装。在重新安装完成之前，应用程序不可用。
+ **In-place update (就地更新)**：根据您在 `update` 脚本中提供的指令，仅将新文件或更改的文件添加到现有安装中。应用程序在整个更新过程中保持可用。
1. 对于 **Name (名称)**，请确认输入了软件包的名称。
1. 对于 **Version (版本)**，如果要安装最新发布的版本以外的软件包版本，请输入版本标识符。
1. 对于 **Targets (目标)**，选择 **Selecting all managed instances in this account (选择此账户中的所有托管实例)**、**Specifying tags (指定标签)** 或 **Manually Selecting Instance (手动选择实例)**。如果使用标签将资源设置为目标，请在提供的字段中输入标签键和标签值。
**注意**
您可以通过选择 **Selecting all managed instances in this account**（选择此账户中的所有托管式实例）或 **Manually Selecting Instance**（手动选择实例）来选择托管式 AWS IoT Greengrass 核心设备。
1. 对于 **Specify schedule (指定计划)**，选择 **On Schedule (按计划)** 定期运行此关联，或选择 **No Schedule (无计划)** 只运行此关联一次。有关这些选项的详细信息，请参阅[在 Systems Manager 中使用关联。](state-manager-associations.md)。使用控件为关联创建 `cron` 或频率计划。
1. 选择**创建关联**。
1. 在 **Association (关联)** 页面上，选择您创建的关联旁边的按钮，然后选择 **Apply association now (立即应用关联)**。
State Manager 在指定的目标中创建并立即运行关联。有关运行关联的结果的更多信息，请参阅本指南中的 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
有关使用 **Advanced options (高级选项)**、**Rate control (速率控制)** 和 **Output options (输出选项)** 中的选项的更多信息，请参阅 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
## 使用 AWS CLI 一次性安装软件包
您可以在 AWS CLI 中运行 **send-command** 一次性安装 Distributor 软件包。如果已安装软件包，在卸载软件包并在其位置安装新版本时，应用程序将脱机。
**若要使用 AWS CLI 一次性安装软件包**
+ 在 AWS CLI 中运行以下命令。
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
**注意**
`installationType` 的默认行为是 `Uninstall and reinstall`。在安装完整软件包时，您可以从该命令中省略 `"installationType":["Uninstall and reinstall"]`。
示例如下：
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-00000000000000" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["ExamplePackage"]}'
```
有关可以与 **send-command** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
## 使用 AWS CLI 一次性更新软件包
您可以在 AWS CLI 中运行 **send-command** 以更新 Distributor 软件包，而无需将关联的应用程序脱机。仅替换软件包中的新文件或更新的文件。
**若要使用 AWS CLI 一次性更新软件包**
+ 在 AWS CLI 中运行以下命令。
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
**注意**
在添加新文件或更改的文件时，您必须在命令中包含 `"installationType":["In-place update"]`。
示例如下：
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-02573cafcfEXAMPLE" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["ExamplePackage"]}'
```
有关可以与 **send-command** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
## 使用 AWS CLI 计划软件包安装
您可以在 AWS CLI 中运行 **create-association** 按计划安装 Distributor 软件包。`--name`的值（文档名称）始终为 `AWS-ConfigureAWSPackage`。以下命令使用键 `InstanceIds` 指定目标托管式节点。如果已安装软件包，在卸载软件包并在其位置安装新版本时，应用程序将脱机。
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance-ID1\",\"instance-ID2\"]}]
```
**注意**
`installationType` 的默认行为是 `Uninstall and reinstall`。在安装完整软件包时，您可以从该命令中省略 `"installationType":["Uninstall and reinstall"]`。
示例如下：
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["Uninstall and reinstall"],"name":["Test-ConfigureAWSPackage"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"i-02573cafcfEXAMPLE\",\"i-0471e04240EXAMPLE\"]}]
```
有关可以与 **create-association** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html)。
## 使用 AWS CLI 计划软件包更新
您可以在 AWS CLI 中运行 **create-association** 以按计划更新 Distributor 软件包，而无需将关联的应用程序脱机。仅替换软件包中的新文件或更新的文件。`--name`的值（文档名称）始终为 `AWS-ConfigureAWSPackage`。以下命令使用键 `InstanceIds` 指定目标实例。
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance-ID1\",\"instance-ID2\"]}]
```
**注意**
在添加新文件或更改的文件时，您必须在命令中包含 `"installationType":["In-place update"]`。
示例如下：
```
aws ssm create-association \
--name "AWS-ConfigureAWSPackage" \
--parameters '{"action":["Install"],"installationType":["In-place update"],"name":["Test-ConfigureAWSPackage"]}' \
--targets [{\"Key\":\"InstanceIds\",\"Values\":[\"i-02573cafcfEXAMPLE\",\"i-0471e04240EXAMPLE\"]}]
```
有关可以与 **create-association** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html)。
# 卸载 Distributor 软件包
您可以借助 Run Command，使用 AWS 管理控制台或 AWS Command Line Interface（AWS CLI）从 AWS Systems Manager 托管式节点中卸载 Distributor 软件包。Distributor 和 Run Command 都是 AWS Systems Manager 中的工具。在此版本中，一条命令只能卸载一个软件包的一个版本。您可以卸载特定版本或默认版本。
**重要**
使用 Distributor 安装的软件包只能通过 Distributor 卸载。否则，Systems Manager 仍可能将应用程序注册为 `INSTALLED`，导致其他意外结果。
**Topics**
+ [使用控制台卸载软件包](#distributor-pkg-uninstall-console)
+ [使用 AWS CLI 卸载软件包](#distributor-pkg-uninstall-cli)
## 使用控制台卸载软件包
您可以在 Systems Manager 控制台中使用 Run Command 一次性卸载软件包。Distributor 使用 [AWS Systems Manager Run Command](run-command.md) 卸载软件包。
**若要使用控制台卸载软件包**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 在 Run Command 主页上，选择 **Run command (运行命令)**。
1. 选择 `AWS-ConfigureAWSPackage` 命令文档。
1. 从 **Action (操作)** 中，选择 **Uninstall (卸载)**
1. 对于 **Name (名称)**，输入要卸载的软件包的名称。
1. 对于 **Targets**（目标），选择您希望如何将托管式节点设为目标。您可以指定目标共享的标签键和值。您还可以通过选择属性（例如 ID、平台和 SSM Agent 版本）来指定目标。
1. 您可以使用高级选项添加有关该操作的注释、更改 **Rate control (速率控制)** 中的 **Concurrency (并发)** 和 **Error threshold (错误阈值)** 的值、指定输出选项，或者配置 Amazon Simple Notification Service (Amazon SNS) 通知。有关更多信息，请参阅本指南中的[从控制台运行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/rc-console.html)。
1. 做好卸载软件包的准备后，选择 **Run (运行)**，然后选择 **View results (查看结果)**。
1. 在命令列表中，选择您运行的 `AWS-ConfigureAWSPackage` 命令。如果命令仍在执行中，则选择控制台右上角的“刷新”图标。
1. 如果 **Status**（状态）列显示 **Success**（成功）或 **Failed**（失败），则选择 **Output**（输出）选项卡。
1. 选择 **View Output (查看输出)**。命令输出页面将显示命令执行的结果。
## 使用 AWS CLI 卸载软件包
您可以使用 AWS CLI 通过 Run Command 从托管式节点中卸载 Distributor 软件包。
**若要使用 AWS CLI 卸载软件包**
+ 在 AWS CLI 中运行以下命令。
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "instance-IDs" \
--parameters '{"action":["Uninstall"],"name":["package-name (in same account) or package-ARN (shared from different account)"]}'
```
示例如下：
```
aws ssm send-command \
--document-name "AWS-ConfigureAWSPackage" \
--instance-ids "i-02573cafcfEXAMPLE" \
--parameters '{"action":["Uninstall"],"name":["Test-ConfigureAWSPackage"]}'
```
有关可以与 **send-command** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
# 删除 Distributor 软件包
本节介绍如何删除软件包。您不能删除某个版本的软件包，只能删除整个软件包。
## 使用控制台删除软件包
您可以使用 AWS Systems Manager 控制台从 Distributor（AWS Systems Manager 中的一项工具）中删除软件包或软件包版本。删除软件包将从 Distributor 删除此软件包的所有版本。
**若要使用控制台删除软件包**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 **Distributor** 主页上，选择要删除的软件包。
1. 在软件包的详细信息页面上，选择 **Delete package (删除软件包)**。
1. 当系统提示确认删除时，选择 **Delete package (删除软件包)**。
## 使用控制台删除软件包版本
您可以使用 Systems Manager 控制台从 Distributor 中删除软件包版本。
**若要使用控制台删除软件包版本**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Distributor**。
1. 在 **Distributor** 主页上，选择要删除其版本的软件包。
1. 在软件包的版本页面上，选择要删除的版本，然后选择 **Delete version (删除版本)**。
1. 当系统提示确认删除时，选择 **Delete package version (删除软件包版本)**。
## 使用命令行删除软件包
您可以使用首选命令行工具从 Distributor 中删除软件包。
------
#### [ Linux & macOS ]
**若要使用 AWS CLI 删除软件包**
1. 运行以下命令列出特定软件包的文档。在此命令的结果中，查找要删除的软件包。
```
aws ssm list-documents \
--filters Key=Name,Values=package-name
```
1. 运行以下命令删除软件包。将 *package-name* 替换为软件包名称。
```
aws ssm delete-document \
--name "package-name"
```
1. 再次运行 **list-documents** 命令，验证是否已删除此软件包。您删除的软件包不应在包含在该列表中。
```
aws ssm list-documents \
--filters Key=Name,Values=package-name
```
------
#### [ Windows ]
**若要使用 AWS CLI 删除软件包**
1. 运行以下命令列出特定软件包的文档。在此命令的结果中，查找要删除的软件包。
```
aws ssm list-documents ^
--filters Key=Name,Values=package-name
```
1. 运行以下命令删除软件包。将 *package-name* 替换为软件包名称。
```
aws ssm delete-document ^
--name "package-name"
```
1. 再次运行 **list-documents** 命令，验证是否已删除此软件包。您删除的软件包不应在包含在该列表中。
```
aws ssm list-documents ^
--filters Key=Name,Values=package-name
```
------
#### [ PowerShell ]
**若要使用 Tools for PowerShell 删除软件包**
1. 运行以下命令列出特定软件包的文档。在此命令的结果中，查找要删除的软件包。
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Name"
$filter.Values = "package-name"
Get-SSMDocumentList `
-Filters @($filter)
```
1. 运行以下命令删除软件包。将 *package-name* 替换为软件包名称。
```
Remove-SSMDocument `
-Name "package-name"
```
1. 再次运行 **Get-SSMDocumentList** 命令，验证是否已删除此软件包。您删除的软件包不应在包含在该列表中。
```
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Name"
$filter.Values = "package-name"
Get-SSMDocumentList `
-Filters @($filter)
```
------
## 使用命令行删除软件包版本
您可以使用首选命令行工具从 Distributor 中删除软件包版本。
------
#### [ Linux & macOS ]
**若要使用 AWS CLI 删除软件包版本**
1. 运行以下命令列出软件包的版本。在此命令的结果中，查找要删除的软件包版本。
```
aws ssm list-document-versions \
--name "package-name"
```
1. 运行以下命令删除软件包版本。将 *package-name* 替换为软件包名称，并将 *version* 替换为版本号。
```
aws ssm delete-document \
--name "package-name" \
--document-version version
```
1. 运行 **list-document-versions** 命令，验证软件包的版本是否已删除。此时应找不到已删除的软件包版本。
```
aws ssm list-document-versions \
--name "package-name"
```
------
#### [ Windows ]
**若要使用 AWS CLI 删除软件包版本**
1. 运行以下命令列出软件包的版本。在此命令的结果中，查找要删除的软件包版本。
```
aws ssm list-document-versions ^
--name "package-name"
```
1. 运行以下命令删除软件包版本。将 *package-name* 替换为软件包名称，并将 *version* 替换为版本号。
```
aws ssm delete-document ^
--name "package-name" ^
--document-version version
```
1. 运行 **list-document-versions** 命令，验证软件包的版本是否已删除。此时应找不到已删除的软件包版本。
```
aws ssm list-document-versions ^
--name "package-name"
```
------
#### [ PowerShell ]
**若要使用 Tools for PowerShell 删除软件包版本**
1. 运行以下命令列出软件包的版本。在此命令的结果中，查找要删除的软件包版本。
```
Get-SSMDocumentVersionList `
-Name "package-name"
```
1. 运行以下命令删除软件包版本。将 *package-name* 替换为软件包名称，并将 *version* 替换为版本号。
```
Remove-SSMDocument `
-Name "package-name" `
-DocumentVersion version
```
1. 运行 **Get-SSMDocumentVersionList** 命令，验证软件包的版本是否已删除。此时应找不到已删除的软件包版本。
```
Get-SSMDocumentVersionList `
-Name "package-name"
```
------
有关可以与 **list-documents** 命令结合使用的其他选项的信息，请参阅 *AWS CLI 命令参考* AWS Systems Manager 一节中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/list-documents.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-documents.html)。有关可以与 **delete-document** 命令配合使用的其他选项的信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/delete-document.html)。
# 审计和记录 Distributor 活动
您可以使用 AWS CloudTrail 来审核与 Distributor（AWS Systems Manager 中的一项工具）相关的活动。有关 Systems Manager 的审计和日志记录选项的更多信息，请参阅 [AWS Systems Manager 中的日志记录和监控](monitoring.md)。
## 使用 CloudTrail 审计 Distributor 活动
CloudTrail 可以捕获在 AWS Systems Manager 控制台、AWS Command Line Interface (AWS CLI) 和 Systems Manager 软件开发工具包中进行的 API 调用。可以在 CloudTrail 控制台中查看这些信息，也可以将其存储在 Amazon Simple Storage Service (Amazon S3) 存储桶中。账户的所有 CloudTrail 日志都存储在一个存储桶中。
Run Command 和State Manager操作的日志显示了文档创建、软件包安装和软件包卸载活动。Run Command 和State Manager都是 AWS Systems Manager 中的工具。有关查看和使用 Systems Manager 活动的 CloudTrail 日志的更多信息，请参阅 [使用 AWS CloudTrail 记录 AWS Systems Manager API 调用](monitoring-cloudtrail-logs.md)。
# AWS Systems Manager Distributor 故障排除
以下信息可帮助排查使用 Distributor（AWS Systems Manager 中的一项工具）时可能出现的问题。
**Topics**
+ [安装了具有相同名称的错误的软件包](#distributor-tshoot-1)
+ [错误：“无法检索清单：找不到软件包的最新版本”](#distributor-tshoot-2)
+ [错误：“无法检索清单：验证异常”](#distributor-tshoot-3)
+ [软件包不受支持（软件包缺少安装操作）](#distributor-tshoot-4)
+ [错误：无法下载清单：带有名称的文档不存在](#distributor-tshoot-5)
+ [上传失败。](#distributor-tshoot-6)
+ [错误：找不到平台：找不到平台清单：oracle，版本 8.9，架构 x86\$164](#distributor-tshoot-7)
## 安装了具有相同名称的错误的软件包
**问题：**您已安装了一个软件包，但 Distributor 安装了一个不同的软件包。
**原因：**在安装过程中，Systems Manager 先查找 AWS 发布的软件包作为结果，然后才查找用户定义的外部软件包。如果用户定义的软件包名称与 AWS 发布的软件包名称相同，则将安装 AWS 软件包而不是您的软件包。
**解决方案：**要避免此问题，请将您的软件包命名为与 AWS 发布的软件包不同的名称。
## 错误：“无法检索清单：找不到软件包的最新版本”
**问题：**您收到类似如下内容的错误。
```
Failed to retrieve manifest: ResourceNotFoundException: Could not find the latest version of package
arn:aws:ssm:::package/package-name status code: 400, request id: guid
```
**原因：**您使用的 SSM Agent 版本的 Distributor 版本低于 2.3.274.0。
**解决方案：**将 SSM Agent 版本更新为 2.3.274.0 或更高版本。有关更多信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample) 或 [演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)。
## 错误：“无法检索清单：验证异常”
**问题：**您收到类似如下内容的错误。
```
Failed to retrieve manifest: ValidationException: 1 validation error detected: Value 'documentArn'
at 'packageName' failed to satisfy constraint: Member must satisfy regular expression pattern:
arn:aws:ssm:region-id:account-id:package/package-name
```
**原因：**您使用的 SSM Agent 版本的 Distributor 版本低于 2.3.274.0。
**解决方案：**将 SSM Agent 版本更新为 2.3.274.0 或更高版本。有关更多信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample) 或 [演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)。
## 软件包不受支持（软件包缺少安装操作）
**问题：**您收到类似如下内容的错误。
```
Package is not supported (package is missing install action)
```
**原因：**软件包目录结构不正确。
**解决方案：**不要压缩包含软件和所需脚本的父目录。相反，应直接在绝对路径中创建一个包含所有所需内容的 `.zip` 文件。要验证是否已正确创建 `.zip` 文件，请解压缩目标平台目录，并审核目录结构。例如，安装脚本绝对路径应为 `/ExamplePackage_targetPlatform/install.sh`。
## 错误：无法下载清单：带有名称的文档不存在
**问题：**您收到类似如下内容的错误。
```
Failed to download manifest - failed to retrieve package document description: InvalidDocument: Document with name filename does not exist.
```
**原因 1：**在共享来自其他账户的 Distributor 软件包时，Distributor 无法通过软件包名称找到该软件包。
**解决方案 1：**在共享来自其他账户的软件包时，请使用软件包的 Amazon 资源名称（ARN），而不只是软件包名称。
**原因 2：**在使用 VPC 时，没有向自己的 IAM 实例配置文件提供对 AWS 托管式 S3 存储桶的访问权限，而该存储桶包含目标 AWS 区域适用的 `AWS-ConfigureAWSPackage` 档案。
**解决方案 2：**确保自己的 IAM 实例配置文件提供向 SSM Agent 提供了对 AWS 托管式 S3 存储桶（该存储桶包含目标 AWS 区域适用的 `AWS-ConfigureAWSPackage` 文档）的访问权限，如 [SSM Agent 与 AWS 托管 S3 存储桶进行通信](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions)中所述。
## 上传失败。
**问题**：您收到类似如下内容的错误：
```
Upload failed. At least one of your files was not successfully uploaded to your S3 bucket.
```
**原因：**您软件包的名称中包含空格。例如，`Hello World.msi` 将无法上传。
## 错误：找不到平台：找不到平台清单：oracle，版本 8.9，架构 x86\$164
**问题**：您收到类似如下内容的错误：
```
Failed to find platform: no manifest found for platform: oracle, version 8.9, architecture x86_64
```
**原因：**此错误表示 JSON 软件包清单没有该平台（在本例中为 Oracle Linux）对应的任何定义。
**解决方法：**从 [Trend Micro Deep Security Software](https://help.deepsecurity.trendmicro.com/software.html) 网站下载要分发的软件包。使用 [使用简单工作流创建软件包](distributor-working-with-packages-create.md#distributor-working-with-packages-create-simple) 创建 `.rpm` 软件包。为软件包设置以下值，然后使用 Distributor 完成软件包上传：
```
Platform version: _any
Target platform: oracle
Architecture: x86_64
```
# AWS Systems Manager Fleet Manager
Fleet Manager（AWS Systems Manager 中的一项工具）是一种统一的用户界面（UI）体验，可帮助您远程管理在 AWS 上或在本地运行的节点。借助 Fleet Manager，您可以从一个控制台查看整个服务器机群的运行状况和性能状态。您还可以从单个节点收集数据，以便从该控制台执行常见的故障排除和管理任务。这包括使用远程桌面协议 (RDP) 连接到 Windows 实例、查看文件夹和文件内容、Windows 注册表管理、操作系统用户管理等等。
要开始使用 Fleet Manager，请打开 [Systems Manager 控制台](https://console.aws.amazon.com/systems-manager/fleet-manager)。在导航窗格中，选择 **Fleet Manager**。
## 谁应该使用 Fleet Manager？
任何想要集中管理节点实例集的 AWS 客户都应使用 Fleet Manager。
## 我的组织如何从 Fleet Manager 获益？
Fleet Manager 具备下列优势：
+ 可以执行各种常见系统管理任务，而不必手动连接到您的托管式节点。
+ 可从单个统一控制台管理在多个平台上运行的节点。
+ 可从单个统一控制台管理运行不同操作系统的节点。
+ 可以提高系统管理的效率。
## Fleet Manager 具有哪些功能？
Fleet Manager 的主要功能包括以下方面：
+ **访问 Red Hat 知识库门户**
通过 Red Hat Enterprise Linux (RHEL) 实例，访问 Red Hat 知识库门户上的二进制文件、知识共享和论坛。
+ **托管式节点状态**
可以查看哪些托管式实例处于 `running` 状态，以及哪些实例处于 `stopped` 状态。有关已停止实例的更多信息，请参阅《Amazon EC2 用户指南》**中的[停止和启动您的实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html)。对于 AWS IoT Greengrass 核心设备，您可以查看状态显示为 `online`、`offline` 还是 `Connection lost`。
**注意**
如果您已在 2021 年 7 月 12 日之前停止托管式实例，它将不会显示 `stopped` 标记。要显示该标记，请启动和停止该实例。
+ **查看实例信息**
可以查看有关连接到托管实例的卷上存储的文件夹和文件数据的信息、有关实例的实时性能数据，以及存储在实例上的日志数据。
+ **查看边缘设备信息**
查看设备的 AWS IoT Greengrass 事物名称、SSM Agent ping 状态和版本等信息。
+ **管理账户和注册表**
可以管理您的实例上的操作系统（OS）用户账户和 Windows 实例上的注册表。
+ **控制对功能的访问权限**
可以使用 AWS Identity and Access Management (IAM) 策略控制对 Fleet Manager 功能的访问。借助这些策略，您可以控制企业中的哪些个人用户或组能够使用各项 Fleet Manager 功能，以及他们能够管理哪些托管式节点。
**Topics**
+ [谁应该使用 Fleet Manager？](#fleet-who)
+ [我的组织如何从 Fleet Manager 获益？](#fleet-benefits)
+ [Fleet Manager 具有哪些功能？](#fleet-features)
+ [设置 Fleet Manager](setting-up-fleet-manager.md)
+ [使用托管式节点](fleet-manager-managed-nodes.md)
+ [使用默认主机管理配置自动管理 EC2 实例](fleet-manager-default-host-management-configuration.md)
+ [使用 Remote Desktop 连接到 Windows Server 托管式实例](fleet-manager-remote-desktop-connections.md)
+ [在托管式实例上管理 Amazon EBS 卷](fleet-manager-manage-amazon-ebs-volumes.md)
+ [访问 Red Hat 知识库门户](fleet-manager-red-hat-knowledge-base-access.md)
+ [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)
# 设置 Fleet Manager
您 AWS 账户中的用户必须先获得必要权限，然后才能使用 Fleet Manager（AWS Systems Manager 中的一项工具）来监控和管理托管式节点。此外，任何 Amazon Elastic Compute Cloud（Amazon EC2）实例；AWS IoT Greengrass 核心设备；以及要使用 Fleet Manager 监控和管理的本地服务器、边缘设备和虚拟机（VM）必须是 Systems Manager *托管式节点*。托管节点是指在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中配置为与 Systems Manager 一起使用的任何计算机。
这意味着节点必须满足某些先决条件并使用 AWS Systems Manager Agent (SSM Agent) 进行配置。
根据计算机类型，请参阅以下主题之一，以确保您的计算机满足托管式节点的要求。
+ Amazon EC2 实例：[使用 Systems Manager 管理 EC2 实例](systems-manager-setting-up-ec2.md)
**提示**
您还可以使Quick Setup（AWS Systems Manager 中的一项工具），帮助将 Amazon EC2 实例快速配置为个人账户中的托管式实例。如果您的企业使用 AWS Organizations，您还可以在多个企业单位 (OU) 和 AWS 区域 中配置实例。有关使用 Quick Setup 配置托管实例的更多信息，请参阅 [使用 Quick Setup 设置 Amazon EC2 主机管理](quick-setup-host-management.md)。
+ 本地服务器和云中的其他服务器类型：[使用 Systems Manager 管理混合和多云环境中的节点](systems-manager-hybrid-multicloud.md)
+ AWS IoT Greengrass（边缘）设备：[使用 Systems Manager 管理边缘设备](systems-manager-setting-up-edge-devices.md)
**Topics**
+ [控制对 Fleet Manager 的访问](configuring-fleet-manager-permissions.md)
# 控制对 Fleet Manager 的访问
要使用 Fleet Manager（AWS Systems Manager 中的一项工具），您的 AWS Identity and Access Management（IAM）用户或角色必须拥有所需权限。您可以创建一个 IAM policy 提供对所有 Fleet Manager 功能的访问权限，或者修改策略以授予对所选功能的访问权限。然后，您可以将这些权限授予您账户中的用户或身份。
**任务 1：创建 IAM 策略以定义访问权限**
按照《IAM 用户指南》**中的以下主题中提供的方法之一创建 IAM，为身份（用户、角色或用户组）提供 Fleet Manager 的访问权限：
+ [使用客户管理型策略定义自定义 IAM 权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)
您可以使用我们在下面提供的示例策略之一，或者根据要授予的权限对其进行修改。我们为完全的 Fleet Manager 访问权限和只读访问权限提供策略示例。
**任务 2：为用户附加 IAM 策略以授予权限**
在您创建了一个或多个定义 Fleet Manager 的访问权限的 IAM 策略后，使用《IAM 用户指南》**中的以下过程之一，向账户中的身份授予这些权限：
+ [添加 IAM 身份权限（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console)
+ [添加 IAM 身份权限（AWS CLI）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policy-cli)
+ [添加 IAM 身份权限（AWS API）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policy-api)
**Topics**
+ [Fleet Manager 管理员访问权限示例策略](#admin-policy-sample)
+ [Fleet Manager 只读访问权限实例策略](#read-only-policy-sample)
## Fleet Manager 管理员访问权限示例策略
以下策略提供了对所有 Fleet Manager 功能的权限。这意味着用户可以创建和删除本地用户和组、修改任何本地组的组成员资格，以及修改 Windows Server 注册表键或值。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EC2",
"Effect": "Allow",
"Action": [
"ec2:CreateTags",
"ec2:DeleteTags",
"ec2:DescribeInstances",
"ec2:DescribeTags"
],
"Resource": "*"
},
{
"Sid": "General",
"Effect": "Allow",
"Action": [
"ssm:AddTagsToResource",
"ssm:DescribeInstanceAssociationsStatus",
"ssm:DescribeInstancePatches",
"ssm:DescribeInstancePatchStates",
"ssm:DescribeInstanceProperties",
"ssm:GetCommandInvocation",
"ssm:GetServiceSetting",
"ssm:GetInventorySchema",
"ssm:ListComplianceItems",
"ssm:ListInventoryEntries",
"ssm:ListTagsForResource",
"ssm:ListCommandInvocations",
"ssm:ListAssociations",
"ssm:RemoveTagsFromResource"
],
"Resource": "*"
},
{
"Sid": "DefaultHostManagement",
"Effect": "Allow",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
},
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com"
]
}
}
},
{
"Sid": "SendCommand",
"Effect": "Allow",
"Action": [
"ssm:GetDocument",
"ssm:SendCommand",
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:111122223333:instance/*",
"arn:aws:ssm:*:111122223333:managed-instance/*",
"arn:aws:ssm:*:111122223333:document/SSM-SessionManagerRunShell",
"arn:aws:ssm:*:*:document/AWS-PasswordReset",
"arn:aws:ssm:*:*:document/AWSFleetManager-AddUsersToGroups",
"arn:aws:ssm:*:*:document/AWSFleetManager-CopyFileSystemItem",
"arn:aws:ssm:*:*:document/AWSFleetManager-CreateDirectory",
"arn:aws:ssm:*:*:document/AWSFleetManager-CreateGroup",
"arn:aws:ssm:*:*:document/AWSFleetManager-CreateUser",
"arn:aws:ssm:*:*:document/AWSFleetManager-CreateUserInteractive",
"arn:aws:ssm:*:*:document/AWSFleetManager-CreateWindowsRegistryKey",
"arn:aws:ssm:*:*:document/AWSFleetManager-DeleteFileSystemItem",
"arn:aws:ssm:*:*:document/AWSFleetManager-DeleteGroup",
"arn:aws:ssm:*:*:document/AWSFleetManager-DeleteUser",
"arn:aws:ssm:*:*:document/AWSFleetManager-DeleteWindowsRegistryKey",
"arn:aws:ssm:*:*:document/AWSFleetManager-DeleteWindowsRegistryValue",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetDiskInformation",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetFileContent",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetFileSystemContent",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetGroups",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetPerformanceCounters",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetProcessDetails",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetUsers",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetWindowsEvents",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetWindowsRegistryContent",
"arn:aws:ssm:*:*:document/AWSFleetManager-MountVolume",
"arn:aws:ssm:*:*:document/AWSFleetManager-MoveFileSystemItem",
"arn:aws:ssm:*:*:document/AWSFleetManager-RemoveUsersFromGroups",
"arn:aws:ssm:*:*:document/AWSFleetManager-RenameFileSystemItem",
"arn:aws:ssm:*:*:document/AWSFleetManager-SetWindowsRegistryValue",
"arn:aws:ssm:*:*:document/AWSFleetManager-StartProcess",
"arn:aws:ssm:*:*:document/AWSFleetManager-TerminateProcess"
]
},
{
"Sid": "TerminateSession",
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"${aws:userid}"
]
}
}
}
]
}
```
------
## Fleet Manager 只读访问权限实例策略
以下策略提供了对只读 Fleet Manager 功能的权限。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EC2",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeTags"
],
"Resource": "*"
},
{
"Sid": "General",
"Effect": "Allow",
"Action": [
"ssm:DescribeInstanceAssociationsStatus",
"ssm:DescribeInstancePatches",
"ssm:DescribeInstancePatchStates",
"ssm:DescribeInstanceProperties",
"ssm:GetCommandInvocation",
"ssm:GetServiceSetting",
"ssm:GetInventorySchema",
"ssm:ListComplianceItems",
"ssm:ListInventoryEntries",
"ssm:ListTagsForResource",
"ssm:ListCommandInvocations",
"ssm:ListAssociations"
],
"Resource": "*"
},
{
"Sid": "SendCommand",
"Effect": "Allow",
"Action": [
"ssm:GetDocument",
"ssm:SendCommand",
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:111122223333:instance/*",
"arn:aws:ssm:*:111122223333:managed-instance/*",
"arn:aws:ssm:*:111122223333:document/SSM-SessionManagerRunShell",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetDiskInformation",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetFileContent",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetFileSystemContent",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetGroups",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetPerformanceCounters",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetProcessDetails",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetUsers",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetWindowsEvents",
"arn:aws:ssm:*:*:document/AWSFleetManager-GetWindowsRegistryContent"
]
},
{
"Sid": "TerminateSession",
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"${aws:userid}"
]
}
}
}
]
}
```
------
# 使用托管式节点
*托管式节点*是为 AWS Systems Manager 配置的任何计算机。您可以将以下计算机类型配置为托管式节点：
+ Amazon Elastic Compute Cloud（Amazon EC2）实例
+ 您本地的服务器（本地服务器）
+ AWS IoT Greengrass 核心设备
+ AWS IoT 和非 AWS 边缘设备
+ 虚拟机，包括其他云环境中的虚拟机
在 Systems Manager 控制台中，任何带有“mi-”前缀的计算机都已使用[*混合激活*](activations.md)配置为托管式节点。边缘设备显示其 AWS IoT 事物名称。
**注意**
对于 macOS 实例，唯一受支持的功能是查看文件系统。
**关于 Systems Manager 实例套餐**
AWS Systems Manager 提供了标准实例层和高级实例层。两者都支持[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的托管式节点。通过标准实例套餐，每个 AWS 区域 内每个 AWS 账户 最多可以注册 1000 台计算机。如果您需要在一个账户和区域中注册超过 1000 台计算机，则使用高级实例套餐。在高级实例套餐中，您可以根据需要创建许多托管式节点。为 Systems Manager 配置的所有托管式节点均按使用量付费。有关启用高级实例套餐的更多信息，请参阅 [打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)。有关定价的更多信息，请参阅 [AWS Systems Manager 定价](https://aws.amazon.com/systems-manager/pricing/)。
请注意以下关于标准实例层和高级实例层的附加信息：
+ 通过高级实例，您还可以使用 AWS Systems Manager Session Manager 连接到[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 节点。Session Manager 提供了对您的实例的交互式 Shell 访问。有关更多信息，请参阅 [AWS Systems Manager Session Manager](session-manager.md)。
+ 标准实例配额也适用于使用 Systems Manager 本地激活的 Amazon EC2 实例（但这不是常见情况）。
+ 要修补 Microsoft 在虚拟机 (VM) 本地实例上发布的应用程序，请激活高级实例套餐。使用高级实例套餐需支付费用。修补 Microsoft 在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上发布的应用程序不收取额外费用。有关更多信息，请参阅 [Microsoft 在 Windows Server 上发布的补丁应用程序](patch-manager-patching-windows-applications.md)。
**显示托管式节点**
如果您没有看到控制台中列出托管式节点，则执行以下操作：
1. 确认控制台在您创建托管式节点的 AWS 区域 中处于打开状态。您可以使用顶部的列表（控制台右上角）切换区域。
1. 确认托管式节点的设置步骤是否满足 Systems Manager 要求。有关信息，请参阅[为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
1. 对于非 EC2 计算机，请确认您已完成混合激活过程。有关更多信息，请参阅 [使用 Systems Manager 管理混合和多云环境中的节点](systems-manager-hybrid-multicloud.md)。
请注意以下额外信息：
+ Fleet Manager 控制台不显示已终止的 Amazon EC2 节点。
+ Systems Manager 需要准确的时间参考以便在计算机上执行操作。如果托管式节点上的日期和时间设置不正确，计算机可能与 API 请求的签名日期不匹配。有关更多信息，请参阅 [使用案例和最佳实践](systems-manager-best-practices.md)。
+ 创建或编辑标签时，系统可能需要最多 1 小时才能在表筛选条件中显示更改。
+ 在托管节点的状态保持 `Connection Lost` 至少 30 天后，该节点可能不再会在 Fleet Manager 控制台中列出。必须首先解决导致连接中断的问题，然后才能将其恢复到列表中。有关故障排除提示，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)。
**验证托管式节点的 Systems Manager 支持**
AWS Config 提供了 AWS 托管式规则，AWS Config 使用这些可自定义的预定义规则来评估您的 AWS 资源配置是否符合常用的最佳实践。AWS ConfigManaged Rules 包括 [ec2-instance-managed-by-systems-manager](https://docs.aws.amazon.com/config/latest/developerguide/ec2-instance-managed-by-systems-manager.html) 规则。该规则会检查您账户中的 Amazon EC2 实例是否由 Systems Manager 托管。有关更多信息，请参阅 [AWS Config Managed Rules](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config_use-managed-rules.html)。
**改善托管式节点的安保状况**
有关在托管式节点上提高针对未授权根级别命令的安保状况的更多信息，请参阅 [通过 SSM Agent 限制对根级别命令的访问](ssm-agent-restrict-root-level-commands.md)。
**取消注册托管式节点**
您可以随时取消注册托管式节点。例如，如果您正在管理多个具有相同 AWS Identity and Access Management (IAM) 角色的节点，并且您发现了任何类型的恶意行为，则您可以随时取消注册任意数量的计算机。（要重新注册同一台计算机，必须使用不同的混合激活码和激活 ID，不能使用先前注册时用过的激活码和激活 ID。） 有关取消注册托管式节点的信息，请参阅 [在混合和多云环境中取消注册托管式节点](fleet-manager-deregister-hybrid-nodes.md)。
**Topics**
+ [配置实例套餐](fleet-manager-configure-instance-tiers.md)
+ [在托管式节点上重置密码](fleet-manager-reset-password.md)
+ [在混合和多云环境中取消注册托管式节点](fleet-manager-deregister-hybrid-nodes.md)
+ [通过 Fleet Manager 来使用 OS 文件系统](fleet-manager-file-system-management.md)
+ [监控托管式节点性能](fleet-manager-monitoring-node-performance.md)
+ [使用进程](fleet-manager-manage-processes.md)
+ [查看托管式节点上的日志](fleet-manager-view-node-logs.md)
+ [使用 Fleet Manager 来管理托管式节点上的 OS 用户账户和组](fleet-manager-manage-os-user-accounts.md)
+ [在托管式节点上管理 Windows 注册表](fleet-manager-manage-windows-registry.md)
# 配置实例套餐
本主题描述了必须激活高级实例化套餐的情况。
AWS Systems Manager 为[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 计算机提供了标准实例套餐和高级实例套餐。
每个 AWS 区域 内每个账户可以注册最多 1000 个标准[混合激活节点](activations.md)，无需额外收费。但是，注册超过 1000 个混合节点需要激活高级实例套餐。使用高级实例套餐需支付费用。有关更多信息，请参阅[AWS Systems Manager定价](https://aws.amazon.com/systems-manager/pricing/)。
即使注册的混合激活节点少于 1000 个，但还有两种场景也需要高级实例套餐：
+ 您希望使用 Session Manager 连接到非 EC2 节点。
+ 您希望修补 Microsoft 在非 EC2 节点上发布的应用程序（非操作系统）。
**注意**
修补 Microsoft 在 Amazon EC2 实例上发布的应用程序不收取费用。
## 高级实例套餐详细情况
以下信息详细介绍了必须激活高级实例套餐的三种情况。
场景 1：您希望注册超过 1000 个混合激活节点
使用标准实例套餐，您可以在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中为特定账户中为每个 AWS 区域 注册最多 1000 个非 EC2 节点，无需额外收费。如果您需要在一个区域中注册超过 1000 个非 EC2 节点，则必须使用高级实例套餐。然后，您可以为混合和多云环境激活任意数量的计算机。高级实例套餐根据激活为 Systems Manager 托管式节点的高级节点数量以及这些节点运行的小时数收费。
如果您在特定账户的某个区域中有超过 1000 个本地节点，那么使用[创建混合激活以将节点注册到 Systems Manager](hybrid-activation-managed-nodes.md) 中所述的激活过程的所有 Systems Manager 托管式节点都需支付费用。
您还可以使用 Systems Manager 混合激活现有的 Amazon Elastic Compute Cloud (Amazon EC2) 实例，并将其作为非 EC2 实例使用，例如用于测试。这些节点也可以成为混合节点。但这不是常见的情况。
情况 2：在混合激活节点上修补 Microsoft 发布的应用程序
如果要在混合和多云环境中的非 EC2 节点上修补 Microsoft 发布的应用程序，也需要高级实例套餐。如果您激活高级实例套餐以修补非 EC2 节点上的 Microsoft 应用程序，则即使您的节点少于 1000 个，也会对所有本地节点收取费用。
修补 Microsoft 在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上发布的应用程序不收取额外费用。有关更多信息，请参阅 [Microsoft 在 Windows Server 上发布的补丁应用程序](patch-manager-patching-windows-applications.md)。
情况 3：使用 Session Manager 连接到混合激活节点
Session Manager 提供了对实例的交互式 shell 访问。要使用 Session Manager 连接到混合激活托管式节点，必须激活高级实例套餐。然后，所有混合激活的节点都将收取费用，即使您的节点少于 1000 个。
**摘要：何时需要高级实例套餐？**
使用下表查看何时必须使用高级实例套餐，以及哪些情况将收取额外费用。
****
| 情况 | 是否需要高级实例套餐？ | 是否收取额外费用？ |
| --- | --- | --- |
| 特定账户中我的区域的混合激活节点数超过 1000 个。 | 支持 | 是 |
| 我想用 Patch Manager 在任意数量（甚至少于 1000 个）的混合激活节点上修补 Microsoft 发布的应用程序。 | 支持 | 是 |
| 我想用 Session Manager 连接任意数量（甚至少于 1000 个）的混合激活节点。 | 支持 | 是 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/fleet-manager-configure-instance-tiers.html) | 否 | 否 |
**Topics**
+ [高级实例套餐详细情况](#systems-manager-managed-instances-tier-scenarios)
+ [打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)
+ [从高级实例套餐还原到标准实例套餐](fleet-manager-revert-to-standard-tier.md)
# 打开高级实例套餐
AWS Systems Manager 为[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 计算机提供了标准实例套餐和高级实例套餐。通过标准实例套餐，每个 AWS 区域 内每个 AWS 账户 最多可以注册 1000 台混合激活的计算机。使用 Patch Manager 在非 EC2 节点上修补 Microsoft 发布的应用程序，并使用 Session Manager 连接到非 EC2 节点也需要使用高级实例套餐。有关更多信息，请参阅 [打开高级实例套餐](#fleet-manager-enable-advanced-instances-tier)。
本节介绍如何配置您的混合和多云环境来使用高级实例套餐。
**开始前的准备工作**
查看高级实例的定价详细信息。高级实例按使用量收费。有关更多信息，请参阅 [AWS Systems Manager 定价](https://aws.amazon.com/systems-manager/pricing/)。
## 配置打开高级实例套餐的权限
请验证并确保您在 AWS Identity and Access Management (IAM) 中拥有将您的环境从标准实例套餐更改为高级实例套餐的权限。您必须将 `AdministratorAccess` IAM policy 附加到您的用户、组或角色，或者您必须拥有更改 Systems Manager 激活套餐服务设置的权限。激活套餐设置使用以下 API 操作：
+ [GetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetServiceSetting.html)
+ [UpdateServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateServiceSetting.html)
+ [ResetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ResetServiceSetting.html)
使用以下过程可将内联 IAM policy 添加到用户账户。此策略使用户能够查看当前的托管实例套餐设置。此策略还使用户能够更改或重置指定 AWS 账户 和 AWS 区域 中的当前设置。
1. 登录 AWS 管理控制台，单击 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 在导航窗格中，选择**用户**。
1. 在列表中，选择要在其中嵌入策略的用户的名称。
1. 选择**权限**选项卡。
1. 在页面右侧，在 **Permission policies (权限策略)** 下，选择 **Add inline policy (添加内联策略)**。
1. 选择 **JSON** 选项卡。
1. 将默认内容替换为以下内容：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:servicesetting/ssm/managed-instance/activation-tier"
}
]
}
```
------
1. 选择 **Review policy (审核策略)**。
1. 在 **Review policy (审核策略)** 页面上，对于 **Name (名称)**，输入内联策略的名称。例如：**Managed-Instances-Tier**。
1. 选择**创建策略**。
管理员可以将以下内联策略分配给该用户，从而指定只读权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "*"
}
]
}
```
------
有关创建和编辑 IAM policy 的更多信息，请参阅《IAM 用户指南》中的[创建 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。
## 打开高级实例套餐（控制台）
以下过程介绍如何使用 Systems Manager 控制台，将使用托管实例激活在指定 AWS 账户 和 AWS 区域 中添加的*所有*非 EC2 节点更改为使用高级实例套餐。
**开始前的准备工作**
验证并确保控制台在您创建托管实例的 AWS 区域 中处于打开状态。您可以使用顶部的列表（控制台右上角）切换区域。
验证您是否已在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中完成 Amazon Elastic Compute Cloud（Amazon EC2）实例以及非 EC2 计算机的设置要求。有关信息，请参阅[为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
**重要**
以下过程介绍了如何更改账户级别设置。此更改会导致向您的账户计费。
**打开高级实例套餐（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择**设置**，然后选择**更改实例等级设置**。
1. 查看对话框中有关更改账户设置的信息。
1. 如果您批准，请选择要接受的选项，然后选择**更改设置**。
系统可能需要几分钟才能完成将所有实例从标准实例套餐转移至高级实例套餐的过程。
**注意**
有关恢复为标准实例套餐的信息，请参阅 [从高级实例套餐还原到标准实例套餐](fleet-manager-revert-to-standard-tier.md)。
## 打开高级实例套餐 (AWS CLI)
以下过程介绍了如何使用 AWS Command Line Interface，将使用托管实例激活在指定 AWS 账户 和 AWS 区域 中添加的*所有*本地服务器和 VM 更改为使用高级实例套餐。
**重要**
以下过程介绍了如何更改账户级别设置。此更改会导致向您的账户计费。
**使用 AWS CLI 打开高级实例套餐**
1. 打开 AWS CLI 并运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier \
--setting-value advanced
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier ^
--setting-value advanced
```
------
如果此命令成功，则无任何输出。
1. 运行以下命令来查看当前的 AWS 账户 和 AWS 区域 中托管式节点的当前服务设置。
------
#### [ Linux & macOS ]
```
aws ssm get-service-setting \
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier
```
------
#### [ Windows ]
```
aws ssm get-service-setting ^
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier
```
------
此命令会返回如下信息。
```
{
"ServiceSetting": {
"SettingId": "/ssm/managed-instance/activation-tier",
"SettingValue": "advanced",
"LastModifiedDate": 1555603376.138,
"LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/User_1",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/managed-instance/activation-tier",
"Status": "PendingUpdate"
}
}
```
## 打开高级实例套餐 (PowerShell)
以下过程介绍了如何使用 AWS Tools for Windows PowerShell，将使用托管实例激活在指定 AWS 账户 和 AWS 区域 中添加的*所有* 本地服务器和 VM 更改为使用高级实例套餐。
**重要**
以下过程介绍了如何更改账户级别设置。此更改会导致向您的账户计费。
**使用 PowerShell 打开高级实例套餐**
1. 打开 AWS Tools for Windows PowerShell 并运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
```
Update-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier" `
-SettingValue "advanced"
```
如果此命令成功，则无任何输出。
1. 运行以下命令来查看当前的 AWS 账户 和 AWS 区域 中托管式节点的当前服务设置。
```
Get-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier"
```
此命令会返回如下信息。
```
ARN:arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/managed-instance/activation-tier
LastModifiedDate : 4/18/2019 4:02:56 PM
LastModifiedUser : arn:aws:sts::123456789012:assumed-role/Administrator/User_1
SettingId : /ssm/managed-instance/activation-tier
SettingValue : advanced
Status : PendingUpdate
```
系统可能需要几分钟才能完成将所有节点从标准实例套餐转移至高级实例套餐的过程。
**注意**
有关恢复为标准实例套餐的信息，请参阅 [从高级实例套餐还原到标准实例套餐](fleet-manager-revert-to-standard-tier.md)。
# 从高级实例套餐还原到标准实例套餐
本节介绍如何将高级实例套餐中运行的混合激活节点更改回标准实例套餐。此配置适用于 AWS 账户 和单个 AWS 区域 中的所有混合激活节点。
**开始前的准备工作**
查看以下重要详细信息。
**注意**
如果您在账户和区域中运行的混合激活节点超过 1000 个，则无法恢复到标准实例套餐。您必须先取消注册节点，直到实例数为 1000 或更少为止。这也适用于使用 Systems Manager 混合激活的 Amazon Elastic Compute Cloud（Amazon EC2）实例（但这不是常见情况）。有关更多信息，请参阅 [在混合和多云环境中取消注册托管式节点](fleet-manager-deregister-hybrid-nodes.md)。
恢复后，便无法使用Session Manager（AWS Systems Manager 中的一项工具）以交互方式访问混合激活节点。
恢复后，便无法使用Patch Manager（AWS Systems Manager 中的一项工具）修补 Microsoft 在混合激活节点上发布的应用程序。
将所有混合激活节点恢复为标准实例套餐的过程可能需要 30 分钟或更长时间才能完成。
本节介绍如何将 AWS 账户 和 AWS 区域 中的所有混合激活节点从高级实例套餐恢复到标准实例套餐。
## 恢复为标准实例套餐（控制台）
以下过程介绍了如何使用 Systems Manager 控制台将[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的所有混合激活节点更改为使用指定 AWS 账户 和 AWS 区域 中的标准实例套餐。
**恢复为标准实例套餐（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择 **Account settings (账户设置)** 下拉菜单，然后选择 **Instance tier settings (实例套餐设置)**。
1. 选择 **Change account settings (更改账户设置)**。
1. 查看弹出窗口中有关更改账户设置的信息，然后，如果您批准，请选择接受并继续的选项。
## 恢复为标准实例套餐 (AWS CLI)
以下过程介绍了如何使用 AWS Command Line Interface 将[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的所有混合激活节点更改为使用指定 AWS 账户 和 AWS 区域 中的标准实例套餐。
**使用 AWS CLI 恢复为标准实例套餐**
1. 打开 AWS CLI 并运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier \
--setting-value standard
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier ^
--setting-value standard
```
------
如果此命令成功，则无任何输出。
1. 请在 30 分钟后运行以下命令，以查看当前 AWS 账户 和 AWS 区域 中托管实例的设置。
------
#### [ Linux & macOS ]
```
aws ssm get-service-setting \
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier
```
------
#### [ Windows ]
```
aws ssm get-service-setting ^
--setting-id arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier
```
------
此命令会返回如下信息。
```
{
"ServiceSetting": {
"SettingId": "/ssm/managed-instance/activation-tier",
"SettingValue": "standard",
"LastModifiedDate": 1555603376.138,
"LastModifiedUser": "System",
"ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/managed-instance/activation-tier",
"Status": "Default"
}
}
```
在请求获得批准后，状态将更改为 *Default（默认）*。
## 恢复为标准实例套餐 (PowerShell)
以下过程介绍了如何使用 AWS Tools for Windows PowerShell 将混合和多云环境中的混合激活节点更改为使用指定 AWS 账户 和 AWS 区域 中的标准实例套餐。
**使用 PowerShell 恢复为标准实例套餐**
1. 打开 AWS Tools for Windows PowerShell 并运行以下命令。
```
Update-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier" `
-SettingValue "standard"
```
如果此命令成功，则无任何输出。
1. 请在 30 分钟后运行以下命令，以查看当前 AWS 账户 和 AWS 区域 中托管实例的设置。
```
Get-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:aws-account-id:servicesetting/ssm/managed-instance/activation-tier"
```
此命令会返回如下信息。
```
ARN: arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/managed-instance/activation-tier
LastModifiedDate : 4/18/2019 4:02:56 PM
LastModifiedUser : System
SettingId : /ssm/managed-instance/activation-tier
SettingValue : standard
Status : Default
```
在请求获得批准后，状态将更改为 *Default（默认）*。
# 在托管式节点上重置密码
您可以在托管式节点上重置任何用户的密码。这包括 Amazon Elastic Compute Cloud (Amazon EC2) 实例；AWS IoT Greengrass 核心设备；以及由 AWS Systems Manager 管理的本地服务器、边缘设备和虚拟机 (VM)。密码重置功能构建于Session Manager（AWS Systems Manager 中的一项工具）的基础之上。您可以使用此功能连接到托管式节点，而无需打开入站端口、维护堡垒主机或管理 SSH 密钥。
当用户忘记密码或者您想快速更新密码而不与托管式节点建立 RDP 或 SSH 连接时，密码重置很有用。
**先决条件**
必须满足以下要求，才能在托管式节点上重置密码：
+ 要在其上更改密码的托管式节点必须是 Systems Manager 托管式节点。此外，必须在托管式节点上安装 SSM Agent 版本 2.3.668.0 或更高版本。有关安装或更新 SSM Agent 的信息，请参阅 [使用 SSM Agent](ssm-agent.md)。
+ 密码重置功能使用为您的账户设置的 Session Manager 配置连接到托管式节点。因此，必须已在当前 AWS 区域中为您的账户完成使用 Session Manager 的先决条件。有关更多信息，请参阅 [设置 Session Manager](session-manager-getting-started.md)。
**注意**
仅为高级实例套餐提供对本地节点的 Session Manager 支持。有关更多信息，请参阅 [打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)。
+ 更改密码的 AWS 用户必须对托管式节点具有 `ssm:SendCommand` 权限。有关更多信息，请参阅 [根据标签限制 Run Command 访问](run-command-setting-up.md#tag-based-access)。
**限制访问**
您可以限制用户重置特定托管式节点的密码的能力。通过将基于身份的策略与 `AWS-PasswordReset` SSM 文档结合起来用于 Session Manager `ssm:StartSession` 操作，可以实现这一目的。有关更多信息，请参阅[控制用户会话对实例的访问权限](session-manager-getting-started-restrict-access.md)。
**加密数据**
可为 Session Manager 数据打开 AWS Key Management Service (AWS KMS) 完全加密，以将密码重置选项用于托管式节点。有关更多信息，请参阅 [启用会话数据的 KMS 密钥加密（控制台）](session-preferences-enable-encryption.md)。
## 在托管式节点上重置密码
您可以使用 Systems Manager **Fleet Manager** 控制台或 AWS Command Line Interface (AWS CLI)，在 Systems Manager 托管式节点上重置密码。
**在托管式节点（控制台）上更改密码**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择需要新密码的节点旁边的按钮。
1. 选择**实例操作，重置密码**。
1. 对于 **User name (用户名)**，请输入您要更改其密码的用户的名称。这可以是任何在节点上具有账户的用户名。
1. 选择**提交**。
1. 按照**输入新密码**命令窗口中的提示指定新密码。
**注意**
如果托管式节点上的 SSM Agent 版本不支持密码重置，系统将提示您使用 Run Command（AWS Systems Manager 中的一项工具）安装受支持的版本。
**在托管式节点 (AWS CLI) 上重置密码**
1. 要在托管式节点上重置用户的密码，请运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
**注意**
要使用 AWS CLI 重置密码，Session Manager 插件必须已安装到您的本地计算机上。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name "AWS-PasswordReset" \
--parameters '{"username": ["user-name"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name "AWS-PasswordReset" ^
--parameters username="user-name"
```
------
1. 按照**输入新密码**命令窗口中的提示指定新密码。
## 排除在托管式节点上重置密码的问题
通过确保您已完成[密码重置先决条件](#pw-reset-prereqs)，可以解决许多密码重置问题。对于其他问题，请使用以下信息来帮助您解决密码重置问题。
**Topics**
+ [托管式节点不可用](#password-reset-troubleshooting-instances)
+ [SSM Agent 不是最新版本（控制台）](#password-reset-troubleshooting-ssmagent-console)
+ [未提供密码重置选项 (AWS CLI)](#password-reset-troubleshooting-ssmagent-cli)
+ [未获授权，无法运行 `ssm:SendCommand`](#password-reset-troubleshooting-sendcommand)
+ [Session Manager 错误消息](#password-reset-troubleshooting-session-manager)
### 托管式节点不可用
**问题**：您希望在 **Managed instances**（托管式实例）控制台页面上重置托管式节点的密码，但该节点不在列表中。
+ **解决方案**：可能未为 Systems Manager 配置您要连接的托管式节点。要将 Amazon EC2 实例与 Systems Manager 结合使用，必须将 AWS Identity and Access Management (IAM) 实例配置文件附加到该实例，该配置文件将向 Systems Manager 授予在您的实例上执行操作的权限。有关信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
要将非 EC2 计算机与 Systems Manager 结合使用，请创建一个 IAM 服务角色，该角色将向 Systems Manager 授予在您的托管式节点上执行操作的权限。有关更多信息，请参阅[在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](hybrid-multicloud-service-role.md)。（仅为高级实例套餐提供对本地服务器和 VM 的 Session Manager 支持。有关更多信息，请参阅 [打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)。）
### SSM Agent 不是最新版本（控制台）
**问题**：一条消息报告 SSM Agent 的此版本不支持密码重置功能。
+ **解决方案**：执行密码重置要求使用 SSM Agent 版本 2.3.668.0 或更高版本。在控制台中，您可以通过选择 **Update SSM Agent**（更新 ）来更新托管式节点上的代理。
如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
### 未提供密码重置选项 (AWS CLI)
**问题**：您使用 AWS CLI `[https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)` 命令成功连接到托管式节点。您指定了 SSM 文档 `AWS-PasswordReset` 并提供了有效的用户名，但不显示更改密码的提示。
+ **解决方案**：托管式节点上的 SSM Agent 版本不是最新版本。需要版本 2.3.668.0 或更高版本才能执行密码重置。
如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
### 未获授权，无法运行 `ssm:SendCommand`
**问题**：您尝试连接到托管式节点以更改密码，但收到错误消息，说明您未获授权在托管式节点上运行 `ssm:SendCommand`。
+ **解决方案**：您的 IAM policy 必须包括运行 `ssm:SendCommand` 命令的权限。有关信息，请参阅[根据标签限制 Run Command 访问](run-command-setting-up.md#tag-based-access)。
### Session Manager 错误消息
**问题**：您收到与 Session Manager 相关的错误消息。
+ **解决方案**：密码重置要求正确地配置 Session Manager。有关更多信息，请参阅 [设置 Session Manager](session-manager-getting-started.md) 和 [排除 Session Manager 问题](session-manager-troubleshooting.md)。
# 在混合和多云环境中取消注册托管式节点
如果您不再希望使用 AWS Systems Manager 管理本地服务器、边缘设备或虚拟机 (VM)，则可以将其取消注册。取消注册混合激活节点，会将其从 Systems Manager 中的托管式节点列表中删除。AWS Systems Manager由于不再注册在混合激活节点上运行的代理（SSM Agent），因此将无法刷新其授权令牌。SSM Agent 将休眠，并将其对云中的 Systems Manager 执行 ping 操作的频率减少为每小时一次。Systems Manager 会存储已取消注册的托管式节点的命令历史记录 30 天。
**注意**
只要未达到指定激活码和 ID 的实例限制，就可以使用相同的激活码和 ID 重新注册本地服务器、边缘设备或虚拟机。通过选择**节点工具**，然后选择**混合激活**，您可以在控制台中验证实例限制。如果**注册实例**的值小于**注册限制**，则可以使用相同的激活码和 ID 重新注册计算机。如果该值更大，则必须使用不同的激活码和 ID。
以下过程介绍如何使用 Systems Manager 控制台取消注册混合激活节点。有关如何使用 AWS Command Line Interface 执行此操作的信息，请参阅 [deregister-managed-instance](https://docs.aws.amazon.com/cli/latest/reference/ssm/deregister-managed-instance.html)。
有关信息，请参阅以下主题：
+ [取消注册及重新注册托管式节点（Linux）](hybrid-multicloud-ssm-agent-install-linux.md#systems-manager-install-managed-linux-deregister-reregister)（Linux）
+ [取消注册及重新注册托管式节点（Windows Server）](hybrid-multicloud-ssm-agent-install-windows.md#systems-manager-install-managed-win-deregister-reregister) (Windows Server)
**取消注册混合激活节点（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要取消注册的托管式节点旁边的复选框。
1. 选择**节点操作、工具、取消注册此托管式节点**。
1. 查看**取消注册此托管式节点**对话框中的信息。如果您批准，请选择**取消注册**。
# 通过 Fleet Manager 来使用 OS 文件系统
您可以通过 Fleet Manager（AWS Systems Manager 中的一项工具）来使用托管式节点上的文件系统。使用 Fleet Manager，您可以查看有关存储在附加到托管式节点的卷的目录和文件数据的信息。例如，您可以查看目录和文件的名称、大小、扩展名、拥有者和权限。可从 Fleet Manager 控制台以文本形式预览最多 1 万行的文件数据。您还可以将此功能用于 `tail` 文件。在使用 `tail` 查看文件数据时，最初会显示文件的最后 10 行。随着新的数据行写入文件，视图也将实时更新。因此，您可以从控制台查看日志数据，这可以提高故障排除和系统管理的效率。此外，您可以创建目录以及复制、剪切、粘贴、重命名或删除文件和目录。
我们建议定期创建备份，或为附加到托管式节点的 Amazon Elastic Block Store (Amazon EBS) 卷拍摄快照。复制或剪切并粘贴文件时，目标路径中与新文件或目录同名的现有文件和目录将被替换。如果您替换或修改系统文件和目录，可能会出现严重问题。AWS 不能保证这些问题能得到解决。修改系统文件需自行承担风险。您需对所有文件与目录更改负责，并确保您有备份。删除或替换文件和目录的操作无法撤销。
**注意**
Fleet Manager 使用Session Manager（AWS Systems Manager 中的一项工具）来查看文本预览和 `tail` 文件。对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，附加到托管式实例的实例配置文件必须向 Session Manager 提供权限才能使用此功能。有关向实例配置文件添加 Session Manager 权限的更多信息，请参阅 [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md)。
**Topics**
+ [使用 Fleet Manager 来查看 OS 文件系统](fleet-manager-viewing-file-system.md)
+ [使用 Fleet Manager 来预览 OS 文件](fleet-manager-preview-os-files.md)
+ [使用 Fleet Manager 来查看 OS 文件的末尾内容](fleet-manager-tailing-os-files.md)
+ [使用 Fleet Manager 来复制、剪切和粘贴 OS 文件或目录](fleet-manager-move-files-or-directories.md)
+ [使用 Fleet Manager 来重命名 OS 文件和目录](fleet-manager-renaming-files-and-directories.md)
+ [使用 Fleet Manager 来删除 OS 文件和目录](fleet-manager-deleting-files-and-directories.md)
+ [使用 Fleet Manager 来创建 OS 目录](fleet-manager-creating-directories.md)
+ [使用 Fleet Manager 来剪切、复制和粘贴 OS 目录](fleet-manager-managing-directories.md)
# 使用 Fleet Manager 来查看 OS 文件系统
您可以使用 Fleet Manager 来查看 Systems Manager 托管节点上的 OS 文件系统。
**要使用 Fleet Manager 来查看 OS 文件系统**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要查看的文件系统。
1. 选择**工具，文件系统**。
# 使用 Fleet Manager 来预览 OS 文件
您可以使用 Fleet Manager 来预览 OS 上的文本文件。
**要使用 Fleet Manager 来预览文本文件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要预览的文件。
1. 选择**工具，文件系统**。
1. 选择目录（其中包含要预览的文件）的 **File name**（文件名）。
1. 选择要预览其内容的文件旁边的按钮。
1. 选择**操作，以文本形式预览**。
# 使用 Fleet Manager 来查看 OS 文件的末尾内容
您可以使用 Fleet Manager 在托管节点上查看文件的末尾内容。
**使用 Fleet Manager 来查看 OS 文件的末尾内容**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要查看其末尾内容的文件。
1. 选择**工具，文件系统**。
1. 选择目录（其中包含要查看其末尾内容的文件）的 **File name**（文件名）。
1. 选择要查看其末尾内容的文件旁边的按钮。
1. 选择 **Actions, Tail file**（操作，查看文件末尾内容）。
# 使用 Fleet Manager 来复制、剪切和粘贴 OS 文件或目录
您可以使用 Fleet Manager 在托管节点上复制、剪切和粘贴 OS 文件。
**要使用 Fleet Manager 来复制或剪切和粘贴文件或目录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要复制或者剪切并粘贴的文件。
1. 选择**工具，文件系统**。
1. 要复制或剪切文件，请选择目录（其中包含要复制或剪切的文件）的 **File name**（文件名）。要复制或剪切目录，请选择要复制或剪切的目录旁边的按钮，然后继续执行步骤 8。
1. 选择要复制或剪切的文件旁边的按钮。
1. 在 **Actions**（操作）菜单中，选择 **Copy**（复制）或 **Cut**（剪切）。
1. 在 **File system**（文件系统）视图中，选择要粘贴文件的目录旁边的按钮。
1. 在 **Actions**（操作）菜单中，选择 **Paste**（粘贴）。
# 使用 Fleet Manager 来重命名 OS 文件和目录
您可以使用 Fleet Manager 来重命名您账户中托管节点上的文件和目录。
**要使用 Fleet Manager 来重命名文件或目录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要重命名的文件或目录。
1. 选择**工具，文件系统**。
1. 要重命名文件，请选择目录（其中包含要重命名的文件）的 **File name**（文件名）。要重命名目录，请选择要重命名的目录旁边的按钮，然后继续执行步骤 8。
1. 选择要对其内容进行重命名的文件旁边的按钮。
1. 选择**操作，重命名**。
1. 对于**文件名**，输入文件的新名称，然后选择**重命名**。
# 使用 Fleet Manager 来删除 OS 文件和目录
您可以使用 Fleet Manager 来删除您账户中托管节点上的文件和目录。
**要使用 Fleet Manager 来删除文件或目录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要删除的文件或目录。
1. 选择**工具，文件系统**。
1. 要删除文件，请选择目录（其中包含要删除的文件）的 **File name**（文件名）。要删除目录，请选择要删除的目录旁边的按钮，然后继续执行步骤 7。
1. 选择包含要删除的内容之文件旁边的按钮。
1. 选择**操作，删除**。
# 使用 Fleet Manager 来创建 OS 目录
您可以使用 Fleet Manager 来创建您账户中托管节点上的目录。
**要使用 Fleet Manager 来创建目录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其中创建目录的托管式节点的链接。
1. 选择**工具，文件系统**。
1. 选择要在其中创建新目录的目录的 **File name**（文件名）。
1. 选择 **Create directory**（创建目录）。
1. 对于**目录名称**，输入新目录的名称，然后选择**创建目录**。
# 使用 Fleet Manager 来剪切、复制和粘贴 OS 目录
您可以使用 Fleet Manager 来剪切、复制和粘贴您账户中托管节点上的目录。
**使用 Fleet Manager 来复制或剪切和粘贴目录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择托管式节点的链接，其中包含要复制或者剪切并粘贴的文件。
1. 选择**工具，文件系统**。
1. 选择要复制或剪切的目录旁边的按钮，然后继续执行步骤 8。
1. 在 **Actions**（操作）菜单中，选择 **Copy**（复制）或 **Cut**（剪切）。
1. 在 **File system**（文件系统）视图中，选择要粘贴文件的目录旁边的按钮。
1. 在 **Actions**（操作）菜单中，选择 **Paste**（粘贴）。
# 监控托管式节点性能
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）来实时查看有关托管式节点的性能数据。性能数据可从性能计数器检索。
Fleet Manager 中提供了以下性能计数器：
+ CPU 使用率
+ 磁盘输入/输出 (I/O) 利用率
+ 网络流量
+ 内存使用量
**注意**
Fleet Manager 使用Session Manager（AWS Systems Manager 中的一项工具）来检索性能数据。对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，附加到托管式实例的实例配置文件必须向 Session Manager 提供权限才能使用此功能。有关向实例配置文件添加 Session Manager 权限的更多信息，请参阅 [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md)。
**使用 Fleet Manager 查看性能数据**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要监控其性能的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，性能计数器**。
# 使用进程
您可以通过 Fleet Manager（AWS Systems Manager 中的一项工具）来使用托管式节点上运行的进程。通过 Fleet Manager，您可以查看有关进程的信息。例如，除句柄和线程外，您还可以查看进程的 CPU 利用率和内存使用情况。使用 Fleet Manager，您可以从控制台启动和终止进程。
**注意**
Fleet Manager 使用Session Manager（AWS Systems Manager 中的一项工具）来检索进程数据。对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，附加到托管式实例的实例配置文件必须向 Session Manager 提供权限才能使用此功能。有关向实例配置文件添加 Session Manager 权限的更多信息，请参阅 [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md)。
**Topics**
+ [使用 Fleet Manager 来查看有关 OS 进程的详细信息](fleet-manager-view-process-details.md)
+ [使用 Fleet Manager 在托管节点上启动 OS 进程](fleet-manager-start-process.md)
+ [使用 Fleet Manager 来终止 OS 进程](fleet-manager-terminate-process.md)
# 使用 Fleet Manager 来查看有关 OS 进程的详细信息
您可以使用 Fleet Manager 来查看托管节点上进程的详细信息。
**使用 Fleet Manager 来查看有关进程的详细信息**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要查看其进程的节点的链接。
1. 选择 **Tools, Processes**（工具，进程）。
# 使用 Fleet Manager 在托管节点上启动 OS 进程
您可以使用 Fleet Manager 在托管节点上启动进程。
**使用 Fleet Manager 启动进程**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上启动进程的托管节点的链接。
1. 选择 **Tools, Processes**（工具，进程）。
1. 选择 **Start new process**（启动新进程）。
1. 对于**进程名称或完整路径**，输入进程名称或可执行文件的完整路径。
1. （可选）对于**工作目录**，输入要运行进程的目录路径。
# 使用 Fleet Manager 来终止 OS 进程
**使用 Fleet Manager 来终止 OS 进程**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上启动进程的托管节点的链接。
1. 选择 **Tools, Processes**（工具，进程）。
1. 选择要终止的进程旁边的按钮。
1. 选择**操作，终止进程**或**操作，终止进程树**。
**注意**
终止进程树还会终止使用该进程的所有进程和应用程序。
# 查看托管式节点上的日志
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）查看存储在托管式节点上的日志数据。对于 Windows 托管式节点，您可以从控制台查看 Windows 事件日志并复制其详细信息。要帮助您搜索事件，请按 **Event level (事件级别)**、**Event ID (事件 ID)**、**Event source (事件源)** 和 **Time created (创建时间)** 筛选 Windows 事件日志。您还可以使用查看文件系统的过程查看其他日志数据。有关使用 Fleet Manager 查看文件系统的更多信息，请参阅 [通过 Fleet Manager 来使用 OS 文件系统](fleet-manager-file-system-management.md)。
**使用 Fleet Manager 查看 Windows 事件日志**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Fleet Manager**。
1. 选择要查看其事件日志的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，Windows 事件日志**。
1. 选择其中包含您要查看的事件的 **Log name (日志名称)**。
1. 选择您要查看的 **Log name (日志名称)** 旁边的按钮，然后选择 **View events (查看事件)**。
1. 选择您要查看的事件旁边的按钮，然后选择 **View event details (查看事件详细信息)**。
1. （可选）选择 **Copy as JSON (作为 JSON 进行复制)**，将事件详细信息复制到剪贴板。
# 使用 Fleet Manager 来管理托管式节点上的 OS 用户账户和组
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）来管理托管式节点上的操作系统（OS）用户账户和组。例如，您可以创建和删除用户和组。此外，您还可以查看组成员资格、用户角色和状态等详细信息。
**重要**
Fleet Manager 使用 Run Command 和Session Manager（都是 AWS Systems Manager 中的工具）进行各种用户管理操作。因此，用户可以向操作系统用户账户授予权限，否则他们将无法授予这些权限。这是因为 AWS Systems Manager 代理（SSM Agent）使用根权限（Linux）或 SYSTEM 权限（Windows Server）在 Amazon Elastic Compute Cloud（Amazon EC2）实例上运行。有关通过 SSM Agent 限制对根级别命令的访问的更多信息，请参阅 [通过 SSM Agent 限制对根级别命令的访问](ssm-agent-restrict-root-level-commands.md)。要限制对此功能的访问，我们建议为您的用户创建 AWS Identity and Access Management (IAM) policy，这些策略仅允许访问您定义的操作。有关为 Fleet Manager 创建 IAM policy 的更多信息，请参阅 [控制对 Fleet Manager 的访问](configuring-fleet-manager-permissions.md)。
**Topics**
+ [使用 Fleet Manager 来创建 OS 用户或组](manage-os-user-accounts-create.md)
+ [使用 Fleet Manager 来更新用户或组成员资格](manage-os-user-accounts-update.md)
+ [使用 Fleet Manager 来删除 OS 用户或组](manage-os-user-accounts-delete.md)
# 使用 Fleet Manager 来创建 OS 用户或组
**注意**
Fleet Manager 可以使用 Session Manager 为新用户设置密码。对于 Amazon EC2 实例，附加到托管式实例的实例配置文件必须向 Session Manager 提供权限才能使用此功能。有关向实例配置文件添加 Session Manager 权限的更多信息，请参阅 [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md)。
您可以使用 Fleet Manager 控制台来执行相同的任务，而不必直接登录到服务器来创建用户帐户或组。
**使用 Fleet Manager 来创建 OS 用户账户**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上创建新用户的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，用户和组**。
1. 选择 **Users (用户)** 选项卡，然后选择 **Create user (创建用户)**。
1. 为新用户的 **Name (名称)** 输入一个值。
1. （推荐）选中 **Set password (设置密码)** 旁边的复选框。在该过程结束时，系统将提示您为新用户提供密码。
1. 选择 **Create user (创建用户)**。如果选中此复选框为新用户创建密码，系统将提示您输入密码的值，然后选择 **Done (已完成)**。如果您指定的密码不符合托管式节点的本地或域策略指定的要求，将返回错误。
**使用 Fleet Manager 来创建 OS 组**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其中创建组的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，用户和组**。
1. 选择 **Groups (组)** 选项卡，然后选择 **Create group (创建组)**。
1. 为新组的 **Name (名称)** 输入一个值。
1. （可选）为新组的 **Description (描述)** 输入一个值。
1. （可选）选择要添加到新组的 **Group members (组成员)** 中的用户。
1. 选择 **Create group (创建组)**。
# 使用 Fleet Manager 来更新用户或组成员资格
您可以使用 Fleet Manager 控制台来执行相同的任务，而不必直接登录到服务器来更新用户帐户或组。
**要使用 Fleet Manager 将 OS 用户账户添加到新组**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要更新的用户账户所在的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，用户和组**。
1. 选择**用户**选项卡。
1. 选择要更新的用户旁边的按钮。
1. 选择**操作，将用户添加到组**。
1. 在 **Add to group (添加到组)** 下，选择要向其添加用户的组。
1. 选择 **Add user to group (将用户添加到组)**。
**要使用 Fleet Manager 来编辑 OS 组的成员资格**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要更新的组所在的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，用户和组**。
1. 选择**组**选项卡。
1. 选择要更新的组旁边的按钮。
1. 选择**操作，修改组**。
1. 在**组成员** 下，选择要添加或删除的用户。
1. 选择**修改组**。
# 使用 Fleet Manager 来删除 OS 用户或组
您可以使用 Fleet Manager 控制台来执行相同的任务，而不必直接登录到服务器来删除用户帐户或组。
**使用 Fleet Manager 来删除 OS 用户账户**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要删除的用户账户所在的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**用户和组**。
1. 选择**用户**选项卡。
1. 选择要删除的用户旁边按钮。
1. 选择**操作，删除本地用户**。
**要使用 Fleet Manager 来删除 OS 组**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要删除的组所在的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，用户和组**。
1. 选择**组**选项卡。
1. 选择要更新的组旁边的按钮。
1. 选择**操作，删除本地组**。
# 在托管式节点上管理 Windows 注册表
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）来管理 Windows Server 托管式节点上的注册表。您可以从 Fleet Manager 控制台创建、复制、更新及删除注册表项和值。
**重要**
在修改注册表之前，我们建议您创建注册表的备份，或者为附加到托管式节点的 Amazon Elastic Block Store (Amazon EBS) 根卷拍摄快照。如果不正确地修改注册表，可能会出现严重问题。这些问题可能需要您重新安装操作系统，或从快照还原节点的根卷。AWS 并不能保证这些问题能得到解决。修改注册表需自行承担风险。所有注册表更改均应由您承担责任，并确保您有备份。
## 创建 Windows 注册表键或项
**使用 Fleet Manager 创建 Windows 注册表键**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上创建注册表项的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，Windows 注册表**。
1. 通过选择 **Registry name**（注册表名称），选择要在其中创建新注册表键的配置单元。
1. 选择**创建，创建注册表键**。
1. 选择要在其中创建新键的注册表项旁边的按钮。
1. 选择 **Create registry key (创建注册表键)**。
1. 为新注册表键的 **Name (名称)** 输入一个值，然后选择 **Submit (提交)**。
**使用 Fleet Manager 创建 Windows 注册表项**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上创建注册表项的实例旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，Windows 注册表**。
1. 选择配置单元，然后通过选择 **Registry name**（注册表名称），选择要在其中创建新注册表项的后续注册表键。
1. 选择**创建，创建注册表项**。
1. 为新注册表项的 **Name (名称)** 输入一个值。
1. 选择要为该注册表项创建的值的 **Type (类型)**。有关注册表值类型的更多信息，请参阅[注册表值的类型](https://docs.microsoft.com/en-us/windows/win32/sysinfo/registry-value-types)。
1. 为新注册表项的 **Value (值)** 输入一个值。
## 更新 Windows 注册表项
**使用 Fleet Manager 更新 Windows 注册表项**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上更新注册表项的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，Windows 注册表**。
1. 选择配置单元，然后通过选择 **Registry name**（注册表名称），选择要更新的后续注册表键。
1. 选择要更新的注册表项旁边的按钮。
1. 选择**操作，更新注册表项**。
1. 为注册表项的 **Value (值)** 输入新值。
1. 选择**更新**。
## 删除 Windows 注册表项或键
**使用 Fleet Manager 删除 Windows 注册表键**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上删除注册表项的托管式节点旁边的按钮。
1. 选择**工具，Windows 注册表**。
1. 选择配置单元，然后通过选择 **Registry name**（注册表名称），选择要删除的后续注册表键。
1. 选择要删除的注册表键旁边的按钮。
1. 选择**操作，删除注册表键**。
**使用 Fleet Manager 删除 Windows 注册表项**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要在其上删除注册表项的托管式节点旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，Windows 注册表**。
1. 选择配置单元，然后通过选择 **Registry name**（注册表名称），选择包含要删除的注册表项的后续注册表键。
1. 选择要删除的注册表项旁边的按钮。
1. 选择**操作，删除注册表项**。
# 使用默认主机管理配置自动管理 EC2 实例
通过“默认主机管理配置”设置，AWS Systems Manager 可以将 Amazon EC2 实例作为*托管式实例*自动管理。托管实例是一个配置为与 Systems Manager 一起使用的 EC2 实例。
使用 Systems Manager 管理实例的好处包括以下几点：
+ 可以使用 Session Manager 安全地连接到您的 EC2 实例。
+ 可以使用 Patch Manager 执行自动补丁扫描。
+ 可以使用 Systems Manager 清单查看有关您的实例的详细信息。
+ 可以使用 Fleet Manager 追踪和管理实例。
+ 可以自动保持 SSM Agent 处于最新状态。
*Fleet Manager、Inventory、Patch Manager和Session Manager都是 Systems Manager 中的工具。*
使用默认主机管理配置时，无需手动创建 AWS Identity and Access Management（IAM）实例配置文件即可管理 EC2 实例。“默认主机管理配置”会创建并应用默认 IAM 角色，确保 Systems Manager 有权管理已激活该设置的 AWS 账户 和 AWS 区域 中的所有实例。
如果提供的权限不足以满足您的应用场景要求，您还可以向“默认主机管理配置”创建的默认 IAM 角色添加策略。或者，如果您不需要默认 IAM 角色提供的所有功能的权限，可以创建自己的自定义角色和策略。对您为“默认主机管理配置”选择的 IAM 角色所做的任何更改，都适用于相应区域和账户中的所有托管 Amazon EC2 实例。
有关“默认主机管理配置”所用策略的更多信息，请参阅 [AWS 托管式策略：AmazonSSMManagedEC2InstanceDefaultPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSSMManagedEC2InstanceDefaultPolicy)。
**实施最低权限访问**
本主题中的过程仅由管理员执行。因此，我们建议实施*最低权限访问权限*，以防止非管理员用户配置或修改“默认主机管理配置”。要查看限制访问“默认主机管理配置”时的策略示例，请参阅本主题后面的 [“默认主机管理配置”的最低权限策略示例](#least-privilege-examples)。
**重要**
使用“默认主机管理配置”注册的实例的注册信息，存储在本地的 `var/lib/amazon/ssm` 或 `C:\ProgramData\Amazon` 目录中。如果移除这些目录或其中的文件，将导致实例无法使用默认主机管理配置获取连接到 Systems Manager 所需的凭证。在这些情况下，您必须使用 IAM 实例配置文件为实例提供所需的权限，或者重新创建实例。
**Topics**
+ [先决条件](#dhmc-prerequisites)
+ [激活“默认主机管理配置”设置](#dhmc-activate)
+ [停用“默认主机管理配置”设置](#dhmc-deactivate)
+ [“默认主机管理配置”的最低权限策略示例](#least-privilege-examples)
## 先决条件
要在激活该设置的 AWS 区域 和 AWS 账户 中使用“默认主机管理配置”，就必须满足以下要求。
+ 要管理的实例必须使用实例元数据服务版本 2（imdsv2）。
“默认主机管理配置”不支持实例元数据服务版本 1。有关过渡到 IMDSv2 的信息，请参阅《Amazon EC2 用户指南》**中的[转换为使用实例元数据服务版本 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.html)。
+ 3.2.582.0 版本或更高版本的 SSM Agent 必须安装在实例上。
有关检查您的实例上安装的 SSM Agent 版本的信息，请参阅 [正在检查 SSM Agent 版本号](ssm-agent-get-version.md)。
有关更新 SSM Agent 的信息，请参阅 [自动更新 SSM Agent](ssm-agent-automatic-updates.md#ssm-agent-automatic-updates-console)。
+ 作为执行本主题中任务的管理员，您必须具有 [GetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetServiceSetting.html)、[ResetServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_ResetServiceSetting.html) 和 [UpdateServiceSetting](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateServiceSetting.html) API 操作的权限。此外，您还必须有权获得 `AWSSystemsManagerDefaultEC2InstanceManagementRole` IAM 角色的 `iam:PassRole` 权限。以下是提供这些权限的示例策略。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetServiceSetting",
"ssm:ResetServiceSetting",
"ssm:UpdateServiceSetting"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
},
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com"
]
}
}
}
]
}
```
------
+ 如果已经使用 Systems Manager 将 IAM 实例配置文件附加到要管理的 EC2 实例，则必须从中移除任何允许 `ssm:UpdateInstanceInformation` 操作的权限。SSM Agent 会首先尝试使用实例配置文件权限，然后才会使用“默认主机管理配置”权限。如果您在自己的 IAM 实例配置文件中允许该 `ssm:UpdateInstanceInformation` 操作，则该实例将不使用“默认主机管理配置”权限。
## 激活“默认主机管理配置”设置
您可以从 Fleet Manager 控制台或者使用 AWS Command Line Interface 或 AWS Tools for Windows PowerShell 激活“默认主机管理配置”。
您必须在想要通过此设置管理 Amazon EC2 实例的每个区域中，逐个开启“默认主机管理配置”。
在开启“默认主机管理配置”后，实例最多可能需要 30 分钟，就能使用您在下述过程步骤 5 中所选角色的凭证。
**激活“默认主机管理配置”（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择**账户管理，配置默认主机管理配置**。
1. 打开**启用默认主机管理配置**。
1. 选择用于为您的实例启用 Systems Manager 工具的 AWS Identity and Access Management（IAM）角色。我们建议使用“默认主机管理配置”提供的默认角色。它包含使用 Systems Manager 管理您的 Amazon EC2 实例所需的最低权限集合。如果您更喜欢使用自定义角色，则该角色的信任策略必须允许 Systems Manager 作为可信实体。
1. 选择**配置**以完成设置。
**激活“默认主机管理配置”（命令行）**
1. 在您的本地计算机上创建包含以下信任关系策略的 JSON 文件。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"",
"Effect":"Allow",
"Principal":{
"Service":"ssm.amazonaws.com"
},
"Action":"sts:AssumeRole"
}
]
}
```
------
1. 打开 AWS CLI 或 Tools for Windows PowerShell 并运行以下命令之一，以在您的账户中创建一个服务角色，具体取决于您本地计算机的操作系统类型。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws iam create-role \
--role-name AWSSystemsManagerDefaultEC2InstanceManagementRole \
--path /service-role/ \
--assume-role-policy-document file://trust-policy.json
```
------
#### [ Windows ]
```
aws iam create-role ^
--role-name AWSSystemsManagerDefaultEC2InstanceManagementRole ^
--path /service-role/ ^
--assume-role-policy-document file://trust-policy.json
```
------
#### [ PowerShell ]
```
New-IAMRole `
-RoleName "AWSSystemsManagerDefaultEC2InstanceManagementRole" `
-Path "/service-role/" `
-AssumeRolePolicyDocument "file://trust-policy.json"
```
------
1. 运行以下命令，将 `AmazonSSMManagedEC2InstanceDefaultPolicy` 托管策略附加到您新建的角色。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedEC2InstanceDefaultPolicy \
--role-name AWSSystemsManagerDefaultEC2InstanceManagementRole
```
------
#### [ Windows ]
```
aws iam attach-role-policy ^
--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedEC2InstanceDefaultPolicy ^
--role-name AWSSystemsManagerDefaultEC2InstanceManagementRole
```
------
#### [ PowerShell ]
```
Register-IAMRolePolicy `
-PolicyArn "arn:aws:iam::aws:policy/AmazonSSMManagedEC2InstanceDefaultPolicy" `
-RoleName "AWSSystemsManagerDefaultEC2InstanceManagementRole"
```
------
1. 打开 AWS CLI 或 Tools for Windows PowerShell 并运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm update-service-setting \
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role \
--setting-value service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole
```
------
#### [ Windows ]
```
aws ssm update-service-setting ^
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role ^
--setting-value service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole
```
------
#### [ PowerShell ]
```
Update-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role" `
-SettingValue "service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole"
```
------
如果此命令成功，则无任何输出。
1. 运行以下命令，以查看当前的 AWS 账户 和 AWS 区域 中“默认主机管理配置”的当前服务设置。
------
#### [ Linux & macOS ]
```
aws ssm get-service-setting \
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role
```
------
#### [ Windows ]
```
aws ssm get-service-setting ^
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role
```
------
#### [ PowerShell ]
```
Get-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
```
------
此命令会返回如下信息。
```
{
"ServiceSetting": {
"SettingId": "/ssm/managed-instance/default-ec2-instance-management-role",
"SettingValue": "service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"LastModifiedDate": "2022-11-28T08:21:03.576000-08:00",
"LastModifiedUser": "System",
"ARN": "arn:aws:ssm:us-east-2:-123456789012:servicesetting/ssm/managed-instance/default-ec2-instance-management-role",
"Status": "Custom"
}
}
```
## 停用“默认主机管理配置”设置
您可以从 Fleet Manager 控制台或者使用 AWS Command Line Interface 或 AWS Tools for Windows PowerShell 停用“默认主机管理配置”。
您必须在不再想要通过此配置管理 Amazon EC2 实例的每个区域中，逐个关闭“默认主机管理配置”设置。在一个区域将其停用，不会在所有区域将其停用。
如果您停用“默认主机管理配置”，并且未将实例配置文件附加到允许访问 Systems Manager 的 Amazon EC2 实例，则这些实例将不再由 Systems Manager 管理。
**停用“默认主机管理配置”（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择**账户管理，默认主机管理配置**。
1. 关闭**启用默认主机管理配置**。
1. 选择**配置**以禁用“默认主机管理配置”。
**停用“默认主机管理配置”（命令行）**
+ 打开 AWS CLI 或 Tools for Windows PowerShell 并运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm reset-service-setting \
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role
```
------
#### [ Windows ]
```
aws ssm reset-service-setting ^
--setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role
```
------
#### [ PowerShell ]
```
Reset-SSMServiceSetting `
-SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
```
------
## “默认主机管理配置”的最低权限策略示例
以下示例策略演示如何防止组织成员更改您账户中的“默认主机管理配置”设置。
### 适用于 AWS Organizations 的服务控制策略
以下策略演示如何防止您 AWS Organizations 中的非管理员成员更新您的“默认主机管理配置”设置。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Deny",
"Action": [
"ssm:UpdateServiceSetting",
"ssm:ResetServiceSetting"
],
"Resource": "arn:aws:ssm:*:*:servicesetting/ssm/managed-instance/default-ec2-instance-management-role",
"Condition": {
"StringNotEqualsIgnoreCase": {
"aws:PrincipalTag/job-function": [
"administrator"
]
}
}
},
{
"Effect": "Deny",
"Action": [
"iam:PassRole"
],
"Resource": "arn:aws:iam::*:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "ssm.amazonaws.com"
},
"StringNotEqualsIgnoreCase": {
"aws:PrincipalTag/job-function": [
"administrator"
]
}
}
},
{
"Effect": "Deny",
"Resource": "arn:aws:iam::*:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole",
"Action": [
"iam:AttachRolePolicy",
"iam:DeleteRole"
],
"Condition": {
"StringNotEqualsIgnoreCase": {
"aws:PrincipalTag/job-function": [
"administrator"
]
}
}
}
]
}
```
------
### 适用于 IAM 主体的策略
以下策略演示如何防止您 AWS Organizations 中的 IAM 组、角色或用户更新您的“默认主机管理配置”设置。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ssm:UpdateServiceSetting",
"ssm:ResetServiceSetting"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:servicesetting/ssm/managed-instance/default-ec2-instance-management-role"
},
{
"Effect": "Deny",
"Action": [
"iam:AttachRolePolicy",
"iam:DeleteRole",
"iam:PassRole"
],
"Resource": "arn:aws:iam::111122223333:role/service-role/AWSSystemsManagerDefaultEC2InstanceManagementRole"
}
]
}
```
------
# 使用 Remote Desktop 连接到 Windows Server 托管式实例
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具），通过 Remote Desktop Protocol（RDP）连接到自己的 Windows Server Amazon Elastic Compute Cloud（Amazon EC2）实例。Fleet Manager远程桌面由 [Amazon DCV](https://docs.aws.amazon.com/dcv/latest/adminguide/what-is-dcv.html) 提供支持，可让您直接从 Systems Manager 控制台安全连接到 Windows Server 实例。在一个浏览器窗口中最多可以同时连接四个连接。
Fleet Manager 远程桌面 API 被命名为 AWS Systems Manager GUI Connect。有关 Systems Manager GUI Connect API 的使用信息，请参阅 *[AWS Systems Manager GUI ConnectAPI 参考](https://docs.aws.amazon.com/ssm-guiconnect/latest/APIReference)*。
目前，您只能对运行 Windows Server 2012 RTM 或更高版本的实例使用远程桌面。远程桌面仅支持英语输入。
Fleet Manager Remote Desktop 是一项仅适用于控制台的服务，不支持通过命令行连接到托管式实例。要通过 Shell 连接到 Windows Server 托管式实例，可以使用 Session Manager（AWS Systems Manager 中的另一项工具）。有关更多信息，请参阅 [AWS Systems Manager Session Manager](session-manager.md)。
**注意**
RDP 连接的持续时间并不是由 AWS Identity and Access Management（IAM）凭证的持续时间决定的。相反，连接会持续存在，直到达到最大连接持续时间或空闲时间限制为止（以先到者为准）。有关更多信息，请参阅 [远程连接持续时间和并发](#rdp-duration-concurrency)。
有关配置 AWS Identity and Access Management（IAM）权限以允许实例与 Systems Manager 交互的信息，请参阅[为 Systems Manager 配置实例权限](setup-instance-permissions.md)。
**Topics**
+ [设置环境](#rdp-prerequisites)
+ [为远程桌面配置 IAM 权限](#rdp-iam-policy-examples)
+ [验证远程桌面连接](#rdp-authentication)
+ [远程连接持续时间和并发](#rdp-duration-concurrency)
+ [Systems Manager GUI Connect 对 AWS IAM Identity Center 属性的处理](#iam-identity-center-attribute-handling)
+ [使用远程桌面连接到托管式节点](#rdp-connect-to-node)
+ [查看有关当前和已完成连接的信息](#list-connections)
## 设置环境
在使用远程桌面之前，请确保环境满足以下要求：
+ **托管式节点配置**
确保在 Systems Manager 中将您的 Amazon EC2 实例配置为[托管式节点](fleet-manager-managed-nodes.md)。
+ **最低 SSM Agent 版本**
验证节点运行的 SSM Agent 版本是否为 3.0.222.0 或更高版本。有关如何检查节点上正在运行哪个代理版本的信息，请参阅 [正在检查 SSM Agent 版本号](ssm-agent-get-version.md)。有关安装或更新 SSM Agent 的信息，请参阅 [使用 SSM Agent](ssm-agent.md)。
+ **RDP 端口配置**
要接受远程连接，Windows Server 节点上的 Remote Desktop Services 服务必须使用默认 RDP 端口 3389。这是 AWS 提供的 Amazon Machine Images（AMIs）上的默认配置。系统没有明确要求您打开任何入站端口才能使用远程桌面。
+ **键盘功能的 PSReadLine 模块版本**
为确保您的键盘在 PowerShell 中正常运行，请验证运行 Windows Server 2022 的节点是否安装了 PSReadLine 模块版本 2.2.2 或更高版本。如果它们运行的是旧版本，您可以使用以下命令安装所需的版本。
```
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
```
NuGet 程序包提供程序安装完成后，请运行以下命令。
```
Install-Module `
-Name PSReadLine `
-Repository PSGallery `
-MinimumVersion 2.2.2 -Force
```
+ **会话管理器配置**
使用远程桌面之前，您必须先完成会话管理器设置的先决条件。当您使用远程桌面连接到实例时，将应用为 AWS 账户 和 AWS 区域 定义的所有会话首选项。有关更多信息，请参阅 [设置 Session Manager](session-manager-getting-started.md)。
**注意**
如果您使用 Amazon Simple Storage Service（Amazon S3）记录会话管理器活动，则远程桌面连接将在 `bucket_name/Port/stderr` 中生成以下错误。该错误是预期行为，可以安全忽略。
```
Setting up data channel with id SESSION_ID failed: failed to create websocket for datachannel with error: CreateDataChannel failed with no output or error: createDataChannel request failed: unexpected response from the service
Session is already terminated
```
## 为远程桌面配置 IAM 权限
除了 Systems Manager 和 Session Manager 所需的 IAM 权限外，您使用的用户或角色还必须拥有启动连接的权限。
**启动连接的权限**
要在控制台中与 EC2 实例建立 RDP 连接，需要以下权限：
+ `ssm-guiconnect:CancelConnection`
+ `ssm-guiconnect:GetConnection`
+ `ssm-guiconnect:StartConnection`
**列出连接的权限**
要在控制台中查看连接列表，需要以下权限：
`ssm-guiconnect:ListConnections`
以下是 IAM policy 示例，您可以将这些策略附加到用户或角色以允许与远程桌面进行不同类型的交互。将每个*示例资源占位符*替换为您自己的信息。
### 用于连接到 EC2 实例的标准策略
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EC2",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:GetPasswordData"
],
"Resource": "*"
},
{
"Sid": "SSM",
"Effect": "Allow",
"Action": [
"ssm:DescribeInstanceProperties",
"ssm:GetCommandInvocation",
"ssm:GetInventorySchema"
],
"Resource": "*"
},
{
"Sid": "TerminateSession",
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"${aws:userid}"
]
}
}
},
{
"Sid": "SSMStartSession",
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:111122223333:instance/*",
"arn:aws:ssm:*:111122223333:managed-instance/*",
"arn:aws:ssm:*::document/AWS-StartPortForwardingSession"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "ssm-guiconnect.amazonaws.com"
}
}
},
{
"Sid": "GuiConnect",
"Effect": "Allow",
"Action": [
"ssm-guiconnect:CancelConnection",
"ssm-guiconnect:GetConnection",
"ssm-guiconnect:StartConnection",
"ssm-guiconnect:ListConnections"
],
"Resource": "*"
}
]
}
```
------
### 用于连接到具有特定标签的 EC2 实例的策略
**注意**
在以下 IAM 策略中，`SSMStartSession` 部分需要 `ssm:StartSession` 操作的 Amazon 资源名称（ARN）。如图所示，您指定的 ARN *不*需要 AWS 账户 ID。如果您指定账户 ID，则 Fleet Manager 会返回 `AccessDeniedException`。
位于示例策略下方的 `AccessTaggedInstances` 部分也要求提供 `ssm:StartSession` 的 ARN。对于这些 ARN，您需要指定 AWS 账户 ID。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EC2",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:GetPasswordData"
],
"Resource": "*"
},
{
"Sid": "SSM",
"Effect": "Allow",
"Action": [
"ssm:DescribeInstanceProperties",
"ssm:GetCommandInvocation",
"ssm:GetInventorySchema"
],
"Resource": "*"
},
{
"Sid": "SSMStartSession",
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ssm:*::document/AWS-StartPortForwardingSession"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "ssm-guiconnect.amazonaws.com"
}
}
},
{
"Sid": "AccessTaggedInstances",
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:111122223333:instance/*",
"arn:aws:ssm:*:111122223333:managed-instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/tag key": [
"tag value"
]
}
}
},
{
"Sid": "GuiConnect",
"Effect": "Allow",
"Action": [
"ssm-guiconnect:CancelConnection",
"ssm-guiconnect:GetConnection",
"ssm-guiconnect:StartConnection",
"ssm-guiconnect:ListConnections"
],
"Resource": "*"
}
]
}
```
------
### 用于 AWS IAM Identity Center 用户连接到 EC2 实例的策略
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SSO",
"Effect": "Allow",
"Action": [
"sso:ListDirectoryAssociations*",
"identitystore:DescribeUser"
],
"Resource": "*"
},
{
"Sid": "EC2",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:GetPasswordData"
],
"Resource": "*"
},
{
"Sid": "SSM",
"Effect": "Allow",
"Action": [
"ssm:DescribeInstanceProperties",
"ssm:GetCommandInvocation",
"ssm:GetInventorySchema"
],
"Resource": "*"
},
{
"Sid": "TerminateSession",
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"${aws:userName}"
]
}
}
},
{
"Sid": "SSMStartSession",
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*",
"arn:aws:ssm:*:*:managed-instance/*",
"arn:aws:ssm:*:*:document/AWS-StartPortForwardingSession"
],
"Condition": {
"ForAnyValue:StringEquals": {
"aws:CalledVia": "ssm-guiconnect.amazonaws.com"
}
}
},
{
"Sid": "SSMSendCommand",
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ec2:*:*:instance/*",
"arn:aws:ssm:*:*:managed-instance/*",
"arn:aws:ssm:*:*:document/AWSSSO-CreateSSOUser"
]
},
{
"Sid": "GuiConnect",
"Effect": "Allow",
"Action": [
"ssm-guiconnect:CancelConnection",
"ssm-guiconnect:GetConnection",
"ssm-guiconnect:StartConnection",
"ssm-guiconnect:ListConnections"
],
"Resource": "*"
}
]
}
```
------
## 验证远程桌面连接
建立远程连接时，您可以使用 Windows 凭证或与实例关联的 Amazon EC2 密钥对（`.pem` 文件）进行身份验证。有关使用密钥对的信息，请参阅《Amazon EC2 用户指南》**中的 [Amazon EC2 密钥对和 Windows 实例](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-key-pairs.html)。
或者，如果您已使用 AWS IAM Identity Center 对 AWS 管理控制台 进行身份验证，您可以在不提供额外凭证的情况下连接到实例。有关允许使用 IAM Identity Center 进行远程连接身份验证的策略示例，请参阅 [为远程桌面配置 IAM 权限](#rdp-iam-policy-examples)。
**开始前的准备工作**
在开始使用远程桌面进行连接之前，请注意以下有关使用 IAM Identity Center 身份验证的条件。
+ 远程桌面支持您启用 IAM Identity Center 的同一 AWS 区域 中的节点的 IAM Identity Center 身份验证。
+ 远程桌面支持最多 16 个字符的 IAM Identity Center 用户名。
+ 远程桌面支持由字母数字字符和以下特殊字符组成的 IAM Identity Center 用户名：`.` `-` `_`
**重要**
包含以下字符的 IAM Identity Center 用户名将无法成功连接：`+` `=` `,`
IAM Identity Center 支持用户名中的这些字符，但 Fleet Manager RDP 连接不支持。
此外，如果 IAM Identity Center 用户名包含一个或多个 `@` 符号，则 Fleet Manager 会忽略第一个 `@` 符号及其后面的所有字符，无论 `@` 是否引入电子邮件地址的域部分。例如，对于 IAM Identity Center 用户名 `diego_ramirez@example.com`，`@example.com` 部分将被忽略，而 Fleet Manager 的用户名变为 `diego_ramirez`。对于 `diego_r@mirez@example.com`，Fleet Manager 忽略 `@mirez@example.com`，并且 Fleet Manager 的用户名变为 `diego_r`。
+ 使用 IAM Identity Center 对连接进行身份验证后，远程桌面会在实例的本地管理员组中创建一个本地 Windows 用户。远程连接结束后，此用户仍然存在。
+ 远程桌面不允许对作为 Microsoft Active Directory 域控制器的节点进行 IAM Identity Center 身份验证。
+ 尽管远程桌面允许您对*已加入* Active Directory 域的节点使用 IAM Identity Center 身份验证，但我们不建议这样做。此身份验证方法向用户授予管理权限，这些权限可能会覆盖域授予的更严格的权限。
**IAM Identity Center 身份验证支持的区域**
以下 AWS 区域支持使用 IAM Identity Center 身份验证的 Remote Desktop 连接：
+ 美国东部（俄亥俄州）(us-east-2)
+ 美国东部（弗吉尼亚州北部）(us-east-1)
+ 美国西部（北加利福尼亚）(us-west-1)
+ 美国西部（俄勒冈州）(us-west-2)
+ 非洲（开普敦）(af-south-1)
+ 亚太地区（香港）(ap-east-1)
+ 亚太地区（孟买）(ap-south-1)
+ 亚太地区（东京）(ap-northeast-1)
+ 亚太地区（首尔）(ap-northeast-2)
+ 亚太地区（大阪）(ap-northeast-3)
+ 亚太地区（新加坡）(ap-southeast-1)
+ 亚太地区（悉尼）(ap-southeast-2)
+ 亚太地区（雅加达）（ap-southeast-3）
+ 加拿大（中部）(ca-central-1)
+ 欧洲地区（法兰克福）(eu-central-1)
+ 欧洲地区（斯德哥尔摩）(eu-north-1)
+ 欧洲地区（爱尔兰）(eu-west-1)
+ 欧洲地区（伦敦）(eu-west-2)
+ 欧洲地区（巴黎）（eu-west-3）
+ 以色列（特拉维夫）（il-central-1）
+ 南美洲（圣保罗）（sa-east-1）
+ 欧洲（米兰）(eu-south-1)
+ 中东（巴林）(me-south-1)
+ AWS GovCloud（美国东部）(us-gov-east-1)
+ AWS GovCloud（美国西部）(us-gov-west-1)
## 远程连接持续时间和并发
以下条件适用于活动的远程桌面连接：
+ **连接持续时间**
默认情况下，远程桌面连接会在 60 分钟后断开。为防止连接断开，您可以选择在断开连接之前**续订会话**以重置持续时间计时器。
+ **连接超时**
远程桌面连接在闲置超过 10 分钟后会断开连接。
+ **连接持久性**
使用远程桌面连接 Windows Server 后，连接会继续，直到达到最大连接持续时间（60 分钟）或空闲超时限制（10 分钟）。连接持续时间并不取决于 AWS Identity and Access Management（IAM）凭证的持续时间。即使 IAM 凭证到期，只要未达到连接持续时间限制，连接仍将继续。使用远程桌面时，如果 IAM 凭证到期，则应立即退出浏览器页面以终止连接。
+ **并发连接**
默认情况下，对于相同的 AWS 账户 和 AWS 区域，您同一时间最多可以有 5 个处于活动状态的远程桌面连接。要请求将服务配额增加到最多 50 个并发连接，请参阅《Service Quotas User Guide》**中的 [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)。
**注意**
Windows Server 的标准许可证允许两个并发 RDP 连接。要支持更多连接，必须从 Microsoft 购买额外的客户端访问许可证（CAL），或从 AWS 购买 Microsoft 远程桌面服务许可证。有关补充许可证的更多信息，请参阅以下主题：
Microsoft 网站上的 [Client Access Licenses and Management Licenses](https://www.microsoft.com/en-us/licensing/product-licensing/client-access-license)
《License Manager User Guide》**中的 [Use License Manager user-based subscriptions for supported software products](https://docs.aws.amazon.com/license-manager/latest/userguide/user-based-subscriptions.html)
## Systems Manager GUI Connect 对 AWS IAM Identity Center 属性的处理
Systems Manager GUI Connect 是支持使用 RDP 将 Fleet Manager 连接到 EC2 实例的 API。关闭连接后，将保留以下 IAM Identity Center 用户数据：
+ `username`
默认情况下，Systems Manager GUI Connect 使用 AWS 托管式密钥静态加密此身份属性。在 Systems Manager GUI Connect 中不支持使用客户托管密钥加密此属性。如果您删除 IAM Identity Center 实例中的用户，Systems Manager GUI Connect 将继续保留与该用户关联的 `username` 属性 7 年，之后删除该属性。保留这些数据是为了支持审计事件，例如列出 Systems Manager GUI Connect 连接历史记录。该数据无法手动删除。
## 使用远程桌面连接到托管式节点
**浏览器对文本的复制/粘贴支持**
若使用 Google Chrome 和 Microsoft Edge 浏览器，可以将托管式节点中的文本复制并粘贴到本地计算机，也可以将本地计算机中的文本复制并粘贴到所连接的托管式节点。
若使用 Mozilla Firefox 浏览器，则只能将托管式节点中的文本复制并粘贴到本地计算机，不能将本地计算机中的文本复制到托管式节点。
**使用 Fleet Manager 远程桌面连接到托管式节点**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择您想要连接到的节点。您可以选择复选框或节点名称。
1. 在**节点操作**菜单中，选择**连接远程桌面**。
1. 选择首选的 **Authentication type**（身份验证类型）。如果您选择**用户凭据**，请输入您要连接的节点上的 Windows 用户账户的用户名和密码。如果您选择**密钥对**，您可以使用以下方法之一提供身份验证：
1. 如果您想从本地文件系统中选择与您的实例关联的 PEM 密钥，请选择**浏览本地计算机**。
–或者–
1. 如果要复制 PEM 文件的内容并将其粘贴到提供的字段中，请选择**粘贴密钥对内容**。
1. 选择 **Connect**（连接）。
1. 要选择首选的显示分辨率，请在**操作**菜单中选择**分辨率**，然后从以下选项中进行选择：
+ **自动适应**
+ **1920 x 1080**
+ **1400 x 900**
+ **1366 x 768**
+ **800 x 600**
**自动适应**选项根据检测到的屏幕尺寸设置分辨率。
## 查看有关当前和已完成连接的信息
您可以使用 Systems Manager 控制台中的 Fleet Manager 部分来查看有关在您的账户中建立的 RDP 连接的信息。通过一组筛选条件，您可以按照时间范围、特定实例、建立连接的用户和特定状态的连接来缩小所显示的连接列表的范围。控制台还提供选项卡，显示有关所有当前活动连接和所有过去连接的信息。
**要查看有关当前和已完成连接的信息**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择**账户管理，连接远程桌面**。
1. 选择以下选项卡之一：
+ **活动连接**
+ **连接历史记录**
1. 要进一步缩小所显示的连接结果列表的范围，请在搜索 (![\[\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/search-icon.png)) 框中指定一个或多个筛选条件 您也可以输入自由文本搜索词。
# 在托管式实例上管理 Amazon EBS 卷
[Amazon Elastic Block Store](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html)（Amazon EBS）提供了块级存储卷，以与 Amazon Elastic Compute Cloud（Amazon EC2）实例一起使用。EBS 卷的行为类似于原始、未格式化的块储存设备。您可以将这些卷作为设备挂载在实例上。
您可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）来管理托管式实例上的 Amazon EBS 卷。例如，您可以初始化 EBS 卷，格式化分区，然后挂载该卷以使其可供使用。
**注意**
Fleet Manager 目前仅支持 Windows Server 实例的 Amazon EBS 卷管理。
## 查看 EBS 卷详细信息
**使用 Fleet Manager 查看 EBS 卷的详细信息**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要查看 EBS 卷详细信息的托管式实例旁边的按钮。
1. 请选择**查看详细信息**。
1. 选择**工具，EBS 卷**。
1. 要查看 EBS 卷的详细信息，请在**卷 ID**列中选择其 ID。
## 初始化和格式化 EBS 卷
**使用 Fleet Manager 初始化和格式化 EBS 卷**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要初始化、格式化和挂载 EBS 卷的托管式实例旁边的按钮。只有当磁盘为空时，才能对 EBS 卷进行初始化。
1. 请选择**查看详细信息**。
1. 在**工具**菜单中，选择 **EBS 卷**。
1. 选择要初始化和格式化的 EBS 卷的旁边的按钮。
1. 选择**初始化并格式化**。
1. 在**分区样式**中，选择要用于该 EBS 卷的分区样式。
1. （可选）为该分区选择一个**驱动器盘符**。
1. （可选）输入一个**分区名称**来标识该分区。
1. 选择用于整理分区中存储的文件和数据的**文件系统**。
1. 选择**确认**以使该 EBS 卷可供使用。确认后，您将无法从 AWS 管理控制台 更改分区配置，但可以使用 SSH 或 RDP 登录实例来更改分区配置。
# 访问 Red Hat 知识库门户
如果您是 Red Hat 客户，可以使用 Fleet Manager（AWS Systems Manager 中的一项工具）访问知识库门户。如果您在 AWS 上运行 Red Hat Enterprise Linux (RHEL) 实例或使用 RHEL 服务，您将被视为 Red Hat 客户。知识库门户包括二进制文件、知识共享和社群支持论坛，这些资源仅向获得 Red Hat 许可的客户提供。
除 Systems Manager 和 Fleet Manager 所需的 AWS Identity and Access Management（IAM）权限外，用于访问控制台的用户或角色还必须允许 `rhelkb:GetRhelURL` 操作能够访问知识库门户。
**访问 Red Hat 知识库门户**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 选择要用于连接到 Red Hat 知识库门户的 RHEL 实例。
1. 选择**账户管理**、**访问 Red Hat 知识库**以打开 Red Hat 知识库页面。
如果您使用 AWS 上的 RHEL 运行完全受支持的 RHEL 工作负载，您还可以使用 AWS 凭证，通过 Red Hat 的网站访问 Red Hat 知识库。
# 排除托管式节点可用性的问题
对于 Run Command、Distributor 和Session Manager等多项 AWS Systems Manager 工具，您可以选择手动选择要在其上运行操作的托管式节点。在这种情况下，指定要手动选择节点后，系统会显示托管式节点列表，您可以在其中运行该操作。
本主题提供的信息可帮助您诊断*您已确认正在运行的*托管式节点未包含在 Systems Manager 中的托管式节点列表中的原因。
为使节点能由 Systems Manager 管理，并在托管式节点列表中列出，它必须满足三个要求：
+ SSM Agent 必须在具有受支持的操作系统的节点上安装和运行。
**注意**
将一些 AWS 托管式 Amazon Machine Images（AMIs）配置为启动已预安装 [SSM Agent](ssm-agent.md) 的实例。（您还可以配置自定义 AMI 以预安装 SSM Agent。） 有关更多信息，请参阅 [查找预装了 SSM Agent 的 AMIs](ami-preinstalled-agent.md)。
+ 对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，您必须将 AWS Identity and Access Management (IAM) 实例配置文件附加到实例。实例配置文件让实例能够与 Systems Manager 服务进行通信。如果您没有为实例分配实例配置文件，则可以使用[混合激活](activations.md)进行注册，但这不是常见用例。
+ SSM Agent 必须能够连接到 Systems Manager 端点，以便将其自身注册到服务中。此后，托管式节点必须可用于服务，这一点将通过以下方法来确认：服务每五分钟发送一个信号，以检查实例的运行状况。
+ 在托管节点的状态保持 `Connection Lost` 至少 30 天后，该节点可能不再会在 Fleet Manager 控制台中列出。必须首先解决导致连接中断的问题，然后才能将其恢复到列表中。
在确认某个托管节点正在运行后，您可以使用以下命令来检查 SSM Agent 是否已成功注册到 Systems Manager 服务。在成功注册之前，此命令不会返回结果。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-associations-status \
--instance-id instance-id
```
------
#### [ Windows ]
```
aws ssm describe-instance-associations-status ^
--instance-id instance-id
```
------
#### [ PowerShell ]
```
Get-SSMInstanceAssociationsStatus `
-InstanceId instance-id
```
------
如果注册成功并且托管式节点现在可用于 Systems Manager 操作，该命令会返回类似于以下内容的结果。
```
{
"InstanceAssociationStatusInfos": [
{
"AssociationId": "fa262de1-6150-4a90-8f53-d7eb5EXAMPLE",
"Name": "AWS-GatherSoftwareInventory",
"DocumentVersion": "1",
"AssociationVersion": "1",
"InstanceId": "i-02573cafcfEXAMPLE",
"Status": "Pending",
"DetailedStatus": "Associated"
},
{
"AssociationId": "f9ec7a0f-6104-4273-8975-82e34EXAMPLE",
"Name": "AWS-RunPatchBaseline",
"DocumentVersion": "1",
"AssociationVersion": "1",
"InstanceId": "i-02573cafcfEXAMPLE",
"Status": "Queued",
"AssociationName": "SystemAssociationForScanningPatches"
}
]
}
```
如果注册尚未完成或失败，该命令将返回类似于以下内容的结果：
```
{
"InstanceAssociationStatusInfos": []
}
```
如果命令在 5 分钟左右后未返回结果，请使用以下信息帮助您对托管式节点的问题进行故障排除。
**Topics**
+ [解决方案 1：确认 SSM Agent 已安装在托管式节点上，并且正在运行](#instances-missing-solution-1)
+ [解决方案 2：确认已为实例（仅限 EC2 实例）指定 IAM 实例配置文件](#instances-missing-solution-2)
+ [解决方案 3：验证并确保服务终端节点的连接性](#instances-missing-solution-3)
+ [解决方案 4：验证并确保目标操作系统支持](#instances-missing-solution-4)
+ [解决方案 5：确认您在与 Amazon EC2 实例相同的 AWS 区域 中工作。](#instances-missing-solution-5)
+ [解决方案 6：验证应用于托管节点上 SSM Agent 的代理配置](#instances-missing-solution-6)
+ [解决方案 7：在托管式实例上安装 TLS 证书](#hybrid-tls-certificate)
+ [使用 `ssm-cli` 排除托管节点可用性的故障](troubleshooting-managed-nodes-using-ssm-cli.md)
## 解决方案 1：确认 SSM Agent 已安装在托管式节点上，并且正在运行
确保最新版本的 SSM Agent 已安装在托管式节点上，并且正在运行。
要确定 SSM Agent 是否已安装在托管式节点上并且正在运行，请参阅 [正在检查 SSM Agent 状态并启动代理](ssm-agent-status-and-restart.md)。
要在托管式节点上安装或重新安装 SSM Agent，请参阅以下主题：
+ [在适用于 Linux 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-linux.md)
+ [如何在混合 Linux 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-linux.md)
+ [在适用于 Windows Server 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-windows.md)
+ [如何在混合 Windows 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-windows.md)
## 解决方案 2：确认已为实例（仅限 EC2 实例）指定 IAM 实例配置文件
对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，确认实例已配置有允许实例与 Systems Manager API 通信的 AWS Identity and Access Management (IAM) 实例配置文件。此外，还要验证并确保您的用户具有 IAM 信任策略，允许您的用户与 Systems Manager API 通信。
**注意**
本地服务器、边缘设备和虚拟机 (VM) 使用 IAM 服务角色而不是实例配置文件。有关更多信息，请参阅[在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](hybrid-multicloud-service-role.md)。
**确定拥有所需权限的实例配置文件是否附加到 EC2 实例**
1. 通过以下网址打开 Amazon EC2 控制台：[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 在导航窗格中，选择 **Instances (实例)**。
1. 选择要检查实例配置文件的实例。
1. 在底部窗格中的 **Description (描述)** 选项卡上，找到 **IAM role (IAM 角色)**，然后选择角色的名称。
1. 在实例配置文件的角色 **Summary (摘要)** 页面上的 **Permissions (权限)** 选项卡上，确保 `AmazonSSMManagedInstanceCore` 列在 **Permissions policies (权限策略)** 之下。
如果改为使用自定义策略，请确保其提供的权限与 `AmazonSSMManagedInstanceCore` 相同。
[在控制台中打开 `AmazonSSMManagedInstanceCore`](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore$jsonEditor)
有关可以附加到 Systems Manager 的实例配置文件的其他策略的信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
## 解决方案 3：验证并确保服务终端节点的连接性
验证并确保实例可连接到 Systems Manager 服务终端节点。通过为 Systems Manager 创建和配置 VPC 终端节点，或者允许 HTTPS（端口 443）出站流量传输到服务终端节点，来提供此连接性。
对于 Amazon EC2 实例，如果 Virtual Private Cloud (VPC) 配置允许出站流量，则 AWS 区域 的 Systems Manager 服务终端节点可用于注册该实例。但是，如果启动实例的 VPC 配置不允许出站流量，并且您无法更改此配置以允许连接到公有服务终端节点，则必须改成为 VPC 配置接口端点。
有关更多信息，请参阅[使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。
## 解决方案 4：验证并确保目标操作系统支持
确认您选择的操作可在您希望看到列出的托管式节点类型上运行。某些 Systems Manager 操作既可仅以 Windows 实例作为目标，也可仅以 Linux 实例作为目标。例如，Systems Manager (SSM) 文档 `AWS-InstallPowerShellModule` 和 `AWS-ConfigureCloudWatch` 只能在 Windows 实例上运行。在 **Run a command (运行命令)** 页面上，如果选择这些文档之一，并选择 **Choose instances manually (手动选择实例)**，将仅列出您的 Windows 实例，并且仅有它们可供选择。
## 解决方案 5：确认您在与 Amazon EC2 实例相同的 AWS 区域 中工作。
Amazon EC2 实例将在特定 AWS 区域 中创建和使用，例如美国东部（俄亥俄）区域 (us-east-2) 或欧洲（爱尔兰）区域 (eu-west-1)。确保您在与要使用的 Amazon EC2 实例相同的 AWS 区域 中工作。有关更多信息，请参阅 *AWS 管理控制台 入门*中的[选择区域](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html#select-region)。
## 解决方案 6：验证应用于托管节点上 SSM Agent 的代理配置
验证应用于托管节点上 SSM Agent 的代理配置正确无误。如果代理配置不正确，则节点将无法连接到所需的服务终端节点，或者 Systems Manager 可能错误识别托管式节点的操作系统。有关更多信息，请参阅[配置 SSM Agent 以在 Linux 节点上使用代理](configure-proxy-ssm-agent.md)和[配置 SSM Agent以使用 Windows Server 实例的代理](configure-proxy-ssm-agent-windows.md)。
## 解决方案 7：在托管式实例上安装 TLS 证书
必须在与 AWS Systems Manager 结合使用的每个托管式实例上安装传输层安全性协议（TLS）证书。AWS 服务 使用这些证书来加密对其他 AWS 服务的调用。
默认情况下，从任何 Amazon Machine Image (AMI) 创建的每个 Amazon EC2 实例上都已安装 TLS 证书。大多数现代操作系统在其信任存储中包含来自 Amazon Trust Services CA 的所需 TLS 证书。
要验证实例上是否已安装所需的证书，请根据实例的操作系统运行以下命令。务必将 URL 的 *region* 部分替换为托管式实例所在的 AWS 区域。
------
#### [ Linux & macOS ]
```
curl -L https://ssm.region.amazonaws.com
```
------
#### [ Windows ]
```
Invoke-WebRequest -Uri https://ssm.region.amazonaws.com
```
------
命令应返回 `UnknownOperationException` 错误。如果您收到 SSL/TLS 错误消息，可能未安装所需的证书。
如果您发现所需的 Amazon Trust Services CA 证书未安装在您的基本操作系统、从并非由 Amazon 提供的 AMIs 创建的实例上或您自己的本地服务器和虚拟机上，则必须安装并允许来自 [Amazon Trust Services](https://www.amazontrust.com/repository/) 的证书，或使用 AWS Certificate Manager (ACM) 为受支持的集成服务创建和管理证书。
每个托管实例都必须安装以下传输层安全性 (TLS) 证书之一。
+ Amazon Root CA 1
+ Starfield Services Root Certificate Authority – G2
+ Starfield Class 2 Certificate Authority
有关使用 ACM 的信息，请参阅 [《AWS Certificate Manager 用户指南》](https://docs.aws.amazon.com/acm/latest/userguide/)。
如果您的计算环境中的证书由组策略对象 (GPO) 进行托管，则您可能需要将组策略配置为包含其中一个证书。
有关 Amazon Root 和 Starfield 证书的更多信息，请参阅博客文章 [How to Prepare for AWS’s Move to Its Own Certificate Authority](https://aws.amazon.com/blogs/security/how-to-prepare-for-aws-move-to-its-own-certificate-authority/)。
# 使用 `ssm-cli` 排除托管节点可用性的故障
`ssm-cli` 是包含在 SSM Agent 安装中的独立命令行工具。在计算机上安装 SSM Agent 3.1.501.0 或更高版本后，可以在该计算机上运行 `ssm-cli` 命令。这些命令的输出有助于确定，计算机是否满足要由 AWS Systems Manager 托管的 Amazon EC2 实例或非 EC2 计算机的最低要求，从而将其添加到 Systems Manager 的托管式节点列表中。（SSM Agent 版本 3.1.501.0 已于 2021 年 11 月发布。）
**最低要求**
对于要由 AWS Systems Manager 管理并在托管式节点列表中可用的 Amazon EC2 实例或非 EC2 计算机，必须满足三个主要要求：
+ SSM Agent 必须在具有[受支持的操作系统](operating-systems-and-machine-types.md#prereqs-operating-systems)的计算机上安装和运行。
将一些适用于 EC2 的 AWS 托管 Amazon Machine Images（AMIs）配置为启动已预安装 [SSM Agent](ssm-agent.md) 的实例。（您还可以配置自定义 AMI 以预安装 SSM Agent。） 有关更多信息，请参阅 [查找预装了 SSM Agent 的 AMIs](ami-preinstalled-agent.md)。
+ 必须将与 Systems Manager 服务进行通信提供所需权限的 AWS Identity and Access Management（IAM）实例配置文件（适用于 EC2 实例）或服务角色（适用于非 EC2 计算机）附加到该计算机上。
+ SSM Agent 必须能够连接到 Systems Manager 端点，以便将其自身注册到服务中。此后，托管节点必须可用于该服务，这一点将通过以下方法来确认：服务每五分钟发送一个信号，以检查托管节点的运行状况。
**`ssm-cli` 中预配置的命令**
包含用于收集所需信息的预配置命令，以帮助您诊断您已确认正在运行的计算机未包含在 Systems Manager 中的托管式节点列表中的原因。这些命令会在您指定 `get-diagnostics` 选项时运行。
在计算机上运行以下命令，使用 `ssm-cli` 帮助您排除托管节点可用性的故障。
------
#### [ Linux & macOS ]
```
ssm-cli get-diagnostics --output table
```
------
#### [ Windows ]
在 Windows Server 计算机上，您必须先导航到 `C:\Program Files\Amazon\SSM` 目录，才能运行该命令。
```
ssm-cli.exe get-diagnostics --output table
```
------
#### [ PowerShell ]
在 Windows Server 计算机上，您必须先导航到 `C:\Program Files\Amazon\SSM` 目录，才能运行该命令。
```
.\ssm-cli.exe get-diagnostics --output table
```
------
该命令以类似于下表的形式返回输出。
**注意**
对 `ssmmessages`、`s3`、`kms`、`logs` 和 `monitoring` 端点进行的连接检查针对其他可选功能，例如可以录入到 Amazon Simple Storage Service (Amazon S3) 或 Amazon CloudWatch Logs 并使用 AWS Key Management Service (AWS KMS) 加密的 Session Manager。
------
#### [ Linux & macOS ]
```
[root@instance]# ssm-cli get-diagnostics --output table
┌───────────────────────────────────────┬─────────┬───────────────────────────────────────────────────────────────────────┐
│ Check │ Status │ Note │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ EC2 IMDS │ Success │ IMDS is accessible and has instance id i-0123456789abcdefa in Region │
│ │ │ us-east-2 │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Hybrid instance registration │ Skipped │ Instance does not have hybrid registration │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to ssm endpoint │ Success │ ssm.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to ec2messages endpoint │ Success │ ec2messages.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to ssmmessages endpoint │ Success │ ssmmessages.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to s3 endpoint │ Success │ s3.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to kms endpoint │ Success │ kms.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to logs endpoint │ Success │ logs.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Connectivity to monitoring endpoint │ Success │ monitoring.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ AWS Credentials │ Success │ Credentials are for │
│ │ │ arn:aws:sts::123456789012:assumed-role/Fullaccess/i-0123456789abcdefa │
│ │ │ and will expire at 2021-08-17 18:47:49 +0000 UTC │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Agent service │ Success │ Agent service is running and is running as expected user │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ Proxy configuration │ Skipped │ No proxy configuration detected │
├───────────────────────────────────────┼─────────┼───────────────────────────────────────────────────────────────────────┤
│ SSM Agent version │ Success │ SSM Agent version is 3.0.1209.0, latest available agent version is │
│ │ │ 3.1.192.0 │
└───────────────────────────────────────┴─────────┴───────────────────────────────────────────────────────────────────────┘
```
------
#### [ Windows Server and PowerShell ]
```
PS C:\Program Files\Amazon\SSM> .\ssm-cli.exe get-diagnostics --output table
┌───────────────────────────────────────┬─────────┬─────────────────────────────────────────────────────────────────────┐
│ Check │ Status │ Note │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ EC2 IMDS │ Success │ IMDS is accessible and has instance id i-0123456789EXAMPLE in │
│ │ │ Region us-east-2 │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Hybrid instance registration │ Skipped │ Instance does not have hybrid registration │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to ssm endpoint │ Success │ ssm.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to ec2messages endpoint │ Success │ ec2messages.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to ssmmessages endpoint │ Success │ ssmmessages.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to s3 endpoint │ Success │ s3.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to kms endpoint │ Success │ kms.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to logs endpoint │ Success │ logs.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Connectivity to monitoring endpoint │ Success │ monitoring.us-east-2.amazonaws.com is reachable │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ AWS Credentials │ Success │ Credentials are for │
│ │ │ arn:aws:sts::123456789012:assumed-role/SSM-Role/i-123abc45EXAMPLE │
│ │ │ and will expire at 2021-09-02 13:24:42 +0000 UTC │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Agent service │ Success │ Agent service is running and is running as expected user │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Proxy configuration │ Skipped │ No proxy configuration detected │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ Windows sysprep image state │ Success │ Windows image state value is at desired value IMAGE_STATE_COMPLETE │
├───────────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────┤
│ SSM Agent version │ Success │ SSM Agent version is 3.2.815.0, latest agent version in us-east-2 │
│ │ │ is 3.2.985.0 │
└───────────────────────────────────────┴─────────┴─────────────────────────────────────────────────────────────────────┘
```
------
下表提供由 `ssm-cli` 执行的每项检查的其他详细信息。
**`ssm-cli` 诊断检查**
| Check | Details |
| --- | --- |
| Amazon EC2 实例元数据服务 | 指示托管节点是否能够访问元数据服务。测试失败表明，与 http://169.254.169.254 的连接出现问题，这可能由本地路由、代理或操作系统（OS）防火墙和代理配置引起。 |
| 混合实例注册 | 指示是否使用混合激活注册 SSM Agent。 |
| 连接到 ssm 端点 | 指示节点是否能够在 TCP 端口 443 上访问 Systems Manager 的服务端点。测试失败表明，与 https://ssm.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。连接问题可能由 VPC 配置引起，包括安全组、网络访问控制列表、路由表或操作系统防火墙和代理。 |
| 连接到 ec2messages 端点 | 指示节点是否能够在 TCP 端口 443 上访问 Systems Manager 的服务端点。测试失败表明，与 https://ec2messages.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。连接问题可能由 VPC 配置引起，包括安全组、网络访问控制列表、路由表或操作系统防火墙和代理。 |
| 连接到 ssmmessages 端点 | 指示节点是否能够在 TCP 端口 443 上访问 Systems Manager 的服务端点。测试失败表明，与 https://ssmmessages.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。连接问题可能由 VPC 配置引起，包括安全组、网络访问控制列表、路由表或操作系统防火墙和代理。 |
| 连接到 s3 端点 | 指示节点是否能够在 TCP 端口 443 上访问 Amazon Simple Storage Service 的服务端点。测试失败表明，与 https://s3.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。节点无需连接到此端点，即可在托管式节点列表中显示。 |
| 连接到 kms 端点 | 节点能够在 TCP 端口 443 上访问 AWS Key Management Service 的服务端点。测试失败表明，与 `https://kms.region.amazonaws.com` 的连接出现问题，具体取决于节点所在的 AWS 区域。节点无需连接到此端点，即可在托管式节点列表中显示。 |
| 连接到 logs 端点 | 节点能够在 TCP 端口 443 上访问 Amazon CloudWatch Logs 的服务端点。测试失败表明，与 https://logs.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。节点无需连接到此端点，即可在托管式节点列表中显示。 |
| 连接到 monitoring 端点 | 节点能够在 TCP 端口 443 上访问 Amazon CloudWatch 的服务端点。测试失败表明，与 https://monitoring.region.amazonaws.com 的连接出现问题，具体取决于节点所在的 AWS 区域。节点无需连接到此端点，即可在托管式节点列表中显示。 |
| AWS 凭证 | 指示 SSM Agent 是否有基于附加到计算机的 IAM 实例配置文件（适用于 EC2 实例）或 IAM 服务角色（适用于非 EC2 计算机）所需要的凭证。测试失败表明，没有 IAM 实例配置文件或 IAM 服务角色附加到计算机上，或者其不包含 Systems Manager 所需的权限。 |
| 代理服务 | 指示 SSM Agent 服务是否正在运行，以及该服务是否以 root （适用于 Linux 或 macOS）或 SYSTEM（适用于 Windows Server）运行。测试失败表明，SSM Agent 服务未运行或未作为 root 或 SYSTEM 运行。 |
| 代理配置 | 指示 SSM Agent 是否配置为使用代理。 |
| Sysprep 映像状态（仅适用于 Windows） | 指示节点上 Sysprep 的状态。如果 Sysprep 状态是 IMAGE\$1STATE\$1COMPLETE 之外的值，则 SSM Agent 不会在节点上启动。 |
| SSM Agent 版本 | 指示是否已安装最新可用版本的 SSM Agent。 |
# AWS Systems Manager 混合激活
要将非 EC2 计算机配置为在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中与 AWS Systems Manager 搭配使用，您需创建*混合激活*。作为托管式节点支持的非 EC2 计算机类型包括以下几种：
+ 您本地的服务器（本地服务器）
+ AWS IoT Greengrass 核心设备
+ AWS IoT 和非 AWS 边缘设备
+ 虚拟机，包括其他云环境中的虚拟机
当您运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-activation.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-activation.html) 命令启动混合激活过程时，您会在命令响应中收到激活码和 ID。然后，您需要在命令中包含激活码和 ID 以在计算机上安装 SSM Agent，如[在混合 Linux 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-linux.md) 中的步骤 3 和[在混合 Windows Server 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-windows.md) 中的步骤 4 所述。
此激活过程适用于*除* AWS IoT Greengrass 核心设备之外的所有非 EC2 计算机类型。有关为 Systems Manager 配置 AWS IoT Greengrass 核心设备的信息，请参阅 [使用 Systems Manager 管理边缘设备](systems-manager-setting-up-edge-devices.md)。
**注意**
目前不为非 EC2 macOS 计算机提供支持。
**关于 Systems Manager 实例套餐**
AWS Systems Manager 提供了标准实例层和高级实例层。两者都支持[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的托管式节点。通过标准实例套餐，每个 AWS 区域 内每个 AWS 账户 最多可以注册 1000 台计算机。如果您需要在一个账户和区域中注册超过 1000 台计算机，则使用高级实例套餐。在高级实例套餐中，您可以根据需要创建许多托管式节点。为 Systems Manager 配置的所有托管式节点均按使用量付费。有关启用高级实例套餐的更多信息，请参阅 [打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)。有关定价的更多信息，请参阅 [AWS Systems Manager 定价](https://aws.amazon.com/systems-manager/pricing/)。
请注意以下关于标准实例层和高级实例层的附加信息：
+ 通过高级实例，您还可以使用 AWS Systems Manager Session Manager 连接到[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 节点。Session Manager 提供了对您的实例的交互式 Shell 访问。有关更多信息，请参阅 [AWS Systems Manager Session Manager](session-manager.md)。
+ 标准实例配额也适用于使用 Systems Manager 本地激活的 Amazon EC2 实例（但这不是常见情况）。
+ 要修补 Microsoft 在虚拟机 (VM) 本地实例上发布的应用程序，请激活高级实例套餐。使用高级实例套餐需支付费用。修补 Microsoft 在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上发布的应用程序不收取额外费用。有关更多信息，请参阅 [Microsoft 在 Windows Server 上发布的补丁应用程序](patch-manager-patching-windows-applications.md)。
# AWS Systems Manager 清单
可以通过 AWS Systems Manager Inventory 了解您的 AWS 计算环境。您可以使用 Inventory 从托管式节点收集*元数据*。您可以将此元数据存储在中央 Amazon Simple Storage Service（Amazon S3）存储桶中，然后使用内置工具查询数据并快速确定哪些节点正在运行软件和软件策略所需的配置，以及需要更新哪些节点。您可以使用一个一键式过程在所有托管式节点上配置 Inventory。您还可以通过使用 Amazon Athena 配置及查看多个 AWS 区域 和 AWS 账户 的清单数据。要开始使用“清单”，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/inventory)。在导航窗格中，选择 **Inventory (清单)**。
如果 Systems Manager Inventory 收集的预配置元数据类型未满足您的需求，则您可以创建自定义清单。自定义清单是一个简单的 JSON 文件，包含您提供并添加到特定目录中的托管式节点的信息。当 Systems Manager Inventory 收集数据时，它将捕获此自定义清单数据。例如，如果您运行一个大型数据中心，您可以将每个服务器的机架位置指定为自定义清单。然后，在您查看其他清单数据时，则可以查看机架空间数据。
**重要**
Systems Manager Inventory *仅*从托管式节点收集元数据。Inventory 不会访问专有信息或数据。
下表描述了可以使用 Systems Manager Inventory 收集的数据的类型。该表还介绍了定位节点的不同产品以及您可以指定的收集间隔。
****
| 配置 | 详细信息 |
| --- | --- |
| 元数据类型 | 您可以配置 Inventory 以收集以下类型的数据： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/systems-manager-inventory.html) 要查看清单收集的所有元数据的列表，请参阅 [清单收集的元数据](inventory-schema.md)。 |
| 要定位的节点 | 您可以选择清点 AWS 账户 中的所有托管式节点、单独选择节点，或者使用标签将节点组设为目标。有关从所有托管节点收集清单数据的更多信息，请参阅 [清点 AWS 账户 中的所有托管式节点](inventory-collection.md#inventory-management-inventory-all)。 |
| 何时收集信息 | 您可以按分钟、小时和天数指定收集间隔。最短收集间隔为 30 分钟。 |
**注意**
根据所收集的数据量，系统可能需要几分钟将数据报告到您指定的输出中。收集信息后，数据会通过安全 HTTPS 通道发送到一个只能从您的AWS 账户访问的纯文本 AWS 存储。
您可以在 **Inventory**（清单）页面上查看 Systems Manager 控制台中的数据，该页面包括几个预定义的卡，可以帮助您查询数据。
![\[Systems Manager 控制台中的 Systems Manager Inventory 卡。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-cards.png)
**注意**
Inventory 卡可以自动筛选掉状态为 *Terminated (已终止)* 和 *Stopped (已停止)* 的 Amazon EC2 托管实例。对于本地托管式节点和 AWS IoT Greengrass 核心设备托管式节点，Inventory 卡会自动筛选掉状态为 *Terminated*（已终止）的节点。
如果您创建资源数据同步，以同步所有数据并将其存储在单个 Amazon S3 存储桶中，则可以在 **Inventory Detail View (Inventory 详细视图)** 页面上详细查看这些数据。有关更多信息，请参阅 [查询多个区域和账户的清单数据](systems-manager-inventory-query.md)。
**EventBridge 支持**
支持此 Systems Manager 工具作为 Amazon EventBridge 规则中的一个*事件*类型。有关信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md)和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
**Topics**
+ [了解有关 Systems Manager Inventory 的更多信息](inventory-about.md)
+ [设置 Systems Manager Inventory](systems-manager-inventory-setting-up.md)
+ [配置清单收集](inventory-collection.md)
+ [查询多个区域和账户的清单数据](systems-manager-inventory-query.md)
+ [使用筛选条件查询清单收集](inventory-query-filters.md)
+ [聚合清单数据](inventory-aggregate.md)
+ [使用自定义清单](inventory-custom.md)
+ [查看清单历史记录和变更跟踪](inventory-history.md)
+ [停止数据收集和删除清单数据](systems-manager-inventory-delete.md)
+ [将自定义清单元数据分配给某个托管式节点](inventory-custom-metadata.md)
+ [使用 AWS CLI 配置清单数据收集](inventory-collection-cli.md)
+ [演练：使用资源数据同步聚合清单数据](inventory-resource-data-sync.md)
+ [对 Systems Manager Inventory 的问题进行故障排除](syman-inventory-troubleshooting.md)
# 了解有关 Systems Manager Inventory 的更多信息
当您配置 AWS Systems Manager Inventory 时，您可以指定要收集的元数据的类型、应从中收集元数据的托管式节点以及元数据收集的计划。这些配置将与您的 AWS 账户 一起保存为 AWS Systems Manager State Manager 关联。关联就是配置。
**注意**
Inventory 仅收集元数据。它不会收集任何个人数据或专有数据。
**Topics**
+ [清单收集的元数据](inventory-schema.md)
+ [使用文件和 Windows 注册表清单](inventory-file-and-registry.md)
# 清单收集的元数据
以下示例显示了由每个 AWS Systems Manager Inventory 插件收集的元数据的完整列表。
```
{
"typeName": "AWS:InstanceInformation",
"version": "1.0",
"attributes":[
{ "name": "AgentType", "dataType" : "STRING"},
{ "name": "AgentVersion", "dataType" : "STRING"},
{ "name": "ComputerName", "dataType" : "STRING"},
{ "name": "InstanceId", "dataType" : "STRING"},
{ "name": "IpAddress", "dataType" : "STRING"},
{ "name": "PlatformName", "dataType" : "STRING"},
{ "name": "PlatformType", "dataType" : "STRING"},
{ "name": "PlatformVersion", "dataType" : "STRING"},
{ "name": "ResourceType", "dataType" : "STRING"},
{ "name": "AgentStatus", "dataType" : "STRING"},
{ "name": "InstanceStatus", "dataType" : "STRING"}
]
},
{
"typeName" : "AWS:Application",
"version": "1.1",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "ApplicationType", "dataType": "STRING"},
{ "name": "Publisher", "dataType": "STRING"},
{ "name": "Version", "dataType": "STRING"},
{ "name": "Release", "dataType": "STRING"},
{ "name": "Epoch", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "Architecture", "dataType": "STRING"},
{ "name": "URL", "dataType": "STRING"},
{ "name": "Summary", "dataType": "STRING"},
{ "name": "PackageId", "dataType": "STRING"}
]
},
{
"typeName" : "AWS:File",
"version": "1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "Size", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "FileVersion", "dataType": "STRING"},
{ "name": "InstalledDate", "dataType": "STRING"},
{ "name": "ModificationTime", "dataType": "STRING"},
{ "name": "LastAccessTime", "dataType": "STRING"},
{ "name": "ProductName", "dataType": "STRING"},
{ "name": "InstalledDir", "dataType": "STRING"},
{ "name": "ProductLanguage", "dataType": "STRING"},
{ "name": "CompanyName", "dataType": "STRING"},
{ "name": "ProductVersion", "dataType": "STRING"}
]
},
{
"typeName": "AWS:AWSComponent",
"version": "1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "ApplicationType", "dataType": "STRING"},
{ "name": "Publisher", "dataType": "STRING"},
{ "name": "Version", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "Architecture", "dataType": "STRING"},
{ "name": "URL", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsUpdate",
"version":"1.0",
"attributes":[
{ "name": "HotFixId", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "InstalledBy", "dataType": "STRING"}
]
},
{
"typeName": "AWS:Network",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "SubnetMask", "dataType": "STRING"},
{ "name": "Gateway", "dataType": "STRING"},
{ "name": "DHCPServer", "dataType": "STRING"},
{ "name": "DNSServer", "dataType": "STRING"},
{ "name": "MacAddress", "dataType": "STRING"},
{ "name": "IPV4", "dataType": "STRING"},
{ "name": "IPV6", "dataType": "STRING"}
]
},
{
"typeName": "AWS:PatchSummary",
"version":"1.0",
"attributes":[
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "BaselineId", "dataType": "STRING"},
{ "name": "SnapshotId", "dataType": "STRING"},
{ "name": "OwnerInformation", "dataType": "STRING"},
{ "name": "InstalledCount", "dataType": "NUMBER"},
{ "name": "InstalledPendingRebootCount", "dataType": "NUMBER"},
{ "name": "InstalledOtherCount", "dataType": "NUMBER"},
{ "name": "InstalledRejectedCount", "dataType": "NUMBER"},
{ "name": "NotApplicableCount", "dataType": "NUMBER"},
{ "name": "UnreportedNotApplicableCount", "dataType": "NUMBER"},
{ "name": "MissingCount", "dataType": "NUMBER"},
{ "name": "FailedCount", "dataType": "NUMBER"},
{ "name": "OperationType", "dataType": "STRING"},
{ "name": "OperationStartTime", "dataType": "STRING"},
{ "name": "OperationEndTime", "dataType": "STRING"},
{ "name": "InstallOverrideList", "dataType": "STRING"},
{ "name": "RebootOption", "dataType": "STRING"},
{ "name": "LastNoRebootInstallOperationTime", "dataType": "STRING"},
{ "name": "ExecutionId", "dataType": "STRING", "isOptional": "true"},
{ "name": "NonCompliantSeverity", "dataType": "STRING", "isOptional": "true"},
{ "name": "SecurityNonCompliantCount", "dataType": "NUMBER", "isOptional": "true"},
{ "name": "CriticalNonCompliantCount", "dataType": "NUMBER", "isOptional": "true"},
{ "name": "OtherNonCompliantCount", "dataType": "NUMBER", "isOptional": "true"}
]
},
{
"typeName": "AWS:PatchCompliance",
"version":"1.0",
"attributes":[
{ "name": "Title", "dataType": "STRING"},
{ "name": "KBId", "dataType": "STRING"},
{ "name": "Classification", "dataType": "STRING"},
{ "name": "Severity", "dataType": "STRING"},
{ "name": "State", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"}
]
},
{
"typeName": "AWS:ComplianceItem",
"version":"1.0",
"attributes":[
{ "name": "ComplianceType", "dataType": "STRING", "isContext": "true"},
{ "name": "ExecutionId", "dataType": "STRING", "isContext": "true"},
{ "name": "ExecutionType", "dataType": "STRING", "isContext": "true"},
{ "name": "ExecutionTime", "dataType": "STRING", "isContext": "true"},
{ "name": "Id", "dataType": "STRING"},
{ "name": "Title", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "Severity", "dataType": "STRING"},
{ "name": "DocumentName", "dataType": "STRING"},
{ "name": "DocumentVersion", "dataType": "STRING"},
{ "name": "Classification", "dataType": "STRING"},
{ "name": "PatchBaselineId", "dataType": "STRING"},
{ "name": "PatchSeverity", "dataType": "STRING"},
{ "name": "PatchState", "dataType": "STRING"},
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "InstalledTime", "dataType": "STRING"},
{ "name": "InstallOverrideList", "dataType": "STRING", "isOptional": "true"},
{ "name": "DetailedText", "dataType": "STRING", "isOptional": "true"},
{ "name": "DetailedLink", "dataType": "STRING", "isOptional": "true"},
{ "name": "CVEIds", "dataType": "STRING", "isOptional": "true"}
]
},
{
"typeName": "AWS:ComplianceSummary",
"version":"1.0",
"attributes":[
{ "name": "ComplianceType", "dataType": "STRING"},
{ "name": "PatchGroup", "dataType": "STRING"},
{ "name": "PatchBaselineId", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "OverallSeverity", "dataType": "STRING"},
{ "name": "ExecutionId", "dataType": "STRING"},
{ "name": "ExecutionType", "dataType": "STRING"},
{ "name": "ExecutionTime", "dataType": "STRING"},
{ "name": "CompliantCriticalCount", "dataType": "NUMBER"},
{ "name": "CompliantHighCount", "dataType": "NUMBER"},
{ "name": "CompliantMediumCount", "dataType": "NUMBER"},
{ "name": "CompliantLowCount", "dataType": "NUMBER"},
{ "name": "CompliantInformationalCount", "dataType": "NUMBER"},
{ "name": "CompliantUnspecifiedCount", "dataType": "NUMBER"},
{ "name": "NonCompliantCriticalCount", "dataType": "NUMBER"},
{ "name": "NonCompliantHighCount", "dataType": "NUMBER"},
{ "name": "NonCompliantMediumCount", "dataType": "NUMBER"},
{ "name": "NonCompliantLowCount", "dataType": "NUMBER"},
{ "name": "NonCompliantInformationalCount", "dataType": "NUMBER"},
{ "name": "NonCompliantUnspecifiedCount", "dataType": "NUMBER"}
]
},
{
"typeName": "AWS:InstanceDetailedInformation",
"version":"1.0",
"attributes":[
{ "name": "CPUModel", "dataType": "STRING"},
{ "name": "CPUCores", "dataType": "NUMBER"},
{ "name": "CPUs", "dataType": "NUMBER"},
{ "name": "CPUSpeedMHz", "dataType": "NUMBER"},
{ "name": "CPUSockets", "dataType": "NUMBER"},
{ "name": "CPUHyperThreadEnabled", "dataType": "STRING"},
{ "name": "OSServicePack", "dataType": "STRING"}
]
},
{
"typeName": "AWS:Service",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "DisplayName", "dataType": "STRING"},
{ "name": "ServiceType", "dataType": "STRING"},
{ "name": "Status", "dataType": "STRING"},
{ "name": "DependentServices", "dataType": "STRING"},
{ "name": "ServicesDependedOn", "dataType": "STRING"},
{ "name": "StartType", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsRegistry",
"version":"1.0",
"attributes":[
{ "name": "KeyPath", "dataType": "STRING"},
{ "name": "ValueName", "dataType": "STRING"},
{ "name": "ValueType", "dataType": "STRING"},
{ "name": "Value", "dataType": "STRING"}
]
},
{
"typeName": "AWS:WindowsRole",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "DisplayName", "dataType": "STRING"},
{ "name": "Path", "dataType": "STRING"},
{ "name": "FeatureType", "dataType": "STRING"},
{ "name": "DependsOn", "dataType": "STRING"},
{ "name": "Description", "dataType": "STRING"},
{ "name": "Installed", "dataType": "STRING"},
{ "name": "InstalledState", "dataType": "STRING"},
{ "name": "SubFeatures", "dataType": "STRING"},
{ "name": "ServerComponentDescriptor", "dataType": "STRING"},
{ "name": "Parent", "dataType": "STRING"}
]
},
{
"typeName": "AWS:Tag",
"version":"1.0",
"attributes":[
{ "name": "Key", "dataType": "STRING"},
{ "name": "Value", "dataType": "STRING"}
]
},
{
"typeName": "AWS:ResourceGroup",
"version":"1.0",
"attributes":[
{ "name": "Name", "dataType": "STRING"},
{ "name": "Arn", "dataType": "STRING"}
]
},
{
"typeName": "AWS:BillingInfo",
"version": "1.0",
"attributes": [
{ "name": "BillingProductId", "dataType": "STRING"}
]
}
```
**注意**
对于 `"typeName": "AWS:InstanceInformation"`，`InstanceStatus` 可以是以下情况之一：Active (活动)、ConnectionLost (连接已丢失)、Stopped (已停止)、Terminated (已终止)。
随着 2.5 版本的发布，RPM 包管理器将 Serial 属性替换成了 Epoch。与 Serial 一样，Epoch 属性是一个单调递增整数。当您使用 `AWS:Application` 类型进行清点时，Epoch 的值越大就意味着版本越新。如果 Epoch 值相同或为空，请使用 Version 或 Release 属性值来确定较新版本。
某些元数据在 Linux 实例中不可用。具体而言，对于“typeName”：“AWS:Network”，Linux 实例尚不支持以下元数据类型。但在 Windows 中受支持。
\$1 "name": "SubnetMask", "dataType": "STRING"\$1，
\$1 "name": "DHCPServer", "dataType": "STRING"\$1，
\$1 "name": "DNSServer", "dataType": "STRING"\$1，
\$1 "name": "Gateway", "dataType": "STRING"\$1，
# 使用文件和 Windows 注册表清单
借助 AWS Systems Manager 清单可以搜索和清点 Windows Server、Linux 及 macOS 操作系统上的文件。您还可以搜索并清点 Windows 注册表。
**文件**：您可以收集关于文件的元数据信息，包括文件名称、文件创建时间、文件上次修改和访问时间以及文件大小等等。要开始收集文件清单，您需要指定要执行清点的文件路径、用于定义要清点的文件类型的一个或多个模式，以及是否应以递归的方式遍历路径。Systems Manager 将清点与模式相匹配的指定路径中的文件的所有文件元数据。清单文件使用以下参数输入。
```
{
"Path": string,
"Pattern": array[string],
"Recursive": true,
"DirScanLimit" : number // Optional
}
```
+ **路径**：您要清点文件的目录路径。对于 Windows，您可以使用 `%PROGRAMFILES% ` 等环境变量，前提是该变量要映射到单个目录路径。例如，如果您使用映射到多个目录路径的 %PATH%，则清单会引发错误。
+ **模式**：确定文件的一组模式。
+ **递归**：指示清单是否应以递归方式遍历目录的布尔值。
+ **DirScanLimit**：指定要扫描多少目录的可选值。使用此参数可以将对托管式节点的性能影响降至最低。清单最多扫描 5000 个目录。
**注意**
清单在所有指定路径中收集最多 500 个文件的元数据。
下面是一些在执行文件清单时如何指定参数的示例。
+ 在 Linux 和 macOS 上，将收集 `/home/ec2-user` 目录（不包括所有子目录）中的 .sh 文件的元数据。
```
[{"Path":"/home/ec2-user","Pattern":["*.sh", "*.sh"],"Recursive":false}]
```
+ 在 Windows 上，会以递归方式收集程序文件夹 (包括子目录) 中的所有“.exe”文件的元数据。
```
[{"Path":"C:\Program Files","Pattern":["*.exe"],"Recursive":true}]
```
+ 在 Windows 上，会收集指定日志模式的元数据。
```
[{"Path":"C:\ProgramData\Amazon","Pattern":["*amazon*.log"],"Recursive":true}]
```
+ 在执行递归集合时会限制目录计数。
```
[{"Path":"C:\Users","Pattern":["*.ps1"],"Recursive":true, "DirScanLimit": 1000}]
```
**Windows 注册表**：您可以收集 Windows 注册表项和值。您可以选择一个键路径并以递归方式收集所有键和值。您还可以收集特定路径的特定注册表项及其值。清单会收集键路径、名称、类型和值。
```
{
"Path": string,
"Recursive": true,
"ValueNames": array[string] // optional
}
```
+ **路径**：注册表项的路径。
+ **递归**：指示清单是否应以递归方式遍历注册表路径的布尔值。
+ **ValueNames**：执行注册表项的清单的一组值名称。如果使用此参数，Systems Manager 仅将清点指定路径的指定值名称。
**注意**
清单针对所有指定路径收集最多 250 个注册表项值。
下面是一些在执行 Windows 注册表清单时如何指定参数的示例。
+ 以递归方式针对特定路径收集所有键和值。
```
[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon","Recursive": true}]
```
+ 针对特定路径收集所有键和值（已关闭递归搜索）。
```
[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Intel\PSIS\PSIS_DECODER", "Recursive": false}]
```
+ 使用 `ValueNames` 选项收集特定键。
```
{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\MachineImage","ValueNames":["AMIName"]}
```
# 设置 Systems Manager Inventory
在您使用 AWS Systems Manager Inventory 收集有关托管式节点上运行的应用程序、服务、AWS 组件等对象的元数据之前，我们建议您配置资源数据同步，以将清单数据的存储集中在单个 Amazon Simple Storage Service (Amazon S3) 存储桶中。我们还建议您配置清单事件的 Amazon EventBridge 监控。这些过程将使查看和管理清单数据和收集变得更加轻松。
**Topics**
+ [为 Inventory 创建资源数据同步](inventory-create-resource-data-sync.md)
+ [使用 EventBridge 监控 Inventory 事件](systems-manager-inventory-setting-up-eventbridge.md)
# 为 Inventory 创建资源数据同步
本主题介绍如何为 AWS Systems Manager Inventory 设置和配置资源数据同步。有关 Systems Manager Explorer 的资源数据同步的信息，请参阅 [设置 Systems Manager Explorer 以显示来自多个账户和区域的数据](Explorer-resource-data-sync.md)。
## 关于资源数据同步
您可以使用 Systems Manager 资源数据同步，将从所有托管式节点收集到的清单数据发送到单个 Amazon Simple Storage Service（Amazon S3）存储桶。在收集新的清单数据时，资源数据同步自动更新集中式数据。在所有清单数据存储在目标 Amazon S3 存储桶中后，可以使用 Amazon Athena 和 Amazon Quick 等服务查询和分析聚合数据。
例如，假设您将清单配置为收集有关操作系统（OS）和 150 个托管式节点机群上运行的应用程序的数据。其中某些节点位于本地数据中心内，而某些则在跨多个 AWS 区域 的 Amazon Elastic Compute Cloud（Amazon EC2）中运行。如果您*没有*配置资源数据同步，则需要手动收集为每个托管式节点收集的清单数据，或者必须创建脚本以收集该信息。然后您需要将数据传输到应用程序中，以便运行查询和分析数据。
通过使用资源数据同步，您可以执行一次性操作以同步所有托管式节点中的所有清单数据。在成功创建同步后，Systems Manager 会创建所有清单数据的基准，并将其保存在目标 Amazon S3 存储桶中。在收集新的清单数据时，Systems Manager 将自动更新 Amazon S3 存储桶中的数据。然后就可以快速且经济高效地将数据移植到 Amazon Athena 和 Amazon Quick。
图 1 显示了资源数据同步如何将来自[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的 Amazon EC2 和其他计算机类型的清单数据聚合到目标 Amazon S3 存储桶。该图还显示了如何为多个 AWS 账户 和 AWS 区域 执行资源数据同步。
**图 1：为多个 AWS 账户 和 AWS 区域 执行资源数据同步**
![\[Systems Manager 资源数据同步架构\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-resource-data-sync-updated.png)
如果删除一个托管式节点，则资源数据同步会保留已删除节点的清单文件。但是，对于正在运行的节点，在创建新文件并将它们写入 Amazon S3 存储桶时，资源数据同步会自动覆盖旧清单文件。如果要随着时间推移跟踪清单变化，您可以使用 AWS Config 服务跟踪 `SSM:ManagedInstanceInventory` 资源类型。有关更多信息，请参见 [AWS Config 入门](https://docs.aws.amazon.com/config/latest/developerguide/getting-started.html)。
可以按照本节中的过程，使用 Amazon S3 和 AWS Systems Manager 控制台为 Inventory 创建资源数据同步。您也可以使用 AWS CloudFormation 创建或删除资源数据同步。要使用 CloudFormation，请将 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-resourcedatasync.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-resourcedatasync.html) 资源添加到您的 CloudFormation 模板。有关信息，请参阅以下文档资源：
+ [适用于 AWS Systems Manager 中的资源数据同步的 AWS CloudFormation 资源](https://aws.amazon.com/blogs/mt/aws-cloudformation-resource-for-resource-data-sync-in-aws-systems-manager/)（博客）
+ *《AWS CloudFormation 用户指南》*中的[使用 AWS CloudFormation 模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html)
**注意**
可以使用 AWS Key Management Service (AWS KMS) 加密 Amazon S3 存储桶中的清单数据。有关如何使用 AWS Command Line Interface（AWS CLI）创建加密同步以及如何使用 Amazon Athena 和 Amazon Quick 中的集中式数据的示例，请参阅[演练：使用资源数据同步聚合清单数据](inventory-resource-data-sync.md)。
## 开始前的准备工作
在创建资源数据同步之前，请使用以下过程创建中央 Amazon S3 存储桶，以存储聚合清单数据。该过程介绍如何分配存储桶策略，以便 Systems Manager 能将来自多个账户的清单数据写入存储桶。如果您已有一个要用于聚合清单数据以进行资源数据同步的 Amazon S3 存储桶，则必须在以下过程中将该存储桶配置为使用该策略。
**注意**
如果指定的 Amazon S3 存储桶被配置为使用对象锁定，则 Systems Manager Inventory 无法将数据添加到该存储桶。请验证并确保您为资源数据同步创建或选择的 Amazon S3 存储桶未被配置为使用 Amazon S3 对象锁定。有关更多信息，请参阅*《Amazon Simple Storage Service 用户指南》*中的 [Amazon S3 对象锁定的工作原理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html)。
**为资源数据同步创建和配置 Amazon S3 存储桶**
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 创建用来存储聚合清单数据的存储桶。有关更多信息，请参阅[《Amazon Simple Storage Service 用户指南》](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)中的*创建存储桶*。请记下存储桶名称和创建此存储桶的 AWS 区域。
1. 选择**权限**选项卡，然后选择**存储桶策略**。
1. 将下面的存储桶策略复制并粘贴到策略编辑器中。将 *amzn-s3-demo-bucket* 替换为您创建的 S3 存储桶的名称。将 *account\$1ID\$1number* 替换为有效的 AWS 账户 ID 号码。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SSMBucketPermissionsCheck",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
},
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*/accountid=111122223333/*",
"arn:aws:s3:::amzn-s3-demo-bucket/*/accountid=444455556666/*",
"arn:aws:s3:::amzn-s3-demo-bucket/*/accountid=123456789012/*",
"arn:aws:s3:::amzn-s3-demo-bucket/*/accountid=777788889999/*"
],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:ssm:*:111122223333:resource-data-sync/*"
}
}
}
]
}
```
------
1. 保存更改。
## 为 Inventory 创建资源数据同步
按照以下过程，使用 Systems Manager 控制台为 Systems Manager Inventory 创建资源数据同步。有关如何使用 AWS CLI 创建资源数据同步的信息，请参阅 [使用 AWS CLI 配置清单数据收集](inventory-collection-cli.md)。
**创建资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 在**账户管理**菜单中，选择**资源数据同步**。
1. 选择**创建资源数据同步**。
1. 在**同步名称**字段中，输入同步配置的名称。
1. 在**存储桶名称**字段中，输入您使用**为资源数据同步创建和配置 Amazon S3 存储桶**过程创建的 Amazon S3 存储桶的名称。
1. （可选）在**存储桶前缀**字段中，输入 Amazon S3 存储桶前缀（子目录）的名称。
1. 在**存储桶区域**字段中，如果您创建的 Amazon S3 存储桶位于当前的 AWS 区域 中，请选择**此区域**。如果存储桶位于其他 AWS 区域 中，则请选择**其他区域**，然后输入该区域的名称。
**注意**
如果同步和目标 Amazon S3 存储桶位于不同区域中，您可能需要支付数据传输费用。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。
1. （可选）在 **KMS 密钥 ARN** 字段中，键入或粘贴 KMS 密钥 ARN，以加密 Amazon S3 中的清单数据。
1. 选择**创建**。
要同步来自多个 AWS 区域的清单数据，您必须在*每个*区域中创建一个资源数据同步。在要收集清单数据并将其发送到中央 Amazon S3 存储桶的每个 AWS 区域 中重复此过程。当您在每个区域中创建同步时，请在**存储桶名称**字段中指定中央 Amazon S3 存储桶。然后，使用**存储桶区域**选项选择要在其中创建中央 Amazon S3 存储桶的区域，如下面的屏幕截图中所示。下次关联运行以收集清单数据时，Systems Manager 会将数据存储在中央 Amazon S3 存储桶中。
![\[来自多个 AWS 区域的 Systems Manager 资源数据同步\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-rds-multiple-regions.png)
## 为 AWS Organizations 中定义的多个账户创建清单资源数据同步
您可以将来自 AWS Organizations 中定义的 AWS 账户的清单数据同步到中央 Amazon S3 存储桶。完成以下过程后，清单数据将同步到中央存储桶中的*各个* Amazon S3 密钥前缀。每个键前缀均代表一个不同的 AWS 账户 ID。
**开始前的准备工作**
在开始之前，请验证并确保您已在 AWS Organizations 中设置和配置了多个 AWS 账户。有关更多信息，请参阅《AWS Organizations 用户指南》中的** [https://docs.aws.amazon.com/organizations/latest/userguide/rgs_getting-started.html](https://docs.aws.amazon.com/organizations/latest/userguide/rgs_getting-started.html)。
另外，请注意，您必须为 AWS Organizations 中定义的每个 AWS 区域 和 AWS 账户 创建基于组织的资源数据同步。
### 创建中央 Amazon S3 存储桶
可以使用以下过程创建中央 Amazon S3 存储桶，以存储聚合清单数据。该过程介绍如何分配存储桶策略，以便 Systems Manager 能将来自您的 AWS Organizations 账户 ID 的清单数据写入存储桶。如果您已有一个要用于聚合清单数据以进行资源数据同步的 Amazon S3 存储桶，则必须在以下过程中将该存储桶配置为使用该策略。
**为 AWS Organizations 中定义的多个账户的资源数据同步创建和配置 Amazon S3 存储桶**
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 创建用来存储聚合清单数据的存储桶。有关更多信息，请参阅[《Amazon Simple Storage Service 用户指南》](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)中的*创建存储桶*。请记下存储桶名称和创建此存储桶的 AWS 区域。
1. 选择**权限**选项卡，然后选择**存储桶策略**。
1. 将下面的存储桶策略复制并粘贴到策略编辑器中。将 *amzn-s3-demo-bucket* 和 *organization-id* 分别替换为您创建的 Amazon S3 存储桶的名称和有效的 AWS Organizations 账户 ID。
或者，将 *bucket-prefix* 替换为 Amazon S3 前缀（子目录）的名称。如果您未创建前缀，则从以下策略的 ARN 中删除 *bucket-prefix/*。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SSMBucketPermissionsCheck",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
},
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/bucket-prefix/*/accountid=*/*"
],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceOrgID": "organization-id"
}
}
},
{
"Sid": " SSMBucketDeliveryTagging",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObjectTagging",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/bucket-prefix/*/accountid=*/*"
]
}
]
}
```
------
### 为 AWS Organizations 中定义的账户创建清单资源数据同步
以下过程介绍如何使用 AWS CLI 为 AWS Organizations 中定义的账户创建资源数据同步。您必须使用 AWS CLI 执行此任务。您还必须为 AWS Organizations 中定义的每个 AWS 区域 和 AWS 账户 执行此过程。
**为 AWS Organizations 中定义的账户创建资源数据同步 (AWS CLI)**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令，验证并确保您没有任何其他*基于 AWS Organizations* 的资源数据同步。可以有多个标准同步，包括多个标准同步和一个基于组织的同步。但是只能有一个基于组织的资源数据同步。
```
aws ssm list-resource-data-sync
```
如果该命令返回了另一个基于组织的资源数据同步，则您必须将其删除，或选择不创建新资源数据同步。
1. 运行以下命令，为 AWS Organizations 中定义的账户创建资源数据同步。对于 amzn-s3-demo-bucket，请指定您在本主题的前面创建的 Amazon S3 存储桶的名称。如果您为存储桶创建了前缀（子目录），则为 *prefix-name* 指定此信息。
```
aws ssm create-resource-data-sync --sync-name name --s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=prefix-name,SyncFormat=JsonSerDe,Region=AWS 区域, for example us-east-2,DestinationDataSharing={DestinationDataSharingType=Organization}"
```
1. 为您希望在其中将数据同步到中央 Amazon S3 存储桶的每个 AWS 区域 和 AWS 账户 重复步骤 2 和步骤 3。
### 管理资源数据同步
每个 AWS 账户 在每个 AWS 区域 可以有 5 个资源数据同步。您可以使用 AWS Systems Manager Fleet Manager 控制台来管理您的资源数据同步。
**查看资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 在**账户管理**下拉菜单中，选择**资源数据同步**。
1. 从表中选择资源数据同步，然后选择**查看详细信息**以查看有关资源数据同步的信息。
**删除资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 在**账户管理**下拉菜单中，选择**资源数据同步**。
1. 从表中选择资源数据同步，然后选择**删除**。
# 使用 EventBridge 监控 Inventory 事件
您可以在 Amazon EventBridge 中配置规则来创建事件，以响应 AWS Systems Manager Inventory 资源状态更改。EventBridge 支持针对以下 Inventory 状态更改的事件。将尽最大努力发送所有事件。
**Custom inventory type deleted for a specific instance**（针对特定实例删除的自定义清单类型）：如果配置了用于监控此事件的规则，EventBridge 将在删除特定托管式节点上的自定义清单类型时创建一个事件。EventBridge 将针对每个自定义清单类型的每个节点发送一个事件。以下是一个示例事件模式。
```
{
"timestampMillis": 1610042981103,
"source": "SSM",
"account": "123456789012",
"type": "INVENTORY_RESOURCE_STATE_CHANGE",
"startTime": "Jan 7, 2021 6:09:41 PM",
"resources": [
{
"arn": "arn:aws:ssm:us-east-1:123456789012:managed-instance/i-12345678"
}
],
"body": {
"action-status": "succeeded",
"action": "delete",
"resource-type": "managed-instance",
"resource-id": "i-12345678",
"action-reason": "",
"type-name": "Custom:MyCustomInventoryType"
}
}
```
**Custom inventory type deleted event for all instances**（所有实例的自定义清单类型删除事件）：如果配置了用于监控此事件的规则，EventBridge 将在删除适用于所有托管式节点的自定义清单类型时创建一个事件。以下是一个示例事件模式。
```
{
"timestampMillis": 1610042904712,
"source": "SSM",
"account": "123456789012",
"type": "INVENTORY_RESOURCE_STATE_CHANGE",
"startTime": "Jan 7, 2021 6:08:24 PM",
"resources": [
],
"body": {
"action-status": "succeeded",
"action": "delete-summary",
"resource-type": "managed-instance",
"resource-id": "",
"action-reason": "The delete for type name Custom:SomeCustomInventoryType was completed. The deletion summary is: {\"totalCount\":1,\"remainingCount\":0,\"summaryItems\":[{\"version\":\"1.1\",\"count\":1,\"remainingCount\":0}]}",
"type-name": "Custom:MyCustomInventoryType"
}
}
```
**[PutInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutInventory.html) call with old schema version event (使用旧架构版本事件进行 PutInventory 调用)**：如果配置了用于监控此事件的规则，EventBridge 将在使用低于当前架构的架构版本进行 PutInventory 调用时创建一个事件。此事件适用于所有清单类型。以下是一个示例事件模式。
```
{
"timestampMillis": 1610042629548,
"source": "SSM",
"account": "123456789012",
"type": "INVENTORY_RESOURCE_STATE_CHANGE",
"startTime": "Jan 7, 2021 6:03:49 PM",
"resources": [
{
"arn": "arn:aws:ssm:us-east-1:123456789012:managed-instance/i-12345678"
}
],
"body": {
"action-status": "failed",
"action": "put",
"resource-type": "managed-instance",
"resource-id": "i-01f017c1b2efbe2bc",
"action-reason": "The inventory item with type name Custom:MyCustomInventoryType was sent with a disabled schema verison 1.0. You must send a version greater than 1.0",
"type-name": "Custom:MyCustomInventoryType"
}
}
```
有关如何配置 EventBridge 以监控这些事件的信息，请参阅 [为 Systems Manager 事件配置 EventBridge](monitoring-systems-manager-events.md)。
# 配置清单收集
本节介绍了如何使用 Systems Manager 控制台在一个或多个托管式节点上配置 AWS Systems Manager Inventory 收集。有关如何使用 AWS Command Line Interface (AWS CLI) 配置清单收集的示例，请参阅 [使用 AWS CLI 配置清单数据收集](inventory-collection-cli.md)。
在配置清单收集时，应该首先创建 AWS Systems Manager State Manager 关联。Systems Manager 将在关联运行时收集清单数据。如果您不首先创建关联，并尝试使用 AWS Systems Manager Run Command（举例来说）调用 `aws:softwareInventory` 插件，则系统将返回以下错误：`The aws:softwareInventory plugin can only be invoked via ssm-associate.`
**注意**
如果您为一个托管式节点创建多个清单关联，请注意以下行为：
可为每个节点分配一个以*所有*节点为目标的清单关联 (--targets "Key=InstanceIds,Values=\$1")。
还可以为每个节点分配一个特定关联，该关联使用标签键/值对或 AWS 资源组。
如果为某个节点分配了多个清单关联，则对于尚未运行的关联，状态将显示为 *Skipped*（已跳过）。最近运行的关联将显示清单关联的实际状态。
如果为某个节点分配了多个清单关联，并且每个关联都使用标签键/值对，则这些清单关联将因标签冲突而无法在该节点上运行。关联仍会在没有标签键/值冲突的节点上运行。
**开始前的准备工作**
配置清单收集前，请完成以下任务。
+ 更新要清点的节点上的 AWS Systems Manager SSM Agent。通过运行最新版本的 SSM Agent，可确保您能够收集所有支持的清单类型的元数据。有关如何使用 State Manager 更新 SSM Agent 的信息，请参阅 [演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)。
+ 验证您是否已在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中完成 Amazon Elastic Compute Cloud（Amazon EC2）实例以及非 EC2 计算机的设置要求。有关信息，请参阅[为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
+ 对于 Microsoft Windows Server 节点，确认已使用 Windows PowerShell 3.0（或更高版本）配置了您的托管节点。SSM Agent 使用 PowerShell 中的 `ConvertTo-Json` cmdlet 将 Windows 更新清单数据转换为所需格式。
+ （可选）创建资源数据同步，以将清单数据集中存储在 Amazon S3 存储桶中。然后，在收集新的清单数据时，资源数据同步将自动更新集中式数据。有关更多信息，请参阅 [演练：使用资源数据同步聚合清单数据](inventory-resource-data-sync.md)。
+ (可选) 创建用于收集自定义清单的 JSON 文件。有关更多信息，请参阅 [使用自定义清单](inventory-custom.md)。
## 清点 AWS 账户 中的所有托管式节点
您可以通过创建全局清单关联，清点 AWS 账户 中的所有托管式节点。全局清单关联执行以下操作：
+ 自动将全局清单配置（关联）应用到 AWS 账户 中的所有现有托管式节点。应用和运行全局清单关联时，将跳过已具有清单关联的托管式节点。跳过某个节点时，详细状态消息将说明 `Overridden By Explicit Inventory Association`。全局关联跳过了这些节点，但在它们运行所分配的清单关联时，仍会报告清单。
+ 将在您的 AWS 账户 中创建的新节点自动添加到全局清单关联。
**注意**
如果为全局清单关联配置了一个托管式节点，并且您将特定关联分配给该节点，则 Systems Manager Inventory 会降低全局关联的优先级，并应用该特定关联。
全局清单关联在 SSM Agent版本 2.0.790.0 或更高版本中可用。有关如何在节点上更新 SSM Agent 的信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
### 一键式配置清单收集（控制台）
可以使用以下过程为您的 AWS 账户 和单个 AWS 区域 中的所有托管式节点配置 Systems Manager Inventory。
**配置 Systems Manager Inventory 的当前区域中的所有托管式节点**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Inventory (清单)**。
1. 在 **Managed instances with inventory enabled (启用了清单的托管实例)** 卡上，选择 **Click here to enable inventory on all instances (单击此处在所有实例上启用清单)**。
![\[在所有托管式节点上 Systems Manager Inventory。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-one-click-1.png)
如果成功，控制台会显示以下消息。
![\[在所有托管式节点上 Systems Manager Inventory。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-one-click-2.png)
根据您账户中的托管式节点的数量，可能需要几分钟才能应用全局库存关联。等待几分钟，然后刷新页面。验证图形更改是否反映在所有托管式节点上均配置了清单。
### 使用控制台配置收集
本节包含有关如何使用 Systems Manager 控制台将 Systems Manager Inventory 配置为收集托管式节点中的元数据的信息。您可以快速收集特定 AWS 账户 内所有节点（以及未来可能在该账户中创建的任何节点）中的元数据，也可以选择通过使用标签或节点 ID 收集清单数据。
**注意**
在完成此过程之前，请检查是否已存在全局清单关联。如果全局清单关联已经存在，则无论何时启动新实例，该关联都将应用于该实例，并对新实例进行清点。
**配置清单收集**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Inventory (清单)**。
1. 选择**设置清单**。
1. 在 **Targets**（目标）部分中，通过选择以下选项之一来标识您要运行此操作的节点。
+ **Selecting all managed instances in this account**（选择此账户中的所有托管式实例）– 使用此选项可选择没有现有清单关联的所有托管式节点。如果您选择此选项，则在清单收集期间将跳过已有清单关联的节点，并会在清单结果中显示 **Skipped**（已跳过）状态。有关更多信息，请参阅 [清点 AWS 账户 中的所有托管式节点](#inventory-management-inventory-all)。
+ **Specifying a tag**（指定标签）– 使用此选项可以指定单个标签，用于标识要从中收集清单的账户中的节点。如果使用标签，则将来使用相同标签创建的所有节点也将报告清单。如果现有清单关联到所有节点，则使用标签选择特定节点作为其他清单的目标，会覆盖 **All managed instances**（所有托管式实例）目标组中的成员资格。未来从 **All managed instances**（所有托管式实例）进行清单收集时，将跳过具有指定标签的托管式节点。
+ **Manually selecting instances**（手动选择实例）– 使用此选项可以选择账户中的特定托管式节点。使用此选项明确选择特定节点，将覆盖 **All managed instances**（所有托管式实例）目标上的清单关联。未来从 **All managed instances**（所有托管式实例）进行清单收集时，将跳过该节点。
**注意**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 在 **Schedule**（计划）部分中，选择您希望系统从节点收集清单元数据的频率。
1. 在 **Parameters (参数)** 部分中，使用列表打开或关闭不同类型的清单收集。有关收集文件和 Windows 注册表清单的更多信息，请参阅[使用文件和 Windows 注册表清单](inventory-file-and-registry.md)。
1. 如果希望将关联执行状态存储在 Amazon S3 存储桶中，请在 **Advanced (高级)** 部分中选择 **Sync inventory execution logs to an Amazon S3 bucket (将清单执行日志同步到 Amazon S3 存储桶)**。
1. 选择**设置清单**。Systems Manager 会创建一个 State Manager 关联，并立即在节点上运行 Inventory。
1. 在导航窗格中，请选择 **State Manager**。验证并确保已创建了使用 `AWS-GatherSoftwareInventory` 文档的新关联。关联计划使用 Rate 表达式。此外，确认 **Status** 字段显示 **Success**。如果您选择了 **Sync inventory execution logs to an Amazon S3 bucket (将清单执行日志同步到 Amazon S3 存储桶)** 选项，则您可在几分钟后在 Amazon S3 中查看日志数据。要查看特定节点的清单数据，请在导航窗格中选择 **Managed Instances**（托管式实例）。
1. 选择一个节点，然后选择 **View details**（查看详细信息）。
1. 在节点详细信息页面上，选择 **Inventory**（清单）。使用 **Inventory type** 列表筛选清单。
# 查询多个区域和账户的清单数据
AWS Systems Manager Inventory 可与 Amazon Athena 集成，以帮助您查询来自多个 AWS 区域和 AWS 账户的清单数据。Athena 集成使用资源数据同步，以便您可以在 AWS Systems Manager 控制台中的 **Detailed View**（详细视图）页面上查看来自所有托管式节点的清单数据。
**重要**
此功能将使用 AWS Glue 网络爬取您的 Amazon Simple Storage Service (Amazon S3) 存储桶中的数据，以及使用 Amazon Athena 查询这些数据。根据抓取和查询的数据量，您可能需要为使用这些服务付费。使用 AWS Glue 时，您需要按小时费率（按秒计）为爬网程序（发现数据）和 ETL 作业（处理和加载数据）付费。使用 Athena，您需要按每次查询所扫描的数据量付费。建议您在使用 Amazon Athena 与 Systems Manager Inventory 的集成之前查看这些服务的定价准则。有关更多信息，请参阅 [Amazon Athena 定价](https://aws.amazon.com/athena/pricing/)和 [AWS Glue 定价](https://aws.amazon.com/glue/pricing/)。
您可以在所有提供 Amazon Athena 的 AWS 区域 中的 **Detailed View (详细视图)** 页面上查看清单数据。有关受支持的区域列表，请参阅《Amazon Web Services 一般参考》**中的 [Amazon Athena Service Endpoints](https://docs.aws.amazon.com/general/latest/gr/athena.html#athena_region)。
**开始前的准备工作**
Athena 集成使用资源数据同步。您必须设置并配置资源数据同步才能使用该功能。有关更多信息，请参阅 [演练：使用资源数据同步聚合清单数据](inventory-resource-data-sync.md)。
另请注意，**Detailed View (详细视图)** 页面将为资源数据同步使用的中央 Amazon S3 存储桶的*拥有者*显示清单数据。如果您不是中央 Amazon S3 存储桶的拥有者，则无法在 **Detailed View (详细视图)** 页面上查看清单数据。
## 配置访问权限
您必须将 IAM 实体配置为拥有查看数据的权限，然后才能在 Systems Manager 控制台中的**详细视图**页面上查询及查看来自多个账户和区域的数据。
如果清单数据存储在使用 AWS Key Management Service（AWS KMS）加密的 Amazon S3 存储桶中，您还必须配置 IAM 实体和 `Amazon-GlueServiceRoleForSSM` 服务角色，以便进行 AWS KMS 加密。
**Topics**
+ [配置您的 IAM 实体以访问“详细视图”页面](#systems-manager-inventory-query-iam-user)
+ [（可选）配置查看 AWS KMS 加密数据的权限](#systems-manager-inventory-query-kms)
### 配置您的 IAM 实体以访问“详细视图”页面
下文介绍了在**详细视图**页面上查看清单数据所需的最低权限。
`AWSQuicksightAthenaAccess` 托管策略
以下 `PassRole` 和其他所需权限块
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowGlue",
"Effect": "Allow",
"Action": [
"glue:GetCrawler",
"glue:GetCrawlers",
"glue:GetTables",
"glue:StartCrawler",
"glue:CreateCrawler"
],
"Resource": "*"
},
{
"Sid": "iamPassRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"arn:aws:iam::111122223333:role/SSMInventoryGlueRole",
"arn:aws:iam::111122223333:role/SSMInventoryServiceRole"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "glue.amazonaws.com"
}
}
},
{
"Sid": "iamRoleCreation",
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:AttachRolePolicy"
],
"Resource": "arn:aws:iam::111122223333:role/*"
},
{
"Sid": "iamPolicyCreation",
"Effect": "Allow",
"Action": "iam:CreatePolicy",
"Resource": "arn:aws:iam::111122223333:policy/*"
}
]
}
```
------
（可选）如果用于存储清单数据的 Amazon S3 存储桶使用 AWS KMS 进行加密，则您还必须将以下数据块添加到策略中。
```
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:Region:account_ID:key/key_ARN"
]
}
```
要提供访问权限，请为您的用户、组或角色添加权限：
+ AWS IAM Identity Center 中的用户和群组：
创建权限集合。按照《AWS IAM Identity Center 用户指南》**中[创建权限集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)的说明进行操作。
+ 通过身份提供者在 IAM 中托管的用户：
创建适用于身份联合验证的角色。按照《IAM 用户指南》**中[针对第三方身份提供者创建角色（联合身份验证）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)的说明进行操作。
+ IAM 用户：
+ 创建您的用户可以担任的角色。按照《IAM 用户指南》**中[为 IAM 用户创建角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)的说明进行操作。
+ （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》**中[向用户添加权限（控制台）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)中的说明进行操作。
### （可选）配置查看 AWS KMS 加密数据的权限
如果用于存储清单数据的 Amazon S3 存储桶使用 AWS Key Management Service（AWS KMS）进行加密，则您必须将 IAM 实体和 **Amazon-GlueServiceRoleForSSM** 角色配置为拥有对 AWS KMS 密钥的 `kms:Decrypt` 权限。
**开始前的准备工作**
要提供对 AWS KMS 密钥的 `kms:Decrypt` 权限，请将以下策略块添加到您的 IAM 实体：
```
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:Region:account_ID:key/key_ARN"
]
}
```
如果您尚未这样做，请完成该过程，并添加对 AWS KMS 密钥的 `kms:Decrypt` 权限。
使用以下过程将 **Amazon-GlueServiceRoleForSSM** 角色配置为拥有对 AWS KMS 密钥的 `kms:Decrypt` 权限。
**将 **Amazon-GlueServiceRoleForSSM** 角色配置为拥有 `kms:Decrypt` 权限**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 在导航窗格中，选择 **Roles (角色)**，然后使用搜索字段查找 **Amazon-GlueServiceRoleForSSM** 角色。此时将打开**摘要**页面。
1. 使用搜索字段查找 **Amazon-GlueServiceRoleForSSM** 角色。选择角色名称 。此时将打开**摘要**页面。
1. 选择角色名称 。此时将打开**摘要**页面。
1. 选择**添加内联策略**。此时将打开**创建策略**页面。
1. 选择 **JSON** 选项卡。
1. 删除编辑器中现有的 JSON 文本，然后将以下策略复制并粘贴到 JSON 编辑器中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/key_ARN"
]
}
]
}
```
------
1. 选择**查看策略**
1. 在**查看策略**页面上的**名称**字段中输入名称。
1. 选择**创建策略**。
## 在清单详细视图页面上查询数据
使用以下过程可在 Systems Manager Inventory **Detailed View (详细视图)** 页面上查看来自多个 AWS 区域和 AWS 账户的清单数据。
**重要**
仅在提供 Amazon Athena 的 AWS 区域 中提供了 Inventory **Detailed View (详细视图)** 页面。如果在 Systems Manager Inventory 页面上未显示以下选项卡，则意味着 Athena 在该区域中不可用，并且您无法使用 **Detailed View (详细视图)** 查询数据。
![\[显示 Inventory“控制面板”|“详细视图”|“设置”选项卡\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-detailed-view-for-error.png)
**在 AWS Systems Manager 控制台中查看多个区域和账户的清单数据**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Inventory (清单)**。
1. 选择 **Detailed View (详细视图)** 选项卡。
![\[访问 AWS Systems Manager Inventory（清单）详细视图页面\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-detailed-view.png)
1. 选择要查询数据的资源数据同步。
![\[在 AWS Systems Manager 控制台中显示清单数据\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-display-data.png)
1. 在 **Inventory Type (清单类型)** 列表中，请选择要查询的清单数据类型，然后按 Enter。
![\[在 AWS Systems Manager 控制台中选择清单类型\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-type.png)
1. 要筛选数据，请选择筛选条件栏，然后选择筛选选项。
![\[在 AWS Systems Manager 控制台中筛选清单数据\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-filter.png)
您可以使用 **Export to CSV (导出到 CSV)** 按钮在电子表格应用程序（如 Microsoft Excel）中查看当前查询集。您也可以使用 **Query History (查询历史记录)** 和 **Run Advanced Queries (运行高级查询)** 按钮查看历史记录详细信息，并与 Amazon Athena 中的数据进行交互。
### 编辑 AWS Glue 爬网程序计划
预设情况下，AWS Glue 每天会爬取中央 Amazon S3 存储桶中的清单数据两次。如果您经常更改要在节点上收集的数据的类型，则可能需要更频繁地抓取数据，如以下过程中所述。
**重要**
AWS Glue 按小时费率（按秒计费）向您的 AWS 账户收取执行爬网程序（发现数据）和 ETL 任务（处理和加载数据）的费用。在更改爬网程序计划前，请先查看 [AWS Glue 定价](https://aws.amazon.com/glue/pricing/)页面。
**更改清单数据爬网程序计划**
1. 通过 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 打开 AWS Glue 控制台。
1. 在导航窗格中，选择 **爬网程序**。
1. 在爬网程序列表中，选择 Systems Manager Inventory 数据爬网程序旁边的选项。爬网程序名称使用以下格式：
`AWSSystemsManager-s3-bucket-name-Region-account_ID`
1. 选择 **Action (操作)**，然后选择 **Edit crawler (编辑爬网程序)**。
1. 在导航窗格中，选择 **Schedule (计划)**。
1. 在 **Cron expression (Cron 表达式)** 字段中，使用 cron 格式指定一个新计划。有关更多信息，请参阅 *AWS Glue Developer Guide* 中的[基于时间的任务和爬网程序日程](https://docs.aws.amazon.com/glue/latest/dg/monitor-data-warehouse-schedule.html)。
**重要**
您可以暂停爬网程序以停止 AWS Glue 产生的费用。如果暂停爬网程序或降低爬取数据的频率，则 Inventory **Detailed View (详细视图)** 可能会显示非当前数据。
# 使用筛选条件查询清单收集
收集清单数据后，可以使用 AWS Systems Manager 中的筛选功能查询满足特定筛选条件的托管式节点列表。
**根据清单筛选条件查询节点**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Inventory (清单)**。
1. 在 **Filter by resource groups, tags or inventory types** 部分中，选择筛选框。此时会显示预定义筛选器列表。
1. 选择要筛选的属性。例如，选择 `AWS:Application`。如果出现提示，选择要筛选的二级属性。例如，选择 `AWS:Application.Name`。
1. 从列表中选择一个分隔符。例如，选择 **Begin with**。此时筛选器中会显示一个文本框。
1. 在该文本框中输入一个值。例如，输入 *Amazon*（SSM Agent 命名为 *Amazon SSM Agent*）。
1. 按 Enter。系统返回一个托管式节点列表，其中包含以单词 *Amazon* 开头的应用程序名称。
**注意**
您可以组合多个筛选条件来细化搜索。
# 聚合清单数据
在为 AWS Systems Manager Inventory 配置托管式节点后，您可以查看清单数据的聚合计数。例如，假设您配置了数十或数百个托管式节点来收集 `AWS:Application` 清单类型。通过使用此部分中的信息，您即可查看配置为收集此数据的节点数的准确计数。
您还可以通过针对某数据类型进行聚合以查看特定清单详细信息。例如，`AWS:InstanceInformation` 清单类型收集 `Platform` 数据类型的操作系统平台信息。通过聚合 `Platform` 数据类型的数据，您可以快速查看运行 Windows Server、Linux 以及 macOS 的节点的数量。
本节中的过程介绍了如何使用 AWS Command Line Interface (AWS CLI) 查看清单数据的聚合计数。您还可以在 AWS Systems Manager 控制台的 **Inventory (清单)** 页面上预配置聚合计数。这些预配置的控制面板称为 *Inventory Insights*，而且它们提供清单配置问题的一键修正。
请注意有关清单数据的聚合计数的以下重要详细信息：
+ 如果您终止配置为收集清单数据的托管式节点，Systems Manager 会将清单数据保留 30 天，然后将其删除。对于正在运行的节点，系统将删除存在超过 30 天的清单数据。如果您需要将清单数据存储 30 天以上，可以使用 AWS Config 来记录历史记录，或者定期查询数据并将其上传到 Amazon Simple Storage Service (Amazon S3) 存储桶。
+ 如果先前已将某个节点配置为报告某一特定清单数据类型（例如 `AWS:Network`），后来您将该配置更改为停止收集该类型，聚合计数仍会显示 `AWS:Network` 数据，直到该节点已被终止并已经过 30 天为止。
有关如何快速配置并收集某一特定 AWS 账户 中所有节点（以及未来可能在该账户中创建的任何节点）中的清单数据的信息，请参阅 [清点 AWS 账户 中的所有托管式节点](inventory-collection.md#inventory-management-inventory-all)。
**Topics**
+ [聚合清单数据以查看收集特定类型数据的节点的计数](#inventory-aggregate-type)
+ [使用组聚合清单数据，以查看已配置为以及未配置为收集某个清单类型的节点](#inventory-aggregate-groups)
## 聚合清单数据以查看收集特定类型数据的节点的计数
您可以使用 AWS Systems Manager [GetInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetInventory.html) API 操作，查看收集一个或多个清单类型和数据类型的节点的聚合计数。例如，`AWS:InstanceInformation` 清单类型使您能够通过结合使用 GetInventory API 操作和 `AWS:InstanceInformation.PlatformType` 数据类型，来查看操作系统的聚合。以下是示例 AWS CLI 命令和输出。
```
aws ssm get-inventory --aggregators "Expression=AWS:InstanceInformation.PlatformType"
```
系统将返回类似于以下内容的信息。
```
{
"Entities":[
{
"Data":{
"AWS:InstanceInformation":{
"Content":[
{
"Count":"7",
"PlatformType":"windows"
},
{
"Count":"5",
"PlatformType":"linux"
}
]
}
}
}
]
}
```
**开始使用**
确定要查看其计数的清单类型和数据类型。您可以通过在 AWS CLI 中运行以下命令查看支持聚合的清单类型和数据类型的列表。
```
aws ssm get-inventory-schema --aggregator
```
该命令返回支持聚合的清单类型和数据类型的 JSON 列表。**TypeName** 字段显示支持的清单类型。此处，**Name (名称)** 字段显示每个数据类型。例如，在以下列表中，`AWS:Application` 清单类型包括 `Name` 和 `Version` 的数据类型。
```
{
"Schemas": [
{
"TypeName": "AWS:Application",
"Version": "1.1",
"DisplayName": "Application",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "Version"
}
]
},
{
"TypeName": "AWS:InstanceInformation",
"Version": "1.0",
"DisplayName": "Platform",
"Attributes": [
{
"DataType": "STRING",
"Name": "PlatformName"
},
{
"DataType": "STRING",
"Name": "PlatformType"
},
{
"DataType": "STRING",
"Name": "PlatformVersion"
}
]
},
{
"TypeName": "AWS:ResourceGroup",
"Version": "1.0",
"DisplayName": "ResourceGroup",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
}
]
},
{
"TypeName": "AWS:Service",
"Version": "1.0",
"DisplayName": "Service",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "DisplayName"
},
{
"DataType": "STRING",
"Name": "ServiceType"
},
{
"DataType": "STRING",
"Name": "Status"
},
{
"DataType": "STRING",
"Name": "StartType"
}
]
},
{
"TypeName": "AWS:WindowsRole",
"Version": "1.0",
"DisplayName": "WindowsRole",
"Attributes": [
{
"DataType": "STRING",
"Name": "Name"
},
{
"DataType": "STRING",
"Name": "DisplayName"
},
{
"DataType": "STRING",
"Name": "FeatureType"
},
{
"DataType": "STRING",
"Name": "Installed"
}
]
}
]
}
```
您可以通过创建使用以下语法的命令来聚合任何所列清单类型的数据。
```
aws ssm get-inventory --aggregators "Expression=InventoryType.DataType"
```
下面是一些示例。
**示例 1**
此示例聚合节点使用的 Windows 角色的计数。
```
aws ssm get-inventory --aggregators "Expression=AWS:WindowsRole.Name"
```
**示例 2**
此示例聚合安装在节点上的应用程序的计数。
```
aws ssm get-inventory --aggregators "Expression=AWS:Application.Name"
```
**组合多个聚合器**
您也可以在一个命令中组合多个清单类型和数据类型，以帮助您更好地了解数据。下面是一些示例。
**示例 1**
此示例聚合节点使用的操作系统类型的计数。它还会返回操作系统的特定名称。
```
aws ssm get-inventory --aggregators '[{"Expression": "AWS:InstanceInformation.PlatformType", "Aggregators":[{"Expression": "AWS:InstanceInformation.PlatformName"}]}]'
```
**示例 2**
此示例聚合在节点上运行的应用程序和每个应用程序的特定版本的计数。
```
aws ssm get-inventory --aggregators '[{"Expression": "AWS:Application.Name", "Aggregators":[{"Expression": "AWS:Application.Version"}]}]'
```
如果您愿意，也可以使用 JSON 文件中的一个或多个清单类型和数据类型创建聚合表达式并从 AWS CLI 调用该文件。该文件中的 JSON 必须使用以下语法。
```
[
{
"Expression": "string",
"Aggregators": [
{
"Expression": "string"
}
]
}
]
```
您必须使用 .json 文件扩展名保存该文件。
以下是使用多个清单类型和数据类型的示例。
```
[
{
"Expression": "AWS:Application.Name",
"Aggregators": [
{
"Expression": "AWS:Application.Version",
"Aggregators": [
{
"Expression": "AWS:InstanceInformation.PlatformType"
}
]
}
]
}
]
```
使用以下命令从 AWS CLI 调用该文件。
```
aws ssm get-inventory --aggregators file://file_name.json
```
此命令会返回如下信息。
```
{"Entities":
[
{"Data":
{"AWS:Application":
{"Content":
[
{"Count": "3",
"PlatformType": "linux",
"Version": "2.6.5",
"Name": "audit-libs"},
{"Count": "2",
"PlatformType": "windows",
"Version": "2.6.5",
"Name": "audit-libs"},
{"Count": "4",
"PlatformType": "windows",
"Version": "6.2.8",
"Name": "microsoft office"},
{"Count": "2",
"PlatformType": "windows",
"Version": "2.6.5",
"Name": "chrome"},
{"Count": "1",
"PlatformType": "linux",
"Version": "2.6.5",
"Name": "chrome"},
{"Count": "2",
"PlatformType": "linux",
"Version": "6.3",
"Name": "authconfig"}
]
}
},
"ResourceType": "ManagedInstance"}
]
}
```
## 使用组聚合清单数据，以查看已配置为以及未配置为收集某个清单类型的节点
使用 Systems Manager Inventory 中的组，您可以快速查看已配置为和未配置为收集一个或多个清单类型的托管式节点的计数。利用组，可指定一个或多个清单类型和使用 `exists` 运算符的筛选条件。
例如，假设您已将四个托管式节点配置为收集以下清单类型：
+ 节点 1：`AWS:Application`
+ 节点 2：`AWS:File`
+ 节点 3：`AWS:Application`、`AWS:File`
+ 节点 4：`AWS:Network`
您可以从 AWS CLI 运行以下命令，以查看已配置为收集 `AWS:Application` 和 `AWS:File inventory` 类型的节点的数量。该响应还返回未配置为收集这两个清单类型的节点数的计数。
```
aws ssm get-inventory --aggregators 'Groups=[{Name=ApplicationAndFile,Filters=[{Key=TypeName,Values=[AWS:Application],Type=Exists},{Key=TypeName,Values=[AWS:File],Type=Exists}]}]'
```
该命令响应显示仅一个托管式节点已配置为收集 `AWS:Application` 和 `AWS:File` 清单类型。
```
{
"Entities":[
{
"Data":{
"ApplicationAndFile":{
"Content":[
{
"notMatchingCount":"3"
},
{
"matchingCount":"1"
}
]
}
}
}
]
}
```
**注意**
组不会返回数据类型计数。此外，您也无法深入查询结果来查看已配置为或未配置为收集该清单类型的节点的 ID。
如果您愿意，也可以使用 JSON 文件中的一个或多个清单类型创建聚合表达式并从 AWS CLI 调用该文件。该文件中的 JSON 必须使用以下语法：
```
{
"Aggregators":[
{
"Groups":[
{
"Name":"Name",
"Filters":[
{
"Key":"TypeName",
"Values":[
"Inventory_type"
],
"Type":"Exists"
},
{
"Key":"TypeName",
"Values":[
"Inventory_type"
],
"Type":"Exists"
}
]
}
]
}
]
}
```
您必须使用 .json 文件扩展名保存该文件。
使用以下命令从 AWS CLI 调用该文件。
```
aws ssm get-inventory --cli-input-json file://file_name.json
```
**其他示例**
以下示例说明了如何聚合清单数据，以查看已配置为和未配置为收集指定清单类型的托管式节点。这些示例使用 AWS CLI。每个示例包含一个带筛选条件的完整命令，您可以从命令行和示例 input.json 文件运行该命令（如果您更喜欢在文件中输入该信息）。
**示例 1**
此示例聚合已配置为和未配置为收集 `AWS:Application` 或 `AWS:File` 清单类型的节点的计数。
从 AWS CLI 运行以下命令。
```
aws ssm get-inventory --aggregators 'Groups=[{Name=ApplicationORFile,Filters=[{Key=TypeName,Values=[AWS:Application, AWS:File],Type=Exists}]}]'
```
如果您更喜欢使用文件，请将以下示例复制并粘贴到文件中并且将其另存为 input.json。
```
{
"Aggregators":[
{
"Groups":[
{
"Name":"ApplicationORFile",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Application",
"AWS:File"
],
"Type":"Exists"
}
]
}
]
}
]
}
```
从 AWS CLI 运行以下命令。
```
aws ssm get-inventory --cli-input-json file://input.json
```
此命令会返回如下信息。
```
{
"Entities":[
{
"Data":{
"ApplicationORFile":{
"Content":[
{
"notMatchingCount":"1"
},
{
"matchingCount":"3"
}
]
}
}
}
]
}
```
**示例 2**
此示例聚合已配置为和未配置为收集 `AWS:Application`、`AWS:File` 和 `AWS:Network` 清单类型的节点的计数。
从 AWS CLI 运行以下命令。
```
aws ssm get-inventory --aggregators 'Groups=[{Name=Application,Filters=[{Key=TypeName,Values=[AWS:Application],Type=Exists}]}, {Name=File,Filters=[{Key=TypeName,Values=[AWS:File],Type=Exists}]}, {Name=Network,Filters=[{Key=TypeName,Values=[AWS:Network],Type=Exists}]}]'
```
如果您更喜欢使用文件，请将以下示例复制并粘贴到文件中并且将其另存为 input.json。
```
{
"Aggregators":[
{
"Groups":[
{
"Name":"Application",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Application"
],
"Type":"Exists"
}
]
},
{
"Name":"File",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:File"
],
"Type":"Exists"
}
]
},
{
"Name":"Network",
"Filters":[
{
"Key":"TypeName",
"Values":[
"AWS:Network"
],
"Type":"Exists"
}
]
}
]
}
]
}
```
从 AWS CLI 运行以下命令。
```
aws ssm get-inventory --cli-input-json file://input.json
```
此命令会返回如下信息。
```
{
"Entities":[
{
"Data":{
"Application":{
"Content":[
{
"notMatchingCount":"2"
},
{
"matchingCount":"2"
}
]
},
"File":{
"Content":[
{
"notMatchingCount":"2"
},
{
"matchingCount":"2"
}
]
},
"Network":{
"Content":[
{
"notMatchingCount":"3"
},
{
"matchingCount":"1"
}
]
}
}
}
]
}
```
# 使用自定义清单
您可以通过创建 AWS Systems Manager Inventory *自定义清单*，将所需的任何元数据分配给您的节点。例如，假设您负责管理数据中心内多个机架中的大量服务器，而且这些服务器已配置为 Systems Manager 托管式节点。目前，您在电子表格中存储服务器机架位置的相关信息。借助自定义清单，您可以指定每个节点的机架位置作为节点上的元数据。当您使用 Systems Manager 收集清单时，该元数据将与其他清单元数据一起收集。然后，您可以使用[资源数据同步](inventory-resource-data-sync.html)将所有清单元数据移植到中央 Amazon S3 存储桶，并查询这些数据。
**注意**
Systems Manager 最多可为每个 AWS 账户 支持 20 个自定义清单类型。
要将自定义清单分配给某个节点，可以使用 Systems Manager [PutInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutInventory.html) API 操作，如 [将自定义清单元数据分配给某个托管式节点](inventory-custom-metadata.md) 中所述。或者，您可以创建自定义清单 JSON 文件并将其上传到该节点。本部分描述了如何创建 JSON 文件。
以下包含自定义清单的示例 JSON 文件指定有关本地服务器的机架信息。此示例指定一种类型的自定义清单数据 (`"TypeName": "Custom:RackInformation"`)，在描述数据的 `Content` 下有多个条目。
```
{
"SchemaVersion": "1.0",
"TypeName": "Custom:RackInformation",
"Content": {
"Location": "US-EAST-02.CMH.RACK1",
"InstalledTime": "2016-01-01T01:01:01Z",
"vendor": "DELL",
"Zone" : "BJS12",
"TimeZone": "UTC-8"
}
}
```
您也可以在 `Content` 部分指定不同条目，如以下示例所示。
```
{
"SchemaVersion": "1.0",
"TypeName": "Custom:PuppetModuleInfo",
"Content": [{
"Name": "puppetlabs/aws",
"Version": "1.0"
},
{
"Name": "puppetlabs/dsc",
"Version": "2.0"
}
]
}
```
自定义清单的 JSON 架构需要 `SchemaVersion`、`TypeName` 和 `Content` 部分，但您可以定义这些部分的信息。
```
{
"SchemaVersion": "user_defined",
"TypeName": "Custom:user_defined",
"Content": {
"user_defined_attribute1": "user_defined_value1",
"user_defined_attribute2": "user_defined_value2",
"user_defined_attribute3": "user_defined_value3",
"user_defined_attribute4": "user_defined_value4"
}
}
```
`TypeName` 值的长度限制为 100 个字符。此外，`TypeName` 值必须以大写的单词 `Custom` 开头。例如 `Custom:PuppetModuleInfo`。因此，以下示例将导致异常：`CUSTOM:PuppetModuleInfo`、`custom:PuppetModuleInfo`。
`Content` 部分包括属性和 *data*。这些项目不区分大小写。但是，如果您定义了属性（例如：“`Vendor`”：“DELL”），则在自定义清单文件中必须一致地引用此属性。如果您在一个文件中指定“`Vendor`”：“DELL”（在 `vendor` 中使用大写字母“V”），在另一个文件中指定“`vendor`”：“DELL”（在 `vendor` 中使用小写字母“v”），系统会返回错误。
**注意**
您必须使用 `.json` 扩展名保存文件，并且您定义的清单必须仅包含字符串值。
创建文件之后，您必须在节点上保存文件。下表说明了自定义清单 JSON 文件必须存储在节点上的哪个位置。
****
| 操作系统 | 路径 |
| --- | --- |
| Linux | /var/lib/amazon/ssm/*node-id*/inventory/custom |
| macOS | `/opt/aws/ssm/data/node-id/inventory/custom` |
| Windows Server | %SystemDrive%\$1ProgramData\$1Amazon\$1SSM\$1InstanceData\$1*note-id*\$1inventory\$1custom |
有关如何使用自定义清单的示例，请参阅[使用 EC2 Systems Manager 自定义清单类型获取队列的磁盘利用率](https://aws.amazon.com/blogs/mt/get-disk-utilization-of-your-fleet-using-ec2-systems-manager-custom-inventory-types/)。
## 删除自定义清单
您可以使用 [DeleteInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeleteInventory.html) API 操作来删除自定义清单类型以及与该类型关联的数据。您可以使用 AWS Command Line Interface (AWS CLI) 调用 delete-inventory 命令来删除某一清单类型的所有数据。您可以使用 `SchemaDeleteOption` 调用 delete-inventory 命令来删除自定义清单类型。
**注意**
清单类型也称为清单架构。
`SchemaDeleteOption` 参数包括以下选项：
+ **DeleteSchema**：此选项删除指定的自定义类型和与之关联的所有数据。如果需要，可以稍后重新创建架构。
+ **DisableSchema**：如果您选择此选项，系统将关闭当前版本，删除其所有数据，并在版本低于或等于已关闭版本时忽略所有新数据。您可以通过对高于已关闭版本的版本调用 [PutInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutInventory.html) 操作来重新允许此清单类型。
**使用 AWS CLI 删除或关闭自定义清单**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令来使用 `dry-run` 选项查看将从系统中删除哪些数据。此命令不会删除任何数据。
```
aws ssm delete-inventory --type-name "Custom:custom_type_name" --dry-run
```
系统将返回类似于以下内容的信息。
```
{
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}
```
有关如何了解和删除清单摘要的信息，请参阅 [了解删除清单摘要](#delete-custom-inventory-summary)。
1. 运行以下命令来删除自定义清单类型的所有数据。
```
aws ssm delete-inventory --type-name "Custom:custom_type_name"
```
**注意**
此命令的输出未显示删除进度。因此，TotalCount (总计数) 和 Remaining Count (剩余计数) 始终相同，因为系统尚未删除任何数据。您可以使用 describe-inventory-deletions 命令来显示删除进度，如本主题的下文所述。
系统将返回类似于以下内容的信息。
```
{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"custom_type_name"
}
```
系统将从 Systems Manager Inventory 服务中删除指定的自定义清单类型的所有数据。
1. 运行如下命令。此命令对清单类型的当前版本执行以下操作：关闭当前版本、删除其所有数据，并在版本低于或等于已关闭版本时忽略所有新数据。
```
aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option "DisableSchema"
```
系统将返回类似于以下内容的信息。
```
{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}
```
您可以使用以下命令查看已关闭的清单类型。
```
aws ssm get-inventory-schema --type-name Custom:custom_type_name
```
1. 运行以下命令来删除清单类型。
```
aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option "DeleteSchema"
```
系统将删除指定的自定义类型的架构和所有清单数据。
系统将返回类似于以下内容的信息。
```
{
"DeletionId":"system_generated_deletion_ID",
"DeletionSummary":{
"RemainingCount":3,
"SummaryItems":[
{
"Count":2,
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1,
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"Custom:custom_type_name"
}
```
### 查看删除状态
您可以使用 `describe-inventory-deletions` AWS CLI 命令来查看删除操作的状态。您可以指定删除 ID 来查看特定删除操作的状态。或者，您也可以省略删除 ID 来查看最近 30 天运行的所有删除的列表。
****
1. 运行以下命令来查看删除操作的状态。系统将返回 delete-inventory 摘要中的删除 ID。
```
aws ssm describe-inventory-deletions --deletion-id system_generated_deletion_ID
```
系统将返回最新状态。删除操作可能尚未完成。系统将返回类似于以下内容的信息。
```
{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 1,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 1,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "InProgress",
"LastStatusMessage": "The Delete is in progress",
"LastStatusUpdateTime": 1521744844,
"TypeName": "Custom:custom_type_name"}
]
}
```
如果删除操作成功，则 `LastStatusMessage` 指出：Deletion is successful。
```
{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521745253,
"TypeName": "Custom:custom_type_name"}
]
}
```
1. 运行以下命令来查看最近 30 天运行的所有删除的列表。
```
aws ssm describe-inventory-deletions --max-results a number
```
```
{"InventoryDeletions":
[
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521682552,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521682852,
"TypeName": "Custom:custom_type_name"},
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521744844,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521745253,
"TypeName": "Custom:custom_type_name"},
{"DeletionId": "system_generated_deletion_ID",
"DeletionStartTime": 1521680145,
"DeletionSummary":
{"RemainingCount": 0,
"SummaryItems":
[
{"Count": 1,
"RemainingCount": 0,
"Version": "1.0"}
],
"TotalCount": 1},
"LastStatus": "Complete",
"LastStatusMessage": "Deletion is successful",
"LastStatusUpdateTime": 1521680471,
"TypeName": "Custom:custom_type_name"}
],
"NextToken": "next-token"
```
### 了解删除清单摘要
为帮助您了解删除清单摘要的内容，请考虑以下示例。某用户将 Custom:RackSpace 清单分配给了三个节点。清单项目 1 和 2 使用自定义类型版本 1.0 ("SchemaVersion":"1.0")。清单项目 3 使用自定义类型版本 2.0 ("SchemaVersion":"2.0")。
RackSpace 自定义清单 1
```
{
"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567890",
"SchemaVersion":"1.0" "Content":[
{
content of custom type omitted
}
]
}
```
RackSpace 自定义清单 2
```
{
"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567891",
"SchemaVersion":"1.0" "Content":[
{
content of custom type omitted
}
]
}
```
RackSpace 自定义清单 3
```
{
"CaptureTime":"2018-02-19T10:48:55Z",
"TypeName":"CustomType:RackSpace",
"InstanceId":"i-1234567892",
"SchemaVersion":"2.0" "Content":[
{
content of custom type omitted
}
]
}
```
用户运行以下命令来预览将删除哪些数据。
```
aws ssm delete-inventory --type-name "Custom:RackSpace" --dry-run
```
系统将返回类似于以下内容的信息。
```
{
"DeletionId":"1111-2222-333-444-66666",
"DeletionSummary":{
"RemainingCount":3,
"TotalCount":3,
TotalCount and RemainingCount are the number of items that would be deleted if this was not a dry run. These numbers are the same because the system didn't delete anything.
"SummaryItems":[
{
"Count":2, The system found two items that use SchemaVersion 1.0. Neither item was deleted.
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1, The system found one item that uses SchemaVersion 1.0. This item was not deleted.
"RemainingCount":1,
"Version":"2.0"
}
],
},
"TypeName":"Custom:RackSpace"
}
```
用户运行以下命令来删除 Custom:RackSpace 清单。
**注意**
此命令的输出未显示删除进度。因此，`TotalCount` 和 `RemainingCount` 始终相同，因为系统尚未删除任何数据。您可以使用 `describe-inventory-deletions` 命令来显示删除进度。
```
aws ssm delete-inventory --type-name "Custom:RackSpace"
```
系统将返回类似于以下内容的信息。
```
{
"DeletionId":"1111-2222-333-444-7777777",
"DeletionSummary":{
"RemainingCount":3, There are three items to delete
"SummaryItems":[
{
"Count":2, The system found two items that use SchemaVersion 1.0.
"RemainingCount":2,
"Version":"1.0"
},
{
"Count":1, The system found one item that uses SchemaVersion 2.0.
"RemainingCount":1,
"Version":"2.0"
}
],
"TotalCount":3
},
"TypeName":"RackSpace"
}
```
### 在 EventBridge 中查看清单删除操作
您可以配置 Amazon EventBridge，在用户删除自定义清单时创建事件。EventBridge 为自定义清单删除操作提供三种类型的事件：
+ **实例的删除操作**：特定托管式节点的自定义清单是否已成功删除。
+ **删除操作摘要**：删除操作的摘要。
+ **针对已关闭的自定义清单类型的警告**：如果用户对先前关闭的自定义清单类型版本调用了 [PutInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutInventory.html) API 操作，则会发出警告事件。
下面是每个事件的示例。
**实例的删除操作**
```
{
"version":"0",
"id":"998c9cde-56c0-b38b-707f-0411b3ff9d11",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",
"account":"478678815555",
"time":"2018-05-24T22:24:34Z",
"region":"us-east-1",
"resources":[
"arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0a5feb270fc3f0b97"
],
"detail":{
"action-status":"succeeded",
"action":"delete",
"resource-type":"managed-instance",
"resource-id":"i-0a5feb270fc3f0b97",
"action-reason":"",
"type-name":"Custom:MyInfo"
}
}
```
**删除操作摘要**
```
{
"version":"0",
"id":"83898300-f576-5181-7a67-fb3e45e4fad4",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",
"account":"478678815555",
"time":"2018-05-24T22:28:25Z",
"region":"us-east-1",
"resources":[
],
"detail":{
"action-status":"succeeded",
"action":"delete-summary",
"resource-type":"managed-instance",
"resource-id":"",
"action-reason":"The delete for type name Custom:MyInfo was completed. The deletion summary is: {\"totalCount\":2,\"remainingCount\":0,\"summaryItems\":[{\"version\":\"1.0\",\"count\":2,\"remainingCount\":0}]}",
"type-name":"Custom:MyInfo"
}
}
```
**针对已关闭的自定义清单类型的警告**
```
{
"version":"0",
"id":"49c1855c-9c57-b5d7-8518-b64aeeef5e4a",
"detail-type":"Inventory Resource State Change",
"source":"aws.ssm",
"account":"478678815555",
"time":"2018-05-24T22:46:58Z",
"region":"us-east-1",
"resources":[
"arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0ee2d86a2cfc371f6"
],
"detail":{
"action-status":"failed",
"action":"put",
"resource-type":"managed-instance",
"resource-id":"i-0ee2d86a2cfc371f6",
"action-reason":"The inventory item with type name Custom:MyInfo was sent with a disabled schema version 1.0. You must send a version greater than 1.0",
"type-name":"Custom:MyInfo"
}
}
```
可以使用以下过程为自定义清单删除操作创建 EventBridge 规则。此过程向您介绍如何创建向 Amazon SNS 主题发送自定义清单删除操作通知的规则。开始前，请验证您是否拥有 Amazon SNS 主题，如果没有请新建一个。有关更多信息，请参阅 *Amazon Simple Notification Service Developer Guide* 中的[入门](https://docs.aws.amazon.com/sns/latest/dg/GettingStarted.html)。
**为删除清单操作配置 EventBridge**
1. 打开位于 [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/) 的 Amazon EventBridge 控制台。
1. 在导航窗格中，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。
规则不能与同一区域中的另一个规则和同一事件总线上的名称相同。
1. 对于**事件总线**，请选择要与此规则关联的事件总线。如果您希望此规则响应来自您自己的 AWS 账户的匹配事件，请选择 **defaul**（默认）。当您账户中的某个 AWS 服务发出一个事件时，它始终会发送到您账户的默认事件总线。
1. 对于**规则类型**，选择**具有事件模式的规则**。
1. 选择**下一步**。
1. 对于**事件源**，选择**AWS 事件或 EventBridge 合作伙伴事件**。
1. 在 **Event pattern**（事件模式）部分，选择 **Event pattern form**（事件模式表单）。
1. 对于**事件源**，选择**AWS 服务**。
1. 对于 ** service**（AWS 服务），选择 **Systems Manager**。
1. 对于 **Event type (事件类型)**，选择 **Inventory (清单)**。
1. 对于 **Specific detail type(s)**（具体详细信息类型），选择 **Inventory Resource State Change**（清单资源状态更改）。
1. 选择**下一步**。
1. 对于**目标类型**，选择**AWS 服务**。
1. 对于 **Select a target**（选择一个目标），选择 **SNS topic**（SNS 主题），然后对于 **Topic**（主题），选择您的主题。
1. 在 **Additional settings**（其他设置）部分，对于 **Configure target input**（配置目标输入），请验证已选择 **Matched event**（匹配的事件）。
1. 选择**下一步**。
1. （可选）为规则输入一个或多个标签。有关更多信息，请参阅 *Amazon EventBridge 用户指南*中的[标记 Amazon EventBridge 资源](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html)。
1. 选择 **Next（下一步）**。
1. 查看规则详细信息并选择**创建规则**。
# 查看清单历史记录和变更跟踪
您可以使用 [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/) 查看所有托管式节点的 AWS Systems Manager Inventory 历史记录和更改跟踪。AWS Config 提供了关于 AWS 账户 中 AWS 资源配置的详细视图。这些信息包括资源之间的关联方式以及资源以前的配置方式，让您了解资源的配置和关系如何随着的时间的推移而更改。要查看清单历史记录和更改跟踪，您必须在 AWS Config 中打开以下资源：
+ SSM:ManagedInstanceInventory
+ SSM:PatchCompliance
+ SSM:AssociationCompliance
+ SSM:FileData
**注意**
请注意关于 Inventory 历史记录和更改跟踪的以下重要详细信息：
如果您使用 AWS Config 来跟踪系统中的更改，则必须配置 Systems Manager Inventory 以收集 `AWS:File` 元数据，以便能够查看 AWS Config (`SSM:FileData`) 中的文件更改。如果不进行此配置，则 AWS Config 不会跟踪系统上的文件更改。
通过打开 SSM:PatchCompliance 和 SSM:AssociationCompliance，您可以查看 Systems Manager Patch Manager 修补和 Systems Manager State Manager 关联的合规历史记录及更改跟踪。有关这些资源的合规性管理的更多信息，请参阅 [了解有关合规性的详细信息](compliance-about.md)。
以下过程介绍了如何使用 AWS Command Line Interface (AWS CLI) 在 AWS Config 中打开清单历史记录和更改跟踪记录。有关如何在 AWS Config 中选择和配置这些资源的更多信息，请参阅 *AWS Config Developer Guide *中的[选择哪些资源 AWS Config 记录](https://docs.aws.amazon.com/config/latest/developerguide/select-resources.html)。有关 AWS Config 定价的信息，请参阅 [ 定价](https://aws.amazon.com/config/pricing/)。
**开始之前**
AWS Config 需要 AWS Identity and Access Management (IAM) 权限才能获取有关 Systems Manager 资源的配置详细信息。在以下过程中，您必须为向 Systems Manager 资源提供 AWS Config 权限的 IAM 角色指定 Amazon Resource Name (ARN)。您可以将 `AWS_ConfigRole` 托管式策略附加到分配给 AWS Config 的 IAM 角色。有关该角色的更多信息，请参阅《AWS Config 开发人员指南》中的 [AWS 托管式策略：AWS\$1ConfigRole](https://docs.aws.amazon.com/config/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AWS_ConfigRole)。要了解如何创建 IAM 角色并将 `AWS_ConfigRole` 托管式策略分配给该角色，请参阅《*IAM 用户指南*》中的[创建向 AWS 服务 委托权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。
**在 AWS Config 中打开清单历史记录和更改跟踪记录**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 将以下 JSON 示例复制并粘贴到一个简单的文本文件中，并将其另存为 recordingGroup.json。
```
{
"allSupported":false,
"includeGlobalResourceTypes":false,
"resourceTypes":[
"AWS::SSM::AssociationCompliance",
"AWS::SSM::PatchCompliance",
"AWS::SSM::ManagedInstanceInventory",
"AWS::SSM::FileData"
]
}
```
1. 运行以下命令以将 recordingGroup.json 文件加载到 AWS Config 中。
```
aws configservice put-configuration-recorder --configuration-recorder name=myRecorder,roleARN=arn:aws:iam::123456789012:role/myConfigRole --recording-group file://recordingGroup.json
```
1. 运行以下命令以开始记录清单历史记录和变更跟踪。
```
aws configservice start-configuration-recorder --configuration-recorder-name myRecorder
```
在配置历史记录和更改跟踪后，您可以通过在 Systems Manager 控制台中选择 **AWS Config** 按钮来深入了解某一特定托管式节点的历史记录。您可以从 **Managed Instances**（托管式实例）页面或 **Inventory**（清单）页面访问 **AWS Config** 按钮。根据您的监视器大小，您可能需要滚动到页面右侧以查看该按钮。
# 停止数据收集和删除清单数据
如果您不再需要使用 AWS Systems Manager Inventory 以查看有关 AWS 资源的元数据，可以停止数据收集，并删除已收集到的数据。本节包含以下信息。
**Topics**
+ [停止数据收集](#systems-manager-inventory-delete-association)
+ [删除 Inventory 资源数据同步](#systems-manager-inventory-delete-RDS)
## 停止数据收集
当您最初配置 Systems Manager 以收集清单数据时，系统会创建 State Manager 关联，用于定义计划和从中收集元数据的资源。您可以通过删除任何使用 `AWS-GatherSoftwareInventory` 文档的 State Manager 关联，来停止数据收集。
**删除 Inventory 关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择一个使用 `AWS-GatherSoftwareInventory` 文档的关联，然后选择 **Delete (删除)**。
1. 对于任何其余使用 `AWS-GatherSoftwareInventory` 文档的关联重复步骤 3。
## 删除 Inventory 资源数据同步
如果您不再需要使用 AWS Systems Manager Inventory 来查看有关您的 AWS 资源的元数据，那么我们还建议您删除用于清单数据收集的资源数据同步。
**删除 Inventory 资源数据同步**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Inventory (清单)**。
1. 选择 **Resource Data Syncs (资源数据同步)**。
1. 在列表中，选择一个同步。
**重要**
确保您选择了用于 Inventory 的同步。Systems Manager 可为多项工具的资源数据同步提供支持。如果选择的同步错误，则可能会导致 Systems Manager Explorer 或 Systems Manager Compliance 的数据聚合中断。
1. 选择 **Delete**（删除）
1. 对您要删除的所有其余资源数据同步，重复这些步骤。
1. 删除存储数据的 Amazon Simple Storage Service (Amazon S3) 存储桶。有关删除 Amazon S3 存储桶的信息，请参阅[删除存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html)。
# 将自定义清单元数据分配给某个托管式节点
以下过程为您演示了使用 AWS Systems Manager [PutInventory](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutInventory.html) API 操作将自定义清单元数据分配给托管式节点的过程。此示例将机架位置信息分配给某个节点。有关自定义清单的更多信息，请参阅 [使用自定义清单](inventory-custom.md)。
**将自定义清单元数据分配给某个节点**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令，以便将机架位置信息分配给某个节点。
**Linux**
```
aws ssm put-inventory --instance-id "ID" --items '[{"CaptureTime": "2016-08-22T10:01:01Z", "TypeName": "Custom:RackInfo", "Content":[{"RackLocation": "Bay B/Row C/Rack D/Shelf E"}], "SchemaVersion": "1.0"}]'
```
**Windows**
```
aws ssm put-inventory --instance-id "ID" --items "TypeName=Custom:RackInfo,SchemaVersion=1.0,CaptureTime=2021-05-22T10:01:01Z,Content=[{RackLocation='Bay B/Row C/Rack D/Shelf F'}]"
```
1. 运行以下命令以便查看此节点的自定义清单条目。
```
aws ssm list-inventory-entries --instance-id ID --type-name "Custom:RackInfo"
```
系统会使用类似以下形式的信息进行响应。
```
{
"InstanceId": "ID",
"TypeName": "Custom:RackInfo",
"Entries": [
{
"RackLocation": "Bay B/Row C/Rack D/Shelf E"
}
],
"SchemaVersion": "1.0",
"CaptureTime": "2016-08-22T10:01:01Z"
}
```
1. 运行以下命令以查看自定义清单架构。
```
aws ssm get-inventory-schema --type-name Custom:RackInfo
```
系统会使用类似以下形式的信息进行响应。
```
{
"Schemas": [
{
"TypeName": "Custom:RackInfo",
"Version": "1.0",
"Attributes": [
{
"DataType": "STRING",
"Name": "RackLocation"
}
]
}
]
}
```
# 使用 AWS CLI 配置清单数据收集
以下过程为您演示了将 AWS Systems Manager Inventory 配置为从托管式节点收集元数据的过程。在配置清单收集时，应该首先创建 Systems Manager State Manager 关联。Systems Manager 将在关联运行时收集清单数据。如果您不首先创建关联，并尝试使用 Systems Manager Run Command（举例来说）调用 `aws:softwareInventory` 插件，则系统将返回以下错误：
`The aws:softwareInventory plugin can only be invoked via ssm-associate`.
**注意**
一个节点一次只能配置一个清单关联。如果您为一个节点配置了两个或更多清单关联，则关联不会运行，而且系统不会收集清单数据。
## 快速配置 Inventory 的所有托管式节点 (CLI)
您可以在您的 AWS 账户 和当前区域中快速配置所有托管式节点来收集清单数据。这称为创建全局清单关联。要使用 AWS CLI 创建全局清单关联，请为 `instanceIds` 值使用通配符选项，如以下过程所示。
**在您的 AWS 账户 和当前区域中为所有托管式节点配置清单 (CLI)**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行如下命令。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name AWS-GatherSoftwareInventory \
--targets Key=InstanceIds,Values=* \
--schedule-expression "rate(1 day)" \
--parameters applications=Enabled,awsComponents=Enabled,customInventory=Enabled,instanceDetailedInformation=Enabled,networkConfig=Enabled,services=Enabled,windowsRoles=Enabled,windowsUpdates=Enabled
```
------
#### [ Windows ]
```
aws ssm create-association ^
--name AWS-GatherSoftwareInventory ^
--targets Key=InstanceIds,Values=* ^
--schedule-expression "rate(1 day)" ^
--parameters applications=Enabled,awsComponents=Enabled,customInventory=Enabled,instanceDetailedInformation=Enabled,networkConfig=Enabled,services=Enabled,windowsRoles=Enabled,windowsUpdates=Enabled
```
------
**注意**
此命令不允许 Inventory 收集 Windows 注册表或文件的元数据。要为这些数据类型启用清单，请使用下一个过程。
## 在托管式节点上手动配置 Inventory (CLI)
通过以下过程，使用节点 ID 或标签在您的托管式节点上手动配置 AWS Systems Manager Inventory。
**手动配置 Inventory 的托管式节点 (CLI)**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令，创建一个在节点上运行 Systems Manager Inventory 的 State Manager 关联。将每个*示例资源占位符*替换为您自己的信息。此命令将服务配置为每六小时运行一次，并从节点收集网络配置、Windows 更新和应用程序元数据。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name "AWS-GatherSoftwareInventory" \
--targets "Key=instanceids,Values=an_instance_ID" \
--schedule-expression "rate(240 minutes)" \
--output-location "{ \"S3Location\": { \"OutputS3Region\": \"region_ID, for example us-east-2\", \"OutputS3BucketName\": \"amzn-s3-demo-bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" \
--parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--name "AWS-GatherSoftwareInventory" ^
--targets "Key=instanceids,Values=an_instance_ID" ^
--schedule-expression "rate(240 minutes)" ^
--output-location "{ \"S3Location\": { \"OutputS3Region\": \"region_ID, for example us-east-2\", \"OutputS3BucketName\": \"amzn-s3-demo-bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" ^
--parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"
```
------
系统会使用类似以下形式的信息进行响应。
```
{
"AssociationDescription": {
"ScheduleExpression": "rate(240 minutes)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "Test",
"OutputS3BucketName": "Test bucket",
"OutputS3Region": "us-east-2"
}
},
"Name": "The name you specified",
"Parameters": {
"applications": [
"Enabled"
],
"networkConfig": [
"Enabled"
],
"windowsUpdates": [
"Enabled"
]
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g",
"DocumentVersion": "$DEFAULT",
"LastUpdateAssociationDate": 1480544990.06,
"Date": 1480544990.06,
"Targets": [
{
"Values": [
"i-02573cafcfEXAMPLE"
],
"Key": "InstanceIds"
}
]
}
}
```
您可以搭配使用 `Targets` 参数和 EC2 标签来确定大型目标节点组。请参阅以下示例。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name "AWS-GatherSoftwareInventory" \
--targets "Key=tag:Environment,Values=Production" \
--schedule-expression "rate(240 minutes)" \
--output-location "{ \"S3Location\": { \"OutputS3Region\": \"us-east-2\", \"OutputS3BucketName\": \"amzn-s3-demo-bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" \
--parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--name "AWS-GatherSoftwareInventory" ^
--targets "Key=tag:Environment,Values=Production" ^
--schedule-expression "rate(240 minutes)" ^
--output-location "{ \"S3Location\": { \"OutputS3Region\": \"us-east-2\", \"OutputS3BucketName\": \"amzn-s3-demo-bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" ^
--parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"
```
------
您还可以搭配使用 `files` 和 `windowsRegistry` 清单类型与表达式来清点 Windows Server 节点上的清单文件和 Windows 注册表项。有关这些清单类型的更多信息，请参阅 [使用文件和 Windows 注册表清单](inventory-file-and-registry.md)。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name "AWS-GatherSoftwareInventory" \
--targets "Key=instanceids,Values=i-0704358e3a3da9eb1" \
--schedule-expression "rate(240 minutes)" \
--parameters '{"files":["[{\"Path\": \"C:\\Program Files\", \"Pattern\": [\"*.exe\"], \"Recursive\": true}]"], "windowsRegistry": ["[{\"Path\":\"HKEY_LOCAL_MACHINE\\Software\\Amazon\", \"Recursive\":true}]"]}' \
--profile dev-pdx
```
------
#### [ Windows ]
```
aws ssm create-association ^
--name "AWS-GatherSoftwareInventory" ^
--targets "Key=instanceids,Values=i-0704358e3a3da9eb1" ^
--schedule-expression "rate(240 minutes)" ^
--parameters '{"files":["[{\"Path\": \"C:\\Program Files\", \"Pattern\": [\"*.exe\"], \"Recursive\": true}]"], "windowsRegistry": ["[{\"Path\":\"HKEY_LOCAL_MACHINE\\Software\\Amazon\", \"Recursive\":true}]"]}' ^
--profile dev-pdx
```
------
1. 运行以下命令查看关联状态。
```
aws ssm describe-instance-associations-status --instance-id an_instance_ID
```
系统会使用类似以下形式的信息进行响应。
```
{
"InstanceAssociationStatusInfos": [
{
"Status": "Pending",
"DetailedStatus": "Associated",
"Name": "reInvent2016PolicyDocumentTest",
"InstanceId": "i-1a2b3c4d5e6f7g",
"AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g",
"DocumentVersion": "1"
}
]
}
```
# 演练：使用资源数据同步聚合清单数据
以下演练介绍了如何使用 AWS Command Line Interface (AWS CLI) 为 AWS Systems Manager Inventory 创建资源数据同步配置。资源数据同步可将所有托管式节点中的清单数据自动移植到中央 Amazon Simple Storage Service (Amazon S3) 存储桶。每当发现新的清单数据时，同步操作会自动更新中央 Amazon S3 存储桶中的数据。
此演练还介绍了如何使用 Amazon Athena 和 Amazon Quick 查询及分析聚合数据。有关在 AWS 管理控制台 中使用 Systems Manager 创建资源数据同步的信息，请参阅 [演练：使用资源数据同步聚合清单数据](#inventory-resource-data-sync)。有关在 AWS 管理控制台 中使用 Systems Manager 从多个 AWS 区域 和账户中查询清单的信息，请参阅 [查询多个区域和账户的清单数据](systems-manager-inventory-query.md)。
**注意**
本演练包括有关如何使用 AWS Key Management Service (AWS KMS) 加密同步的信息。Inventory 不收集任何用户特定、专有或敏感数据，因此加密是可选的。有关 AWS KMS 的更多信息，请参阅 [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/)。
**开始前的准备工作**
在开始本节中的演练之前，请审核或完成以下任务：
+ 从托管式节点收集清单数据。对于本演练中的 Amazon Athena 和 Amazon Quick 章节，我们建议您采集应用程序数据。有关如何收集清单数据的更多信息，请参阅 [配置清单收集](inventory-collection.md) 或 [使用 AWS CLI 配置清单数据收集](inventory-collection-cli.md)。
+ （可选）如果清单数据存储在使用 AWS Key Management Service (AWS KMS) 加密的 Amazon Simple Storage Service (Amazon S3) 存储桶中，您还必须配置 IAM 账户和 `Amazon-GlueServiceRoleForSSM` 服务角色，以便进行 AWS KMS 加密。如果您没有配置 IAM 账户和此角色，则当您选择控制台中的 **Detailed View (详细视图)** 选项卡时，Systems Manager 将显示 `Cannot load Glue tables`。有关更多信息，请参阅 [（可选）配置查看 AWS KMS 加密数据的权限](systems-manager-inventory-query.md#systems-manager-inventory-query-kms)。
+ （可选）如果希望使用 AWS KMS 来加密资源数据同步，则您必须创建包含以下策略的新密钥，或者必须更新现有密钥并向其添加此策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "ssm-access-policy",
"Statement": [
{
"Sid": "ssm-access-policy-statement",
"Action": [
"kms:GenerateDataKey"
],
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Resource": "arn:aws:kms:us-east-1:123456789012:key/KMS_key_id",
"Condition": {
"StringLike": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:ssm:*:123456789012:resource-data-sync/*"
}
}
}
]
}
```
------
**为 Inventory 创建资源数据同步**
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 创建用来存储聚合清单数据的存储桶。有关更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)。请记下存储桶名称和创建此存储桶的 AWS 区域。
1. 创建存储桶后，选择 **Permissions** 选项卡，然后选择 **Bucket Policy**。
1. 将下面的存储桶策略复制并粘贴到策略编辑器中。将 amzn-s3-demo-bucket 和 *account-id* 分别替换为您创建的 Amazon S3 存储桶的名称和有效的 AWS 账户 ID。添加多个账户时，请为每个账户添加一个附加条件字符串和 ARN。添加一个账户时，请从示例中删除附加占位符。或者，将 *bucket-prefix* 替换为 Amazon S3 前缀（子目录）的名称。如果您未创建前缀，则从该策略的 ARN 中删除 *bucket-prefix/*。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": " SSMBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "s3:PutObject",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/bucket-prefix/*/accountid=111122223333/*"
],
"Condition": {
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceAccount": [
"111122223333",
"444455556666",
"123456789012",
"777788889999"
]
},
"ArnLike": {
"aws:SourceArn": [
"arn:aws:ssm:*:111122223333:resource-data-sync/*",
"arn:aws:ssm:*:444455556666:resource-data-sync/*",
"arn:aws:ssm:*:123456789012:resource-data-sync/*",
"arn:aws:ssm:*:777788889999:resource-data-sync/*"
]
}
}
}
]
}
```
------
1. （可选）如果要加密同步，则必须将以下条件添加到上一步中列出的策略中。将这些内容添加在 `StringEquals` 部分中。
```
"s3:x-amz-server-side-encryption":"aws:kms",
"s3:x-amz-server-side-encryption-aws-kms-key-id":"arn:aws:kms:region:account_ID:key/KMS_key_ID"
```
示例如下：
```
"StringEquals": {
"s3:x-amz-acl": "bucket-owner-full-control",
"aws:SourceAccount": "account-id",
"s3:x-amz-server-side-encryption":"aws:kms",
"s3:x-amz-server-side-encryption-aws-kms-key-id":"arn:aws:kms:region:account_ID:key/KMS_key_ID"
}
```
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. （可选）如果要加密同步，请运行以下命令，以验证存储桶策略是否强制执行 AWS KMS 密钥要求。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws s3 cp ./A_file_in_the_bucket s3://amzn-s3-demo-bucket/prefix/ \
--sse aws:kms \
--sse-kms-key-id "arn:aws:kms:region:account_ID:key/KMS_key_id" \
--region region, for example, us-east-2
```
------
#### [ Windows ]
```
aws s3 cp ./A_file_in_the_bucket s3://amzn-s3-demo-bucket/prefix/ ^
--sse aws:kms ^
--sse-kms-key-id "arn:aws:kms:region:account_ID:key/KMS_key_id" ^
--region region, for example, us-east-2
```
------
1. 运行以下命令，以使用您在此过程开始时创建的 Amazon S3 存储桶创建资源数据同步配置。此命令从您登录的 AWS 区域创建同步。
**注意**
如果同步和目标 Amazon S3 存储桶位于不同区域中，您可能需要支付数据传输费用。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。
------
#### [ Linux & macOS ]
```
aws ssm create-resource-data-sync \
--sync-name a_name \
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=prefix_name, if_specified,SyncFormat=JsonSerDe,Region=bucket_region"
```
------
#### [ Windows ]
```
aws ssm create-resource-data-sync ^
--sync-name a_name ^
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=prefix_name, if_specified,SyncFormat=JsonSerDe,Region=bucket_region"
```
------
您可以使用 `region` 参数指定创建同步配置的位置。在下例中，来自 us-west-1 区域的清单数据将同步到 us-west-2 区域内的 Amazon S3 存储桶中。
------
#### [ Linux & macOS ]
```
aws ssm create-resource-data-sync \
--sync-name InventoryDataWest \
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=HybridEnv,SyncFormat=JsonSerDe,Region=us-west-2"
--region us-west-1
```
------
#### [ Windows ]
```
aws ssm create-resource-data-sync ^
--sync-name InventoryDataWest ^
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=HybridEnv,SyncFormat=JsonSerDe,Region=us-west-2" ^ --region us-west-1
```
------
（可选）如果要使用 AWS KMS 加密同步，请运行以下命令创建同步。如果您加密同步，则 AWS KMS 密钥和 Amazon S3 存储桶必须位于同一区域中。
------
#### [ Linux & macOS ]
```
aws ssm create-resource-data-sync \
--sync-name sync_name \
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=prefix_name, if_specified,SyncFormat=JsonSerDe,AWSKMSKeyARN=arn:aws:kms:region:account_ID:key/KMS_key_ID,Region=bucket_region" \
--region region
```
------
#### [ Windows ]
```
aws ssm create-resource-data-sync ^
--sync-name sync_name ^
--s3-destination "BucketName=amzn-s3-demo-bucket,Prefix=prefix_name, if_specified,SyncFormat=JsonSerDe,AWSKMSKeyARN=arn:aws:kms:region:account_ID:key/KMS_key_ID,Region=bucket_region" ^
--region region
```
------
1. 运行以下命令查看同步配置的状态。
```
aws ssm list-resource-data-sync
```
如果您在其他区域中创建了同步配置，则必须指定 `region` 参数，如下例所示。
```
aws ssm list-resource-data-sync --region us-west-1
```
1. 在成功创建同步配置后，检查 Amazon S3 中的目标存储桶。清单数据应在几分钟内显示。
**使用 Amazon Athena 中的数据**
以下部分介绍如何在 Amazon Athena 中查看和查询数据。在开始之前，我们建议您首先了解 Athena。有关更多信息，请参阅 *Amazon Athena 用户指南*中的[什么是 Amazon Athena？](https://docs.aws.amazon.com/athena/latest/ug/what-is.html)和[使用数据](https://docs.aws.amazon.com/athena/latest/ug/work-with-data.html)。
**在 Amazon Athena 中查看和查询数据**
1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。
1. 将以下语句复制并粘贴到查询编辑器中，然后选择 **Run Query**。
```
CREATE DATABASE ssminventory
```
系统将创建一个名为 ssminventory 的数据库。
1. 将以下语句复制并粘贴到查询编辑器中，然后选择 **Run Query**。将 amzn-s3-demo-bucket 和 *bucket\$1prefix* 分别替换为 Amazon S3 目标的名称和前缀。
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Application (
Name string,
ResourceId string,
ApplicationType string,
Publisher string,
Version string,
InstalledTime string,
Architecture string,
URL string,
Summary string,
PackageId string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket_prefix/AWS:Application/'
```
1. 将以下语句复制并粘贴到查询编辑器中，然后选择 **Run Query**。
```
MSCK REPAIR TABLE ssminventory.AWS_Application
```
系统将对表进行分区。
**注意**
如果您从其他 AWS 区域或 AWS 账户中创建资源数据同步，则必须再次运行此命令以更新分区。您可能还需要更新 Amazon S3 存储桶策略。
1. 要预览数据，请选择 `AWS_Application` 表旁边的视图图标。
![\[Amazon Athena 中的预览数据图标。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sysman-inventory-resource-data-sync-walk.png)
1. 将以下语句复制并粘贴到查询编辑器中，然后选择 **Run Query**。
```
SELECT a.name, a.version, count( a.version) frequency
from aws_application a where
a.name = 'aws-cfn-bootstrap'
group by a.name, a.version
order by frequency desc
```
该查询将返回不同版本的 `aws-cfn-bootstrap`（它是 Linux、macOS 和 Windows Server 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例上出现的 AWS 应用程序）的计数。
1. 分别将以下语句复制并粘贴到查询编辑器中，将 amzn-s3-demo-bucket 和 *bucket-prefix* 分别替换为 Amazon S3 的相应信息，然后选择**运行查询**。这些语句将在 Athena 中设置其他清单表。
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_AWSComponent (
`ResourceId` string,
`Name` string,
`ApplicationType` string,
`Publisher` string,
`Version` string,
`InstalledTime` string,
`Architecture` string,
`URL` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket-prefix/AWS:AWSComponent/'
```
```
MSCK REPAIR TABLE ssminventory.AWS_AWSComponent
```
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_WindowsUpdate (
`ResourceId` string,
`HotFixId` string,
`Description` string,
`InstalledTime` string,
`InstalledBy` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket-prefix/AWS:WindowsUpdate/'
```
```
MSCK REPAIR TABLE ssminventory.AWS_WindowsUpdate
```
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_InstanceInformation (
`AgentType` string,
`AgentVersion` string,
`ComputerName` string,
`IamRole` string,
`InstanceId` string,
`IpAddress` string,
`PlatformName` string,
`PlatformType` string,
`PlatformVersion` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket-prefix/AWS:InstanceInformation/'
```
```
MSCK REPAIR TABLE ssminventory.AWS_InstanceInformation
```
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Network (
`ResourceId` string,
`Name` string,
`SubnetMask` string,
`Gateway` string,
`DHCPServer` string,
`DNSServer` string,
`MacAddress` string,
`IPV4` string,
`IPV6` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket-prefix/AWS:Network/'
```
```
MSCK REPAIR TABLE ssminventory.AWS_Network
```
```
CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_PatchSummary (
`ResourceId` string,
`PatchGroup` string,
`BaselineId` string,
`SnapshotId` string,
`OwnerInformation` string,
`InstalledCount` int,
`InstalledOtherCount` int,
`NotApplicableCount` int,
`MissingCount` int,
`FailedCount` int,
`OperationType` string,
`OperationStartTime` string,
`OperationEndTime` string
)
PARTITIONED BY (AccountId string, Region string, ResourceType string)
ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
'serialization.format' = '1'
) LOCATION 's3://amzn-s3-demo-bucket/bucket-prefix/AWS:PatchSummary/'
```
```
MSCK REPAIR TABLE ssminventory.AWS_PatchSummary
```
**使用 Amazon Quick 中的数据**
以下部分进行了概述，并包含用于在 Amazon Quick 中构建可视化内容的链接。
**在 Amazon Quick 中构建可视化内容**
1. 注册 [Amazon Quick](https://quicksight.aws/)，然后登录到 Quick 控制台。
1. 从 `AWS_Application` 表和您创建的任何其他表创建数据集。有关更多信息，请参阅《Amazon Quick 用户指南》中的 [Creating a dataset using Amazon Athena data](https://docs.aws.amazon.com/quicksuite/latest/userguide/create-a-data-set-athena.html)**。
1. 联接表。例如，您可以联接 `AWS_InstanceInformation` 中的 `instanceid` 列，因为它与其他清单表中的 `resourceid` 列匹配。有关联表的更多信息，请参阅《Amazon Quick 用户指南》中的 [Joining data](https://docs.aws.amazon.com/quicksuite/latest/userguide/joining-data.html)**。
1. 构建可视化内容。有关更多信息，请参阅《Amazon Quick 用户指南》**中的 [Analyses and reports: Visualizing data in Amazon Quick Sight](https://docs.aws.amazon.com/quicksuite/latest/userguide/working-with-visuals.html)。
# 对 Systems Manager Inventory 的问题进行故障排除
本主题包括有关如何排除 AWS Systems Manager Inventory 中常见错误或问题的信息。如果您在 Systems Manager 中查看节点时遇到问题，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)。
**Topics**
+ [不支持多次应用所有使用文档“`AWS-GatherSoftwareInventory`”的关联](#systems-manager-inventory-troubleshooting-multiple)
+ [清单执行状态永远不会退出待处理状态](#inventory-troubleshooting-pending)
+ [`AWS-ListWindowsInventory` 文档无法运行](#inventory-troubleshooting-ListWindowsInventory)
+ [控制台不显示 Inventory“控制面板”\$1“详细视图”\$1“设置”选项卡](#inventory-troubleshooting-tabs)
+ [UnsupportedAgent](#inventory-troubleshooting-unsupported-agent)
+ [Skipped](#inventory-troubleshooting-skipped)
+ [失败](#inventory-troubleshooting-failed)
+ [Amazon EC2 实例的库存合规性失败](#inventory-troubleshooting-ec2-compliance)
+ [S3 存储桶对象包含旧数据](#systems-manager-inventory-troubleshooting-s3)
## 不支持多次应用所有使用文档“`AWS-GatherSoftwareInventory`”的关联
错误消息 `Multiple apply all associations with document 'AWS-GatherSoftwareInventory' are not supported` 表示：您尝试在其中*为所有节点*配置 Inventory 关联的一个或多个 AWS 区域，已配置有一个适用于所有节点的清单关联。如有必要，您可以删除所有节点的现有清单关联，然后创建新的清单关联。要查看现有清单关联，在 Systems Manager 控制台中选择 **State Manager**，然后找到使用 `AWS-GatherSoftwareInventory` SSM 文档的关联。如果跨多个区域创建了所有节点的现有清单关联，并且您希望创建一个新的清单关联，则必须从现有清单关联存在的每个区域中删除它。
## 清单执行状态永远不会退出待处理状态
清单收集永远不会退出 `Pending` 状态的原因有两个：
+ 所选 AWS 区域 中没有节点：
如果您使用 Systems Manager Quick Setup 创建全局清单关联，并且如果所选区域中没有可用节点，则清单关联（`AWS-GatherSoftwareInventory` 文档）的状态将显示 `Pending`。****
+ 权限不足
如果一个或多个节点没有运行 Systems Manager Inventory 的权限，清单关联将显示 `Pending`。验证并确保 AWS Identity and Access Management (IAM) 实例配置文件包含 **AmazonSSMManagedInstanceCore** 托管式策略。有关如何将此策略添加到实例配置文件的信息，请参阅[EC2 实例权限的替代配置](setup-instance-permissions.md#instance-profile-add-permissions)。
实例配置文件必须至少拥有以下 IAM 权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:DescribeAssociation",
"ssm:ListAssociations",
"ssm:ListInstanceAssociations",
"ssm:PutInventory",
"ssm:PutComplianceItems",
"ssm:UpdateAssociationStatus",
"ssm:UpdateInstanceAssociationStatus",
"ssm:UpdateInstanceInformation",
"ssm:GetDocument",
"ssm:DescribeDocument"
],
"Resource": "*"
}
]
}
```
------
## `AWS-ListWindowsInventory` 文档无法运行
`AWS-ListWindowsInventory` 文档已被弃用。请勿使用此文档收集清单，而应使用 [配置清单收集](inventory-collection.md) 中描述的其中一个进程。
## 控制台不显示 Inventory“控制面板”\$1“详细视图”\$1“设置”选项卡
仅在提供 Amazon Athena 的 AWS 区域 中提供了 Inventory **Detailed View (详细视图)** 页面。如果在 Inventory 页面上未显示以下选项卡，则意味着 Athena 在该区域中不可用，并且您无法使用 **Detailed View (详细视图)** 查询数据。
![\[显示 Inventory“控制面板”|“详细视图”|“设置”选项卡\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/inventory-detailed-view-for-error.png)
## UnsupportedAgent
如果清单关联的详细状态显示为 **UnsupportedAgent**，并且**关联状态**显示为**失败**，则说明托管式节点上的 AWS Systems Manager SSM Agent 版本不正确。例如，要创建全局清单关联（用于清点 AWS 账户 中的所有节点），您必须使用 SSM Agent 版本 2.0.790.0 或更高版本。您可以在 **Managed Instances**（托管式实例）页面的 **Agent version**（代理版本）列中查看各个节点上运行的代理版本。有关如何在节点上更新 SSM Agent 的信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
## Skipped
如果某个节点的清单关联状态显示为**跳过**，则意味着该节点已经有更高优先级清单关联在运行。当多个清单关联可能应用于同一个托管节点时，Systems Manager 会遵循特定的优先顺序。
### 清单关联优先顺序
Systems Manager 按照以下优先顺序应用清单关联：
1. **Quick Setup清单关联**：使用 Quick Setup 和统一控制台创建的关联。这些关联的名称以 `AWS-QuickSetup-SSM-CollectInventory-` 开头，并以所有托管节点为目标。
1. **显式清单关联**：使用以下方法，以特定托管节点为目标的关联：
+ 实例 ID
+ 标签键值对
+ AWS 资源组
1. **全局清单关联**：以所有托管节点为目标（使用 `--targets "Key=InstanceIds,Values=*"`），但**并非**通过 Quick Setup 创建的关联。
### 常见场景
**场景 1：Quick Setup 关联优先于显式关联**
+ 您拥有一个以所有实例为目标的清单关联 Quick Setup
+ 您通过标签创建一个以特定托管节点为目标的手动关联
+ 结果：手动关联显示为 `Skipped`，详细状态为 `OverriddenByExplicitInventoryAssociation`
+ 该 Quick Setup 关联继续从所有实例收集清单
**场景 2：显式关联优先于全局关联**
+ 您拥有一个以所有实例为目标的全局清单关联（并非通过 Quick Setup 创建）
+ 您创建一个以特定实例为目标的关联
+ 结果：对于特定的目标实例，全局关联显示 `Skipped`
+ 显式关联运行在目标实例上
### 解决步骤
**如果您想使用自己的清单关联而非 Quick Setup：**
1. **识别 Quick Setup 关联**：在 Systems Manager 控制台中，转至 State Manager 并查找名字以 `AWS-QuickSetup-SSM-CollectInventory-` 开头的关联。
1. **删除 Quick Setup 配置**：
+ 转至 Systems Manager 控制台中的 Quick Setup。
+ 查找清单收集配置。
+ 删除 Quick Setup 配置（这将移除已关联的清单关联）。
**注意**
无需手动删除通过 Quick Setup 创建的关联。
1. **验证关联是否运行**：删除 Quick Setup 配置后，显式清单关联应该已成功开始运行。
**如果您要修改现有行为：**
+ 要查看现有所有清单关联，请在 Systems Manager 控制台中选择 **State Manager**，然后找到使用 `AWS-GatherSoftwareInventory` SSM 文档的关联。
+ 请谨记，每个托管节点一次只能有一个活动的清单关联。
**重要**
当为跳过的节点分配的（更高优先级）清单关联运行时，仍会从跳过的节点收集清单数据。
Quick Setup 清单关联优先于其他所有类型，即使是具有显式目标的类型。
当任何关联被更高优先级的关联覆盖时，无论关联类型如何，都会显示详细的状态消息 `OverriddenByExplicitInventoryAssociation`。
## 失败
如果某个节点的清单关联状态显示 **Failed**（失败），则意味着节点上分配了多个清单关联。一个节点一次只能分配一个清单关联。清单关联使用 `AWS-GatherSoftwareInventory` AWS Systems Manager 文档（SSM 文档）。可以使用 AWS Command Line Interface (AWS CLI) 运行以下命令来查看节点的关联列表。
```
aws ssm describe-instance-associations-status --instance-id instance-ID
```
## Amazon EC2 实例的库存合规性失败
如果为 Amazon Elastic Compute Cloud (Amazon EC2) 实例分配多个库存关联，则该实例的库存合规性可能会失败。
要解决此问题，请删除分配给实例的一个或多个库存关联。有关更多信息，请参阅[删除关联](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-state-manager-delete-association.html)。
**注意**
如果您为一个托管式节点创建多个清单关联，请注意以下行为：
可为每个节点分配一个以*所有*节点为目标的清单关联 (--targets "Key=InstanceIds,Values=\$1")。
还可以为每个节点分配一个特定关联，该关联使用标签键-值对或 AWS 资源组。
如果为某个节点分配了多个清单关联，则对于尚未运行的关联，状态将显示为 *Skipped*（已跳过）。最近运行的关联将显示清单关联的实际状态。
如果为某个节点分配了多个清单关联，并且每个关联都使用标签键 - 值对，则这些清单关联将因标签冲突而无法在该节点上运行。关联仍会在没有标签键 - 值冲突的节点上运行。
## S3 存储桶对象包含旧数据
清单关联成功并发现新数据后，Amazon S3 存储桶对象中的数据将会更新。关联运行但失败时，每个节点的 Amazon S3 存储桶对象都会更新，但在这种情况下，对象内的数据不会更新。只有当关联成功运行时，Amazon S3 存储桶对象内的数据才会更新。清单关联失败时，将在 Amazon S3 存储桶对象中看到旧数据。
# AWS Systems Manager Patch Manager
Patch Manager是 AWS Systems Manager 中的一项工具，可使用安全相关更新及其他类型的更新自动执行修补托管式节点的过程。
**注意**
Systems Manager 为Quick Setup（AWS Systems Manager 中的一项工具）中的*补丁策略*提供支持。建议使用补丁策略来配置修补操作。使用单一补丁策略配置，您可以为贵组织中所有区域的所有账户定义修补、仅为所选的账户和区域定义修补，或为单个账户区域对定义修补。有关更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
您可以使用 Patch Manager 来应用操作系统和应用程序的补丁。（在 Windows Server 上，应用程序支持仅限于更新 Microsoft 发布的应用程序。） 您可以使用 Patch Manager 在 Windows 节点上安装 Service Pack，并在 Linux 节点上执行次要版本升级。可以按操作系统类型对 Amazon Elastic Compute Cloud（Amazon EC2）实例、边缘设备或本地服务器和虚拟机（VM）的实例集进行修补。这包括多个操作系统的支持版本，如 [Patch Manager 先决条件](patch-manager-prerequisites.md)中所列。您可以扫描实例以仅查看缺失补丁的报告，也可以扫描并自动安装所有缺失的补丁。要开始使用 Patch Manager，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/patch-manager)。在导航窗格中，请选择 **Patch Manager**。
在 Patch Manager 中提供补丁之前，AWS 不会测试这些补丁。此外，Patch Manager 不支持升级操作系统的主要版本，例如，将 Windows Server 2016 升级到 Windows Server 2019，或将 Red Hat Enterprise Linux（RHEL）7.0 升级到 RHEL 8.0。
对于报告修补程序严重性级别的基于 Linux 的操作系统类型，Patch Manager 将软件发布者报告的严重性级别用于更新通知或单个修补程序。Patch Manager 不会从第三方来源（例如[常见漏洞评分系统](https://www.first.org/cvss/) (CVSS)），或者[国家漏洞数据库](https://nvd.nist.gov/vuln) (NVD) 发布的指标中获取严重性级别。
## 我的组织如何从 Patch Manager 获益？
Patch Manager 会使用安全相关更新及其他类型的更新自动执行修补托管式节点的过程。此功能有多个重要的好处：
+ **集中控制修补**：使用补丁策略，您可以为组织中所有区域的所有账户、特定账户和区域或者单个账户区域对设置定期修补操作。
+ **灵活的修补操作**：您可以选择通过扫描实例来仅查看缺失的补丁报告，也可以扫描并自动安装所有缺失的补丁。
+ **全面的合规性报告**：扫描操作完成后，您可以查看有关哪些托管式节点的补丁安装不合规以及缺失哪些补丁的详细信息。
+ **跨平台支持**：Patch Manager 支持多种操作系统，包括各种 Linux 发行版、macOS 和 Windows Server。
+ **自定义补丁基准**：您可以通过自定义补丁基准来指定批准安装的补丁，从而定义组织的补丁合规性要求。
+ **与其他 AWS 服务集成**：Patch Manager 可与 AWS Organizations、AWS Security Hub CSPM、AWS CloudTrail 和 AWS Config 集成，从而加强管理和安全性。
+ **确定性升级**：通过提供 Amazon Linux 2023 等操作系统的多版本存储库，支持确定性升级要求。
## 谁应该使用 Patch Manager？
Patch Manager 适合以下人员使用：
+ 需要在跨托管式节点实例集保持补丁合规性的 IT 管理员
+ 需要清晰了解整个基础设施环境中补丁合规状态的运营经理
+ 需要大规模实施自动化修补解决方案的云架构师
+ 需要将补丁安装功能集成到运营工作流的 DevOps 工程师
+ 部署了多账户/多区域环境并且需要集中式补丁管理的组织
+ 任何负责维护 AWS 托管式节点、边缘设备、本地服务器和虚拟机安全状况和运行状况的人员
## Patch Manager 的主要功能是什么？
Patch Manager 具有多个重要的功能：
+ **补丁策略**：通过与 AWS Organizations 集成，使用单个策略来配置跨多个 AWS 账户和区域的修补操作。
+ **自定义补丁基准**：定义在补丁发布后几天内自动批准补丁的规则，以及已批准和已拒绝的补丁列表。
+ **多种修补方法**：根据自己的具体需求选择补丁策略、维护时段或按需“立即修补”操作。
+ **合规性报告**：生成有关补丁合规状态的详细报告，并且可将报告以 CSV 格式发送到 Amazon S3 存储桶。
+ **跨平台支持**：可跨 Windows Server、多种 Linux 发行版和 macOS 修补操作系统和应用程序。
+ **灵活计划**：使用自定义 CRON 或 Rate 表达式设置不同的扫描和补丁安装计划。
+ **生命周期挂钩**：使用 Systems Manager 文档在修补操作之前和之后运行自定义脚本。
+ **侧重安全**：默认情况下，Patch Manager 侧重于安全相关更新，而不是安装所有可用补丁。
+ **速率控制**：为修补操作配置并发和错误阈值，从而尽可能减少对运营的影响。
## Patch Manager中的合规性是什么？
AWS、操作系统 (OS) 供应商或安全咨询公司等第三方未定义 Systems Manager 实例集中托管节点的*补丁合规性*构成要素的基准测试。
相反，您可以在*补丁基准*中定义补丁合规性对于您的组织或账户中的托管节点意味着什么。补丁基准是一种配置，它指定必须在托管节点上安装哪些补丁的规则。当托管节点的所有补丁都符合您在补丁基准中指定的批准标准时，该节点即符合补丁要求。
请注意，*符合*补丁基准并不意味着托管节点一定是*安全*的。“合规”意味着补丁基准定义的*可用*且*已批准*的补丁已安装在节点上。托管节点的整体安全性由Patch Manager范围之外的许多因素决定。有关更多信息，请参阅 [AWS Systems Manager 中的安全性](security.md)。
每个补丁基准都是针对特定受支持的操作系统 (OS) 类型的配置，例如 Red Hat Enterprise Linux (RHEL)、macOS 或 Windows Server。补丁基准可以为所有受支持的操作系统版本定义修补规则，或者也可以仅限于您指定的版本（例如 RHEL 7.8 和 RHEL 9.3）。
在补丁基准中，您可以指定批准安装特定类别和严重级别的所有补丁。例如，您可以包括归类为 `Security` 的所有补丁，但排除其他补丁（例如 `Bugfix` 或 `Enhancement`）。并且，您可以包括严重性为 `Critical` 的所有补丁，但排除其他补丁（例如 `Important` 和 `Moderate`）。
您还可以通过将补丁 ID 添加到要批准或拒绝的特定补丁列表中，在补丁基准中明确定义补丁，例如 Windows Server 的 `KB2736693` 或 Amazon Linux 2023 (AL2023) 的 `dbus.x86_64:1:1.12.28-1.amzn2023.0.1`。您可以选择指定补丁可用后等待修补的特定天数。对于 Linux 和 macOS，您可以选择指定合规性外部补丁列表（安装覆盖列表），而不是补丁基准规则定义的列表。
运行修补操作时，Patch Manager会将当前应用于托管节点的补丁与应根据补丁基准中设置的规则或安装覆盖列表应用的补丁进行比较。您可以选择让 Patch Manager 只显示缺失补丁的报告（`Scan` 操作），也可以选择让 Patch Manager 自动安装它发现的托管节点中缺失的所有补丁（`Scan and install` 操作）。
**注意**
补丁合规性数据代表最近一次成功修补操作的时间点快照。每个合规性报告都包含一个捕获时间，用于标识合规性状态的计算时间。在查看合规性数据时，请考虑捕获时间以确定操作是否按预期执行。
Patch Manager提供了可用于修补操作的预定义补丁基准；但是，这些预定义的配置仅作为示例提供，而不是推荐的最佳实践。我们建议您创建自己的自定义补丁基准，以便更好地控制您的实例集的补丁合规性构成要素。
有关补丁基准的更多信息，请参阅以下主题：
+ [预定义和自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md)
+ [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)
+ [查看 AWS 预定义补丁基准](patch-manager-view-predefined-patch-baselines.md)
+ [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)
+ [使用补丁合规性报告](patch-manager-compliance-reports.md)
## 主要组件
在开始使用Patch Manager工具之前，您应该熟悉该工具的修补操作的一些主要组件和功能。
**补丁基准**
Patch Manager 使用*补丁基准*，该基准包含用于在补丁发布几天内自动批准补丁的规则以及一系列已批准和已拒绝的补丁。运行修补操作时，Patch Manager 会将当前应用于托管节点的补丁与应根据补丁基准中设置的规则应用的补丁进行比较。您可以选择让 Patch Manager 只显示缺失补丁的报告（`Scan` 操作），也可以选择让 Patch Manager 自动安装它发现的托管节点中缺失的所有补丁（`Scan and install` 操作）。
**修补操作方法**
Patch Manager 目前提供运行 `Scan` 和 `Scan and install` 操作的四种方法：
+ **（推荐）在 Quick Setup 中配置的补丁策略**：基于与 AWS Organizations 的集成，单个补丁策略可以定义整个组织的修补计划和补丁基准（包括多个 AWS 账户 和这些账户操作所在的 AWS 区域）。补丁策略也可以仅针对组织中的某些组织单位（OU）。您可以使用单个补丁策略按不同的计划进行扫描安装。有关更多信息，请参阅[使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)和[Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
+ **在 Quick Setup 中配置的主机管理选项**：与 AWS Organizations 的集成还支持主机管理配置，从而可以对整个组织运行修补操作。但是，此选项仅限于使用当前默认补丁基准扫描缺失的补丁并在合规性报告中提供结果。此操作方法无法安装补丁。有关更多信息，请参阅 [使用 Quick Setup 设置 Amazon EC2 主机管理](quick-setup-host-management.md)。
+ **运行补丁 `Scan` 或 `Install` 任务的维护时段**：可以在 Systems Manager 的 Maintenance Windows 工具中设置维护时段，将其配置为按照您定义的计划运行不同类型的任务。Run Command 类型任务可用于运行 `Scan` 或 `Scan and install` 任务（用于您选择的一组托管节点）。每个维护时段任务只能针对单一 AWS 账户-AWS 区域 对中的托管节点。有关更多信息，请参阅 [教程：使用控制台创建修补的维护时段](maintenance-window-tutorial-patching.md)。
+ **Patch Manager 中的按需**立即修补**操作** – 使用**立即修补**选项，可以在需要尽快修补托管式节点时，绕过计划设置。使用 **Patch now**（立即修补），您可以指定是运行 `Scan` 还是 `Scan and install` 操作，以及要在哪些托管节点上运行该操作。您还可以选择在修补操作期间将 Systems Manager 文档（SSM 文档）作为生命周期挂钩运行。每个 **Patch now**（立即修补）操作只能针对单一 AWS 账户-AWS 区域 对中的托管节点。有关更多信息，请参阅 [按需修补托管式节点](patch-manager-patch-now-on-demand.md)。
**合规性报告**
`Scan` 操作完成后，可以使用 Systems Manager 控制台查看相关信息，了解哪些托管节点不满足补丁合规性以及每个节点缺少哪些补丁。也可以生成 .csv 格式的补丁合规性报告，发送到您选择的 Amazon Simple Storage Service（Amazon S3）存储桶。您可以生成一次性报告，也可以生成定期报告。对于单个托管式节点，报告包含节点所有补丁的详细信息。对于所有托管式节点的报告，仅提供缺少多少补丁的摘要。生成报告后，您可以使用 Amazon Quick 等工具导入和分析数据。有关更多信息，请参阅 [使用补丁合规性报告](patch-manager-compliance-reports.md)。
**注意**
通过使用补丁策略生成的合规性项的执行类型为 `PatchPolicy`。补丁策略操作中未生成的合规项的执行类型为 `Command`。
**集成**
Patch Manager 与以下其他 AWS 服务 服务集成在一起：
+ **AWS Identity and Access Management（IAM）**：使用 IAM 控制哪些用户、群组和角色有权访问 Patch Manager 操作。有关更多信息，请参阅 [AWS Systems Manager 如何与 IAM 协同工作](security_iam_service-with-iam.md) 和[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
+ **AWS CloudTrail**：使用 CloudTrail 记录由用户、角色或群组发起的修补操作事件历史记录以供审核。有关更多信息，请参阅 [使用 AWS CloudTrail 记录 AWS Systems Manager API 调用](monitoring-cloudtrail-logs.md)。
+ **AWS Security Hub CSPM**：可将来自 Patch Manager 的补丁合规性数据发送到 AWS Security Hub CSPM。Security Hub CSPM 能让您全面了解高优先级安全警报和合规性状态。它还监控您的实例集的修补状态。有关更多信息，请参阅 [将 Patch Manager 与 AWS Security Hub CSPM 集成](patch-manager-security-hub-integration.md)。
+ **AWS Config**：在 AWS Config 中设置录制以在 Patch Manager 控制面板中查看 Amazon EC2 实例管理数据。有关更多信息，请参阅 [查看补丁程序控制面板摘要](patch-manager-view-dashboard-summaries.md)。
**Topics**
+ [我的组织如何从 Patch Manager 获益？](#how-can-patch-manager-benefit-my-organization)
+ [谁应该使用 Patch Manager？](#who-should-use-patch-manager)
+ [Patch Manager 的主要功能是什么？](#what-are-the-main-features-of-patch-manager)
+ [Patch Manager中的合规性是什么？](#patch-manager-definition-of-compliance)
+ [主要组件](#primary-components)
+ [Quick Setup 中的补丁策略配置](patch-manager-policies.md)
+ [Patch Manager 先决条件](patch-manager-prerequisites.md)
+ [Patch Manager 操作是如何工作的](patch-manager-patching-operations.md)
+ [适用于修补托管式节点的 SSM 命令文档](patch-manager-ssm-documents.md)
+ [补丁基准](patch-manager-patch-baselines.md)
+ [在 Amazon Linux 2 托管式节点上使用 Kernel Live Patching](patch-manager-kernel-live-patching.md)
+ [使用控制台处理 Patch Manager 资源和合规性](patch-manager-console.md)
+ [使用 AWS CLI 处理 Patch Manager 资源使用](patch-manager-cli-commands.md)
+ [AWS Systems Manager Patch Manager 教程](patch-manager-tutorials.md)
+ [排除 Patch Manager 问题](patch-manager-troubleshooting.md)
# Quick Setup 中的补丁策略配置
AWS 建议使用*补丁策略*为组织和 AWS 账户配置补丁。补丁政策于 2022 年 12 月在Patch Manager中推出。
补丁策略是您使用Quick Setup（AWS Systems Manager 中的一项工具）设置的一项配置。与以前配置修补的方法相比，补丁策略可以对修补操作进行更广泛、更集中的控制。补丁策略可用于 [Patch Manager 支持的所有操作系统](patch-manager-prerequisites.md#pm-prereqs)，包括支持的 Linux、macOS和 Windows Server 版本。有关创建补丁策略的说明，请参阅 [使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)。
## 补丁策略的主要功能
与其使用其他方法修补您的节点，不如使用补丁策略来利用以下主要功能：
+ **单一设置**：若使用维护时段或 State Manager 关联设置修补操作，可能需要在 Systems Manager 控制台的不同部分执行多项任务。使用补丁策略，可以在单个向导中设置所有修补操作。
+ **多账户/多区域支持**：使用 Patch Manager 中的维护时段、State Manager关联或 **Patch now**（立即修补）功能，您只能针对一个 AWS 账户 与 AWS 区域 对中的托管节点。如果您使用多个账户和多个区域，则设置和维护任务可能需要大量时间，因为您必须在每个账户—区域对中执行设置任务。但是，如果您使用 AWS Organizations，则可以在您的所有 AWS 账户 的所有 AWS 区域 设置一个应用于所有托管节点的补丁策略。或者，您也可以选择把补丁策略只应用于您选择的账户和区域中的某些组织单位 (OU)。还可以选择把补丁策略应用于单个本地账户。
+ **组织层面的安装支持**：Quick Setup 中的现有主机管理配置选项支持对托管节点进行每日扫描，以确定是否满足补丁合规性。但是，要在预定时间完成此扫描，且只生成补丁合规信息。不执行补丁安装。使用补丁策略，您可以指定不同的扫描和安装计划。您还可使用自定义的 CRON 或 Rate 表达式来选择这些操作的频率和时间。例如，您可以每天扫描缺失的补丁，以便为您提供定期更新的合规信息。但是，为了避免不必要的停机，您的安装计划可能仅为每周一次。
+ **简化的补丁基准选择**：补丁策略仍包含补丁基准，补丁基准的配置方式不变。但是，在创建或更新补丁策略时，可以在单个列表中为每种操作系统（OS）类型选择要使用的 AWS 托管或自定义基准。无需在单独的任务中为每种操作系统类型指定默认基准。
**注意**
在运行基于补丁策略的修补操作时，他们使用的是 `AWS-RunPatchBaseline` SSM 文档。有关更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
**相关信息**
[使用 Systems Manager Quick Setup 在整个 AWS 组织中集中部署修补操作](https://aws.amazon.com/blogs/mt/centrally-deploy-patching-operations-across-your-aws-organization-using-systems-manager-quick-setup/)（AWS 云运营和迁移博客）
## 与补丁策略的其他区别
相比以前配置修补的方法，使用补丁策略时需要注意一些其他差异：
+ **无需补丁组**：在以前的修补操作中，您可以将多个节点标记为属于一个补丁组，然后指定用于该补丁组的补丁基准。如果没有定义补丁组，Patch Manager 使用操作系统类型当前默认的补丁基准修补实例。使用补丁策略则不再需要设置和维护补丁组。
**注意**
对于在 2022 年 12 月 22 日发布补丁策略支持之前尚未使用补丁组的账户-区域对，控制台不支持补丁组功能。补丁组功能在此日期之前开始使用补丁组的账户区域对中仍然可用。
+ **已删除“配置修补”页面**：在补丁策略发布之前，您可以在 **Configure patching**（配置修补）页面上指定要修补哪些节点的默认值、修补计划和修补操作。此页面已从 Patch Manager 中删除。现在已在补丁策略中指定这些选项。
+ **不支持“立即修补”**：按需修补节点的能力仍然仅限于每次一个 AWS 账户 - AWS 区域 对。有关信息，请参阅[按需修补托管式节点](patch-manager-patch-now-on-demand.md)。
+ **补丁策略和合规信息**：在根据修补策略配置扫描托管节点是否合规时，系统将为您提供合规数据。您可以像使用其他合规性扫描方法一样查看并处理数据。尽管您可以为整个组织或多个组织单位设置补丁策略，但会单独报告每个 AWS 账户 - AWS 区域 对的合规信息。有关更多信息，请参阅 [使用补丁合规性报告](patch-manager-compliance-reports.md)。
+ **关联合规性状态和补丁策略** – Quick Setup 补丁策略下的托管式节点的修补状态与该节点的 State Manager 关联执行状态相匹配。如果关联执行状态为 `Compliant`，则还会将托管式节点的修补状态标记为 `Compliant`。如果关联执行状态为 `Non-Compliant`，则还会将托管式节点的修补状态标记为 `Non-Compliant`。
## 补丁策略支持的 AWS 区域
以下区域当前支持 Quick Setup 中的补丁策略配置：
+ 美国东部（俄亥俄州）(us-east-2)
+ 美国东部（弗吉尼亚州北部）(us-east-1)
+ 美国西部（北加利福尼亚）(us-west-1)
+ 美国西部（俄勒冈州）(us-west-2)
+ 亚太地区（孟买）(ap-south-1)
+ 亚太地区（首尔）(ap-northeast-2)
+ 亚太地区（新加坡）(ap-southeast-1)
+ 亚太地区（悉尼）(ap-southeast-2)
+ 亚太地区（东京）(ap-northeast-1)
+ 加拿大（中部）(ca-central-1)
+ 欧洲地区（法兰克福）(eu-central-1)
+ 欧洲地区（爱尔兰）(eu-west-1)
+ 欧洲地区（伦敦）(eu-west-2)
+ 欧洲地区（巴黎）（eu-west-3）
+ 欧洲地区（斯德哥尔摩）(eu-north-1)
+ 南美洲（圣保罗）（sa-east-1）
# Patch Manager 先决条件
使用Patch Manager（AWS Systems Manager 中的一项工具）之前，请确保自己已满足必要的先决条件。
**Topics**
+ [SSM Agent 版本](#agent-versions)
+ [Python 版本](#python-version)
+ [其他程序包要求](#additional-package-requirements)
+ [与补丁源的连接](#source-connectivity)
+ [S3 端点访问](#s3-endpoint-access)
+ [在本地安装补丁的权限](#local-installation-permissions)
+ [Patch Manager 支持的操作系统](#supported-os)
## SSM Agent 版本
SSM Agent 版本 2.0.834.0 或更高版本在要用 Patch Manager 管理的托管式节点上运行。
**注意**
如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
## Python 版本
对于 macOS 以及大多数 Linux 操作系统（OS），Patch Manager 目前支持 Python 版本 2.6 - 3.12。AlmaLinux、Debian Server 和 Ubuntu Server 操作系统需要使用受支持版本的 Python 3（3.0 - 3.12）。
## 其他程序包要求
对于基于 DNF 的操作系统，可能需要使用 `zstd`、`xz` 和 `unzip` 实用程序来解压缩存储库信息和补丁文件。基于 DNF 的操作系统包括 Amazon Linux 2023、Red Hat Enterprise Linux 8 及更高版本、Oracle Linux 8 及更高版本、Rocky Linux、AlmaLinux 以及 CentOS 8 及更高版本。如果您看到类似于 `No such file or directory: b'zstd'`、`No such file or directory: b'unxz'` 的错误或由于缺失 `unzip` 而导致修补失败，则需要安装这些实用程序。`zstd`、`xz` 和 `unzip` 可以通过运行以下命令进行安装：
```
dnf install zstd xz unzip
```
## 与补丁源的连接
如果您的托管式节点没有直接连接到互联网，并且您正在通过某个 VPC 端点使用 Amazon Virtual Private Cloud（Amazon VPC），则必须确保这些节点能够访问源补丁存储库（存储库）。在 Linux 节点上，通常是从节点上配置的远程存储库下载补丁更新。因此，节点必须能够连接到远程存储库，才能执行修补。有关更多信息，请参阅 [如何选择安全性补丁](patch-manager-selecting-patches.md)。
在仅支持 IPv6 的环境中运行的节点上进行修补时，请确保该节点与补丁源有连接。您可以检查修补执行的 Run Command 输出，以检查有关无法访问的存储库的警告。对于基于 DNF 的操作系统，如果 `/etc/dnf/dnf.conf` 下的 `skip_if_unavailable` 选项设置为 `True`，则可以配置在修补期间跳过不可用的存储库。基于 DNF 的操作系统包括 Amazon Linux 2023、Red Hat Enterprise Linux 8 及更高版本、Oracle Linux 8 及更高版本、Rocky Linux、AlmaLinux 以及 CentOS 8 及更高版本。在 Amazon Linux 2023 上，`skip_if_unavailable` 选项默认设置为 `True`。
**CentOS Stream：启用 `EnableNonSecurity` 标志**
CentOS Stream 节点将 DNF 用作软件包管理器，其使用更新通知概念。更新通知只是修复特定问题的软件包的集合。
但是，CentOS Stream 默认存储库不配置更新通知。这意味着 Patch Manager 不检测默认 CentOS Stream 存储库上的软件包。要允许 Patch Manager 处理更新通知中未包含的软件包，您必须启用补丁基准规则中的 `EnableNonSecurity` 标记。
**Windows Server：确保连接到 Windows 更新目录或 Windows 服务器更新服务（WSUS）**
Windows Server 托管式节点必须能够连接到 Windows 更新目录或 Windows Server Update Service (WSUS)。确认您的节点通过互联网网关、NAT 网关或 NAT 实例已经连接到 [Microsoft 更新目录](https://www.catalog.update.microsoft.com/home.aspx)。如果您使用的是 WSUS，请确认该节点已连接到环境中的 WSUS 服务器。有关更多信息，请参阅 [问题：托管式节点无法访问 Windows 更新目录或 WSUS](patch-manager-troubleshooting.md#patch-manager-troubleshooting-instance-access)。
## S3 端点访问
无论托管式节点是在私有网络还是公有网络中运行，如果无法访问所需的 AWS 托管式 Amazon Simple Storage Service（Amazon S3）存储桶，则修补操作会失败。有关托管式节点必须能够访问的 S3 存储桶的信息，请参阅 [SSM Agent 与 AWS 托管 S3 存储桶进行通信](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions) 和 [使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。
## 在本地安装补丁的权限
在 Windows Server 和 Linux 操作系统上，Patch Manager分别假定使用管理员和根用户账户来安装补丁。
然而，在 macOS 上，对于 Brew 和 Brew Cask，Homebrew 不支持在根用户账户下运行其命令。因此，Patch Manager 以 Homebrew 目录的所有者或属于 Homebrew 目录的所有者组的有效用户身份查询并运行 Homebrew 命令。因此，为了安装补丁，`homebrew` 目录的所有者还需要 `/usr/local` 目录的递归所有者权限。
**提示**
以下命令可为指定的用户提供此权限：
```
sudo chown -R $USER:admin /usr/local
```
## Patch Manager 支持的操作系统
Patch Manager 工具可能不支持其他 Systems Manager 工具支持的所有相同的操作系统版本。（有关 Systems Manager 所支持的操作系统的完整列表，请参阅 [Systems Manager 支持的操作系统](operating-systems-and-machine-types.md#prereqs-operating-systems)。） 因此，请确保要使用 Patch Manager 的托管式节点在下表所列操作系统之一中运行。
**注意**
Patch Manager 依靠在托管式节点上配置的补丁存储库（例如 Windows 的 Windows 更新目录和 Windows Server Update Services）来检索要安装的可用补丁。因此，对于生命周期终止（EOL）操作系统版本，如果没有新的更新可用，则 Patch Manager 可能无法报告新的更新。这可能是因为 Linux 发行版维护者、Microsoft 或 Apple 没有发布任何新更新，或者因为托管式节点没有访问新更新的适当许可。
强烈建议避免使用生命周期 (EOL) 已终止的操作系统版本。包括 AWS 在内的操作系统供应商通常不为生命周期已终止的版本提供安全补丁或其他更新。继续使用生命周期终止的操作系统会大大增加无法应用升级（包括安全修复）以及其他操作问题的风险。AWS 不会在生命周期已终止的操作系统版本上测试 Systems Manager 功能。
Patch Manager 报告托管式节点上可用补丁的合规性状态。因此，如果实例运行的是 EOL 操作系统，但没有可用的更新，则 Patch Manager 可能会将该节点报告为“合规”，具体取决于为修补操作配置的补丁基准。
| 操作系统 | Details |
| --- | --- |
| Linux | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-prerequisites.html) |
| macOS | *macOS 仅支持 Amazon EC2 实例。* 13.0–13.7（Ventura） 14*.x* (Sonoma) 15*.x* (Sequoia) macOS 操作系统更新 Patch Manager 不支持 macOS 操作系统（OS）更新或升级，例如从 13.1 到 13.2。要在 macOS 上执行操作系统版本更新，我们建议使用 Apple 的内置操作系统升级机制。有关更多信息，请参阅 Apple Developer 文档网站上的 [Device Management](https://developer.apple.com/documentation/devicemanagement)。 Homebrew 支持 Patch Manager 要求将开源软件包管理系统 Homebrew 安装在以下任一默认安装位置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-prerequisites.html) 如果未安装 Homebrew，则使用 Patch Manager 执行的修补操作将无法正常运行。 区域支持 并非所有 AWS 区域 都支持 macOS。有关对适用于 macOS 的 Amazon EC2 支持的一般信息，请参阅《Amazon EC2 用户指南》**中的 [Amazon EC2 Mac 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html)。 macOS 边缘设备 macOS 不支持适用于 AWS IoT Greengrass 核心设备的 SSM Agent。您不能使用 Patch Manager 修补 macOS 边缘设备。 |
| Windows | Windows Server 2012 至 Windows Server 2025，包括 R2 版本。 Windows 10 不支持适用于 AWS IoT Greengrass 核心设备的 SSM Agent。您不能使用 Patch Manager 修补 Windows 10 边缘设备。 Windows Server 2012 和 2012 R2 支持 Windows Server 2012 和 2012 R2 支持已于 2023 年 10 月 10 日结束。要将 Patch Manager 与这些版本一起使用，还建议使用 Microsoft 的扩展安全更新（ESU）。有关更多信息，请参阅 Microsoft 网站上的 [Windows Server 2012 和 2012 R2 即将终止支持](https://learn.microsoft.com/en-us/lifecycle/announcements/windows-server-2012-r2-end-of-support)。 |
# Patch Manager 操作是如何工作的
本节介绍一些技术细节，说明Patch Manager（AWS Systems Manager 中的一项工具）如何确定安装哪些补丁，以及如何在每个受支持的操作系统上安装这些补丁。对于 Linux 操作系统，其还提供有关在自定义补丁基准中为补丁指定源存储库（而非托管式节点上配置的默认源存储库）的信息。此节还提供了有关补丁基准规则在不同的 Linux 操作系统分发版上的工作原理的详细信息。
**注意**
无论您使用哪种配置方法或类型进行修补操作，以下主题中的信息都适用：
Quick Setup 中配置的补丁策略
Quick Setup 中配置的主机管理选项
运行补丁 `Scan` 或 `Install` 任务的维护时段
按需 **Patch now**（立即修补）操作
**Topics**
+ [如何计算软件包发布日期和更新日期](patch-manager-release-dates.md)
+ [如何选择安全性补丁](patch-manager-selecting-patches.md)
+ [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)
+ [如何安装补丁](patch-manager-installing-patches.md)
+ [补丁基准规则在基于 Linux 的系统上的工作原理](patch-manager-linux-rules.md)
+ [Linux 和 Windows Server 之间的补丁操作差异](patch-manager-windows-and-linux-differences.md)
# 如何计算软件包发布日期和更新日期
**重要**
本页面上的信息适用于 Amazon Elastic Compute Cloud（Amazon EC2）实例的 Amazon Linux 2 和 Amazon Linux 2023 操作系统（OS）。这些 OS 类型的软件包由 Amazon Web Services 创建和维护。其他操作系统的软件包和存储库的发布日期和更新日期的计算方式受其制造商管理方式的影响。对于除 Amazon Linux 2 和 Amazon Linux 2023 之外的操作系统，如 Red Hat Enterprise Linux，请参阅制造商的文档，以了解有关如何更新和维护其软件包的信息。
在您创建的[自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md#patch-manager-baselines-custom)设置中，对于大多数操作系统类型，您可以指定补丁在特定天数后自动批准安装。AWS 提供了几个预定义的补丁基准，其中包括 7 天的自动批准日期。
*自动批准延迟*是发布补丁后到自动批准补丁用于修补前等待的天数。例如，可以使用 `CriticalUpdates` 分类创建规则，并将其配置为自动批准延迟为 7 天。此时，发布日期或最后更新日期为 7 月 7 日的新关键补丁将在 7 月 14 日自动获得批准。
为了避免在 Amazon Linux 2 和 Amazon Linux 2023 上出现自动批准延迟的意外结果，了解其发布日期和更新日期的计算方式至关重要。
**注意**
如果 Amazon Linux 2 或 Amazon Linux 2023 存储库未提供软件包的发布日期信息，则Patch Manager会将软件包的构建时间用作自动批准日期规范的日期。如果无法确定软件包的构建时间，Patch Manager 会使用默认日期 1970 年 1 月 1 日。这将导致 Patch Manager 绕过补丁基准（配置为批准 1970 年 1 月 1 日之后任一日期发布的补丁）中的所有自动批准日期规范。
在大多数情况下，安装补丁之前的自动批准等待时间根据 `updateinfo.xml` 中的 `Updated Date` 值，而不是 `Release Date` 值计算。以下是有关这些日期计算的重要细节：
+ `Release Date` 是指*通知*发布的日期。但这并不意味着该软件包在相关存储库中可用。
+ `Update Date` 是指通知最后更新的日期。通知的更新可以指文本更新或描述更新这样的小更新。但这并不意味着该软件包在该日期发布，也不意味着在相关存储库中可用。
这意味着如果软件包的 `Update Date` 值为 7 月 7 日，可能直到（例如）7 月 13 日才能安装。假设在这种情况下，如果补丁基准指定的自动批准延迟为 7 天，则会在 7 月 14 日的 `Install` 操作中运行。因为 `Update Date` 值是运行日期前 7 天，所以软件包中的补丁和更新将在 7 月 14 日安装。即使自软件包可用于实际安装以来仅过了 1 天，安装仍会进行。
+ 包含操作系统或应用程序补丁的软件包在首次发布后可以更新多次。
+ 软件包可以发布到 AWS 托管存储库中，但如果以后发现它有问题，则可以回滚。
在某些补丁操作中，这些因素可能并不重要。例如，如果补丁基准配置为安装严重性的值为 `Low` 和 `Medium`，且分类为 `Recommended` 的补丁，则任何自动批准延迟都可能几乎不会对您的操作产生影响。
但是，如果关键或高严重性补丁的安装时间较为重要，您可能需要对补丁的安装时间进行更多的控制。执行此操作的建议方法是使用替代补丁源存储库，而不是默认存储库来执行托管节点上的补丁操作。
您可以在创建自定义补丁基准时指定备用补丁源存储库。在每个自定义补丁基准中，您可以为多达 20 个版本的受支持的 Linux 操作系统指定补丁源配置。有关更多信息，请参阅 [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。
# 如何选择安全性补丁
Patch Manager（AWS Systems Manager 中的一项工具）的主要设计意图在于在托管式节点上安装与安全性相关的操作系统更新。默认情况下，Patch Manager 并非安装所有可用的补丁，而只安装一小部分旨在提高安全性的补丁。
默认情况下，除非安装其他软件包更新需要替换，Patch Manager 不会将软件包存储库中标记为已过时软件包替换为任何具有不同名称的替换软件包。而对于更新软件包的命令，Patch Manager 仅会报告已安装但已过时的软件包并为其安装缺失的更新。这是因为替换已过时软件包通常需要卸载现有软件包并安装其替换软件包。替换已过时软件包可能会引入不在计划内的重大更改或额外功能。
这种行为与 YUM 和 DNF 的 `update-minimal` 命令一致，后者也侧重于安全更新而不是功能升级。有关更多信息，请参阅 [如何安装补丁](patch-manager-installing-patches.md)。
**注意**
当您在补丁基准规则中使用 `ApproveUntilDate` 参数或 `ApproveAfterDays` 参数时，Patch Manager会使用协调世界时 (UTC) 评估补丁发布日期。
例如，对于 `ApproveUntilDate`，如果您指定一个日期（例如 `2025-11-16`），则在 `2025-11-16T00:00:00Z` 到 `2025-11-16T23:59:59Z` 之间发布的补丁将获得批准。
请注意，托管节点上的本机软件包管理器显示的补丁发布日期可能因系统本地时区而异，但Patch Manager始终使用 UTC 时间进行审批计算。这确保了与官方安全公告网站上发布的补丁发布日期保持一致。
对于报告修补程序严重性级别的基于 Linux 的操作系统类型，Patch Manager 将软件发布商报告的严重性级别用于更新通知或单个修补程序。Patch Manager 不会从第三方来源（例如[常见漏洞评分系统](https://www.first.org/cvss/) (CVSS)），或者[国家漏洞数据库](https://nvd.nist.gov/vuln) (NVD) 发布的指标中获取严重性级别。
**注意**
在 Patch Manager 支持的所有基于 Linux 的系统中，您可以选择为托管式节点配置的不同源存储库，以便通常用于安装非安全性更新。有关信息，请参阅[如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。
请从以下选项卡中进行选择，了解 Patch Manager 如何为您的操作系统选择安全补丁。
------
#### [ Amazon Linux 2 and Amazon Linux 2023 ]
在 Amazon Linux 2 上处理预配置存储库的方式与在 Amazon Linux 2023 上不同。
在 Amazon Linux 2 上，Systems Manager 补丁基准服务使用托管节点上的预配置存储库。节点上通常有两个预配置存储库（存储库）：
**在 Amazon Linux 2 上**
+ **存储库 ID**：`amzn2-core/2/architecture`
**存储库名称**：`Amazon Linux 2 core repository`
+ **存储库 ID**：`amzn2extra-docker/2/architecture`
**存储库名称**：`Amazon Extras repo for docker`
**注意**
*架构*可以是 x86\$164 或（对于 Graviton 处理器）aarch64。
当您创建 Amazon Linux 2023（AL2023）实例时，它包含 AL2023 版本和您选择的特定 AMI 中可用的更新。AL2023 实例在启动时不会自动接收其他重大和重要的安全更新。相反，通过 AL2023 支持的默认开启的*版本化存储库功能进行确定性升级*，您可以根据满足您特定需求的计划应用更新。有关更多信息，请参阅《Amazon Linux 2023 User Guide》**中的 [Deterministic upgrades through versioned repositories](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html)。
在 AL2023 上，预配置的存储库如下所示：
+ **存储库 ID**：`amazonlinux`
**存储库名称**：Amazon Linux 2023 存储库
在 Amazon Linux 2023（预览版）上，预配置的存储库与程序包更新的*锁定版本*相关。AL2023 的新 Amazon Machine Images（AMIs）在发布后会锁定到特定版本。对于补丁更新，Patch Manager 会检索补丁更新存储库的最新锁定版本，然后根据该锁定版本的内容更新托管式节点上的程序包。
**软件包管理器**
Amazon Linux 2 托管节点使用 Yum 作为软件包管理器。Amazon Linux 2023 使用 DNF 作为软件包管理器。
两个程序包管理器都将*更新通知*概念作为名为 `updateinfo.xml` 的文件使用。更新通知只是修复特定问题的软件包的集合。Patch Manager 将更新通知中的所有软件包视为安全性软件包。单个软件包未分配分类或严重性级别。因此，Patch Manager 会向相关软件包分配更新通知属性。
**注意**
如果在**创建补丁基准**页面中选中了**包括非安全性更新**复选框，则未分配到 `updateinfo.xml` 文件中的软件包（或包含一个没有正确格式的分类、严重性和日期值的文件的软件包）可以包含在补丁的预筛选列表中。但是，为了应用补丁，补丁仍必须符合用户指定的补丁基准规则。
有关**包括非安全性更新**选项的更多信息，请参阅[如何安装补丁](patch-manager-installing-patches.md)和[补丁基准规则在基于 Linux 的系统上的工作原理](patch-manager-linux-rules.md)。
------
#### [ CentOS Stream ]
在 CentOS Stream 上，Systems Manager 补丁基准服务使用托管式节点上的预配置存储库（储存库）。以下列表提供了虚构 CentOS 9.2 的示例 Amazon Machine Image (AMI)：
+ **存储库 ID**：`example-centos-9.2-base`
**存储库名称**：`Example CentOS-9.2 - Base`
+ **存储库 ID**：`example-centos-9.2-extras`
**存储库名称**：`Example CentOS-9.2 - Extras`
+ **存储库 ID**：`example-centos-9.2-updates`
**存储库名称**：`Example CentOS-9.2 - Updates`
+ **存储库 ID**：`example-centos-9.x-examplerepo`
**存储库名称**：`Example CentOS-9.x – Example Repo Packages`
**注意**
所有更新都是从托管式节点上配置的远程存储库下载。因此，节点必须具有对 Internet 的出站访问权限才能连接到存储库，以便执行修补。
CentOS Stream 节点将 DNF 用作软件包管理器。软件包管理器使用更新通知概念。更新通知只是修复特定问题的软件包的集合。
但是，CentOS Stream 默认存储库不配置更新通知。这意味着 Patch Manager 不检测默认 CentOS Stream 存储库上的软件包。要允许 Patch Manager 处理更新通知中未包含的软件包，您必须启用补丁基准规则中的 `EnableNonSecurity` 标记。
**注意**
支持 CentOS Stream 更新通知。带有更新通知的存储库发布后即可供下载。
------
#### [ Debian 服务器 ]
在 Debian Server 上，Systems Manager 补丁基准服务使用实例上的预配置存储库（存储库）。这些预配置存储库用于提取可用软件包升级的更新列表。在这一点上，Systems Manager 的作用类似于 `sudo apt-get update` 命令。
然后，在 `debian-security codename` 存储库中筛选软件包。这就表示，在 Debian Server 的每个版本上，Patch Manager 仅识别属于该版本关联存储库一部分的升级，如下所示：
+ Debian Server 11：`debian-security bullseye`
+ Debian Server 12：`debian-security bookworm`
------
#### [ Oracle Linux ]
在 Oracle Linux 上，Systems Manager 补丁基准服务使用托管式节点上的预配置存储库（储存库）。节点上通常有两个预配置存储库。
**Oracle Linux 7**：
+ **存储库 ID**：`ol7_UEKR5/x86_64`
**存储库名称**：`Latest Unbreakable Enterprise Kernel Release 5 for Oracle Linux 7Server (x86_64)`
+ **存储库 ID**：`ol7_latest/x86_64`
**存储库名称**：`Oracle Linux 7Server Latest (x86_64)`
**Oracle Linux 8**：
+ **存储库 ID**：`ol8_baseos_latest`
**存储库名称**：`Oracle Linux 8 BaseOS Latest (x86_64)`
+ **存储库 ID**：`ol8_appstream`
**存储库名称**：`Oracle Linux 8 Application Stream (x86_64)`
+ **存储库 ID**：`ol8_UEKR6`
**存储库名称**：`Latest Unbreakable Enterprise Kernel Release 6 for Oracle Linux 8 (x86_64)`
**Oracle Linux 9**：
+ **存储库 ID**：`ol9_baseos_latest`
**存储库名称**：`Oracle Linux 9 BaseOS Latest (x86_64)`
+ **存储库 ID**：`ol9_appstream`
**存储库名称**：`Oracle Linux 9 Application Stream Packages(x86_64)`
+ **存储库 ID**：`ol9_UEKR7`
**存储库名称**：`Oracle Linux UEK Release 7 (x86_64)`
**注意**
所有更新都是从托管式节点上配置的远程存储库下载。因此，节点必须具有对 Internet 的出站访问权限才能连接到存储库，以便执行修补。
Oracle Linux 托管式节点将 Yum 用作软件包管理器，并且 Yum 将更新通知表现为名为 `updateinfo.xml` 的文件。更新通知只是修复特定问题的软件包的集合。单个软件包未分配分类或严重性级别。出于这个原因, Patch Manager 会向相关软件包分配更新通知属性，并根据补丁基准中指定的分类筛选器安装软件包。
**注意**
如果在**创建补丁基准**页面中选中了**包括非安全性更新**复选框，则未分配到 `updateinfo.xml` 文件中的软件包（或包含一个没有正确格式的分类、严重性和日期值的文件的软件包）可以包含在补丁的预筛选列表中。但是，为了应用补丁，补丁仍必须符合用户指定的补丁基准规则。
------
#### [ AlmaLinux, RHEL, and Rocky Linux ]
在 AlmaLinux、Red Hat Enterprise Linux 和 Rocky Linux 上，Systems Manager 补丁基准服务使用托管式节点上的预配置存储库（储存库）。节点上通常有三个预配置存储库。
所有更新都是从托管式节点上配置的远程存储库下载。因此，节点必须具有对 Internet 的出站访问权限才能连接到存储库，以便执行修补。
**注意**
如果在**创建补丁基准**页面中选中了**包括非安全性更新**复选框，则未分配到 `updateinfo.xml` 文件中的软件包（或包含一个没有正确格式的分类、严重性和日期值的文件的软件包）可以包含在补丁的预筛选列表中。但是，为了应用补丁，补丁仍必须符合用户指定的补丁基准规则。
Red Hat Enterprise Linux 7 托管式节点将 Yum 用作程序包管理器。AlmaLinux、Red Hat Enterprise Linux 8 和 Rocky Linux 托管式节点使用 DNF 作为程序包管理器。两个程序包管理器都将更新通知概念作为名为 `updateinfo.xml` 的文件使用。更新通知只是修复特定问题的软件包的集合。单个软件包未分配分类或严重性级别。出于这个原因, Patch Manager 会向相关软件包分配更新通知属性，并根据补丁基准中指定的分类筛选器安装软件包。
RHEL 7
以下存储库 ID 与 RHUI 2 相关联。RHUI 3 于 2019 年 12 月推出，并为 Yum 存储库 ID 引入了不同的命名方案。根据您从中创建托管式节点的 RHEL-7 AMI，您可能需要更新命令。有关更多信息，请参阅 *Red Hat 客户门户*上的 [Repository IDs for RHEL 7 in AWS Have Changed](https://access.redhat.com/articles/4599971)。
+ **存储库 ID**：`rhui-REGION-client-config-server-7/x86_64`
**存储库名称**：`Red Hat Update Infrastructure 2.0 Client Configuration Server 7`
+ **存储库 ID**：`rhui-REGION-rhel-server-releases/7Server/x86_64`
**存储库名称**：`Red Hat Enterprise Linux Server 7 (RPMs)`
+ **存储库 ID**：`rhui-REGION-rhel-server-rh-common/7Server/x86_64`
**存储库名称**：`Red Hat Enterprise Linux Server 7 RH Common (RPMs)`
AlmaLinux、8、RHEL 8 和 Rocky Linux 8
+ **存储库 ID**：`rhel-8-appstream-rhui-rpms`
**存储库名称**：`Red Hat Enterprise Linux 8 for x86_64 - AppStream from RHUI (RPMs)`
+ **存储库 ID**：`rhel-8-baseos-rhui-rpms`
**存储库名称**：`Red Hat Enterprise Linux 8 for x86_64 - BaseOS from RHUI (RPMs)`
+ **存储库 ID**：`rhui-client-config-server-8`
**存储库名称**：`Red Hat Update Infrastructure 3 Client Configuration Server 8`
AlmaLinux 9、RHEL 9 和 Rocky Linux 9
+ **存储库 ID**：`rhel-9-appstream-rhui-rpms`
**存储库名称**：`Red Hat Enterprise Linux 9 for x86_64 - AppStream from RHUI (RPMs)`
+ **存储库 ID**：`rhel-9-baseos-rhui-rpms`
**存储库名称**：`Red Hat Enterprise Linux 9 for x86_64 - BaseOS from RHUI (RPMs)`
+ **存储库 ID**：`rhui-client-config-server-9`
**存储库名称**：`Red Hat Enterprise Linux 9 Client Configuration`
------
#### [ SLES ]
在 SUSE Linux Enterprise Server (SLES) 托管式节点上，ZYPP 库从以下位置获取可用补丁的列表（软件包集合）：
+ 存储库的列表：`etc/zypp/repos.d/*`
+ 软件包信息：`/var/cache/zypp/raw/*`
SLES 托管式节点将 Zypper 用作软件包管理器，并且 Zypper 使用补丁的概念。补丁只是修复特定问题的程序包的集合。Patch Manager 处理补丁中所有引用为与安全性相关的软件包。因为没有为单个软件包提供分类或严重性，所以 Patch Manager 为软件包分配它们属于的补丁的属性。
------
#### [ Ubuntu Server ]
在 Ubuntu Server 上，Systems Manager 补丁基准服务使用托管式节点上的预配置存储库（储存库）。这些预配置存储库用于提取可用软件包升级的更新列表。在这一点上，Systems Manager 的作用类似于 `sudo apt-get update` 命令。
然后，将从 `codename-security` 存储库筛选软件包，其中的代号对应唯一的发行版本，例如 `trusty` 适用于 Ubuntu Server 14。Patch Manager 只识别包含在这些储存库的升级：
+ Ubuntu Server 16.04 LTS：`xenial-security`
+ Ubuntu Server 18.04 LTS：`bionic-security`
+ Ubuntu Server 20.04 LTS：`focal-security`
+ Ubuntu Server 22.04 LTS：`jammy-security`
+ Ubuntu Server 24.04 LTS (`noble-security`)
+ Ubuntu Server 25.04 (`plucky-security`)
------
#### [ Windows Server ]
在 Microsoft Windows 操作系统上，Patch Manager 检索 Microsoft 通过其发布至 Microsoft 更新的以及 Windows Server Update Services (WSUS) 自动获取的可用更新的列表。
**注意**
Patch Manager 仅为支持 Patch Manager 的 Windows Server 操作系统版本提供可用补丁。例如，Patch Manager 不能用于修补 Windows RT。
Patch Manager 持续监控每个 AWS 区域 中的新更新。每个区域每天至少刷新一次可用更新的列表。在处理来自 Microsoft 的补丁信息时，Patch Manager 会删除已被其补丁列表中的后续更新取代的更新。因此，Patch Manager 只显示最新更新，以供您安装。例如，如果 `KB4012214` 取代了 `KB3135456`，则 `KB4012214` 会显示为 Patch Manager 的更新。
同样，Patch Manager 仅可安装在修补操作期间托管节点上可用的补丁。默认情况下，Windows Server 2019 和 Windows Server 2022 会移除由较新更新所取代的更新。因此，如果您在 Windows Server 补丁基准中使用 `ApproveUntilDate` 参数，但 `ApproveUntilDate` 参数中选择的日期*早于*最新补丁发布的日期，则会出现以下情况：
+ 取代的补丁已从节点中删除，因此无法使用 Patch Manager 进行安装。
+ 节点上存在最新的替换补丁，但尚未批准按照 `ApproveUntilDate` 参数的指定日期进行安装。
这意味着托管节点在 Systems Manager 操作方面是合规的，即使可能未安装上个月的关键补丁亦是如此。使用 `ApproveAfterDays` 参数时也可能出现同样的情况。由于 Microsoft 取代的补丁行为，可以设置一个数字（通常大于 30 天），这样，如果 Microsoft 的最新可用补丁是在经过 `ApproveAfterDays` 中的天数之前发布的，则绝不会安装 Windows Server 的补丁。请注意，如果您修改了 Windows 组策略对象（GPO）设置，以使取代的补丁在托管式节点上可用，则此系统行为不适用。
**注意**
在某些情况下，Microsoft 会为未指定更新日期和时间的应用程序发布补丁。在这些情况下，系统会默认提供 `01/01/1970` 的更新日期和时间。
------
# 如何指定备用补丁源存储库 (Linux)
当您使用托管式节点上配置的默认存储库执行修补操作时，Patch Manager（AWS Systems Manager 中的一项工具）会扫描或安装与安全性相关的补丁。这是 Patch Manager 的默认行为。有关 Patch Manager 如何选择和安装安全性补丁的完整信息，请参阅 [如何选择安全性补丁](patch-manager-selecting-patches.md)。
不过，在 Linux 系统中，您还可以使用 Patch Manager 安装与安全性无关的补丁，或安装与托管式节点上配置的默认源存储库不同的源存储库中的补丁。您可以在创建自定义补丁基准时指定备用补丁源存储库。在每个自定义补丁基准中，您可以为多达 20 个版本的受支持的 Linux 操作系统指定补丁源配置。
例如，假设您的 Ubuntu Server 实例集同时包括 Ubuntu Server 25.04 托管节点。在这种情况下，您可以在相同的自定义补丁基准中为每个版本指定备用存储库。对于每个版本，您提供名称，指定操作系统版本类型 (产品)，并提供存储库配置。您也可以指定适用于所有版本的受支持的操作系统的单个备用源存储库。
**注意**
运行为托管式节点指定备用补丁存储库的自定义补丁基准，不会使这些存储库成为操作系统中的新默认存储库。修补操作完成后，以前配置为节点操作系统的默认存储库的存储库仍为默认存储库。
有关使用此选项的示例场景的列表，请参阅本主题后面的[备用补丁源存储库的示例用法](#patch-manager-alternative-source-repository-examples)。
有关默认和自定义补丁基准的信息，请参阅 [预定义和自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md)。
**示例：使用控制台**
要在 Systems Manager 控制台中指定备用补丁源存储库，请使用**创建补丁基准**上的**补丁来源**部分。有关使用 **Patch sources (补丁源)** 选项的信息，请参阅[创建适用于 Linux 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-linux.md)。
**示例：使用 AWS CLI**
有关将 `--sources` 选项与 AWS Command Line Interface (AWS CLI) 结合使用的示例，请参阅 [创建对不同操作系统版本使用自定义存储库的补丁基准](patch-manager-cli-commands.md#patch-manager-cli-commands-create-patch-baseline-mult-sources)。
**Topics**
+ [备用存储库的重要注意事项](#alt-source-repository-important)
+ [备用补丁源存储库的示例用法](#patch-manager-alternative-source-repository-examples)
## 备用存储库的重要注意事项
使用备用补丁存储库计划修补策略时，请注意以下几点：
**强制执行存储库更新验证（YUM 和 DNF）**
如果无法建立与存储库的连接，Linux 发行版上软件包管理器的默认配置可能会设置为跳过无法访问的软件包存储库。要强制执行存储库更新验证，请将 `skip_if_unavailable=False` 添加到存储库配置中。
有关 `skip_if_available` 选项的更多信息，请参阅 [与补丁源的连接](patch-manager-prerequisites.md#source-connectivity)。
**只指定用于修补的存储库**
指定备用存储库并不意味着指定*额外* 存储库。您可以选择指定除托管式节点上配置为默认存储库以外的存储库。但是，如果需要应用默认存储库更新，还必须在备用补丁源配置中指定默认存储库。
例如，在 Amazon Linux 2 托管式节点上，默认存储库为 `amzn2-core` 和 `amzn2extra-docker`。如果需要在修补操作中包括 Extra Packages for Enterprise Linux (EPEL) 存储库，您必须将所有三个存储库都指定为备用存储库。
**注意**
运行为托管式节点指定备用补丁存储库的自定义补丁基准，不会使这些存储库成为操作系统中的新默认存储库。修补操作完成后，以前配置为节点操作系统的默认存储库的存储库仍为默认存储库。
**基于 YUM 的分发版本的修补行为取决于 updateinfo.xml 清单**
为基于 YUM 的分发版本（如 Amazon Linux 2 或 Red Hat Enterprise Linux）指定备用补丁存储库时，修补行为取决于存储库是否包含一个采用正确格式的完整 `updateinfo.xml` 文件形式的更新清单。此文件指定各软件包的发行日期、分类和严重性。以下任一项都会影响修补行为：
+ 如果筛选**分类**和**严重性**，但并未在 `updateinfo.xml` 中指定它们，筛选器将不会包含此软件包。这也意味着没有 `updateinfo.xml` 文件的软件包不会包含在修补中。
+ 如果按 **ApprovalAfterDays** 筛选，但软件包的发行日期不是 Unix Epoch 格式（或未指定发行日期），筛选器将不会包含此软件包。
+ 如果您在**创建补丁基准**页面中选择了**包括非安全性更新**复选框，则存在例外。在这种情况下，没有 `updateinfo.xml` 文件（或包含此文件但 **Classification**（分类）、**Severity**（严重性）和 **Date**（日期）值格式不正确）的软件包*将*包含在补丁的预筛选列表中。（它们仍必须满足其他补丁基准规则要求才能安装。）
## 备用补丁源存储库的示例用法
**示例 1 – Ubuntu Server 的非安全性更新**
在使用 AWS 提供的预定义补丁基准 `AWS-UbuntuDefaultPatchBaseline` 的 Ubuntu Server 托管式节点机群上，您已经在使用 Patch Manager 安装安全性补丁。您可以创建基于此默认补丁基准的新补丁基准，但在批准规则中指定您也希望安装属于默认分配的与安全性无关的更新。当对节点运行此补丁基准时，将应用针对安全性和非安全性问题的补丁。您还可以选择在为基准指定的补丁异常中批准非安全性补丁。
**示例 2 – Ubuntu Server 的个人软件包存档 (PPA)**
Ubuntu Server 托管式节点正在运行通过 [Ubuntu 个人软件包归档 (PPA)](https://launchpad.net/ubuntu/+ppas) 分发的软件。在这种情况下，需创建补丁基准，用于指定已在托管式节点上配置为修补操作源存储库的 PPA 存储库。然后使用 Run Command 在节点上运行补丁基准文档。
**示例 3：受支持 Amazon Linux 版本上的企业内部应用程序**
您需要在 Amazon Linux 托管式节点上运行满足行业监管合规性要求所需的一些应用程序。您可以在节点上为这些应用程序配置存储库，使用 YUM 对这些应用程序进行初始安装，然后更新或创建新的补丁基准以包括此新企业存储库。此后，您可以使用 Run Command 运行 `AWS-RunPatchBaseline` 文档，并通过 `Scan` 选项查看企业软件包是否列在已安装软件包中以及在托管式节点上是否为最新。如果它不是最新的，可以使用 `Install` 选项再次运行该文档来更新应用程序。
# 如何安装补丁
Patch Manager 是 AWS Systems Manager 中的一个工具，使用操作系统内置的软件包管理器在托管式节点上安装更新。例如，在 Amazon Linux 2023 上的 Windows Server 和 `DNF` 上使用 Windows 更新 API。补丁管理器会考虑节点上现有的软件包管理器和存储库配置，包括存储库状态、映像 URL、GPG 验证等设置以及 `skip_if_unavailable` 等选项。
Patch Manager 不会安装新软件包来替换当前安装的已过时软件包。（例外情况：新软件包是正在安装的其他软件包更新的依赖项，或者新软件包与已过时软件包同名。） 相反，Patch Manager 会报告已安装的软件包并安装可用的更新。这种方法有助于防止在用一个软件包替换另一个软件包时，可能导致的系统功能意外更改。
如果需要卸载已过时软件包并安装替换软件包，则可能需要使用自定义脚本或软件包管理器命令，而不是使用标准的 Patch Manager 操作。
请从以下选项卡中进行选择，了解 Patch Manager 如何在操作系统上安装补丁。
------
#### [ Amazon Linux 2 and Amazon Linux 2023 ]
在 Amazon Linux 2 和 Amazon Linux 2023 托管节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL 来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. YUM 更新 API（Amazon Linux 2）或 DNF 更新 API（Amazon Linux 2023）用于已批准的补丁，如下所示：
+ 对于 AWS 提供的预定义默认补丁基准，仅应用 `updateinfo.xml` 中指定的补丁（仅安全性更新）。这是因为未选中**包括非安全性更新**复选框。预定义的基准等同于具有以下内容的自定义基准：
+ 未选中**包括非安全性更新**复选框
+ 严重性列表为 `[Critical, Important]`
+ 分类列表为 `[Security, Bugfix]`
对于 Amazon Linux 2，此工作流程的等效 yum 命令为：
```
sudo yum update-minimal --sec-severity=Critical,Important --bugfix -y
```
对于 Amazon Linux 2023，此工作流程的等效 dnf 命令为：
```
sudo dnf upgrade-minimal --sec-severity=Critical --sec-severity=Important --bugfix -y
```
如果选中了**包括非安全性更新**复选框，则 `updateinfo.xml` 中的补丁和未在 `updateinfo.xml` 中的补丁都会应用（安全更新和非安全性更新）。
对于 Amazon Linux 2，如果基准选中了**包括非安全性更新**，并且严重性列表为 `[Critical, Important]`，分类列表为 `[Security, Bugfix]`，则等效的 yum 命令为：
```
sudo yum update --security --sec-severity=Critical,Important --bugfix -y
```
对于 Amazon Linux 2023，等效的 dnf 命令为：
```
sudo dnf upgrade --security --sec-severity=Critical --sec-severity=Important --bugfix -y
```
**注意**
如果您在 Patch Manager 之外运行这些 `yum` 或 `dnf` 命令，则会使用不同的名称安装新软件包，来替换现已过时软件包。但是，这些软件包*无法*通过等效的 Patch Manager 操作安装。
**Amazon Linux 2023 的更多修补详细信息**
支持严重性级别“无”
Amazon Linux 2023 还支持补丁严重性级别 `None`，DNF 软件包管理器可识别该严重性级别。
支持严重性级别“中”
对于 Amazon Linux 2023，补丁严重性级别 `Medium` 相当于可能在某些外部存储库中定义的 `Moderate` 严重性。如果您在补丁基准中包含 `Medium` 严重性补丁，则外部补丁中的 `Moderate` 严重性补丁也会安装在实例上。
使用 API 操作 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatches.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatches.html) 查询合规性数据时，筛选严重性级别 `Medium` 会报告严重性级别为 `Medium` 和 `Moderate` 的补丁。
Amazon Linux 2023 的传递依赖项处理
对于 Amazon Linux 2023，Patch Manager 可能会安装与等效 `dnf` 命令安装不同的传递依赖项版本。传递依赖项是为了满足其他包的要求而自动安装的包（依赖项的依赖项）。
例如，`dnf upgrade-minimal --security` 安装解决已知安全问题所需的传递依赖项的*最低*版本，而 Patch Manager 安装相同传递依赖项的**最新可用版本。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
**注意**
Linux 发行版上软件包管理器的默认配置可以设置为跳过无法访问但没有错误的软件包存储库。在这种情况下，相关的修补操作将在不安装存储库更新的情况下继续进行，并成功结束。要强制执行存储库更新，请将 `skip_if_unavailable=False` 添加到存储库配置中。
有关 `skip_if_available` 选项的更多信息，请参阅 [与补丁源的连接](patch-manager-prerequisites.md#source-connectivity)。
------
#### [ CentOS Stream ]
在 CentOS Stream 托管式节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL 来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. 对已批准的补丁应用 CentOS Stream DNF 更新。
**注意**
对于 CentOS Stream，Patch Manager 可能会安装与等效 `dnf` 命令安装不同的传递依赖项版本。传递依赖项是为了满足其他包的要求而自动安装的包（依赖项的依赖项）。
例如，`dnf upgrade-minimal ‐‐security` 安装解决已知安全问题所需的传递依赖项的*最低*版本，而 Patch Manager 安装相同传递依赖项的*最新可用版本*。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
------
#### [ Debian 服务器 ]
在 Debian Server 实例上，补丁安装工作流程如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 如果某个更新可用于 `python3-apt` （一个 `libapt` 的 Python 库接口），则将升级到最新版本。（即使您没有选择**包括非安全更新**选项，该非安全软件包也会更新。）
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
**注意**
由于无法可靠地确定 Debian Server 更新程序包的发布日期，因此该操作系统不支持自动审批选项。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
**注意**
对于 Debian Server，补丁候选版本仅限于 `debian-security` 中包含的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 使用 APT 库升级软件包。
**注意**
Patch Manager 不支持使用 APT `Pin-Priority` 选项为软件包分配优先级。Patch Manager 汇总所有已启用存储库的可用更新，并选择匹配每个已安装软件包基准的最新更新。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
------
#### [ macOS ]
在 macOS 托管式节点上，补丁安装工作流如下：
1. `/Library/Receipts/InstallHistory.plist` 属性列表是软件的记录，已使用 `softwareupdate` 和 `installer` 软件包管理器安装和更新了这些软件。使用 `pkgutil` 命令行工具（适用于 `installer`）和 `softwareupdate` 软件包管理器，运行 CLI 命令来解析此列表。
对于 `installer`，对 CLI 命令的响应包括 `package name`、`version`、`volume`、`location` 和 `install-time` 详细信息，但只有 `package name` 和 `version` 被 Patch Manager 使用。
适用于 `softwareupdate`，对 CLI 命令的响应包括软件包名称 (`display name`)、`version` 和 `date`，但 Patch Manager 只使用软件包名称和版本。
对于 Brew 和 Brew 桶，自制软件不支持在根用户下运行的命令。因此, Patch Manager 以 Homebrew 目录的所有者或属于 Homebrew 目录的所有者组的有效用户身份查询并运行 Homebrew 命令。这些命令类似于 `softwareupdate` 和 `installer` 并通过 Python 子进程运行以收集软件包数据，并对输出进行解析以识别软件包名称和版本。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. 在托管式节点上调用相应的软件包 CLI 以处理批准的补丁，如下所示：
**注意**
`installer` 缺乏检查和安装更新的功能。因此，对于 `installer`、Patch Manager 仅报告安装了哪些软件包。因此, `installer` 软件包从未作为 `Missing` 来报告。
+ 对于 AWS 提供的预定义默认补丁基准，以及*未*选中**包括非安全性更新**复选框的自定义补丁基准，则将仅应用安全性更新。
+ 对于*已*选中**包括非安全性更新**复选框的自定义补丁基准，安全性和非安全性更新都将应用。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
------
#### [ Oracle Linux ]
在 Oracle Linux 托管式节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL 来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. 在版本 7 托管式节点上，对已批准的补丁应用 YUM 更新 API，如下所示：
+ 对于 AWS 提供的预定义默认补丁基准，以及*未*选中**包括非安全性更新**复选框的自定义补丁基准，则将仅应用 `updateinfo.xml` 中指定的补丁（仅安全性更新）。
此工作流的等效 yum 命令为：
```
sudo yum update-minimal --sec-severity=Important,Moderate --bugfix -y
```
+ 对于*已*选中**包括非安全性更新**复选框的自定义补丁基准，`updateinfo.xml` 中的补丁和未在 `updateinfo.xml` 中的补丁都将应用（安全性和非安全性更新）。
此工作流的等效 yum 命令为：
```
sudo yum update --security --bugfix -y
```
在版本 8 和 9 托管式节点上，对已批准的补丁应用 DNF 更新 API，如下所示：
+ 对于 AWS 提供的预定义默认补丁基准，以及*未*选中**包括非安全性更新**复选框的自定义补丁基准，则将仅应用 `updateinfo.xml` 中指定的补丁（仅安全性更新）。
此工作流的等效 yum 命令为：
```
sudo dnf upgrade-minimal --security --sec-severity=Moderate --sec-severity=Important
```
**注意**
对于 Oracle Linux，Patch Manager 可能会安装与等效 `dnf` 命令安装不同的传递依赖项版本。传递依赖项是为了满足其他包的要求而自动安装的包（依赖项的依赖项）。
例如，`dnf upgrade-minimal --security` 安装解决已知安全问题所需的传递依赖项的*最低*版本，而 Patch Manager 安装相同传递依赖项的*最新可用版本*。
+ 对于*已*选中**包括非安全性更新**复选框的自定义补丁基准，`updateinfo.xml` 中的补丁和未在 `updateinfo.xml` 中的补丁都将应用（安全性和非安全性更新）。
此工作流的等效 yum 命令为：
```
sudo dnf upgrade --security --bugfix
```
**注意**
如果您在 Patch Manager 之外运行这些 `yum` 或 `dnf` 命令，则会使用不同的名称安装新软件包，来替换现已过时软件包。但是，这些软件包*无法*通过等效的 Patch Manager 操作安装。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
**注意**
Linux 发行版上软件包管理器的默认配置可以设置为跳过无法访问但没有错误的软件包存储库。在这种情况下，相关的修补操作将在不安装存储库更新的情况下继续进行，并成功结束。要强制执行存储库更新，请将 `skip_if_unavailable=False` 添加到存储库配置中。
有关 `skip_if_available` 选项的更多信息，请参阅 [与补丁源的连接](patch-manager-prerequisites.md#source-connectivity)。
------
#### [ AlmaLinux, RHEL, and Rocky Linux ]
在 AlmaLinux、Red Hat Enterprise Linux 和 Rocky Linux 托管式节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL 来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. YUM 更新 API（在 RHEL 7 上）或 DNF 更新 API（在 AlmaLinux 8 和 9、RHEL 8、9 和 10 以及 Rocky Linux 8 和 9 上）根据以下规则应用于已批准的补丁：
**场景 1：排除非安全性更新**
+ **适用对象**：AWS 提供的预定义默认补丁基准和自定义补丁基准。
+ **包括非安全性更新**复选框：*未*选中。
+ **应用的补丁**：仅当 `updateinfo.xml` 中指定的补丁（仅安全性更新）与补丁基准配置相匹配且位于所配置的存储库中时，*才会*应用这些补丁。
在某些情况下，在所配置的存储库中，`updateinfo.xml` 中指定的补丁可能不再可用。配置的存储库通常只有最新版本的补丁，这是先前所有更新的累积汇总，但是最新版本可能与补丁基准规则不匹配，因此在修补操作中会省略。
+ **命令**：对于 RHEL 7，此工作流的等效 Yum 命令为：
```
sudo yum update-minimal --sec-severity=Critical,Important --bugfix -y
```
对于 AlmaLinux、RHEL 8 和 Rocky Linux，此工作流的等效 DNF 命令为：
```
sudo dnf update-minimal --sec-severity=Critical --bugfix -y ; \
sudo dnf update-minimal --sec-severity=Important --bugfix -y
```
**注意**
对于 AlmaLinux、RHEL 和 Rocky LinuxRocky Linux，Patch Manager 可能会安装与等效 `dnf` 命令安装不同的传递依赖项版本。传递依赖项是为了满足其他包的要求而自动安装的包（依赖项的依赖项）。
例如，`dnf upgrade-minimal --security` 安装解决已知安全问题所需的传递依赖项的*最低*版本，而 Patch Manager 安装相同传递依赖项的*最新可用版本*。
**场景 2：包括非安全性更新**
+ **适用对象**：自定义补丁基准。
+ **包括非安全性更新**复选框：选中。
+ **应用的补丁**：`updateinfo.xml` 中的补丁*和*未在 `updateinfo.xml` 中的补丁（安全性和非安全性更新）都会应用。
+ **命令**：对于 RHEL 7，此工作流的等效 Yum 命令为：
```
sudo yum update --security --bugfix -y
```
对于 AlmaLinux 8 和 9、RHEL 8 和 9 以及 Rocky Linux 8 和 9，此工作流的等效 DNF 命令为：
```
sudo dnf update --security --bugfix -y
```
**注意**
如果您在 Patch Manager 之外运行这些 `yum` 或 `dnf` 命令，则会使用不同的名称安装新软件包，来替换现已过时软件包。但是，这些软件包*无法*通过等效的 Patch Manager 操作安装。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
**注意**
Linux 发行版上软件包管理器的默认配置可以设置为跳过无法访问但没有错误的软件包存储库。在这种情况下，相关的修补操作将在不安装存储库更新的情况下继续进行，并成功结束。要强制执行存储库更新，请将 `skip_if_unavailable=False` 添加到存储库配置中。
有关 `skip_if_available` 选项的更多信息，请参阅 [与补丁源的连接](patch-manager-prerequisites.md#source-connectivity)。
------
#### [ SLES ]
在 SUSE Linux Enterprise Server (SLES) 托管式节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL 来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 如果批准了补丁的多个版本，则应用最新版本。
1. 对已批准的补丁应用 Zypper 更新 API。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
------
#### [ Ubuntu Server ]
在 Ubuntu Server 托管式节点上，补丁安装工作流如下：
1. 如果使用 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 文档的 `InstallOverrideList` 参数，使用 https URL 或 Amazon Simple Storage Service (Amazon S3) 路径样式 URL来指定补丁列表，则会安装列出的补丁，并跳过步骤 2-7。
1. 如果某个更新可用于 `python3-apt` （一个 `libapt` 的 Python 库接口），则将升级到最新版本。（即使您没有选择**包括非安全更新**选项，该非安全软件包也会更新。）
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)，只保留符合资格的软件包做进一步处理。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)。每条批准规则可以将一个软件包定义为已批准。
**注意**
由于无法可靠地确定 Ubuntu Server 的更新程序包的发布日期，因此此操作系统不支持自动批准选项。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。
如果包含非安全更新，也会考虑来自其他存储库的补丁。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
**注意**
对于 Ubuntu Server 的每个版本，补丁候选版本仅限于作为该版本关联存储库一部分的补丁，如下所示：
Ubuntu Server 16.04 LTS：`xenial-security`
Ubuntu Server 18.04 LTS：`bionic-security`
Ubuntu Server 20.04 LTS：`focal-security`
Ubuntu Server 22.04 LTS：`jammy-security`
Ubuntu Server 24.04 LTS (`noble-security`)
Ubuntu Server 25.04 (`plucky-security`)
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches)。已批准的补丁即使被 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters) 丢弃，也会批准更新；如果 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules) 中未指定任何批准规则，则给予批准。
1. 依照补丁基准中的规定应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches)。从已批准的补丁列表中删除已拒绝的补丁，并且不会应用已拒绝的补丁。
1. 使用 APT 库升级软件包。
**注意**
Patch Manager 不支持使用 APT `Pin-Priority` 选项为软件包分配优先级。Patch Manager 汇总所有已启用存储库的可用更新，并选择匹配每个已安装软件包基准的最新更新。
1. 如果安装了任何更新，则会重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
------
#### [ Windows Server ]
在 Windows Server 托管式节点上执行修补操作时，节点从 Systems Manager 请求相应补丁基准快照。此快照包含已批准部署的补丁基准中可用的所有更新的列表。系统会将更新列表发送到 Windows 更新 API，Windows 更新 API 确定哪些更新适用于托管式节点并根据需要安装更新。Windows 仅允许安装最新可用版本的 KB。当 KB 或 KB 的任何先前版本与应用的补丁基准匹配时，Patch Manager 会安装 KB 的最新版本。如果安装了任何更新，则系统会根据完成所有必要修补所需的次数重启托管式节点。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。） 可在 Run Command 请求输出中找到修补操作摘要。其他日志可在托管式节点上的 `%PROGRAMDATA%\Amazon\PatchBaselineOperations\Logs` 文件夹中找到。
因为使用 Windows Update API 下载和安装 KB，所以操作遵循 Windows Update 的所有组策略设置。使用 Patch Manager 时不需要任何组策略设置，但会应用已定义的所有设置，以便（例如）将托管式节点定向到 Windows Server Update Services (WSUS) 服务器。
**注意**
默认情况下，Windows 从 Microsoft 的 Windows Update 站点下载所有 KB，这是因为 Patch Manager 使用 Windows Update API 驱动 KB 的下载和安装。因此，托管式节点必须能够访问 Microsoft Windows 更新站点，否则修补将失败。或者，您也可以将 WSUS 服务器配置为 KB 存储库，然后使用组策略将托管式节点配置为将该 WSUS 服务器设为目标。
Patch Manager可能会在为 Windows Server 创建自定义补丁基准时引用 KB ID，例如基准配置中包含**已批准的补丁**列表或**已拒绝的补丁**列表时。只有在 Microsoft Windows Update 或 WSUS 服务器中分配了 KB ID 的更新才由Patch Manager安装。修补操作中不会包含缺少 KB ID 的更新。
有关创建自定义补丁基准的信息，请参阅以下主题：
[创建适用于 Windows Server 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-windows.md)
[创建补丁基准（CLI）](patch-manager-create-a-patch-baseline-for-windows.md)
[适用于 Windows 操作系统的软件包名称格式](patch-manager-approved-rejected-package-name-formats.md#patch-manager-approved-rejected-package-name-formats-windows)
------
# 补丁基准规则在基于 Linux 的系统上的工作原理
对于 Linux 分发版，补丁基准中规则的工作方式因分发版类型的不同而有所差异。与 Windows Server 托管式节点上的补丁更新不同，将在每个节点上评估规则，以便考虑实例上配置的存储库。Patch Manager（AWS Systems Manager 中的一项工具）使用本机软件包管理器推动安装补丁基准批准的补丁。
对于报告修补程序严重性级别的基于 Linux 的操作系统类型，Patch Manager 将软件发布者报告的严重性级别用于更新通知或单个修补程序。Patch Manager 不会从第三方来源（例如[常见漏洞评分系统](https://www.first.org/cvss/) (CVSS)），或者[国家漏洞数据库](https://nvd.nist.gov/vuln) (NVD) 发布的指标中获取严重性级别。
**Topics**
+ [补丁基准规则在 Amazon Linux 2 和 Amazon Linux 2023 上的工作原理](#linux-rules-amazon-linux)
+ [补丁基准规则在 CentOS Stream 上的工作原理](#linux-rules-centos)
+ [补丁基准规则在 Debian Server 上的工作原理](#linux-rules-debian)
+ [补丁基准规则在 macOS 上的工作原理](#linux-rules-macos)
+ [补丁基准规则在 Oracle Linux 上的工作原理](#linux-rules-oracle)
+ [补丁基准规则在 AlmaLinux、RHEL 和 Rocky Linux 上的工作原理](#linux-rules-rhel)
+ [补丁基准规则在 SUSE Linux Enterprise Server 上的工作原理](#linux-rules-sles)
+ [补丁基准规则在 Ubuntu Server 上的工作原理](#linux-rules-ubuntu)
## 补丁基准规则在 Amazon Linux 2 和 Amazon Linux 2023 上的工作原理
**注意**
Amazon Linux 2023（AL2023）使用版本控制的存储库，这些存储库可以通过一个或多个系统设置锁定到特定版本。对于 AL2023 EC2 实例的所有修补操作，Patch Manager 使用最新的存储库版本，与系统配置无关。有关更多信息，请参阅《Amazon Linux 2023 User Guide》**中的 [Deterministic upgrades through versioned repositories](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html)。
在 Amazon Linux 2 和 Amazon Linux 2023 上，补丁选择过程如下：
1. 在托管节点上，YUM 库（Amazon Linux 2）或 DNF 库（Amazon Linux 2023）将访问每个已配置存储库的 `updateinfo.xml` 文件。
如果未找到 `updateinfo.xml` 文件，是否安装补丁将取决于**包括非安全性更新**和**自动批准**设置。例如，如果允许非安全更新，则会在自动批准时间到达时安装这些更新。
1. `updateinfo.xml` 中的每个更新通知都包含几个属性，它们表示通知中的软件包的属性，如下表所述。
**更新通知属性**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
1. 托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 Product 键属性的值。
1. 根据以下准则为更新选择程序包。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 CentOS Stream 上的工作原理
CentOS Stream 默认存储库不包含 `updateinfo.xml` 文件。不过，您创建或使用的自定义存储库可能包含该文件。在本主题中，对 `updateinfo.xml` 的引用仅适用于这些自定义存储库。
在 CentOS Stream 上，补丁选择过程如下：
1. 在托管式节点上，DNF 库可访问每个已配置存储库的 `updateinfo.xml` 文件（如果该文件存在于自定义存储库中）。
如果未找到 `updateinfo.xml`（其中始终包含默认存储库），是否安装补丁将取决于**包括非安全性更新**和**自动批准**设置。例如，如果允许非安全更新，则会在自动批准时间到达时安装这些更新。
1. 如果存在 `updateinfo.xml`，该文件中的每个更新通知都包含几个属性，这些属性表示通知中软件包的属性，如下表所述。
**更新通知属性**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
1. 在所有情况下，托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 Product 键属性的值。
1. 根据以下准则为更新选择程序包。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 Debian Server 上的工作原理
在 Debian Server上，补丁基准服务提供对*优先级*和*部分*字段的筛选。这些字段通常存在于所有 Debian Server 软件包中。为确定补丁基准是否选择了某个补丁，Patch Manager 执行以下操作：
1. 在 Debian Server 系统上，运行等效于 `sudo apt-get update` 的程序刷新可用软件包列表。不配置存储库，从 `sources` 列表中配置的存储库提取数据。
1. 如果某个更新可用于 `python3-apt` （一个 `libapt` 的 Python 库接口），则将升级到最新版本。（即使您没有选择**包括非安全更新**选项，该非安全软件包也会更新。）
1. 接下来将应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)、[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)、[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches) 和 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches) 列表。
**注意**
由于无法可靠地确定 Debian Server 更新程序包的发布日期，因此该操作系统不支持自动审批选项。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。在这种情况下，对于 Debian Server，补丁候选版本仅限于以下存储库中包含的补丁：
这些存储库的命名如下：
+ Debian Server 11：`debian-security bullseye`
+ Debian Server 12：`debian-security bookworm`
如果包含非安全更新，也会考虑来自其他存储库的补丁。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
要查看 *Priority* 和 *Section* 字段的内容，运行以下 `aptitude` 命令：
**注意**
您需要先在 Debian Server 系统上安装 Aptitude。
```
aptitude search -F '%p %P %s %t %V#' '~U'
```
在对此命令的响应中，按以下格式报告所有可升级软件包：
```
name, priority, section, archive, candidate version
```
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 macOS 上的工作原理
在 macOS 上，补丁选择过程如下：
1. 在托管式节点上，Patch Manager 访问 `InstallHistory.plist` 文件的已解析内容并标识软件包名称和版本。
有关解析过程的详细信息，请参阅 [如何安装补丁](patch-manager-installing-patches.md) 中的 **macOS** 选项卡。
1. 托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 Product 键属性的值。
1. 根据以下准则为更新选择程序包。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 Oracle Linux 上的工作原理
在 Oracle Linux 上，补丁选择过程如下：
1. 在托管式节点上，YUM 库可访问每个已配置存储库的 `updateinfo.xml` 文件。
**注意**
如果存储库不是由 Oracle 管理的，则可能不存在 `updateinfo.xml` 文件。如果未找到 `updateinfo.xml`，是否安装补丁将取决于**包括非安全性更新**和**自动批准**设置。例如，如果允许非安全更新，则会在自动批准时间到达时安装这些更新。
1. `updateinfo.xml` 中的每个更新通知都包含几个属性，它们表示通知中的软件包的属性，如下表所述。
**更新通知属性**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
1. 托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 Product 键属性的值。
1. 根据以下准则为更新选择程序包。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 AlmaLinux、RHEL 和 Rocky Linux 上的工作原理
在 AlmaLinux、Red Hat Enterprise Linux（RHEL）和 Rocky Linux 上，补丁选择过程如下：
1. 在托管式节点上，YUM 库 (RHEL 7) 或 DNF 库（AlmaLinux 8 和 9、RHEL 8、9 和 10 以及 Rocky Linux 8 和 9）访问每个已配置存储库的 `updateinfo.xml` 文件。
**注意**
如果存储库不是由 Red Hat 管理的，可能不存在 `updateinfo.xml` 文件。如果找不到 `updateinfo.xml`，则不会应用任何补丁。
1. `updateinfo.xml` 中的每个更新通知都包含几个属性，它们表示通知中的软件包的属性，如下表所述。
**更新通知属性**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
1. 托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 Product 键属性的值。
1. 根据以下准则为更新选择程序包。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-linux-rules.html)
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
## 补丁基准规则在 SUSE Linux Enterprise Server 上的工作原理
在 SLES 上，每个补丁包括以下表示补丁中的软件包的属性的属性：
+ **类别**：对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中的 **Classification** 键属性的值。表示更新通知中包含的补丁的类型。
可以使用 AWS CLI 命令 **[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html)** 或 API 操作 **[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html)** 来查看受支持值的列表。您也可以在 Systems Manager 控制台中**创建补丁基准**页面或**编辑补丁基准**页面中的**审批规则**区中查看列表。
+ **严重性**：对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中的**严重性**键属性的值。表示补丁的严重性。
可以使用 AWS CLI 命令 **[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html)** 或 API 操作 **[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html)** 来查看受支持值的列表。您也可以在 Systems Manager 控制台中**创建补丁基准**页面或**编辑补丁基准**页面中的**审批规则**区中查看列表。
托管式节点的产品由 SSM Agent 确定。此属性对应于补丁基准的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html) 数据类型中 **Product** 键属性的值。
对于每个补丁，补丁基准用作筛选器，只允许更新包含符合条件的软件包。如果应用补丁基准定义后有多个软件包适用，则使用最新版本。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
## 补丁基准规则在 Ubuntu Server 上的工作原理
在 Ubuntu Server上，补丁基准服务提供对*优先级*和*部分*字段的筛选。这些字段通常存在于所有 Ubuntu Server 软件包中。为确定补丁基准是否选择了某个补丁，Patch Manager 执行以下操作：
1. 在 Ubuntu Server 系统上，运行等效于 `sudo apt-get update` 的程序刷新可用软件包列表。不配置存储库，从 `sources` 列表中配置的存储库提取数据。
1. 如果某个更新可用于 `python3-apt` （一个 `libapt` 的 Python 库接口），则将升级到最新版本。（即使您没有选择**包括非安全更新**选项，该非安全软件包也会更新。）
1. 接下来将应用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-GlobalFilters)、[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovalRules)、[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-ApprovedPatches) 和 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#EC2-CreatePatchBaseline-request-RejectedPatches) 列表。
**注意**
由于无法可靠地确定 Ubuntu Server 的更新程序包的发布日期，因此此操作系统不支持自动批准选项。
但是，批准规则也取决于在创建或上次更新补丁基准时是否选中**包括非安全更新**复选框。
如果不包含非安全更新，则应用一条隐式规则，以便只选择在安全存储库中有升级的软件包。对于每个软件包，软件包的候选版本（通常为最新版本）必须包含在安全存储库中。在这种情况下，对于 Ubuntu Server，补丁候选版本仅限于以下存储库中包含的补丁：
+ Ubuntu Server 16.04 LTS：`xenial-security`
+ Ubuntu Server 18.04 LTS：`bionic-security`
+ Ubuntu Server 20.04 LTS：`focal-security`
+ Ubuntu Server 22.04 LTS：`jammy-security`
+ Ubuntu Server 24.04 LTS (`noble-security`)
+ Ubuntu Server 25.04 (`plucky-security`)
如果包含非安全更新，也会考虑来自其他存储库的补丁。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
要查看 *Priority* 和 *Section* 字段的内容，运行以下 `aptitude` 命令：
**注意**
您需要先在 Ubuntu Server 16 系统上安装 Aptitude。
```
aptitude search -F '%p %P %s %t %V#' '~U'
```
在对此命令的响应中，按以下格式报告所有可升级软件包：
```
name, priority, section, archive, candidate version
```
有关补丁合规性状态值的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
# Linux 和 Windows Server 之间的补丁操作差异
本主题介绍Patch Manager（AWS Systems Manager 中的一项工具）中 Linux 和 Windows Server 修补之间的重要差异。
**注意**
要修补 Linux 托管式节点，节点必须运行 SSM Agent 2.0.834.0 版或更高版本。
如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
## 区别 1：补丁评估
Patch Manager 在 Windows 托管式节点和 Linux 托管式节点上使用不同的进程，以评估应该存在的补丁。
**Linux**
对于 Linux 修补，Systems Manager 会评估补丁基准规则以及 *每个*托管式节点上已批准和已被拒绝的补丁列表。Systems Manager 必须在每个节点上评估修补，因为该服务从托管式节点上配置的存储库中检索已知补丁和更新列表。
**Windows**
对于 Windows 修补，Systems Manager *直接在服务中*评估补丁基准规则以及已批准和已拒绝的补丁列表。它可以执行此操作是因为 Windows 补丁从单个存储库 (Windows 更新) 拉取。
## 区别 2：`Not Applicable` 补丁
因为 Linux 操作系统有大量可用的软件包，所以 Systems Manager 不报告处于*不适用*状态的补丁的详细信息。例如，A `Not Applicable` 补丁是在实例未安装 Apache 时的 Apache 软件的补丁。Systems Manager 确实会在摘要中报告 `Not Applicable` 补丁的数量，但如果为某个托管式节点调用 [DescribeInstancePatches](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatches.html) API，则返回的数据中不包含状态为 `Not Applicable` 的补丁。这一行为不同于 Windows。
## 区别 3：SSM 文档支持
`AWS-ApplyPatchBaseline` Systems Manager 文档（SSM 文档）不支持 Linux 托管式节点。如需对 Linux、macOS 和 Windows Server 托管式节点应用补丁基准，则推荐的 SSM 文档是 `AWS-RunPatchBaseline`。有关更多信息，请参阅[适用于修补托管式节点的 SSM 命令文档](patch-manager-ssm-documents.md)和[用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
## 区别 4：应用程序补丁
Patch Manager 的主要目的是将补丁应用到操作系统。不过，您也可以使用 Patch Manager 将补丁应用到托管式节点上的某些应用程序。
**Linux**
在 Linux 操作系统上，Patch Manager 使用配置的存储库进行更新，不会区分操作系统补丁和应用程序补丁。您可以使用 Patch Manager 来定义从哪些存储库获取更新。有关更多信息，请参阅 [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。
**Windows**
在 Windows Server 托管式节点上，您可以为 Microsoft 发布的应用程序（如 Microsoft Word 2016 和 Microsoft Exchange Server 2016）应用已批准规则，以及*已批准*和*已被拒绝*补丁例外。有关更多信息，请参阅 [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
## 区别 5：自定义补丁基准中已拒绝的补丁列表选项
创建自定义补丁基准时，您可以为此**已拒绝的补丁**列表指定一个或多个补丁。对于 Linux 托管节点，如果它们是基准允许的其他补丁的依赖项，则也可以选择允许安装它们。
但是，Windows Server 不支持补丁依赖项的概念。您可以将补丁添加到 Windows Server 的自定义基准的**已拒绝的补丁**列表中，但结果取决于（1）被拒绝的补丁是否已安装在托管节点上，以及（2）您为**被拒绝的补丁操作**选择了哪个选项。
有关 Windows Server 上已拒绝的补丁选项的详细信息，请参阅下表。
| 安装状态 | 选项：“作为依赖项允许” | 选项：“语句块” |
| --- | --- | --- |
| 补丁已安装 | 报告状态：INSTALLED\$1OTHER | 报告状态：INSTALLED\$1REJECTED |
| 尚未安装补丁 | 补丁已跳过 | 补丁已跳过 |
Microsoft 发布的每个 Windows Server 补丁通常都包含成功安装所需的所有信息。但是，有时可能需要必备程序包，您必须手动安装该程序包。 Patch Manager 不报告有关这些先决条件的信息。有关相关信息，请参阅 Microsoft 网站上的 [Windows 更新问题排查](https://learn.microsoft.com/en-us/troubleshoot/windows-client/installing-updates-features-roles/windows-update-issues-troubleshooting)。
# 适用于修补托管式节点的 SSM 命令文档
本主题介绍了目前可用的九个 Systems Manager 文档（SSM 文档），有助于您保持为托管式节点提供最新的安全性相关更新补丁。
我们建议在修补操作中仅使用这些文档中的五个。结合使用这五个 SSM 文档，您即可获得使用 AWS Systems Manager 进行修补的全部选项。其中有四个文档是在四个早期 SSM 文档之后发布的，替换了这四个早期文档，对功能进行了扩展和整合。
**适用于修补的推荐 SSM 文档**
我们建议在修补操作中使用以下五个 SSM 文档。
+ `AWS-ConfigureWindowsUpdate`
+ `AWS-InstallWindowsUpdates`
+ `AWS-RunPatchBaseline`
+ `AWS-RunPatchBaselineAssociation`
+ `AWS-RunPatchBaselineWithHooks`
**适用于修补的旧版 SSM 文档**
以下四个旧版 SSM 文档在某些 AWS 区域中仍然可用，但不再更新或支持。无法保证这些文档在 IPv6 环境中有效，仅支持 IPv4。无法保证这些文档在所有情况下都有效，并且将来可能不再支持。我们建议您不要使用这些文档进行修补操作。
+ `AWS-ApplyPatchBaseline`
+ `AWS-FindWindowsUpdates`
+ `AWS-InstallMissingWindowsUpdates`
+ `AWS-InstallSpecificWindowsUpdates`
有关在仅支持 IPv6 的环境中设置修补操作的步骤，请参阅[教程：在仅支持 IPv6 的环境中修补服务器](patch-manager-server-patching-iPv6-tutorial.md)。
请参考以下各节，了解有关如何在修补操作中使用这些 SSM 文档的更多信息。
**Topics**
+ [用于修补托管式节点的推荐 SSM 文档](#patch-manager-ssm-documents-recommended)
+ [适用于修补托管式节点的旧 SSM 文档](#patch-manager-ssm-documents-legacy)
+ [适用于修补托管式节点的 SSM 文档的已知限制](#patch-manager-ssm-documents-known-limitations)
+ [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)
+ [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md)
+ [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md)
+ [在 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 中使用 InstallOverrideList 参数的示例场景](patch-manager-override-lists.md)
+ [使用基准覆盖参数](patch-manager-baselineoverride-parameter.md)
## 用于修补托管式节点的推荐 SSM 文档
建议在进行托管式节点的修补操作时使用以下五个 SSM 文档。
**Topics**
+ [`AWS-ConfigureWindowsUpdate`](#patch-manager-ssm-documents-recommended-AWS-ConfigureWindowsUpdate)
+ [`AWS-InstallWindowsUpdates`](#patch-manager-ssm-documents-recommended-AWS-InstallWindowsUpdates)
+ [`AWS-RunPatchBaseline`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaseline)
+ [`AWS-RunPatchBaselineAssociation`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaselineAssociation)
+ [`AWS-RunPatchBaselineWithHooks`](#patch-manager-ssm-documents-recommended-AWS-RunPatchBaselineWithHooks)
### `AWS-ConfigureWindowsUpdate`
支持配置基本的 Windows 更新功能，并使用它们来自动安装更新 (或关闭自动更新)。在所有 AWS 区域 中可用。
此 SSM 文档可提示 Windows 更新下载并安装指定的更新，并根据需要重启托管式节点。将此文档与State Manager（AWS Systems Manager 中的一项工具）结合使用，确保 Windows Update 保持其配置。您也可以使用 Run Command（AWS Systems Manager 中的一项工具）手动运行该文档来更改 Windows Update 配置。
本文档中的可用参数支持指定要安装的更新类别 (或是否关闭自动更新)，还支持指定在星期几的什么时间运行修补操作。如果您不需要对 Windows 更新进行严格控制，也不需要收集合规性信息，则此 SSM 文档最为有用。
**替换早期 SSM 文档：**
+ *无*
### `AWS-InstallWindowsUpdates`
在 Windows Server 托管式节点上安装更新。在所有 AWS 区域 中可用。
如果您希望安装指定更新 (使用 `Include Kbs` 参数)，或希望安装特定类别或分类的补丁，但不需要补丁合规性信息，则此 SSM 文档可提供基本修补功能。
**替换早期 SSM 文档：**
+ `AWS-FindWindowsUpdates`
+ `AWS-InstallMissingWindowsUpdates`
+ `AWS-InstallSpecificWindowsUpdates`
这三个早期文档执行不同的功能，但您可以使用较新的 SSM 文档 `AWS-InstallWindowsUpdates` 的不同参数设置得到同样的结果。这些参数设置在 [适用于修补托管式节点的旧 SSM 文档](#patch-manager-ssm-documents-legacy) 中进行了介绍。
### `AWS-RunPatchBaseline`
在托管式节点上安装补丁或扫描节点，以确定是否缺少任何符合条件的补丁。在所有 AWS 区域 中可用。
`AWS-RunPatchBaseline` 允许您使用指定为操作系统类型的“默认”补丁基准来控制补丁批准。报告补丁合规性信息，您可以使用 Systems Manager 合规性工具进行查看。您可使用这些工具深入了解托管式节点的补丁合规性状态，例如哪些节点缺少补丁以及缺少哪些补丁。当您使用 `AWS-RunPatchBaseline` 时，将使用 `PutInventory` API 命令记录补丁合规性信息。对于 Linux 操作系统，为来自托管式节点上配置的默认源存储库和来自在自定义补丁基准中指定的任何备用源存储库的补丁提供合规性信息。有关备用源存储库的更多信息，请参阅 [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。有关 Systems Manager 合规性工具的更多信息，请参阅 [AWS Systems Manager Compliance](systems-manager-compliance.md)。
**替换早期文档：**
+ `AWS-ApplyPatchBaseline`
旧文档 `AWS-ApplyPatchBaseline` 仅适用于 Windows Server 托管式节点，不提供应用程序修补支持。较新的 `AWS-RunPatchBaseline` 对 Windows 和 Linux 系统提供了同等支持。要使用 `AWS-RunPatchBaseline` 文档，需要版本 2.0.834.0 或 SSM Agent 的更高版本。
有关如何使用 `AWS-RunPatchBaseline` SSM 文档的更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
### `AWS-RunPatchBaselineAssociation`
在实例上安装补丁，或扫描实例以确定是否缺少任何符合条件的补丁。在所有商业 AWS 区域 中提供。
`AWS-RunPatchBaselineAssociation` 与 `AWS-RunPatchBaseline` 的不同表现在几个重要方面：
+ `AWS-RunPatchBaselineAssociation` 主要用于使用Quick Setup（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 Systems Manager Quick Setup](systems-manager-quick-setup.md)
+ [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md)
+ `AWS-RunPatchBaselineAssociation` 支持使用标签来标识在运行时使用哪个补丁基准来用于一组目标。
+ 对于使用 `AWS-RunPatchBaselineAssociation` 的修补操作，将按照特定的 State Manager 关联来编译补丁合规性数据。在运行 `AWS-RunPatchBaselineAssociation` 时收集的补丁合规性数据，使用 `PutComplianceItems` API 命令而不是 `PutInventory` 命令来记录。这样可以防止覆盖与此特定关联无关的合规性数据。
对于 Linux 操作系统，为来自实例上配置的默认源存储库和来自您在自定义补丁基准中指定的任何备用源存储库的补丁提供合规性信息。有关备用源存储库的更多信息，请参阅 [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。有关 Systems Manager 合规性工具的更多信息，请参阅 [AWS Systems Manager Compliance](systems-manager-compliance.md)。
**替换早期文档：**
+ **无**
有关如何使用 `AWS-RunPatchBaselineAssociation` SSM 文档的更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md)。
### `AWS-RunPatchBaselineWithHooks`
在托管式节点上安装补丁或扫描节点，以确定是否缺少任何符合条件的补丁，您可以使用可选钩子在修补周期内在三个点运行 SSM 文档。在所有商业 AWS 区域 中提供。在 macOS 上不受支持。
在其 `Install` 操作中，`AWS-RunPatchBaselineWithHooks` 不同于 `AWS-RunPatchBaseline`。
`AWS-RunPatchBaselineWithHooks` 支持托管式节点修补期间在指定点运行的生命周期钩子。由于补丁安装有时需要重启托管式节点，修补操作分为两个事件，共有三个支持自定义功能的钩子。第一个钩子先于 `Install with NoReboot` 操作。第二个钩子后于 `Install with NoReboot` 操作。节点重启后，即可使用第三个钩子。
**替换早期文档：**
+ **无**
有关如何使用 `AWS-RunPatchBaselineWithHooks` SSM 文档的更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md)。
## 适用于修补托管式节点的旧 SSM 文档
以下四个 SSM 文档仍可在某些 AWS 区域 中使用。不过，这些版本已不再更新，将来可能不再受支持，因此不建议使用。请使用 [用于修补托管式节点的推荐 SSM 文档](#patch-manager-ssm-documents-recommended) 中介绍的文档。
**Topics**
+ [`AWS-ApplyPatchBaseline`](#patch-manager-ssm-documents-legacy-AWS-ApplyPatchBaseline)
+ [`AWS-FindWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-AWS-FindWindowsUpdates)
+ [`AWS-InstallMissingWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-InstallMissingWindowsUpdates)
+ [`AWS-InstallSpecificWindowsUpdates`](#patch-manager-ssm-documents-legacy-AWS-InstallSpecificWindowsUpdates)
### `AWS-ApplyPatchBaseline`
仅支持 Windows Server 托管式节点，但不包括对在其替换文档 `AWS-RunPatchBaseline` 中找到的修补应用程序的支持。在 2017 年 8 月之后推出的 AWS 区域 中不提供。
**注意**
此 SSM 文档 `AWS-RunPatchBaseline` 的替换文档需要版本 2.0.834.0 或 SSM Agent 的更高版本。可以使用 `AWS-UpdateSSMAgent` 文档将托管式节点更新为代理的最新版本。
### `AWS-FindWindowsUpdates`
已被 `AWS-InstallWindowsUpdates` 取代，可执行所有相同的操作。在 2017 年 4 月之后推出的 AWS 区域 中不提供。
要得到与这个早期 SSM 文档相同的结果，请使用推荐的替换文档 `AWS-InstallWindowsUpdates` 的以下参数配置：
+ `Action` = `Scan`
+ `Allow Reboot` = `False`
### `AWS-InstallMissingWindowsUpdates`
已被 `AWS-InstallWindowsUpdates` 取代，可执行所有相同的操作。在 2017 年 4 月之后推出的所有 AWS 区域 中均不提供。
要得到与这个早期 SSM 文档相同的结果，请使用推荐的替换文档 `AWS-InstallWindowsUpdates` 的以下参数配置：
+ `Action` = `Install`
+ `Allow Reboot` = `True`
### `AWS-InstallSpecificWindowsUpdates`
已被 `AWS-InstallWindowsUpdates` 取代，可执行所有相同的操作。在 2017 年 4 月之后推出的所有 AWS 区域 中均不提供。
要得到与这个早期 SSM 文档相同的结果，请使用推荐的替换文档 `AWS-InstallWindowsUpdates` 的以下参数配置：
+ `Action` = `Install`
+ `Allow Reboot` = `True`
+ `Include Kbs` = *KB 文章的逗号分隔列表*
## 适用于修补托管式节点的 SSM 文档的已知限制
### 外部重启中断
如果在安装补丁期间，节点上的系统启动了重启（例如，将更新应用于固件或诸如 SecuReboot 之类的功能），则即使成功安装了补丁，修补文档的执行也可能会中断并标记为失败。出现这种情况是因为 SSM Agent 无法在外部重启后保持和恢复文档执行状态。
要在执行失败后验证补丁安装状态，请运行 `Scan` 修补操作，然后在补丁管理器中检查补丁合规性数据，进而评测当前的合规性状态。
# 用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`
AWS Systems Manager 支持 `AWS-RunPatchBaseline`，这是Patch Manager（AWS Systems Manager 中的一项工具）的 Systems Manager 文档（SSM 文档）。此 SSM 文档在托管式节点上为安全性相关更新和其他类型的更新执行修补操作。运行文档时，如果未指定补丁组，则使用为操作系统类型指定的“默认”的补丁基准。否则，它将使用与补丁组关联的补丁基准。有关补丁组的信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
您可以使用文档 `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 子进程在节点上调用 AWS Command Line Interface (AWS CLI），以检索指定软件包管理器的安装和更新信息，并为每个更新软件包驱动适当的软件包管理器。
------
每个快照都专用于一个 AWS 账户、补丁组、操作系统和快照 ID。快照通过预签名的 Amazon Simple Storage Service (Amazon S3) URL 传送，该 URL 在快照创建 24 小时后过期。但是，在 URL 过期后，如果要将相同的快照内容应用于其他托管式节点，您可以在创建快照后最久 3 天内生成新的预签名 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-RunPatchBaseline` 文档中将 `RebootOption` 参数设置为 `NoReboot`，在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。
有关查看补丁合规性数据的信息，请参阅 [关于补丁合规性](compliance-about.md#compliance-monitor-patch)。
## `AWS-RunPatchBaseline` 参数
`AWS-RunPatchBaseline` 支持六个参数。`Operation` 参数是必需的。`InstallOverrideList` 、 `BaselineOverride` 和 `RebootOption` 参数是可选的。从技术上讲，`Snapshot-ID` 是可选的，但我们建议在维护时段之外运行 `AWS-RunPatchBaseline` 时为其提供一个自定义值，而在维护时段操作中运行此文档时，让 Patch Manager 自动提供该值。
**Topics**
+ [参数名称: `Operation`](#patch-manager-aws-runpatchbaseline-parameters-operation)
+ [参数名称: `AssociationId`](#patch-manager-aws-runpatchbaseline-parameters-association-id)
+ [参数名称: `Snapshot ID`](#patch-manager-aws-runpatchbaseline-parameters-snapshot-id)
+ [参数名称: `InstallOverrideList`](#patch-manager-aws-runpatchbaseline-parameters-installoverridelist)
+ [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption)
+ [参数名称: `BaselineOverride`](#patch-manager-aws-runpatchbaseline-parameters-baselineoverride)
+ [参数名称: `StepTimeoutSeconds`](#patch-manager-aws-runpatchbaseline-parameters-steptimeoutseconds)
### 参数名称: `Operation`
**用法**：必需。
**选项**：`Scan` \$1 `Install`。
Scan
选择 `Scan` 选项时，`AWS-RunPatchBaseline` 确定托管式节点的补丁合规性状态并向 Patch Manager 报告此信息。`Scan` 不提示要安装的更新或要重启的托管式节点。相反，该操作会标识哪些地方缺少已批准并且适用于节点的更新。
安装
选择 `Install` 选项时，`AWS-RunPatchBaseline` 会尝试安装托管式节点中缺失并已批准的适用更新。在 `Install` 操作中生成的补丁合规性信息不会列出任何缺失的更新。但是，如果更新的安装因任何原因失败，它会报告处于失败状态的更新。一旦在托管式节点上安装了更新，就一定会重启节点，以确保正常安装和激活更新。（例外：如果将 `AWS-RunPatchBaseline` 文档中的 `RebootOption` 参数设置为 `NoReboot`，则在 Patch Manager 运行后不会重启托管式节点。有关更多信息，请参阅 [参数名称: `RebootOption`](#patch-manager-aws-runpatchbaseline-parameters-norebootoption)。）
如果在 Patch Manager 更新托管式节点*之前*安装了基准规则指定的补丁，则系统可能无法按预期重启。当补丁是由用户手动安装或由其他程序（例如 Ubuntu Server 上的 `unattended-upgrades` 程序包）自动安装时，可能会发生这种情况。
### 参数名称: `AssociationId`
**用法**：可选。
`AssociationId` 是State Manager（AWS Systems Manager 中的一项工具）中现有关联的 ID。Patch Manager 使用它来将合规性数据添加到指定的关联上。此关联与[在 Quick Setup 的补丁策略中设置](quick-setup-patch-manager.md)的修补操作有关。
**注意**
使用 `AWS-RunPatchBaseline` 时，如果在补丁策略基准覆盖的同时提供了一个 `AssociationId` 值，系统将以 `PatchPolicy` 操作来完成修补，`AWS:ComplianceItem` 中报告的 `ExecutionType` 值也是 `PatchPolicy`。如果未提供任何 `AssociationId` 值，系统将以 `Command` 操作来完成修补，提交的 `AWS:ComplianceItem` 中报告的 `ExecutionType` 值也是 `Command`。
如果您还没有要使用的关联，可以通过运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-association.html) 命令来创建关联。
### 参数名称: `Snapshot ID`
**用法**：可选。
`Snapshot ID` 是 Patch Manager 使用的唯一 ID (GUID)，用于确保在单一操作中修补的一组托管式节点均具有完全相同的一组已批准补丁。尽管它定义为可选参数，根据是否在维护时段中运行 `AWS-RunPatchBaseline`，我们还是提供了不同的最佳实践建议，如下表所述。
**`AWS-RunPatchBaseline` 最佳实践**
| Mode | 最佳实践 | Details |
| --- | --- | --- |
| 正在维护时段内运行 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（AWS 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` 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
使用 `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 的环境中修补服务器](patch-manager-server-patching-iPv6-tutorial.md)。
有关如何使用 `InstallOverrideList` 参数按不同维护时段计划将不同类型的补丁应用到目标组，同时仍使用单个补丁基准的说明，请参阅 [在 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 中使用 InstallOverrideList 参数的示例场景](patch-manager-override-lists.md)。
**有效的 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](http://www.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}` 格式或 \$1软件包名称\$1 格式。
------
**示例补丁列表**
+ **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` \$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`。
`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` 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
有关如何使用 `BaselineOverride` 参数的更多信息，请参阅 [使用基准覆盖参数](patch-manager-baselineoverride-parameter.md)。
### 参数名称: `StepTimeoutSeconds`
**用法**：必需。
命令在被视为失败前将会运行的时间（以秒为单位），介于 1 至 36000 秒（10 小时）之间。
# 用于修补的 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`
# 用于修补的 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)。
# 在 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 中使用 InstallOverrideList 参数的示例场景
当您要在Patch Manager（AWS Systems Manager 中的一项工具）中覆盖由当前默认补丁基准指定的补丁时，可以使用 `InstallOverrideList` 参数。本主题提供示例说明如何使用此参数来实现以下目标：
+ 将不同的补丁集应用于托管式节点目标组。
+ 以不同频率应用这些补丁集。
+ 对这两个操作使用相同的补丁基准。
假设您要在 Amazon Linux 2 托管式节点上安装两种不同类别的补丁。您希望使用维护时段按不同的计划安装这些补丁。您希望每周运行一个维护时段并安装所有 `Security` 补丁。您希望另一个维护时段每月运行一次，并安装所有可用的补丁或 `Security` 之外类别的补丁。
但是，一次只能将一个补丁基准定义为操作系统的默认值。此要求有助于避免一个补丁基准批准补丁而另一个补丁阻止补丁的情况，这种情况可能导致相互冲突的版本之间出现问题。
以下策略允许您使用 `InstallOverrideList` 参数按照不同的计划将不同类型的补丁应用到目标组，同时仍使用相同的补丁基准。
1. 在默认补丁基准中，确保仅指定 `Security` 更新。
1. 创建每周运行 `AWS-RunPatchBaseline` 或 `AWS-RunPatchBaselineAssociation` 的维护时段。不要指定覆盖列表。
1. 创建要每月应用的所有类型的补丁的覆盖列表，并将其存储在 Amazon Simple Storage Service (Amazon S3) 存储桶中。
1. 创建每月运行一次的第二个维护时段。但是，对于您为此维护时段注册的 Run Command 任务，请指定覆盖列表的位置。
结果：每周只安装在默认补丁基准中定义的 `Security` 补丁。每月都会安装所有可用的补丁或您定义的任何补丁子集。
**注意**
当您修补仅使用 IPv6 的节点时，请确保提供的 URL 可从该节点访问。如果将 SSM Agent 配置选项 `UseDualStackEndpoint` 设置为 `true`，则在提供 S3 URL 时将使用双堆栈 S3 客户端。有关将代理配置为使用双堆栈的更多信息，请参阅 [教程：在仅支持 IPv6 的环境中修补服务器](patch-manager-server-patching-iPv6-tutorial.md)。
有关更多信息和示例列表，请参阅 [参数名称: `InstallOverrideList`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-installoverridelist)。
# 使用基准覆盖参数
您可以在运行时使用Patch Manager（AWS Systems Manager 中的一项工具）中的基准覆盖功能来定义修补首选项。通过指定包含一个带有补丁基准列表的 JSON 对象的 Amazon Simple Storage Service (Amazon S3) 存储桶来实施。该修补操作使用与主机操作系统匹配的 JSON 对象中提供的基准，而不是应用默认补丁基准中的规则。
**重要**
`BaselineOverride` 文件名不能包含以下字符：反引号 (`)、单引号 (')、双引号 (") 和美元符号 (\$1)。
除非补丁操作使用补丁策略，否则使用 `BaselineOverride` 参数不会覆盖参数中提供的基准的补丁合规性。输出结果记录在来自 Run Command（AWS Systems Manager 中的一项工具）的标准输出日志中。结果仅打印标记为 `NON_COMPLIANT` 的软件包。这意味着软件包被标记为 `Missing`、 `Failed`、 `InstalledRejected` 或者 `InstalledPendingReboot`。
但是，当补丁操作使用补丁策略时，系统会传递关联的 S3 存储桶中的覆盖参数，并更新托管式节点的合规性值。有关补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
**注意**
当您修补仅使用 IPv6 的节点时，请确保提供的 URL 可从该节点访问。如果将 SSM Agent 配置选项 `UseDualStackEndpoint` 设置为 `true`，则在提供 S3 URL 时将使用双堆栈 S3 客户端。有关将代理配置为使用双堆栈的更多信息，请参阅 [教程：在仅支持 IPv6 的环境中修补服务器](patch-manager-server-patching-iPv6-tutorial.md)。
## 使用快照 ID 的补丁基准覆盖，或者安装覆盖列表参数
在两种情况下，补丁基准覆盖具有值得注意的行为。
**同时使用基准覆盖和快照 ID**
快照 ID 可确保特定修补命令中的所有托管式节点都应用相同的内容。例如，如果您一次修补 1000 个节点，则补丁相同。
当同时使用快照 ID 和补丁基准覆盖时，快照 ID 优先于补丁基准覆盖。仍将使用基准覆盖规则，但只会对其进行评估一次。在前面的示例中，1000 个托管式节点中的补丁仍始终相同。如果在修补操作的中程，您将引用的 S3 存储桶中的 JSON 文件更改为不同的内容，应用的补丁仍将保持不变。这是因为提供了快照 ID。
**同时使用基准覆盖和安装覆盖列表**
您不能同时使用这两个参数。如果提供了两个参数，则修补文档将失败，并且不会在托管式节点上执行任何扫描或安装。
## 代码示例
以下 Python 代码示例说明了如何生成补丁基准覆盖。
```
import boto3
import json
ssm = boto3.client('ssm')
s3 = boto3.resource('s3')
s3_bucket_name = 'my-baseline-override-bucket'
s3_file_name = 'MyBaselineOverride.json'
baseline_ids_to_export = ['pb-0000000000000000', 'pb-0000000000000001']
baseline_overrides = []
for baseline_id in baseline_ids_to_export:
baseline_overrides.append(ssm.get_patch_baseline(
BaselineId=baseline_id
))
json_content = json.dumps(baseline_overrides, indent=4, sort_keys=True, default=str)
s3.Object(bucket_name=s3_bucket_name, key=s3_file_name).put(Body=json_content)
```
这将产生类似下面的补丁基准覆盖。
```
[
{
"ApprovalRules": {
"PatchRules": [
{
"ApproveAfterDays": 0,
"ComplianceLevel": "UNSPECIFIED",
"EnableNonSecurity": false,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"*"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"*"
]
},
{
"Key": "SEVERITY",
"Values": [
"*"
]
}
]
}
}
]
},
"ApprovedPatches": [],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"GlobalFilters": {
"PatchFilters": []
},
"OperatingSystem": "AMAZON_LINUX_2",
"RejectedPatches": [],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"Sources": []
},
{
"ApprovalRules": {
"PatchRules": [
{
"ApproveUntilDate": "2021-01-06",
"ComplianceLevel": "UNSPECIFIED",
"EnableNonSecurity": true,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"*"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"*"
]
},
{
"Key": "SEVERITY",
"Values": [
"*"
]
}
]
}
}
]
},
"ApprovedPatches": [
"open-ssl*"
],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"GlobalFilters": {
"PatchFilters": []
},
"OperatingSystem": "SUSE",
"RejectedPatches": [
"python*"
],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"Sources": []
}
]
```
# 补丁基准
本节主题介绍当您在托管式节点上运行 `Scan` 或 `Install` 操作时，补丁基准在Patch Manager（AWS Systems Manager 中的一项工具）中的工作方式。
**Topics**
+ [预定义和自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md)
+ [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)
+ [补丁组](patch-manager-patch-groups.md)
+ [Microsoft 在 Windows Server 上发布的补丁应用程序](patch-manager-patching-windows-applications.md)
# 预定义和自定义补丁基准
Patch Manager（AWS Systems Manager 中的一项工具）为Patch Manager支持的每个操作系统提供预定义补丁基准。您可以按照当前配置的方式使用这些基准（无法自定义它们），也可以创建您自己的自定义补丁基准。自定义补丁基准允许您更好地控制在您的环境下批准或拒绝哪些补丁。此外，预定义基准会为使用这些基准安装的所有补丁分配 `Unspecified` 合规性级别。对于要分配的合规性值，您可以创建预定义基准的副本，并指定要分配给补丁的合规性值。有关更多信息，请参阅[自定义基准](#patch-manager-baselines-custom)和[使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
**注意**
无论您使用哪种方法或类型的配置进行修补操作，本主题中的信息均适用：
Quick Setup 中配置的补丁策略
Quick Setup 中配置的主机管理选项
运行补丁 `Scan` 或 `Install` 任务的维护时段
按需 **Patch now**（立即修补）操作
**Topics**
+ [预定义基准](#patch-manager-baselines-pre-defined)
+ [自定义基准](#patch-manager-baselines-custom)
## 预定义基准
下表介绍了 Patch Manager 提供的预定义补丁基准。
有关 Patch Manager 支持各操作系统的哪些版本的信息，请参阅 [Patch Manager 先决条件](patch-manager-prerequisites.md)。
****
| 名称 | 支持的操作系统 | Details |
| --- | --- | --- |
| `AWS-AlmaLinuxDefaultPatchBaseline` | AlmaLinux | 批准分类为“Security”且严重性等级为“关键”或“重要”的所有操作系统补丁。还批准分类为“Bugfix”的所有补丁。补丁将在发布或更新后 7 天自动批准。¹ |
| AWS-AmazonLinux2DefaultPatchBaseline | Amazon Linux 2 | 批准分类为“Security”且严重性等级为“关键”或“重要”的所有操作系统补丁。还批准分类为“缺陷修正”的所有补丁。补丁将在发布后 7 天自动批准。¹ |
| AWS-AmazonLinux2023DefaultPatchBaseline | Amazon Linux 2023 | 批准分类为“Security”且严重性等级为“关键”或“重要”的所有操作系统补丁。补丁将在发布后七天自动批准。在发布 7 天后还批准分类为“缺陷修正”的所有补丁。 |
| AWS-CentOSDefaultPatchBaseline | CentOS Stream | 在所有更新可用 7 天后批准这些更新（包括非安全性更新）。 |
| AWS-DebianDefaultPatchBaseline | Debian Server | 立即批准优先级为“Required”、“Important”、“Standard”、“Optional”或“Extra”的与操作系统安全相关的所有补丁。由于存储库中未提供可靠的发布日期，因此批准之前无需等待。 |
| AWS-MacOSDefaultPatchBaseline | macOS | 批准分类为“Security”的所有操作系统补丁。同时批准具有当前更新的所有软件包。 |
| AWS-OracleLinuxDefaultPatchBaseline | Oracle Linux | 批准分类为“Security”且严重性等级为“重要”或“中等”的所有操作系统补丁。在发布 7 天后还批准分类为“Bugfix”的所有补丁。补丁将在发布或更新后 7 天自动批准。¹ |
| `AWS-RedHatDefaultPatchBaseline` | Red Hat Enterprise Linux (RHEL) | 批准分类为“Security”且严重性等级为“关键”或“重要”的所有操作系统补丁。还批准分类为“Bugfix”的所有补丁。补丁将在发布或更新后 7 天自动批准。¹ |
| `AWS-RockyLinuxDefaultPatchBaseline` | Rocky Linux | 批准分类为“Security”且严重性等级为“关键”或“重要”的所有操作系统补丁。还批准分类为“Bugfix”的所有补丁。补丁将在发布或更新后 7 天自动批准。¹ |
| AWS-SuseDefaultPatchBaseline | SUSE Linux Enterprise Server (SLES) | 批准分类为“Security”且严重性为“严重”或“重要”的所有操作系统补丁。补丁将在发布或更新后 7 天自动批准。¹ |
| `AWS-UbuntuDefaultPatchBaseline` | Ubuntu Server | 立即批准优先级为“Required”、“Important”、“Standard”、“Optional”或“Extra”的与操作系统安全相关的所有补丁。由于存储库中未提供可靠的发布日期，因此批准之前无需等待。 |
| AWS-DefaultPatchBaseline | Windows Server | 批准分类为“CriticalUpdates”或“SecurityUpdates”且 MSRC 严重性为“严重”或“重要”的所有 Windows Server 操作系统补丁。补丁将在发布或更新后 7 天自动批准。² |
| AWS-WindowsPredefinedPatchBaseline-OS | Windows Server | 批准分类为“CriticalUpdates”或“SecurityUpdates”且 MSRC 严重性为“严重”或“重要”的所有 Windows Server 操作系统补丁。补丁将在发布或更新后 7 天自动批准。² |
| AWS-WindowsPredefinedPatchBaseline-OS-Applications | Windows Server | 对于 Windows Server 操作系统，批准分类为“CriticalUpdates”或“SecurityUpdates”且 MSRC 严重性为“严重”或“重要”的所有补丁。对于 Microsoft 发布的应用程序，批准所有补丁。在发布或更新后 7 天自动批准操作系统和应用程序的补丁。² |
¹ 对于 Amazon Linux 2，补丁自动批准前的 7 天等待时间根据 `updateinfo.xml` 中的 `Updated Date` 值，而不是 `Release Date` 值计算。有多种因素会影响 `Updated Date` 值。其他操作系统处理发布和更新日期的方式有所不同。有关帮助您避免自动批准延迟的意外结果的信息，请参阅 [如何计算软件包发布日期和更新日期](patch-manager-release-dates.md)。
² 对于 Windows Server，默认基准包括 7 天的自动批准延迟。要在发布后 7 天内安装补丁，您必须创建自定义基准。
## 自定义基准
使用以下信息来帮助您创建自定义补丁基准以符合修补目标。
**Topics**
+ [在自定义基准中使用自动批准](#baselines-auto-approvals)
+ [有关创建补丁基准的其他信息](#baseline-additional-info)
### 在自定义基准中使用自动批准
如果您创建自己的补丁基准，则可使用以下类别选择自动批准哪些补丁。
+ **操作系统**：受支持的 Windows Server、Amazon Linux、Ubuntu Server 等版本。
+ **产品名称**（对于操作系统）：例如，RHEL 7.5、Amazon Linux 2023 2023.8.20250808、Windows Server 2012、Windows Server 2012 R2 等。
+ **产品名称**（仅对于 Windows Server 上 Microsoft 发布的应用程序）：例如，Word 2016、BizTalk 服务器等。
+ **分类**：例如，关键更新、安全更新等。
+ **严重性**：例如，关键、重要等。
对于您创建的每个批准规则，您可以选择指定自动批准延迟或指定补丁批准截止日期。
**注意**
由于无法可靠地确定 Ubuntu Server 的更新程序包的发布日期，因此此操作系统不支持自动批准选项。
自动批准延迟是发布或最后更新补丁后到自动批准补丁用于修补前等待的天数。例如，如果您使用 `CriticalUpdates` 分类创建一条规则并将其自动批准延迟配置为 7 天，则将在 7 月 14 日自动批准 7 月 7 日发布的新关键补丁。
如果 Linux 存储库未提供软件包的发布日期信息，Patch Manager 会将软件包的构建时间用作符合 Amazon Linux 2、Amazon Linux 2023 和 Red Hat Enterprise Linux (RHEL) 自动批准日期规范的日期。如果无法确定软件包的构建时间，Patch Manager 会使用默认日期 1970 年 1 月 1 日。这将导致 Patch Manager 绕过补丁基准（配置为批准 1970 年 1 月 1 日之后任一日期发布的补丁）中的所有自动批准日期规范。
当您指定自动批准截止日期时，Patch Manager 会自动应用在该日期或之前发布或最后更新的所有补丁。例如，如果将 2023 年 7 月 7 日指定为截止日期，系统都不会自动安装于 2023 年 7 月 8 日或之后发布或最后更新的所有补丁。
创建自定义补丁基准时，您可以为此补丁基准批准的补丁指定合规性严重性级别，例如 `Critical` 或 `High`。如果任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
### 有关创建补丁基准的其他信息
创建补丁基准时，请牢记以下信息：
+ Patch Manager 为每个受支持的操作系统提供一个预定义的补丁基准。这些预定义的补丁基准将被用作每个操作系统类型的默认补丁基准，除非您创建自己的补丁基准，并将其指定为相应操作系统类型的默认补丁基准。
**注意**
适用于 Windows Server，提供三个预定义的补丁基准。补丁基准 `AWS-DefaultPatchBaseline` 和 `AWS-WindowsPredefinedPatchBaseline-OS` 仅支持 Windows 操作系统本身的操作系统更新。除非您指定了其他补丁基准，`AWS-DefaultPatchBaseline` 用作 Windows Server 托管式节点的默认补丁基准。这两个补丁基准中的配置设置是相同的。两者中较新的,`AWS-WindowsPredefinedPatchBaseline-OS` 被创建来区分它和 Windows Server 的第三个预定义补丁基准。补丁基准 `AWS-WindowsPredefinedPatchBaseline-OS-Applications`，可用于将补丁应用到 Windows Server 操作系统和 Microsoft 发布的受支持的应用程序。
+ 默认情况下，Windows Server 2019 和 Windows Server 2022 会移除由较新更新所取代的更新。因此，如果您在 Windows Server 补丁基准中使用 `ApproveUntilDate` 参数，但 `ApproveUntilDate` 参数中选择的日期早于最新补丁发布的日期，则在运行修补操作时，不会安装新的补丁。有关 Windows Server 修补规则的更多信息，请参阅 [如何选择安全性补丁](patch-manager-selecting-patches.md) 中的 Windows Server 选项卡。
这意味着托管节点在 Systems Manager 操作方面是合规的，即使可能未安装上个月的关键补丁亦是如此。使用 `ApproveAfterDays` 参数时也可能出现同样的情况。由于 Microsoft 取代的补丁行为，可以设置一个数字（通常大于 30 天），这样，如果 Microsoft 的最新可用补丁是在经过 `ApproveAfterDays` 中的天数之前发布的，则绝不会安装 Windows Server 的补丁。
+ 仅对于 Windows Server：未经补丁基准批准的可用安全更新补丁可以具有合规性值 `Compliant` 或 `Non-Compliant`，如自定义补丁基准中所定义。
创建或更新补丁基准时，需选择要分配给可用但尚未批准的安全补丁（这些补丁由于不符合补丁基准中指定的安装标准而未获批准）的状态。例如，如果您指定在补丁发布后等待较长时间再进行安装，则会跳过某些您可能希望安装的安全补丁。如果在您指定的等待期内发布了该补丁的更新版本，则该补丁的安装等待期将重新开始。如果等待期过长，则可能会发布多个版本的补丁，但不会进行安装。
通过控制台创建或更新补丁基准，需在**可用安全更新合规性状态**字段中指定此选项。通过 AWS CLI 运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-patch-baseline.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-patch-baseline.html) 或 [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-patch-baseline.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-patch-baseline.html) 命令时，需在 `available-security-updates-compliance-status` 参数中指定此选项。
+ 对于本地服务器和虚拟机 (VM)，Patch Manager 尝试使用您的自定义默认补丁基准。如果不存在自定义默认补丁基准，系统将使用相应操作系统的预定义补丁基准。
+ 如果某个补丁在相同的补丁基准中同时被列为已批准和已拒绝，则该补丁将被拒绝。
+ 一个托管式节点只能有一个定义的补丁基准。
+ 可以添加到补丁基准的已批准补丁和已拒绝补丁列表中的软件包名称格式取决于您正在修补的操作系统的类型。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ 如果您在 Quick Setup 中使用[补丁策略配置](patch-manager-policies.md)，则系统会每小时与 Quick Setup 同步一次您对自定义补丁基准所做的更新。
如果删除了补丁策略中引用的自定义补丁基准，那么补丁策略的 Quick Setup **Configuration details**（配置详细信息）页面上会显示一个横幅。横幅将通知您，补丁策略引用的补丁基准已不存在，且后续的修补操作将失败。在这种情况下，返回 Quick Setup **Configurations**（配置）页面，选择 Patch Manager 配置，然后选择 **Actions**（操作），**Edit configuration**（编辑配置）。已删除的补丁基准名称将突出显示，您必须为受影响的操作系统选择新的补丁基准。
+ 当您创建包含多个 `Classification` 和 `Severity` 值的批准规则时，将根据补丁的可用属性对其进行批准。同时包含 `Classification` 和 `Severity` 属性的软件包将匹配两个字段的选定基准值。仅包含 `Classification` 属性的软件包仅匹配选定的基准 `Classification` 值。对于没有 `Severity` 属性的软件包，将忽略同一规则中的严重性要求。
有关创建补丁基准的信息，请参阅 [使用自定义补丁基准](patch-manager-manage-patch-baselines.md) 和 [教程：使用 AWS CLI 修补服务器环境](patch-manager-patch-servers-using-the-aws-cli.md)。
# 已批准补丁和已拒绝补丁列表的程序包名称格式
可以添加到已批准补丁和已拒绝补丁列表中的软件包名称格式取决于您正在修补的操作系统的类型。
## 适用于 Linux 操作系统的软件包名称格式
您可以在补丁基准中为已批准和已拒绝补丁指定的格式因 Linux 类型而异。更具体地说，支持的格式取决于 Linux 操作系统类型使用的软件包管理器。
**Topics**
+ [Amazon Linux 2、Amazon Linux 2023、Oracle Linux 和 Red Hat Enterprise Linux（RHEL）](#patch-manager-approved-rejected-package-name-formats-standard)
+ [Debian Server 和 Ubuntu Server](#patch-manager-approved-rejected-package-name-formats-ubuntu)
+ [SUSE Linux Enterprise Server (SLES)](#patch-manager-approved-rejected-package-name-formats-sles)
### Amazon Linux 2、Amazon Linux 2023、Oracle Linux 和 Red Hat Enterprise Linux（RHEL）
**软件包管理器**：YUM（Amazon Linux 2023 除外）和 RHEL 8，使用 DNF 作为软件包管理器。
**已批准的补丁**：对于已批准的补丁，您可以指定以下任一项：
+ Bugzilla ID，格式为 `1234567` (将只包含系统进程编号的字符串作为 Bugzilla ID。)
+ CVE ID，格式为 `CVE-2018-1234567`
+ 公告 ID，格式为 `RHSA-2017:0864` 和 `ALAS-2018-123`
+ 使用一个或多个可用于软件包命名的组件构造的软件包名称。举例来说，对于名为 `dbus.x86_64:1:1.12.28-1.amzn2023.0.1` 的软件包，组件如下：
+ `name`: `dbus`
+ `architecture`: `x86_64`
+ `epoch`: `1`
+ `version`: `1.12.28`
+ `release`: `1.amzn2023.0.1`
支持具有以下构造的软件包名称：
+ `name`
+ `name.arch`
+ `name-version`
+ `name-version-release`
+ `name-version-release.arch`
+ `version`
+ `version-release`
+ `epoch:version-release`
+ `name-epoch:version-release`
+ `name-epoch:version-release.arch`
+ `epoch:name-version-release.arch`
+ `name.arch:epoch:version-release`
一些示例：
+ `dbus.x86_64`
+ `dbus-1.12.28`
+ `dbus-1.12.28-1.amzn2023.0.1`
+ `dbus-1:1.12.28-1.amzn2023.0.1.x86_64`
+ 我们还支持上述格式带有单个通配符的软件包名称组件，例如：
+ `dbus*`
+ `dbus-1.12.2*`
+ `dbus-*:1.12.28-1.amzn2023.0.1.x86_64`
**已拒绝的补丁**：对于已拒绝的补丁，您可以指定以下任一项：
+ 使用一个或多个可用于软件包命名的组件构造的软件包名称。举例来说，对于名为 `dbus.x86_64:1:1.12.28-1.amzn2023.0.1` 的软件包，组件如下：
+ `name`: `dbus`
+ `architecture`; `x86_64`
+ `epoch`: `1`
+ `version`: `1.12.28`
+ `release`: `1.amzn2023.0.1`
支持具有以下构造的软件包名称：
+ `name`
+ `name.arch`
+ `name-version`
+ `name-version-release`
+ `name-version-release.arch`
+ `version`
+ `version-release`
+ `epoch:version-release`
+ `name-epoch:version-release`
+ `name-epoch:version-release.arch`
+ `epoch:name-version-release.arch`
+ `name.arch:epoch:version-release`
一些示例：
+ `dbus.x86_64`
+ `dbus-1.12.28`
+ `dbus-1.12.28-1.amzn2023.0.1`
+ `dbus-1:1.12.28-1.amzn2023.0.1.x86_64`
+ 我们还支持上述格式带有单个通配符的软件包名称组件，例如：
+ `dbus*`
+ `dbus-1.12.2*`
+ `dbus-*:1.12.28-1.amzn2023.0.1.x86_64`
### Debian Server 和 Ubuntu Server
**软件包管理器**：APT
**已批准的补丁**和**已拒绝的补丁**：对于已批准和已拒绝的补丁，指定以下内容：
+ 软件包名称，格式为 `ExamplePkg33`
**注意**
对于 Debian Server 列表和 Ubuntu Server 列表，不包括架构或版本等元素。例如，您可以指定软件包名称 `ExamplePkg33` 以在补丁列表中包含所有以下项：
`ExamplePkg33.x86.1`
`ExamplePkg33.x86.2`
`ExamplePkg33.x64.1`
`ExamplePkg33.3.2.5-364.noarch`
### SUSE Linux Enterprise Server (SLES)
**软件包管理器**：Zypper
**已批准的补丁**和**已拒绝的补丁**：对于已批准和已拒绝的补丁列表，可以指定以下任一项：
+ 完整软件包名称，格式为：
+ `SUSE-SLE-Example-Package-15-2023-123`
+ `example-pkg-2023.15.4-46.17.1.x86_64.rpm`
+ 包含单个通配符的软件包名称，例如：
+ `SUSE-SLE-Example-Package-15-2023-*`
+ `example-pkg-2023.15.4-46.17.1.*.rpm`
## macOS适用的软件包名称格式
**受支持的软件包管理器**: softwareupdate、 installer、 Brew、 Brew Cask
**已批准的补丁**和**已拒绝的补丁**：对于已批准和已拒绝的补丁列表，可以指定完整的软件包名称，格式如下：
+ `XProtectPlistConfigData`
+ `MRTConfigData`
对于 macOS，在已批准补丁和已拒绝的补丁列表中不支持通配符。
## 适用于 Windows 操作系统的软件包名称格式
对于 Windows 操作系统，请使用 Microsoft 知识库 ID 和 Microsoft 安全公告 ID 指定补丁；例如：
```
KB2032276,KB2124261,MS10-048
```
# 补丁组
**注意**
补丁组不会用于基于*补丁策略*的修补操作。有关使用补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
对于在 2022 年 12 月 22 日发布补丁策略支持之前尚未使用补丁组的账户-区域对，控制台不支持补丁组功能。补丁组功能在此日期之前开始使用补丁组的账户区域对中仍然可用。
您可以使用*补丁组*，将托管式节点与Patch Manager（AWS Systems Manager 中的一项工具）中的特定补丁基准关联。补丁组根据关联的补丁基准规则，帮助确保您将合适的补丁部署到正确的节点集。另外还可以帮助您避免过早地部署补丁（在对补丁进行充分测试之前）。例如，您可以为不同的环境（例如，开发环境、测试环境和生产环境）创建补丁组，并将每个补丁组注册到合适的补丁基准。
运行 `AWS-RunPatchBaseline` 或其他 SSM 命令文档进行修补时，您可以使用托管式节点 ID 或标签，将托管式节点设为目标。SSM Agent 和 Patch Manager 会基于您添加到托管式节点的补丁组值评估要使用的补丁基准。
## 通过标签定义补丁组
您可以使用应用于[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的 Amazon Elastic Compute Cloud（Amazon EC2）实例和非 EC2 节点来创建补丁组。通过标签定义补丁组时，请注意以下详细信息：
+
必须使用应用于托管式节点的标签键 `Patch Group` 或 `PatchGroup` 来定义补丁组。为补丁基准注册补丁组时，为这两个键指定的任何相同*值*都将解释为属于同一补丁组。例如，假设您使用以下第一个键值对标记了五个节点，并使用第二个键值对标记了五个节点：
+ `key=PatchGroup,value=DEV`
+ `key=Patch Group,value=DEV`
用于创建补丁基准的 Patch Manager 命令会根据值 `DEV`，将这 10 个托管式节点合并成一个组。为补丁组创建补丁基准的命令的 AWS CLI 等效命令如下所示：
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id pb-0c10e65780EXAMPLE \
--patch-group DEV
```
将来自不同键的值合并到同一目标是该 Patch Manager 命令所独有的，旨在创建新的补丁组，其他 API 操作则不支持。例如，如果您使用具有相同值的 `PatchGroup` 和 `Patch Group` 键运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) 操作，则您的目标将是两组完全不同的节点：
```
aws ssm send-command \
--document-name AWS-RunPatchBaseline \
--targets "Key=tag:PatchGroup,Values=DEV"
```
```
aws ssm send-command \
--document-name AWS-RunPatchBaseline \
--targets "Key=tag:Patch Group,Values=DEV"
```
+ 基于标签的目标有限制。`SendCommand` 的每个目标数组最多可以包含五个键值对。
+ 建议您只选择其中一个标签键约定，`PatchGroup`（不带空格）或 `Patch Group`（带空格）。但是，如果允许在实例上的 [EC2 实例元数据中使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`。
+ 请注意，此键区分大小写。您可以指定任何*值*来帮助您识别和定位该组中的资源，例如“web servers”或“US-EAST-PROD”，但键必须是 `Patch Group` 或 `PatchGroup`。
创建补丁组和标记托管式节点后，可以使用补丁基准注册补丁组。将补丁组注册到补丁基准可确保补丁组内的节点使用关联的补丁基准中定义的规则。
有关如何创建补丁组并将补丁组与补丁基准关联的更多信息，请参阅 [创建和管理补丁组](patch-manager-tag-a-patch-group.md) 和 [将补丁组添加到补丁基准](patch-manager-tag-a-patch-group.md#sysman-patch-group-patchbaseline)。
要查看使用 AWS Command Line Interface (AWS CLI) 创建补丁基准和补丁组的示例，请参阅 [教程：使用 AWS CLI 修补服务器环境](patch-manager-patch-servers-using-the-aws-cli.md)。有关使用 Amazon EC2 标签的信息，请参阅《Amazon EC2 用户指南》**中的[标记您的 Amazon EC2 资源](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)。
## 工作方式
当系统运行将补丁基准应用于托管式节点的任务时，SSM Agent 会验证是否为该节点定义了补丁组值。如果该节点已分配给一个补丁组，Patch Manager 会验证哪个补丁基准注册到了该组。如果找到了该组的补丁基准，Patch Manager 将通知 SSM Agent 使用关联的补丁基准。如果没有为补丁组配置节点，Patch Manager 会自动通知 SSM Agent 使用当前配置的默认补丁基准。
**重要**
一个托管式节点只能在一个补丁组中。
对每个操作系统类型，一个补丁组只能注册一个补丁基准。
如果在实例上启用 **Allow tags in instance metadata**（允许在实例元数据中使用标签）选项，则无法将 `Patch Group` 标签（带空格）应用于 Amazon EC2 实例。允许在实例元数据中使用标签会导致标签密钥名称不得包含空格。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用标签键 `PatchGroup`（不带空格）。
**图 1：修补操作流程的一般示例**
下图显示了 Systems Manager 在将 Run Command 任务发送到您的服务器实例集以使用 Patch Manager 进行修补时执行的流程的一般示例。这些流程决定了在修补操作中使用哪些补丁基准。（当维护时段配置为使用 Patch Manager 发送命令进行修补时，会使用类似的流程。）
整个流程如下图所示。
![\[用于确定在执行修补操作时要使用哪些补丁基准的 Patch Manager 工作流。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/patch-groups-how-it-works.png)
在本示例中，我们有三组 Windows Server EC2 实例，其应用了以下标签：
****
| EC2 实例组 | 标签 |
| --- | --- |
| 组 1 | `key=OS,value=Windows` `key=PatchGroup,value=DEV` |
| 组 2 | `key=OS,value=Windows` |
| 组 3 | `key=OS,value=Windows` `key=PatchGroup,value=QA` |
在本示例中，我们还有这两个 Windows Server 补丁基准：
****
| 补丁基准 ID | 默认 | 关联的补丁组 |
| --- | --- | --- |
| `pb-0123456789abcdef0` | 是 | `Default` |
| `pb-9876543210abcdef0` | 否 | `DEV` |
使用 Run Command（AWS Systems Manager 中的一项工具）和Patch Manager扫描或安装补丁的一般流程，如下所示：
1. **发送修补命令**：使用 Systems Manager 控制台、SDK、 AWS Command Line Interface (AWS CLI) 或 AWS Tools for Windows PowerShell 使用文档 `AWS-RunPatchBaseline` 发送 Run Command 任务。该图显示了将标签 `key=OS,value=Windows` 指定为目标执行修补托管实例的 Run Command 任务。
1. **补丁基准确定**：SSM Agent 验证应用到 EC2 实例的补丁组标签，并查询 Patch Manager 查找相应的补丁基准。
+ **与补丁基准关联的匹配的补丁组值：**
1. 在组 1 中的 EC2 实例上安装的 SSM Agent 收到步骤 1 中发出的命令后开始修补操作。SSM Agent 验证 EC2 实例是否应用了补丁组标签值 `DEV` 并查询 Patch Manager 以查找关联的补丁基准。
1. Patch Manager 验证补丁基准 `pb-9876543210abcdef0` 是否关联了补丁组 `DEV` 并通知 SSM Agent。
1. SSM Agent 根据在 `pb-9876543210abcdef0` 中配置的批准规则和例外从 Patch Manager 检索补丁基准快照，然后继续执行下一步。
+ **未将补丁组标签添加到实例：**
1. 在组 2 中的 EC2 实例上安装的 SSM Agent 收到步骤 1 中发出的命令后开始修补操作。SSM Agent 验证 EC2 实例是否未应用 `Patch Group` 或 `PatchGroup` 标签，并因此 SSM Agent 查询 Patch Manager 以查找默认的 Windows 补丁基准。
1. Patch Manager 验证默认的 Windows Server 补丁基准是否是 `pb-0123456789abcdef0` 并通知 SSM Agent。
1. SSM Agent 根据在默认的补丁基准 `pb-0123456789abcdef0` 中配置的批准规则和例外从 Patch Manager 检索补丁基准快照，然后继续执行下一步。
+ **没有与补丁基准关联的匹配的补丁组值：**
1. 在组 3 中的 EC2 实例上安装的 SSM Agent 收到步骤 1 中发出的命令后开始修补操作。SSM Agent 验证 EC2 实例是否应用了补丁组标签值 `QA` 并查询 Patch Manager 以查找关联的补丁基准。
1. Patch Manager 没有找到关联了补丁组 `QA` 的补丁基准。
1. Patch Manager 通知 SSM Agent 使用默认的 Windows 补丁基准 `pb-0123456789abcdef0`。
1. SSM Agent 根据在默认的补丁基准 `pb-0123456789abcdef0` 中配置的批准规则和例外从 Patch Manager 检索补丁基准快照，然后继续执行下一步。
1. **补丁扫描或安装**：确定要使用的合适的补丁基准后，SSM Agent 将根据步骤 1 中指定的操作值开始扫描或安装补丁。扫描或安装的补丁由在 Patch Manager 提供的补丁基准快照中定义的批准规则和补丁例外确定。
**更多信息**
+ [补丁合规性状态值](patch-manager-compliance-states.md)
# Microsoft 在 Windows Server 上发布的补丁应用程序
使用本主题中的信息可帮助您准备好使用Patch Manager（AWS Systems Manager 中的一项工具）在 Windows Server 上修补应用程序。
**Microsoft 应用程序修补**
对 Windows Server 托管式节点上应用程序的修补支持，仅限于 Microsoft 发布的应用程序。
**注意**
在某些情况下，Microsoft 会为未指定更新日期和时间的应用程序发布补丁。在这些情况下，系统会默认提供 `01/01/1970` 的更新日期和时间。
**修补 Microsoft 发布的应用程序的补丁基准**
适用于 Windows Server，提供三个预定义的补丁基准。补丁基准 `AWS-DefaultPatchBaseline` 和 `AWS-WindowsPredefinedPatchBaseline-OS` 仅支持 Windows 操作系统本身的操作系统更新。除非您指定了其他补丁基准，`AWS-DefaultPatchBaseline` 用作 Windows Server 托管式节点的默认补丁基准。这两个补丁基准中的配置设置是相同的。两者中较新的,`AWS-WindowsPredefinedPatchBaseline-OS` 被创建来区分它和 Windows Server 的第三个预定义补丁基准。补丁基准 `AWS-WindowsPredefinedPatchBaseline-OS-Applications`，可用于将补丁应用到 Windows Server 操作系统和 Microsoft 发布的受支持的应用程序。
您也可以创建自定义补丁基准，用来在 Windows Server 计算机上更新 Microsoft 发布的应用程序。
**支持在本地服务器、边缘设备、VM 和其他非 EC2 节点上修补由 Microsoft 发布的应用程序**
要在虚拟机（VM）和其他非 EC2 托管式节点上修补 Microsoft 发布的应用程序，必须打开高级实例套餐。使用高级实例套餐需支付费用。**但是，修补 Microsoft 在 Amazon Elastic Compute Cloud (Amazon EC2) 实例上发布的应用程序不收取额外费用。**有关更多信息，请参阅 [配置实例套餐](fleet-manager-configure-instance-tiers.md)。
**“其他微软产品”的 Windows 更新选项**
为了让 Patch Manager 能够在 Windows Server 托管式节点上修补 Microsoft 发布的应用程序，必须在托管式节点上启用 Windows 更新选项 **Give me updates for other Microsoft products when I update Windows**（更新 Windows 时向我提供其他 Microsoft 产品的更新）。
有关在单个托管式节点上允许此选项的信息，请参阅 Microsoft 支持网站上的[使用 Microsoft 更新更新 Office](https://support.microsoft.com/en-us/office/update-office-with-microsoft-update-f59d3f9d-bd5d-4d3b-a08e-1dd659cf5282)。
对于运行 Windows Server 2016 及更高版本的托管式节点机群，您可以使用组策略对象 (GPO) 打开设置。在组策略管理编辑器中，转到**计算机配置**、**管理模板**、**Windows 组件**、**Windows 更新**，然后选择**安装其他 Microsoft 产品的更新**。我们还建议使用其他参数配置 GPO，以防止在 Patch Manager 之外意外自动更新和重启。有关更多信息，请参阅 Microsoft 技术文档网站上的 [Configuring Automatic Updates in a Non-Active Directory Environment](https://docs.microsoft.com/de-de/security-updates/windowsupdateservices/18127499)（在非 Active Directory 环境中配置自动更新）。
对于运行 Windows Server 2012 或 2012 R2 的托管式节点机群，您可以使用脚本打开该选项，如 Microsoft 文档博客网站上的[通过脚本在 Windows 7 中启用和禁用 Microsoft 更新](https://docs.microsoft.com/en-us/archive/blogs/technet/danbuche/enabling-and-disabling-microsoft-update-in-windows-7-via-script)中所述。例如，可以：
1. 将脚本从博客文章保存在文件中。
1. 将文件上传到 Amazon Simple Storage Service (Amazon S3) 存储桶或其他可访问的位置。
1. 使用 Run Command（AWS Systems Manager 中的一项工具），通过 Systems Manager 文档（SSM 文档）`AWS-RunPowerShellScript` 在托管式节点上运行脚本，所使用的命令类似于以下内容。
```
Invoke-WebRequest `
-Uri "https://s3.aws-api-domain/amzn-s3-demo-bucket/script.vbs" `
-Outfile "C:\script.vbs" cscript c:\script.vbs
```
**最低参数要求**
要在自定义补丁基准中包括 Microsoft 发布的应用程序，您必须至少指定要修补的产品。下面的 AWS Command Line Interface (AWS CLI) 命令演示了修补产品（如 Microsoft Office 2016）的最低要求：
------
#### [ Linux & macOS ]
```
aws ssm create-patch-baseline \
--name "My-Windows-App-Baseline" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT,Values='Office 2016'},{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"
```
------
#### [ Windows Server ]
```
aws ssm create-patch-baseline ^
--name "My-Windows-App-Baseline" ^
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT,Values='Office 2016'},{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"
```
------
如果您指定了 Microsoft 应用程序产品系列，您指定的每个产品都必须是所选产品系列的受支持的成员产品。例如，要修补产品“Active Directory Rights Management Services Client 2.0”，您必须将其产品系列指定为“Active Directory”，而不是“Office”或“SQL Server”（举例）。下面的 AWS CLI 命令演示了一对匹配的产品系列和产品。
------
#### [ Linux & macOS ]
```
aws ssm create-patch-baseline \
--name "My-Windows-App-Baseline" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT_FAMILY,Values='Active Directory'},{Key=PRODUCT,Values='Active Directory Rights Management Services Client 2.0'},{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"
```
------
#### [ Windows Server ]
```
aws ssm create-patch-baseline ^
--name "My-Windows-App-Baseline" ^
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=PRODUCT_FAMILY,Values='Active Directory'},{Key=PRODUCT,Values='Active Directory Rights Management Services Client 2.0'},{Key=PATCH_SET,Values='APPLICATION'}]},ApproveAfterDays=5}]"
```
------
**注意**
如果收到有关产品和系列配对不匹配的错误消息，请参阅 [问题：产品系列/产品对不匹配](patch-manager-troubleshooting.md#patch-manager-troubleshooting-product-family-mismatch) 以获取帮助解决问题。
# 在 Amazon Linux 2 托管式节点上使用 Kernel Live Patching
适用于 Amazon Linux 2 的 Kernel Live Patching 使您能够将安全漏洞和严重错误补丁应用于正在运行的 Linux 内核，而无需重启或中断正在运行的应用程序。这让您能够从改进的服务和应用程序可用性中受益，同时保持基础设施的安全和最新状态。在运行 Amazon Linux 2 的 Amazon EC2 实例、Kernel Live Patching 核心设备和[本地虚拟机](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-2-virtual-machine.html)上支持 AWS IoT Greengrass。
有关 Kernel Live Patching 的一般信息，请参阅 *Amazon Linux 2 User Guide* 中的 [Kernel Live Patching on AL2](https://docs.aws.amazon.com/linux/al2/ug/al2-live-patching.html)。
在 Amazon Linux 2 托管式节点上启用 Kernel Live Patching 之后，您可使用Patch Manager（AWS Systems Manager 中的一项工具）将内核实时补丁应用到托管式节点。使用 Patch Manager 是使用节点上的现有 yum 工作流来应用更新的替代方法。
**开始前的准备工作**
要使用 Patch Manager 将内核实时补丁应用到 Amazon Linux 2 托管式节点上，请确保节点基于正确的架构和内核版本。要了解有关信息，请参阅《Amazon EC2 用户指南》**中的[支持的配置和先决条件](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/al2-live-patching.html#al2-live-patching-prereq)。
**Topics**
+ [使用 Patch Manager 的 Kernel Live Patching](#about-klp)
+ [使用 Patch Manager 的 Kernel Live Patching 的原理](#how-klp-works)
+ [使用 Run Command 来启用 Kernel Live Patching](enable-klp.md)
+ [使用 Run Command 应用内核实时补丁](install-klp.md)
+ [使用 Run Command 来关闭 Kernel Live Patching](disable-klp.md)
## 使用 Patch Manager 的 Kernel Live Patching
更新内核版本
应用内核实时补丁更新后，无需重启托管式节点。但是，AWS 为 Amazon Linux 2 内核版本提供内核实时补丁，最长可达其发布后三个月。在三个月期限之后，您必须更新到更高版本的内核才能继续接收内核实时补丁。我们建议使用维护时段至少每三个月一次安排重启节点，以提示内核版本更新。
卸载内核实时补丁
无法使用 Patch Manager 卸载内核实时补丁。相反，您可以关闭 Kernel Live Patching，从而删除所应用的内核实时补丁的 RPM 程序包。有关更多信息，请参阅 [使用 Run Command 来关闭 Kernel Live Patching](disable-klp.md)。
内核合规性
在某些情况下，从当前内核版本的实时补丁安装所有 CVE 补丁可能会使该内核进入与较新内核版本相同的合规性状态。发生这种情况时，较新版本报告为 `Installed`，而托管式节点报告为 `Compliant`。但是，对于较新的内核版本，不会报告安装时间。
一个内核实时补丁，多个 CVE
如果一个内核实时补丁解决多个 CVE，并且这些 CVE 具有各种分类和严重性值，则只针对该补丁报告 CVE 中的最高分类和严重性。
本节的其余部分介绍如何使用 Patch Manager 将内核实时补丁应用于满足这些要求的托管式节点。
## 使用 Patch Manager 的 Kernel Live Patching 的原理
AWS 为 Amazon Linux 2 发布了两种类型的内核实时补丁：安全更新和错误修复。要应用这些补丁类型，请使用仅针对下表列出的分类和严重性的补丁基准文档。
| 分类 | 严重性 |
| --- | --- |
| Security | Critical, Important |
| Bugfix | All |
您可以创建仅针对这些补丁的自定义补丁基准，也可以使用预定义的 `AWS-AmazonLinux2DefaultPatchBaseline` 补丁基准。换句话说，您可以将 `AWS-AmazonLinux2DefaultPatchBaseline` 与启用 Kernel Live Patching 的 Amazon Linux 2 托管式节点一起使用，并且系统会应用内核实时更新。
**注意**
`AWS-AmazonLinux2DefaultPatchBaseline` 配置指定发布最后更新补丁后的 7 天等待期，然后才会自动安装补丁。如果您不想等待 7 天再自动批准内核实时补丁，则可以创建并使用自定义补丁基准。在补丁基准中，您可以不指定自动批准等待期，也可以指定较短或更长的等待期。有关更多信息，请参阅 [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
我们建议使用以下策略通过内核实时更新来修补托管式节点：
1. 在 Amazon Linux 2 托管式节点上启用 Kernel Live Patching。
1. 使用 Run Command（AWS Systems Manager 中的一项工具）在托管式节点上运行 `Scan` 操作，这些节点使用预定义 `AWS-AmazonLinux2DefaultPatchBaseline` 或自定义补丁基准，该基准也仅针对严重性分类为 `Critical` 和 `Important`，以及 `All` 的严重性为 `Bugfix` 的 `Security` 更新。
1. 使用 Compliance（AWS Systems Manager 中的一项工具）查看是否报告了任何被扫描托管式节点中存在不符合修补合规性的情况。如果是这样，请查看节点合规性详细信息，以确定托管式节点中是否缺少任何内核实时补丁。
1. 要安装缺少的内核实时补丁，请将 Run Command 与之前指定的相同补丁基准一起使用，但这次运行 `Install` 操作而不是 `Scan` 操作。
由于无需重启即可安装内核实时补丁，因此您可以为此操作选择 `NoReboot` 重启选项。
**注意**
如果托管式节点上安装的其他类型补丁需要，或者要更新到较新的内核，您仍然可以重启托管式节点。在这些情况下，请改为选择 `RebootIfNeeded` 重启选项。
1. 返回到合规性以验证安装了内核实时补丁。
# 使用 Run Command 来启用 Kernel Live Patching
要启用 Kernel Live Patching，您可以在托管式节点上运行 `yum` 命令，或使用 Run Command 以及您创建的自定义 Systems Manager 文档（SSM 文档）。
有关通过直接在托管式节点上运行 `yum` 命令来打开 Kernel Live Patching 的信息，请参阅《Amazon EC2 用户指南》**中的[启用 Kernel Live Patching](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/al2-live-patching.html#al2-live-patching-prereq)。
**注意**
当您启用内核实时修补时，如果已在托管式节点上运行的内核为比 `kernel-4.14.165-131.185.amzn2.x86_64`（支持的最低版本）*更早*，进程将安装最新的可用内核版本并重启托管式节点。如果节点已运行 `kernel-4.14.165-131.185.amzn2.x86_64` 或更高版本，进程不会安装更新的版本，也不会重启节点。
**使用 Run Command 来启用 Kernel Live Patching (控制台)**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档**列表中，选择自定义 SSM 文档 `AWS-ConfigureKernelLivePatching`。
1. 在 **Command parameters**（命令参数）部分中，指定是否希望作为此操作的一部分重启托管式节点。
1. 有关使用此页上的其余控件的信息，请参阅 [从控制台运行命令](running-commands-console.md)。
1. 选择**运行**。
**启用 Kernel Live Patching (AWS CLI)**
+ 在本地计算机上运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-ConfigureKernelLivePatching" \
--parameters "EnableOrDisable=Enable" \
--targets "Key=instanceids,Values=instance-id"
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-ConfigureKernelLivePatching" ^
--parameters "EnableOrDisable=Enable" ^
--targets "Key=instanceids,Values=instance-id"
```
------
将 *instance-id* 替换为要启用该功能的 Amazon Linux 2 托管式节点的 ID，例如 i-02573cafcfEXAMPLE。您可以使用以下任一格式，在多个托管式节点上启用该功能。
+ `--targets "Key=instanceids,Values=instance-id1,instance-id2"`
+ `--targets "Key=tag:tag-key,Values=tag-value"`
有关可以在命令中使用的其他选项的信息，请参阅《AWS CLI Command Reference》**中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
# 使用 Run Command 应用内核实时补丁
要应用内核实时补丁，您可以在托管式节点上运行 `yum` 命令，也可以使用 Run Command 和 SSM 文档 `AWS-RunPatchBaseline`。
有关通过在托管式节点上直接运行 `yum` 命令来应用内核实时补丁的信息，请参阅《Amazon EC2 用户指南》**中的[应用内核实时补丁](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/al2-live-patching.html#al2-live-patching-apply)。
**使用 Run Command 应用内核实时补丁（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档**列表中，请选择 SSM 文档 `AWS-RunPatchBaseline`。
1. 在 **Command parameters ( 命令参数)** 部分，执行以下操作之一：
+ 如果要检查是否有新的内核实时补丁，请对于 **Operation (操作)** 选择 `Scan`。对于 **Reboot Option**（重启选项），如果不希望托管式节点在此操作后重启，请选择 `NoReboot`。操作完成后，您可以在合规性中检查新的补丁和合规性状态。
+ 如果您已经检查了补丁合规性，并准备好应用可用的内核实时补丁，请对于 **Operation (操作)** 选择 `Install`。对于 **Reboot Option**（重启选项），如果不希望托管式节点在此操作后重启，请选择 `NoReboot`。
1. 有关使用此页上的其余控件的信息，请参阅 [从控制台运行命令](running-commands-console.md)。
1. 选择**运行**。
**使用 Run Command (AWS CLI) 应用内核实时补丁**
1. 要在合规性检查结果出来之前执行 `Scan` 操作，请从本地计算机运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunPatchBaseline" \
--targets "Key=InstanceIds,Values=instance-id" \
--parameters '{"Operation":["Scan"],"RebootOption":["RebootIfNeeded"]}'
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets "Key=InstanceIds,Values=instance-id" ^
--parameters {\"Operation\":[\"Scan\"],\"RebootOption\":[\"RebootIfNeeded\"]}
```
------
有关可以在命令中使用的其他选项的信息，请参阅《AWS CLI Command Reference》**中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
1. 要在合规性检查结果出来之后执行 `Install` 操作，请从本地计算机运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunPatchBaseline" \
--targets "Key=InstanceIds,Values=instance-id" \
--parameters '{"Operation":["Install"],"RebootOption":["NoReboot"]}'
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets "Key=InstanceIds,Values=instance-id" ^
--parameters {\"Operation\":[\"Install\"],\"RebootOption\":[\"NoReboot\"]}
```
------
在上述两个命令中，将 *instance-id* 替换为要应用内核实时补丁的 Amazon Linux 2 托管式节点的 ID，例如 i-02573cafcfEXAMPLE。您可以使用以下任一格式，在多个托管式节点上启用该功能。
+ `--targets "Key=instanceids,Values=instance-id1,instance-id2"`
+ `--targets "Key=tag:tag-key,Values=tag-value"`
有关可以在这些命令中使用的其他选项的信息，请参阅《AWS CLI Command Reference》**中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
# 使用 Run Command 来关闭 Kernel Live Patching
要关闭 Kernel Live Patching，您可以在托管式节点上运行 `yum` 命令，也可以使用 Run Command 以及自定义 SSM 文档 `AWS-ConfigureKernelLivePatching`。
**注意**
如果您不再需要使用内核实时修补，可以随时关闭它。在大多数情况下，不需要关闭该功能。
有关通过直接在托管式节点上运行 `yum` 命令来关闭 Kernel Live Patching 的信息，请参阅《Amazon EC2 用户指南》**中的[启用 Kernel Live Patching](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/al2-live-patching.html#al2-live-patching-enable)。
**注意**
关闭 Kernel Live Patching 时，该进程会卸载 Kernel Live Patching 插件，然后重启托管式节点。
**使用 Run Command 来关闭 Kernel Live Patching (控制台)**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档** 列表中，请选择 SSM 文档 `AWS-ConfigureKernelLivePatching`。
1. 在 **Command parameters (命令参数)** 部分中，为必需的参数指定值。
1. 有关使用此页上的其余控件的信息，请参阅 [从控制台运行命令](running-commands-console.md)。
1. 选择**运行**。
**关闭 Kernel Live Patching (AWS CLI)**
+ 运行类似于下面的命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-ConfigureKernelLivePatching" \
--targets "Key=instanceIds,Values=instance-id" \
--parameters "EnableOrDisable=Disable"
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-ConfigureKernelLivePatching" ^
--targets "Key=instanceIds,Values=instance-id" ^
--parameters "EnableOrDisable=Disable"
```
------
将 *instance-id* 替换为要关闭该功能的 Amazon Linux 2 托管式节点的 ID，例如 i-02573cafcfEXAMPLE。要在多个托管式节点上关闭该功能，您可以使用以下任一格式。
+ `--targets "Key=instanceids,Values=instance-id1,instance-id2"`
+ `--targets "Key=tag:tag-key,Values=tag-value"`
有关可以在命令中使用的其他选项的信息，请参阅《AWS CLI Command Reference》**中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html)。
# 使用控制台处理 Patch Manager 资源和合规性
要使用Patch Manager（AWS Systems Manager 中的一项工具），请完成以下任务。此部分更详细地说明了这些任务。
1. 验证您使用的每个操作系统类型的 AWS 预定义的补丁基准是否符合您的需求。如果不符合，则为该托管式节点类型创建定义一组标准补丁的补丁基准，并将其设置为默认值。
1. 使用 Amazon Elastic Compute Cloud (Amazon EC2) 标签将托管节点整理到补丁组中（可选，但建议执行）。
1. 请执行以下操作之一：
+ （推荐）在Quick Setup（Systems Manager 中的一项工具）中配置补丁策略让您可以按计划为整个组织、部分组织单位或单个 AWS 账户安装缺失的补丁。有关更多信息，请参阅 [使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)。
+ 在 Run Command 任务类型中，创建使用 Systems Manager 文档（SSM 文档）`AWS-RunPatchBaseline` 的维护时段。有关更多信息，请参阅 [教程：使用控制台创建修补的维护时段](maintenance-window-tutorial-patching.md)。
+ 在 Run Command 操作中，手动运行 `AWS-RunPatchBaseline`。有关更多信息，请参阅 [从控制台运行命令](running-commands-console.md)。
+ 使用 **Patch now**（立即修补）功能按需手动修补节点。有关更多信息，请参阅 [按需修补托管式节点](patch-manager-patch-now-on-demand.md)。
1. 监视修补以验证合规性和调查故障。
**Topics**
+ [创建补丁策略](patch-manager-create-a-patch-policy.md)
+ [查看补丁程序控制面板摘要](patch-manager-view-dashboard-summaries.md)
+ [使用补丁合规性报告](patch-manager-compliance-reports.md)
+ [按需修补托管式节点](patch-manager-patch-now-on-demand.md)
+ [使用补丁基准](patch-manager-create-a-patch-baseline.md)
+ [查看可用的补丁](patch-manager-view-available-patches.md)
+ [创建和管理补丁组](patch-manager-tag-a-patch-group.md)
+ [将 Patch Manager 与 AWS Security Hub CSPM 集成](patch-manager-security-hub-integration.md)
# 创建补丁策略
补丁策略是您使用Quick Setup（AWS Systems Manager 中的一项工具）设置的一项配置。与其他配置修补的方法相比，补丁策略可以对补丁操作进行更广泛、更集中的控制。补丁策略定义了自动修补节点和应用程序时使用的计划和基准。
有关更多信息，请参阅以下主题：
+ [Quick Setup 中的补丁策略配置](patch-manager-policies.md)
+ [使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)
# 查看补丁程序控制面板摘要
Patch Manager中的**控制面板**选项卡在控制台中提供一个摘要视图，可用于在统一视图中监控修补操作。Patch Manager是 AWS Systems Manager 中的一项工具。在**控制面板**选项卡上，您可以查看以下内容：
+ 有多少托管式节点符合和不符合修补规则的快照。
+ 托管式节点补丁合规性结果的时间快照。
+ 对于每种最常见的不合规原因，有多少不合规的托管式节点链接计数。
+ 最近修补操作的链接列表。
+ 已设置的定期修补任务的链接列表。
**查看补丁控制面板摘要**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**控制面板**选项卡。
1. 滚动到包含要查看的摘要数据的部分：
+ **Amazon EC2 实例管理**
+ **合规性摘要**
+ **不合规问题计数**
+ **合规性报告**
+ **基于非补丁策略的操作**
+ **基于非补丁策略的重复任务**
# 使用补丁合规性报告
使用以下主题中的信息帮助您Patch Manager（AWS Systems Manager 中的一项工具）中生成和使用补丁合规性报告。
无论您使用哪种配置方法或类型进行修补操作，以下主题中的信息都适用：
+ Quick Setup 中配置的补丁策略
+ Quick Setup 中配置的主机管理选项
+ 运行补丁 `Scan` 或 `Install` 任务的维护时段
+ 按需 **Patch now**（立即修补）操作
**重要**
补丁合规性报告是仅在成功进行修补操作后生成的特定时间点快照。每个报告都包含一个捕获时间，用于标识合规性状态的计算时间。
如果您用多种操作来扫描实例的补丁合规性，请注意每次扫描都会覆盖先前扫描的补丁合规性数据。作为结果，您最终可能会导致补丁合规性数据中产生意外结果。有关更多信息，请参阅 [识别创建补丁合规性数据的执行](patch-manager-compliance-data-overwrites.md)。
要验证使用哪个补丁基准来生成最新的合规性信息，请导航到 Patch Manager 中的**合规性报告**选项卡，找到要了解的托管节点行，然后在**使用的基准 ID** 列中选择基准 ID。
**Topics**
+ [查看补丁合规性结果](patch-manager-view-compliance-results.md)
+ [生成 .csv 补丁合规性报告](patch-manager-store-compliance-results-in-s3.md)
+ [使用 Patch Manager 修复不合规的托管式节点](patch-manager-noncompliant-nodes.md)
+ [识别创建补丁合规性数据的执行](patch-manager-compliance-data-overwrites.md)
# 查看补丁合规性结果
使用这些过程可查看有关托管式节点的补丁合规性信息。
此过程适用于使用 `AWS-RunPatchBaseline` 文档的补丁操作。查看有关使用 `AWS-RunPatchBaselineAssociation` 文档进行补丁操作的补丁合规性信息的信息，请参阅 [标识不合规的托管式节点](patch-manager-find-noncompliant-nodes.md)。
**注意**
Quick Setup和 Explorer 的补丁扫描操作使用 `AWS-RunPatchBaselineAssociation` 文档。Quick Setup和 Explorer 都是 AWS Systems Manager 中的工具。
**确定针对特定 CVE 问题的补丁解决方案 (Linux)**
对于许多基于 Linux 的操作系统，补丁合规性结果表明哪些常见漏洞和暴露 (CVE) 公告问题是通过哪些补丁来解决的。此信息可帮助您确定需要安装丢失或失败的补丁的紧迫程度。
受支持的以下操作系统的类型版本中包含 CVE 详细信息：
+ AlmaLinux
+ Amazon Linux 2
+ Amazon Linux 2023
+ Oracle Linux
+ Red Hat Enterprise Linux (RHEL)
+ Rocky Linux
**注意**
默认情况下，CentOS Stream 不提供有关更新的 CVE 信息。但是，您可以使用 Fedora 发布的 Extra Packages for Enterprise Linux (EPEL) 存储库等第三方存储库来允许这种支持。想要了解有关信息，请参阅 Fedora 维基词条中的 [EPEL](https://fedoraproject.org/wiki/EPEL)。
目前，仅报告状态为 `Missing` 或 `Failed` 的补丁的 CVE ID 值。
您还可以根据情况和修补目标的需要，将 CVE ID 添加到补丁基准中已批准或已拒绝的补丁列表中。
有关使用已批准和已拒绝的补丁列表的信息，请参阅以下主题：
+ [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)
+ [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)
+ [补丁基准规则在基于 Linux 的系统上的工作原理](patch-manager-linux-rules.md)
+ [如何安装补丁](patch-manager-installing-patches.md)
**注意**
在某些情况下，Microsoft 会为未指定更新日期和时间的应用程序发布补丁。在这些情况下，系统会默认提供 `01/01/1970` 的更新日期和时间。
## 查看补丁合规性结果
使用以下过程在 AWS Systems Manager 控制台中查看合规性数据。
**注意**
有关生成下载到 Amazon Simple Storage Service (Amazon S3) 存储桶的补丁合规性报告的信息，请参阅 [生成 .csv 补丁合规性报告](patch-manager-store-compliance-results-in-s3.md)。
**查看补丁合规性结果**
1. 请执行以下操作之一。
**选项 1**（推荐）：从Patch Manager（AWS Systems Manager 中的一项工具）中导航：
+ 在导航窗格中，请选择 **Patch Manager**。
+ 选择 **Compliance reporting**（合规性报告）选项卡。
+ 在**节点修补详细信息**区域中，选择要查看其补丁合规性结果的托管式节点 ID。此处将不会显示处于 `stopped` 或 `terminated` 状态的节点。
+ 在**详细信息**区域的**属性**列表中，选择**补丁**。
**选项 2**：从 Compliance（AWS Systems Manager 中的一项工具）中导航：
+ 在导航窗格中，选择 **合规性**。
+ 适用于**合规性资源摘要**，请在列中为要查看的补丁资源类型选择一个数字，例如**不合规资源**。
+ 在下面的**资源**列表中，选择要查看其补丁合规性结果的托管式节点的 ID。
+ 在**详细信息**区域的**属性**列表中，选择**补丁**。
**选项 3**：从 Fleet Manager（AWS Systems Manager 中的一项工具）中导航：
+ 在导航窗格中，请选择 **Fleet Manager**。
+ 在**托管式实例**区域中，选择要查看其补丁合规性结果的托管式节点的 ID。
+ 在**详细信息**区域的**属性**列表中，选择**补丁**。
1. （可选）在搜索框 (![\[The Search icon\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/search-icon.png)）中，从可用筛选器中选择。
例如，对于 Red Hat Enterprise Linux (RHEL)，从以下选项中进行选择：
+ 名称
+ 分类
+ 州
+ 严重性
对于 Windows Server，从以下选项中进行选择：
+ KB
+ 分类
+ 州
+ 严重性
1. 为您选择的筛选器类型选择一个可用值。例如，如果您选择了**状态**，现在选择一个合规性状态，例如**已安装待定重启**、**已失败**或者**缺少**。
**注意**
目前，仅报告状态为 `Missing` 或 `Failed` 的补丁的 CVE ID 值。
1. 根据托管式节点的合规性状态，您可以选择采取哪些操作来补救任何不合规的节点。
例如，您可以选择立即修补不合规托管式节点。有关按需修补托管式节点的信息，请参阅 [按需修补托管式节点](patch-manager-patch-now-on-demand.md)。
有关补丁合规性数据的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。
# 生成 .csv 补丁合规性报告
您可以使用 AWS Systems Manager 控制台来生成补丁合规性报告，这些报告将以 .csv 文件格式另存到您选择的 Amazon Simple Storage Service (Amazon S3) 存储桶。您可以生成单个按需报告或制定自动生成报告的计划。
可以在所选择的 AWS 账户 和 AWS 区域 中为单个托管式节点或所有托管式节点生成报告。对于单个节点，报告包含全面的详细信息，包括与不合规节点相关的补丁 ID。对于所有托管式节点的报告，仅提供摘要信息和不合规节点的补丁计数。
生成报告后，您可以使用 Amazon Quick 等工具导入和分析数据。Quick 是一项商业智能（BI）服务，可用于在交互式视觉环境中浏览和解读信息。有关更多信息，请参阅 [Amazon Quick 用户指南](https://docs.aws.amazon.com/quicksuite/latest/userguide/what-is.html)。
**注意**
创建自定义补丁基准时，您可以为此补丁基准批准的补丁指定合规性严重性级别，例如 `Critical` 或 `High`。如果任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
也可以指定一个在生成报告时发送通知的 Amazon Simple Notification Service (Amazon SNS) 主题。
**生成补丁合规性报告的服务角色**
首次生成报告时，Systems Manager 会创建名为 `AWS-SystemsManager-PatchSummaryExportRole` 的自动化担任角色，用于导出到 S3 的过程。
**注意**
如果您要将合规性数据导出到加密的 S3 存储桶，则必须更新其关联的 AWS KMS 密钥政策以为 `AWS-SystemsManager-PatchSummaryExportRole` 提供必要的权限。例如，将与此类似的权限添加到 S3 存储桶的 AWS KMS 策略中：
```
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "role-arn"
}
```
将 *role-arn* 替换为账户中创建的 Amazon 资源名称（ARN），格式为 `arn:aws:iam::111222333444:role/service-role/AWS-SystemsManager-PatchSummaryExportRole`。
有关更多信息，请参阅《*AWS Key Management Service 开发人员指南*》中的[在 AWS KMS 中使用密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
首次按计划生成报告时，Systems Manager 会创建另一个名为 `AWS-EventBridge-Start-SSMAutomationRole` 的另一个服务角色，以及服务角色 `AWS-SystemsManager-PatchSummaryExportRole`（如果尚未创建）以用于导出过程。`AWS-EventBridge-Start-SSMAutomationRole` 使 Amazon EventBridge 能够使用运行手册[AWS-导出补丁报告到 S3](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-exportpatchreporttos3) 来启动自动化。
我们建议不要尝试修改这些策略和角色。这样做可能会导致补丁合规性报告生成失败。有关更多信息，请参阅 [解决补丁合规性报告生成中的问题](#patch-compliance-reports-troubleshooting)。
**Topics**
+ [生成的补丁合规性报告中有哪些内容？](#patch-compliance-reports-to-s3-examples)
+ [为单个托管式节点生成补丁合规性报告](#patch-compliance-reports-to-s3-one-instance)
+ [为所有托管式节点生成补丁合规性报告](#patch-compliance-reports-to-s3-all-instances)
+ [查看补丁合规性报告历史](#patch-compliance-reporting-history)
+ [查看补丁合规性报告计划](#patch-compliance-reporting-schedules)
+ [解决补丁合规性报告生成中的问题](#patch-compliance-reports-troubleshooting)
## 生成的补丁合规性报告中有哪些内容？
本主题提供有关生成并下载到指定 S3 存储桶的补丁合规性报告中包含的内容类型的信息。
### 单个托管式节点的报告格式
为单个托管式节点生成的报告提供摘要信息和详细信息。
[下载示例报告（单个节点）](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/Sample-single-instance-patch-compliance-report.zip)
单个托管式节点的摘要信息包括以下内容：
+ 索引
+ 实例 ID
+ 实例名称
+ 实例 IP
+ 平台名称
+ 平台版本
+ SSM Agent 版本
+ 补丁基准
+ 补丁组
+ 合规性状态
+ 合规性严重性
+ 不合规的重大严重性补丁计数
+ 不合规的高严重性补丁计数
+ 不合规的中等严重性补丁计数
+ 不合规的低严重性补丁计数
+ 不合规的信息严重性补丁计数
+ 不合规的未指定严重性补丁计数
单个托管式节点的详细信息包括以下内容：
+ 索引
+ 实例 ID
+ 实例名称
+ 补丁名称
+ KB ID/补丁 ID
+ 修补状态
+ 上次报告时间
+ 合规级别
+ 补丁严重性
+ 补丁分类
+ CVE ID
+ 补丁基准
+ 日志 URL
+ 实例 IP
+ 平台名称
+ 平台版本
+ SSM Agent 版本
**注意**
创建自定义补丁基准时，您可以为此补丁基准批准的补丁指定合规性严重性级别，例如 `Critical` 或 `High`。如果任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
### 所有托管式节点的报告格式
为所有托管式节点生成的报告仅提供摘要信息。
[下载示例报告（所有托管式节点）](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/Sample-all-instances-patch-compliance-report.zip)
所有托管式节点的摘要信息包括以下内容：
+ 索引
+ 实例 ID
+ 实例名称
+ 实例 IP
+ 平台名称
+ 平台版本
+ SSM Agent 版本
+ 补丁基准
+ 补丁组
+ 合规性状态
+ 合规性严重性
+ 不合规的重大严重性补丁计数
+ 不合规的高严重性补丁计数
+ 不合规的中等严重性补丁计数
+ 不合规的低严重性补丁计数
+ 不合规的信息严重性补丁计数
+ 不合规的未指定严重性补丁计数
## 为单个托管式节点生成补丁合规性报告
在 AWS 账户 中使用以下过程为单个托管式节点生成补丁摘要报告。单个托管式节点的报告提供有关每个不合规补丁的详细信息，包括补丁名称和 ID。
**为单个托管式节点生成补丁合规性报告**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择 **Compliance reporting**（合规性报告）选项卡。
1. 选择要为其生成报告的托管式节点所在行的按钮，然后选择 **View detail**（查看详细信息）。
1. 在 **Patch summary**（补丁摘要）部分中，选择 **Export to S3**（导出到 S3）。
1. 对于**报告名称**，输入名称以帮助您以后识别该报告。
1. 对于**报告频率**，选择下列选项之一：
+ **按需** — 创建一次性报告。跳至步骤 9。
+ **按计划** — 指定自动生成报告的定期计划。继续执行步骤 8。
1. 对于**计划类型**，请指定速率表达式（如每 3 天），或者提供 cron 表达式来设置报告频率。
有关 Cron 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
1. 对于于 **Bucket name**，选择要存储 .csv 报告文件的 S3 存储桶的名称。
**重要**
如果您处于 2019 年 3 月 20 日之后启动的 AWS 区域 中，则必须在该区域选择 S3 存储桶。默认情况下，在该日期之后启动的区域会被关闭。有关这些区域的详细信息和列表，请参阅《Amazon Web Services 一般参考》**中的 [Enabling a Region](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable)。
1. （可选）要在报告生成时发送通知，请展开 **SNS topic**（SNS 主题）部分，然后从 **SNS topic Amazon Resource Name (ARN)** [SNS 主题的 Amazon Resource Name (ARN)] 中选择一个现存的 Amazon SNS 主题。
1. 选择**提交**。
有关查看生成报告的历史记录的信息，请参阅 [查看补丁合规性报告历史](#patch-compliance-reporting-history)。
有关查看已创建的报告计划详细信息的信息，请参阅 [查看补丁合规性报告计划](#patch-compliance-reporting-schedules)。
## 为所有托管式节点生成补丁合规性报告
在 AWS 账户 中使用以下过程为所有托管式节点生成补丁摘要报告。所有托管式节点的报告会指明哪些节点不合规以及不合规补丁的数量。它不提供补丁的名称或其他标识符。对于这些额外详细信息，您可以为单个托管式节点生成补丁合规性报告。有关更多信息，请参阅本主题前面的 [为单个托管式节点生成补丁合规性报告](#patch-compliance-reports-to-s3-one-instance)。
**为所有托管式节点生成补丁合规性报告**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择 **Compliance reporting**（合规性报告）选项卡。
1. 选择**导出到 S3**。（不要先选择节点 ID。）
1. 对于**报告名称**，输入名称以帮助您以后识别该报告。
1. 对于**报告频率**，选择下列选项之一：
+ **按需** — 创建一次性报告。跳至步骤 8。
+ **按计划** — 指定自动生成报告的定期计划。继续执行步骤 7。
1. 对于**计划类型**，请指定速率表达式（如每 3 天），或者提供 cron 表达式来设置报告频率。
有关 Cron 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
1. 对于于 **Bucket name**，选择要存储 .csv 报告文件的 S3 存储桶的名称。
**重要**
如果您处于 2019 年 3 月 20 日之后启动的 AWS 区域 中，则必须在该区域选择 S3 存储桶。默认情况下，在该日期之后启动的区域会被关闭。有关这些区域的详细信息和列表，请参阅《Amazon Web Services 一般参考》**中的 [Enabling a Region](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable)。
1. （可选）要在报告生成时发送通知，请展开 **SNS topic**（SNS 主题）部分，然后从 **SNS topic Amazon Resource Name (ARN)** [SNS 主题的 Amazon Resource Name (ARN)] 中选择一个现存的 Amazon SNS 主题。
1. 选择**提交**。
有关查看生成报告的历史记录的信息，请参阅 [查看补丁合规性报告历史](#patch-compliance-reporting-history)。
有关查看已创建的报告计划详细信息的信息，请参阅 [查看补丁合规性报告计划](#patch-compliance-reporting-schedules)。
## 查看补丁合规性报告历史
使用本主题中的信息帮助您查看有关 AWS 账户 中生成的补丁合规性报告的详细信息。
**查看补丁合规性报告历史**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择 **Compliance reporting**（合规性报告）选项卡。
1. 选择**查看所有 S3 导出**，然后选择**导出历史记录**选项卡。
## 查看补丁合规性报告计划
使用本主题中的信息帮助您查看在 AWS 账户 中生成的补丁合规性报告历史的详细信息。
**查看补丁合规性报告历史**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择 **Compliance reporting**（合规性报告）选项卡。
1. 选择 **View all S3 exports**（查看所有 S3 导出），然后选择 **Report schedule rules**（报告计划规则）选项卡。
## 解决补丁合规性报告生成中的问题
利用以下信息，帮助排查Patch Manager（AWS Systems Manager 中的一项工具）中有关生成补丁合规性报告的问题。
**Topics**
+ [报告 `AWS-SystemsManager-PatchManagerExportRolePolicy` 策略已损坏的消息](#patch-compliance-reports-troubleshooting-1)
+ [在删除补丁合规性策略或角色后，未成功按照计划生成报告](#patch-compliance-reports-troubleshooting-2)
### 报告 `AWS-SystemsManager-PatchManagerExportRolePolicy` 策略已损坏的消息
**问题**：您收到类似于以下内容的错误消息，指示 `AWS-SystemsManager-PatchManagerExportRolePolicy` 已损坏：
```
An error occurred while updating the AWS-SystemsManager-PatchManagerExportRolePolicy
policy. If you have edited the policy, you might need to delete the policy, and any
role that uses it, then try again. Systems Manager recreates the roles and policies
you have deleted.
```
+ **解决方案**：在生成新的补丁合规性报告之前，使用 Patch Manager 控制台或 AWS CLI 删除受影响的角色和策略。
**使用控制台删除损坏的策略**
1. 访问：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)，打开 IAM 控制台
1. 请执行以下操作之一：
**按需报告** — 如果在生成一次性按需报告时出现问题，请在左侧导航栏中选择**策略**，搜索 `AWS-SystemsManager-PatchManagerExportRolePolicy`，然后删除该策略。下一步，选择**角色**，搜索 `AWS-SystemsManager-PatchSummaryExportRole`，然后删除该角色。
**计划报告**：如果在按计划生成报告时出现问题，请在左侧导航栏中选择**策略**，一次搜索一个 `AWS-EventBridge-Start-SSMAutomationRolePolicy` 和 `AWS-SystemsManager-PatchManagerExportRolePolicy`，然后删除每个策略。下一步，选择**角色**，一次搜索一个 `AWS-EventBridge-Start-SSMAutomationRole` 和 `AWS-SystemsManager-PatchSummaryExportRole`，然后删除每个角色。
**使用 AWS CLI 删除损坏的策略**
请将*占位符值*替换为账户 ID。
+ 如果在生成一次性按需报告时出现问题，请运行以下命令：
```
aws iam delete-policy --policy-arn arn:aws:iam::account-id:policy/AWS-SystemsManager-PatchManagerExportRolePolicy
```
```
aws iam delete-role --role-name AWS-SystemsManager-PatchSummaryExportRole
```
如果在按计划生成报告时出现问题，请运行以下命令：
```
aws iam delete-policy --policy-arn arn:aws:iam::account-id:policy/AWS-EventBridge-Start-SSMAutomationRolePolicy
```
```
aws iam delete-policy --policy-arn arn:aws:iam::account-id:policy/AWS-SystemsManager-PatchManagerExportRolePolicy
```
```
aws iam delete-role --role-name AWS-EventBridge-Start-SSMAutomationRole
```
```
aws iam delete-role --role-name AWS-SystemsManager-PatchSummaryExportRole
```
完成任一过程后，按照以下步骤生成或计划新的补丁合规性报告。
### 在删除补丁合规性策略或角色后，未成功按照计划生成报告
**问题**：首次生成报告时，Systems Manager 会创建一个服务角色和一个策略，用于导出过程 (`AWS-SystemsManager-PatchSummaryExportRole` 和 `AWS-SystemsManager-PatchManagerExportRolePolicy`)。首次按计划生成报告时，Systems Manager 会创建另一个服务角色和策略 (`AWS-EventBridge-Start-SSMAutomationRole` 和 `AWS-EventBridge-Start-SSMAutomationRolePolicy`)。这些功能让 Amazon EventBridge 使用运行手册启动自动化 [AWS 导出补丁报告到 S3](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-exportpatchreporttos3)。
如果您删除这些策略或角色中的任何一个，则计划与指定的 S3 存储桶和 Amazon SNS 主题之间的连接可能会丢失。
+ **解决方案**：若要变通解决此问题，我们建议删除以前的计划，并创建一个新的计划来替换遇到问题的计划。
# 使用 Patch Manager 修复不合规的托管式节点
本节中的主题概述了如何标识不符合补丁合规性要求的托管式节点以及如何使节点合规。
**Topics**
+ [标识不合规的托管式节点](patch-manager-find-noncompliant-nodes.md)
+ [补丁合规性状态值](patch-manager-compliance-states.md)
+ [修补不合规的托管式节点](patch-manager-compliance-remediation.md)
# 标识不合规的托管式节点
当运行两个 AWS Systems Manager 文档（SSM 文档）中的其中一个文档时，会标识不合规的托管式节点。这些 SSM 文档引用了Patch Manager（AWS Systems Manager 中的一项工具）中每个托管式节点相应的补丁基准。然后，这些文档会评估托管式节点的补丁状态，并向您提供合规性结果。
有两个 SSM 文档用于标识或更新不合规的托管式节点：`AWS-RunPatchBaseline` 和 `AWS-RunPatchBaselineAssociation`。每个文档的使用流程不同，其合规性结果通过不同的渠道提供。下表概述了这些文档之间的差异。
**注意**
来自 Patch Manager 的补丁合规性数据可以发送到 AWS Security Hub CSPM。Security Hub CSPM 能让您全面了解高优先级安全警报和合规性状态。它还监控您的实例集的修补状态。有关更多信息，请参阅 [将 Patch Manager 与 AWS Security Hub CSPM 集成](patch-manager-security-hub-integration.md)。
| | `AWS-RunPatchBaseline` | `AWS-RunPatchBaselineAssociation` |
| --- | --- | --- |
| 使用文档的过程 | **按需修补** – 您可以使用 **Patch now**（立即修补）选项按需扫描或修补托管式节点。有关信息，请参阅[按需修补托管式节点](patch-manager-patch-now-on-demand.md)。 **Systems Manager Quick Setup补丁策略**：您可以在Quick Setup（AWS Systems Manager 中的一项工具）中创建修补配置，可针对整个组织、部分组织单位或单个 AWS 账户按不同的计划扫描或安装缺失的补丁。有关信息，请参阅[使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)。 **运行命令**：在 Run Command（AWS Systems Manager 中的一项工具）的操作中，您可以手动运行 `AWS-RunPatchBaseline`。有关信息，请参阅[从控制台运行命令](running-commands-console.md)。 **维护时段** – 在 Run Command 任务类型中，您可以使用 SSM 文档 `AWS-RunPatchBaseline` 创建维护时段。有关信息，请参阅[教程：使用控制台创建修补的维护时段](maintenance-window-tutorial-patching.md)。 | **Systems Manager Quick Setup 主机管理**：您可以在 Quick Setup 中启用主机管理配置选项，每天扫描您的托管实例的补丁合规性。有关信息，请参阅[使用 Quick Setup 设置 Amazon EC2 主机管理](quick-setup-host-management.md)。 **Systems Manager [Explorer](Explorer.md)**：只要允许 Explorer（AWS Systems Manager 中的一项工具），该工具就会定期扫描托管式实例来了解补丁合规性，并会在 Explorer 控制面板中报告结果。 |
| 补丁扫描结果数据的格式 | 在 `AWS-RunPatchBaseline` 运行后，Patch Manager会将 `AWS:PatchSummary` 对象发送至 Inventory（AWS Systems Manager 中的一项工具）。此报告仅在成功完成修补操作后生成，并且包含用于标识合规性状态计算时间的捕获时间。 | 在 `AWS-RunPatchBaselineAssociation` 运行后，Patch Manager 发送 `AWS:ComplianceItem` 对象至 Systems Manager 库存。 |
| 在控制台中查看补丁合规性报告 | 您可以查看使用 [Systems Manager 配置合规性](systems-manager-compliance.md)中的 `AWS-RunPatchBaseline` 和 [使用托管式节点](fleet-manager-managed-nodes.md) 进程的补丁合规性信息。有关更多信息，请参阅 [查看补丁合规性结果](patch-manager-view-compliance-results.md)。 | 如果您使用 Quick Setup 扫描托管实例的补丁合规性，您可以在 [Systems Manager Fleet Manager](fleet-manager.md) 中查看合规性报告。在 Fleet Manager 控制台中，选择托管式节点的节点 ID。在**常规**菜单中，选择**配置合规性**。 如果您将Explorer 扫描托管实例的补丁合规性，您可以在 Explorer 和 [Systems Manager OpsCenter](OpsCenter.md) 中查看合规性报告。 |
| 查看补丁合规性结果的 AWS CLI 命令 | 对于使用 `AWS-RunPatchBaseline` 的进程，您可以使用以下 AWS CLI 命令查看有关托管式节点上的补丁的摘要信息。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-find-noncompliant-nodes.html) | 对于使用 `AWS-RunPatchBaselineAssociation` 的进程，您可以使用以下 AWS CLI 命令查看有关实例补丁的摘要信息。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-find-noncompliant-nodes.html) |
| 修补操作 | 对于使用 `AWS-RunPatchBaseline` 的进程，可以指定是否仅希望该操作运行 `Scan` 操作，或者 `Scan and install` 操作。 如果您的目标是标识而非修复不合规的托管式节点，则仅运行 `Scan` 操作。 | Quick Setup 和 Explorer 进程，使用 AWS-RunPatchBaselineAssociation，请仅运行 Scan 操作。 |
| 更多信息 | [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md) | [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineAssociation`](patch-manager-aws-runpatchbaselineassociation.md) |
有关您可能看到报告的各种补丁合规性状态的信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)
有关修复不符合补丁合规性要求的托管式节点的信息，请参阅 [修补不合规的托管式节点](patch-manager-compliance-remediation.md)。
# 补丁合规性状态值
有关托管式节点补丁的信息包括每个单一补丁的状态报告。
**提示**
如果要将特定补丁合规性状态分配给托管式节点，可以使用 [https://docs.aws.amazon.com/cli/latest/reference/ssm/put-compliance-items.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/put-compliance-items.html) AWS Command Line Interface（AWS CLI）命令或 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutComplianceItems.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PutComplianceItems.html) API 操作。控制台中不支持分配合规性状态。
使用下表中的信息可帮助您确定托管式节点可能不符合补丁合规性要求的原因。
## Debian Server 和 Ubuntu Server 的补丁合规性值
对于 Debian Server 和 Ubuntu Server，将软件包分类到不同合规性状态的规则如下表所述。
**注意**
在评估 `INSTALLED`、`INSTALLED_OTHER` 和 `MISSING` 状态值时，请记住以下事项：如果在创建或更新补丁基准时未选中**包括非安全性更新**复选框，则补丁候选版本仅限于以下存储库中的补丁：
Ubuntu Server 16.04 LTS：`xenial-security`
Ubuntu Server 18.04 LTS：`bionic-security`
Ubuntu Server 20.04 LTS：`focal-security`
Ubuntu Server 22.04 LTS：`jammy-security`
Ubuntu Server 24.04 LTS (`noble-security`)
Ubuntu Server 25.04 (`plucky-security`)
`debian-security` (Debian Server)
如果选择了**包括非安全更新**复选框，也会考虑来自其他存储库的补丁。
| 修补状态 | 说明 | 合规性状态 |
| --- | --- | --- |
| **`INSTALLED`** | 补丁在补丁基准中列出，并已安装在托管式节点上。如果托管式节点上已运行 `AWS-RunPatchBaseline` 文档，则可能是由个人手动安装或由 Patch Manager 自动安装补丁。 | 合规 |
| **`INSTALLED_OTHER`** | 补丁不包括在基准中，或者未获基准批准，但已安装在托管式节点上。该补丁可能已手动安装，该软件包可能是另一个已批准补丁的必需依赖项，或者该补丁可能已包含在 InstallOverrideList 操作中。如果您没有指定 `Block` 作为**拒绝的修补**行动,`INSTALLED_OTHER` 补丁还包括已安装但拒绝的补丁。 | 合规 |
| **`INSTALLED_PENDING_REBOOT`** | `INSTALLED_PENDING_REBOOT` 可能表示以下任一情况： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-compliance-states.html) 无论是哪种情况，都不表示具有此状态的补丁*需要*重新启动，而是只表示自安装补丁以来该节点尚未重新启动。 | 不合规 |
| **`INSTALLED_REJECTED`** | 该补丁已安装在托管式节点上，但列在 **Rejected patches**（已被拒绝补丁）列表中。这通常意味着补丁是在添加到已拒绝的补丁列表之前安装的。 | 不合规 |
| **`MISSING`** | 基准中已批准补丁，但托管式节点上未安装该补丁。如果将 `AWS-RunPatchBaseline` 文档任务配置为扫描（而不是安装），系统将为扫描期间找到但未安装的补丁报告此状态。 | 不合规 |
| **`FAILED`** | 基准中已批准补丁，但无法安装补丁。要解决此问题，请查看命令输出中是否有可帮助您理解此问题的信息。 | 不合规 |
## 其他操作系统的补丁合规性值
对于除 Debian Server 和 Ubuntu Server 之外的所有操作系统，将软件包分类到不同合规性状态的规则如下表所述。
| 修补状态 | 说明 | 合规性值 |
| --- | --- | --- |
| **`INSTALLED`** | 补丁在补丁基准中列出，并已安装在托管式节点上。如果节点上已运行 `AWS-RunPatchBaseline` 文档，则可能是由个人手动安装或由 Patch Manager 自动安装补丁。 | 合规 |
| **`INSTALLED_OTHER`**¹ | 补丁不在基准中，但已安装在托管式节点上。有两个可能的原因： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-compliance-states.html) | 合规 |
| **`INSTALLED_REJECTED`** | 该补丁已安装在托管式节点上，但列在已被拒绝补丁列表中。这通常意味着补丁是在添加到已拒绝的补丁列表之前安装的。 | 不合规 |
| **`INSTALLED_PENDING_REBOOT`** | `INSTALLED_PENDING_REBOOT` 可能表示以下任一情况： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/patch-manager-compliance-states.html) 无论是哪种情况，都不表示具有此状态的补丁*需要*重新启动，而是只表示自安装补丁以来该节点尚未重新启动。 | 不合规 |
| **`MISSING`** | 基准中已批准补丁，但托管式节点上未安装该补丁。如果将 `AWS-RunPatchBaseline` 文档任务配置为扫描（而不是安装），系统将为扫描期间找到但未安装的补丁报告此状态。 | 不合规 |
| **`FAILED`** | 基准中已批准补丁，但无法安装补丁。要解决此问题，请查看命令输出中是否有可帮助您理解此问题的信息。 | 不合规 |
| **`NOT_APPLICABLE`**¹ | *此合规性状态仅针对 Windows Server 操作系统报告。* 基准中已批准补丁，但托管式节点上未安装使用该补丁的服务或功能。例如，如果基准中已批准 Web 服务器服务 [如 Internet Information Services (IIS)] 的补丁，但托管式节点上未安装该 Web 服务，则该补丁将显示 `NOT_APPLICABLE`。如果补丁已由后续更新取代，则也可以将补丁标记为 `NOT_APPLICABLE`。这意味着安装了更高版本的更新，并且不再需要 `NOT_APPLICABLE` 更新。 | 不适用 |
| AVAILABLE\$1SECURITY\$1UPDATES | *此合规性状态仅针对 Windows Server 操作系统报告。* 未经补丁基准批准的可用安全更新补丁可以具有合规性值 `Compliant` 或 `Non-Compliant`，如自定义补丁基准中所定义。 创建或更新补丁基准时，需选择要分配给可用但尚未批准的安全补丁（这些补丁由于不符合补丁基准中指定的安装标准而未获批准）的状态。例如，如果您指定在补丁发布后等待较长时间再进行安装，则会跳过某些您可能希望安装的安全补丁。如果在您指定的等待期内发布了该补丁的更新版本，则该补丁的安装等待期将重新开始。如果等待期过长，则可能会发布多个版本的补丁，但不会进行安装。 对于补丁摘要计数，当某个补丁报告为 `AvailableSecurityUpdate` 时，它将始终计入 `AvailableSecurityUpdateCount`。如果基准配置为将此类补丁报告为 `NonCompliant`，则它们也会计入 `SecurityNonCompliantCount`。如果基准配置为将此类补丁报告为 `Compliant`，则它们不会计入 `SecurityNonCompliantCount`。此类补丁始终以未指定严重性的形式报告，且永远不会计入 `CriticalNonCompliantCount`。 | “合规”或“不合规”，取决于为可用安全更新选择的选项。 通过控制台创建或更新补丁基准，需在**可用安全更新合规性状态**字段中指定此选项。通过 AWS CLI 运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-patch-baseline.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-patch-baseline.html) 或 [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-patch-baseline.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-patch-baseline.html) 命令时，需在 `available-security-updates-compliance-status` 参数中指定此选项。 |
¹ 对于状态为 `INSTALLED_OTHER` 和 `NOT_APPLICABLE` 的补丁，根据 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-patches.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-instance-patches.html) 命令，Patch Manager 会从查询结果中省略一些数据，例如 `Classification` 和 `Severity` 的值。这样做有助于防止超出 Inventory（AWS Systems Manager 中的一项工具）中单个节点的数据限制。要查看所有补丁的详细信息，可以使用 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-available-patches.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-available-patches.html) 命令。
# 修补不合规的托管式节点
许多 AWS Systems Manager 工具和流程均可用来检查托管式节点是否符合补丁合规性要求，您也可以使用这些工具和流程来使节点符合当前应用的补丁规则。要使托管式节点符合补丁合规性要求，Patch Manager（AWS Systems Manager 中的一项工具）必须运行 `Scan and install` 操作。（如果您的目标仅是标识而非修复不合规的托管式节点，请改为运行 `Scan` 操作。有关更多信息，请参阅 [标识不合规的托管式节点](patch-manager-find-noncompliant-nodes.md)。）
**使用 Systems Manager 安装补丁**
您可以从多个工具中选择以运行 `Scan and install` 操作：
+ （推荐）在Quick Setup（Systems Manager 中的一项工具）中配置补丁策略让您可以按计划为整个组织、部分组织单位或单个 AWS 账户安装缺失的补丁。有关更多信息，请参阅 [使用 Quick Setup 补丁策略为组织中的实例配置修补](quick-setup-patch-manager.md)。
+ 在 Run Command 任务类型中，创建使用 Systems Manager 文档（SSM 文档）`AWS-RunPatchBaseline` 的维护时段。有关信息，请参阅[教程：使用控制台创建修补的维护时段](maintenance-window-tutorial-patching.md)。
+ 在 Run Command 操作中，手动运行 `AWS-RunPatchBaseline`。有关信息，请参阅[从控制台运行命令](running-commands-console.md)。
+ 使用**修补**选项，按需安装补丁。有关信息，请参阅[按需修补托管式节点](patch-manager-patch-now-on-demand.md)。
# 识别创建补丁合规性数据的执行
补丁合规性数据代表最近一次成功修补操作的时间点快照。每个合规性报告都包含执行 ID 和捕获时间，可帮助您确定是哪个操作创建了合规性数据以及何时生成的。
如果您用多种操作来扫描实例的补丁合规性，则每次扫描都会覆盖先前扫描的补丁合规性数据。作为结果，您最终可能会导致补丁合规性数据中产生意外结果。
例如，假设您创建了一个补丁策略，该策略每天在当地时间凌晨 2 点扫描补丁合规性。该补丁策略使用的补丁基准是针对严重性标记为 `Critical`、`Important` 和 `Moderate` 的补丁。该补丁基准还指定了一些特定的已拒绝补丁。
同时，假设您已经设置了一个没有删除或停用的维护时段，每天在当地时间凌晨 4 点扫描同一组托管节点。该维护时段的任务使用其他补丁基准，该基准仅针对 `Critical` 严重性的补丁，且不排除任何特定补丁。
当维护时段执行第二次扫描时，第一次扫描的补丁合规性数据将被删除，并替换为第二次扫描的补丁合规性数据。
因此，我们强烈建议在修补操作中仅使用一种自动方法进行扫描和安装。如果您要设置补丁策略，应该删除或停用其他扫描补丁合规性的方法。有关更多信息，请参阅以下主题：
+ 要从维护时段删除修补操作任务：[使用控制台更新或注销维护时段任务](sysman-maintenance-update.md#sysman-maintenance-update-tasks)
+ 删除 State Manager 关联：[删除关联](systems-manager-state-manager-delete-association.md)。
要在“主机管理”配置中停用每日补丁合规性扫描，请在 Quick Setup 中执行以下操作：
1. 在导航窗格中，请选择 **Quick Setup**。
1. 选择要更新的主机管理配置。
1. 选择 **Actions, Edit configuration**（操作、编辑配置）。
1. 清除 **Scan instances for missing patches daily**（每日扫描实例以查找缺失的补丁）复选框。
1. 选择**更新**。
**注意**
使用 **Patch now**（立即修补）选项扫描托管节点的合规性也会覆盖补丁合规性数据。
# 按需修补托管式节点
使用Patch Manager（AWS Systems Manager 中的一项工具）中的**立即修补**选项，您可以从 Systems Manager 控制台运行按需修补操作。这意味着您不必创建计划来更新托管式节点的合规性状态，或在不合规的节点上安装补丁。您也不需要在Patch Manager和 Maintenance Windows（AWS Systems Manager 中的一项工具）之间切换 Systems Manager 控制台来设置或修改计划的补丁时段。
当您必须尽快在托管式节点上应用零日更新或安装其他关键补丁时，**Patch now**（立即修补）特别有用。
**注意**
每次仅支持按需修补一个 AWS 账户 与 AWS 区域 对。这不能用于基于*补丁策略*的修补操作。我们建议使用补丁策略来确保所有托管节点满足合规性。有关使用补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
**Topics**
+ [“立即补丁”的工作原理](#patch-on-demand-how-it-works)
+ [运行“立即修补”](#run-patch-now)
## “立即补丁”的工作原理
要运行**立即修补**，您只需指定两个必需的设置：
+ 是仅扫描缺少的补丁，还是在托管式节点上扫描*并*安装补丁
+ 要在哪个托管式节点上运行该操作
当 **Patch now**（立即修补）操作运行时，其确定以与为其他修补操作选择的基准相同的方式使用哪个补丁基准。如果托管式节点与补丁组关联，则将使用为该组指定的补丁基准。如果托管式节点未与补丁组关联，则该操作使用的补丁基准为当前设置为托管式节点操作系统类型的默认补丁基准。这可以是预定义基准，也可以是您设置为默认基准的自定义基准。有关选择补丁基准的更多信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
您可以为 **Patch now**（立即修补）指定的选项包括：选择修补后重启托管式节点的时间或是否重启托管式节点，指定 Amazon Simple Storage Service (Amazon S3) 存储桶来存储修补操作的日志数据，以及在修补期间将 Systems Manager 文档（SSM 文档）作为生命周期钩子运行。
### “立即修补”的并发和错误阈值
适用于**立即修补**操作，并发和错误阈值选项由 Patch Manager 来处理。您无需指定一次修补多少个托管式节点，也不需要指定操作失败之前允许的错误数。在按需进行修补时，Patch Manager 将应用下表中描述的并发和错误阈值设置。
**重要**
以下阈值仅适用于 `Scan and install` 操作。对于 `Scan` 操作，Patch Manager 会尝试同时扫描多达 1,000 个节点，并继续扫描，直到遇到多达 1,000 个错误。
**并发性：安装操作**
| **Patch now**（立即修补）操作中的托管式节点总数 | 一次扫描或修补的托管式节点数量 |
| --- | --- |
| 少于 25 | 1 |
| 25-100 | 5% |
| 101 到 1,000 | 8% |
| 1,000 以上 | 10% |
**错误阈值：安装操作**
| **Patch now**（立即修补）操作中的托管式节点总数 | 操作失败前允许的错误数 |
| --- | --- |
| 少于 25 | 1 |
| 25-100 | 5 |
| 101 到 1,000 | 10 |
| 1,000 以上 | 10 |
### 使用“立即修补”生命周期钩子
**立即修补**提供了在 `Install` 修补操作期间将 SSM 命令文档作为生命周期钩子运行的能力。您可以使用这些钩子执行诸如在修补之前关闭应用程序或在修补后或重启后对应用程序运行状况检查之类的任务。
有关使用生命周期钩子的更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaselineWithHooks`](patch-manager-aws-runpatchbaselinewithhooks.md)。
下表列出了适用于三个**立即修补**重启选项之一的可用生命周期钩子，以及每个钩子的示例用途。
**生命周期钩子和示例用途**
| 重启选项 | 钩子：安装前 | 钩子：安装后 | 钩子：退出时 | 钩子：计划重启后 |
| --- | --- | --- | --- | --- |
| 如果需要，重启 | 在开始修补之前运行 SSM 文档。 示例用途：在修补过程开始之前安全地关闭应用程序。 | 在修补操作结束时和托管式节点重启前运行 SSM 文档。 示例用途：在潜在重启之前运行诸如安装第三方应用程序等操作。 | 修补操作完成后运行 SSM 文档，重新启动实例。 示例用途：确保应用程序在修补后按预期运行。 | 不可用 |
| 不重启我的实例 | 同上。 | 在修补操作结束时运行 SSM 文档。 示例用途：确保应用程序在修补后按预期运行。 | *不可用* | *不可用* |
| 计划重启时间 | 同上。 | 与不重启我的实例相同。 | 不可用 | 在计划的重启完成后立即运行 SSM 文档。 示例用途：确保应用程序在重启后按预期运行。 |
## 运行“立即修补”
使用以下过程按需修补托管式节点。
**要运行“立即修补”**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**立即修补**。
1. 适用于**修补操作**，请选择以下选项之一：
+ **Scan**（扫描）：Patch Manager 查找托管式节点中缺少的补丁，但不进行安装。您可以在**合规性**控制面板中查看结果，或在你使用的其他工具中查看补丁合规性。
+ **Scan and install**（扫描并安装）：Patch Manager 查找并安装托管式节点中缺少的补丁。
1. 仅在上一个步骤中选择**扫描并安装**时，使用此步骤。对于 **重启选项**，请选择以下选项之一：
+ **Reboot if needed**（如需要，则重启）：安装后，Patch Manager 仅在需要完成补丁安装时才会重启托管式节点。
+ **Don't reboot my instances**（不重启我的实例）：安装后，Patch Manager 不会重启托管式节点。当您在 Patch Manager 之外选择或管理重启时，您可以手动重启节点。
+ **Schedule a reboot time**（计划重启时间）：为 Patch Manager 重启托管式节点，指定日期、时间和 UTC 时区。在您运行**立即修补**操作时，计划的重启将在 State Manager 中列为关联内容，名称为 `AWS-PatchRebootAssociation`。
**重要**
如果在主修补操作开始后取消该操作，则State Manager中的 `AWS-PatchRebootAssociation` 关联不会自动取消。为防止意外重启，如果不再希望发生计划重启，则必须手动从State Manager中删除 `AWS-PatchRebootAssociation`。否则可能导致系统意外重启，从而影响生产工作负载。您可以在 Systems Manager 控制台的**State Manager** > **关联**下找到此关联。
1. 对于 **要修补的实例**，请选择以下任一项：
+ **Patch all instances**（修补所有实例）：在当前 AWS 区域 中，Patch Manager 在 AWS 账户 中的所有托管式节点上运行指定操作。
+ **Patch only the target instances I specify**（仅修补我指定的目标实例）：您可以指定要在下一步中作为目标的托管式节点。
1. 仅在上一个步骤中选择**仅修补我指定的目标实例**时，使用此步骤。在 **Target selection**（目标选择）部分中，通过指定标签、手动选择节点或指定资源组，标识要在其上运行此操作的节点。
**注意**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
如果选择以资源组为目标，请注意，基于 AWS CloudFormation 堆栈的资源组仍然必须使用默认 `aws:cloudformation:stack-id` 标签来标记。如果已删除，Patch Manager 可能无法确定属于资源组的托管式节点。
1. （可选）对于**补丁日志存储**，如果要从此修补操作创建和保存日志，请选择用于存储日志的 S3 存储桶。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. （可选）如果要在修补操作的特定点期间将 SSM 文档作为生命周期钩子运行，请执行以下操作：
+ 选择**使用生命周期钩子**。
+ 对于每个可用钩子，选择要在操作的指定点运行的 SSM 文档：
+ 安装前
+ 安装后
+ 退出时
+ 计划重启后
**注意**
默认文档 `AWS-Noop`，不运行任何操作。
1. 选择**立即修补**。
打开 **Association execution targets (关联执行目标)**页面。[“立即修补”使用State Manager（AWS Systems Manager 中的一项工具）中的关联进行操作。] 在 **Operation summary**（操作摘要）区域中，您可以监控指定托管式节点上的扫描或修补状态。
# 使用补丁基准
Patch Manager（AWS Systems Manager 中的一项工具）中的补丁基准定义获批在托管式节点上安装的补丁。您可以逐个指定批准或拒绝的补丁。也可以创建自动批准规则，指定应自动批准的某些更新类型 (例如重要更新)。拒绝补丁列表将覆盖这些规则和批准列表。要使用一系列已批准的补丁来安装特定软件包，需要先删除所有自动批准规则。如果您将补丁明确标识为已拒绝，即使它匹配自动批准规则中的所有条件，也不会被批准或安装。此外，即使补丁获批用于某个托管式节点，只有该补丁适用于托管式节点上的软件时，才会安装该补丁。
**Topics**
+ [查看 AWS 预定义补丁基准](patch-manager-view-predefined-patch-baselines.md)
+ [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)
+ [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)
**更多信息**
+ [补丁基准](patch-manager-patch-baselines.md)
# 查看 AWS 预定义补丁基准
Patch Manager（AWS Systems Manager 中的一项工具）包含用于Patch Manager支持的每个操作系统的预定义补丁基准。您可以利用这些补丁基准（您不能对其进行自定义），也可创建自己的补丁基准。以下过程介绍了如何查看预定义的补丁基准，以查看它是否满足您的需求。要了解有关补丁基准的更多信息，请参阅 [预定义和自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md)。
**查看 AWS 预定义补丁基准**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 在补丁基准列表中，请选择其中一个预定义补丁基准的基准 ID。
–或者–
如果您是在当前 AWS 区域 首次访问 Patch Manager，请选择**从概览开始**，然后选择**补丁基准**选项卡，然后选择预定义补丁基准之一的基准 ID。
**注意**
适用于 Windows Server，提供三个预定义的补丁基准。补丁基准 `AWS-DefaultPatchBaseline` 和 `AWS-WindowsPredefinedPatchBaseline-OS` 仅支持 Windows 操作系统本身的操作系统更新。除非您指定了其他补丁基准，`AWS-DefaultPatchBaseline` 用作 Windows Server 托管式节点的默认补丁基准。这两个补丁基准中的配置设置是相同的。两者中较新的,`AWS-WindowsPredefinedPatchBaseline-OS` 被创建来区分它和 Windows Server 的第三个预定义补丁基准。补丁基准 `AWS-WindowsPredefinedPatchBaseline-OS-Applications`，可用于将补丁应用到 Windows Server 操作系统和 Microsoft 发布的受支持的应用程序。
有关更多信息，请参阅 [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)。
1. 在**批准规则**部分中，查看补丁基准配置。
1. 如果托管式节点接受该配置，则可以直接跳至过程 [创建和管理补丁组](patch-manager-tag-a-patch-group.md)。
–或者–
要创建自己的默认补丁基准，请继续主题 [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
# 使用自定义补丁基准
Patch Manager（AWS Systems Manager 中的一项工具）包含用于Patch Manager支持的每个操作系统的预定义补丁基准。您可以利用这些补丁基准（您不能对其进行自定义），也可创建自己的补丁基准。
以下过程描述如何创建、更新和删除您自己的自定义补丁基准。要了解有关补丁基准的更多信息，请参阅 [预定义和自定义补丁基准](patch-manager-predefined-and-custom-patch-baselines.md)。
**Topics**
+ [创建适用于 Linux 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-linux.md)
+ [创建适用于 macOS 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-macos.md)
+ [创建适用于 Windows Server 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-windows.md)
+ [更新或删除自定义补丁基准](patch-manager-update-or-delete-a-patch-baseline.md)
# 创建适用于 Linux 的自定义补丁基准
在Patch Manager（AWS Systems Manager 中的一项工具）中，按照以下过程为 Linux 托管式节点创建自定义补丁基准。
有关为 macOS 托管式节点创建补丁基准的信息，请参阅 [创建适用于 macOS 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-macos.md)。有关为 Windows 托管式节点创建补丁基准的信息，请参阅 [创建适用于 Windows Server 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-windows.md)。
**为 Linux 托管式节点创建自定义补丁基准**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡，然后选择**创建补丁基准**。
–或者–
如果您是在当前 AWS 区域首次访问 Patch Manager，请选择**从概览开始**，然后选择**补丁基准**选项卡，然后选择**创建补丁基准**。
1. 在 **Name (名称)** 中，输入新补丁基准的名称，例如，`MyRHELPatchBaseline`。
1. （可选）对于 **Description (描述)**，输入此补丁基准的描述。
1. 对于 **Operating system (操作系统)**，请选择操作系统，例如 `Red Hat Enterprise Linux`。
1. 如果要在创建后即开始将此补丁基准用作所选操作系统的默认项，请选中 **Set this patch baseline as the default patch baseline for *operating system name* instances (将此补丁基准设置为 <操作系统名称> 实例的默认补丁基准)** 旁边的框。
**注意**
只有在 2022 年 12 月 22 日 [补丁策略](patch-manager-policies.md) 发布之前首次访问 Patch Manager时，此选项才可用。
有关将现有补丁基准设置为默认项的信息，请参阅 [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)。
1. 在 **Approval rules for operating-systems (操作系统的批准规则)** 部分，使用字段创建一个或多个自动批准规则。
+ **产品**：批准规则适用的操作系统版本，例如 `RedhatEnterpriseLinux7.4`。默认选择为 `All`。
+ **Classification (分类)**：批准规则适用于的补丁的类型，例如 `Security` 或 `Enhancement`。默认选择为 `All`。
**提示**
您可以配置补丁基准来控制是否安装 Linux 的次要版本升级，如 RHEL 7.8。次要版本升级可由 Patch Manager 自动安装，前提是此更新在适当的存储库中可用。
对于 Linux 操作系统，次要版本升级的分类方式不一致。它们可以分类为错误修复或安全更新，或者不分类，即使在同一内核版本中也是如此。以下是控制补丁基准是否安装这些补丁的几个选项。
**选项 1**：确保在可用时安装次要版本升级的最广泛的批准规则是将 **Classification**（分类）指定为 `All` (\$1)，然后选择 **Include nonsecurity updates**（包括非安全更新）选项。
**选项 2**：为确保安装操作系统版本的补丁，您可以使用通配符 (\$1) 在基准的 **Patch exceptions (补丁例外)** 部分指定其内核格式。例如，RHEL 7.\$1 的内核格式为 `kernel-3.10.0-*.el7.x86_64`。
在补丁基准中的 **Approved patches**（已批准补丁）列表中输入 `kernel-3.10.0-*.el7.x86_64`，以确保所有补丁（包括次要版本升级）都应用到 RHEL 7.\$1 托管式节点。（如果您知道次要版本补丁的确切程序包名称，则可以输入此名称。）
**Option 3**（选项 3）：通过使用 `AWS-RunPatchBaseline` 文档中的 [InstallOverrideList](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-installoverridelist) 参数，您可以最大程度地控制应用于托管式节点的补丁（包括次要版本升级）。有关更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
+ **Severity (严重性)**：规则适用于的补丁的严重性值，例如 `Critical`。默认选择为 `All`。
+ **Auto-approval**（自动批准）：选择要自动批准的补丁的方法。
**注意**
由于无法可靠地确定 Ubuntu Server 的更新程序包的发布日期，因此此操作系统不支持自动批准选项。
+ **在指定的天数后批准补丁**：Patch Manager 在发布或最后更新补丁之后等待的天数，然后自动批准补丁。可以输入零 (0) 到 360 的任何整数。对于大多数情况，我们建议等待期不超过 100 天。
+ **批准在特定日期之前发布的补丁**：补丁发布日期，Patch Manager 自动应用在该日期或之前发布或更新的所有补丁。例如，如果指定 2023 年 7 月 7 日，则不会自动安装在 2023 年 7 月 8 日或之后发布或最后更新的任何补丁。
+ （可选）**合规性报告**：要分配给基准批准的补丁的严重性级别，例如 `Critical` 或 `High`。
**注意**
如果您指定合规性报告级别以及任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
+ **Include non-security updates (包括非安全性更新)**：选中此复选框，除了可以安装与安全性相关的补丁外，还可以安装源存储库中提供的非安全性 Linux 操作系统补丁。
有关在自定义补丁基准中使用批准规则的更多信息，请参阅 [自定义基准](patch-manager-predefined-and-custom-patch-baselines.md#patch-manager-baselines-custom)。
1. 如果要明确批准除满足批准规则的补丁外的任何补丁，请在 **Patch exceptions (补丁例外)** 部分执行以下操作：
+ 对于 **Approved patches (已批准的补丁)**，输入要批准的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ （可选）对于 **Approved patches compliance level (已批准补丁合规性级别)**，为列表中的补丁分配合规性级别。
+ 如果您指定的任何已批准的补丁与安全性无关，请选中**包括非安全性更新**复选框，以便也在 Linux 操作系统上安装这些补丁。
1. 如果要明确拒绝除满足批准规则的补丁外的任何补丁，请在 **Patch exceptions (补丁例外)** 部分执行以下操作：
+ 对于 **Rejected patches (已拒绝的补丁)**，输入要拒绝的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ 对于**已拒绝的补丁操作**，请选择 Patch Manager 要对**已拒绝的补丁**列表中包含的补丁采取的操作。
+ **允许作为依赖项**：仅当**已拒绝的补丁**列表中的软件包是另一个软件包的依赖项时，才安装它。它被视为符合补丁基准，并且它的状态报告为 *InstalledOther*。这是未指定选项时的默认操作。
+ **阻止**：在任何情况下，Patch Manager 都不安装**已拒绝补丁**列表中的软件包以及包含相关补丁作为依赖项的软件包。如果在将软件包添加到**已拒绝补丁**列表之前已安装该软件包，或者之后会在 Patch Manager 外部安装该软件包，则将其视为不符合补丁基准并将状态报告为 *InstalledRejected*。
**注意**
Patch Manager 递归搜索补丁依赖项。
1. （可选）如果您要为不同版本的操作系统 (如 *AmazonLinux2016.03* 和 *AmazonLinux2017.09*) 指定备用补丁存储库，请为 **Patch sources (补丁来源)** 部分中的每个产品执行以下操作：
+ 在 **Name (名称)** 中，输入名称以帮助您标识源配置。
+ 在 **Product**（产品）中，请选择补丁源存储库适用于的操作系统的版本，例如 `RedhatEnterpriseLinux7.4`。
+ 在**配置**中，输入要以适当格式使用的存储库配置的值：
------
#### [ Example for yum repositories ]
```
[main]
name=MyCustomRepository
baseurl=https://my-custom-repository
enabled=1
```
**提示**
有关 yum 存储库配置可用的其他选项的信息，请参阅 [dnf.conf(5)](https://man7.org/linux/man-pages/man5/dnf.conf.5.html)。
------
#### [ Examples for Ubuntu Server and Debian 服务器 ]
`deb http://security.ubuntu.com/ubuntu jammy main`
`deb https://site.example.com/debian distribution component1 component2 component3`
必须在一行中指定 Ubuntu Server 存储库的存储库信息。有关更多示例和信息，请参阅 *Ubuntu 服务器手册*网站上的 [jammy (5) sources.list.5.gz](https://manpages.ubuntu.com/manpages/jammy/man5/sources.list.5.html) 以及 *Debian Wiki* 上的 [sources.list 格式](https://wiki.debian.org/SourcesList#sources.list_format)。
------
选择**添加其他来源**来为每个其他操作系统版本指定源存储库，最多 20 个。
有关备用源补丁存储库的更多信息，请参阅 [如何指定备用补丁源存储库 (Linux)](patch-manager-alternative-source-repository.md)。
1. （可选）对于**管理标签**，将一个或多个标签键名称/值对应用到补丁基准。
标签是您分配给资源的可选元数据。标签允许您按各种标准（如用途、所有者或环境）对资源进行分类。例如，您可能想要标记补丁基准来确定其指定的补丁的严重性级别、它适用的操作系统系列以及环境类型。在这种情况下，您可以指定类似于以下键名称/值对的标签：
+ `Key=PatchSeverity,Value=Critical`
+ `Key=OS,Value=RHEL`
+ `Key=Environment,Value=Production`
1. 请选择**创建补丁基准**。
# 创建适用于 macOS 的自定义补丁基准
在Patch Manager（AWS Systems Manager 中的一项工具）中，按照以下过程为 macOS 托管式节点创建自定义补丁基准。
有关为 Windows Server 托管式节点创建补丁基准的信息，请参阅 [创建适用于 Windows Server 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-windows.md)。有关为 Linux 托管式节点创建补丁基准的信息，请参阅 [创建适用于 Linux 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-linux.md)。
**注意**
并非所有 AWS 区域 都支持 macOS。有关对适用于 macOS 的 Amazon EC2 支持的一般信息，请参阅《Amazon EC2 用户指南》**中的 [Amazon EC2 Mac 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html)。
**为 macOS 托管式节点创建自定义补丁基准**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡，然后选择**创建补丁基准**。
–或者–
如果您是在当前 AWS 区域首次访问 Patch Manager，请选择**从概览开始**，然后选择**补丁基准**选项卡，然后选择**创建补丁基准**。
1. 在 **Name (名称)** 中，输入新补丁基准的名称，例如，`MymacOSPatchBaseline`。
1. （可选）对于 **Description (描述)**，输入此补丁基准的描述。
1. 对于 **Operating system**（操作系统），请选择 macOS。
1. 如果要在创建后即开始将此补丁基准用作 macOS 的默认项，请选中**将此补丁基准设置为 macOS 实例的默认补丁基准** 旁边的框。
**注意**
只有在 2022 年 12 月 22 日 [补丁策略](patch-manager-policies.md) 发布之前首次访问 Patch Manager时，此选项才可用。
有关将现有补丁基准设置为默认项的信息，请参阅 [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)。
1. 在 **Approval rules for operating-systems (操作系统的批准规则)** 部分，使用字段创建一个或多个自动批准规则。
+ **产品**：批准规则适用的操作系统版本，例如 `BigSur11.3.1` 或 `Ventura13.7`。默认选择为 `All`。
+ **分类**：要在修补过程中应用软件包的软件包管理器。可从以下选项中进行选择：
+ 软件更新
+ 安装程序
+ 酿造
+ 酿造桶
默认选择为 `All`。
+ （可选）**合规性报告**：要分配给基准批准的补丁的严重性级别，例如 `Critical` 或 `High`。
**注意**
如果您指定合规性报告级别以及任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
有关在自定义补丁基准中使用批准规则的更多信息，请参阅 [自定义基准](patch-manager-predefined-and-custom-patch-baselines.md#patch-manager-baselines-custom)。
1. 如果要明确批准除满足批准规则的补丁外的任何补丁，请在 **Patch exceptions (补丁例外)** 部分执行以下操作：
+ 对于 **Approved patches (已批准的补丁)**，输入要批准的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ （可选）对于 **Approved patches compliance level (已批准补丁合规性级别)**，为列表中的补丁分配合规性级别。
1. 如果要明确拒绝除满足批准规则的补丁外的任何补丁，请在 **Patch exceptions (补丁例外)** 部分执行以下操作：
+ 对于 **Rejected patches (已拒绝的补丁)**，输入要拒绝的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ 对于**已拒绝的补丁操作**，请选择 Patch Manager 要对**已拒绝的补丁**列表中包含的补丁采取的操作。
+ **允许作为依赖项**：仅当**已拒绝的补丁**列表中的软件包是另一个软件包的依赖项时，才安装它。它被视为符合补丁基准，并且它的状态报告为 *InstalledOther*。这是未指定选项时的默认操作。
+ **阻止**：在任何情况下，Patch Manager 都不安装**已拒绝补丁**列表中的软件包以及包含相关补丁作为依赖项的软件包。如果在将软件包添加到**已拒绝补丁**列表之前已安装该软件包，或者之后会在 Patch Manager 外部安装该软件包，则将其视为不符合补丁基准并将状态报告为 *InstalledRejected*。
1. （可选）对于**管理标签**，将一个或多个标签键名称/值对应用到补丁基准。
标签是您分配给资源的可选元数据。标签允许您按各种标准（如用途、所有者或环境）对资源进行分类。例如，您可能想要标记补丁基准来确定其指定的补丁的严重性级别、它适用的软件包管理器以及环境类型。在这种情况下，您可以指定类似于以下键名称/值对的标签：
+ `Key=PatchSeverity,Value=Critical`
+ `Key=PackageManager,Value=softwareupdate`
+ `Key=Environment,Value=Production`
1. 请选择**创建补丁基准**。
# 创建适用于 Windows Server 的自定义补丁基准
在Patch Manager（AWS Systems Manager 中的一项工具）中，按照以下过程为 Windows 托管式节点创建自定义补丁基准。
有关为 Linux 托管式节点创建补丁基准的信息，请参阅 [创建适用于 Linux 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-linux.md)。有关为 macOS 托管式节点创建补丁基准的信息，请参阅 [创建适用于 macOS 的自定义补丁基准](patch-manager-create-a-patch-baseline-for-macos.md)。
有关创建仅限于安装 Windows Service Pack 的补丁基准的示例，请参阅 [教程：使用控制台创建用于安装 Windows Service Pack 的补丁基准](patch-manager-windows-service-pack-patch-baseline-tutorial.md)。
**创建自定义补丁基准 (Windows)**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡，然后选择**创建补丁基准**。
–或者–
如果您是在当前 AWS 区域首次访问 Patch Manager，请选择**从概览开始**，然后选择**补丁基准**选项卡，然后选择**创建补丁基准**。
1. 在 **Name (名称)** 中，输入新补丁基准的名称，例如，`MyWindowsPatchBaseline`。
1. （可选）对于 **Description (描述)**，输入此补丁基准的描述。
1. 对于 **Operating system**（操作系统），请选择 `Windows`。
1. 对于**可用安全更新合规性状态**，需选择要分配给可用但尚未批准的安全补丁（这些补丁不符合补丁基准中指定的安装标准因此未获批准）的状态，即**不合规**或**合规**。
示例场景：如果您指定在补丁发布后等待较长时间再进行安装，则会跳过某些您可能希望安装的安全补丁。如果在您指定的等待期内发布了该补丁的更新版本，则该补丁的安装等待期将重新开始。如果等待期过长，则可能会发布多个版本的补丁，但不会进行安装。
1. 如果要在创建后即开始将此补丁基准用作 Windows 的默认项，请选择 **Set this patch baseline as the default patch baseline for Windows Server instances**（将此补丁基准设置为 Windows Server 实例的默认补丁基准）。
**注意**
只有在 2022 年 12 月 22 日 [补丁策略](patch-manager-policies.md) 发布之前首次访问 Patch Manager时，此选项才可用。
有关将现有补丁基准设置为默认项的信息，请参阅 [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)。
1. 在 **Approval rules for operating systems (操作系统的批准规则)** 部分，使用字段创建一个或多个自动批准规则。
+ **产品**：批准规则适用的操作系统版本，例如 `WindowsServer2012`。默认选择为 `All`。
+ **Classification (分类)**：批准规则适用于的补丁的类型，例如 `CriticalUpdates`、`Drivers` 和 `Tools`。默认选择为 `All`。
**提示**
您可以在您的批准规则中包括 Windows 服务包安装，方法是包含 `ServicePacks` 或通过在您的**分类**列表中选择 `All`。有关示例，请参阅 [教程：使用控制台创建用于安装 Windows Service Pack 的补丁基准](patch-manager-windows-service-pack-patch-baseline-tutorial.md)。
+ **Severity (严重性)**：规则适用于的补丁的严重性值，例如 `Critical`。默认选择为 `All`。
+ **Auto-approval**（自动批准）：选择要自动批准的补丁的方法。
+ **在指定的天数后批准补丁**：Patch Manager 在发布或更新补丁之后等待的天数，然后自动批准补丁。可以输入零 (0) 到 360 的任何整数。对于大多数情况，我们建议等待期不超过 100 天。
+ **批准在特定日期之前发布的补丁**：补丁发布日期，Patch Manager 自动应用在该日期或之前发布或更新的所有补丁。例如，如果指定 2023 年 7 月 7 日，则不会自动安装在 2023 年 7 月 8 日或之后发布或最后更新的任何补丁。
+ （可选）**Compliance reporting（合规性报告）**：要分配给基准批准的补丁的严重性级别，例如 `High`。
**注意**
如果您指定合规性报告级别以及任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
1. （可选）在**应用程序的批准规则**部分，使用字段创建一个或多个自动批准规则。
**注意**
您可以将已批准和已拒绝的补丁列表指定为补丁例外，而不是指定批准规则。请参阅步骤 10 和 11。
+ **Product family (产品系列)**：您要为其指定规则的一般 Microsoft 产品系列，如 `Office` 或 `Exchange Server`。
+ **产品**：批准规则适用的应用程序版本，例如 `Office 2016` 或 `Active Directory Rights Management Services Client 2.0 2016`。默认选择为 `All`。
+ **Classification (分类)**：批准规则适用于的补丁的类型，例如 `CriticalUpdates`。默认选择为 `All`。
+ **Severity (严重性)**：规则适用于的补丁的严重性值，如 `Critical`。默认选择为 `All`。
+ **Auto-approval**（自动批准）：选择要自动批准的补丁的方法。
+ **在指定的天数后批准补丁**：Patch Manager 在发布或更新补丁之后等待的天数，然后自动批准补丁。可以输入零 (0) 到 360 的任何整数。对于大多数情况，我们建议等待期不超过 100 天。
+ **批准在特定日期之前发布的补丁**：补丁发布日期，Patch Manager 自动应用在该日期或之前发布或更新的所有补丁。例如，如果指定 2023 年 7 月 7 日，则不会自动安装在 2023 年 7 月 8 日或之后发布或最后更新的任何补丁。
+ （可选）**合规性报告**：要分配给基准批准的补丁的严重性级别，例如 `Critical` 或 `High`。
**注意**
如果您指定合规性报告级别以及任何已批准补丁的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
1. （可选）如果要明确批准任何补丁，而不是允许根据批准规则选择补丁，请在**修补例外**部分进行以下操作：
+ 对于 **Approved patches (已批准的补丁)**，输入要批准的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ （可选）对于 **Approved patches compliance level (已批准补丁合规性级别)**，为列表中的补丁分配合规性级别。
1. 如果要明确拒绝除满足批准规则的补丁外的任何补丁，请在 **Patch exceptions (补丁例外)** 部分执行以下操作：
+ 对于 **Rejected patches (已拒绝的补丁)**，输入要拒绝的补丁的逗号分隔列表。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
+ 对于**已拒绝的补丁操作**，请选择 Patch Manager 要对**已拒绝的补丁**列表中包含的补丁采取的操作。
+ **允许作为依赖项**：Windows Server 不支持软件包依赖项的概念。如果**已拒绝的补丁**列表中的软件包已安装在节点上，则其状态将报告为 `INSTALLED_OTHER`。任何尚未安装在节点上的软件包都将被跳过。
+ **阻止**：Patch Manager 在任何情况下都不会安装**已拒绝的补丁**列表中的软件包。如果在将软件包添加到**已拒绝补丁**列表之前已安装该软件包，或者之后会在 Patch Manager 外部安装该软件包，则将其视为不符合补丁基准并将状态报告为 `INSTALLED_REJECTED`。
有关已拒绝软件包操作的更多信息，请参阅[自定义补丁基准中的“已拒绝的补丁”列表选项](patch-manager-windows-and-linux-differences.md#rejected-patches-diff)。
1. （可选）对于**管理标签**，将一个或多个标签键名称/值对应用到补丁基准。
标签是您分配给资源的可选元数据。标签允许您按各种标准（如用途、所有者或环境）对资源进行分类。例如，您可能想要标记补丁基准来确定其指定的补丁的严重性级别、它适用的操作系统系列以及环境类型。在这种情况下，您可以指定类似于以下键名称/值对的标签：
+ `Key=PatchSeverity,Value=Critical`
+ `Key=OS,Value=RHEL`
+ `Key=Environment,Value=Production`
1. 请选择**创建补丁基准**。
# 更新或删除自定义补丁基准
您可以更新或删除自己在Patch Manager（AWS Systems Manager 中的一项工具）中创建的自定义补丁基准。更新补丁基准时，可以更改它的名称或说明、批准规则，以及对已批准和已拒绝补丁的例外。另外还可以更新应用于补丁基准的标签。您不能更改为其创建补丁基准的操作系统类型，也不能对 AWS 提供的预定义补丁基准进行更改。
## 更新或删除补丁基准
请按照以下步骤更新或删除补丁基准。
**重要**
在 Quick Setup 中删除补丁策略配置可能使用的自定义补丁基准时要谨慎。
如果您在 Quick Setup 中使用[补丁策略配置](patch-manager-policies.md)，则系统会每小时与 Quick Setup 同步一次您对自定义补丁基准所做的更新。
如果删除了补丁策略中引用的自定义补丁基准，那么补丁策略的 Quick Setup **Configuration details**（配置详细信息）页面上会显示一个横幅。横幅将通知您，补丁策略引用的补丁基准已不存在，且后续的修补操作将失败。在这种情况下，返回 Quick Setup **Configurations**（配置）页面，选择 Patch Manager 配置，然后选择 **Actions**（操作），**Edit configuration**（编辑配置）。已删除的补丁基准名称将突出显示，您必须为受影响的操作系统选择新的补丁基准。
**更新或删除补丁基准**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 请选择要更新或删除的补丁基准，然后执行以下操作之一：
+ 要从您的 AWS 账户 中删除补丁基准，请选择**删除**。系统将提示您确认操作。
+ 要对补丁基准的名称或说明、批准规则或补丁例外进行更改，请选择 **Edit**（编辑）。在 **Edit patch baseline**（编辑补丁基准）页面中，更改所需的值和选项，然后选择 **Save changes**（保存更改）。
+ 要添加、更改或删除应用到补丁基准的标签，请选择 **Tags (标签)** 选项卡，然后选择 **Edit tags (编辑标签)**。在 **Edit patch baseline tags (编辑补丁基准标签)** 页面上，对补丁基准标签进行更新，然后选择 **Save changes (保存更改)**。
有关您可以进行的配置选择的信息，请参阅 [使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
# 将现有补丁基准设置为默认项
**重要**
您在此处所作的任何默认补丁基准选择均不适用于基于补丁策略的修补操作。补丁策略将使用自身的补丁基准规范。有关补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
当您在Patch Manager（AWS Systems Manager 中的一项工具）中创建自定义补丁基准时，可在创建后便将此基准设置为关联的操作系统类型的默认项。有关信息，请参阅[使用自定义补丁基准](patch-manager-manage-patch-baselines.md)。
您还可以将现有补丁基准设置为某个操作系统类型的默认项。
**注意**
您执行的步骤取决于您首次访问 Patch Manager 是在 2022 年 12 月 22 日补丁策略发布之前还是之后。如果您在此日期之前使用过 Patch Manager，则可以使用控制台过程。否则，请使用 AWS CLI 过程。补丁策略发布前未使用 Patch Manager 的区域不会显示控制台过程中引用的**操作**菜单。
**将补丁基准设置为默认项**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡。
1. 在补丁基准列表中，选择当前未设置为操作系统类型的默认项的补丁基准的按钮。
**Default baseline (默认基准)** 列指示哪些基准当前被设置为默认项。
1. 在 **Actions (操作)** 菜单中，选择 **Set default patch baseline (设置默认补丁基准)**。
**重要**
如果您在 2022 年 12 月 22 日之前未在当前 AWS 账户 和区域中使用 Patch Manager，则**操作**菜单不可用。有关更多信息，请参阅本主题前面的**注释**。
1. 在确认对话框中，选择 **Set default (设置默认值)**。
**将补丁基准设置为默认项（AWS CLI）**
1. 运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-baselines.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-baselines.html) 命令以查看可用补丁基准及其 ID 和 Amazon 资源名称（ARN）的列表。
```
aws ssm describe-patch-baselines
```
1. 运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-default-patch-baseline.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-default-patch-baseline.html) 命令将基准设置为与其关联的操作系统的默认设置。将 *baseline-id-or-ARN* 替换为要使用的自定义补丁基准或预定义基准的 ID。
------
#### [ Linux & macOS ]
```
aws ssm register-default-patch-baseline \
--baseline-id baseline-id-or-ARN
```
以下是将自定义基准设置为默认基准的示例。
```
aws ssm register-default-patch-baseline \
--baseline-id pb-abc123cf9bEXAMPLE
```
以下是将 AWS 托管的预定义基准设置为默认基准的示例。
```
aws ssm register-default-patch-baseline \
--baseline-id arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-0574b43a65ea646e
```
------
#### [ Windows Server ]
```
aws ssm register-default-patch-baseline ^
--baseline-id baseline-id-or-ARN
```
以下是将自定义基准设置为默认基准的示例。
```
aws ssm register-default-patch-baseline ^
--baseline-id pb-abc123cf9bEXAMPLE
```
以下是将 AWS 托管的预定义基准设置为默认基准的示例。
```
aws ssm register-default-patch-baseline ^
--baseline-id arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-071da192df1226b63
```
------
# 查看可用的补丁
使用Patch Manager（AWS Systems Manager 中的一项工具），您可以查看指定操作系统以及特定操作系统版本（可选）的所有可用补丁。
**提示**
要生成可用补丁列表并将其保存到文件中，可以使用 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-available-patches.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-available-patches.html) 命令并指定您的首选[输出](https://docs.aws.amazon.com/cli/latest/reference/ssm/cli-usage-output.html)。
**查看可用补丁**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁**选项卡。
–或者–
如果您是在当前 AWS 区域首次访问 Patch Manager，请选择**从概览开始**，然后选择**补丁**选项卡。
**注意**
对于 Windows Server，**补丁**选项卡显示 Windows Server 更新服务（WSUS）提供的更新。
1. 对于**操作系统**，选择要查看其可用补丁的操作系统，例如 `Windows` 或者 `Amazon Linux`。
1. （可选）对于**产品**，选择操作系统版本，例如 `WindowsServer2019` 或者 `AmazonLinux2018.03`。
1. （可选）要添加或删除结果的信息列，请选择位于**补丁**列表右上方的配置按钮 (![\[The icon to view configuration settings.\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/configure-button.png))。（默认情况下，**补丁**选项卡仅显示部分可用补丁元数据的列。）
有关可以添加到视图中的元数据类型的信息，请参阅 *AWS Systems Manager API 参考*中的[补丁](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Patch.html)。
# 创建和管理补丁组
如果您在操作中*未*使用补丁策略，则可以通过使用标签将托管式节点添加到补丁组来组织修补工作。
**注意**
补丁组不会用于基于*补丁策略*的修补操作。有关使用补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
对于在 2022 年 12 月 22 日发布补丁策略支持之前尚未使用补丁组的账户-区域对，控制台不支持补丁组功能。补丁组功能在此日期之前开始使用补丁组的账户区域对中仍然可用。
要在修补操作中使用标签，必须将标签键 `Patch Group` 或 `PatchGroup` 应用于托管式节点。您还必须指定要为补丁组提供的名称作为标签的值。您可以指定任何标签值，但标签键必须为 `Patch Group` 或 `PatchGroup`。
如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`（不带空格）。
使用标签对托管式节点进行分组后，请将补丁组值添加到补丁基准。通过将补丁组注册到补丁基准，您可以确保在修补操作期间安装正确的补丁。有关补丁组的更多信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
完成本主题中的任务，使用带节点和补丁基准的标签对托管式节点进行修补。只有在修补 Amazon EC2 实例时才需要执行任务 1。只有在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中修补非 EC2 实例时才需要执行任务 2。所有托管式节点都必须执行任务 3。
**提示**
您还可以使用 AWS CLI 命令 `[https://docs.aws.amazon.com/cli/latest/reference/ssm/add-tags-to-resource.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/add-tags-to-resource.html)` 或 Systems Manager API 操作 ssm-agent-minimum-s3-permissions-required`[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_AddTagsToResource.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_AddTagsToResource.html)`，向托管式节点添加标签。
**Topics**
+ [任务 1：请使用标签将 EC2 实例添加到补丁组](#sysman-patch-group-tagging-ec2)
+ [任务 2：使用标签将托管式节点添加到补丁组](#sysman-patch-group-tagging-managed)
+ [任务 3：将补丁组添加到补丁基准](#sysman-patch-group-patchbaseline)
## 任务 1：请使用标签将 EC2 实例添加到补丁组
您可以使用 Systems Manager 控制台或 Amazon EC2 控制台向 EC2 实例添加标签。只有在修补 Amazon EC2 实例时才需要执行此任务。
**重要**
如果在实例上启用 **Allow tags in instance metadata**（允许在实例元数据中使用标签）选项，则无法将 `Patch Group` 标签（带空格）应用于 Amazon EC2 实例。允许在实例元数据中使用标签会导致标签密钥名称不得包含空格。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用标签键 `PatchGroup`（不带空格）。
**选项 1：将 EC2 实例添加到补丁组（Systems Manager 控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 在**托管式节点**列表中，选择您要配置以进行修补的托管式 EC2 实例的 ID。EC2 实例的节点 ID 以 `i-` 开头。
**注意**
使用 Amazon EC2 控制台和 AWS CLI 时，可以将 `Key = Patch Group` 或 `Key = PatchGroup` 标签应用于尚未配置为与 Systems Manager 结合使用的实例。
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 选择**标签**选项卡，然后选择**编辑**。
1. 在左列中，输入 **Patch Group** 或 **PatchGroup**。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`（不带空格）。
1. 在右列中，输入一个标签值作为此补丁组的名称。
1. 选择**保存**。
1. 重复此过程，向同一补丁组中添加其他 EC2 实例。
**选项 2：将 EC2 实例添加到补丁组（Amazon EC2 控制台）**
1. 打开 [ Amazon EC2 控制台](https://console.aws.amazon.com/ec2/)，然后在导航窗格中选择**实例**。
1. 从实例列表中选择您要配置用于修补的实例。
1. 在**操作**菜单中，依次选择**实例设置**、**管理标签**。
1. 选择**添加新标签**。
1. 对于 **Key**（键），输入 **Patch Group** 或 **PatchGroup**。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`（不带空格）。
1. 对于**值**，输入一个值作为此补丁组的名称。
1. 选择**保存**。
1. 重复此过程，向同一补丁组中添加其他实例。
## 任务 2：使用标签将托管式节点添加到补丁组
按照本主题中的步骤，向 AWS IoT Greengrass 核心设备和非 EC2 混合激活的托管式节点（mi-\$1）添加标签。只有在混合和多云环境中修补非 EC2 实例时才需要执行此任务。
**注意**
您不能使用 Amazon EC2 控制台为非 EC2 托管式节点添加标签。
**将非 EC2 托管式节点添加到补丁组（Systems Manager 控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Fleet Manager**。
1. 在**托管实例**列表中，选择您要为修补配置的托管节点的名称。
**注意**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 选择**标签**选项卡，然后选择**编辑**。
1. 在左列中，输入 **Patch Group** 或 **PatchGroup**。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`（不带空格）。
1. 在右列中，输入一个标签值作为此补丁组的名称。
1. 选择**保存**。
1. 重复此过程，向同一补丁组添加其他托管式节点。
## 任务 3：将补丁组添加到补丁基准
要将特定的补丁基准与托管式节点关联，必须将补丁组值添加到补丁基准。通过将补丁组注册到补丁基准，您可以确保在修补操作期间安装正确的补丁。无论是修补 EC2 实例、非 EC2 托管式节点还是两者，都需要执行此任务。
有关补丁组的更多信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
**注意**
您执行的步骤取决于您首次访问 Patch Manager 是在 2022 年 12 月 22 日[补丁策略](patch-manager-policies.md)发布之前还是之后。
**将补丁组添加到补丁基准（Systems Manager 控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 如果您是首次在当前 AWS 区域 中访问 Patch Manager，并且 Patch Manager 起始页打开，则请选择**从概览开始**。
1. 选择**补丁基准**选项卡，然后在**补丁基准**列表中，选择要为补丁组配置的补丁基准的名称。
如果您在补丁策略发布后才首次访问 Patch Manager，则必须选择已创建的自定义基准。
1. 如果**基准 ID** 详细信息页面包含**操作**菜单，请执行以下操作：
+ 选择 **Actions (操作)**，然后选择 **Modify patch groups (修改补丁组)**。
+ 在 [任务 2：使用标签将托管式节点添加到补丁组](#sysman-patch-group-tagging-managed) 中输入您添加到托管式节点的标签*值*，然后选择**添加**。
如果**基准 ID** 详细信息页面*不*包含**操作**菜单，则无法在控制台中配置补丁组。请改为执行以下操作之一：
+ （推荐）在Quick Setup（AWS Systems Manager 中的一项工具）中设置补丁策略，将补丁基准映射到一个或多个 EC2 实例。
有关更多信息，请参阅 [Using Quick Setup patch policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager-policies.html) 和 [Automate organization-wide patching using a Quick Setup patch policy](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-patch-manager.html)。
+ 使用 AWS Command Line Interface（AWS CLI）中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-patch-baseline-for-patch-group.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-patch-baseline-for-patch-group.html) 命令配置补丁组。
# 将 Patch Manager 与 AWS Security Hub CSPM 集成
[AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) 向您提供 AWS 中安全状态的全面视图。Security Hub CSPM 会跨 AWS 账户、AWS 服务 和受支持的第三方合作伙伴产品收集安全数据。利用 Security Hub CSPM，您可以根据安全行业标准和最佳实践检查您的环境。Security Hub CSPM 帮助您分析安全趋势并确定最高优先级的安全问题。
通过使用Patch Manager（AWS Systems Manager 中的一项工具）和 Security Hub CSPM 之间的集成，您可以将有关不合规节点的调查发现从Patch Manager发送至 Security Hub CSPM。调查发现是安全检查或与安全相关的检测的可观测记录。然后，Security Hub CSPM 可以在其对您的安全状况分析中包含这些补丁相关的调查发现。
无论您使用哪种配置方法或类型进行修补操作，以下主题中的信息都适用：
+ Quick Setup 中配置的补丁策略
+ Quick Setup 中配置的主机管理选项
+ 运行补丁 `Scan` 或 `Install` 任务的维护时段
+ 按需 **Patch now**（立即修补）操作
**Contents**
+ [Patch Manager 如何将调查发现发送到 Security Hub CSPM](#securityhub-integration-sending-findings)
+ [Patch Manager 发送的结果类型](#securityhub-integration-finding-types)
+ [发送调查发现的延迟](#securityhub-integration-finding-latency)
+ [Security Hub CSPM 不可用时重试](#securityhub-integration-retry-send)
+ [查看 Security Hub CSPM 中的 调查发现](#securityhub-integration-view-findings)
+ [来自 Patch Manager 的典型调查发现](#securityhub-integration-finding-example)
+ [打开并配置集成](#securityhub-integration-enable)
+ [如何停止发送调查发现](#securityhub-integration-disable)
## Patch Manager 如何将调查发现发送到 Security Hub CSPM
在 Security Hub CSPM 中，安全问题按调查发现进行跟踪。一些检查结果来自其他 AWS 服务或第三方合作伙伴检测到的问题。Security Hub CSPM 还有一套用于检测安全问题和生成调查发现的规则。
Patch Manager是 Systems Manager 的一项工具，能将结果发送到 Security Hub CSPM。在您通过运行 SSM 文档（`AWS-RunPatchBaseline`、`AWS-RunPatchBaselineAssociation` 或者 `AWS-RunPatchBaselineWithHooks`）来执行修补操作之后，修补信息将被发送至 Inventory 或 Compliance（都是 AWS Systems Manager 中的工具），或同时发给这两者。在库存、合规性或两者收到数据后，Patch Manager 会收到通知。然后,Patch Manager 评估数据的准确性、格式化和合规性。如果满足所有条件，Patch Manager将数据转发到 Security Hub CSPM。
Security Hub CSPM 提供了用于管理来自所有这些来源的调查发现的工具。您可以查看和筛选调查发现列表，并查看调查发现的详细信息。有关更多信息，请参阅 *AWS Security Hub 用户指南*中的[查看结果](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-viewing.html)。您还可以跟踪调查发现的调查状态。有关更多信息，请参阅 *AWS Security Hub 用户指南*中[对结果采取行动](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-taking-action.html)。
Security Hub CSPM 中的所有调查发现都使用名为 AWS 安全调查发现格式（ASFF）的标准 JSON 格式。ASFF 包含有关问题根源、受影响资源以及调查发现当前状态的详细信息。有关更多信息，请参阅《AWS Security Hub 用户指南》**中的 [AWS 安全调查发现格式（ASFF）](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.htm)。
### Patch Manager 发送的结果类型
Patch Manager 使用 [AWS 安全调查发现格式（ASFF）](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html)将调查发现发送到 Security Hub CSPM。在 ASFF 中，`Types` 字段提供调查发现类型。来自 Patch Manager 的结果可能具有 `Types` 的以下值：
+ 软件和配置检查/补丁管理
Patch Manager 为每个不合规的托管式节点发送一个调查发现。调查发现与资源类型 [https://docs.aws.amazon.com//securityhub/latest/userguide/securityhub-findings-format-attributes.html#asff-resourcedetails-awsec2instance](https://docs.aws.amazon.com//securityhub/latest/userguide/securityhub-findings-format-attributes.html#asff-resourcedetails-awsec2instance) 一起报告，以便调查发现可以与其他 Security Hub CSPM 集成相关联，这些集成会报告 `AwsEc2Instance` 资源类型。只有当操作发现托管式节点不合规时，Patch Manager 才会将调查发现转发给 Security Hub CSPM。调查发现中包括补丁摘要结果。
**注意**
向 Security Hub CSPM 报告不合规的节点之后。节点合规后Patch Manager不会向 Security Hub CSPM 发送更新。将所需的补丁应用到托管式节点后，您可以在 Security Hub CSPM 中手动解决调查发现的问题。
有关合规性定义的更多信息，请参阅 [补丁合规性状态值](patch-manager-compliance-states.md)。有关 `PatchSummary` 的更多信息，请参阅 *AWS Security Hub API 参考*中的[补丁程序摘要](https://docs.aws.amazon.com//securityhub/1.0/APIReference/API_PatchSummary.html)。
### 发送调查发现的延迟
当Patch Manager创建新调查发现时，通常会在几秒到 2 小时内将结果发送到 Security Hub CSPM。速度取决于处理 AWS 区域 时的流量。
### Security Hub CSPM 不可用时重试
如果存在服务中断，则运行 AWS Lambda 函数，以便在服务再次运行后将消息放回主队列。当消息进入主队列后，将自动重试。
如果 Security Hub CSPM 不可用，Patch Manager重试发送调查发现，直到收到这些调查发现。
### 查看 Security Hub CSPM 中的 调查发现
此程序介绍如何在 Security Hub CSPM 中查看有关实例集中不符合补丁合规性的托管式节点的调查发现。
**查看补丁合规性的 Security Hub CSPM 调查发现**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 AWS Security Hub CSPM 控制台：[https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/)。
1. 在导航窗格中，选择 **调查发现**。
1. 选择**添加筛选条件**（![\[The Search icon\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/search-icon.png)）框。
1. 在菜单中的**筛选条件**下，选择**产品名称**。
1. 在打开的对话框中，在第一个字段中选择 **is**，然后在第二个字段中输入 **Systems Manager Patch Manager**。
1. 选择**应用**。
1. 添加您需要的任何其他筛选条件以帮助缩小搜索范围。
1. 在结果列表中，选择您想了解更多信息的调查发现的标题。
屏幕右侧将打开一个窗格，其中包含有关资源、发现的问题和建议补救措施的更多详细信息。
**重要**
目前，Security Hub CSPM 将所有托管式节点的资源类型报告为 `EC2 Instance`。这包括您已注册用于 Systems Manager 的本地服务器和虚拟机（VM）。
**严重性分类**
**Systems Manager Patch Manager** 的调查发现列表包括有关调查发现严重性的报告。**严重性**级别包括以下内容（从最低到最高）：
+ **性** – 未发现任何问题。
+ **低** – 问题不需要修复。
+ **中** – 必须解决问题，但不是紧急的。
+ **高** – 必须优先解决问题。
+ **严重** – 必须立即解决此问题，以避免它升级。
严重性由实例上最严重的不合规软件包确定。由于您可以拥有多个具有多个严重性级别的补丁基准，因此会在所有不合规软件包中报告最高的严重性。例如，假设您有两个不合规程序包，其中程序包 A 的严重性为“严重”，而程序包 B 的严重性为“低”。“严重”将报告为严重性。
请注意，严重性字段与 Patch Manager `Compliance` 字段直接相关。这是您设置分配给与规则匹配的各个补丁的字段。由于此 `Compliance` 字段已分配给各个补丁，因此不会反映在“补丁摘要”级别。
**相关内容**
+ 《AWS Security Hub User Guide》**中的 [Findings](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings.html)
+ *AWS 管理与治理博客*中的 [Multi-Account patch compliance with Patch Manager and Security Hub](https://aws.amazon.com/blogs/mt/multi-account-patch-compliance-with-patch-manager-and-security-hub/)
## 来自 Patch Manager 的典型调查发现
Patch Manager使用 [AWS 安全调查发现格式（ASFF）](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html)将调查发现发送到 Security Hub CSPM。
下面是来自 Patch Manager 的典型调查发现的示例。
```
{
"SchemaVersion": "2018-10-08",
"Id": "arn:aws:patchmanager:us-east-2:111122223333:instance/i-02573cafcfEXAMPLE/document/AWS-RunPatchBaseline/run-command/d710f5bd-04e3-47b4-82f6-df4e0EXAMPLE",
"ProductArn": "arn:aws:securityhub:us-east-1::product/aws/ssm-patch-manager",
"GeneratorId": "d710f5bd-04e3-47b4-82f6-df4e0EXAMPLE",
"AwsAccountId": "111122223333",
"Types": [
"Software & Configuration Checks/Patch Management/Compliance"
],
"CreatedAt": "2021-11-11T22:05:25Z",
"UpdatedAt": "2021-11-11T22:05:25Z",
"Severity": {
"Label": "INFORMATIONAL",
"Normalized": 0
},
"Title": "Systems Manager Patch Summary - Managed Instance Non-Compliant",
"Description": "This AWS control checks whether each instance that is managed by AWS Systems Manager is in compliance with the rules of the patch baseline that applies to that instance when a compliance Scan runs.",
"Remediation": {
"Recommendation": {
"Text": "For information about bringing instances into patch compliance, see 'Remediating out-of-compliance instances (Patch Manager)'.",
"Url": "https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-compliance-remediation.html"
}
},
"SourceUrl": "https://us-east-2.console.aws.amazon.com/systems-manager/fleet-manager/i-02573cafcfEXAMPLE/patch?region=us-east-2",
"ProductFields": {
"aws/securityhub/FindingId": "arn:aws:securityhub:us-east-2::product/aws/ssm-patch-manager/arn:aws:patchmanager:us-east-2:111122223333:instance/i-02573cafcfEXAMPLE/document/AWS-RunPatchBaseline/run-command/d710f5bd-04e3-47b4-82f6-df4e0EXAMPLE",
"aws/securityhub/ProductName": "Systems Manager Patch Manager",
"aws/securityhub/CompanyName": "AWS"
},
"Resources": [
{
"Type": "AwsEc2Instance",
"Id": "i-02573cafcfEXAMPLE",
"Partition": "aws",
"Region": "us-east-2"
}
],
"WorkflowState": "NEW",
"Workflow": {
"Status": "NEW"
},
"RecordState": "ACTIVE",
"PatchSummary": {
"Id": "pb-0c10e65780EXAMPLE",
"InstalledCount": 45,
"MissingCount": 2,
"FailedCount": 0,
"InstalledOtherCount": 396,
"InstalledRejectedCount": 0,
"InstalledPendingReboot": 0,
"OperationStartTime": "2021-11-11T22:05:06Z",
"OperationEndTime": "2021-11-11T22:05:25Z",
"RebootOption": "NoReboot",
"Operation": "SCAN"
}
}
```
## 打开并配置集成
要使用Patch Manager与 Security Hub CSPM 的集成，必须开启 Security Hub CSPM。有关如何开启 Security Hub CSPM 的信息，请参阅《AWS Security Hub 用户指南》**中的[设置 Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-settingup.html)。
以下程序介绍如何集成Patch Manager和 Security Hub CSPM（如果 Security Hub CSPM 已处于活动状态，但Patch Manager集成处于关闭状态）。只有在手动关闭集成时，才需要完成此过程。
**把Patch Manager添加到 Security Hub CSPM 集成**
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**设置**选项卡。
–或者–
如果您是在当前 AWS 区域首次访问 Patch Manager，请选择**从概览开始**，然后选择**设置**选项卡。
1. 在**导出到 Security Hub CSPM** 部分（在**补丁合规性调查发现未导出到 Security Hub** 的右侧），选择**启用**。
## 如何停止发送调查发现
要停止向 Security Hub CSPM 发送调查发现，您可以使用 Security Hub CSPM 控制台或 API。
有关更多信息，请参阅《AWS Security Hub 用户指南》**中的以下主题：
+ [禁用和启用来自集成的结果流（控制台）](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-integrations-managing.html#securityhub-integration-findings-flow-console)
+ [禁用来自集成（Security Hub CSPM API，AWS CLI）的结果流](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-integrations-managing.html#securityhub-integration-findings-flow-disable-api)
# 使用 AWS CLI 处理 Patch Manager 资源使用
本节包含可用于为Patch Manager（AWS Systems Manager 中的一项工具）执行配置任务的 AWS Command Line Interface（AWS CLI）命令的示例。
有关通过 AWS CLI 使用自定义补丁基准对服务器环境进行修补的说明，请参阅[教程：使用 AWS CLI 修补服务器环境](patch-manager-patch-servers-using-the-aws-cli.md)。
有关使用 AWS CLI 完成 AWS Systems Manager 任务的更多信息，请参阅[AWS CLI 命令参考的 AWS Systems Manager 部分](https://docs.aws.amazon.com/cli/latest/reference/ssm/index.html)。
**Topics**
+ [AWS CLI 命令用于补丁基准](#patch-baseline-cli-commands)
+ [用于补丁组的 AWS CLI 命令](#patch-group-cli-commands)
+ [AWS CLI 命令用于查看补丁摘要和详细信息](#patch-details-cli-commands)
+ [用于扫描和修补托管式节点的 AWS CLI 命令](#patch-operations-cli-commands)
## AWS CLI 命令用于补丁基准
**Topics**
+ [创建补丁基准](#patch-manager-cli-commands-create-patch-baseline)
+ [创建对不同操作系统版本使用自定义存储库的补丁基准](#patch-manager-cli-commands-create-patch-baseline-mult-sources)
+ [更新补丁基准](#patch-manager-cli-commands-update-patch-baseline)
+ [重命名补丁基准](#patch-manager-cli-commands-rename-patch-baseline)
+ [删除补丁基准](#patch-manager-cli-commands-delete-patch-baseline)
+ [列出所有补丁基准](#patch-manager-cli-commands-describe-patch-baselines)
+ [列出所有 AWS 提供的补丁基准](#patch-manager-cli-commands-describe-patch-baselines-aws)
+ [列出我的补丁基准](#patch-manager-cli-commands-describe-patch-baselines-custom)
+ [显示补丁基准](#patch-manager-cli-commands-get-patch-baseline)
+ [获取默认补丁基准](#patch-manager-cli-commands-get-default-patch-baseline)
+ [将自定义补丁基准设置为默认基准](#patch-manager-cli-commands-register-default-patch-baseline)
+ [将 AWS 补丁基准重置为默认基准](#patch-manager-cli-commands-register-aws-patch-baseline)
+ [标记补丁基准](#patch-manager-cli-commands-add-tags-to-resource)
+ [列出补丁基准的标签](#patch-manager-cli-commands-list-tags-for-resource)
+ [从补丁基准删除标签](#patch-manager-cli-commands-remove-tags-from-resource)
### 创建补丁基准
以下命令将创建一个补丁基准，该补丁基准将在 Windows Server 2012 R2 的关键和重要安全更新发布 5 天后批准所有这些更新。还为已批准和已拒绝的补丁列表指定了补丁。此外，补丁基准已标记来指示它适用于生产环境。
------
#### [ Linux & macOS ]
```
aws ssm create-patch-baseline \
--name "Windows-Server-2012R2" \
--tags "Key=Environment,Value=Production" \
--description "Windows Server 2012 R2, Important and Critical security updates" \
--approved-patches "KB2032276,MS10-048" \
--rejected-patches "KB2124261" \
--rejected-patches-action "ALLOW_AS_DEPENDENCY" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Important,Critical]},{Key=CLASSIFICATION,Values=SecurityUpdates},{Key=PRODUCT,Values=WindowsServer2012R2}]},ApproveAfterDays=5}]"
```
------
#### [ Windows Server ]
```
aws ssm create-patch-baseline ^
--name "Windows-Server-2012R2" ^
--tags "Key=Environment,Value=Production" ^
--description "Windows Server 2012 R2, Important and Critical security updates" ^
--approved-patches "KB2032276,MS10-048" ^
--rejected-patches "KB2124261" ^
--rejected-patches-action "ALLOW_AS_DEPENDENCY" ^
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Important,Critical]},{Key=CLASSIFICATION,Values=SecurityUpdates},{Key=PRODUCT,Values=WindowsServer2012R2}]},ApproveAfterDays=5}]"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
### 创建对不同操作系统版本使用自定义存储库的补丁基准
仅适用于 Linux 托管式节点。以下命令显示如何指定要用于特定版本的 Amazon Linux 操作系统的补丁存储库。此示例使用 Amazon Linux 2017.09 上默认启用的源存储库，但可以调整为您为托管式节点配置的不同源存储库。
**注意**
为了更好地说明这一更为复杂的命令，我们将 `--cli-input-json` 选项与存储在外部 JSON 文件中的其他选项结合使用。
1. 创建一个名称类似于 `my-patch-repository.json` 的 JSON 文件并将以下内容添加到其中。
```
{
"Description": "My patch repository for Amazon Linux 2",
"Name": "Amazon-Linux-2",
"OperatingSystem": "AMAZON_LINUX_2",
"ApprovalRules": {
"PatchRules": [
{
"ApproveAfterDays": 7,
"EnableNonSecurity": true,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "SEVERITY",
"Values": [
"Important",
"Critical"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"Security",
"Bugfix"
]
},
{
"Key": "PRODUCT",
"Values": [
"AmazonLinux2"
]
}
]
}
}
]
},
"Sources": [
{
"Name": "My-AL2",
"Products": [
"AmazonLinux2"
],
"Configuration": "[amzn-main] \nname=amzn-main-Base\nmirrorlist=http://repo./$awsregion./$awsdomain//$releasever/main/mirror.list //nmirrorlist_expire=300//nmetadata_expire=300 \npriority=10 \nfailovermethod=priority \nfastestmirror_enabled=0 \ngpgcheck=1 \ngpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-amazon-ga \nenabled=1 \nretries=3 \ntimeout=5\nreport_instanceid=yes"
}
]
}
```
1. 在保存文件的目录中，键入以下命令。
```
aws ssm create-patch-baseline --cli-input-json file://my-patch-repository.json
```
系统将返回类似于以下内容的信息。
```
{
"BaselineId": "pb-0c10e65780EXAMPLE"
}
```
### 更新补丁基准
以下命令将两个带已拒绝状态的补丁和一个带已批准状态的补丁添加到现有补丁基准。
有关已批准的补丁和已拒绝的补丁列表的已接受格式的信息，请参阅 [已批准补丁和已拒绝补丁列表的程序包名称格式](patch-manager-approved-rejected-package-name-formats.md)。
------
#### [ Linux & macOS ]
```
aws ssm update-patch-baseline \
--baseline-id pb-0c10e65780EXAMPLE \
--rejected-patches "KB2032276" "MS10-048" \
--approved-patches "KB2124261"
```
------
#### [ Windows Server ]
```
aws ssm update-patch-baseline ^
--baseline-id pb-0c10e65780EXAMPLE ^
--rejected-patches "KB2032276" "MS10-048" ^
--approved-patches "KB2124261"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012R2",
"RejectedPatches":[
"KB2032276",
"MS10-048"
],
"GlobalFilters":{
"PatchFilters":[
]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"
],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"
],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1481001494.035,
"CreatedDate":1480997823.81,
"ApprovedPatches":[
"KB2124261"
],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}
```
### 重命名补丁基准
------
#### [ Linux & macOS ]
```
aws ssm update-patch-baseline \
--baseline-id pb-0c10e65780EXAMPLE \
--name "Windows-Server-2012-R2-Important-and-Critical-Security-Updates"
```
------
#### [ Windows Server ]
```
aws ssm update-patch-baseline ^
--baseline-id pb-0c10e65780EXAMPLE ^
--name "Windows-Server-2012-R2-Important-and-Critical-Security-Updates"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012-R2-Important-and-Critical-Security-Updates",
"RejectedPatches":[
"KB2032276",
"MS10-048"
],
"GlobalFilters":{
"PatchFilters":[
]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"
],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"
],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1481001795.287,
"CreatedDate":1480997823.81,
"ApprovedPatches":[
"KB2124261"
],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}
```
### 删除补丁基准
```
aws ssm delete-patch-baseline --baseline-id "pb-0c10e65780EXAMPLE"
```
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
### 列出所有补丁基准
```
aws ssm describe-patch-baselines
```
系统将返回类似于以下内容的信息。
```
{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
},
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}
```
以下是另一个命令，该命令将列出 AWS 区域 中的所有补丁基准。
------
#### [ Linux & macOS ]
```
aws ssm describe-patch-baselines \
--region us-east-2 \
--filters "Key=OWNER,Values=[All]"
```
------
#### [ Windows Server ]
```
aws ssm describe-patch-baselines ^
--region us-east-2 ^
--filters "Key=OWNER,Values=[All]"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
},
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}
```
### 列出所有 AWS 提供的补丁基准
------
#### [ Linux & macOS ]
```
aws ssm describe-patch-baselines \
--region us-east-2 \
--filters "Key=OWNER,Values=[AWS]"
```
------
#### [ Windows Server ]
```
aws ssm describe-patch-baselines ^
--region us-east-2 ^
--filters "Key=OWNER,Values=[AWS]"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineIdentities":[
{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":true,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}
]
}
```
### 列出我的补丁基准
------
#### [ Linux & macOS ]
```
aws ssm describe-patch-baselines \
--region us-east-2 \
--filters "Key=OWNER,Values=[Self]"
```
------
#### [ Windows Server ]
```
aws ssm describe-patch-baselines ^
--region us-east-2 ^
--filters "Key=OWNER,Values=[Self]"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineIdentities":[
{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":false,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical security updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
]
}
```
### 显示补丁基准
```
aws ssm get-patch-baseline --baseline-id pb-0c10e65780EXAMPLE
```
**注意**
对于自定义补丁基准，您可以指定补丁基准 ID 或完整的 Amazon Resource Name (ARN)。对于 AWS 提供的补丁基准，必须指定完整 ARN。例如 `arn:aws:ssm:us-east-2:075727635805:patchbaseline/pb-0c10e65780EXAMPLE`。
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE",
"Name":"Windows-Server-2012R2",
"PatchGroups":[
"Web Servers"
],
"RejectedPatches":[
],
"GlobalFilters":{
"PatchFilters":[
]
},
"ApprovalRules":{
"PatchRules":[
{
"PatchFilterGroup":{
"PatchFilters":[
{
"Values":[
"Important",
"Critical"
],
"Key":"MSRC_SEVERITY"
},
{
"Values":[
"SecurityUpdates"
],
"Key":"CLASSIFICATION"
},
{
"Values":[
"WindowsServer2012R2"
],
"Key":"PRODUCT"
}
]
},
"ApproveAfterDays":5
}
]
},
"ModifiedDate":1480997823.81,
"CreatedDate":1480997823.81,
"ApprovedPatches":[
],
"Description":"Windows Server 2012 R2, Important and Critical security updates"
}
```
### 获取默认补丁基准
```
aws ssm get-default-patch-baseline --region us-east-2
```
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}
```
### 将自定义补丁基准设置为默认基准
------
#### [ Linux & macOS ]
```
aws ssm register-default-patch-baseline \
--region us-east-2 \
--baseline-id "pb-0c10e65780EXAMPLE"
```
------
#### [ Windows Server ]
```
aws ssm register-default-patch-baseline ^
--region us-east-2 ^
--baseline-id "pb-0c10e65780EXAMPLE"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
### 将 AWS 补丁基准重置为默认基准
------
#### [ Linux & macOS ]
```
aws ssm register-default-patch-baseline \
--region us-east-2 \
--baseline-id "arn:aws:ssm:us-east-2:123456789012:patchbaseline/pb-0c10e65780EXAMPLE"
```
------
#### [ Windows Server ]
```
aws ssm register-default-patch-baseline ^
--region us-east-2 ^
--baseline-id "arn:aws:ssm:us-east-2:123456789012:patchbaseline/pb-0c10e65780EXAMPLE"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
### 标记补丁基准
------
#### [ Linux & macOS ]
```
aws ssm add-tags-to-resource \
--resource-type "PatchBaseline" \
--resource-id "pb-0c10e65780EXAMPLE" \
--tags "Key=Project,Value=Testing"
```
------
#### [ Windows Server ]
```
aws ssm add-tags-to-resource ^
--resource-type "PatchBaseline" ^
--resource-id "pb-0c10e65780EXAMPLE" ^
--tags "Key=Project,Value=Testing"
```
------
### 列出补丁基准的标签
------
#### [ Linux & macOS ]
```
aws ssm list-tags-for-resource \
--resource-type "PatchBaseline" \
--resource-id "pb-0c10e65780EXAMPLE"
```
------
#### [ Windows Server ]
```
aws ssm list-tags-for-resource ^
--resource-type "PatchBaseline" ^
--resource-id "pb-0c10e65780EXAMPLE"
```
------
### 从补丁基准删除标签
------
#### [ Linux & macOS ]
```
aws ssm remove-tags-from-resource \
--resource-type "PatchBaseline" \
--resource-id "pb-0c10e65780EXAMPLE" \
--tag-keys "Project"
```
------
#### [ Windows Server ]
```
aws ssm remove-tags-from-resource ^
--resource-type "PatchBaseline" ^
--resource-id "pb-0c10e65780EXAMPLE" ^
--tag-keys "Project"
```
------
## 用于补丁组的 AWS CLI 命令
**Topics**
+ [创建补丁组](#patch-manager-cli-commands-create-patch-group)
+ [将补丁组“Web 服务器”注册到补丁基准](#patch-manager-cli-commands-register-patch-baseline-for-patch-group-web-servers)
+ [将补丁组“后端”注册到 AWS 提供的补丁基准](#patch-manager-cli-commands-register-patch-baseline-for-patch-group-backend)
+ [显示补丁组注册](#patch-manager-cli-commands-describe-patch-groups)
+ [从补丁基准取消注册补丁组](#patch-manager-cli-commands-deregister-patch-baseline-for-patch-group)
### 创建补丁组
**注意**
补丁组不会用于基于*补丁策略*的修补操作。有关使用补丁策略的更多信息，请参阅 [Quick Setup 中的补丁策略配置](patch-manager-policies.md)。
为帮助您组织修补工作，我们建议您使用标签将托管式节点添加到补丁组。补丁组需要使用标签键 `Patch Group` 或 `PatchGroup`。如果[在 EC2 实例元数据中允许使用标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS)，则必须使用 `PatchGroup`（不带空格）。您可以指定任何标签值，但标签键必须为 `Patch Group` 或 `PatchGroup`。有关补丁组的更多信息，请参阅 [补丁组](patch-manager-patch-groups.md)。
使用标签对托管式节点进行分组后，请将补丁组值添加到补丁基准。通过将补丁组注册到补丁基准，您可以确保在修补操作期间安装正确的补丁。
#### 任务 1：请使用标签将 EC2 实例添加到补丁组
**注意**
使用 Amazon Elastic Compute Cloud (Amazon EC2) 控制台和 AWS CLI，则可以应用 `Key = Patch Group` 或 `Key = PatchGroup` 标签到尚未配置为与 Systems Manager 一起使用的实例。如果在应用 `Patch Group` 或 `Key = PatchGroup` 标签之后，未列出您希望在 Patch Manager 中看到的 EC2 实例，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
运行以下命令将 `PatchGroup` 标签添加到 EC2 实例。
```
aws ec2 create-tags --resources "i-1234567890abcdef0" --tags "Key=PatchGroup,Value=GroupValue"
```
#### 任务 2：使用标签将托管式节点添加到补丁组
运行以下命令以将 `PatchGroup` 标签添加到托管式节点。
------
#### [ Linux & macOS ]
```
aws ssm add-tags-to-resource \
--resource-type "ManagedInstance" \
--resource-id "mi-0123456789abcdefg" \
--tags "Key=PatchGroup,Value=GroupValue"
```
------
#### [ Windows Server ]
```
aws ssm add-tags-to-resource ^
--resource-type "ManagedInstance" ^
--resource-id "mi-0123456789abcdefg" ^
--tags "Key=PatchGroup,Value=GroupValue"
```
------
#### 任务 3：将补丁组添加到补丁基准
运行以下命令将 `PatchGroup` 标签值关联到指定的补丁基准。
------
#### [ Linux & macOS ]
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id "pb-0c10e65780EXAMPLE" \
--patch-group "Development"
```
------
#### [ Windows Server ]
```
aws ssm register-patch-baseline-for-patch-group ^
--baseline-id "pb-0c10e65780EXAMPLE" ^
--patch-group "Development"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup": "Development",
"BaselineId": "pb-0c10e65780EXAMPLE"
}
```
### 将补丁组“Web 服务器”注册到补丁基准
------
#### [ Linux & macOS ]
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id "pb-0c10e65780EXAMPLE" \
--patch-group "Web Servers"
```
------
#### [ Windows Server ]
```
aws ssm register-patch-baseline-for-patch-group ^
--baseline-id "pb-0c10e65780EXAMPLE" ^
--patch-group "Web Servers"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup":"Web Servers",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
### 将补丁组“后端”注册到 AWS 提供的补丁基准
------
#### [ Linux & macOS ]
```
aws ssm register-patch-baseline-for-patch-group \
--region us-east-2 \
--baseline-id "arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE" \
--patch-group "Backend"
```
------
#### [ Windows Server ]
```
aws ssm register-patch-baseline-for-patch-group ^
--region us-east-2 ^
--baseline-id "arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE" ^
--patch-group "Backend"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup":"Backend",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}
```
### 显示补丁组注册
```
aws ssm describe-patch-groups --region us-east-2
```
系统将返回类似于以下内容的信息。
```
{
"PatchGroupPatchBaselineMappings":[
{
"PatchGroup":"Backend",
"BaselineIdentity":{
"BaselineName":"AWS-DefaultPatchBaseline",
"DefaultBaseline":false,
"BaselineDescription":"Default Patch Baseline Provided by AWS.",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}
},
{
"PatchGroup":"Web Servers",
"BaselineIdentity":{
"BaselineName":"Windows-Server-2012R2",
"DefaultBaseline":true,
"BaselineDescription":"Windows Server 2012 R2, Important and Critical updates",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
}
]
}
```
### 从补丁基准取消注册补丁组
------
#### [ Linux & macOS ]
```
aws ssm deregister-patch-baseline-for-patch-group \
--region us-east-2 \
--patch-group "Production" \
--baseline-id "arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
```
------
#### [ Windows Server ]
```
aws ssm deregister-patch-baseline-for-patch-group ^
--region us-east-2 ^
--patch-group "Production" ^
--baseline-id "arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup":"Production",
"BaselineId":"arn:aws:ssm:us-east-2:111122223333:patchbaseline/pb-0c10e65780EXAMPLE"
}
```
## AWS CLI 命令用于查看补丁摘要和详细信息
**Topics**
+ [获取补丁基准定义的所有补丁](#patch-manager-cli-commands-describe-effective-patches-for-patch-baseline)
+ [获取 Amazonux2018.03 的所有分类为 `SECURITY` 、严重性为 `Critical` 的补丁](#patch-manager-cli-commands-describe-available-patches-linux)
+ [获取 Windows Server 2012 的所有补丁，其 MSRC 严重性为 `Critical`](#patch-manager-cli-commands-describe-available-patches)
+ [获取所有可用补丁](#patch-manager-cli-commands-describe-available-patches)
+ [获取每个托管式节点的补丁摘要状态](#patch-manager-cli-commands-describe-instance-patch-states)
+ [获取托管式节点的补丁合规性详细信息](#patch-manager-cli-commands-describe-instance-patches)
+ [查看修补合规性结果 (AWS CLI）](#viewing-patch-compliance-results-cli)
### 获取补丁基准定义的所有补丁
**注意**
此命令仅受 Windows Server 补丁基准的支持。
------
#### [ Linux & macOS ]
```
aws ssm describe-effective-patches-for-patch-baseline \
--region us-east-2 \
--baseline-id "pb-0c10e65780EXAMPLE"
```
------
#### [ Windows Server ]
```
aws ssm describe-effective-patches-for-patch-baseline ^
--region us-east-2 ^
--baseline-id "pb-0c10e65780EXAMPLE"
```
------
系统将返回类似于以下内容的信息。
```
{
"NextToken":"--token string truncated--",
"EffectivePatches":[
{
"PatchStatus":{
"ApprovalDate":1384711200.0,
"DeploymentStatus":"APPROVED"
},
"Patch":{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2876331",
"ProductFamily":"Windows",
"Product":"WindowsServer2012R2",
"Vendor":"Microsoft",
"Description":"A security issue has been identified in a Microsoft software
product that could affect your system. You can help protect your system
by installing this update from Microsoft. For a complete listing of the
issues that are included in this update, see the associated Microsoft
Knowledge Base article. After you install this update, you may have to
restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows Server 2012 R2 Preview (KB2876331)",
"ReleaseDate":1384279200.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2876331",
"MsrcNumber":"MS13-089",
"Id":"e74ccc76-85f0-4881-a738-59e9fc9a336d"
}
},
{
"PatchStatus":{
"ApprovalDate":1428858000.0,
"DeploymentStatus":"APPROVED"
},
"Patch":{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2919355",
"ProductFamily":"Windows",
"Product":"WindowsServer2012R2",
"Vendor":"Microsoft",
"Description":"Windows Server 2012 R2 Update is a cumulative
set of security updates, critical updates and updates. You
must install Windows Server 2012 R2 Update to ensure that
your computer can continue to receive future Windows Updates,
including security updates. For a complete listing of the
issues that are included in this update, see the associated
Microsoft Knowledge Base article for more information. After
you install this item, you may have to restart your computer.",
"Classification":"SecurityUpdates",
"Title":"Windows Server 2012 R2 Update (KB2919355)",
"ReleaseDate":1428426000.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2919355",
"MsrcNumber":"MS14-018",
"Id":"8452bac0-bf53-4fbd-915d-499de08c338b"
}
}
---output truncated---
```
### 获取 Amazonux2018.03 的所有分类为 `SECURITY` 、严重性为 `Critical` 的补丁
------
#### [ Linux & macOS ]
```
aws ssm describe-available-patches \
--region us-east-2 \
--filters Key=PRODUCT,Values=AmazonLinux2018.03 Key=SEVERITY,Values=Critical
```
------
#### [ Windows Server ]
```
aws ssm describe-available-patches ^
--region us-east-2 ^
--filters Key=PRODUCT,Values=AmazonLinux2018.03 Key=SEVERITY,Values=Critical
```
------
系统将返回类似于以下内容的信息。
```
{
"Patches": [
{
"AdvisoryIds": ["ALAS-2011-1"],
"BugzillaIds": [ "1234567" ],
"Classification": "SECURITY",
"CVEIds": [ "CVE-2011-3192"],
"Name": "zziplib",
"Epoch": "0",
"Version": "2.71",
"Release": "1.3.amzn1",
"Arch": "i686",
"Product": "AmazonLinux2018.03",
"ReleaseDate": 1590519815,
"Severity": "CRITICAL"
}
]
}
---output truncated---
```
### 获取 Windows Server 2012 的所有补丁，其 MSRC 严重性为 `Critical`
------
#### [ Linux & macOS ]
```
aws ssm describe-available-patches \
--region us-east-2 \
--filters Key=PRODUCT,Values=WindowsServer2012 Key=MSRC_SEVERITY,Values=Critical
```
------
#### [ Windows Server ]
```
aws ssm describe-available-patches ^
--region us-east-2 ^
--filters Key=PRODUCT,Values=WindowsServer2012 Key=MSRC_SEVERITY,Values=Critical
```
------
系统将返回类似于以下内容的信息。
```
{
"Patches":[
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2727528",
"ProductFamily":"Windows",
"Product":"WindowsServer2012",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could
allow an unauthenticated remote attacker to compromise your
system and gain control over it. You can help protect your
system by installing this update from Microsoft. After you
install this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Windows Server 2012 (KB2727528)",
"ReleaseDate":1352829600.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2727528",
"MsrcNumber":"MS12-072",
"Id":"1eb507be-2040-4eeb-803d-abc55700b715"
},
{
"ContentUrl":"https://support.microsoft.com/en-us/kb/2729462",
"ProductFamily":"Windows",
"Product":"WindowsServer2012",
"Vendor":"Microsoft",
"Description":"A security issue has been identified that could
allow an unauthenticated remote attacker to compromise your
system and gain control over it. You can help protect your
system by installing this update from Microsoft. After you
install this update, you may have to restart your system.",
"Classification":"SecurityUpdates",
"Title":"Security Update for Microsoft .NET Framework 3.5 on
Windows 8 and Windows Server 2012 for x64-based Systems (KB2729462)",
"ReleaseDate":1352829600.0,
"MsrcClassification":"Critical",
"Language":"All",
"KbNumber":"KB2729462",
"MsrcNumber":"MS12-074",
"Id":"af873760-c97c-4088-ab7e-5219e120eab4"
}
---output truncated---
```
### 获取所有可用补丁
```
aws ssm describe-available-patches --region us-east-2
```
系统将返回类似于以下内容的信息。
```
{
"NextToken":"--token string truncated--",
"Patches":[
{
"Classification": "SecurityUpdates",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4074588",
"Description": "A security issue has been identified in a Microsoft software
product that could affect your system. You can help protect your system by
installing this update from Microsoft. For a complete listing of the issues
that are included in this update, see the associated Microsoft Knowledge Base
article. After you install this update, you may have to restart your system.",
"Id": "11adea10-0701-430e-954f-9471595ae246",
"KbNumber": "KB4074588",
"Language": "All",
"MsrcNumber": "",
"MsrcSeverity": "Critical",
"Product": "WindowsServer2016",
"ProductFamily": "Windows",
"ReleaseDate": 1518548400,
"Title": "2018-02 Cumulative Update for Windows Server 2016 (1709) for x64-based
Systems (KB4074588)",
"Vendor": "Microsoft"
},
{
"Classification": "SecurityUpdates",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4074590",
"Description": "A security issue has been identified in a Microsoft software
product that could affect your system. You can help protect your system by
installing this update from Microsoft. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article. After you install this update, you may have to restart your system.",
"Id": "f5f58231-ac5d-4640-ab1b-9dc8d857c265",
"KbNumber": "KB4074590",
"Language": "All",
"MsrcNumber": "",
"MsrcSeverity": "Critical",
"Product": "WindowsServer2016",
"ProductFamily": "Windows",
"ReleaseDate": 1518544805,
"Title": "2018-02 Cumulative Update for Windows Server 2016 for x64-based
Systems (KB4074590)",
"Vendor": "Microsoft"
}
---output truncated---
```
### 获取每个托管式节点的补丁摘要状态
每个托管式节点的摘要可为您提供每个节点中具有以下状态的补丁数量：“NotApplicable”（不适用）、“Missing”（缺少）、“Failed”（失败）、“InstalledOther”（已安装其他）和“Installed”（已安装）。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-patch-states \
--instance-ids i-08ee91c0b17045407 i-09a618aec652973a9
```
------
#### [ Windows Server ]
```
aws ssm describe-instance-patch-states ^
--instance-ids i-08ee91c0b17045407 i-09a618aec652973a9
```
------
系统将返回类似于以下内容的信息。
```
{
"InstancePatchStates":[
{
"InstanceId": "i-08ee91c0b17045407",
"PatchGroup": "",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "6d03d6c5-f79d-41d0-8d0e-00a9aEXAMPLE",
"InstalledCount": 50,
"InstalledOtherCount": 353,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 0,
"FailedCount": 0,
"UnreportedNotApplicableCount": -1,
"NotApplicableCount": 671,
"OperationStartTime": "2020-01-24T12:37:56-08:00",
"OperationEndTime": "2020-01-24T12:37:59-08:00",
"Operation": "Scan",
"RebootOption": "NoReboot"
},
{
"InstanceId": "i-09a618aec652973a9",
"PatchGroup": "",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "c7e0441b-1eae-411b-8aa7-973e6EXAMPLE",
"InstalledCount": 36,
"InstalledOtherCount": 396,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 3,
"FailedCount": 0,
"UnreportedNotApplicableCount": -1,
"NotApplicableCount": 420,
"OperationStartTime": "2020-01-24T12:37:34-08:00",
"OperationEndTime": "2020-01-24T12:37:37-08:00",
"Operation": "Scan",
"RebootOption": "NoReboot"
}
---output truncated---
```
### 获取托管式节点的补丁合规性详细信息
```
aws ssm describe-instance-patches --instance-id i-08ee91c0b17045407
```
系统将返回类似于以下内容的信息。
```
{
"NextToken":"--token string truncated--",
"Patches":[
{
"Title": "bind-libs.x86_64:32:9.8.2-0.68.rc1.60.amzn1",
"KBId": "bind-libs.x86_64",
"Classification": "Security",
"Severity": "Important",
"State": "Installed",
"InstalledTime": "2019-08-26T11:05:24-07:00"
},
{
"Title": "bind-utils.x86_64:32:9.8.2-0.68.rc1.60.amzn1",
"KBId": "bind-utils.x86_64",
"Classification": "Security",
"Severity": "Important",
"State": "Installed",
"InstalledTime": "2019-08-26T11:05:32-07:00"
},
{
"Title": "dhclient.x86_64:12:4.1.1-53.P1.28.amzn1",
"KBId": "dhclient.x86_64",
"Classification": "Security",
"Severity": "Important",
"State": "Installed",
"InstalledTime": "2019-08-26T11:05:31-07:00"
},
---output truncated---
```
### 查看修补合规性结果 (AWS CLI）
**查看单个托管式节点的补丁合规性结果**
在 AWS Command Line Interface (AWS CLI) 中运行以下命令，查看单个托管式节点的补丁合规性结果。
```
aws ssm describe-instance-patch-states --instance-id instance-id
```
以 `i-02573cafcfEXAMPLE` 或 `mi-0282f7c436EXAMPLE` 格式，将 *instance-id* 替换为要查看其结果的托管式节点的 ID。
系统将返回类似于以下内容的信息。
```
{
"InstancePatchStates": [
{
"InstanceId": "i-02573cafcfEXAMPLE",
"PatchGroup": "mypatchgroup",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "a3f5ff34-9bc4-4d2c-a665-4d1c1EXAMPLE",
"CriticalNonCompliantCount": 2,
"SecurityNonCompliantCount": 2,
"OtherNonCompliantCount": 1,
"InstalledCount": 123,
"InstalledOtherCount": 334,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 1,
"FailedCount": 2,
"UnreportedNotApplicableCount": 11,
"NotApplicableCount": 2063,
"OperationStartTime": "2021-05-03T11:00:56-07:00",
"OperationEndTime": "2021-05-03T11:01:09-07:00",
"Operation": "Scan",
"LastNoRebootInstallOperationTime": "2020-06-14T12:17:41-07:00",
"RebootOption": "RebootIfNeeded"
}
]
}
```
**查看某个区域中所有 EC2 实例的补丁计数摘要**
`describe-instance-patch-states` 支持一次只检索一个托管实例的结果。但是，使用自定义脚本与 `describe-instance-patch-states` 命令，您可以生成更精细的报告。
例如，如果在本地计算机上安装 [jq 筛选工具](https://stedolan.github.io/jq/download/)，您可以运行以下命令来识别哪些 EC2 实例在特定 AWS 区域 中的状态为 `InstalledPendingReboot`。
```
aws ssm describe-instance-patch-states \
--instance-ids $(aws ec2 describe-instances --region region | jq '.Reservations[].Instances[] | .InstanceId' | tr '\n|"' ' ') \
--output text --query 'InstancePatchStates[*].{Instance:InstanceId, InstalledPendingRebootCount:InstalledPendingRebootCount}'
```
*region* 表示 AWS Systems Manager 支持的 AWS 区域 的标识符，例如 `us-east-2` 对应美国东部（俄亥俄州）区域。有关支持的 *region* 值的列表，请参阅《Amazon Web Services 一般参考》**中的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 的 **Region** 列。
例如：
```
aws ssm describe-instance-patch-states \
--instance-ids $(aws ec2 describe-instances --region us-east-2 | jq '.Reservations[].Instances[] | .InstanceId' | tr '\n|"' ' ') \
--output text --query 'InstancePatchStates[*].{Instance:InstanceId, InstalledPendingRebootCount:InstalledPendingRebootCount}'
```
系统将返回类似于以下内容的信息。
```
1 i-02573cafcfEXAMPLE
0 i-0471e04240EXAMPLE
3 i-07782c72faEXAMPLE
6 i-083b678d37EXAMPLE
0 i-03a530a2d4EXAMPLE
1 i-01f68df0d0EXAMPLE
0 i-0a39c0f214EXAMPLE
7 i-0903a5101eEXAMPLE
7 i-03823c2fedEXAMPLE
```
除了 `InstalledPendingRebootCount`，您可以搜索的计数类型列表包括以下内容：
+ `CriticalNonCompliantCount`
+ `SecurityNonCompliantCount`
+ `OtherNonCompliantCount`
+ `UnreportedNotApplicableCount `
+ `InstalledPendingRebootCount`
+ `FailedCount`
+ `NotApplicableCount`
+ `InstalledRejectedCount`
+ `InstalledOtherCount`
+ `MissingCount`
+ `InstalledCount`
## 用于扫描和修补托管式节点的 AWS CLI 命令
运行以下命令来扫描补丁合规性或安装补丁后，可以使用 [AWS CLI 命令用于查看补丁摘要和详细信息](#patch-details-cli-commands) 部分里的命令来查看有关补丁状态和合规性的信息。
**Topics**
+ [扫描托管式节点以检查是否符合补丁合规性要求 (AWS CLI)](#patch-operations-scan)
+ [在托管式节点上安装补丁 (AWS CLI)](#patch-operations-install-cli)
### 扫描托管式节点以检查是否符合补丁合规性要求 (AWS CLI)
**扫描指定托管式节点以检查是否符合补丁合规性要求**
运行如下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name 'AWS-RunPatchBaseline' \
--targets Key=InstanceIds,Values='i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE' \
--parameters 'Operation=Scan' \
--timeout-seconds 600
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets Key=InstanceIds,Values="i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" ^
--parameters "Operation=Scan" ^
--timeout-seconds 600
```
------
系统将返回类似于以下内容的信息。
```
{
"Command": {
"CommandId": "a04ed06c-8545-40f4-87c2-a0babEXAMPLE",
"DocumentName": "AWS-RunPatchBaseline",
"DocumentVersion": "$DEFAULT",
"Comment": "",
"ExpiresAfter": 1621974475.267,
"Parameters": {
"Operation": [
"Scan"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE,
i-0471e04240EXAMPLE"
]
}
],
"RequestedDateTime": 1621952275.267,
"Status": "Pending",
"StatusDetails": "Pending",
"TimeoutSeconds": 600,
---output truncated---
}
}
```
**按补丁组标签扫描托管式节点以检查是否符合补丁合规性要求**
运行如下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name 'AWS-RunPatchBaseline' \
--targets Key='tag:PatchGroup',Values='Web servers' \
--parameters 'Operation=Scan' \
--timeout-seconds 600
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets Key="tag:PatchGroup",Values="Web servers" ^
--parameters "Operation=Scan" ^
--timeout-seconds 600
```
------
系统将返回类似于以下内容的信息。
```
{
"Command": {
"CommandId": "87a448ee-8adc-44e0-b4d1-6b429EXAMPLE",
"DocumentName": "AWS-RunPatchBaseline",
"DocumentVersion": "$DEFAULT",
"Comment": "",
"ExpiresAfter": 1621974983.128,
"Parameters": {
"Operation": [
"Scan"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "tag:PatchGroup",
"Values": [
"Web servers"
]
}
],
"RequestedDateTime": 1621952783.128,
"Status": "Pending",
"StatusDetails": "Pending",
"TimeoutSeconds": 600,
---output truncated---
}
}
```
### 在托管式节点上安装补丁 (AWS CLI)
**在指定托管式节点上安装补丁**
运行如下命令。
**注意**
目标托管式节点按需重启以完成补丁安装。有关更多信息，请参阅 [用于修补的 SSM 命令文档：`AWS-RunPatchBaseline`](patch-manager-aws-runpatchbaseline.md)。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name 'AWS-RunPatchBaseline' \
--targets Key=InstanceIds,Values='i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE' \
--parameters 'Operation=Install' \
--timeout-seconds 600
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets Key=InstanceIds,Values="i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" ^
--parameters "Operation=Install" ^
--timeout-seconds 600
```
------
系统将返回类似于以下内容的信息。
```
{
"Command": {
"CommandId": "5f403234-38c4-439f-a570-93623EXAMPLE",
"DocumentName": "AWS-RunPatchBaseline",
"DocumentVersion": "$DEFAULT",
"Comment": "",
"ExpiresAfter": 1621975301.791,
"Parameters": {
"Operation": [
"Install"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE,
i-0471e04240EXAMPLE"
]
}
],
"RequestedDateTime": 1621953101.791,
"Status": "Pending",
"StatusDetails": "Pending",
"TimeoutSeconds": 600,
---output truncated---
}
}
```
**在指定补丁组中的托管式节点上安装补丁**
运行如下命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name 'AWS-RunPatchBaseline' \
--targets Key='tag:PatchGroup',Values='Web servers' \
-parameters 'Operation=Install' \
--timeout-seconds 600
```
------
#### [ Windows Server ]
```
aws ssm send-command ^
--document-name "AWS-RunPatchBaseline" ^
--targets Key="tag:PatchGroup",Values="Web servers" ^
--parameters "Operation=Install" ^
--timeout-seconds 600
```
------
系统将返回类似于以下内容的信息。
```
{
"Command": {
"CommandId": "fa44b086-7d36-4ad5-ac8d-627ecEXAMPLE",
"DocumentName": "AWS-RunPatchBaseline",
"DocumentVersion": "$DEFAULT",
"Comment": "",
"ExpiresAfter": 1621975407.865,
"Parameters": {
"Operation": [
"Install"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "tag:PatchGroup",
"Values": [
"Web servers"
]
}
],
"RequestedDateTime": 1621953207.865,
"Status": "Pending",
"StatusDetails": "Pending",
"TimeoutSeconds": 600,
---output truncated---
}
}
```
# AWS Systems Manager Patch Manager 教程
本节中的教程演示如何针对各种修补场景使用Patch Manager（AWS Systems Manager 中的一项工具）。
**Topics**
+ [教程：在仅支持 IPv6 的环境中修补服务器](patch-manager-server-patching-iPv6-tutorial.md)
+ [教程：使用控制台创建用于安装 Windows Service Pack 的补丁基准](patch-manager-windows-service-pack-patch-baseline-tutorial.md)
+ [教程：使用控制台更新应用程序依赖项、修补托管式节点并执行特定于应用程序的运行状况检查](aws-runpatchbaselinewithhooks-tutorial.md)
+ [教程：使用 AWS CLI 修补服务器环境](patch-manager-patch-servers-using-the-aws-cli.md)
# 教程：在仅支持 IPv6 的环境中修补服务器
Patch Manager 支持对仅具有 IPv6 的环境中的节点进行修补。通过更新 SSM Agent 配置，可以将修补操作配置为仅调用 IPv6 服务端点。
**在仅支持 IPv6 的环境中修补服务器**
1. 确保托管式节点上安装了 SSM Agent 版本 3.3270.0 或更高版本。
1. 在托管节点上，导航到 SSM Agent 配置文件。您可以在以下目录中找到 `amazon-ssm-agent.json` 文件：
+ Linux：`/etc/amazon/ssm/`
+ macOS: `/opt/aws/ssm/`
+ Windows Server: `C:\Program Files\Amazon\SSM`
如果 `amazon-ssm-agent.json` 尚不存在，请将同一目录下的 `amazon-ssm-agent.json.template` 内容复制到 `amazon-ssm-agent.json`。
1. 更新以下条目以设置正确的区域并将 `UseDualStackEndpoint` 设置为 `true`：
```
{
--------
"Agent": {
"Region": "region",
"UseDualStackEndpoint": true
},
--------
}
```
1. 使用适用于您操作系统的命令重启 SSM Agent 服务：
+ Linux：`sudo systemctl restart amazon-ssm-agent`
+ 使用 Snap 的 Ubuntu Server：`sudo snap restart amazon-ssm-agent`
+ macOS：`sudo launchctl stop com.amazon.aws.ssm`，之后是 `sudo launchctl start com.amazon.aws.ssm`
+ Windows Server：`Stop-Service AmazonSSMAgent`，之后是 `Start-Service AmazonSSMAgent`
有关每个操作系统的完整命令列表，请参阅 [正在检查 SSM Agent 状态并启动代理](ssm-agent-status-and-restart.md)。
1. 执行任何修补操作，以验证修补操作在仅支持 IPv6 的环境中是否成功。确保被修补的节点与补丁源有连接。您可以检查修补执行的 Run Command 输出，以检查有关无法访问的存储库的警告。在仅支持 IPv6 的环境中运行的节点上进行修补时，请确保该节点与补丁源有连接。您可以检查修补执行的 Run Command 输出，以检查有关无法访问的存储库的警告。对于基于 DNF 的操作系统，如果 `/etc/dnf/dnf.conf` 下的 `skip_if_unavailable` 选项设置为 `True`，则可以配置在修补期间跳过不可用的存储库。基于 DNF 的操作系统包括 Amazon Linux 2023、Red Hat Enterprise Linux 8 及更高版本、Oracle Linux 8 及更高版本、Rocky Linux、AlmaLinux 以及 CentOS 8 及更高版本。在 Amazon Linux 2023 上，`skip_if_unavailable` 选项默认设置为 `True`。
**注意**
使用“安装覆盖列表”或“基准覆盖”功能时，请确保提供的 URL 可从节点访问。如果将 SSM Agent 配置选项 `UseDualStackEndpoint` 设置为 `true`，则在提供 S3 URL 时将使用双堆栈 S3 客户端。
# 教程：使用控制台创建用于安装 Windows Service Pack 的补丁基准
创建自定义补丁基准时，可以指定安装所有、部分或仅安装一种支持的补丁。
在适用于 Windows 的补丁基准中，您可以选择 `ServicePacks` 作为唯一的 **Classification (分类)** 选项，以便将补丁更新仅限于 Service Pack。Patch Manager（AWS Systems Manager 中的一项工具）可以自动安装服务包，前提是此更新在 Windows Update 或 Windows Server Update Services（WSUS）中可用。
您可以配置补丁基准，以控制是安装所有 Windows 版本的 Service Pack，还是仅安装特定版本（如 Windows 7 或 Windows Server 2016）的 Service Pack。
使用以下过程创建自定义补丁基准，专门用于在 Windows 托管式节点上安装所有 Service Pack。
**创建用于安装 Windows Service Pack（控制台）的补丁基准**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡，然后选择**创建补丁基准**。
1. 在 **Name (名称)** 中，输入新补丁基准的名称，例如，`MyWindowsServicePackPatchBaseline`。
1. （可选）对于 **Description (描述)**，输入此补丁基准的描述。
1. 对于 **Operating system**（操作系统），请选择 `Windows`。
1. 如果要在创建后即开始将此补丁基准用作 Windows 的默认项，请选择 **Set this patch baseline as the default patch baseline for Windows Server instances**（将此补丁基准设置为 Windows Server 实例的默认补丁基准）。
**注意**
只有在 2022 年 12 月 22 日 [补丁策略](patch-manager-policies.md) 发布之前首次访问 Patch Manager时，此选项才可用。
有关将现有补丁基准设置为默认项的信息，请参阅 [将现有补丁基准设置为默认项](patch-manager-default-patch-baseline.md)。
1. 在 **Approval rules for operating systems (操作系统的批准规则)** 部分，使用字段创建一个或多个自动批准规则。
+ **产品**：批准规则适用的操作系统版本，例如 `WindowsServer2012`。您可以选择一个、多个或所有受支持的 Windows 版本。默认选择为 `All`。
+ **Classification (分类)**：选择 `ServicePacks`。
+ **Severity (严重性)**：规则适用于的补丁的严重性值。要确保规则包含所有 Service Pack，请选择 `All`。
+ **Auto-approval**（自动批准）：选择要自动批准的补丁的方法。
+ **在指定的天数后批准补丁**：Patch Manager 在发布或更新补丁之后等待的天数，然后自动批准补丁。可以输入零 (0) 到 360 的任何整数。对于大多数情况，我们建议等待期不超过 100 天。
+ **批准在特定日期之前发布的补丁**：补丁发布日期，Patch Manager 自动应用在该日期或之前发布或更新的所有补丁。例如，如果指定 2023 年 7 月 7 日，则不会自动安装在 2023 年 7 月 8 日或之后发布或最后更新的任何补丁。
+ （可选）**Compliance reporting (合规性报告)**：要分配给由基准批准的 Service Pack 的严重性级别，例如 `High`。
**注意**
如果您指定合规性报告级别以及任何已批准 Service Pack 的补丁状态报告为 `Missing`，则补丁基准报告的总体合规性严重性级别就是您指定的严重级别。
1. （可选）对于**管理标签**，将一个或多个标签键名称/值对应用到补丁基准。
标签是您分配给资源的可选元数据。标签允许您按各种标准（如用途、所有者或环境）对资源进行分类。对于专用于更新 Service Pack 的此补丁基准，您可以指定键值对，如下所示：
+ `Key=OS,Value=Windows`
+ `Key=Classification,Value=ServicePacks`
1. 请选择**创建补丁基准**。
# 教程：使用控制台更新应用程序依赖项、修补托管式节点并执行特定于应用程序的运行状况检查
在许多情况下，在使用最新软件更新修补托管式节点后必须将其重启。但是，在没有安全措施的情况下重启生产中的节点可能会导致若干问题，例如调用告警、记录不正确的指标数据以及中断数据同步。
本教程将演示为了避免上述类似问题，如何通过使用 AWS Systems Manager 文档（SSM 文档）`AWS-RunPatchBaselineWithHooks` 来实现复杂的多步骤修补操作，该操作可完成以下事项：
1. 防止新连接到应用程序
1. 安装操作系统更新
1. 更新应用程序的软件包依赖项
1. 重启系统
1. 执行特定于应用程序的运行状况检查
在此示例中，我们以这种方式设置了我们的基础设施：
+ 目标虚拟机在 Systems Manager 中注册为托管式节点。
+ `Iptables` 作本地防火墙。
+ 托管式节点上托管的应用程序正在端口 443 上运行。
+ 托管式节点上托管的应用程序是 `nodeJS` 应用程序。
+ 托管式节点上托管的应用程序由 pm2 进程管理器管理。
+ 应用程序已经具有指定的运行状况检查终端节点。
+ 应用程序的运行状况检查终结点不需要终端用户身份验证。终端节点允许进行运行状况检查，以满足组织在建立可用性方面的要求。（在您的环境中，可能只需确定正在运行 `nodeJS` 应用程序，并且能够侦听请求。在其他情况下，您可能还需要验证是否已建立到缓存层或数据库层的连接。）
本教程中的示例仅用于演示目的，并不意味着按原样实施到生产环境中。另请注意，Patch Manager（Systems Manager 中的一项工具）的生命周期挂钩功能和 `AWS-RunPatchBaselineWithHooks` 文档搭配使用，可以支持许多其他场景。下面是几个示例。
+ 在修补之前停止指标报告代理，并在托管式节点重启后重启该代理。
+ 在进行修补之前，将托管式节点与 CRM 或 PCS 集群分离，并在节点重启后重新连接。
+ 在应用操作系统 (OS) 更新之后、托管式节点重启之前，在 Windows Server 计算机上更新第三方软件（例如，Java、Tomcat、Adobe 应用程序等）。
**更新应用程序依赖项、修补托管式节点并执行特定于应用程序的运行状况检查**
1. 使用以下内容为预安装脚本创建 SSM 文档，并将其命名为 `NodeJSAppPrePatch`。将*您的应用程序*替换为应用程序的名称。
此脚本会立即阻止新的传入请求，并在开始修补操作之前为已经激活的请求提供 5 秒钟的完成时间。对于 `sleep` 选项，请指定一个比传入请求完成通常所需秒数大的秒数。
```
# exit on error
set -e
# set up rule to block incoming traffic
iptables -I INPUT -j DROP -p tcp --syn --destination-port 443 || exit 1
# wait for current connections to end. Set timeout appropriate to your application's latency
sleep 5
# Stop your application
pm2 stop your_application
```
有关创建 SSM 文档的信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。
1. 为安装后脚本创建包含以下内容的另一个 SSM 文档，以更新应用程序依赖项，并将其命名为 `NodeJSAppPostPatch`。将*/您的/应用程序/路径*替换为通向您的应用程序的路径。
```
cd /your/application/path
npm update
# you can use npm-check-updates if you want to upgrade major versions
```
1. 创建另一个包含以下内容的 SSM 文档，其中的 `onExit` 脚本使应用程序备份并执行运行状况检查。命名此 SSM 文档为 `NodeJSAppOnExitPatch`。将*您的应用程序*替换为您的应用程序的名称。
```
# exit on error
set -e
# restart nodeJs application
pm2 start your_application
# sleep while your application starts and to allow for a crash
sleep 10
# check with pm2 to see if your application is running
pm2 pid your_application
# re-enable incoming connections
iptables -D INPUT -j DROP -p tcp --syn --destination-port
# perform health check
/usr/bin/curl -m 10 -vk -A "" http://localhost:443/health-check || exit 1
```
1. 在State Manager（AWS Systems Manager 中的一项工具）中创建关联，通过执行下列步骤发出操作：
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **State Manager**，然后选择**创建关联**。
1. 对于**名称**，请提供一个名称来帮助标识关联的用途。
1. 在**文档**列表中，选择 `AWS-RunPatchBaselineWithHooks`。
1. 对于**操作**，选择**安装**。
1. （可选）对于**快照 ID**，提供您生成的 GUID，以帮助加快操作速度并确保一致性。GUID 值可以像 `00000000-0000-0000-0000-111122223333` 一样简单。
1. 对于**安装前钩子文档名称**，输入 `NodeJSAppPrePatch`。
1. 对于**安装后钩子文档名称**，输入 `NodeJSAppPostPatch`。
1. 对于**针对 ExitHook 文档名称**，输入 `NodeJSAppOnExitPatch`。
1. 对于 **Targets**（目标），通过指定标签、手动选择节点、选择资源组或选择所有托管式节点来标识托管式节点。
1. 对于**指定时间表**，指定运行关联的频率。对于托管式节点修补，每周修补一次是常见的节奏。
1. 在 **Rate control**（速率控制）部分中，选择用于控制如何在多个托管式节点上运行关联的选项。确保一次只更新部分托管式节点。否则，您的所有或大部分队列都可以同时离线。有关使用速率控制的更多信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 选择**创建关联**。
# 教程：使用 AWS CLI 修补服务器环境
以下过程介绍如何使用自定义补丁基准、补丁组和维护时段来修补服务器环境。
**开始前的准备工作**
+ 在托管式节点上安装或更新 SSM Agent。要修补 Linux 托管式节点，节点必须运行 SSM Agent 2.0.834.0 版或更高版本。有关更多信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
+ 配置 Maintenance Windows（AWS Systems Manager 中的一项工具）的角色和权限。有关更多信息，请参阅 [设置 Maintenance Windows](setting-up-maintenance-windows.md)。
+ 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
**配置 Patch Manager 并修补托管式节点（命令行）**
1. 运行以下命令以创建名为 `Production-Baseline` 的适用于 Windows 的补丁基准。此补丁基准会在补丁发布或最后更新 7 天后批准用于生产环境。即，我们已标记补丁基准，以指示它适用于生产环境。
**注意**
`OperatingSystem` 参数和 `PatchFilters` 因补丁基准应用到的目标托管式节点的操作系统而异。有关详细信息，请参阅 [OperatingSystem](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreatePatchBaseline.html#systemsmanager-CreatePatchBaseline-request-OperatingSystem) 和 [PatchFilter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_PatchFilter.html)。
------
#### [ Linux & macOS ]
```
aws ssm create-patch-baseline \
--name "Production-Baseline" \
--operating-system "WINDOWS" \
--tags "Key=Environment,Value=Production" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Critical,Important]},{Key=CLASSIFICATION,Values=[SecurityUpdates,Updates,ServicePacks,UpdateRollups,CriticalUpdates]}]},ApproveAfterDays=7}]" \
--description "Baseline containing all updates approved for production systems"
```
------
#### [ Windows Server ]
```
aws ssm create-patch-baseline ^
--name "Production-Baseline" ^
--operating-system "WINDOWS" ^
--tags "Key=Environment,Value=Production" ^
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Critical,Important]},{Key=CLASSIFICATION,Values=[SecurityUpdates,Updates,ServicePacks,UpdateRollups,CriticalUpdates]}]},ApproveAfterDays=7}]" ^
--description "Baseline containing all updates approved for production systems"
```
------
系统将返回类似于以下内容的信息。
```
{
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
1. 运行以下命令为两个补丁组注册“生产-基准”补丁基准。这些组命名为“数据库服务器”和“前端服务器”。
------
#### [ Linux & macOS ]
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id pb-0c10e65780EXAMPLE \
--patch-group "Database Servers"
```
------
#### [ Windows Server ]
```
aws ssm register-patch-baseline-for-patch-group ^
--baseline-id pb-0c10e65780EXAMPLE ^
--patch-group "Database Servers"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup":"Database Servers",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
------
#### [ Linux & macOS ]
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id pb-0c10e65780EXAMPLE \
--patch-group "Front-End Servers"
```
------
#### [ Windows Server ]
```
aws ssm register-patch-baseline-for-patch-group ^
--baseline-id pb-0c10e65780EXAMPLE ^
--patch-group "Front-End Servers"
```
------
系统将返回类似于以下内容的信息。
```
{
"PatchGroup":"Front-End Servers",
"BaselineId":"pb-0c10e65780EXAMPLE"
}
```
1. 运行以下命令为生产服务器创建两个维护时段。第一个时段在每周二晚上 10 点运行。第二个时段在每周六晚上 10 点运行。此外，维护时段已标记来指示它适用于生产环境。
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "Production-Tuesdays" \
--tags "Key=Environment,Value=Production" \
--schedule "cron(0 0 22 ? * TUE *)" \
--duration 1 \
--cutoff 0 \
--no-allow-unassociated-targets
```
------
#### [ Windows Server ]
```
aws ssm create-maintenance-window ^
--name "Production-Tuesdays" ^
--tags "Key=Environment,Value=Production" ^
--schedule "cron(0 0 22 ? * TUE *)" ^
--duration 1 ^
--cutoff 0 ^
--no-allow-unassociated-targets
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowId":"mw-0c50858d01EXAMPLE"
}
```
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "Production-Saturdays" \
--tags "Key=Environment,Value=Production" \
--schedule "cron(0 0 22 ? * SAT *)" \
--duration 2 \
--cutoff 0 \
--no-allow-unassociated-targets
```
------
#### [ Windows Server ]
```
aws ssm create-maintenance-window ^
--name "Production-Saturdays" ^
--tags "Key=Environment,Value=Production" ^
--schedule "cron(0 0 22 ? * SAT *)" ^
--duration 2 ^
--cutoff 0 ^
--no-allow-unassociated-targets
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowId":"mw-9a8b7c6d5eEXAMPLE"
}
```
1. 运行以下命令，将 `Database` 和 `Front-End` 服务器补丁组注册到其各自的维护时段。
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--targets "Key=tag:PatchGroup,Values=Database Servers" \
--owner-information "Database Servers" \
--resource-type "INSTANCE"
```
------
#### [ Windows Server ]
```
aws ssm register-target-with-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--targets "Key=tag:PatchGroup,Values=Database Servers" ^
--owner-information "Database Servers" ^
--resource-type "INSTANCE"
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowTargetId":"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}
```
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id mw-9a8b7c6d5eEXAMPLE \
--targets "Key=tag:PatchGroup,Values=Front-End Servers" \
--owner-information "Front-End Servers" \
--resource-type "INSTANCE"
```
------
#### [ Windows Server ]
```
aws ssm register-target-with-maintenance-window ^
--window-id mw-9a8b7c6d5eEXAMPLE ^
--targets "Key=tag:PatchGroup,Values=Front-End Servers" ^
--owner-information "Front-End Servers" ^
--resource-type "INSTANCE"
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowTargetId":"faa01c41-1d57-496c-ba77-ff9caEXAMPLE"
}
```
1. 运行以下命令注册一个补丁任务，该任务在 `Database` 和 `Front-End` 服务器各自的维护时段内安装缺少的更新。
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--task-arn "AWS-RunPatchBaseline" \
--service-role-arn "arn:aws:iam::123456789012:role/MW-Role" \
--task-type "RUN_COMMAND" \
--max-concurrency 2 \
--max-errors 1 \
--priority 1 \
--task-invocation-parameters "RunCommand={Parameters={Operation=Install}}"
```
------
#### [ Windows Server ]
```
aws ssm register-task-with-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" ^
--task-arn "AWS-RunPatchBaseline" ^
--service-role-arn "arn:aws:iam::123456789012:role/MW-Role" ^
--task-type "RUN_COMMAND" ^
--max-concurrency 2 ^
--max-errors 1 ^
--priority 1 ^
--task-invocation-parameters "RunCommand={Parameters={Operation=Install}}"
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id mw-9a8b7c6d5eEXAMPLE \
--targets "Key=WindowTargetIds,Values=faa01c41-1d57-496c-ba77-ff9caEXAMPLE" \
--task-arn "AWS-RunPatchBaseline" \
--service-role-arn "arn:aws:iam::123456789012:role/MW-Role" \
--task-type "RUN_COMMAND" \
--max-concurrency 2 \
--max-errors 1 \
--priority 1 \
--task-invocation-parameters "RunCommand={Parameters={Operation=Install}}"
```
------
#### [ Windows Server ]
```
aws ssm register-task-with-maintenance-window ^
--window-id mw-9a8b7c6d5eEXAMPLE ^
--targets "Key=WindowTargetIds,Values=faa01c41-1d57-496c-ba77-ff9caEXAMPLE" ^
--task-arn "AWS-RunPatchBaseline" ^
--service-role-arn "arn:aws:iam::123456789012:role/MW-Role" ^
--task-type "RUN_COMMAND" ^
--max-concurrency 2 ^
--max-errors 1 ^
--priority 1 ^
--task-invocation-parameters "RunCommand={Parameters={Operation=Install}}"
```
------
系统将返回类似于以下内容的信息。
```
{
"WindowTaskId":"8a5c4629-31b0-4edd-8aea-33698EXAMPLE"
}
```
1. 运行以下命令以获取补丁组的高级补丁合规性摘要。概括性补丁合规性摘要包括补丁处于相应状态的托管式节点的数量。
**注意**
在第一个维护时段内，在补丁任务运行之前，预计会在摘要中看到托管式节点数量为零。
------
#### [ Linux & macOS ]
```
aws ssm describe-patch-group-state \
--patch-group "Database Servers"
```
------
#### [ Windows Server ]
```
aws ssm describe-patch-group-state ^
--patch-group "Database Servers"
```
------
系统将返回类似于以下内容的信息。
```
{
"Instances": number,
"InstancesWithFailedPatches": number,
"InstancesWithInstalledOtherPatches": number,
"InstancesWithInstalledPatches": number,
"InstancesWithInstalledPendingRebootPatches": number,
"InstancesWithInstalledRejectedPatches": number,
"InstancesWithMissingPatches": number,
"InstancesWithNotApplicablePatches": number,
"InstancesWithUnreportedNotApplicablePatches": number
}
```
1. 运行以下命令以获取补丁组的每个托管式节点的补丁摘要状态。每个托管式节点摘要包括处于相应补丁状态的许多补丁（按补丁组的每个托管式节点划分）。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-patch-states-for-patch-group \
--patch-group "Database Servers"
```
------
#### [ Windows Server ]
```
aws ssm describe-instance-patch-states-for-patch-group ^
--patch-group "Database Servers"
```
------
系统将返回类似于以下内容的信息。
```
{
"InstancePatchStates": [
{
"BaselineId": "string",
"FailedCount": number,
"InstalledCount": number,
"InstalledOtherCount": number,
"InstalledPendingRebootCount": number,
"InstalledRejectedCount": number,
"InstallOverrideList": "string",
"InstanceId": "string",
"LastNoRebootInstallOperationTime": number,
"MissingCount": number,
"NotApplicableCount": number,
"Operation": "string",
"OperationEndTime": number,
"OperationStartTime": number,
"OwnerInformation": "string",
"PatchGroup": "string",
"RebootOption": "string",
"SnapshotId": "string",
"UnreportedNotApplicableCount": number
}
]
}
```
有关可以用于 Patch Manager 配置任务的其他 AWS CLI 命令的示例，请参阅 [使用 AWS CLI 处理 Patch Manager 资源使用](patch-manager-cli-commands.md)。
# 排除 Patch Manager 问题
利用以下信息，帮助排查Patch Manager（AWS Systems Manager 中的一项工具）出现的问题。
**Topics**
+ [问题：`baseline_overrides.json` 出现“Invoke-PatchBaselineOperation : Access Denied”错误或“Unable to download file from S3”错误](#patch-manager-troubleshooting-patch-policy-baseline-overrides)
+ [问题：修补失败，没有明显的原因或错误消息](#race-condition-conflict)
+ [问题：意外的补丁合规结果](#patch-manager-troubleshooting-compliance)
+ [在 Linux 上运行 `AWS-RunPatchBaseline` 时出现的错误](#patch-manager-troubleshooting-linux)
+ [在 Windows Server 上运行 `AWS-RunPatchBaseline` 时出现错误](#patch-manager-troubleshooting-windows)
+ [在 macOS 上运行 `AWS-RunPatchBaseline` 时出现错误](#patch-manager-troubleshooting-macos)
+ [使用 AWS 支持 Automation 运行手册](#patch-manager-troubleshooting-using-support-runbooks)
+ [联系 AWS 支持](#patch-manager-troubleshooting-contact-support)
## 问题：`baseline_overrides.json` 出现“Invoke-PatchBaselineOperation : Access Denied”错误或“Unable to download file from S3”错误
**问题**：运行补丁策略指定的修补操作时，您会收到类似于以下示例的错误。
------
#### [ Example error on Windows Server ]
```
----------ERROR-------
Invoke-PatchBaselineOperation : Access Denied
At C:\ProgramData\Amazon\SSM\InstanceData\i-02573cafcfEXAMPLE\document\orchestr
ation\792dd5bd-2ad3-4f1e-931d-abEXAMPLE\PatchWindows\_script.ps1:219 char:13
+ $response = Invoke-PatchBaselineOperation -Operation Install -Snapsho ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OperationStopped: (Amazon.Patch.Ba...UpdateOpera
tion:InstallWindowsUpdateOperation) [Invoke-PatchBaselineOperation], Amazo
nS3Exception
+ FullyQualifiedErrorId : PatchBaselineOperations,Amazon.Patch.Baseline.Op
erations.PowerShellCmdlets.InvokePatchBaselineOperation
failed to run commands: exit status 0xffffffff
```
------
#### [ Example error on Linux ]
```
[INFO]: Downloading Baseline Override from s3://aws-quicksetup-patchpolicy-123456789012-abcde/baseline_overrides.json
[ERROR]: Unable to download file from S3: s3://aws-quicksetup-patchpolicy-123456789012-abcde/baseline_overrides.json.
[ERROR]: Error loading entrance module.
```
------
**原因**：您在 Quick Setup 中创建了补丁策略，并且某些托管式节点已附加了实例配置文件（适用于 EC2 实例）或服务角色（适用于非 EC2 计算机）。
但是，如下图所示，您未选中**将所需的 IAM 策略添加到附加到实例的现有实例配置文件**复选框。
![\[\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/QS-instance-profile-option.png)
创建补丁策略时，还会创建一个 Amazon S3 存储桶来存储策略的配置 `baseline_overrides.json` 文件。如果您在创建策略时未选中**将所需的 IAM 策略添加到附加到实例的现有实例配置文件**复选框，则在 S3 存储桶中访问 `baseline_overrides.json` 所需的 IAM 策略和资源标签不会自动添加到现有 IAM 实例配置文件和服务角色中。
**解决方案 1**：删除现有的补丁策略配置，然后创建替代策略配置，确保选中**将所需的 IAM 策略添加到附加到实例的现有实例配置文件**复选框。此选择会将此 Quick Setup 配置创建的 IAM 策略应用于已附加实例配置文件或服务角色的节点。（默认情况下，Quick Setup 向还*没有*实例配置文件或服务角色的实例和节点添加所需策略。） 有关更多信息，请参阅 [Automate organization-wide patching using a Quick Setup patch policy](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-patch-manager.html)。
**解决方案 2**：手动将所需的权限和标签添加到与 Quick Setup 一起使用的每个 IAM 实例配置文件和 IAM 服务角色。有关说明，请参阅[补丁策略 S3 存储桶的权限](quick-setup-patch-manager.md#patch-policy-s3-bucket-permissions)。
## 问题：修补失败，没有明显的原因或错误消息
**问题**：修补操作失败，但未返回错误消息。
**可能的原因**：修补托管式节点时，即使已成功安装补丁，文档执行也可能会中断并标记为失败。如果系统在修补操作期间启动意外重启（例如，将更新应用于固件或诸如 SecuReboot 之类的功能），则可能会发生这种情况。SSM Agent 无法在外部重启后保持和恢复文档执行状态，从而导致执行被报告为失败。
**解决方案**：要在执行失败后验证补丁安装状态，请运行 `Scan` 修补操作，然后在补丁管理器中检查补丁合规性数据，进而评测当前的合规性状态。
如果确定外部重启不是导致这种情况失败的原因，我们建议联系 [AWS 支持](#patch-manager-troubleshooting-contact-support)。
## 问题：意外的补丁合规结果
**问题**：在 `Scan` 操作后查看生成的修补合规性详细信息时，结果中包含的信息不符合补丁基准中设置的规则。例如，您在补丁基准中添加到 **Rejected patches**（已拒绝补丁）列表中的异常被列为 `Missing`。或者，即使您的补丁基准仅指定 `Critical` 补丁，分类为 `Important` 的补丁也被列为缺失。
**原因**：Patch Manager 目前支持运行 `Scan` 操作的多种方法：
+ Quick Setup 中配置的补丁策略
+ Quick Setup 中配置的主机管理选项
+ 运行补丁 `Scan` 或 `Install` 任务的维护时段
+ 按需 **Patch now**（立即修补）操作
运行 `Scan` 操作时，它会覆盖最近扫描的合规性详细信息。如果您设置了多个方法来运行 `Scan` 操作，并且这些方法使用不同的补丁基准和不同的规则，那么它们会导致不同的补丁合规结果。
**解决方案**：为避免出现意外的补丁合规结果，我们建议一次仅使用一种方法来运行 Patch Manager `Scan` 操作。有关更多信息，请参阅 [识别创建补丁合规性数据的执行](patch-manager-compliance-data-overwrites.md)。
## 在 Linux 上运行 `AWS-RunPatchBaseline` 时出现的错误
**Topics**
+ [问题：“没有这样的文件或目录”错误](#patch-manager-troubleshooting-linux-1)
+ [问题：“另一个进程已获得 yum 锁定” 错误](#patch-manager-troubleshooting-linux-2)
+ [问题：“权限拒绝/未能运行命令” 错误](#patch-manager-troubleshooting-linux-3)
+ [问题：“Unable to download payload”错误](#patch-manager-troubleshooting-linux-4)
+ [问题：“不支持的软件包管理器和 python 版本组合” 错误](#patch-manager-troubleshooting-linux-5)
+ [问题：Patch Manager 没有应用指定来排除某些软件包的规则](#patch-manager-troubleshooting-linux-6)
+ [问题：修补失败同时 Patch Manager 报告 TLS 的服务器名称指示扩展不可用](#patch-manager-troubleshooting-linux-7)
+ [问题:Patch Manager 报告“没有更多的镜像要尝试”](#patch-manager-troubleshooting-linux-8)
+ [问题：修补失败并显示消息“Error code returned from curl is 23”](#patch-manager-troubleshooting-linux-9)
+ [问题：修补失败并显示消息“Error unpacking rpm package…”](#error-unpacking-rpm)
+ [问题：修补失败并显示消息“上传清单时出现服务端错误”](#inventory-upload-error)
+ [问题：修补失败并显示消息“Errors were encountered while downloading packages”](#errors-while-downloading)
+ [问题：修补失败并出现内存不足（OOM）错误](#patch-manager-troubleshooting-linux-oom)
+ [问题：修补失败并显示消息“The following signatures couldn't be verified because the public key is not available”](#public-key-unavailable)
+ [问题：修补失败并显示消息“NoMoreMirrorsRepoError”](#no-more-mirrors-repo-error)
+ [问题：修补失败并显示消息“Unable to download payload”](#payload-download-error)
+ [问题：修补失败并显示消息“install errors: dpkg: error: dpkg frontend is locked by another process”](#dpkg-frontend-locked)
+ [问题：Ubuntu Server 上的修补失败并出现“dpkg was interrupted”错误](#dpkg-interrupted)
+ [问题：程序包管理器实用工具无法解析包依赖项](#unresolved-dependency)
+ [问题：SLES 托管节点上的 Zypper 软件包锁定依赖项故障](#patch-manager-troubleshooting-linux-zypper-locks)
+ [问题：无法获取锁。另一个修补操作正在进行中。](#patch-manager-troubleshooting-linux-concurrent-lock)
### 问题：“没有这样的文件或目录”错误
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败，并出现以下错误之一。
```
IOError: [Errno 2] No such file or directory: 'patch-baseline-operations-X.XX.tar.gz'
```
```
Unable to extract tar file: /var/log/amazon/ssm/patch-baseline-operations/patch-baseline-operations-1.75.tar.gz.failed to run commands: exit status 155
```
```
Unable to load and extract the content of payload, abort.failed to run commands: exit status 152
```
**原因 1**：要运行 `AWS-RunPatchBaseline` 的两个命令同时在同一托管式节点上运行。这将创建一个竞争条件，导致临时 `file patch-baseline-operations*` 未能正确创建或访问。
**原因 2**：`/var` 目录中的存储空间依然不足。
**解决方案 1**：确保维护时段没有具有相同的优先级并且在相同的目标 ID 上运行的两个或多个运行 `AWS-RunPatchBaseline` 的 Run Command 任务。如果是这种情况，请重新排序优先级。Run Command 是 AWS Systems Manager 中的一项工具。
**解决方案 2**：确保一次只有一个维护时段正在运行 Run Command 任务，该任务对相同的目标、在相同的时间表上使用 `AWS-RunPatchBaseline`。如果出现这种情况，请更改时间表。
**解决方案 3**：确保按照相同的计划只有一个State Manager关联正在运行 `AWS-RunPatchBaseline`，并针对相同的托管式节点。State Manager是 AWS Systems Manager 中的一项工具。
**解决方案 4**：在 `/var` 目录中为更新程序包释放足够的存储空间。
### 问题：“另一个进程已获得 yum 锁定” 错误
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败并显示以下错误。
```
12/20/2019 21:41:48 root [INFO]: another process has acquired yum lock, waiting 2 s and retry.
```
**原因**：`AWS-RunPatchBaseline` 文档已经开始在某个托管式节点上运行（在该节点中，该文档已在其他操作中运行），并且已获得软件包管理器 `yum` 进程。
**解决方案**：确保按计划运行 `AWS-RunPatchBaseline` 的 State Manager 关联、维护时段任务或其他配置不会在几乎同一时间针对相同的托管节点。
### 问题：“权限拒绝/未能运行命令” 错误
**问题**：当您运行 `AWS-RunPatchBaseline`，则修补失败并显示以下错误。
```
sh:
/var/lib/amazon/ssm/instanceid/document/orchestration/commandid/PatchLinux/_script.sh: Permission denied
failed to run commands: exit status 126
```
**原因**：`/var/lib/amazon/` 可能会使用 `noexec` 权限。这是一个问题，因为 SSM Agent 把有效载荷脚本下载到 `/var/lib/amazon/ssm` 并从该位置运行它们。
**解决方案**：确保您已将独占分区配置为 `/var/log/amazon` 和 `/var/lib/amazon`，并且它们挂载了 `exec` 权限。
### 问题：“Unable to download payload”错误
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败并显示以下错误。
```
Unable to download payload: https://s3.amzn-s3-demo-bucket.region.amazonaws.com/aws-ssm-region/patchbaselineoperations/linux/payloads/patch-baseline-operations-X.XX.tar.gz.failed to run commands: exit status 156
```
**原因**：托管式节点没有访问指定的 Amazon Simple Storage Service (Amazon S3) 存储桶所需的权限。
**解决方案**：更新您的网络配置，以便可访问 S3 端点。有关更多详细信息，请参阅 [SSM Agent 与 AWS 托管 S3 存储桶进行通信](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions) 中 Patch Manager 对 S3 存储桶的所需访问。
### 问题：“不支持的软件包管理器和 python 版本组合” 错误
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败并显示以下错误。
```
An unsupported package manager and python version combination was found. Apt requires Python3 to be installed.
failed to run commands: exit status 1
```
**原因**：Debian Server 或 Ubuntu Server 实例上未安装受支持版本的 python3。
**解决方案**：在服务器上安装受支持版本的 python3（3.0 - 3.12），Debian Server 和 Ubuntu Server 托管节点必须使用这些版本。
### 问题：Patch Manager 没有应用指定来排除某些软件包的规则
**问题**：您试图排除某些软件包，方法是在 `/etc/yum.conf` 文件中指定这些软件包，格式为 `exclude=package-name`，但在 Patch Manager `Install` 操作期间不排除它们。
**原因**：Patch Manager 不包含 `/etc/yum.conf` 文件中指定的排除项。
**解决方案**：要排除特定软件包，请创建自定义补丁基准并创建排除不想安装的软件包的规则。
### 问题：修补失败同时 Patch Manager 报告 TLS 的服务器名称指示扩展不可用
**问题**：修补操作发出以下消息。
```
/var/log/amazon/ssm/patch-baseline-operations/urllib3/util/ssl_.py:369:
SNIMissingWarning: An HTTPS request has been made, but the SNI (Server Name Indication) extension
to TLS is not available on this platform. This might cause the server to present an incorrect TLS
certificate, which can cause validation failures. You can upgrade to a newer version of Python
to solve this.
For more information, see https://urllib3.readthedocs.io/en/latest/advanced-usage.html#ssl-warnings
```
**原因**：此消息不表示错误存在。相反，这是一个警告，即随操作系统一起分发的较旧版本的 Python 不支持 TLS 服务器名称指示。在连接到支持 SNI 的 AWS API 时，Systems Manager 补丁有效载荷脚本发出此警告。
**解决方案**：若要在报告此消息时解决任何修补失败问题，请查看 `stdout` 和 `stderr` 文件的内容。如果您尚未配置补丁基准以将这些文件存储在 S3 存储桶或 Amazon CloudWatch Logs 中，则可以在 Linux 托管节点上的以下位置找到这些文件。
`/var/lib/amazon/ssm/instance-id/document/orchestration/Run-Command-execution-id/awsrunShellScript/PatchLinux`
### 问题:Patch Manager 报告“没有更多的镜像要尝试”
**问题**：修补操作发出以下消息。
```
[Errno 256] No more mirrors to try.
```
**原因**：在托管式节点上配置的存储库无法正常工作。可能的原因包括：
+ `yum` 缓存已损坏。
+ 由于网络相关问题，无法访问存储库 URL。
**解决方案**：Patch Manager 使用托管式节点的默认软件包管理器执行修补操作。双重检查存储库是否已配置并正常运行。
### 问题：修补失败并显示消息“Error code returned from curl is 23”
**问题**：使用 `AWS-RunPatchBaseline` 的修补操作失败，并出现类似以下内容的错误：
```
05/01/2025 17:04:30 root [ERROR]: Error code returned from curl is 23
```
**原因**：系统上使用的 curl 工具缺少写入文件系统所需的权限。如果程序包管理器的默认 curl 工具被其他版本（例如随 snap 安装的版本）所取代，则可能会发生这种情况。
**解决方案**：如果安装其他版本时卸载了程序包管理器提供的 curl 版本，请重新安装。
如果您需要安装多个 curl 版本，请确保与程序包管理器关联的版本位于 `PATH` 变量中列出的第一个目录中。您可以通过运行命令 `echo $PATH` 来查看系统上检查可执行文件的目录的当前顺序。
### 问题：修补失败并显示消息“Error unpacking rpm package…”
**问题**：修补操作失败，并出现类似以下内容的错误：
```
Error : Error unpacking rpm package python-urllib3-1.25.9-1.amzn2.0.2.noarch
python-urllib3-1.25.9-1.amzn2.0.1.noarch was supposed to be removed but is not!
failed to run commands: exit status 1
```
**原因 1**：特定程序包存在于多个程序包安装程序（例如 `pip` 和 `yum` 或 `dnf`）中时，使用默认程序包管理器时可能会发生冲突。
一个常见的示例是 `urllib3` 程序包，可以在 `pip`、`yum` 和 `dnf` 中找到。
**原因 2**：`python-urllib3` 程序包已损坏。如果 `yum` 或 `dnf` 先前安装了 `rpm` 程序包之后，`pip` 安装或更新了程序包文件，则可能会发生这种情况。
**解决方案**：通过运行命令 `sudo pip uninstall urllib3` 从 pip 中删除 `python-urllib3` 程序包，仅将此程序包保留在默认程序包管理器（`yum` 或 `dnf`）中。
### 问题：修补失败并显示消息“上传清单时出现服务端错误”
**问题**：运行 `AWS-RunPatchBaseline` 文档时，收到以下错误消息：
```
Encounter service side error when uploading the inventory
```
**原因**：要运行 `AWS-RunPatchBaseline` 的两个命令同时在同一托管式节点上运行，这导致在修补操作期间初始化 boto3 客户端时产生了争用条件。
**解决方案**：确保按计划运行 `AWS-RunPatchBaseline` 的 State Manager 关联、维护时段任务或其他配置不会在几乎同一时间针对相同的托管节点。
### 问题：修补失败并显示消息“Errors were encountered while downloading packages”
**问题**：在修补期间，您会收到类似以下内容的错误：
```
YumDownloadError: [u'Errors were encountered while downloading
packages.', u'libxml2-2.9.1-6.el7_9.6.x86_64: [Errno 5] [Errno 12]
Cannot allocate memory', u'libxslt-1.1.28-6.el7.x86_64: [Errno 5]
[Errno 12] Cannot allocate memory', u'libcroco-0.6.12-6.el7_9.x86_64:
[Errno 5] [Errno 12] Cannot allocate memory', u'openldap-2.4.44-25.el7_9.x86_64:
[Errno 5] [Errno 12] Cannot allocate memory',
```
**原因**：托管式节点上的可用内存不足时，可能会发生此错误。
**解决方案**：配置交换内存，或将实例升级到其他类型以增加内存。然后开始新的修补操作。
### 问题：修补失败并出现内存不足（OOM）错误
**问题**：运行 `AWS-RunPatchBaseline` 时，由于托管式节点上内存不足，修补操作失败。您可能会看到诸如 `Cannot allocate memory`、`Killed`（来自 Linux OOM Killer）之类的错误，或者操作意外失败。在 RAM 小于 1 GB 的实例上出现此错误的可能性更高，但有大量可用更新时也可能会影响内存较大的实例。
**原因**：Patch Manager 在托管式节点上使用原生软件包管理器运行修补操作。修补操作期间所需的内存取决于多个因素，包括：
+ 托管式节点上安装的软件包和可用更新数量。
+ 正在使用的软件包管理器及其内存特性。
+ 执行修补操作时托管式节点上运行的其他进程。
对于安装了大量软件包或有大量可用更新的托管式节点，执行修补操作期间将需要更多内存。当可用内存不足时，修补进程将会失败退出并显示错误。操作系统也可能会终止修补进程。
**解决方法**：尝试以下一种或多种解决方法：
+ 在托管式节点上工作负载较低的时段安排修补操作，例如使用维护时段。
+ 将实例升级到具有更多内存的类型。
+ 在托管式节点上配置交换内存。请注意，在 EBS 吞吐量有限的实例上大量使用交换可能会导致性能下降。
+ 检查并减少修补操作期间在托管式节点上运行的进程数量。
### 问题：修补失败并显示消息“The following signatures couldn't be verified because the public key is not available”
**问题**：Ubuntu Server 上的修补失败，并出现类似以下内容的错误：
```
02/17/2022 21:08:43 root [ERROR]: W:GPG error:
http://repo.mysql.com/apt/ubuntu bionic InRelease: The following
signatures couldn't be verified because the public key is not available:
NO_PUBKEY 467B942D3A79BD29, E:The repository ' http://repo.mysql.com/apt/ubuntu bionic
```
**原因**：GNU 隐私保护（GPG）密钥已过期或丢失。
**解决方案**：刷新 GPG 密钥，或者重新添加密钥。
例如，借助之前显示的错误，我们发现 `467B942D3A79BD29` 密钥丢失，必须添加此密钥。为此，请运行以下命令之一：
```
sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com --recv-keys 467B942D3A79BD29
```
```
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 467B942D3A79BD29
```
或者，要刷新所有密钥，请运行以下命令：
```
sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com --refresh-keys
```
如果之后再次出现此错误，我们建议将问题报告给维护存储库的组织。在修复可用之前，您可以编辑 `/etc/apt/sources.list` 文件以在修补过程中省略存储库。
为此，请打开 `sources.list` 文件进行编辑，找到存储库所在的行，然后在行首插入 `#` 字符将其注释掉。保存并关闭此文件。
### 问题：修补失败并显示消息“NoMoreMirrorsRepoError”
**问题**：您会收到类似以下内容的错误：
```
NoMoreMirrorsRepoError: failure: repodata/repomd.xml from pgdg94: [Errno 256] No more mirrors to try.
```
**原因**：源存储库中存在错误。
**解决方案**：我们建议将问题报告给维护存储库的组织。在错误修复之前，您可以在操作系统级别禁用存储库。为此，请运行以下命令，将 *repo-name* 的值替换为存储库名称：
```
yum-config-manager --disable repo-name
```
以下为示例。
```
yum-config-manager --disable pgdg94
```
运行此命令后，再次执行修补操作。
### 问题：修补失败并显示消息“Unable to download payload”
**问题**：您会收到类似以下内容的错误：
```
Unable to download payload:
https://s3.dualstack.eu-west-1.amazonaws.com/aws-ssm-eu-west-1/patchbaselineoperations/linux/payloads/patch-baseline-operations-1.83.tar.gz.
failed to run commands: exit status 156
```
**原因**：托管式节点配置存在错误或不完整。
**解决方案**：确保托管式节点配置如下：
+ 安全组中的出站 TCP 443 规则。
+ NACL 中的出口 TCP 443 规则。
+ NACL 中的入口 TCP 1024-65535 规则。
+ 路由表中的 NAT/IGW 用于提供与 S3 端点的连接。如果实例无法访问互联网，请为其提供与 S3 端点的连接。为此，请在 VPC 中添加 S3 网关端点，并将其与托管式节点的路由表集成。
### 问题：修补失败并显示消息“install errors: dpkg: error: dpkg frontend is locked by another process”
**问题**：修补失败，并出现类似以下内容的错误：
```
install errors: dpkg: error: dpkg frontend is locked by another process
failed to run commands: exit status 2
Failed to install package; install status Failed
```
**原因**：程序包管理器已经在操作系统级别的托管式节点上运行另一个进程。如果其他进程需要很长时间才能完成，则 Patch Manager 修补操作可能会超时并失败。
**解决方案**：使用程序包管理器的其他进程完成后，执行新的修补操作。
### 问题：Ubuntu Server 上的修补失败并出现“dpkg was interrupted”错误
**问题**：在 Ubuntu Server 上，修补失败并出现类似以下内容的错误：
```
E: dpkg was interrupted, you must manually run
'dpkg --configure -a' to correct the problem.
```
**原因**：一个或多个程序包配置错误。
**解决方案**：执行以下步骤：
1. 通过依次运行以下命令来检查受影响的程序包，以及每个程序包存在的问题：
```
sudo apt-get check
```
```
sudo dpkg -C
```
```
dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' | grep -E ^.[^nci]
```
1. 通过运行以下命令更正有问题的程序包：
```
sudo dpkg --configure -a
```
1. 如果之前的命令未完全解决问题，可运行以下命令：
```
sudo apt --fix-broken install
```
### 问题：程序包管理器实用工具无法解析包依赖项
**问题**：托管式节点上的本机程序包管理器无法解析程序包依赖项，修补失败。以下错误消息示例指示使用 `yum` 作为程序包管理器的操作系统上的此类故障。
```
09/22/2020 08:56:09 root [ERROR]: yum update failed with result code: 1,
message: [u'rpm-python-4.11.3-25.amzn2.0.3.x86_64 requires rpm = 4.11.3-25.amzn2.0.3',
u'awscli-1.18.107-1.amzn2.0.1.noarch requires python2-botocore = 1.17.31']
```
**原因**：在 Linux 操作系统上，Patch Manager 使用计算机上的本机程序包管理器来执行修补操作。例如 `yum`、`dnf`、`apt` 和 `zypper`。应用程序会根据需要自动检测、安装、更新或删除从属程序包。但是，某些情况可能会导致程序包管理器无法完成依赖项操作，例如：
+ 操作系统上配置了多个相互冲突的存储库。
+ 由于网络相关问题，无法访问远程存储库 URL。
+ 存储库中发现了错误架构的包。
**解决方案**：由于各种原因，依赖项可能会导致修补失败。因此，我们建议您联系 AWS 支持 以帮助您进行故障排除。
### 问题：SLES 托管节点上的 Zypper 软件包锁定依赖项故障
**问题**：使用 `Install` 操作在 SUSE Linux Enterprise Server 实例上运行 `AWS-RunPatchBaseline` 时，修补程序失败，并出现与软件包锁定相关的依赖项检查错误。您可能会看到类似于以下内容的错误消息：
```
Problem: mock-pkg-has-dependencies-0.2.0-21.adistro.noarch requires mock-pkg-standalone = 0.2.0, but this requirement cannot be provided
uninstallable providers: mock-pkg-standalone-0.2.0-21.adistro.noarch[local-repo]
Solution 1: remove lock to allow installation of mock-pkg-standalone-0.2.0-21.adistro.noarch[local-repo]
Solution 2: do not install mock-pkg-has-dependencies-0.2.0-21.adistro.noarch
Solution 3: break mock-pkg-has-dependencies-0.2.0-21.adistro.noarch by ignoring some of its dependencies
Choose from above solutions by number or cancel [1/2/3/c] (c): c
```
在此示例中，软件包 `mock-pkg-standalone` 已锁定，您可以通过运行 `sudo zypper locks` 并在输出中查找软件包名称来进行验证。
或者您可能会看到指示依赖项检查失败的日志条目：
```
Encountered a known exception in the CLI Invoker: CLIInvokerError(error_message='Dependency check failure during commit process', error_code='4')
```
**注意**
该问题仅在 `Install` 操作期间出现。`Scan` 操作不应用软件包锁定，也不受现有软件包锁定的影响。”
**原因**：当 zypper 软件包锁定由于依赖项冲突而阻止安装或更新软件包时，就会发生这种错误。软件包锁定可能由若干原因所致：
+ **客户应用的锁定**：您或您的系统管理员使用 zypper 命令（例如 `zypper addlock`）手动锁定了软件包。
+ **Patch Manager 拒绝修补**：当您在补丁基准的“**拒绝的修补程序**”列表中指定软件包时，Patch Manager 会自动应用软件包锁定以阻止安装软件包。
+ **操作中断产生的残留锁**：在极少数情况下，如果修补操作在 Patch Manager 清理临时锁之前中断（例如系统重启），则在托管节点上可能会留存残留的软件包锁。
**解决方案**：要解决 zypper 软件包锁定的问题，请根据原因执行以下步骤：
**步骤 1：确定已锁定的软件包**
连接到 SLES 托管节点并运行以下命令，列出所有当前锁定的软件包：
```
sudo zypper locks
```
**步骤 2：确定锁的来源**
+ 如果锁定的软件包是您出于系统稳定性而故意锁定的，请考虑软件包是否需要保持锁定状态，或者是否可以临时解锁以进行修补。
+ 如果锁定的软件包与补丁基准的“**拒绝的修补程序**”列表中的条目相匹配，则表明这些软件包可能是因为修补操作中断而产生的残留锁。在正常操作中，Patch Manager 会临时应用这些锁定，并在操作完成后自动移除。您可以从拒绝列表中移除软件包，也可以修改补丁基准的规则。
+ 如果无法识别锁定的软件包，并且软件包不是故意锁定的，则可能是之前中断的修补操作产生的残留锁。
**第 3 步：根据需要移除锁定**
要移除特定的软件包锁定，请使用以下命令：
```
sudo zypper removelock package-name
```
要移除所有软件包锁定（谨慎使用），请运行：
```
sudo zypper cleanlocks
```
**步骤 4：更新补丁基准（如适用）**
如果锁定是由补丁基准中拒绝的修补程序造成的：
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Patch Manager**。
1. 选择**补丁基准**选项卡，然后选择自定义补丁基准。
1. 选择**操作**、**修改补丁基准**。
1. 在“**拒绝的修补程序**”部分，查看列出的软件包并移除应允许安装的任何软件包。
1. 选择**保存更改**。
**步骤 5：重试修补操作**
移除有问题的锁定并根据需要更新补丁基准之后，请再次运行 `AWS-RunPatchBaseline` 文档。
**注意**
Patch Manager 在 `Install` 操作期间对拒绝的修补程序应用锁定时，其设计旨在于修补操作完成后自动清理这些锁。如果在运行 `sudo zypper locks` 时看到了这些锁定，则表示之前的修补操作在清理完成之前已中断。但是，如果修补操作中断，则可能需要按照本流程中的说明进行手动清理。
**预防**：为避免未来出现 zypper 锁定冲突，请：
+ 仔细查看补丁基准中拒绝的修补程序，确保其中仅包含您真正想要排除的软件包。
+ 避免手动锁定可能需要作为安全更新依赖项的软件包。
+ 如果必须手动锁定软件包，请记录原因并定期检查锁定。
+ 确保修补操作成功完成，且未因系统重启或其他因素而中断。
+ 监控修补操作直至完成，避免因为系统重启或其他可能妨碍正确清理临时锁定的操作而中断。
### 问题：无法获取锁。另一个修补操作正在进行中。
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败，错误代码为 4，并显示以下错误消息。
```
[ERROR]: Cannot acquire lock on /var/log/amazon/ssm/patch-baseline-concurrent.lock. Another patching operation is in progress.
```
**原因**：当多个修补操作试图同时在同一受管节点上运行时，会发生此错误。锁定文件可防止并发修补操作，以避免冲突并确保系统稳定性。
**解决方案**：确保不要安排修补操作在同一托管节点上同时运行。请查看下面的配置以识别和解决调度冲突：
+ **补丁策略**：检查您的快速设置功能补丁策略配置，确保它们不会与其他修补计划重叠。
+ **维护时段**：检查维护时段关联，以确认多个时段不会在重叠时间对同一托管节点执行修补任务。
+ **手动立即修补操作**：避免在计划修补过程中启动手动**立即修补**操作。
## 在 Windows Server 上运行 `AWS-RunPatchBaseline` 时出现错误
**Topics**
+ [问题：产品系列/产品对不匹配](#patch-manager-troubleshooting-product-family-mismatch)
+ [问题: `AWS-RunPatchBaseline` 输出返回 `HRESULT`(Windows Server）](#patch-manager-troubleshooting-hresult)
+ [问题：托管式节点无法访问 Windows 更新目录或 WSUS](#patch-manager-troubleshooting-instance-access)
+ [问题：无法下载 PatchBaselineOperations （补丁基准操作） PowerShell 模块](#patch-manager-troubleshooting-module-not-downloadable)
+ [问题：缺少补丁](#patch-manager-troubleshooting-missing-patches)
+ [问题：无法获取锁。另一个修补操作正在进行中。](#patch-manager-troubleshooting-windows-concurrent-lock)
### 问题：产品系列/产品对不匹配
**问题**：在 Systems Manager 控制台中创建补丁基准时，您指定了产品系列和产品。例如，您可能选择：
+ **产品系列**：`Office`
**产品**：`Office 2016`
**原因**：如果您尝试使用不匹配的产品系列/产品对创建补丁基准，则会显示一条错误消息。以下是可能发生这种情况的原因：
+ 您选择了有效的产品系列/产品对，但随后删除了所选的产品系列。
+ 您从 **Obsolete or mismatched options (过时或不匹配的选项)** 子列表中选择的产品，而不是 **Available and matching options (可用和匹配选项)** 子列表。
产品**过时或不匹配的选项**子列表中的项目，可能是通过 SDK 或 AWS Command Line Interface (AWS CLI) `create-patch-baseline` 命令错误输入的。这可能意味着存在拼写错误或产品被分配到了错误的产品系列。如果为之前的补丁基准指定了某个产品，但该产品目前没有 Microsoft 提供的补丁，它也会包含在 **过时或不匹配的选项** 子列表中。
**解决方案**为避免控制台中出现此问题，请始终从**当前可用选项**子列表中选择选项。
您还可以使用 AWS CLI 中的 `[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-patch-properties.html)` 命令或 `[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchProperties.html)` API 命令查看具有可用补丁的产品。
### 问题: `AWS-RunPatchBaseline` 输出返回 `HRESULT`(Windows Server）
**问题**：您收到类似如下内容的错误：
```
----------ERROR-------
Invoke-PatchBaselineOperation : Exception Details: An error occurred when
attempting to search Windows Update.
Exception Level 1:
Error Message: Exception from HRESULT: 0x80240437
Stack Trace: at WUApiLib.IUpdateSearcher.Search(String criteria)..
(Windows updates)
11/22/2020 09:17:30 UTC | Info | Searching for Windows Updates.
11/22/2020 09:18:59 UTC | Error | Searching for updates resulted in error: Exception from HRESULT: 0x80240437
----------ERROR-------
failed to run commands: exit status 4294967295
```
**原因**：此输出表示本机 Windows 更新 API 无法运行修补操作。
**解决方案**：检查以下 microsoft.com 主题中的 `HResult` 代码以确定解决错误的故障排除步骤：
+ [按组件划分的 Windows 更新错误代码](https://learn.microsoft.com/en-us/windows/deployment/update/windows-update-error-reference)
+ [Windows 更新常见错误和缓解措施](https://learn.microsoft.com/en-us/troubleshoot/windows-client/deployment/common-windows-update-errors)
### 问题：托管式节点无法访问 Windows 更新目录或 WSUS
**问题**：您收到类似如下内容的错误。
```
Downloading PatchBaselineOperations PowerShell module from https://s3.aws-api-domain/path_to_module.zip to C:\Windows\TEMP\Amazon.PatchBaselineOperations-1.29.zip.
Extracting PatchBaselineOperations zip file contents to temporary folder.
Verifying SHA 256 of the PatchBaselineOperations PowerShell module files.
Successfully downloaded and installed the PatchBaselineOperations PowerShell module.
Patch Summary for
PatchGroup :
BaselineId :
Baseline : null
SnapshotId :
RebootOption : RebootIfNeeded
OwnerInformation :
OperationType : Scan
OperationStartTime : 1970-01-01T00:00:00.0000000Z
OperationEndTime : 1970-01-01T00:00:00.0000000Z
InstalledCount : -1
InstalledRejectedCount : -1
InstalledPendingRebootCount : -1
InstalledOtherCount : -1
FailedCount : -1
MissingCount : -1
NotApplicableCount : -1
UnreportedNotApplicableCount : -1
EC2AMAZ-VL3099P - PatchBaselineOperations Assessment Results - 2020-12-30T20:59:46.169
----------ERROR-------
Invoke-PatchBaselineOperation : Exception Details: An error occurred when attempting to search Windows Update.
Exception Level 1:
Error Message: Exception from HRESULT: 0x80072EE2
Stack Trace: at WUApiLib.IUpdateSearcher.Search(String criteria)
at Amazon.Patch.Baseline.Operations.PatchNow.Implementations.WindowsUpdateAgent.SearchForUpdates(String
searchCriteria)
At C:\ProgramData\Amazon\SSM\InstanceData\i-02573cafcfEXAMPLE\document\orchestration\3d2d4864-04b7-4316-84fe-eafff1ea58
e3\PatchWindows\_script.ps1:230 char:13
+ $response = Invoke-PatchBaselineOperation -Operation Install -Snapsho ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OperationStopped: (Amazon.Patch.Ba...UpdateOperation:InstallWindowsUpdateOperation) [Inv
oke-PatchBaselineOperation], Exception
+ FullyQualifiedErrorId : Exception Level 1:
Error Message: Exception Details: An error occurred when attempting to search Windows Update.
Exception Level 1:
Error Message: Exception from HRESULT: 0x80072EE2
Stack Trace: at WUApiLib.IUpdateSearcher.Search(String criteria)
at Amazon.Patch.Baseline.Operations.PatchNow.Implementations.WindowsUpdateAgent.SearchForUpdates(String searc
---Error truncated----
```
**原因**：此错误可能与 Windows 更新组件，或缺乏连接到 Windows 更新目录或 Windows 服务器更新服务 (WSUS)有关。
**解决方案**：确认托管式节点已通过互联网网关、NAT 网关或 NAT 实例与 [Microsoft 更新目录](https://www.catalog.update.microsoft.com/home.aspx)连接。如果您使用的是 WSUS，请确认该托管式节点已连接到环境中的 WSUS 服务器。如果可以连接到预期目标，请查看 Microsoft 文档中 `HResult 0x80072EE2` 的其他潜在原因。这可能表明存在操作系统级问题。
### 问题：无法下载 PatchBaselineOperations （补丁基准操作） PowerShell 模块
**问题**：您收到类似如下内容的错误。
```
Preparing to download PatchBaselineOperations PowerShell module from S3.
Downloading PatchBaselineOperations PowerShell module from https://s3.aws-api-domain/path_to_module.zip to C:\Windows\TEMP\Amazon.PatchBaselineOperations-1.29.zip.
----------ERROR-------
C:\ProgramData\Amazon\SSM\InstanceData\i-02573cafcfEXAMPLE\document\orchestration\aaaaaaaa-bbbb-cccc-dddd-4f6ed6bd5514\
PatchWindows\_script.ps1 : An error occurred when executing PatchBaselineOperations: Unable to connect to the remote server
+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,_script.ps1
failed to run commands: exit status 4294967295
```
**解决方案**：检查托管式节点与 Amazon Simple Storage Service (Amazon S3) 的连接和权限。托管式节点的 AWS Identity and Access Management (IAM) 角色必须使用 [SSM Agent 与 AWS 托管 S3 存储桶进行通信](ssm-agent-technical-details.md#ssm-agent-minimum-s3-permissions) 中引用的最低权限。节点必须通过 Amazon S3 网关端点、NAT 网关或互联网网关与 Amazon S3 端点进行通信。有关 AWS Systems Manager SSM Agent（SSM Agent）的 VPC 端点要求的更多信息，请参阅 [使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。
### 问题：缺少补丁
**问题**：`AWS-RunPatchbaseline` 已成功完成，但缺少一些补丁。
以下是一些常见原因及其解决方案。
**原因 1**：基准无效。
**解决方案 1**：要检查这是否是原因，请使用以下过程。
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择**命令历史记录**选项卡，然后选择要检查其基准的命令。
1. 选择缺少补丁的托管式节点。
1. 选择**步骤 1 - 输出**并查找 `BaselineId` 值。
1. 检查分配的[补丁基准配置](patch-manager-predefined-and-custom-patch-baselines.md#patch-manager-baselines-custom)，即补丁基准的操作系统、产品名称、分类和严重性。
1. 转至[微软更新目录](https://www.catalog.update.microsoft.com/home.aspx)。
1. 搜索 Microsoft 知识库 (KB) 文章 ID（例如 KB3216916）。
1. 确认 **Product**（产品）下的值与托管式节点的值相匹配，然后选择相应的 **Title**（标题）。一个新**更新详细信息**窗口将打开。
1. 在**概述**选项卡中，**分类**和 **MSRC 严重性**必须与之前找到的补丁基准配置匹配。
**原因 2**：已替换补丁。
**解决方案 2**：要检查是否为真，请使用以下过程。
1. 转至[微软更新目录](https://www.catalog.update.microsoft.com/home.aspx)。
1. 搜索 Microsoft 知识库 (KB) 文章 ID（例如 KB3216916）。
1. 确认 **Product**（产品）下的值与托管式节点的值相匹配，然后选择相应的 **Title**（标题）。一个新**更新详细信息**窗口将打开。
1. 转至**程序包详细信息**选项卡。在**此更新已被以下更新所替换：**标头下面查找条目。
**原因 3**：相同的补丁可能具有不同的知识库编号，因为 WSUS 和窗口联机更新由 Microsoft 处理为独立的发布渠道。
**解决方案 3**：检查补丁的资格。如果软件包在 WSUS 下不可用，请安装[操作系统构建 14393.3115](https://support.microsoft.com/en-us/topic/july-16-2019-kb4507459-os-build-14393-3115-511a3df6-c07e-14e3-dc95-b9898a7a7a57)。如果该软件包适用于所有操作系统构建，请安装[操作系统构建 18362.1256 和 18363.1256](https://support.microsoft.com/en-us/topic/december-8-2020-kb4592449-os-builds-18362-1256-and-18363-1256-c448f3df-a5f1-1d55-aa31-0e1cf7a440a9)。
### 问题：无法获取锁。另一个修补操作正在进行中。
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败，错误代码为 4，并显示以下错误消息。
```
Cannot acquire lock on C:\ProgramData\Amazon\SSM\patch-baseline-concurrent.lock. Another patching operation is in progress.
```
**原因**：当多个修补操作试图同时在同一受管节点上运行时，会发生此错误。锁定文件可防止并发修补操作，以避免冲突并确保系统稳定性。
**解决方案**：确保不要安排修补操作在同一托管节点上同时运行。请查看下面的配置以识别和解决调度冲突：
+ **补丁策略**：检查您的快速设置功能补丁策略配置，确保它们不会与其他修补计划重叠。
+ **维护时段**：检查维护时段关联，以确认多个时段不会在重叠时间对同一托管节点执行修补任务。
+ **手动立即修补操作**：避免在计划修补过程中启动手动**立即修补**操作。
## 在 macOS 上运行 `AWS-RunPatchBaseline` 时出现错误
**Topics**
+ [问题：无法获取锁。另一个修补操作正在进行中。](#patch-manager-troubleshooting-macos-concurrent-lock)
### 问题：无法获取锁。另一个修补操作正在进行中。
**问题**：当您运行 `AWS-RunPatchBaseline` 时，修补失败，错误代码为 4，并显示以下错误消息。
```
[ERROR]: Cannot acquire lock on /var/log/amazon/ssm/patch-baseline-concurrent.lock. Another patching operation is in progress.
```
**原因**：当多个修补操作试图同时在同一受管节点上运行时，会发生此错误。锁定文件可防止并发修补操作，以避免冲突并确保系统稳定性。
**解决方案**：确保不要安排修补操作在同一托管节点上同时运行。请查看下面的配置以识别和解决调度冲突：
+ **补丁策略**：检查您的快速设置功能补丁策略配置，确保它们不会与其他修补计划重叠。
+ **维护时段**：检查维护时段关联，以确认多个时段不会在重叠时间对同一托管节点执行修补任务。
+ **手动立即修补操作**：避免在计划修补过程中启动手动**立即修补**操作。
## 使用 AWS 支持 Automation 运行手册
AWS 支持 提供了两个 Automation 运行手册，可用于排查与修补相关的某些问题。
+ `AWSSupport-TroubleshootWindowsUpdate`：[https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/awssupport-troubleshoot-windows-update.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/awssupport-troubleshoot-windows-update.html) 运行手册用于识别可能导致 Amazon Elastic Compute Cloud（Amazon EC2）Windows Server 实例 Windows Server 更新失败的问题。
+ `AWSSupport-TroubleshootPatchManagerLinux`：[https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-troubleshoot-patch-manager-linux.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-troubleshoot-patch-manager-linux.html) 运行手册用于解决可能导致使用Patch Manager的基于 Linux 的托管式节点上出现补丁失败的常见问题。本运行手册的主要目标是确定补丁命令失败的根本原因并提出补救方案。
**注意**
运行 Automation 运行手册会产生费用。有关信息，请参阅 [AWS Systems Manager Automation 定价](https://aws.amazon.com/systems-manager/pricing/#Automation)。
## 联系 AWS 支持
如果您无法在本节或 [AWS re:Post](https://repost.aws/tags/TA-UbbRGVYRWCDaCvae6itYg/aws-systems-manager) 中的 Systems Manager 问题中找到故障排除解决方案，并且您有[开发人员、业务或企业 支持 计划](https://aws.amazon.com/premiumsupport/plans)，可在 [AWS 支持](https://aws.amazon.com/premiumsupport/) 创建一个技术支持用例。
在您联系 支持 之前，收集以下物品：
+ [SSM 代理日志](ssm-agent-logs.md)
+ Run Command 命令 ID、维护时段 ID 或自动化执行 ID
+ 对于 Windows Server 托管式节点，还要收集以下内容：
+ `%PROGRAMDATA%\Amazon\PatchBaselineOperations\Logs`，如 **Windows** 的选项卡 [如何安装补丁](patch-manager-installing-patches.md) 中所描述的那样
+ Windows 更新日志：对于 Windows Server 2012 R2 及更高版本，使用 `%windir%/WindowsUpdate.log`。对于 Windows Server 2016 及更新版本，首先运行 PowerShell 命令 [https://docs.microsoft.com/en-us/powershell/module/windowsupdate/get-windowsupdatelog?view=win10-ps](https://docs.microsoft.com/en-us/powershell/module/windowsupdate/get-windowsupdatelog?view=win10-ps)，然后再使用 `%windir%/WindowsUpdate.log`
+ 对于 Linux 托管式节点，还要收集以下内容：
+ 目录 `/var/lib/amazon/ssm/instance-id/document/orchestration/Run-Command-execution-id/awsrunShellScript/PatchLinux` 的内容
# AWS Systems Manager Run Command
使用 Run Command（AWS Systems Manager 中的一项工具），您可以通过安全方式远程管理托管式节点的配置。*托管式节点*是在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中已为 Systems Manager 配置的任何 Amazon Elastic Compute Cloud（Amazon EC2）实例或非 EC2 计算机。Run Command 支持您自动完成常见管理任务以及大规模执行一次性配置更改。您可以从 AWS 管理控制台、AWS Command Line Interface（AWS CLI）、AWS Tools for Windows PowerShell 或 AWS SDK 使用 Run Command。Run Command 不另外收费。要开始使用 Run Command，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/run-command)。在导航窗格中，请选择 **Run Command**。
管理员可以使用 Run Command 安装或引导启动应用程序，构建部署管道，从 Auto Scaling 组移除实例时捕获日志文件，将实例加入 Windows 域，等等。
由于系统支持 API 的分布式特性，Run Command API 遵循最终一致性模型。这意味着您执行的对您的资源产生影响的 API 命令的结果可能不会立即对您运行的所有后续命令可见。在执行紧随上一个 API 命令的 API 命令时，应记住这一点。
**开始使用**
下表包含可帮助您开始使用 Run Command 的信息。
****
| Topic | Details |
| --- | --- |
| [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md) | 验证您是否已在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中完成 Amazon Elastic Compute Cloud（Amazon EC2）实例以及非 EC2 计算机的设置要求。 |
| [使用 Systems Manager 管理混合和多云环境中的节点](systems-manager-hybrid-multicloud.md) | （可选）将本地服务器和虚拟机注册到 AWS，以便可以使用 Run Command 来管理它们。 |
| [使用 Systems Manager 管理边缘设备](systems-manager-setting-up-edge-devices.md) | （可选）配置边缘设备，以便可以使用 Run Command 管理它们。 |
| [在托管节点上运行命令](running-commands.md) | 了解如何使用 AWS 管理控制台 运行以一个或多个托管式节点为目标的命令。 |
| [Run Command 演练](run-command-walkthroughs.md) | 了解如何使用 Tools for Windows PowerShell 或 AWS CLI 运行命令。 |
**EventBridge 支持**
在 Amazon EventBridge 规则中，支持将此 Systems Manager 工具作为*事件*类型和*目标*类型。有关信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md) 和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
**更多信息**
+ [在 EC2 实例上远程 Run Command（10 分钟教程）](https://aws.amazon.com/getting-started/hands-on/remotely-run-commands-ec2-instance-systems-manager/)
+ 请参阅*《Amazon Web Services 一般参考》*中的 [Systems Manager 服务配额](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)
+ [AWS Systems Manager API 参考](https://docs.aws.amazon.com/systems-manager/latest/APIReference/)
**Topics**
+ [设置 Run Command](run-command-setting-up.md)
+ [在托管节点上运行命令](running-commands.md)
+ [在命令中使用退出代码](run-command-handle-exit-status.md)
+ [了解命令状态](monitor-commands.md)
+ [Run Command 演练](run-command-walkthroughs.md)
+ [对 Systems Manager Run Command 进行故障排除](troubleshooting-remote-commands.md)
# 设置 Run Command
必须先为将运行命令的用户配置 AWS Identity and Access Management（IAM）策略，然后才能使用 Run Command（AWS Systems Manager 中的一项工具）管理节点。如果您在 IAM 策略中使用任何全局条件键执行 `SendCommand` 操作，则必须包含 `aws:ViaAWSService` 条件键并将布尔值设置为 `true`。示例如下：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/YourDocument"
],
"Condition": {
"StringEquals": {
"aws:SourceVpce": [
"vpce-1234567890abcdef0"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/YourDocument"
],
"Condition": {
"Bool": {
"aws:ViaAWSService": "true"
}
}
}
]
}
```
------
您还必须为 Systems Manager 配置节点。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
我们建议您完成以下可选设置任务，以帮助最大限度地改善托管式节点的安保状况并尽量减少节点的日常管理工作。
使用 Amazon EventBridge 监控命令执行情况
您可以使用 Eventbridge 记录命令执行状态更改。您可以创建一个规则，只要状态发生变换或者在变换到一个或多个感兴趣的状态时，就运行该规则。此外，您还可以将 Run Command 指定为发生 EventBridge 事件时的目标操作。有关更多信息，请参阅 [为 Systems Manager 事件配置 EventBridge](monitoring-systems-manager-events.md)。
使用 Amazon CloudWatch Logs 监控命令执行情况
您可以将 Run Command 配置为定期将所有命令输出和错误日志发送到 Amazon CloudWatch 日志组。您可以近乎实时地监控这些输出日志，搜索特定短语、值或模式，以及基于搜索创建警报。有关更多信息，请参阅 [为 Run Command 配置 Amazon CloudWatch Logs](sysman-rc-setting-up-cwlogs.md)。
限制对特定托管式节点的 Run Command 访问
您可以通过使用 AWS Identity and Access Management (IAM) 来限制用户在托管式节点上运行命令的能力。特别是，您可以创建 IAM policy，其中包含一个条件，规定用户只能在使用特定标签标记的托管节点上运行命令。有关更多信息，请参阅 [根据标签限制 Run Command 访问](#tag-based-access)。
## 根据标签限制 Run Command 访问
本节介绍如何通过在 IAM policy 中指定标签条件来限制用户在托管式节点上运行命令的能力。托管式节点包括[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中为 Systems Manager 配置的 Amazon EC2 实例和非 EC2 节点。尽管没有明确显示相关信息，但您也可以限制对托管式 AWS IoT Greengrass 核心设备的访问。首先，您必须标记 AWS IoT Greengrass 设备。有关更多信息，请参阅 *AWS IoT Greengrass Version 2 开发人员指南*中的[标记 AWS IoT Greengrass Version 2 资源](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html)。
您可以通过创建一个 IAM policy 将命令执行限制到特定托管节点，该策略包括一个条件，规定用户只能在带有特定标签的节点上运行命令。在以下示例中，通过以下方式来允许用户使用 Run Command (`Effect: Allow, Action: ssm:SendCommand`)：在任何节点 (`Resource: arn:aws:ec2:*:*:instance/*`) 上使用任何 SSM 文档 (`Resource: arn:aws:ssm:*:*:document/*`)，条件是节点为 Finance WebServer (`ssm:resourceTag/Finance: WebServer`)。如果用户向未经标记或具有除 `Finance: WebServer` 以外的任何标签的节点发送命令，则执行结果将显示 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:*:*:document/*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ec2:*:*:instance/*"
],
"Condition":{
"StringLike":{
"ssm:resourceTag/Finance":[
"WebServers"
]
}
}
}
]
}
```
------
您可以创建允许用户在使用多个标签标记的托管式节点上运行命令的 IAM policy。以下策略允许用户在具有两个标签的托管式节点上运行命令。如果用户向未使用这两个标签标记的节点发送命令，则执行结果将显示 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
],
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}
```
------
您也可以创建允许用户在多个已标记托管式节点组上运行命令的 IAM policy。以下示例策略允许用户在任一已标记节点组或两个已标记节点组上运行命令。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key1":[
"tag_value1"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag_key2":[
"tag_value2"
]
}
}
},
{
"Effect":"Allow",
"Action":[
"ssm:SendCommand"
],
"Resource":[
"arn:aws:ssm:us-west-1::document/AWS-*",
"arn:aws:ssm:us-east-2::document/AWS-*"
]
},
{
"Effect":"Allow",
"Action":[
"ssm:UpdateInstanceInformation",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetDocument"
],
"Resource":"*"
}
]
}
```
------
有关创建 IAM policy 的更多信息，请参阅**《IAM 用户指南》中的[托管策略与内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html)。有关标记托管式节点的更多信息，请参阅 *AWS Resource Groups 用户指南*中的[标签编辑器](https://docs.aws.amazon.com/ARG/latest/userguide/tag-editor.html)。
# 在托管节点上运行命令
本节包括有关如何发送从 AWS Systems Manager 控制台到托管式节点的命令的信息。此部分还包括有关如何取消命令的信息。
请注意，如果节点为 var 目录配置了 `noexec` 挂载选项，Run Command 将无法成功运行命令。
**重要**
当您使用 Run Command 发送命令时，不要包含纯文本格式的敏感信息，例如密码、配置数据或其他密钥。您账户中的所有 Systems Manager API 活动都将记录在 AWS CloudTrail 日志的 S3 存储桶中。这意味着任何有权访问该 Amazon S3 存储桶的用户都能够查看这些密钥的纯文本值。因此，我们建议您创建和使用 `SecureString` 参数，以便加密您在 Systems Manager 操作中使用的敏感数据。
有关更多信息，请参阅 [使用 IAM 策略限制对 Parameter Store 参数的访问](sysman-paramstore-access.md)。
**执行历史记录保留**
每个命令的历史记录最多可保留 30 天。此外，您可以在 Amazon Simple Storage Service 中存储所有日志文件的副本，或在 AWS CloudTrail 中保存所有 API 调用的审计跟踪。
**相关信息**
有关使用其他工具发送命令的信息，请参阅以下主题：
+ [演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用](walkthrough-powershell.md)或者 [AWS Tools for PowerShell Cmdlet 参考的 AWS Systems Manager 部分](https://docs.aws.amazon.com/powershell/latest/reference/items/AWS_Systems_Manager_cmdlets.html)中的示例。
+ [演练：将 AWS CLI 与 Run Command 结合使用](walkthrough-cli.md)或者 [SSM CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/ssm/)中的示例
**Topics**
+ [从控制台运行命令](running-commands-console.md)
+ [使用指令文档版本运行命令](run-command-version.md)
+ [大规模运行命令](send-commands-multiple.md)
+ [取消命令](cancel-run-command.md)
# 从控制台运行命令
在不必登录的情况下，可以通过 AWS 管理控制台使用 Run Command（AWS Systems Manager 中的一项工具）配置托管式节点。此主题包括演示如何使用 Run Command 在托管式节点上[更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample) 的示例。
**开始前的准备工作**
在使用 Run Command 发送命令之前，请确认托管式节点符合 Systems Manager [设置要求](systems-manager-setting-up-nodes.md)。
**使用 Run Command 发送命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在**命令文档**列表中，请选择 Systems Manager 文档。
1. 在 **Command parameters (命令参数)** 部分中，为必需的参数指定值。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）选择一个 CloudWatch 警报以应用于您的命令进行监控。要将 CloudWatch 警报附加到命令，运行命令的 IAM 主体必须具有 `iam:createServiceLinkedRole` 操作的权限。有关 CloudWatch 警报的更多信息，请参阅[使用 Amazon CloudWatch 警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。请注意，如果您的警报激活，任何待处理的命令调用都不会运行。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
有关取消命令的信息，请参阅 [取消命令](cancel-run-command.md)。
## 重新运行命令
Systems Manager 包含两个选项，可帮助您从 Systems Manager 控制台中的 **Run Command** 页面重新运行命令。
+ **Rerun (重新运行)**：利用此按钮，您可以运行同一个命令而不对其进行更改。
+ **复制到新项目**：此按钮将一个命令的设置复制到一个新命令，并为您提供在运行该命令之前编辑这些设置的选项。
**重新运行命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择要重新运行的命令。从命令详细信息页面执行命令后，可以立即重新运行此命令。或者，您可以从 **Command history (命令历史记录)** 选项卡中选择先前运行的命令。
1. 选择 **Rerun (重新运行)** 以在不进行更改的情况下运行相同的命令，或者选择**复制到新项目**以在运行命令之前编辑命令设置。
# 使用指令文档版本运行命令
您可以使用文档版本参数指定在运行命令时使用 AWS Systems Manager 文档的哪个版本。您可以为此参数指定以下选项之一：
+ \$1DEFAULT
+ \$1LATEST
+ 版本号
运行以下过程，使用文档版本参数运行命令。
------
#### [ Linux ]
**在本地 Linux 计算机上使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
aws ssm list-document-versions \
--name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--parameters commands="echo Hello" \
--instance-ids instance-ID \
--document-version '$LATEST'
```
------
#### [ Windows ]
**在本地 Windows 计算机上使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
aws ssm list-document-versions ^
--name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm send-command ^
--document-name "AWS-RunShellScript" ^
--parameters commands="echo Hello" ^
--instance-ids instance-ID ^
--document-version "$LATEST"
```
------
#### [ PowerShell ]
**要使用 Tools for PowerShell 运行命令，请执行以下步骤：**
1. 如果您尚未安装和配置 AWS Tools for PowerShell（适用于 Windows PowerShell 的工具），请执行这些操作。
有关信息，请参阅[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 列出所有可用文档
此命令将基于 AWS Identity and Access Management (IAM) 权限列出您的账户可用的所有文档。
```
Get-SSMDocumentList
```
1. 运行以下命令，查看文档的不同版本。将*文档名称*替换为您自己的信息。
```
Get-SSMDocumentVersionList `
-Name "document name"
```
1. 运行以下命令，运行使用 SSM 文档版本的命令。将每个*示例资源占位符*替换为您自己的信息。
```
Send-SSMCommand `
-DocumentName "AWS-RunShellScript" `
-Parameter @{commands = "echo helloWorld"} `
-InstanceIds "instance-ID" `
-DocumentVersion $LATEST
```
------
# 大规模运行命令
您可以使用 Run Command（AWS Systems Manager 中的一项工具）通过使用 `targets` 在托管式节点实例集上运行命令。`targets` 参数根据您为托管式节点指定的标签接受 `Key,Value` 组合。当您运行该命令时，系统会找到并尝试在匹配指定标签的所有托管式节点上运行命令。有关标记托管式实例的更多信息，请参阅《Tagging AWS Resources User Guide》**中的 [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html)。有关标记托管式 IoT 设备的信息，请参阅 *AWS IoT Greengrass Version 2 开发人员指南*中的[标记 AWS IoT Greengrass Version 2 资源](https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html)。
您也可以使用 `targets` 参数将特定托管式节点 ID 的列表设为目标，如下一部分中所述。
为控制数百个或数千个托管式节点的命令运行，Run Command 还包含一些参数，用于限制同时处理一个请求的节点数量以及取消命令前其可引发的错误数量。
**Topics**
+ [将多个托管式节点设为目标](#send-commands-targeting)
+ [使用速率控制](#send-commands-rate)
## 将多个托管式节点设为目标
您可以通过指定标签、AWS 资源组名称或托管式节点 ID 来运行命令并将托管式节点设为目标。
以下示例显示使用 AWS Command Line Interface (AWS CLI ) 中的 Run Command 时的命令格式。将每个*示例资源占位符*替换为您自己的信息。本部分的示例命令使用 `[...]` 进行截断。
**示例 1：将标签设为目标**
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:tag-name,Values=tag-value \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:tag-name,Values=tag-value ^
[...]
```
------
示**例 2：通过名称将 AWS 资源组设为目标**
您最多可以为每个命令指定一个资源组名称。当您创建资源组时，我们建议您包含 `AWS::SSM:ManagedInstance` 和 `AWS::EC2::Instance` 作为分组条件中的资源类型。
**注意**
为发送将资源组设为目标的命令，您必须已获得列出或查看属于该组的资源的 AWS Identity and Access Management (IAM) 权限。有关更多信息，请参阅 *AWS Resource Groups 用户指南*中的[设置权限](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions)。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=resource-groups:Name,Values=resource-group-name \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=resource-groups:Name,Values=resource-group-name ^
[...]
```
------
**示例 3：通过资源类型将 AWS 资源组设为目标**
您最多可以为每个命令指定五个资源组类型。当您创建资源组时，我们建议您包含 `AWS::SSM:ManagedInstance` 和 `AWS::EC2::Instance` 作为分组条件中的资源类型。
**注意**
为了发送将资源组设为目标的命令，您必须已被授予列出或查看属于该组的资源的 IAM 权限。有关更多信息，请参阅 *AWS Resource Groups 用户指南*中的[设置权限](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html#gettingstarted-prereqs-permissions)。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 ^
[...]
```
------
**示例 4：将实例 ID 设为目标**
以下示例演示如何使用 `instanceids` 密钥和 `targets` 参数将托管式节点设为目标。您可以使用此密钥来将托管式 AWS IoT Greengrass 核心设备设为目标，因为每台设备分配到了 mi-*ID\$1NUMBER*。您可以在 Fleet Manager（AWS Systems Manager 中的一项工具）中查看设备 ID。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 ^
[...]
```
------
如果您使用名为 `Environment` 的 `Key`，以及 `Development`、`Test`、`Pre-production` 和 `Production` 的 `Values` 标记不同环境的托管式节点，则可以使用采用以下语法的 `targets` 参数，向其中*一个*环境的所有托管式节点发送命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Environment,Values=Development \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
------
通过添加到 `Values` 列表，您可以将其他环境中的其他托管式节点设为目标。使用逗号分隔项目。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Environment,Values=Development,Test,Pre-production \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Environment,Values=Development,Test,Pre-production ^
[...]
```
------
**变体**：使用多个 `Key` 条件细化您的目标。
通过包括多个 `Key` 条件，您可以细化您的命令的目标数。如果包括多个 `Key` 条件，系统会将符合*所有*条件的托管式节点设为目标。以下命令会将标记为财务部门*和*标记为数据库服务器角色的所有托管式节点设为目标。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database ^
[...]
```
------
**变体**：使用多个 `Key` 和 `Value` 条件
对上一个示例进行扩展，您可以通过在 `Values` 条件中包括其他项目来将多个部门和多个服务器角色设为目标。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
[...]
```
------
**变体**：使用多个 `Values` 条件将已标记托管式节点设为目标
如果您使用名为 `Department` 的 `Key`，以及 `Sales` 和 `Finance` 的 `Values` 标记不同环境的托管式节点，则可以使用采用以下语法的 `targets` 参数，向这些环境的所有节点发送命令。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values=Sales,Finance \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values=Sales,Finance ^
[...]
```
------
您最多可以为每个键指定五个键和五个值。
如果某个标签密钥（标签名称）或某个标签值包含空格，则需要将该标签密钥或该值用引号引起来，如以下示例所示。
**示例**： `Value` 标签中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:OS,Values="Windows Server 2016" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:OS,Values="Windows Server 2016" ^
[...]
```
------
**示例**： `tag` 键和 `Value` 中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key="tag:Operating System",Values="Windows Server 2016" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key="tag:Operating System",Values="Windows Server 2016" ^
[...]
```
------
**示例**：`Values` 的列表中一个项目中的空格
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" ^
[...]
```
------
## 使用速率控制
您可以使用*并发控件*和*错误控件*，控制将命令发送到组中托管式节点的速率。
**Topics**
+ [使用并发控件](#send-commands-velocity)
+ [使用错误控件](#send-commands-maxerrors)
### 使用并发控件
您可以使用 `max-concurrency` 参数 [**Run a command**（运行命令）页面中的 **Concurrency**（并发）选项] 来控制同时运行命令的托管式节点数量。您可以指定绝对数量的托管式节点（例如 **10**），也可以指定目标集百分比（例如 **10%**）。队列系统将命令传递给单个节点，并等待系统确认了初始调用，再将命令发送到两个或更多节点。系统以指数增长方式将命令发送到更多节点，直到系统达到 `max-concurrency` 值。`max-concurrency` 值默认为 50。下列示例介绍如何为 `max-concurrency` 参数指定值。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 10 \
--targets Key=tag:Environment,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 10% \
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 10 ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 10% ^
--targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
[...]
```
------
### 使用错误控件
您也可以使用 `max-errors` 参数 [**Run a command**（运行命令）页面中的 **Error threshold**（错误阈值）字段] 设置错误限制，将命令的执行控制在几百个或几千个托管式节点范围内。该参数指定系统停止向其他托管式节点发送命令之前所允许的错误数。您可以指定绝对数量的错误（例如 **10**），也可以指定目标集百分比（例如 **10%**）。例如，如果您指定 **3**，系统将在收到第四个错误时停止发送命令。如果您指定 **0**，则系统会在返回第一个错误结果后停止向其他托管式节点发送命令。如果您向 50 个托管式节点发送命令并将 `max-errors` 设置为 **10%**，则系统会在收到第六个错误时停止向其他节点发送命令。
当达到 `max-errors` 时，允许完成已经运行命令的调用，但是其中一些调用也可能失败。如果您需要确保失败的调用数不超过 `max-errors`，请将 `max-concurrency` 设置为 **1**，以便一次进行一个调用。max-errors 默认为 0。下列示例介绍如何为 `max-errors` 参数指定值。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name document-name \
--max-errors 10 \
--targets Key=tag:Database,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-errors 10% \
--targets Key=tag:Environment,Values=Development \
[...]
```
```
aws ssm send-command \
--document-name document-name \
--max-concurrency 1 \
--max-errors 1 \
--targets Key=tag:Environment,Values=Production \
[...]
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name document-name ^
--max-errors 10 ^
--targets Key=tag:Database,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-errors 10% ^
--targets Key=tag:Environment,Values=Development ^
[...]
```
```
aws ssm send-command ^
--document-name document-name ^
--max-concurrency 1 ^
--max-errors 1 ^
--targets Key=tag:Environment,Values=Production ^
[...]
```
------
# 取消命令
只要服务指明命令处于 Pending (待处理) 或 Executing (正在执行) 状态，您就可以尝试取消命令。但是，即使命令仍处于其中某种状态，我们也无法保证该命令将被取消并且基础流程将停止。
**使用控制台取消命令**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Run Command**。
1. 选择要取消的命令调用。
1. 选择**取消命令**。
**使用 AWS CLI 取消命令**
运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm cancel-command \
--command-id "command-ID" \
--instance-ids "instance-ID"
```
------
#### [ Windows ]
```
aws ssm cancel-command ^
--command-id "command-ID" ^
--instance-ids "instance-ID"
```
------
有关已取消命令的状态的信息，请参阅 [了解命令状态](monitor-commands.md)。
# 在命令中使用退出代码
在某些情况下，您可能需要使用退出代码管理处理命令的方式。
## 在命令中指定退出代码
使用 Run Command（AWS Systems Manager 中的一项工具），您可以指定退出代码来确定命令的处理方式。默认情况下，脚本中运行的最后一个命令的退出代码将报告为整个脚本的退出代码。例如，您有一个包含三个命令的脚本。第一个命令失败，但以下命令成功。由于最后一个命令成功，因此执行状态报告为 `succeeded`。
**Shell 脚本**
要在第一个命令失败时使整个脚本失败，您可以包含一个 shell 条件语句，以便在最后一个命令失败之前退出脚本。请使用以下方法。
```
if [ $? != 0 ]
then
exit
fi
```
在以下示例中，如果第一个命令失败，则整个脚本将失败。
```
cd /test
if [ $? != 0 ]
then
echo "Failed"
exit 1
fi
date
```
**PowerShell 脚本**
PowerShell 要求您在脚本中显式调用 `exit`，使 Run Command 能够成功捕获退出代码。
```
if ($?) {}
else {exit }
exit
```
示例如下：
```
cd C:\
if ($?) {echo "Success"}
else {exit 1}
date
```
# 运行命令时处理重启问题
如果使用 Run Command（AWS Systems Manager 中的一项工具）运行脚本来重启托管式节点，建议在脚本中指定退出代码。如果您使用其他一些机制尝试通过脚本重启节点，则即使重启是脚本的最后一步，脚本执行状态也可能无法正确更新。对于 Windows 托管式节点，您需在脚本中指定 `exit 3010`。对于 Linux 和 macOS 托管式节点，需要指定 `exit 194`。退出代码用于指示 AWS Systems Manager Agent (SSM Agent) 重启托管式节点，然后在重启完成后重新启动脚本。在重启开始之前，SSM Agent 会通知云中的 Systems Manager 服务，通信将在服务器重启期间中断。
**注意**
重启脚本不能作为 `aws:runDocument` 插件的一部分。如果一个文档包含重启脚本，另一个文档尝试通过 `aws:runDocument` 插件运行该文档，则 SSM Agent 会返回错误。
**创建幂等脚本**
在开发用于重启托管式节点的脚本时，使脚本具有幂等性，以便脚本执行在重启后从中断的位置继续进行。幂等脚本管理状态并验证是否执行了该操作。当一个步骤设定为仅运行一次时，可以防止该步骤多次运行。
以下是多次重启托管式节点的幂等脚本的概要示例。
```
$name = Get current computer name
If ($name –ne $desiredName)
{
Rename computer
exit 3010
}
$domain = Get current domain name
If ($domain –ne $desiredDomain)
{
Join domain
exit 3010
}
If (desired package not installed)
{
Install package
exit 3010
}
```
**示例**
以下脚本示例使用退出代码来重新启动托管式节点。Linux 示例在 Amazon Linux 上安装软件包更新，然后重新启动该节点。Windows Server 示例在节点上安装 Telnet-Client，然后重新启动该节点。
------
#### [ Amazon Linux 2 ]
```
#!/bin/bash
yum -y update
needs-restarting -r
if [ $? -eq 1 ]
then
exit 194
else
exit 0
fi
```
------
#### [ Windows ]
```
$telnet = Get-WindowsFeature -Name Telnet-Client
if (-not $telnet.Installed)
{
# Install Telnet and then send a reboot request to SSM Agent.
Install-WindowsFeature -Name "Telnet-Client"
exit 3010
}
```
------
# 了解命令状态
Run Command 是 AWS Systems Manager 中的一项工具，报告关于处理过程中命令经历的不同状态以及处理该命令的每个托管式节点的详细状态信息。您可以使用以下方法监控命令状态：
+ 在 Run Command 控制台界面的 **Commands**（命令）选项卡上选择 **Refresh**（刷新）图标。
+ 使用 AWS Command Line Interface (AWS CLI) 调用 [list-commands](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-commands.html) 或 [list-command-invocations](https://docs.aws.amazon.com/cli/latest/reference/ssm/list-command-invocations.html)。或者，使用 AWS Tools for Windows PowerShell 调用 [Get-SSMCommand](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommand.html) 或 [Get-SSMCommandInvocation](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMCommandInvocation.html)。
+ 配置 Amazon EventBridge 以响应状态或状态更改。
+ 将 Amazon Simple Notification Service (Amazon SNS) 配置为发送所有状态更改或特定状态（例如 `Failed` 或 `TimedOut`）的通知。
## Run Command 状态
Run Command 报告以下三个区域的状态详情：插件、调用和总体命令状态。*插件*是在命令的 SSM 文档中定义的代码执行数据块。有关插件的更多信息，请参阅 [命令文档插件参考](documents-command-ssm-plugin-reference.md)。
在将一条命令同时发送给多个托管式节点时，针对每个节点的命令的每个副本均为一个*命令调用*。例如，如果您使用 `AWS-RunShellScript` 文档并将一个 `ifconfig` 命令发送到 20 个 Linux 实例，则该命令具有 20 个调用。每个命令调用都会单独报告状态。给定命令调用的插件也会单独报告状态。
最后，Run Command 包含适用于所有插件和调用的聚合命令状态。聚合命令状态可能不同于插件或调用报告的状态，如下表所述。
**注意**
如果您使用 `max-concurrency` 或 `max-errors` 参数在大量托管式节点上运行命令，则命令状态会反映这些参数施加的限制，如下表所述。有关这些参数的更多信息，请参阅 [大规模运行命令](send-commands-multiple.md)。
**命令插件和调用的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 命令尚未发送到托管式节点，或者 SSM Agent 尚未接收到此类命令。如果代理在等于 Timeout (seconds) (超时 (秒)) 参数和 Execution timeout (执行超时) 参数总和的时间长度之前没有收到命令，则状态将更改为 Delivery Timed Out (传输超时)。 |
| InProgress | Systems Manager 正在尝试将命令发送到托管式节点，或者 SSM Agent 已接收到此类命令并且命令已开始在实例上运行。根据所有命令插件的结果，状态会变为 Success (成功)、Failed (失败)、Delivery Timed Out (传输超时) 或 Execution Timed Out (执行超时)。例外：如果代理未在节点上运行或在节点上不可用，则在代理再次可用或达到执行超时限制之前，命令状态将保持为 In Progress（正在进行）。随后，状态会更改为最终状态。 |
| 延迟 | 系统尝试向托管式节点发送命令，但未成功。系统再次重试。 |
| 成功 | 在各种条件下都会返回此状态。此状态并不意味着命令已在节点上得到处理。例如，由于您的 PowerShell ExecutionPolicy 阻止命令运行，因此在托管式节点上，SSM Agent 可接收到命令，而且命令返回为零的退出代码。这是最终状态。导致命令返回 Success 状态的条件是：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/monitor-commands.html) 当以资源组为目标时，同样的条件也适用。要解决错误或获取有关命令执行的更多信息，请通过返回适当的退出代码 (针对命令失败的非零退出代码) 来发送一个处理错误或异常的命令。 |
| DeliveryTimedOut | 命令未在总超时过期之前传输到托管式节点。总超时不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success（成功）、Incomplete（未完成）还是 Delivery Timed Out（传输超时）。这是最终状态。 |
| ExecutionTimedOut | 命令自动化在托管式节点上开始，但是命令未在执行超时过期之前完成。执行超时算作失败，这样就会发送一个非零回复，Systems Manager 将退出运行命令自动化的尝试，并报告失败状态。 |
| 失败 | 托管式节点上的命令失败。对于插件，这表示结果代码不为 0。对于命令调用，这表示一个或多个插件的结果代码不为 0。调用失败不计入父命令的 max-errors 限制。这是最终状态。 |
| 已取消 | 命令在完成之前被取消。这是最终状态。 |
| 无法传输 | 命令无法传输到托管式节点。节点可能不存在或可能未响应。无法传输的调用不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success (成功) 还是 Incomplete (未完成)。（例如，如果命令中的所有调用具有 Undeliverable (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Undeliverable (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
| 已终止 | 父命令超过其 max-errors 限制且系统取消了后续命令调用。这是最终状态。 |
| InvalidPlatform | 命令被发送到与所选文档指定的所需平台不匹配的托管式节点。Invalid Platform（无效平台）不计入父命令的最大错误数限制，但是有助于区别父命令的状态是 Success（成功）还是 Failed（失败）。（例如，如果命令中的所有调用具有 Invalid Platform (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Invalid Platform (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
| AccessDenied | 启动命令的 AWS Identity and Access Management (IAM) 用户或角色无权访问目标托管式节点。Access Denied（拒绝访问）不计入父命令的 max-errors（最大错误数）限制，但是有助于区别父命令的状态是 Success（成功）还是 Failed（失败）。（例如，如果命令中的所有调用具有 Access Denied (无法传输) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 Access Denied (无法传输) 状态，一个调用返回 Success (成功) 状态，则父命令的状态为 Success (成功)。这是最终状态。 |
**命令的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 任何托管式节点上的代理都尚未收到命令。 |
| InProgress | 命令已发送到至少一个托管式节点，但是在所有节点上都未达到最终状态。 |
| 延迟 | 系统尝试向节点发送命令，但未成功。系统再次重试。 |
| 成功 | 命令由所有指定的或设为目标的托管式节点上的 SSM Agent 接收，并返回了一个为零的退出代码。所有命令调用都已达到最终状态，且未达到 max-errors 的值。此状态并不意味着命令已在所有指定的或设为目标的托管式节点上成功得到处理。这是最终状态。 要解决错误或获取有关命令执行的更多信息，请通过返回适当的退出代码 (针对命令失败的非零退出代码) 来发送一个处理错误或异常的命令。 |
| DeliveryTimedOut | 命令未在总超时过期之前传输到托管式节点。max-errors 值或更多命令调用显示 Delivery Timed Out 状态。这是最终状态。 |
| 失败 | 托管式节点上的命令失败。`max-errors` 值或更多命令调用显示 `Failed` 状态。这是最终状态。 |
| 未完成 | 已尝试在所有托管式节点上执行命令，且一个或多个调用不具有 Success（成功）值。不过，调用失败的次数不足以使状态变为 Failed。这是最终状态。 |
| 已取消 | 命令在完成之前被取消。这是最终状态。 |
| RateExceeded | 作为命令目标的托管式节点数量超出了待处理调用的账户配额。系统在任何节点上执行命令之前取消了命令。这是最终状态。 |
| AccessDenied | 启动命令的用户或角色无权访问目标资源组。AccessDenied 不计入父命令的 max-errors 限制，但是有助于区别父命令的状态是 Success 还是 Failed。（例如，如果命令中的所有调用具有 AccessDenied (拒绝访问) 状态，则返回的命令状态为 Failed (失败)。不过，如果命令具有 5 个调用，其中的 4 个调用返回 AccessDenied (拒绝访问) 状态，1 个调用返回 Success (成功) 状态，则父命令的状态为 Success(成功)。） 这是最终状态。 |
| 在标签中没有实例 | 作为命令目标的标签密钥对值或资源组与任何托管式节点都不匹配。这是最终状态。 |
## 了解命令超时值
在运行命令时，Systems Manager 强制执行以下超时值。
**总超时**
在 Systems Manager 控制台中，您可以在 **Timeout (seconds)**（超时（秒））字段中指定超时值。发送命令后，Run Command 会检查命令是否已过期。如果命令达到命令过期限制（总超时），它会将所有状态为 `InProgress` (正在进行)、`Pending` (待处理) 或 `Delayed` (延迟) 的调用的状态更改为 `DeliveryTimedOut` (传输超时)。
![\[Systems Manager 控制台中的 Timeout (seconds) (超时 (秒)) 字段\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/run-command-delivery-time-out-time-out-seconds.png)
在更深的技术层面上，总超时（**Timeout (seconds)**（超时（秒）））是两个超时值的总和，如下所示：
`Total timeout = "Timeout(seconds)" from the console + "timeoutSeconds": "{{ executionTimeout }}" from your SSM document`
例如，在 Systems Manager 控制台中，**Timeout (seconds) (超时 (秒))** 的默认值是 600 秒。如果使用 `AWS-RunShellScript` SSM 文档运行命令，则 **"timeoutSeconds": "\$1\$1 executionTimeout \$1\$1"** 的默认值为 3600 秒，如以下示例文档所示：
```
"executionTimeout": {
"type": "String",
"default": "3600",
"runtimeConfig": {
"aws:runShellScript": {
"properties": [
{
"timeoutSeconds": "{{ executionTimeout }}"
```
这意味着，在系统将命令状态设置为 `DeliveryTimedOut` 之前，该命令运行了 4200 秒（70 分钟）。
**执行超时**
在 Systems Manager 控制台中，您可以在 **Execution Timeout (执行超时)** 字段中指定执行超时值（如果可用）。并非所有 SSM 文档都要求指定执行超时值。**Execution Timeout**（执行超时）字段仅在 SSM 文档中定义了相应的输入参数时才会显示。如果已指定该值，则命令必须在此时段内完成。
**注意**
Run Command 依靠 SSM Agent 文档最终响应来确定命令是否已传输给代理。SSM Agent 必须发送一个 `ExecutionTimedOut` 信号，才能将调用或命令标记为 `ExecutionTimedOut`。
![\[Systems Manager 控制台中的 Execution Timeout (执行超时) 字段\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/run-command-execution-timeout-console.png)
**默认执行超时**
如果 SSM 文档不要求您明确指定执行超时值，则 Systems Manager 会强制执行硬编码的默认执行超时。
**Systems Manager 如何报告超时**
如果 Systems Manager 收到来自目标上的 SSM Agent 的 `execution timeout` 回复，则 Systems Manager 会将命令调用标记为 `executionTimeout`。
如果 Run Command 没有收到 SSM Agent 文档最终响应，则命令调用被标记为 `deliveryTimeout`。
为了确定目标的超时状态，SSM Agent 将合并 SSM 文档的所有参数和内容来计算 `executionTimeout`。如果 SSM Agent 确定某条命令已超时，它会向服务发送 `executionTimeout`。
**Timeout (seconds) (超时 (秒))** 的默认值为 3600 秒。**Execution Timeout (执行超时)** 的默认值也为 3600 秒。因此，命令的总超时默认为 7200 秒。
**注意**
SSM Agent 采用不同的方式处理 `executionTimeout`，具体取决于 SSM 文档的类型和文档版本。
# Run Command 演练
本节中的演练说明如何借助 AWS Command Line Interface（AWS CLI）或 AWS Tools for Windows PowerShell，使用 Run Command（AWS Systems Manager 中的一项工具）来运行命令。
**Topics**
+ [使用 Run Command 更新软件](run-command-tutorial-update-software.md)
+ [演练：将 AWS CLI 与 Run Command 结合使用](walkthrough-cli.md)
+ [演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用](walkthrough-powershell.md)
您还可以查看以下参考中的示例命令。
+ [Systems Manager AWS CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/ssm/)
+ [AWS Tools for Windows PowerShell - AWS Systems Manager](https://docs.aws.amazon.com/powershell/latest/reference/items/SimpleSystemsManagement_cmdlets.html)
# 使用 Run Command 更新软件
以下步骤说明如何在托管节点上更新软件。
## 使用 Run Command 更新 SSM Agent
以下过程介绍如何更新在托管式节点上运行的 SSM Agent。您可以更新到最新版本的 SSM Agent 或降级到较旧版本。在运行命令时，系统将从 AWS 下载并安装需要的版本，然后卸载运行命令前存在的版本。如果此过程中出现错误，系统将回滚到命令运行之前服务器上的版本，并且命令状态将显示命令失败。
**注意**
如果实例运行 macOS 版本 13.0（Ventura）或更高版本，则该实例必须带有 SSM Agent 版本 3.1.941.0 或更高版本才能运行 AWS-UpdateSSMAgent 文档。如果实例运行 3.1.941.0 之前发布的 SSM Agent 版本，那么您可以通过运行 `brew update` 和 `brew upgrade amazon-ssm-agent` 命令来更新 SSM Agent，从而运行 AWS-UpdateSSMAgent 文档。
要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。
**使用 Run Command 更新 SSM Agent**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在 **Command document** (命令文档) 列表中，请选择 **`AWS-UpdateSSMAgent`**。
1. 在**命令参数**部分中，根据需要为以下参数指定值：
1. （可选）对于 **Version (版本)**，输入要安装的 SSM Agent 的版本。您可以安装代理的[较旧版本](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)。如果您不指定版本，则服务将安装最新版本。
1. （可选）对于 **Allow Downgrade (允许降级)**，选择 **true (真)** 以安装 SSM Agent的早期版本。如果选择此选项，需要指定[较早](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)的版本号。选择 **false** 以仅安装此服务的最新版本。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
## 使用 Run Command 更新 PowerShell
以下过程介绍如何在 Windows Server 2012 和 2012 R2 托管式节点上将 PowerShell 更新到版本 5.1。此过程中提供的脚本将下载 Windows 管理框架 (WMF) 5.1 版更新，并开始安装此更新。在此过程中，节点会重启，因为在安装 WMF 5.1 时要求这么做。完成下载和安装更新大约需要 5 分钟。
**要使用 Run Command 更新 PowerShell，请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Run Command**。
1. 选择 **Run command（运行命令）**。
1. 在 **Command document**（命令文档）列表中，请选择 **`AWS-RunPowerShellScript`**。
1. 在 **Commands (命令)** 部分中，粘贴以下适用于您的操作系统的命令。
------
#### [ Windows Server 2012 R2 ]
```
Set-Location -Path "C:\Windows\Temp"
Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839516" -OutFile "Win8.1AndW2K12R2-KB3191564-x64.msu"
Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('Win8.1AndW2K12R2-KB3191564-x64.msu', '/quiet')
```
------
#### [ Windows Server 2012 ]
```
Set-Location -Path "C:\Windows\Temp"
Invoke-WebRequest "https://go.microsoft.com/fwlink/?linkid=839513" -OutFile "W2K12-KB3191565-x64.msu"
Start-Process -FilePath "$env:systemroot\system32\wusa.exe" -Verb RunAs -ArgumentList ('W2K12-KB3191565-x64.msu', '/quiet')
```
------
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
1. 对于 **Other parameters（其他参数）**：
+ 对于 **Comment（注释）**，请输入有关此命令的信息。
+ 对于 **Timeout (seconds) (超时 (秒))**，请指定在整个命令执行失败之前系统等待的秒数。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **输出选项**，要将命令输出保存到文件，请选中 **将命令输出写入 S3 存储桶** 框。在输入框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给实例的实例配置文件（适用于 EC2 实例）或 IAM 服务角色（混合激活的计算机）的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确保与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 在 **SNS 通知**部分，如果需要发送有关命令执行状态的通知，请选中 **Enable SNS notifications（启用 SNS 通知）**复选框。
有关为 Run Command 配置 Amazon SNS 通知的更多信息，请参阅 [使用 Amazon SNS 通知监控 Systems Manager 状态更改](monitoring-sns-notifications.md)。
1. 选择 **Run（运行）**。
在托管式节点重启且更新安装完成后，连接到您的节点，以确认 PowerShell 已成功升级到版本 5.1。要检查您的节点上的 PowerShell 版本，打开 PowerShell 并输入 `$PSVersionTable`。如果升级成功，输出表中的 `PSVersion` 值将显示为 5.1。
如果 `PSVersion` 值不是 5.1（例如 3.0 或 4.0），请在事件查看器中查看 **Windows Logs (Windows 日志)** 下的 **Setup (设置)** 日志。这些日志说明了更新安装失败的原因。
# 演练：将 AWS CLI 与 Run Command 结合使用
以下示例演练介绍了如何使用 AWS Command Line Interface (AWS CLI) 查看有关命令和命令参数的信息、如何运行命令以及如何查看这些命令的状态。
**重要**
仅允许受信任的管理员使用本主题中所示的 AWS Systems Manager 预配置文档。在 Systems Manager 文档中指定的命令和脚本需要管理权限才能在您的托管式节点上运行。如果用户有权运行任何预定义的 Systems Manager 文档（任何以 `AWS-` 开头的文档），则该用户也具有节点的管理员访问权限。对于所有其他用户，您应创建限制性文档并与特定用户共享这些文档。
**Topics**
+ [步骤 1：入门](#walkthrough-cli-settings)
+ [步骤 2：运行 Shell 脚本以查看资源详细信息](#walkthrough-cli-run-scripts)
+ [步骤 3：使用 `AWS-RunShellScript` 文档发送简单命令](#walkthrough-cli-example-1)
+ [步骤 4：使用 Run Command 运行简单 Python 脚本](#walkthrough-cli-example-2)
+ [步骤 5：使用 Run Command 运行 Bash 脚本](#walkthrough-cli-example-3)
## 步骤 1：入门
您必须具有要配置的托管式节点的管理员权限，或必须已获得 AWS Identity and Access Management (IAM) 中的适当权限。另请注意，此示例使用美国东部（俄亥俄州）区域（us-east-2）。Run Command 在《Amazon Web Services 一般参考》**的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 列出的 AWS 区域 中可用。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
**使用 AWS CLI 运行命令**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 列出所有可用文档。
此命令将基于 IAM 权限列出您的账户可用的所有文档。
```
aws ssm list-documents
```
1. 确认托管式节点已准备好接收命令。
以下命令的输出会显示托管式节点是否处于联机状态。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-information \
--output text --query "InstanceInformationList[*]"
```
------
#### [ Windows ]
```
aws ssm describe-instance-information ^
--output text --query "InstanceInformationList[*]"
```
------
1. 运行以下命令来查看有关特定托管式节点的详细信息。
**注意**
要运行本演练中的命令，请替换实例和命令 ID。对于托管式 AWS IoT Greengrass 核心设备，对实例 ID 使用 mi-*ID\$1NUMBER*。命令 ID 将作为对 **send-command** 的响应返回。可从 Fleet Manager（AWS Systems Manager 中的一项工具）中获得实例 ID。
------
#### [ Linux & macOS ]
```
aws ssm describe-instance-information \
--instance-information-filter-list key=InstanceIds,valueSet=instance-ID
```
------
#### [ Windows ]
```
aws ssm describe-instance-information ^
--instance-information-filter-list key=InstanceIds,valueSet=instance-ID
```
------
## 步骤 2：运行 Shell 脚本以查看资源详细信息
利用 Run Command 和 `AWS-RunShellScript` 文档，您可以在托管式节点上运行任何命令或脚本，就像您已在本地登录一样。
**查看说明和可用参数**
运行以下命令，查看 Systems Manager JSON 文档的描述。
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name "AWS-RunShellScript" \
--query "[Document.Name,Document.Description]"
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name "AWS-RunShellScript" ^
--query "[Document.Name,Document.Description]"
```
------
运行以下命令，查看可用参数和有关这些参数的详细信息。
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name "AWS-RunShellScript" \
--query "Document.Parameters[*]"
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name "AWS-RunShellScript" ^
--query "Document.Parameters[*]"
```
------
## 步骤 3：使用 `AWS-RunShellScript` 文档发送简单命令
运行以下命令，获取 Linux 托管式节点的 IP 信息。
如果您将 Windows Server 托管式节点设为目标，请将 `document-name` 更改为 `AWS-RunPowerShellScript`，并将 `command` 从 `ifconfig` 更改为 `ipconfig`。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "IP config" \
--parameters commands=ifconfig \
--output text
```
------
#### [ Windows ]
```
aws ssm send-command ^
--instance-ids "instance-ID" ^
--document-name "AWS-RunShellScript" ^
--comment "IP config" ^
--parameters commands=ifconfig ^
--output text
```
------
**使用响应数据获取命令信息**
以下命令使用从上一个命令返回的命令 ID 来获取命令执行的详细信息和响应数据。如果命令已完成，系统将返回响应数据。如果命令执行显示 `"Pending"` 或 `"InProgress"`，您再次运行此命令来查看响应数据。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--command-id $sh-command-id \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--command-id $sh-command-id ^
--details
```
------
**标识用户**
以下命令将显示运行命令的默认用户。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux managed node" \
--parameters commands=whoami \
--output text \
--query "Command.CommandId")
```
------
**获取命令状态**
以下命令使用命令 ID 获取托管式节点上的命令执行状态。此示例使用上一个命令中返回的命令 ID。
------
#### [ Linux & macOS ]
```
aws ssm list-commands \
--command-id "command-ID"
```
------
#### [ Windows ]
```
aws ssm list-commands ^
--command-id "command-ID"
```
------
**获取命令详细信息**
以下命令使用上一命令中的命令 ID 来获取每个托管式节点的命令执行状态。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--command-id "command-ID" \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--command-id "command-ID" ^
--details
```
------
**获取包含特定托管式节点的响应数据的命令信息**
以下命令会返回特定托管式节点的原始 `aws ssm send-command` 请求的输出。
------
#### [ Linux & macOS ]
```
aws ssm list-command-invocations \
--instance-id instance-ID \
--command-id "command-ID" \
--details
```
------
#### [ Windows ]
```
aws ssm list-command-invocations ^
--instance-id instance-ID ^
--command-id "command-ID" ^
--details
```
------
**显示 Python 版本**
以下命令会返回在节点上运行的 Python 的版本。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux Instances" \
--parameters commands='python -V' \
--output text --query "Command.CommandId") \
sh -c 'aws ssm list-command-invocations \
--command-id "$sh_command_id" \
--details \
--query "CommandInvocations[].CommandPlugins[].{Status:Status,Output:Output}"'
```
------
## 步骤 4：使用 Run Command 运行简单 Python 脚本
以下命令使用 Run Command 运行一个简单的 Python“Hello World”脚本。
------
#### [ Linux & macOS ]
```
sh_command_id=$(aws ssm send-command \
--instance-ids "instance-ID" \
--document-name "AWS-RunShellScript" \
--comment "Demo run shell script on Linux Instances" \
--parameters '{"commands":["#!/usr/bin/python","print \"Hello World from python\""]}' \
--output text \
--query "Command.CommandId") \
sh -c 'aws ssm list-command-invocations \
--command-id "$sh_command_id" \
--details \
--query "CommandInvocations[].CommandPlugins[].{Status:Status,Output:Output}"'
```
------
## 步骤 5：使用 Run Command 运行 Bash 脚本
此部分中的示例演示如何使用 Run Command 运行以下 Bash 脚本。
有关使用 Run Command 运行存储在远程位置的脚本的示例，请参阅[从 Amazon S3 运行脚本](integration-s3.md)和[从 GitHub 运行脚本](integration-remote-scripts.md)。
```
#!/bin/bash
yum -y update
yum install -y ruby
cd /home/ec2-user
curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install
chmod +x ./install
./install auto
```
此脚本将在 Amazon Linux 和 Red Hat Enterprise Linux (RHEL) 实例上安装 AWS CodeDeploy 代理，如《AWS CodeDeploy 用户指南》中的[为 CodeDeploy 创建 Amazon EC2 实例](https://docs.aws.amazon.com/codedeploy/latest/userguide/instances-ec2-create.html)所述。**
该脚本将从 AWS 托管的 S3 存储桶安装 CodeDeploy 代理程序，该存储桶位于美国东部（俄亥俄州）区域（us-east-2）（`aws-codedeploy-us-east-2`）。
**在 AWS CLI 命令中运行 Bash 脚本**
以下示例演示了如何使用 `--parameters` 选项在 CLI 命令中包含 Bash 脚本。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--targets '[{"Key":"InstanceIds","Values":["instance-id"]}]' \
--parameters '{"commands":["#!/bin/bash","yum -y update","yum install -y ruby","cd /home/ec2-user","curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install","chmod +x ./install","./install auto"]}'
```
------
**在 JSON 文件中运行 Bash 脚本**
在以下示例中，Bash 脚本的内容存储在一个 JSON 文件中，该文件通过使用 `--cli-input-json` 选项包含在命令中。
------
#### [ Linux & macOS ]
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--targets "Key=InstanceIds,Values=instance-id" \
--cli-input-json file://installCodeDeployAgent.json
```
------
#### [ Windows ]
```
aws ssm send-command ^
--document-name "AWS-RunShellScript" ^
--targets "Key=InstanceIds,Values=instance-id" ^
--cli-input-json file://installCodeDeployAgent.json
```
------
引用的 `installCodeDeployAgent.json` 文件的内容如以下示例所示。
```
{
"Parameters": {
"commands": [
"#!/bin/bash",
"yum -y update",
"yum install -y ruby",
"cd /home/ec2-user",
"curl -O https://aws-codedeploy-us-east-2.s3.amazonaws.com/latest/install",
"chmod +x ./install",
"./install auto"
]
}
}
```
# 演练：将 AWS Tools for Windows PowerShell 与 Run Command 结合使用
以下示例说明如何使用 AWS Tools for Windows PowerShell 查看有关命令和命令参数的信息、如何运行命令以及如何查看这些命令的状态。本演练为每个预定义的 AWS Systems Manager 文档包含了一个示例。
**重要**
仅允许受信任的管理员使用本主题中所示的 Systems Manager 预配置文档。在 Systems Manager 文档中指定的命令和脚本需要管理权限才能在您的托管式节点上运行。如果用户有权运行任何预定义的 Systems Manager 文档（任何以 AWS 开头的文档），则该用户也具有节点的管理员访问权限。对于所有其他用户，您应创建限制性文档并与特定用户共享这些文档。
**Topics**
+ [配置 AWS Tools for Windows PowerShell 会话设置](#walkthrough-powershell-settings)
+ [列出所有可用文档](#walkthrough-powershell-all-documents)
+ [运行 PowerShell 命令或脚本](#walkthrough-powershell-run-script)
+ [使用 `AWS-InstallApplication` 文档安装应用程序](#walkthrough-powershell-install-application)
+ [使用 `AWS-InstallPowerShellModule` JSON 文档安装 PowerShell 模块](#walkthrough-powershell-install-module)
+ [使用 `AWS-JoinDirectoryServiceDomain` JSON 文档将托管式节点加入域中](#walkthrough-powershell-domain-join)
+ [使用 `AWS-ConfigureCloudWatch` 文档将 Windows 指标发送到 Amazon CloudWatch Logs](#walkthrough-powershell-windows-metrics)
+ [使用 `AWS-ConfigureWindowsUpdate` 文档启用或关闭 Windows 自动更新](#walkthrough-powershell-enable-windows-update)
+ [使用 Run Command 管理 Windows 更新](#walkthough-powershell-windows-updates)
## 配置 AWS Tools for Windows PowerShell 会话设置
**指定您的凭证**
在本地计算机上打开 **Tools for Windows PowerShell** 并运行以下命令以指定您的凭证。您必须具有要配置的托管式节点的管理员权限，或必须已获得 AWS Identity and Access Management (IAM) 中的适当权限。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
```
Set-AWSCredentials –AccessKey key-name –SecretKey key-name
```
**设置默认 AWS 区域**
运行以下命令为 PowerShell 会话设置区域。此示例使用美国东部（俄亥俄州）区域（us-east-2）。Run Command 在《Amazon Web Services 一般参考》**的 [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) 列出的 AWS 区域 中可用。
```
Set-DefaultAWSRegion `
-Region us-east-2
```
## 列出所有可用文档
此命令将列出您的账户可用的所有文档。
```
Get-SSMDocumentList
```
## 运行 PowerShell 命令或脚本
利用 Run Command 和 `AWS-RunPowerShell` 文档，您可以在托管式节点上运行任何命令或脚本，就像您已在本地登录一样。您可以发出命令或输入本地脚本的路径以运行命令。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-RunPowerShellScript"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-RunPowerShellScript" | Select -ExpandProperty Parameters
```
### 使用 `AWS-RunPowerShellScript` 文档发送命令
以下命令在两个托管式节点上显示 `"C:\Users"` 目录的内容和 `"C:\"` 目录的内容。
```
$runPSCommand = Send-SSMCommand `
-InstanceIds @("instance-ID-1", "instance-ID-2") `
-DocumentName "AWS-RunPowerShellScript" `
-Comment "Demo AWS-RunPowerShellScript with two instances" `
-Parameter @{'commands'=@('dir C:\Users', 'dir C:\')}
```
**获取命令请求详细信息**
以下命令使用 `CommandId` 获取两个托管式节点上的命令执行状态。此示例使用上一个命令中返回的 `CommandId`。
```
Get-SSMCommand `
-CommandId $runPSCommand.CommandId
```
此示例中命令的状态可以是 Success、Pending 或 InProgress。
**获取每个托管式节点的命令信息**
以下命令使用上一命令中的 `CommandId` 来获取每个托管式节点的命令执行状态。
```
Get-SSMCommandInvocation `
-CommandId $runPSCommand.CommandId
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令会返回特定托管式节点的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $runPSCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
### 取消命令
以下命令取消 `AWS-RunPowerShellScript` 文档的 `Send-SSMCommand`。
```
$cancelCommand = Send-SSMCommand `
-InstanceIds @("instance-ID-1","instance-ID-2") `
-DocumentName "AWS-RunPowerShellScript" `
-Comment "Demo AWS-RunPowerShellScript with two instances" `
-Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'}
Stop-SSMCommand -CommandId $cancelCommand.CommandId
```
**查看命令状态**
以下命令检查 `Cancel` 命令的状态。
```
Get-SSMCommand `
-CommandId $cancelCommand.CommandId
```
## 使用 `AWS-InstallApplication` 文档安装应用程序
利用 Run Command 和 `AWS-InstallApplication` 文档，您可以在托管式节点上安装、修复或卸载应用程序。该命令需要 MSI 的路径或地址。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallApplication"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallApplication" | Select -ExpandProperty Parameters
```
### 使用 `AWS-InstallApplication` 文档发送命令
以下命令将以无人值守的模式在托管式节点上安装 Python 版本，并将输出记录在 `C:` 驱动器上的本地文本文件中。
```
$installAppCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallApplication" `
-Parameter @{'source'='https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi'; 'parameters'='/norestart /quiet /log c:\pythoninstall.txt'}
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $installAppCommand.CommandId `
-Details $true
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令返回 Python 安装的结果。
```
Get-SSMCommandInvocation `
-CommandId $installAppCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-InstallPowerShellModule` JSON 文档安装 PowerShell 模块
您可使用 Run Command 在托管式节点上安装 PowerShell 模块。有关 PowerShell 模块的更多信息，请参阅 [Windows PowerShell 模块](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_modules?view=powershell-6)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-InstallPowerShellModule" | Select -ExpandProperty Parameters
```
### 安装 PowerShell 模块
以下命令下载 EZOut.zip 文件，安装该文件，然后运行另一个命令来安装 XPS Viewer。最后，输出此命令将上传到一个名为“amzn-s3-demo-bucket”的 S3 存储桶中。
```
$installPSCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallPowerShellModule" `
-Parameter @{'source'='https://gallery.technet.microsoft.com/EZOut-33ae0fb7/file/110351/1/EZOut.zip';'commands'=@('Add-WindowsFeature -name XPS-Viewer -restart')} `
-OutputS3BucketName amzn-s3-demo-bucket
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $installPSCommand.CommandId `
-Details $true
```
**获取包含托管式节点的响应数据的命令信息**
以下命令返回特定 `CommandId` 的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $installPSCommand.CommandId `
-Details $true | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-JoinDirectoryServiceDomain` JSON 文档将托管式节点加入域中
借助 Run Command，您可以将托管式节点快速加入 AWS Directory Service 域中。执行此命令前，请[创建目录](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started_create_directory.html)。还建议您了解 Directory Service 的更多信息。有关更多信息，请参阅 [AWS Directory Service 管理指南](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/)。
您只能将托管式节点加入域中，无法从域中删除节点。
**注意**
有关在使用 Run Command 调用脚本时托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-JoinDirectoryServiceDomain"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-JoinDirectoryServiceDomain" | Select -ExpandProperty Parameters
```
### 将托管式节点加入域中
以下命令可将托管式节点加入给定的 Directory Service 域中，并将生成的任何输出上传至示例 Amazon Simple Storage Service（Amazon S3）存储桶。
```
$domainJoinCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-JoinDirectoryServiceDomain" `
-Parameter @{'directoryId'='d-example01'; 'directoryName'='ssm.example.com'; 'dnsIpAddresses'=@('192.168.10.195', '192.168.20.97')} `
-OutputS3BucketName amzn-s3-demo-bucket
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $domainJoinCommand.CommandId `
-Details $true
```
**获取包含托管式节点的响应数据的命令信息**
此命令返回特定 `CommandId` 的原始 `Send-SSMCommand` 的输出。
```
Get-SSMCommandInvocation `
-CommandId $domainJoinCommand.CommandId `
-Details $true | Select -ExpandProperty CommandPlugins
```
## 使用 `AWS-ConfigureCloudWatch` 文档将 Windows 指标发送到 Amazon CloudWatch Logs
您可以将应用程序、系统、安全和 Windows 事件跟踪 (ETW) 日志中的 Windows Server 消息发送到 Amazon CloudWatch Logs。在首次允许日志记录时，Systems Manager 会发送从您开始上传该应用程序、系统、安全和 ETW 日志时起一 (1) 分钟内生成的所有日志。其中不包括在此时间之前产生的日志。如果您关闭日志记录并在以后再次启用日志记录，Systems Manager 会从其上次停止的时间继续发送日志。对于任何自定义日志文件和 Internet Information Services (IIS) 日志，Systems Manager 会从头读取日志文件。此外，Systems Manager 还可以将性能计数器数据发送到 CloudWatch Logs。
如果先前在 EC2Config 中启用了 CloudWatch 集成，则 Systems Manager 设置会覆盖 `C:\Program Files\Amazon\EC2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json` 文件中本地存储在托管式节点上的任何设置。有关使用 EC2Config 管理单个托管式节点上的性能计数器和日志的更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[使用 CloudWatch 代理从 Amazon EC2 实例和本地服务器收集指标和日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureCloudWatch"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureCloudWatch" | Select -ExpandProperty Parameters
```
### 将应用程序日志发送到 CloudWatch
以下命令可配置托管式节点并将 Windows 应用程序日志移至 CloudWatch。
```
$cloudWatchCommand = Send-SSMCommand `
-InstanceID instance-ID `
-DocumentName "AWS-ConfigureCloudWatch" `
-Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"ApplicationEventLog", "FullName":"AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"LogName":"Application", "Levels":"7"}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters":{"Region":"region", "LogGroup":"my-log-group", "LogStream":"instance-id"}}], "Flows":{"Flows":["ApplicationEventLog,CloudWatch"]}}}'}
```
**获取每个托管式节点的命令信息**
以下命令使用 `CommandId` 获取命令执行的状态。
```
Get-SSMCommandInvocation `
-CommandId $cloudWatchCommand.CommandId `
-Details $true
```
**获取包含特定托管式节点的响应数据的命令信息**
以下命令返回 Amazon CloudWatch 配置的结果。
```
Get-SSMCommandInvocation `
-CommandId $cloudWatchCommand.CommandId `
-Details $true `
-InstanceId instance-ID | Select -ExpandProperty CommandPlugins
```
### 使用 `AWS-ConfigureCloudWatch` 文档将性能计数器发送到 CloudWatch
以下演示命令将性能计数器数据上传到 CloudWatch。有关更多信息，请参阅《*[Amazon CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*》。
```
$cloudWatchMetricsCommand = Send-SSMCommand `
-InstanceID instance-ID `
-DocumentName "AWS-ConfigureCloudWatch" `
-Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"PerformanceCounter", "FullName":"AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"CategoryName":"Memory", "CounterName":"Available MBytes", "InstanceName":"", "MetricName":"AvailableMemory", "Unit":"Megabytes","DimensionName":"", "DimensionValue":""}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"AccessKey":"", "SecretKey":"","Region":"region", "NameSpace":"Windows-Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'}
```
## 使用 `AWS-ConfigureWindowsUpdate` 文档启用或关闭 Windows 自动更新
利用 Run Command 和 `AWS-ConfigureWindowsUpdate` 文档，您可以在 Windows Server 托管式节点上启用或关闭 Windows 自动更新。此命令将 Windows 更新代理配置为在您指定的日期和时间下载并安装 Windows 更新。如果更新需要重启，托管式节点将在安装更新 15 分钟后自动重启。利用此命令，您还可以将 Windows 更新配置为检查更新但不安装更新。`AWS-ConfigureWindowsUpdate` 文档在 Windows Server 2012 及更高版本上获得官方支持。
**查看说明和可用参数**
```
Get-SSMDocumentDescription `
–Name "AWS-ConfigureWindowsUpdate"
```
**查看有关参数的更多信息**
```
Get-SSMDocumentDescription `
-Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters
```
### 启用 Windows 自动更新
以下命令将 Windows 更新配置为在每天晚上 22:00 自动下载和安装更新。
```
$configureWindowsUpdateCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-ConfigureWindowsUpdate" `
-Parameters @{'updateLevel'='InstallUpdatesAutomatically'; 'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}
```
**查看用于允许 Windows 自动更新的命令状态**
以下命令使用 `CommandId` 获取用于允许 Windows 自动更新的命令执行的状态。
```
Get-SSMCommandInvocation `
-Details $true `
-CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
```
### 关闭 Windows 自动更新
以下命令可降低 Windows 更新通知级别，使系统检查更新但不自动更新托管式节点。
```
$configureWindowsUpdateCommand = Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-ConfigureWindowsUpdate" `
-Parameters @{'updateLevel'='NeverCheckForUpdates'}
```
**查看用于关闭 Windows 自动更新的命令状态**
以下命令使用 `CommandId` 获取用于关闭 Windows 自动更新的命令执行的状态。
```
Get-SSMCommandInvocation `
-Details $true `
-CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
```
## 使用 Run Command 管理 Windows 更新
使用 Run Command 和 `AWS-InstallWindowsUpdates` 文档，您可以管理 Windows Server 托管式节点的更新。此命令在托管式节点上扫描或安装缺少的更新，并且可以选择在安装后重启。还可以为在您的环境中安装的更新指定相应的分类和严重性级别。
**注意**
有关在使用 Run Command 调用脚本时重启托管式节点的信息，请参阅 [运行命令时处理重启问题](send-commands-reboot.md)。
以下示例说明了如何执行指定的 Windows Update 管理任务。
### 搜索所有缺少的 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Scan'}
```
### 安装特定的 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'IncludeKbs'='kb-ID-1,kb-ID-2,kb-ID-3';'AllowReboot'='True'}
```
### 安装缺少的重要 Windows 更新
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'}
```
### 安装缺少的 Windows 更新 (带特定排除内容)
```
Send-SSMCommand `
-InstanceId instance-ID `
-DocumentName "AWS-InstallWindowsUpdates" `
-Parameters @{'Action'='Install';'ExcludeKbs'='kb-ID-1,kb-ID-2';'AllowReboot'='True'}
```
# 对 Systems Manager Run Command 进行故障排除
Run Command（AWS Systems Manager 中的一项工具）在每次命令执行时提供状态详细信息。有关命令状态的更多信息，请参阅 [了解命令状态](monitor-commands.md)。您也可以使用本主题中的信息来帮助排查 Run Command 问题。
**Topics**
+ [我的部分托管式节点缺失](#where-are-instances)
+ [我的脚本中的一个步骤失败，但总体状态为 “succeeded”。](#ts-exit-codes)
+ [SSM Agent 未正常运行](#ts-ssmagent-linux)
## 我的部分托管式节点缺失
在 **Run a command**（运行命令）页面上，选择要运行的 SSM 文档并在 **Targets**（目标）部分中选择 **Manually selecting instances**（手动选择实例）后，将显示托管式节点的列表，您可以从中选择要在其上运行命令的节点。
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
创建、激活、重新引导或重新启动托管式节点、在节点上安装 Run Command 或将 AWS Identity and Access Management (IAM) 实例配置文件附加到节点后，该托管式节点可能需要几分钟时间才会添加到列表中。
## 我的脚本中的一个步骤失败，但总体状态为 “succeeded”。
您可以使用 Run Command 定义脚本如何处理退出代码。默认情况下，脚本中运行的最后一个命令的退出代码将报告为整个脚本的退出代码。但是，如果在最后一个命令失败之前有任何命令，则可以包含条件语句来退出脚本。有关信息以及示例，请参阅 [在命令中指定退出代码](run-command-handle-exit-status.md#command-exit-codes)。
## SSM Agent 未正常运行
如果在使用 Run Command 运行命令时遇到问题，可能是因为 SSM Agent 存在问题。有关调查 SSM Agent 的相关问题的信息，请参阅 [排除 SSM Agent 问题](troubleshooting-ssm-agent.md)。
# AWS Systems Manager Session Manager
Session Manager是一项完全托管的 AWS Systems Manager 工具。借助 Session Manager，您可以管理 Amazon Elastic Compute Cloud（Amazon EC2）实例、边缘设备、本地服务器和虚拟机（VM）。您可以使用基于浏览器的一键式交互 Shell 或 AWS Command Line Interface (AWS CLI)。Session Manager 提供安全的节点管理，而无需打开入站端口、维护堡垒主机或管理 SSH 密钥。Session Manager 还可以帮助您遵守需要托管式节点受控访问权限的公司策略、严格的安全实践以及包含节点访问详细信息的日志，同时能够让终端用户轻松地一键式跨平台访问您的托管式节点。要开始使用 Session Manager，请打开 [Systems Manager 控制台](https://console.aws.amazon.com/systems-manager/session-manager)。在导航窗格中，请选择 **Session Manager**。
## 我的组织如何从 Session Manager 获益？
Session Manager 具备下列优势：
+ **使用 IAM policy 集中控制对托管式节点的访问**
管理员可以集中地授予和撤销对托管式节点的访问。仅使用 AWS Identity and Access Management (IAM) 策略，您就可以控制贵企业中的哪些个人用户或组能够使用 Session Manager 以及他们能够访问的托管式节点。
+ **无需打开入站端口，也无需管理堡垒主机或 SSH 密钥**
在托管式节点上保持打开入站 SSH 端口和远程 PowerShell 端口，会极大增加实体在托管式节点上运行未经授权或恶意命令的风险。Session Manager 让您能够关闭这些入站端口，并且无需管理 SSH 密钥和证书以及堡垒主机和跳转盒，从而帮助您提高安全状况。
+ **从控制台和 CLI 一键访问托管式节点**
通过使用 AWS Systems Manager 控制台或 Amazon EC2 控制台，只需单击一下即可启动会话。通过使用 AWS CLI，您还可以启动一个会话以运行单个命令或一系列命令。由于对托管式节点的权限是通过 IAM policy 而非 SSH 密钥或其他机制提供，连接时间得到大幅缩短。
+ **连接到[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境的 Amazon EC2 实例和非 EC2 托管式节点**
连接到[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的 Amazon Elastic Compute Cloud（Amazon EC2）实例和非 EC2 节点。
要使用 Session Manager 连接到非 EC2 节点，必须首先激活高级实例套餐。**使用高级实例套餐需支付费用。**但是，使用 Session Manager 连接到 EC2 实例不需要额外收费。有关信息，请参阅[配置实例套餐](fleet-manager-configure-instance-tiers.md)。
+ **端口转发**
将托管式节点中的任意端口重新导向到客户端上的本地端口。然后，连接到本地端口，并访问在节点内运行的服务器应用程序。
+ **对 Windows、Linux 和 macOS 的跨平台支持**
Session Manager 通过单个工具提供对 Windows、Linux 和 macOS 的支持。例如，您不需要为 Linux 和 macOS 托管式节点使用 SSH 客户端，也不需要为 Windows Server 托管式节点使用 RDP 连接。
+ **记录会话活动**
为满足企业的运营或安全要求，您可能需要提供对托管式节点的连接以及在其上运行的命令的记录。您还可以在组织中的用户开始或结束会话活动时收到通知。
通过与以下 AWS 服务集成来提供日志记录功能：
+ **AWS CloudTrail** – AWS CloudTrail 捕获有关在 AWS 账户中进行的 Session Manager API 调用的信息，并将其写入存储在指定 Amazon Simple Storage Service (Amazon S3) 存储桶中的日志文件。账户的所有 CloudTrail 日志都存储在一个存储桶中。有关更多信息，请参阅 [使用 AWS CloudTrail 记录 AWS Systems Manager API 调用](monitoring-cloudtrail-logs.md)。
+ **Amazon Simple Storage Service** – 您可以选择将会话日志数据存储在您选择的 Amazon S3 存储桶中，以便用于调试和故障排除。在将日志数据发送到 Amazon S3 存储桶时，可以使用或不使用您的 AWS KMS key 进行加密。有关更多信息，请参阅 [使用 Amazon S3 记录会话数据（控制台）](session-manager-logging-s3.md)。
+ **Amazon CloudWatch Logs** – 借助 CloudWatch Logs，您可以监控、存储和访问各种 AWS 服务的日志文件。您可以将会话日志数据发送到 CloudWatch Logs 日志组，以便用于调试和故障排除。在将日志数据发送到日志组时，可以使用您的 KMS 密钥进行 AWS KMS 加密，也可以不加密。有关更多信息，请参阅 [使用 Amazon CloudWatch Logs 记录会话数据（控制台）](session-manager-logging-cloudwatch-logs.md)。
+ **Amazon EventBridge** 和 **Amazon Simple Notification Service** – 使用 EventBridge，您可以设置规则来检测指定的 AWS 资源何时发生更改。您可以创建规则来检测组织中的用户何时启动或停止会话，然后通过 Amazon SNS 接收有关事件的通知（例如，文本消息或电子邮件）。您还可以配置 CloudWatch 事件来启动其他响应。有关更多信息，请参阅 [使用 Amazon EventBridge 监控会话活动（控制台）](session-manager-auditing.md#session-manager-auditing-eventbridge-events)。
**注意**
日志记录不可用于通过端口转发或 SSH 连接的 Session Manager 会话。这是因为 SSH 会对 AWS CLI 和 Session Manager 端点之间建立的安全 TLS 连接中的所有会话数据进行加密，而 Session Manager 仅用作 SSH 连接的隧道。
## 谁应该使用 Session Manager？
+ 任何希望改善其安全状况、通过集中控制对托管式节点的访问来减少运营开销以及希望减少入站节点访问的 AWS 客户。
+ 希望监控并跟踪托管式节点访问和活动、关闭托管式节点上的入站端口或允许连接到没有公有 IP 地址的托管式节点的信息安全专家。
+ 希望从单一位置授予及撤销访问权限并为用户提供一个同时适用于 Linux、macOS 和 Windows Server 托管式节点的解决方案的管理员。
+ 希望只需单击一下即可从浏览器或 AWS CLI 连接到托管式节点而不必提供 SSH 密钥的用户。
## Session Manager 的主要功能是什么？
+ **对 Windows Server、Linux 和 macOS 托管式节点的支持**
Session Manager 可让您与 Amazon Elastic Compute Cloud（EC2）实例、边缘设备、本地服务器和虚拟机（VM）之间建立安全连接。有关支持的操作系统类型的列表，请参阅 [设置 Session Manager](session-manager-getting-started.md)。
**注意**
仅为高级实例套餐提供对本地计算机的 Session Manager 支持。有关信息，请参阅[打开高级实例套餐](fleet-manager-enable-advanced-instances-tier.md)。
+ **支持通过控制台、CLI 和开发工具包等方式访问 Session Manager 功能**
您可以通过以下方式使用Session Manager：
**AWS Systems Manager 控制台**使管理员和终端用户能够访问所有 Session Manager 功能。您可以通过使用 Systems Manager 控制台来执行与会话相关的任何任务。
利用 Amazon EC2 控制台，终端用户能够连接到其已获得会话权限的 EC2 实例。
**AWS CLI** 包括对适用于最终用户的 Session Manager 功能的访问。您可以使用 AWS CLI 启动会话、查看会话列表和永久结束会话。
**注意**
要使用 AWS CLI 运行会话命令，您必须使用 1.16.12 版本（或更高版本）的 CLI，并且必须已在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。要在 GitHub 上查看插件，请参阅 [session-manager-plugin](https://github.com/aws/session-manager-plugin)。
+ **IAM 访问控制**
通过使用 IAM policy，您可以控制企业中的哪些成员能够启动与托管式节点的会话以及他们能够访问哪些节点。您还可以提供对托管式节点的临时访问。例如，您可能需要仅为执勤工程师（或一组执勤工程师）在当班期间提供对生产服务器的访问权限。
+ **日志记录支持**
Session Manager通过与许多其他 AWS 服务集成，为您提供在 AWS 账户中记录会话历史记录的选项。有关更多信息，请参阅[记录会话活动](session-manager-auditing.md)和[启用和禁用会话日志记录](session-manager-logging.md)。
+ **可配置的 Shell 配置文件**
Session Manager 为您提供配置会话中的首选项的选项。您可以使用这些可自定义的配置文件定义首选项，例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。
+ **客户密钥数据加密支持**
您可以配置 Session Manager 以加密发送到 Amazon Simple Storage Service (Amazon S3) 存储桶或流式传输到 CloudWatch Logs 日志组的会话数据日志。您还可以配置 Session Manager 来进一步为会话期间在客户端计算机和托管式节点之间传输的数据加密。有关信息，请参阅 [启用和禁用会话日志记录](session-manager-logging.md) 和[配置会话首选项](session-manager-getting-started-configure-preferences.md)。
+ **为没有公有 IP 地址的托管式节点提供 AWS PrivateLink 支持**
您还可以使用 AWS PrivateLink 为 Systems Manager 设置 VPC 终端节点，以进一步保护您的会话。AWS PrivateLink 将托管式节点、Systems Manager 和 Amazon EC2 之间的所有网络流量限制在 Amazon 网络以内。有关更多信息，请参阅[使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](setup-create-vpc.md)。
+ **隧道**
在会话中，使用会话类型 AWS Systems Manager (SSM) 文档在客户端计算机上的本地端口与托管式节点上的远程端口之间通过隧道传输流量，例如 http 或自定义协议。
+ **交互式命令**
创建会话类型的 SSM 文档，使用会话以交互方式运行单个命令，为您提供一种管理用户可以在托管式节点上执行的操作的方法。
## 什么是会话？
会话是使用 Session Manager 与托管式节点之间建立的连接。会话基于客户端（您）和远程托管式节点之间的安全双向通信通道，可流式传输命令的输入和输出。客户端和托管式节点之间的流量使用 TLS 1.2 进行加密，创建连接的请求使用 Sigv4 进行签名。这种双向通信允许交互式 Bash 和 PowerShell 访问托管式节点。您还可以使用 AWS Key Management Service (AWS KMS) 密钥在默认 TLS 加密之外进一步加密数据。
举例来说，假设 John 是 IT 部门的执勤工程师。他收到一个问题通知，要求他远程连接到某个托管式节点（例如需要处理的故障或用于更改节点上的简单配置选项的指令）。John 使用 AWS Systems Manager 控制台、Amazon EC2 控制台或 AWS CLI 启动一个将其连接到该托管式节点的会话，在完成任务所需的节点上运行命令，然后结束该会话。
当 John 发送第一个命令启动会话时，Session Manager 服务对其 ID 进行身份验证，验证 IAM policy 授予 John 的权限，检查配置设置（例如验证允许的会话限制），并向 SSM Agent发送消息以打开双向连接。建立连接并且 John 键入下一个命令后，SSM Agent的命令输出将上传到此通信通道并发送回 John 的本地计算机。
**Topics**
+ [我的组织如何从 Session Manager 获益？](#session-manager-benefits)
+ [谁应该使用 Session Manager？](#session-manager-who)
+ [Session Manager 的主要功能是什么？](#session-manager-features)
+ [什么是会话？](#what-is-a-session)
+ [设置 Session Manager](session-manager-getting-started.md)
+ [使用 Session Manager](session-manager-working-with.md)
+ [记录会话活动](session-manager-auditing.md)
+ [启用和禁用会话日志记录](session-manager-logging.md)
+ [会话文档架构](session-manager-schema.md)
+ [排除 Session Manager 问题](session-manager-troubleshooting.md)
# 设置 Session Manager
在使用 AWS Systems Manager Session Manager 连接到账户中的托管式节点之前，请完成以下主题中的步骤。
**Topics**
+ [步骤 1：满足 Session Manager 先决条件](session-manager-prerequisites.md)
+ [步骤 2：验证或添加 Session Manager 的实例权限](session-manager-getting-started-instance-profile.md)
+ [步骤 3：控制会话对托管式节点的访问](session-manager-getting-started-restrict-access.md)
+ [步骤 4：配置会话首选项](session-manager-getting-started-configure-preferences.md)
+ [步骤 5：（可选）限制对会话中命令的访问](session-manager-restrict-command-access.md)
+ [步骤 6：（可选）使用 AWS PrivateLink 为 Session Manager 设置 VPC 端点](session-manager-getting-started-privatelink.md)
+ [步骤 7：（可选）开启或关闭 ssm-user 账户管理权限](session-manager-getting-started-ssm-user-permissions.md)
+ [步骤 8：（可选）通过 Session Manager 允许和控制 SSH 连接的权限](session-manager-getting-started-enable-ssh-connections.md)
# 步骤 1：满足 Session Manager 先决条件
在使用 Session Manager 之前，请确保环境满足以下要求。
**Session Manager 先决条件**
| 要求 | 说明 |
| --- | --- |
| 支持的操作系统 | 除了[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中使用*高级实例*套餐的非 EC2 计算机之外，Session Manager 还支持连接到 Amazon Elastic Compute Cloud（Amazon EC2）实例。 Session Manager 支持以下操作系统版本： Session Manager 支持[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中使用*高级实例*套餐的 EC2 实例、边缘设备、本地服务器和虚拟机（VM）。有关高级实例的更多信息，请参阅 [配置实例套餐](fleet-manager-configure-instance-tiers.md)。 **Linux 和 **macOS**** Session Manager 支持 AWS Systems Manager 所支持的所有 Linux 和 macOS 版本。有关信息，请参阅[支持的操作系统和计算机类型](operating-systems-and-machine-types.md)。 ** Windows ** Session Manager 支持 Windows Server 2012 及更高版本。 不支持 Microsoft Windows Server 2016 Nano。 |
| SSM Agent | 至少应在要通过会话连接的托管式节点上安装 2.3.68.0 版本或更高版本的 AWS Systems Manager SSM Agent。 要通过该选项以使用在 AWS Key Management Service (AWS KMS) 中创建的密钥加密会话数据，必须在托管式节点上安装 2.3.539.0 版本或更高版本的 SSM Agent。 要在会话中使用 Shell 配置文件，必须在托管式节点上安装 SSM Agent 3.0.161.0 版本或更高版本。 要开启 Session Manager 端口转发或 SSH 会话，必须在托管式节点上安装 SSM Agent 3.0.222.0 版本或更高版本。 要使用 Amazon CloudWatch Logs 流式传输会话数据，必须在托管式节点上安装 SSM Agent 3.0.284.0 版本或更高版本。 有关如何确定实例上运行的版本号的信息，请参阅 [正在检查 SSM Agent 版本号](ssm-agent-get-version.md)。有关手动安装或自动更新 SSM Agent 的信息，请参阅 [使用 SSM Agent](ssm-agent.md)。 关于 ssm-user 账户 从 SSM Agent 的版本 2.3.50.0 开始，代理在托管式节点上创建名为 `ssm-user` 的用户账户，此账户具有根权限或管理员权限。（在 2.3.612.0 之前的版本上，此账户在 SSM Agent 启动或重新启动时创建。在版本 2.3.612.0 及更高版本上，`ssm-user` 在托管式节点上首次启动会话时创建。） 系统使用此用户账户的管理凭证启动会话。有关限制此账户的管理控制权限的信息，请参阅[关闭或打开 ssm-user 账户管理权限](session-manager-getting-started-ssm-user-permissions.md)。 Windows Server 域控制器上的 ssm-user 从 SSM Agent 版本 2.3.612.0 开始，`ssm-user` 账户不会在用作 Windows Server 域控制器的托管式节点上自动创建。要在用作域控制器的 Windows Server 计算机上使用 Session Manager，您必须手动创建 `ssm-user` 账户（如果此账户尚不存在），并为相关用户分配域管理员权限。在 Windows Server 上，每次会话启动时，SSM Agent 都会为 `ssm-user` 账户设置新密码，因此您无需在创建账户时指定密码。 |
| 连接到端点 | 您要连接到的托管式节点必须还允许到以下端点的 HTTPS（端口 443）出站流量： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/session-manager-prerequisites.html) 有关更多信息，请参阅以下主题： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/session-manager-prerequisites.html) 或者，您可以使用接口端点连接到所需端点。有关更多信息，请参阅 [步骤 6：（可选）使用 AWS PrivateLink 为 Session Manager 设置 VPC 端点](session-manager-getting-started-privatelink.md)。 |
| AWS CLI | （可选）如果使用 AWS Command Line Interface (AWS CLI)（而不是使用 AWS Systems Manager 控制台或 Amazon EC2 控制台）启动会话，则必须在本地计算机上安装 1.16.12 版本或更高版本的 CLI。 您可调用 `aws --version` 来查看版本。 如果您需要安装或升级 CLI，请参阅 AWS Command Line Interface 用户指南中的[安装 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)。 如果有新工具添加至 Systems Manager 或者对现有工具进行了更新，则将发布 SSM Agent 的更新版本。无法使用代理的最新版本可能会阻止托管式节点使用 Systems Manager 的各项工具和功能。因此，我们建议您自动完成确保机器上的 SSM Agent 为最新的过程。有关更多信息，请参阅 [自动更新到 SSM Agent](ssm-agent-automatic-updates.md)。要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/mainline/RELEASENOTES.md)页面。 此外，要使用 CLI 通过 Session Manager 管理节点，必须先在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。 |
| 启用高级实例套餐（[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境） | 若要使用 Session Manager 连接到非 EC2 计算机，必须在您可以在其中创建混合激活以将非 EC2 计算机注册为托管式节点的 AWS 账户 和 AWS 区域 中启用高级实例套餐。使用高级实例套餐需支付费用。有关高级实例套餐的更多信息，请参阅 [配置实例套餐](fleet-manager-configure-instance-tiers.md)。 |
| 验证 IAM 服务角色权限（[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境） | 混合激活节点使用在混合激活中指定的 AWS Identity and Access Management（IAM）服务角色，与 Systems Manager API 操作进行通信。此服务角色必须包含使用 Session Manager 连接到[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)计算机所需的权限。如果您的服务角色包含 AWS 托管式策略 `AmazonSSMManagedInstanceCore`，则已提供 Session Manager 所需的权限。 如果您发现服务角色不包含所需权限，则必须取消注册托管式实例，然后利用使用具有所需权限的 IAM 服务角色的新混合激活进行注册。有关取消注册托管式实例的更多信息，请参阅 [在混合和多云环境中取消注册托管式节点](fleet-manager-deregister-hybrid-nodes.md)。有关创建具有 Session Manager 权限的 IAM policy 的更多信息，请参阅[步骤 2：验证或添加 Session Manager 的实例权限色](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-instance-profile.html)。 |
# 步骤 2：验证或添加 Session Manager 的实例权限
默认情况下，AWS Systems Manager 没有在您的实例上执行操作的权限。您可以使用 AWS Identity and Access Management（IAM）角色在账户级别提供实例权限，也可以使用实例配置文件在实例级别提供实例权限。如果您的应用场景允许，我们建议使用“默认主机管理配置”在账户级别授予访问权限。如果您已经使用 `AmazonSSMManagedEC2InstanceDefaultPolicy` 策略为账户设置了“默认主机管理配置”，则可以继续执行下一步。有关“默认主机管理配置”的更多信息，请参阅[使用默认主机管理配置自动管理 EC2 实例](fleet-manager-default-host-management-configuration.md)。
或者，您可以使用实例配置文件为实例提供所需权限。实例配置文件会将 IAM 角色传递给 Amazon EC2 实例。您可以将 IAM 实例配置文件附加到 Amazon EC2 实例（在启动该实例时）或之前启动的实例。有关更多信息，请参阅[使用实例配置文件](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-usingrole-instanceprofile.html)。
对于本地部署服务器或虚拟机 (VM)，权限由与混合激活关联的 IAM 服务角色提供，该激活用于将您的本地部署服务器和虚拟机注册到 Systems Manager。本地服务器和虚拟机不使用实例配置文件。
如果已使用其他 Systems Manager 工具（例如 Run Command 或 Parameter Store），则可能已将具有Session Manager所需的基本权限的实例配置文件附加到 Amazon EC2 实例。如果包含 AWS 托管式策略 `AmazonSSMManagedInstanceCore` 的实例配置文件已附上您的实例，则已提供 Session Manager 所需的权限。如果混合激活中使用的 IAM 服务角色包含 `AmazonSSMManagedInstanceCore` 托管式策略，则也已提供所需权限。
但在某些情况下，您可能需要修改附加到实例配置文件的权限。例如，您希望提供一组更少的实例权限，您已为实例配置文件创建自定义策略，或者您希望使用 Amazon Simple Storage Service (Amazon S3) 加密或 AWS Key Management Service (AWS KMS) 加密选项以保护会话数据。对于这些情况，请执行以下操作之一，以允许在您的实例上执行 Session Manager 操作：
+ **在自定义 IAM 角色中嵌入 Session Manager 操作权限**
要将 Session Manager 操作的权限添加到不依赖于 AWS 提供的原定设置策略 `AmazonSSMManagedInstanceCore` 的现有 IAM 角色，请按照 [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md) 中的步骤操作。
+ **创建仅具有 Session Manager 权限的自定义 IAM 角色**
要创建仅具有 Session Manager 操作权限的 IAM 角色，请按照 [为 Session Manager 创建自定义 IAM 角色](getting-started-create-iam-instance-profile.md) 中的步骤操作。
+ **创建和使用具有所有 Systems Manager 操作权限的新 IAM 角色**
要为 Systems Manager 托管式实例创建使用 AWS 提供的默认策略授予所有 Systems Manager 权限的 IAM 角色，请按照[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)中的步骤进行操作。
**Topics**
+ [向现有 IAM 角色添加 Session Manager 权限](getting-started-add-permissions-to-existing-profile.md)
+ [为 Session Manager 创建自定义 IAM 角色](getting-started-create-iam-instance-profile.md)
# 向现有 IAM 角色添加 Session Manager 权限
使用以下过程为现有 AWS Identity and Access Management（IAM）角色添加 Session Manager 权限。通过向现有角色添加权限，您可以增强计算环境的安全性，而不必使用 AWS`AmazonSSMManagedInstanceCore` 策略来获得实例权限。
**注意**
请注意以下信息：
此过程假设现有角色已包含您希望允许访问的操作的其他 Systems Manager `ssm` 权限。要使用 Session Manager，只有此策略是不够的。
以下策略示例包括一项 `s3:GetEncryptionConfiguration` 操作。如果您在 Session Manager 日志首选项中选择了**强制 S3 日志加密**选项，则需要执行此操作。
如果从附加到 IAM 实例配置文件或 IAM 服务角色的策略中移除 `ssmmessages:OpenControlChannel` 权限，则托管节点上的 SSM Agent 将失去与云端 Systems Manager 服务的连接。但是，移除权限后，连接最多可能需要 1 小时才能终止。这与删除 IAM 实例角色或 IAM 服务角色时的行为相同。
**向现有角色添加 Session Manager 权限（控制台）**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择**角色**。
1. 选择要向其添加权限的角色的名称。
1. 选择**权限**选项卡。
1. 选择**添加权限**，然后选择**创建内联策略**。
1. 选择 **JSON** 选项卡。
1. 将默认策略内容替换为以下内容。将 *key-name* 替换为您要使用的 AWS Key Management Service 密钥（AWS KMS key）的 Amazon 资源名称（ARN）。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-name"
}
]
}
```
------
有关使用 KMS 密钥加密会话数据的信息，请参阅 [启用会话数据的 KMS 密钥加密（控制台）](session-preferences-enable-encryption.md)。
如果您不为会话数据使用 AWS KMS 加密，可以从策略中删除以下内容。
```
,
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}
```
1. 选择**下一步：标签**。
1. （可选）通过选择 **Add tag**（添加标签）并输入策略的首选标签来添加标签。
1. 选择**下一步：审核**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **SessionManagerPermissions**。
1. （可选）对于**描述**，输入策略的描述。
选择 **Create policy (创建策略)**。
有关 `ssmmessages` 操作的信息，请参阅 [参考：ec2messages、ssmmessages 和其他 API 操作](systems-manager-setting-up-messageAPIs.md)。
# 为 Session Manager 创建自定义 IAM 角色
您可以创建一个 AWS Identity and Access Management（IAM）角色来授予 Session Manager 对您的 Amazon EC2 托管实例执行操作的权限。您还可以在其中包含一个策略，以授予将会话日志发送到 Amazon Simple Storage Service（Amazon S3）和 Amazon CloudWatch Logs 所需的权限。
创建 IAM 角色后，如需关于如何将角色附加到实例的信息，请参阅 AWS re:Post 网站上的[附加或替换实例配置文件](https://aws.amazon.com/premiumsupport/knowledge-center/attach-replace-ec2-instance-profile/)。有关 IAM 实例配置文件和角色的更多信息，请参阅《IAM 用户指南》**中的[使用实例配置文件](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)和《Amazon Elastic Compute Cloud 用户指南（适用于 Linux 实例）》**中的[适用于 Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。有关为本地计算机创建 IAM 服务角色的更多信息，请参阅[在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](https://docs.aws.amazon.com/systems-manager/latest/userguide/hybrid-multicloud-service-role.html)。
**Topics**
+ [创建具有最小 Session Manager 权限的 IAM 角色（控制台）](#create-iam-instance-profile-ssn-only)
+ [创建具有 Session Manager、Amazon S3 和 CloudWatch Logs 权限的 IAM 角色（控制台）](#create-iam-instance-profile-ssn-logging)
## 创建具有最小 Session Manager 权限的 IAM 角色（控制台）
使用以下过程可创建一个自定义 IAM 角色，其策略仅提供在实例上执行 Session Manager 操作的权限。
**创建具有最小 Session Manager 权限的实例配置文件（控制台）**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中选择**策略**，然后选择**创建策略**。（如果显示 **Get Started (入门)** 按钮，请选择此按钮，然后选择 **Create Policy (创建策略)**。）
1. 选择 **JSON** 选项卡。
1. 将原定设置内容替换为以下策略。要使用 AWS Key Management Service（AWS KMS）加密会话数据，请将 *key-name* 替换为您要使用的 AWS KMS key 的 Amazon 资源名称（ARN）。
**注意**
如果从附加到 IAM 实例配置文件或 IAM 服务角色的策略中移除 `ssmmessages:OpenControlChannel` 权限，则托管节点上的 SSM Agent 将失去与云端 Systems Manager 服务的连接。但是，移除权限后，连接最多可能需要 1 小时才能终止。这与删除 IAM 实例角色或 IAM 服务角色时的行为相同。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:UpdateInstanceInformation",
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-name"
}
]
}
```
------
有关使用 KMS 密钥加密会话数据的信息，请参阅 [启用会话数据的 KMS 密钥加密（控制台）](session-preferences-enable-encryption.md)。
如果您不为会话数据使用 AWS KMS 加密，可以从策略中删除以下内容。
```
,
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "key-name"
}
```
1. 选择**下一步：标签**。
1. （可选）通过选择 **Add tag**（添加标签）并输入策略的首选标签来添加标签。
1. 选择**下一步：审核**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **SessionManagerPermissions**。
1. （可选）对于**描述**，输入策略的描述。
1. 选择 **Create policy (创建策略)**。
1. 在导航窗格中，选择 **Roles（角色）**，然后选择 **Create role（创建角色）**。
1. 在 **Create role**（创建角色）页面上，选择 **AWS service**（ 服务），对于 **Use case**（使用案例），选择 **EC2**。
1. 选择**下一步**。
1. 在 **Add permissions**（添加权限）页面上，选中刚刚创建的策略名称左侧的复选框，例如 **SessionManagerPermissions**。
1. 选择**下一步**。
1. 在 **Name, review, and create**（名称、审核和创建）页面中，对于 **Role name**（角色名称），输入 IAM 角色的名称，例如 **MySessionManagerRole**。
1. （可选）对于**角色描述**，输入实例配置文件的描述。
1. （可选）通过选择 **Add tag**（添加标签）并输入角色的首选标签来添加标签。
选择**创建角色**。
有关 `ssmmessages` 操作的信息，请参阅 [参考：ec2messages、ssmmessages 和其他 API 操作](systems-manager-setting-up-messageAPIs.md)。
## 创建具有 Session Manager、Amazon S3 和 CloudWatch Logs 权限的 IAM 角色（控制台）
使用以下过程创建一个自定义 IAM 角色，其策略提供在实例上执行 Session Manager 操作的权限。此策略还提供了将会话日志存储在 Amazon Simple Storage Service (Amazon S3) 存储桶和 Amazon CloudWatch Logs 日志组中所需的权限。
**重要**
要将会话日志输出到其他 AWS 账户 拥有的 Amazon S3 存储桶，您必须将 `s3:PutObjectAcl` 权限添加到 IAM 角色策略。此外，您必须确保存储桶策略授予对拥有账户使用的 IAM 角色的跨账户存取权限，来授予 Systems Manager 托管实例的权限。如果存储桶使用密钥管理服务（KMS）加密，则存储桶的 KMS 策略还必须授予此跨账户存取权限。有关在 Amazon S3 中配置跨账户存储桶权限的信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[授予跨账户存储桶权限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html)。如果跨账户权限未添加，则拥有 Amazon S3 存储桶的账户将无法访问会话输出日志。
有关指定存储会话日志的首选项的信息，请参阅 [启用和禁用会话日志记录](session-manager-logging.md)。
**要创建具有 Session Manager、Amazon S3 和 CloudWatch Logs 权限的 IAM 角色（控制台），请执行以下步骤**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中选择**策略**，然后选择**创建策略**。（如果显示 **Get Started (入门)** 按钮，请选择此按钮，然后选择 **Create Policy (创建策略)**。）
1. 选择 **JSON** 选项卡。
1. 将原定设置内容替换为以下策略。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel",
"ssm:UpdateInstanceInformation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/s3-prefix/*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-name"
},
{
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "*"
}
]
}
```
------
1. 选择**下一步：标签**。
1. （可选）通过选择 **Add tag**（添加标签）并输入策略的首选标签来添加标签。
1. 选择**下一步：审核**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **SessionManagerPermissions**。
1. （可选）对于**描述**，输入策略的描述。
1. 选择 **Create policy (创建策略)**。
1. 在导航窗格中，选择 **Roles（角色）**，然后选择 **Create role（创建角色）**。
1. 在 **Create role**（创建角色）页面上，选择 **AWS service**（ 服务），对于 **Use case**（使用案例），选择 **EC2**。
1. 选择**下一步**。
1. 在 **Add permissions**（添加权限）页面上，选中刚刚创建的策略名称左侧的复选框，例如 **SessionManagerPermissions**。
1. 选择**下一步**。
1. 在 **Name, review, and create**（名称、审核和创建）页面中，对于 **Role name**（角色名称），输入 IAM 角色的名称，例如 **MySessionManagerRole**。
1. （可选）对于 **Role description**(角色描述)，输入角色的描述。
1. （可选）通过选择 **Add tag**（添加标签）并输入角色的首选标签来添加标签。
1. 选择**创建角色**。
# 步骤 3：控制会话对托管式节点的访问
您可以使用 AWS Identity and Access Management（IAM）policy 授予或撤消对托管式节点的 Session Manager 访问权限。您可以创建策略并将其附加到 IAM 用户或群组，以指定此用户或群组可以连接到哪些托管式节点。您还可以指定用户或群组可以在这些托管式节点上执行的 Session Manager API 操作。
为了帮助您开始使用 Session Manager 的 IAM 权限策略，我们为最终用户和管理员用户创建了示例策略。您只需稍作修改即可使用这些策略。或者，将这些策略用作创建自定义 IAM policy 的指南。有关更多信息，请参阅 [Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md)。有关如何创建 IAM policy 并将策略附加到用户或组的信息，请参阅**《IAM 用户指南》中的[创建 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) 及[添加和移除 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
**关于会话 ID ARN 格式**
为 Session Manager 访问权限创建 IAM policy 时，您可以指定会话 ID 作为 Amazon 资源名称（ARN）的一部分。会话 ID 包括作为变量的用户名。为了帮助说明这一点，以下是 Session Manager ARN 的格式和示例：
```
arn:aws:ssm:region-id:account-id:session/session-id
```
例如：
```
arn:aws:ssm:us-east-2:123456789012:session/JohnDoe-1a2b3c4d5eEXAMPLE
```
有关在 IAM policy 中使用变量的更多信息，请参阅 [IAM policy 元素：变量](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html)。
**Topics**
+ [通过在 IAM policy 中指定默认会话文档来启动默认 Shell 会话](getting-started-default-session-document.md)
+ [通过在 IAM policy 中指定会话文档来启动与文档的会话](getting-started-specify-session-document.md)
+ [Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md)
+ [Session Manager 的其他示例 IAM policy](getting-started-restrict-access-examples.md)
# 通过在 IAM policy 中指定默认会话文档来启动默认 Shell 会话
当您在 Systems Manager 控制台中为 AWS 账户 配置 Session Manager 或更改会话首选项时，系统会创建一个名为 `SSM-SessionManagerRunShell` 的 SSM 会话文档。这是默认的会话文档。Session Manager 使用此文档存储您的会话首选项，其中包括以下信息：
+ 您要保存会话数据的位置，例如 Amazon Simple Storage Service（Amazon S3）存储桶或 Amazon CloudWatch Logs 日志组。
+ 用于加密会话数据的 AWS Key Management Service（AWS KMS）密钥 ID。
+ 会话是否允许“运行身份”支持。
以下是 `SSM-SessionManagerRunShell` 会话首选项文档中包含的信息的示例。
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "amzn-s3-demo-bucket",
"s3KeyPrefix": "MyS3Prefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyCWLogGroup",
"cloudWatchEncryptionEnabled": false,
"kmsKeyId": "1a2b3c4d",
"runAsEnabled": true,
"runAsDefaultUser": "RunAsUser"
}
}
```
默认情况下，当用户 AWS 管理控制台 从启动会话时，Session Manager 使用默认会话文档。这适用于 Systems Manager 控制台中的 Fleet Manager 或 Session Manager，或 Amazon EC2 控制台中的 EC2 Connect。当用户使用如下示例所示的 AWS CLI 命令启动会话时，Session Manager 也会使用默认会话文档：
```
aws ssm start-session \
--target i-02573cafcfEXAMPLE
```
要开始默认 Shell 会话，您必需在 IAM 策略中指定默认会话文档，如以下示例所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EnableSSMSession",
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/instance-id",
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": [
"ssmmessages:OpenDataChannel"
],
"Resource": [
"*"
]
}
]
}
```
------
# 通过在 IAM policy 中指定会话文档来启动与文档的会话
如果使用默认会话文档的 [start-session](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html) AWS CLI 命令，则可以省略文档名称。系统会自动调用 `SSM-SessionManagerRunShell` 会话文档。
在所有其他情况下，您必须为 `document-name` 参数指定一个值。当用户在命令中指定会话文档的名称时，系统会检查其 IAM policy，以验证他们是否有权访问该文档。如果他们没有权限，连接请求就会失败。以下示例包括 `AWS-StartPortForwardingSession` 会话文档中的 `document-name` 参数。
```
aws ssm start-session \
--target i-02573cafcfEXAMPLE \
--document-name AWS-StartPortForwardingSession \
--parameters '{"portNumber":["80"], "localPortNumber":["56789"]}'
```
有关在 IAM 策略中指定 Session Manager 会话文档的示例，请参阅 [Session Manager 的快速入门最终用户策略](getting-started-restrict-access-quickstart.md#restrict-access-quickstart-end-user)。
**注意**
要使用 SSH 启动会话，必须在目标托管式节点*和*用户的本地计算机上完成配置步骤。有关信息，请参阅[（可选）通过 Session Manager 允许和控制 SSH 连接的权限](session-manager-getting-started-enable-ssh-connections.md)。
# Session Manager 的 IAM policy 示例
使用此部分中的示例可帮助您创建 AWS Identity and Access Management (IAM) policy，以提供访问 Session Manager 所需的最常用权限。
**注意**
您还可以使用 AWS KMS key 策略，控制授予哪些 IAM 实体（用户或角色）和 AWS 账户 访问您的 KMS 密钥的权限。有关信息，请参阅《AWS Key Management Service 开发人员指南》中[管理 AWS KMS 资源的访问权限概览](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html)和[在 AWS KMS 中使用密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。**
**Topics**
+ [Session Manager 的快速入门最终用户策略](#restrict-access-quickstart-end-user)
+ [（快速入门）Session Manager 管理员策略](#restrict-access-quickstart-admin)
## Session Manager 的快速入门最终用户策略
使用以下示例为 Session Manager 创建 IAM 终端用户策略。
您可以创建一个策略，允许用户仅从 Session Manager 控制台和 AWS Command Line Interface (AWS CLI)、仅从 Amazon Elastic Compute Cloud (Amazon EC2) 控制台或从这三项中启动会话。
这些策略为终端用户提供启动连接到特定托管式节点的会话以及仅结束自己的会话的功能。有关可能需要对策略进行的自定义的示例，请参阅 [Session Manager 的其他示例 IAM policy](getting-started-restrict-access-examples.md)。
在以下示例策略中，将每个*示例资源占位符*替换为您自己的信息。
从以下选项卡中进行选择，查看要提供的会话访问范围的示例策略。
------
#### [ 会话管理器 and Fleet Manager ]
使用此示例策略使用户能够仅从 Session Manager 和 Fleet Manager 控制台启动和恢复会话。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-02573cafcfEXAMPLE",
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-name"
}
]
}
```
------
------
#### [ Amazon EC2 ]
使用此示例策略使用户能够仅从 Amazon EC2 控制台启动和恢复会话。该策略不提供从 Session Manager 控制台和 AWS CLI 启动会话所需的所有权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession",
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-02573cafcfEXAMPLE",
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceInformation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}
```
------
------
#### [ AWS CLI ]
使用此示例策略使用户能够仅从 AWS CLI 启动和恢复会话。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession",
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-02573cafcfEXAMPLE",
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-name"
}
]
}
```
------
------
**注意**
`SSM-SessionManagerRunShell` 是 Session Manager 创建的用于存储会话配置首选项的 SSM 文档的默认名称。您可以创建自定义会话文档，并在此策略中指定它。您还可以为使用 SSH 启动会话的用户指定 AWS 提供的文档 `AWS-StartSSHSession`。有关使用 SSH 支持会话所需的配置步骤的信息，请参阅[（可选）通过 Session Manager 允许和控制 SSH 连接的权限](session-manager-getting-started-enable-ssh-connections.md)。
`kms:GenerateDataKey` 权限可让您创建用于加密会话数据的数据加密密钥。如果您将为您的会话数据使用 AWS Key Management Service (AWS KMS) 加密，请将 *key-name* 替换为您要使用的 KMS 密钥的 Amazon Resource Name (ARN)，使用格式 `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE`。如果您不为会话数据使用 KMS 密钥加密，请从策略中删除以下内容。
```
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "key-name"
}
```
有关使用 AWS KMS 加密会话数据的信息，请参阅 [启用会话数据的 KMS 密钥加密（控制台）](session-preferences-enable-encryption.md)。
如果用户尝试从 Amazon EC2 控制台启动会话，则需要 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html) 权限，但 SSM Agent 必须先更新到 Session Manager 所需的最低版本。Run Command 用于向实例发送命令，以便更新代理。
## （快速入门）Session Manager 管理员策略
使用以下示例可为 Session Manager 创建 IAM 管理员策略。
这些策略为管理员提供启动与使用 `Key=Finance,Value=WebServers` 标记的托管式节点的会话的功能，创建、更新和删除首选项的权限，以及仅结束自己的会话的权限。有关可能需要对策略进行的自定义的示例，请参阅 [Session Manager 的其他示例 IAM policy](getting-started-restrict-access-examples.md)。
您可以创建一个策略，允许管理员仅从 Session Manager 控制台和 AWS CLI、仅从 Amazon EC2 控制台或从这三项中执行这些任务。
在以下示例策略中，将每个*示例资源占位符*替换为您自己的信息。
从以下选项卡中进行选择，查看要支持的访问方案的示例策略。
------
#### [ 会话管理器 and CLI ]
使用此示例策略使管理员能够仅从 Session Manager 控制台和 AWS CLI 执行会话相关任务。此策略不提供从 Amazon EC2 控制台执行会话相关任务所需的所有权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:*:111122223333:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/Finance": [
"WebServers"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssmmessages:OpenDataChannel"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:CreateDocument",
"ssm:UpdateDocument",
"ssm:GetDocument",
"ssm:StartSession"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
},
{
"Effect": "Allow",
"Action": [
"ssmmessages:OpenDataChannel"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
}
]
}
```
------
------
#### [ Amazon EC2 ]
使用此示例策略使管理员能够仅从 Amazon EC2 控制台执行会话相关任务。该策略不提供从 Session Manager 控制台和 AWS CLI 执行会话相关任务所需的所有权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession",
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/tag-key": [
"tag-value"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceInformation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
}
]
}
```
------
------
#### [ 会话管理器, CLI, and Amazon EC2 ]
使用此示例策略使管理员能够从 Session Manager 控制台、AWS CLI 和 Amazon EC2 控制台执行会话相关任务。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession",
"ssm:SendCommand"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/tag-key": [
"tag-value"
]
}
}
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceInformation",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ssm:CreateDocument",
"ssm:UpdateDocument",
"ssm:GetDocument",
"ssm:StartSession"
],
"Resource": "arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
}
]
}
```
------
------
**注意**
如果用户尝试从 Amazon EC2 控制台启动会话，但必须发送命令以首先更新 SSM Agent，则需要 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html) 的权限。
# Session Manager 的其他示例 IAM policy
请参阅以下示例策略，以帮助您为要支持的任何 Session Manager 用户访问场景创建自定义 AWS Identity and Access Management (IAM) policy。
**Topics**
+ [示例 1：在控制台中授予对文档的访问权限](#grant-access-documents-console-example)
+ [示例 2：限制对特定托管式节点的访问](#restrict-access-example-instances)
+ [示例 3：根据标签限制访问](#restrict-access-example-instance-tags)
+ [示例 4：仅允许用户结束自己启动的会话](#restrict-access-example-user-sessions)
+ [示例 5：允许对所有会话进行完全（管理）访问](#restrict-access-example-full-access)
## 示例 1：在控制台中授予对文档的访问权限
您可以允许用户在使用会话管理器控制台启动会话时指定自定义文档。以下示例 IAM policy 授予访问指定 AWS 区域 和 AWS 账户 中名称以 **SessionDocument-** 开头的文档的权限。
将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:GetDocument",
"ssm:ListDocuments"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SessionDocument-*"
]
}
]
}
```
------
**注意**
会话管理器控制台仅支持用于定义会话首选项、其 `sessionType` 为 `Standard_Stream` 的会话文档。有关更多信息，请参阅 [会话文档架构](session-manager-schema.md)。
## 示例 2：限制对特定托管式节点的访问
您可以创建一个 IAM policy，用于定义允许用户使用 Session Manager 连接到哪些托管节点。例如，以下策略将授予用户在三个特定节点上开始、结束和恢复其会话的权限。该策略将限制用户连接到指定节点以外的节点。
**注意**
有关联合用户的信息，请参阅 [示例 4：仅允许用户结束自己启动的会话](#restrict-access-example-user-sessions)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/i-1234567890EXAMPLE",
"arn:aws:ec2:us-east-1:111122223333:instance/i-abcdefghijEXAMPLE",
"arn:aws:ec2:us-east-1:111122223333:instance/i-0e9d8c7b6aEXAMPLE",
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
}
]
}
```
------
## 示例 3：根据标签限制访问
您可以根据特定标签限制对托管式节点的访问。在以下示例中，允许用户在任何托管式节点 (`Effect: Allow, Action: ssm:StartSession, ssm:ResumeSession`) 上启动和恢复会话 (`Resource: arn:aws:ec2:region:987654321098:instance/*`)，条件是节点为 Finance WebServer (`ssm:resourceTag/Finance: WebServer`)。如果用户向未经标记或具有除 `Finance: WebServer` 以外的任何标签的托管式节点发送命令，则命令结果将包括 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/*"
],
"Condition": {
"StringLike": {
"ssm:resourceTag/Finance": [
"WebServers"
]
}
}
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession",
"ssm:ResumeSession"
],
"Resource": [
"arn:aws:ssm:*:*:session/${aws:userid}-*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
}
]
}
```
------
您可以创建 IAM policy 来允许用户启动与使用多个标签标记的托管式节点的会话。以下策略允许用户启动与应用了指定标签的托管式节点的会话。如果用户向未使用这些标签标记的托管式节点发送命令，则命令结果将包括 `AccessDenied`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:StartSession"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/tag-key1":[
"tag-value1"
],
"ssm:resourceTag/tag-key2":[
"tag-value2"
]
}
}
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
},
{
"Effect": "Allow",
"Action": [
"ssm:StartSession"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
}
]
}
```
------
有关创建 IAM policy 的更多信息，请参阅**《IAM 用户指南》中的[托管策略与内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html)。有关标记托管式节点的更多信息，请参阅《Amazon EC2 用户指南》**中的[标记 Amazon EC2 资源](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)（内容适用于 Windows 和 Linux 托管式节点）。有关在托管式节点上提高针对未授权根级别命令的安保状况的更多信息，请参阅 [通过 SSM Agent 限制对根级别命令的访问](ssm-agent-restrict-root-level-commands.md)
## 示例 4：仅允许用户结束自己启动的会话
Session Manager 提供了两种方法来控制允许您的 AWS 账户 中的联合用户结束哪些会话。
+ 在 AWS Identity and Access Management (IAM) 权限策略中使用变量 `{aws:userid}`。联合用户只能结束自己启动的会话。对于非联合用户，请使用方法 1。对于联合用户，请使用方法 2。
+ 在 IAM 权限策略中使用 AWS 标签提供的标签。在此策略中，您包含一个条件，该条件允许用户仅结束使用 AWS 提供的特定标签进行标记的会话。此方法适用于所有账户，包括使用联合 ID 授予 AWS 访问权限的账户。
### 方法 1：使用变量 `{aws:username}` 授予终止会话权限
以下 IAM policy 允许用户查看您账户中所有会话的 ID。但是，用户只能通过其启动的会话与托管式节点交互。分配了以下策略的用户无法连接或结束其他用户的会话。此策略使用变量 `{aws:username}` 来实现这一目的。
**注意**
此方法不适用于使用联合 ID 授予 AWS 访问权限的账户。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ssm:DescribeSessions"
],
"Effect": "Allow",
"Resource": [
"*"
]
},
{
"Action": [
"ssm:TerminateSession"
],
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:*:*:session/${aws:username}-*"
]
}
]
}
```
------
### 方法 2：使用 AWS 提供的标签授予 TerminateSession 权限
您可以通过在 IAM policy 中包括条件标签键变量，来控制用户可以结束哪些会话。该条件指定用户只能结束使用这些特定标记键变量和指定值之一或两者标记的会话。
当您的 AWS 账户中的用户启动会话时，Session Manager 会对会话应用两个资源标签。第一个资源标签是 `aws:ssmmessages:target-id`，用它可指定允许用户结束的目标的 ID。另一个资源标签是 `aws:ssmmessages:session-id`，值的格式为 `role-id:caller-specified-role-name`。
**注意**
Session Manager 不支持此 IAM 访问控制策略的自定义标签。您必须使用 AWS 提供的资源标签，如下所述。
** `aws:ssmmessages:target-id` **
使用此标签键，您可以在策略中包含托管式节点 ID 作为值。在以下策略数据块中，条件语句允许用户仅结束节点 i-02573cafcfEXAMPLE。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:target-id": [
"i-02573cafcfEXAMPLE"
]
}
}
}
]
}
```
如果用户尝试结束未获得此 `TerminateSession` 权限的会话，则会收到 `AccessDeniedException` 错误。
** `aws:ssmmessages:session-id` **
此标签键包含会话 ID 的变量作为请求中的值来启动会话。
以下示例演示了调用方类型为 `User` 的情况的策略。您为 `aws:ssmmessages:session-id` 提供的值是用户的 ID。在此示例中，`AIDIODR4TAW7CSEXAMPLE` 表示您的 AWS 账户中的用户的 ID。要检索您的 AWS 账户中的用户的 ID，请使用 IAM 命令 `get-user`。有关信息，请参阅《IAM 用户指南》中 AWS Identity and Access Management 部分中的 [get-user](https://docs.aws.amazon.com/IAM/latest/UserGuide/get-user.html)。**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"AIDIODR4TAW7CSEXAMPLE"
]
}
}
}
]
}
```
以下示例演示了调用方类型为 `AssumedRole` 的情况的策略。针对您为 `aws:ssmmessages:session-id` 提供的值，您可以使用 `{aws:userid}` 变量。或者，您可以针对您为 `aws:ssmmessages:session-id` 提供的值硬编码角色 ID。如果您对角色 ID 进行硬编码，则必须采用以格式 `role-id:caller-specified-role-name` 提供值。例如 `AIDIODR4TAW7CSEXAMPLE:MyRole`。
为了系统标签得以应用，您提供的角色 ID 只能包含以下字符：Unicode 字母、0-9、空格、`_`、`.`、`:`、`/`、`=`、`+`、`-`、`@` 和 `\`。
要检索您的 AWS 账户中的角色的角色 ID，请使用 `get-caller-identity` 命令。有关更多信息，请参阅 AWS CLI 命令参考中的 [get-caller-identity](https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html)。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:TerminateSession"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:resourceTag/aws:ssmmessages:session-id": [
"${aws:userid}*"
]
}
}
}
]
}
```
如果用户尝试结束未获得此 `TerminateSession` 权限的会话，则会收到 `AccessDeniedException` 错误。
**`aws:ssmmessages:target-id`** 和 **`aws:ssmmessages:session-id`**
您还可以创建 IAM policy 来允许用户结束使用这两个系统标签标记的会话，如本示例所示。
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ssm:TerminateSession"
],
"Resource":"*",
"Condition":{
"StringLike":{
"ssm:resourceTag/aws:ssmmessages:target-id":[
"i-02573cafcfEXAMPLE"
],
"ssm:resourceTag/aws:ssmmessages:session-id":[
"${aws:userid}*"
]
}
}
}
]
}
```
## 示例 5：允许对所有会话进行完全（管理）访问
以下 IAM policy 允许用户与所有托管式节点以及所有用户为所有节点创建的所有会话进行不受限制的交互。只应将其授予需要完全控制组织的 Session Manager 活动的管理员。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ssm:StartSession",
"ssm:TerminateSession",
"ssm:ResumeSession",
"ssm:DescribeSessions",
"ssm:GetConnectionStatus"
],
"Effect": "Allow",
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
}
]
}
```
------
# 步骤 4：配置会话首选项
在其 AWS Identity and Access Management（IAM）policy 中授予管理权限的用户可以配置会话首选项，包括以下内容：
+ 为 Linux 托管式节点启用“运行身份”支持。这样，就可以使用指定操作系统用户的凭证启动会话，而非 `ssm-user` AWS Systems Manager 可以在托管式节点上创建的系统生成的 Session Manager 账户的凭证。
+ 配置 Session Manager 以使用 AWS KMS key 加密，以便为在客户端计算机和托管式节点之间传输的数据提供额外保护。
+ 配置 Session Manager，以创建会话历史记录日志并发送到 Amazon Simple Storage Service (Amazon S3) 存储桶或 Amazon CloudWatch Logs 日志组。然后，可以使用存储的日志数据来报告对您的托管节点进行的会话连接以及会话期间在这些节点上运行的命令。
+ 配置会话超时。您可以使用此设置指定在处于不活动状态一段时间后结束会话。
+ 配置 Session Manager 以使用可配置的 Shell 配置文件。您可以使用这些可自定义的配置文件定义会话中的首选项，例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。
有关配置 Session Manager 首选项所需权限的更多信息，请参阅[授予或拒绝更新 Session Manager 首选项的用户权限](preference-setting-permissions.md)。
**Topics**
+ [授予或拒绝更新 Session Manager 首选项的用户权限](preference-setting-permissions.md)
+ [指定空闲会话超时值](session-preferences-timeout.md)
+ [指定最长会话持续时间](session-preferences-max-timeout.md)
+ [允许可配置的 Shell 配置文件](session-preferences-shell-config.md)
+ [为 Linux 和 macOS 托管式节点开启“运行身份”支持](session-preferences-run-as.md)
+ [启用会话数据的 KMS 密钥加密（控制台）](session-preferences-enable-encryption.md)
+ [创建 Session Manager 首选项文档（命令行）](getting-started-create-preferences-cli.md)
+ [更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md)
有关使用 Systems Manager 控制台为记录会话数据配置选项的信息，请参阅以下主题：
+ [使用 Amazon S3 记录会话数据（控制台）](session-manager-logging-s3.md)
+ [使用 Amazon CloudWatch Logs 流式传输会话数据（控制台）](session-manager-logging-cwl-streaming.md)
+ [使用 Amazon CloudWatch Logs 记录会话数据（控制台）](session-manager-logging-cloudwatch-logs.md)
# 授予或拒绝更新 Session Manager 首选项的用户权限
账户首选项存储为每个 AWS 区域的 AWS Systems Manager (SSM) 文档。必须先授予用户访问存储首选项的 SSM 文档类型所需的权限，之后他们才能更新账户中会话的账户首选项。这些权限是通过 AWS Identity and Access Management (IAM) 策略授予的。
**允许创建和更新首选项的管理员策略**
管理员可以随时使用以下策略来创建和更新首选项。以下策略允许访问和更新 us-east-2 账户 123456789012 中的 `SSM-SessionManagerRunShell` 文档。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ssm:CreateDocument",
"ssm:GetDocument",
"ssm:UpdateDocument",
"ssm:DeleteDocument"
],
"Effect": "Allow",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
}
]
}
```
------
**阻止更新首选项的用户策略**
使用以下策略可阻止账户中的最终用户更新或覆盖任何 Session Manager 首选项。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ssm:CreateDocument",
"ssm:GetDocument",
"ssm:UpdateDocument",
"ssm:DeleteDocument"
],
"Effect": "Deny",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/SSM-SessionManagerRunShell"
]
}
]
}
```
------
# 指定空闲会话超时值
Session Manager是 AWS Systems Manager 中的一项工具，使您能够指定在系统结束会话之前允许用户处于非活动状态的时间长度。默认情况下，会话在 20 分钟不活动后超时。您可以修改此设置，指定会话在处于不活动状态 1 到 60 分钟之间的时间后超时。一些专业计算安全机构建议将空闲会话超时设置为最多 15 分钟。
当 Session Manager 收到客户端输入时，空闲会话超时计时器会重置。这些输入包括但不限于：
+ 终端中的键盘输入
+ 终端或浏览器窗口大小调整事件
+ 会话重新连接（ResumeSession），可能由于网络中断、浏览器选项卡管理或 WebSocket 断开连接而发生
由于这些事件会重置空闲计时器，因此即使没有直接终端命令，会话保持活动状态的时间也可能超过配置的超时时间。
如果您的安全要求规定无论活动如何都必须严格限制会话持续时间，则除了空闲超时之外，还应使用*最长会话持续时间*设置。有关更多信息，请参阅 [指定最长会话持续时间](session-preferences-max-timeout.md)。
**要允许空闲会话超时（控制台），请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 在 **Idle session timeout (空闲会话超时)** 的 **Minutes (分钟)** 字段中，指定在结束会话之前允许用户处于非活动状态的时间长度。
1. 选择**保存**。
# 指定最长会话持续时间
Session Manager（AWS Systems Manager 中的一项工具）允许您指定会话在结束前的最长持续时间。默认情况下，会话没有最长持续时间。您指定的最长会话持续时间值必须介于 1 到 1440 分钟之间。
**指定最长会话持续时间（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中 **Enable maximum session duration**（启用最长会话持续时间）旁边的复选框。
1. 在 **Maximum session duration**（最长会话持续时间）下的 **minutes**（分钟）字段中指定会话结束前的最长会话持续时间。
1. 选择**保存**。
# 允许可配置的 Shell 配置文件
默认情况下，适用于 Linux 的 EC2 实例上的会话使用 Bourne Shell（sh）启动。但是，您可能更喜欢使用 Bash 等其他 Shell。通过允许可配置的 Shell 配置文件，您可以自定义会话中的首选项，例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。
**重要**
Systems Manager 不会检查 Shell 配置文件中的命令或脚本，以查看它们在运行之前会对实例进行哪些更改。要限制用户修改在其 Shell 配置文件中输入的命令或脚本，建议执行以下操作：
为您的 AWS Identity and Access Management (IAM) 用户和角色创建自定义的会话类型文档。然后，修改这些用户和角色的 IAM policy，使 `StartSession` API 操作只能使用您为他们创建的会话类型文档。有关信息，请参阅 [创建 Session Manager 首选项文档（命令行）](getting-started-create-preferences-cli.md) 和 [Session Manager 的快速入门最终用户策略](getting-started-restrict-access-quickstart.md#restrict-access-quickstart-end-user)。
修改 IAM 用户和角色的 IAM policy，以拒绝访问您创建的会话类型文档资源的 `UpdateDocument` API 操作。这样，您的用户和角色便可以使用您为其会话首选项创建的文档，而不允许他们修改任何设置。
**要启用可配置的 Shell 配置文件，请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 在适用操作系统的字段中指定要在会话启动时运行的环境变量、Shell 首选项或命令。
1. 选择**保存**。
以下是一些可以添加到 Shell 配置文件的示例命令。
在 Linux 实例上更改为 Bash Shell，并更改为 /usr 目录。
```
exec /bin/bash
cd /usr
```
在会话开始时输出时间戳和欢迎消息。
------
#### [ Linux & macOS ]
```
timestamp=$(date '+%Y-%m-%dT%H:%M:%SZ')
user=$(whoami)
echo $timestamp && echo "Welcome $user"'!'
echo "You have logged in to a production instance. Note that all session activity is being logged."
```
------
#### [ Windows ]
```
$timestamp = (Get-Date).ToString("yyyy-MM-ddTH:mm:ssZ")
$splitName = (whoami).Split("\")
$user = $splitName[1]
Write-Host $timestamp
Write-Host "Welcome $user!"
Write-Host "You have logged in to a production instance. Note that all session activity is being logged."
```
------
在会话开始时查看动态系统活动。
------
#### [ Linux & macOS ]
```
top
```
------
#### [ Windows ]
```
while ($true) { Get-Process | Sort-Object -Descending CPU | Select-Object -First 30; `
Start-Sleep -Seconds 2; cls
Write-Host "Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName";
Write-Host "------- ------ ----- ----- ----- ------ -- -----------"}
```
------
# 为 Linux 和 macOS 托管式节点开启“运行身份”支持
默认情况下，Session Manager 将使用在托管节点上创建的系统生成的 `ssm-user` 账户的凭证，对连接进行身份验证。（在 Linux 和 macOS 计算机上，此账户添加到 `/etc/sudoers/`。） 如果您选择，则可以改为使用操作系统 (OS) 用户账户或已加入 Active Directory 的示例的域用户的凭据对会话进行身份验证。在这种情况下，Session Manager 会在启动会话之前验证节点上或域中是否存在您指定的操作系统账户。如果您尝试使用节点上或域中不存在的操作系统账户启动会话，则连接将失败。
**注意**
Session Manager 不支持使用操作系统的 `root` 用户账户对连接进行身份验证。对于使用操作系统用户账户进行身份验证的会话，节点的操作系统级别和目录策略（如登录限制或系统资源使用限制）可能不适用。
**工作原理**
如果为会话启用“运行身份”支持，系统将检查访问权限，如下所示：
1. 对于正在启动会话的用户，是否使用 `SSMSessionRunAs = os user account name` 标记了其 IAM 实体（用户或角色）？
如果是，托管节点上是否存在该操作系统用户名？ 如果存在，启动会话。否则，不允会话启动。
如果*尚未*使用 `SSMSessionRunAs = os user account name` 标记 IAM 实体，请继续执行步骤 2。
1. 如果尚未使用 `SSMSessionRunAs = os user account name` 标记 IAM 实体，是否已在 AWS 账户 的 Session Manager 首选项中指定了操作系统用户名？
如果是，托管节点上是否存在该操作系统用户名？ 如果存在，启动会话。否则，不允会话启动。
**注意**
当您激活“运行方式”支持时，它将阻止 Session Manager 使用托管节点上的 `ssm-user` 账户启动会话。这意味着，如果 Session Manager 无法使用指定的操作系统用户账户进行连接，则它不会退回到使用默认方法进行连接。
如果您在未指定操作系统账户或标记 IAM 实体的情况下激活“运行方式”，并且未在 Session Manager 首选项中指定操作系统账户，则会话连接尝试将失败。
**为 Linux 和 macOS 托管式节点启用“运行身份”支持**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中**为 Linux 实例启用运行身份支持**旁边的复选框。
1. 请执行以下操作之一：
+ **选项 1**：在**操作系统用户名**字段中，输入您要用于启动会话的操作系统用户账户的名称。使用此选项，所有会话都由同一操作系统用户为您的 AWS 账户 中使用 Session Manager 连接的所有用户运行。
+ **选项 2**（建议）：选择**打开 IAM 控制台**链接。在导航窗格中，选择**用户**或**角色**。选择要将标签添加到的实体（用户或角色），然后选择**标签**选项卡。对于密钥名称，输入 `SSMSessionRunAs`。对于密钥值，输入操作系统用户账户的名称。选择**保存更改**。
如果您选择此选项，则您可以使用此选项为不同 IAM 实体指定唯一的操作系统用户。有关标记 IAM 实体（用户或角色）的更多信息，请参阅《*IAM 用户指南*》中的[标记 IAM 资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)。
示例如下：
![\[为 Session Manager 运行身份权限指定标签的屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/ssn-run-as-tags.png)
1. 选择**保存**。
# 启用会话数据的 KMS 密钥加密（控制台）
使用 AWS Key Management Service（AWS KMS）创建和管理加密密钥。借助 AWS KMS，您可以控制各个 AWS 服务之间以及应用程序中对加密的使用。您可以指定使用 KMS 密钥加密方式对在托管式节点与 AWS 账户 中用户的本地计算机之间传输的会话数据进行加密。（这是对 AWS 默认提供的 TLS 1.2/1.3 加密的补充）。要加密 Session Manager 会话数据，请使用 AWS KMS 创建*对称* KMS 密钥。
AWS KMS 加密适用于 `Standard_Stream`、`InteractiveCommands` 和 `NonInteractiveCommands` 会话类型。要通过该选项使用在 AWS KMS 中创建的密钥加密会话数据，必须在托管式节点上安装 2.3.539.0 版本或更高版本的 AWS Systems Manager SSM Agent。
**注意**
您必须允许 AWS KMS 加密，才能从 AWS Systems Manager 控制台重置托管式节点上的密码。有关更多信息，请参阅 [在托管式节点上重置密码](fleet-manager-reset-password.md#managed-instance-reset-a-password)。
您可以使用您在 AWS 账户中创建的密钥。您还可以使用在其他 AWS 账户中创建的密钥。其他 AWS 账户中密钥的创建者必须为您提供使用密钥所需的权限。
在您为会话数据启用 KMS 密钥加密后，启动会话的用户及其所连接的托管式节点都必须具有使用密钥的权限。您可以通过 AWS Identity and Access Management (IAM) 策略向 Session Manager 提供使用 KMS 密钥的权限。有关更多信息，请参阅以下主题：
+ 为您账户中的用户添加 AWS KMS 权限：[Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md)。
+ 为您账户中的托管式节点添加 AWS KMS 权限：[步骤 2：验证或添加 Session Manager 的实例权限](session-manager-getting-started-instance-profile.md)。
有关创建和管理 KMS 密钥的更多信息，请参阅 [AWS Key Management Service 开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/)。**
有关使用 AWS CLI 在您的账户中启用会话数据的 KMS 密钥加密的信息，请参阅 [创建 Session Manager 首选项文档（命令行）](getting-started-create-preferences-cli.md) 或 [更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md)。
**注意**
使用 KMS 密钥需支付费用。有关更多信息，请参阅 [AWS Key Management Service 定价](https://aws.amazon.com/kms/pricing/)。
**要启用会话数据的 KMS 密钥加密（控制台），请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中 **Enable KMS encryption**（启用 KMS 加密）旁边的复选框。
1. 请执行以下操作之一：
+ 选择 **Select a KMS key in my current account (选择我当前账户中的 KMS 密钥)** 旁边的按钮，然后从列表中选择一个密钥。
-或者-
选择**输入 KMS 密钥别名或 KMS 密钥 ARN **旁边的按钮。手动输入在您的当前账户中创建的密钥的 KMS 密钥别名，或输入另一账户中的密钥的密钥 Amazon Resource Name (ARN)。示例如下：
+ 密钥别名：`alias/my-kms-key-alias`
+ 密钥 ARN：`arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-12345EXAMPLE`
-或者-
选择 **Create new key (创建新密钥)**，在您的账户中创建新 KMS 密钥。在创建新密钥后，返回到 **Preferences (首选项)** 选项卡，然后选择用于在您的账户中加密会话数据的密钥。
有关共享密钥的更多信息，请参阅《AWS Key Management Service 开发人员指南》中的[允许外部 AWS 账户 访问密钥](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html#key-policy-modifying-external-accounts)。
1. 选择**保存**。
# 创建 Session Manager 首选项文档（命令行）
使用以下步骤创建 SSM 文档，这些文档定义了您的 AWS Systems ManagerSession Manager 会话首选项。您可以使用该文档来配置会话选项，包括数据加密、会话持续时间和日志记录。例如，您可以指定是否要在 Amazon Simple Storage Service（Amazon S3）存储桶或 Amazon CloudWatch Logs 日志组中存储会话日志数据。您可以创建定义 AWS 账户 和 AWS 区域 所有会话的常规首选项的文档，也可以创建定义各个会话首选项的文档。
**注意**
您也可以使用会话管理器控制台配置常规会话首选项。
用于设置会话管理器首选项的文档必须有 `Standard_Stream` 的 `sessionType`。有关会话文档的更多信息，请参阅 [会话文档架构](session-manager-schema.md)。
有关使用命令行更新现有 Session Manager 首选项的信息，请参阅 [更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md)。
有关如何使用 CloudFormation 创建会话首选项的示例，请参阅《AWS CloudFormation 用户指南》中的[为 Session Manager 首选项创建 Systems Manager 文档](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-document.html#aws-resource-ssm-document--examples)。**
**注意**
此过程介绍如何创建用于在 AWS 账户 级别设置 Session Manager 首选项的文档。要创建用于设置会话级别首选项的文档，请为与文件名相关的命令输入指定 `SSM-SessionManagerRunShell` 以外的值。
要使用您的文档为从 AWS Command Line Interface（AWS CLI）开始的会话设置首选项，请提供文档名称作为 `--document-name` 参数值。要为从会话管理器控制台启动的会话设置首选项，可以键入或从列表中选择文档的名称。
**创建 Session Manager 首选项（命令行）**
1. 在本地计算机上使用 `SessionManagerRunShell.json` 之类的名称创建一个 JSON 文件，然后将以下内容粘贴到此文件中。
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "",
"s3KeyPrefix": "",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": false,
"kmsKeyId": "",
"runAsEnabled": false,
"runAsDefaultUser": "",
"idleSessionTimeout": "",
"maxSessionDuration": "",
"shellProfile": {
"windows": "date",
"linux": "pwd;ls"
}
}
}
```
您还可以使用参数将值传递到会话首选项，而不是硬编码这些值，如以下示例所示。
```
{
"schemaVersion":"1.0",
"description":"Session Document Parameter Example JSON Template",
"sessionType":"Standard_Stream",
"parameters":{
"s3BucketName":{
"type":"String",
"default":""
},
"s3KeyPrefix":{
"type":"String",
"default":""
},
"s3EncryptionEnabled":{
"type":"Boolean",
"default":"false"
},
"cloudWatchLogGroupName":{
"type":"String",
"default":""
},
"cloudWatchEncryptionEnabled":{
"type":"Boolean",
"default":"false"
}
},
"inputs":{
"s3BucketName":"{{s3BucketName}}",
"s3KeyPrefix":"{{s3KeyPrefix}}",
"s3EncryptionEnabled":"{{s3EncryptionEnabled}}",
"cloudWatchLogGroupName":"{{cloudWatchLogGroupName}}",
"cloudWatchEncryptionEnabled":"{{cloudWatchEncryptionEnabled}}",
"kmsKeyId":""
}
}
```
1. 指定要发送会话数据的位置。您可以指定 S3 存储桶名称（包含可选前缀）或 CloudWatch Logs 日志组名称。如果您要进一步加密本地客户端与托管式节点之间的数据，请提供用于加密的 KMS 密钥。示例如下：
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "amzn-s3-demo-bucket",
"s3KeyPrefix": "MyS3Prefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyLogGroupName",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": false,
"kmsKeyId": "MyKMSKeyID",
"runAsEnabled": true,
"runAsDefaultUser": "MyDefaultRunAsUser",
"idleSessionTimeout": "20",
"maxSessionDuration": "60",
"shellProfile": {
"windows": "MyCommands",
"linux": "MyCommands"
}
}
}
```
**注意**
如果不需要加密会话日志数据，请将 `s3EncryptionEnabled` 的 `true` 更改为 `false`。
如果您不是将日志发送到 Amazon S3 存储桶或 CloudWatch Logs 日志组，不希望加密活动会话的数据，或不希望为账户中的会话启用“运行身份”支持，则可以删除这些选项的行。确保 `inputs` 部分中的最后一行不以逗号结尾。
如果您添加 KMS 密钥 ID 来加密会话数据，启动会话的用户及其所连接的托管式节点都必须具有使用该密钥的权限。您可以通过 IAM policy 向 Session Manager 提供使用 KMS 密钥的权限。有关更多信息，请参阅以下主题：
为您账户中的用户添加 AWS KMS 权限：[Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md)。
为账户中的托管式节点添加 AWS KMS 权限：[步骤 2：验证或添加 Session Manager 的实例权限](session-manager-getting-started-instance-profile.md)
1. 保存该文件。
1. 在创建此 JSON 文件的目录中，运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm create-document \
--name SSM-SessionManagerRunShell \
--content "file://SessionManagerRunShell.json" \
--document-type "Session" \
--document-format JSON
```
------
#### [ Windows ]
```
aws ssm create-document ^
--name SSM-SessionManagerRunShell ^
--content "file://SessionManagerRunShell.json" ^
--document-type "Session" ^
--document-format JSON
```
------
#### [ PowerShell ]
```
New-SSMDocument `
-Name "SSM-SessionManagerRunShell" `
-Content (Get-Content -Raw SessionManagerRunShell.json) `
-DocumentType "Session" `
-DocumentFormat JSON
```
------
如果成功，该命令将返回类似于以下内容的输出。
```
{
"DocumentDescription": {
"Status": "Creating",
"Hash": "ce4fd0a2ab9b0fae759004ba603174c3ec2231f21a81db8690a33eb66EXAMPLE",
"Name": "SSM-SessionManagerRunShell",
"Tags": [],
"DocumentType": "Session",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "1",
"HashType": "Sha256",
"CreatedDate": 1547750660.918,
"Owner": "111122223333",
"SchemaVersion": "1.0",
"DefaultVersion": "1",
"DocumentFormat": "JSON",
"LatestVersion": "1"
}
}
```
# 更新 Session Manager 首选项（命令行）
以下过程介绍了如何使用首选的命令行工具在选择的 AWS 区域中为您的 AWS 账户更改 AWS Systems Manager Session Manager 首选项。使用 Session Manager 首选项来指定在 Amazon Simple Storage Service (Amazon S3) 存储桶或 Amazon CloudWatch Logs 日志组中记录会话数据的选项。您还可以使用 Session Manager 首选项来加密您的会话数据。
**更新 Session Manager 首选项（命令行）**
1. 在本地计算机上使用 `SessionManagerRunShell.json` 之类的名称创建一个 JSON 文件，然后将以下内容粘贴到此文件中。
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "",
"s3KeyPrefix": "",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": false,
"kmsKeyId": "",
"runAsEnabled": true,
"runAsDefaultUser": "",
"idleSessionTimeout": "",
"maxSessionDuration": "",
"shellProfile": {
"windows": "date",
"linux": "pwd;ls"
}
}
}
```
1. 指定要发送会话数据的位置。您可以指定 S3 存储桶名称（包含可选前缀）或 CloudWatch Logs 日志组名称。如果您要进一步加密本地客户端与托管式节点之间的数据，请提供用于加密的 AWS KMS key。示例如下：
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "amzn-s3-demo-bucket",
"s3KeyPrefix": "MyS3Prefix",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "MyLogGroupName",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": false,
"kmsKeyId": "MyKMSKeyID",
"runAsEnabled": true,
"runAsDefaultUser": "MyDefaultRunAsUser",
"idleSessionTimeout": "20",
"maxSessionDuration": "60",
"shellProfile": {
"windows": "MyCommands",
"linux": "MyCommands"
}
}
}
```
**注意**
如果不需要加密会话日志数据，请将 `s3EncryptionEnabled` 的 `true` 更改为 `false`。
如果您不是将日志发送到 Amazon S3 存储桶或 CloudWatch Logs 日志组，不希望加密活动会话的数据，或不希望为账户中的会话启用“运行身份”支持，则可以删除这些选项的行。确保 `inputs` 部分中的最后一行不以逗号结尾。
如果您添加 KMS 密钥 ID 来加密会话数据，启动会话的用户及其所连接的托管式节点都必须具有使用该密钥的权限。您可以通过 AWS Identity and Access Management (IAM) 策略向 Session Manager 提供使用 KMS 密钥的权限。有关更多信息，请参阅以下主题：
为您账户中的用户添加 AWS KMS 权限：[Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md)。
为您账户中的托管式节点添加 AWS KMS 权限：[步骤 2：验证或添加 Session Manager 的实例权限](session-manager-getting-started-instance-profile.md)。
1. 保存该文件。
1. 在创建此 JSON 文件的目录中，运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm update-document \
--name "SSM-SessionManagerRunShell" \
--content "file://SessionManagerRunShell.json" \
--document-version "\$LATEST"
```
------
#### [ Windows ]
```
aws ssm update-document ^
--name "SSM-SessionManagerRunShell" ^
--content "file://SessionManagerRunShell.json" ^
--document-version "$LATEST"
```
------
#### [ PowerShell ]
```
Update-SSMDocument `
-Name "SSM-SessionManagerRunShell" `
-Content (Get-Content -Raw SessionManagerRunShell.json) `
-DocumentVersion '$LATEST'
```
------
如果成功，该命令将返回类似于以下内容的输出。
```
{
"DocumentDescription": {
"Status": "Updating",
"Hash": "ce4fd0a2ab9b0fae759004ba603174c3ec2231f21a81db8690a33eb66EXAMPLE",
"Name": "SSM-SessionManagerRunShell",
"Tags": [],
"DocumentType": "Session",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "2",
"HashType": "Sha256",
"CreatedDate": 1537206341.565,
"Owner": "111122223333",
"SchemaVersion": "1.0",
"DefaultVersion": "1",
"DocumentFormat": "JSON",
"LatestVersion": "2"
}
}
```
# 步骤 5：（可选）限制对会话中命令的访问
您可以通过使用自定义 `Session` 类型 AWS Systems Manager（SSM）文档来限制用户可以在 AWS Systems Manager Session Manager 会话中运行的命令。在文档中，您可以定义用户启动会话时运行的命令以及用户可以向命令提供的参数。`Session` 文档的 `schemaVersion` 必须为 1.0，文档的 `sessionType` 必须为 `InteractiveCommands`。然后，您可以创建 AWS Identity and Access Management（IAM）policy 以仅允许用户访问您定义的 `Session` 文档。有关使用 IAM policy 限制对会话中命令的访问的更多信息，请参阅 [交互式命令的 IAM policy 示例](#interactive-command-policy-examples)。
仅从 AWS Command Line Interface（AWS CLI）启动的会话支持 `sessionType` 为 `InteractiveCommands` 的文档。用户提供自定义文档名称作为 `--document-name` 参数值，并使用 `--parameters` 选项提供任何命令参数值。有关运行交互式命令的更多信息，请参阅 [启动会话（交互式和非交互式命令）](session-manager-working-with-sessions-start.md#sessions-start-interactive-commands)。
使用以下过程创建自定义 `Session` 类型 SSM 文档来定义允许用户运行的命令。
## 限制对会话中命令的访问（控制台）
**限制用户可以在 Session Manager 会话中运行的命令（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 选择 **Create command or session (创建命令或会话)**。
1. 对于 **Name (名称)**，为文档输入一个描述性名称。
1. 对于 **Document type (文档类型)**，选择 **Session document (会话文档)**。
1. 输入文档内容，用来定义用户可以使用 JSON 或 YAML 在 Session Manager 会话中运行的命令，如以下示例所示。
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Document to view a log file on a Linux instance
sessionType: InteractiveCommands
parameters:
logpath:
type: String
description: The log file path to read.
default: "/var/log/amazon/ssm/amazon-ssm-agent.log"
allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$"
properties:
linux:
commands: "tail -f {{ logpath }}"
runAsElevated: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "1.0",
"description": "Document to view a log file on a Linux instance",
"sessionType": "InteractiveCommands",
"parameters": {
"logpath": {
"type": "String",
"description": "The log file path to read.",
"default": "/var/log/amazon/ssm/amazon-ssm-agent.log",
"allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$"
}
},
"properties": {
"linux": {
"commands": "tail -f {{ logpath }}",
"runAsElevated": true
}
}
}
```
------
1. 选择**创建文档**。
## 限制对会话中命令的访问（命令行）
**开始前的准备工作**
安装并配置 AWS Command Line Interface (AWS CLI) 或 AWS Tools for PowerShell（如果尚未这样做）。有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
**限制用户可以在 Session Manager 会话中运行的命令（命令行）**
1. 为文档内容创建 JSON 或 YAML 文件，用来定义用户可在 Session Manager 会话中运行的命令，如以下示例所示。
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Document to view a log file on a Linux instance
sessionType: InteractiveCommands
parameters:
logpath:
type: String
description: The log file path to read.
default: "/var/log/amazon/ssm/amazon-ssm-agent.log"
allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$"
properties:
linux:
commands: "tail -f {{ logpath }}"
runAsElevated: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "1.0",
"description": "Document to view a log file on a Linux instance",
"sessionType": "InteractiveCommands",
"parameters": {
"logpath": {
"type": "String",
"description": "The log file path to read.",
"default": "/var/log/amazon/ssm/amazon-ssm-agent.log",
"allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$"
}
},
"properties": {
"linux": {
"commands": "tail -f {{ logpath }}",
"runAsElevated": true
}
}
}
```
------
1. 运行以下命令，使用您的内容创建 SSM 文档，该内容定义了用户可以在 Session Manager 会话中运行的命令。
------
#### [ Linux & macOS ]
```
aws ssm create-document \
--content file://path/to/file/documentContent.json \
--name "exampleAllowedSessionDocument" \
--document-type "Session"
```
------
#### [ Windows ]
```
aws ssm create-document ^
--content file://C:\path\to\file\documentContent.json ^
--name "exampleAllowedSessionDocument" ^
--document-type "Session"
```
------
#### [ PowerShell ]
```
$json = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String
New-SSMDocument `
-Content $json `
-Name "exampleAllowedSessionDocument" `
-DocumentType "Session"
```
------
## 交互式命令参数和 AWS CLI
在使用 AWS CLI 时，可以通过多种方式提供交互式命令参数。根据您用于通过 AWS CLI 连接到托管式节点的客户端计算机的操作系统 (OS)，您为包含特殊字符或转义字符的命令提供的语法可能不同。以下示例显示了在使用 AWS CLI 时提供命令参数的一些不同方法，以及如何处理特殊字符或转义字符。
您的命令参数可在 AWS CLI 中引用存储在 Parameter Store 中的参数，如以下示例所示。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name MyInteractiveCommandDocument \
--parameters '{"command":["{{ssm:mycommand}}"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name MyInteractiveCommandDocument ^
--parameters '{"command":["{{ssm:mycommand}}"]}'
```
------
以下示例显示了如何使用 AWS CLI 的简写语法来传递参数。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name MyInteractiveCommandDocument \
--parameters command="ifconfig"
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name MyInteractiveCommandDocument ^
--parameters command="ipconfig"
```
------
您也可以提供 JSON 格式的参数，如以下示例所示。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name MyInteractiveCommandDocument \
--parameters '{"command":["ifconfig"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name MyInteractiveCommandDocument ^
--parameters '{"command":["ipconfig"]}'
```
------
参数也可以存储在 JSON 文件中并提供给 AWS CLI，如以下示例所示。有关从文件中使用 AWS CLI 参数的更多信息，请参阅《AWS Command Line Interface 用户指南》中的[从文件中加载 AWS CLI 参数](https://docs.aws.amazon.com/cli/latest/userguide/;cli-usage-parameters-file.html)。**
```
{
"command": [
"my command"
]
}
```
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name MyInteractiveCommandDocument \
--parameters file://complete/path/to/file/parameters.json
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name MyInteractiveCommandDocument ^
--parameters file://complete/path/to/file/parameters.json
```
------
您还可以从 JSON 输入文件生成 AWS CLI 骨架，如以下示例所示。有关从 JSON 输入文件生成 AWS CLI 骨架的更多信息，请参阅《AWS Command Line Interface 用户指南》中的[从 JSON 或 YAML 输入文件生成 AWS CLI 骨架和输入参数](https://docs.aws.amazon.com/cli/latest/userguide/;cli-usage-skeleton.html)。**
```
{
"Target": "instance-id",
"DocumentName": "MyInteractiveCommandDocument",
"Parameters": {
"command": [
"my command"
]
}
}
```
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--cli-input-json file://complete/path/to/file/parameters.json
```
------
#### [ Windows ]
```
aws ssm start-session ^
--cli-input-json file://complete/path/to/file/parameters.json
```
------
要对引号内的字符进行转义，必须在转义字符中添加额外的反斜杠，如以下示例所示。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name MyInteractiveCommandDocument \
--parameters '{"command":["printf \"abc\\\\tdef\""]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name MyInteractiveCommandDocument ^
--parameters '{"command":["printf \"abc\\\\tdef\""]}'
```
------
有关在 AWS CLI 中将引号和命令参数结合使用的信息，请参阅《AWS Command Line Interface 用户指南》中的[在 AWS CLI 中将引号和字符串结合使用](https://docs.aws.amazon.com/cli/latest/userguide/;cli-usage-parameters-quoting-strings.html)。**
## 交互式命令的 IAM policy 示例
您可以创建 IAM policy 以仅允许用户访问您定义的 `Session` 文档。这将用户可以在 Session Manager 会话中运行的命令限制为仅在自定义 `Session` 类型 SSM 文档中定义的命令。
**允许用户在单个托管式节点上运行交互式命令**
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ssm:StartSession",
"Resource":[
"arn:aws:ec2:us-east-1:444455556666:instance/i-02573cafcfEXAMPLE",
"arn:aws:ssm:us-east-1:444455556666:document/allowed-session-document"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
}
]
}
```
**允许用户在所有托管式节点上运行交互式命令**
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ssm:StartSession",
"Resource":[
"arn:aws:ec2:us-east-1:444455556666:instance/*",
"arn:aws:ssm:us-east-1:444455556666:document/allowed-session-document"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
}
]
}
```
**允许用户在所有托管式节点上运行多个交互式命令**
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ssm:StartSession",
"Resource":[
"arn:aws:ec2:us-east-1:444455556666:instance/*",
"arn:aws:ssm:us-east-1:444455556666:document/allowed-session-document",
"arn:aws:ssm:us-east-1:444455556666:document/allowed-session-document-2"
]
},
{
"Effect": "Allow",
"Action": ["ssmmessages:OpenDataChannel"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:userid}-*"]
}
]
}
```
# 步骤 6：（可选）使用 AWS PrivateLink 为 Session Manager 设置 VPC 端点
您可以通过将 AWS Systems Manager 配置为使用接口 Virtual Private Cloud (VPC) 终端节点来进一步提高托管式节点的安保状况。接口端点由 AWS PrivateLink 提供支持，该技术使您能够通过使用私有 IP 地址私下访问 Amazon Elastic Compute Cloud (Amazon EC2) 和 Systems Manager API。
AWS PrivateLink 将托管式节点、Systems Manager 和 Amazon EC2 之间的所有网络流量限制在 Amazon 网络以内。（托管式节点无法访问互联网。） 而且，您无需 Internet 网关、NAT 设备或虚拟专用网关。
有关创建 VPC 端点的信息，请参阅[使用适用于 Systems Manager 的 VPC 终端节点提高 EC2 实例的安全性](setup-create-vpc.md)。
使用 VPC 终端节点的替代方法是，在托管式节点上允许出站互联网访问。在这种情况下，托管式节点还必须允许到以下端点的 HTTPS（端口 443）出站流量：
+ `ec2messages.region.amazonaws.com`
+ `ssm.region.amazonaws.com`
+ `ssmmessages.region.amazonaws.com`
Systems Manager 使用上述最后一个端点（即 `ssmmessages.region.amazonaws.com`）从 SSM Agent 对云中的 Session Manager 服务进行调用。
要使用可选功能，例如 AWS Key Management Service (AWS KMS) 加密、将日志流式传输至 Amazon CloudWatch Logs (CloudWatch Logs) 以及将日志发送到 Amazon Simple Storage Service (Amazon S3)，您必须允许到以下端点的 HTTPS（端口 443）出站流量：
+ `kms.region.amazonaws.com`
+ `logs.region.amazonaws.com`
+ `s3.region.amazonaws.com`
有关 Systems Manager 所需的端点的更多信息，请参阅[参考：ec2messages、ssmmessages 和其他 API 操作](systems-manager-setting-up-messageAPIs.md)。
# 步骤 7：（可选）开启或关闭 ssm-user 账户管理权限
从 AWS Systems Manager SSM Agent 版本 2.3.50.0 开始，此代理会创建一个名为 `ssm-user` 的本地用户账户，并将其添加到 `/etc/sudoers`（Linux 和 macOS）或管理员组（Windows）。在 2.3.612.0 之前的代理版本上，账户会在 SSM Agent 安装后首次启动或重启时创建。在版本 2.3.612.0 及更高版本上，会话在节点上首次启动时会创建 `ssm-user` 账户。当 AWS Systems Manager Session Manager 会话启动时，此 `ssm-user` 为默认操作系统（OS）用户。SSM Agent 版本 2.3.612.0 于 2019 年 5 月 8 日发布。
如果要阻止 Session Manager 用户在节点上运行管理命令，可以更新 `ssm-user` 账户权限。这些权限在删除后还可以恢复。
**Topics**
+ [在 Linux 和 macOS 上管理 ssm-user sudo 账户权限](#ssm-user-permissions-linux)
+ [在 Windows Server 上管理 ssm-user 管理员账户权限](#ssm-user-permissions-windows)
## 在 Linux 和 macOS 上管理 ssm-user sudo 账户权限
使用以下过程之一在 Linux 和 macOS 托管式节点上启用或禁用 ssm-user 账户 sudo 权限。
**使用 Run Command 修改 ssm-user sudo 权限（控制台）**
+ 在[从控制台运行命令](running-commands-console.md)中的过程中使用以下值：
+ 对于 **Command document (命令文档)**，选择 `AWS-RunShellScript`。
+ 要删除 sudo 访问权限，请在 **Command parameters (命令参数)** 区域中，将以下内容粘贴到 **Commands (命令)** 框中：
```
cd /etc/sudoers.d
echo "#User rules for ssm-user" > ssm-agent-users
```
-或者-
要恢复 sudo 访问权限，请在 **Command parameters (命令参数)** 区域中，将以下内容粘贴到 **Commands (命令)** 框中：
```
cd /etc/sudoers.d
echo "ssm-user ALL=(ALL) NOPASSWD:ALL" > ssm-agent-users
```
**使用命令行修改 ssm-user sudo 权限 (AWS CLI)**
1. 连接到托管式节点并运行以下命令。
```
sudo -s
```
1. 使用以下命令更改工作目录。
```
cd /etc/sudoers.d
```
1. 打开名为 `ssm-agent-users` 的文件进行编辑。
1. 要删除 sudo 访问权限，请删除以下行。
```
ssm-user ALL=(ALL) NOPASSWD:ALL
```
-或者-
要恢复 sudo 访问权限，请添加以下行。
```
ssm-user ALL=(ALL) NOPASSWD:ALL
```
1. 保存该文件。
## 在 Windows Server 上管理 ssm-user 管理员账户权限
使用以下过程之一在 Windows Server 托管式节点上开启或关闭 ssm-user 账户管理员权限。
**使用 Run Command 修改管理员权限（控制台）**
+ 在[从控制台运行命令](running-commands-console.md)中的过程中使用以下值：
对于 **Command document (命令文档)**，选择 `AWS-RunPowerShellScript`。
要删除管理访问权限，请在 **Command parameters (命令参数)** 区域中，将以下内容粘贴到 **Commands (命令)** 框中：
```
net localgroup "Administrators" "ssm-user" /delete
```
-或者-
要恢复管理访问权限，请在 **Command parameters (命令参数)** 区域中，将以下内容粘贴到 **Commands (命令)** 框中：
```
net localgroup "Administrators" "ssm-user" /add
```
**使用 PowerShell 或命令提示符窗口修改管理员权限**
1. 连接到托管式节点并打开 PowerShell 或命令提示符窗口。
1. 要删除管理访问权限，请运行以下命令。
```
net localgroup "Administrators" "ssm-user" /delete
```
-或者-
要恢复管理访问权限，请运行以下命令。
```
net localgroup "Administrators" "ssm-user" /add
```
**使用 Windows 控制台修改管理员权限**
1. 连接到托管式节点并打开 PowerShell 或命令提示符窗口。
1. 在命令行中，运行 `lusrmgr.msc` 打开**本地用户和组**控制台。
1. 打开**用户**目录，然后打开 **ssm-user**。
1. 在 **Member Of (属于)** 选项卡上，执行以下操作之一：
+ 要删除管理员权限，请选择 **Administrators**，然后选择**删除**。
-或者-
要恢复管理访问权限，请在文本框中输入 **Administrators**，然后选择 **Add (添加)**。
1. 选择**确定**。
# 步骤 8：（可选）通过 Session Manager 允许和控制 SSH 连接的权限
您可以允许 AWS 账户 中的用户使用 AWS Systems Manager Session Manager 通过 AWS Command Line Interface (AWS CLI) 建立与托管式节点的 Secure Shell (SSH) 连接。使用 SSH 连接的用户还可以使用安全复制协议 (SCP) 在本地计算机和托管式节点之间复制文件。您可以使用此功能连接到托管式节点，而无需打开入站端口或维护堡垒主机。
当您通过 Session Manager 建立 SSH 连接时，AWS CLI 和 SSM Agent 会通过 TLS 创建到 Session Manager 端点的安全 WebSocket 连接。SSH 会话在此加密隧道内运行，无需在托管节点上开放入站端口，即可提供额外安全保护。
允许 SSH 连接后，您可以使用 AWS Identity and Access Management (IAM) 策略显式允许或拒绝用户、组或角色使用 Session Manager 进行 SSH 连接。
**注意**
日志记录不可用于通过端口转发或 SSH 连接的 Session Manager 会话。这是因为 SSH 会对 AWS CLI 和 Session Manager 端点之间建立的安全 TLS 连接中的所有会话数据进行加密，而 Session Manager 仅用作 SSH 连接的隧道。
**Topics**
+ [允许 Session Manager 的 SSH 连接](#ssh-connections-enable)
+ [通过 Session Manager 控制 SSH 连接的用户权限](#ssh-connections-permissions)
## 允许 Session Manager 的 SSH 连接
使用以下步骤在托管式节点上通过 Session Manager 允许 SSH 连接。
**允许 Session Manager 的 SSH 连接**
1. 在要允许 SSH 连接的托管式节点上，执行以下操作：
+ 确保 SSH 正在托管式节点上运行。（您可以关闭节点上的入站端口。）
+ 确保托管式节点上安装了 SSM Agent 版本 2.3.672.0 或更高版本。
有关在托管式节点上安装或更新 SSM Agent 的更多信息，请参阅以下主题：
+ [在适用于 Windows Server 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-windows.md).
+ [在适用于 Linux 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-linux.md)
+ [在适用于 macOS 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-macos.md)
+ [如何在混合 Windows 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-windows.md)
+ [如何在混合 Linux 节点上安装 SSM Agent](hybrid-multicloud-ssm-agent-install-linux.md)
**注意**
要将 Session Manager 与作为托管式节点激活的本地服务器、边缘设备和虚拟机 (VM) 一起使用，必须使用高级实例套餐。有关高级实例的更多信息，请参阅 [配置实例套餐](fleet-manager-configure-instance-tiers.md)。
1. 在要使用 SSH 连接到托管式节点的本地计算机上，执行以下操作：
+ 确保安装了 Session Manager 插件的版本 1.1.23.0 或更高版本。
有关安装 Session Manager 的信息，请参阅 [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
+ 更新 SSH 配置文件以允许运行代理命令，此命令启动 Session Manager 会话并通过连接传输所有数据。
**Linux 和 macOS**
**提示**
SSH 配置文件通常位于 `~/.ssh/config`。
将以下内容添加到本地计算机上的配置文件中。
```
# SSH over Session Manager
Host i-* mi-*
ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"
User ec2-user
```
** Windows **
**提示**
SSH 配置文件通常位于 `C:\Users\\.ssh\config`。
将以下内容添加到本地计算机上的配置文件中。
```
# SSH over Session Manager
Host i-* mi-*
ProxyCommand C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters portNumber=%p"
```
+ 创建或确认您具有在建立与托管式节点的连接时使用的 Privacy Enhanced Mail 证书（PEM 文件），或者至少具有公有密钥。此密钥必须是已与托管式节点关联的密钥。必须设置私有密钥文件的权限，以确保只有您可以读取该文件。您可以使用以下命令设置您的私有密钥文件的权限，以确保只有您可以读取该文件。
```
chmod 400 .pem
```
例如，对于 Amazon Elastic Compute Cloud (Amazon EC2) 实例，这是您在创建实例时创建或选择的密钥对文件。（您可以在启动会话的命令中指定证书或密钥的路径。有关使用 SSH 启动会话的信息，请参阅 [启动会话 (SSH)](session-manager-working-with-sessions-start.md#sessions-start-ssh)。）
## 通过 Session Manager 控制 SSH 连接的用户权限
在托管式节点上通过 Session Manager 启用 SSH 连接后，您可以使用 IAM policy 允许或拒绝用户、组或角色通过 Session Manager 进行 SSH 连接。
**要使用 IAM policy 允许通过 Session Manager 进行 SSH 连接，请执行以下步骤：**
+ 使用以下选项之一：
+ **选项 1**：通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
在导航窗格中，选择 **Policies (策略)**，然后更新您想要允许通过 Session Manager 启动 SSH 连接的用户或角色的权限策略。
例如，将以下元素添加到您在[Session Manager 的快速入门最终用户策略](getting-started-restrict-access-quickstart.md#restrict-access-quickstart-end-user)中创建的快速入门策略中。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartSession",
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:instance/instance-id",
"arn:aws:ssm:*:*:document/AWS-StartSSHSession"
]
},
{
"Effect": "Allow",
"Action": "ssmmessages:OpenDataChannel",
"Resource": "arn:aws:ssm:*:*:session/${aws:userid}-*"
}
]
}
```
------
+ **选项 2**：使用 AWS 管理控制台、AWS CLI 或 AWS API 将一个内联策略附加到用户策略。
通过使用所选的方法，将**选项 1** 中的策略语句附加到 AWS 用户、组或角色的策略中。
有关信息，请参阅 *IAM 用户指南*中的[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
**要使用 IAM policy 拒绝通过 Session Manager 进行 SSH 连接，请执行以下步骤：**
+ 使用以下选项之一：
+ **选项 1**：通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。在导航窗格中，选择 **Policies (策略)**，然后更新用户或角色的权限策略以阻止启动 Session Manager 会话。
例如，将以下元素添加到您在[Session Manager 的快速入门最终用户策略](getting-started-restrict-access-quickstart.md#restrict-access-quickstart-end-user)中创建的快速入门策略中。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:StartSession",
"Resource": "arn:aws:ssm:*:*:document/AWS-StartSSHSession"
},
{
"Effect": "Allow",
"Action": "ssmmessages:OpenDataChannel",
"Resource": "arn:aws:ssm:*:*:session/${aws:userid}-*"
}
]
}
```
------
+ **选项 2**：使用 AWS 管理控制台、AWS CLI 或 AWS API 将一个内联策略附加到用户策略。
通过使用所选的方法，将**选项 1** 中的策略语句附加到 AWS 用户、组或角色的策略中。
有关信息，请参阅 *IAM 用户指南*中的[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
# 使用 Session Manager
您可以使用 AWS Systems Manager 控制台、Amazon Elastic Compute Cloud (Amazon EC2) 控制台或 AWS Command Line Interface (AWS CLI) 启动会话，以连接到系统管理员使用 AWS Identity and Access Management (IAM) 策略授予您访问权限的托管式节点。根据您的权限，您还可以查看有关会话的信息、恢复未超时的非活动会话以及结束会话。建立会话后，它不受 IAM 角色会话持续时间的影响。关于使用 Session Manager 限制会话持续时间的信息，请参阅[指定空闲会话超时值](session-preferences-timeout.md)和[指定最长会话持续时间](session-preferences-max-timeout.md)。
有关会话的更多信息，请参阅 [什么是会话？](session-manager.md#what-is-a-session)
**Topics**
+ [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)
+ [启动会话](session-manager-working-with-sessions-start.md)
+ [结束会话](session-manager-working-with-sessions-end.md)
+ [查看会话历史记录](session-manager-working-with-view-history.md)
# 为 AWS CLI 安装 Session Manager 插件
要使用 AWS Command Line Interface（AWS CLI）启动与托管式节点的 Session Manager 会话，您必须在本地计算机上安装此 *Session Manager 插件*。您可以在支持的 Microsoft Windows Server、macOS、Linux 和 Ubuntu Server 版本上安装此插件。
**注意**
要使用 AWS CLI 插件，必须在本地计算机上安装 Session Manager 版本 1.16.12 或更高版本。有关更多信息，请参阅[安装或更新 AWS Command Line Interface 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
**Topics**
+ [Session Manager 插件最新版本和发布历史记录](plugin-version-history.md)
+ [在 Windows 上安装 Session Manager 插件](install-plugin-windows.md)
+ [在 macOS 上安装 Session Manager 插件](install-plugin-macos-overview.md)
+ [在 Linux 上安装 Session Manager 插件](install-plugin-linux-overview.md)
+ [验证 Session Manager 插件安装](install-plugin-verify.md)
+ [GitHub 上的 Session Manager 插件](plugin-github.md)
+ [（可选）开启 Session Manager 插件日志记录](install-plugin-configure-logs.md)
# Session Manager 插件最新版本和发布历史记录
本地计算机必须运行支持的 Session Manager 插件版本。当前支持的最低版本为 1.1.17.0。如果运行的是更早的版本，则 Session Manager 操作可能会失败。
要查看使用的是不是最新版本，请在 AWS CLI 中运行以下命令。
**注意**
仅当插件位于操作系统类型的默认安装目录中时，此命令才返回结果。您也可以在 `VERSION` 文件（位于安装此插件的目录中）内容中找到版本信息。
```
session-manager-plugin --version
```
下表列出了 Session Manager 插件的所有版本，以及每个版本所含的功能和增强功能。
**重要**
建议您始终运行最新版本。最新版本包括增强功能，可改善插件的使用体验。
| 版本 | 发行日期 | Details |
| --- | --- | --- |
| 1.2.792.0 | 2026 年 3 月 17 日 | **错误修复**：针对 Windows 增加了国际键盘支持。 |
| 1.2.779.0 | 2026 年 2 月 12 日 | **增强功能**：在 Dockerfile 中将 Go 版本更新至 1.25。 **错误修复**：在 debian 打包脚本中添加 shebang 行。 |
| 1.2.764.0 | 2025 年 11 月 19 日 | **增强**：增加了对签署 OpenDataChannel 请求的支持。 **错误修复**：修复检查样式问题以支持较新的 Go 版本。 |
| 1.2.707.0 | 2025 年 2 月 6 日 | **增强功能**：已将 Dockerfile 中的 Go 版本升级到 1.23。更新了 README 中的版本配置步骤。 |
| 1.2.694.0 | 2024 年 11 月 20 日 | **错误修复**：回滚了向 OpenDataChannel 请求添加凭证的更改。 |
| 1.2.688.0 | 2024 年 11 月 6 日 | **此版本已于 2024 年 11 月 20 日弃用。** **增强功能**：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/plugin-version-history.html) |
| 1.2.677.0 | 2024 年 10 月 10 日 | **增强**：增加了对通过 OpenDataChannel 请求传递插件版本的支持。 |
| 1.2.650.0 | 2024 年 7 月 2 日 | **增强**：将 aws-sdk-go 升级到 1.54.10。**错误修复**：修改了 gofmt 检查的注释。 |
| 1.2.633.0 | 2024 年 5 月 30 日 | 增强：将 Dockerfile 更新为使用 Amazon Elastic Container Registry（Amazon ECR）映像。 |
| 1.2.553.0 | 2024 年 1 月 10 日 | 增强功能：升级了 aws-sdk-go 和相关的 Golang 程序包。 |
| 1.2.536.0 | 2023 年 12 月 4 日 | 增强：增加了对将 [StartSession](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartSession.html) API 响应作为环境变量传递给会话管理器插件的支持。 |
| 1.2.497.0 | 2023 年 8 月 1 日 | 增强功能：将 Go SDK 升级到 v1.44.302。 |
| 1.2.463.0 | 2023 年 3 月 15 日 | 增强功能：在 macOS 捆绑安装程序和已签名的安装程序中增加了对 Apple Mac（M1）的 Mac with Apple silicon 支持。 |
| 1.2.398.0 | 2022 年 10 月 14 日 | 改进：支持 Golang 版本 1.17。更新 macOS 的默认会话管理器插件运行程序以使用 Python3。更新从 SSMCLI 到会话管理器插件的导入路径。 |
| 1.2.339.0 | 2022 年 6 月 16 日 | 错误修复：修复端口会话的空闲会话超时问题。 |
| 1.2.331.0 | 2022 年 5 月 27 日 | 错误修复：修复当本地服务器在超时前无法连接时提前关闭端口会话的问题。 |
| 1.2.323.0 | 2022 年 5 月 19 日 | 错误修复：禁用 smux 保持活动状态以使用空闲会话超时功能。 |
| 1.2.312.0 | 2022 年 3 月 31 日 | 增强功能：支持更多的输出消息有效载荷类型。 |
| 1.2.295.0 | 2022 年 1 月 12 日 | 错误修复：客户端在代理变为非活动状态时重新发送流数据而导致的会话挂起，以及 start\$1publication 和 pause\$1publication 消息的不正确日志。 |
| 1.2.279.0 | 2021 年 10 月 27 日 | 增强功能：面向 Windows 平台打包成 zip 格式。 |
| 1.2.245.0 | 2021 年 8 月 19 日 | 增强功能：将 aws-sdk-go 升级到最新版本（v1.40.17）以支持 AWS IAM Identity Center。 |
| 1.2.234.0 | 2021 年 7 月 26 日 | 错误修复：处理交互式会话类型中会话突然终止的情况。 |
| 1.2.205.0 | 2021 年 6 月 10 日 | 增强功能：添加对已签名 macOS 安装程序的支持。 |
| 1.2.54.0 | 2021 年 1 月 29 日 | 增强功能：添加对在 NonInteractiveCommands 执行模式中运行会话的支持。 |
| 1.2.30.0 | 2020 年 11 月 24 日 | **增强功能**：（仅限端口转发会话）整体性能提升。 |
| 1.2.7.0 | 2020 年 10 月 15 日 | **增强功能**：（仅限端口转发会话）延迟减少并且整体性能提升。 |
| 1.1.61.0 | 2020 年 4 月 17 日 | **增强功能：**添加了对 Linux 和 Ubuntu Server 的 ARM 支持。 |
| 1.1.54.0 | 2020 年 1 月 6 日 | **错误修复**：处理 Session Manager 插件未准备就绪时丢弃数据包的争用情况。 |
| 1.1.50.0 | 2019 年 11 月 19 日 | **增强功能**：添加了将端口转发到本地 unix 套接字的支持。 |
| 1.1.35.0 | 2019 年 11 月 7 日 | **增强功能**：（仅限端口转发会话）在本地用户按 `Ctrl+C` 时将 TerminateSession 命令发送到 SSM Agent。 |
| 1.1.33.0 | 2019 年 9 月 26 日 | 增强功能：（仅限端口转发会话）当客户端断开 TCP 连接时，向服务器发送断开连接信号。 |
| 1.1.31.0 | 2019 年 9 月 6 日 | 增强功能：更新以保持端口转发会话打开，直到远程服务器关闭连接。 |
| 1.1.26.0 | 2019 年 7 月 30 日 | **增强功能**：更新以限制会话期间的数据传输速率。 |
| 1.1.23.0 | 2019 年 7 月 9 日 | **增强功能**：添加对使用 Session Manager 运行 SSH 会话的支持。 |
| 1.1.17.0 | 2019 年 4 月 4 日 | **增强功能**：添加了使用 AWS Key Management Service (AWS KMS) 进一步加密会话数据的支持。 |
| 1.0.37.0 | 2018 年 9 月 20 日 | **增强功能**：Windows 版本错误修复。 |
| 1.0.0.0 | 2018 年 9 月 11 日 | 发布 Session Manager 插件的初始版本。 |
# 在 Windows 上安装 Session Manager 插件
您可以使用独立安装程序在 Windows Vista 上安装 Session Manager 插件。
更新发布后，您必须重复安装过程以获取最新版本的 Session Manager 插件。
**注意**
请注意以下信息。
Session Manager 插件安装程序需要管理员权限才能安装插件。
为获得最佳效果，建议使用 Windows PowerShell 版本 5 或更高版本在 Windows 客户端上启动会话。或者，您可以在 Windows 10 中使用 Shell 命令。Session Manager 插件只支持 PowerShell 和 Shell 命令。第三方命令行工具可能与此插件不兼容。
**要使用 EXE 安装程序安装 Session Manager 插件，请执行以下步骤：**
1. 使用以下 URL 下载安装程序。
```
https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe
```
或者，您可以访问以下 URL 以下载安装程序的 zip 格式版本。
```
https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPlugin.zip
```
1. 运行下载的安装程序并按照屏幕上的说明操作。如果您下载了安装程序的 zip 格式版本，则必须先解压缩安装程序。
将安装位置框留空以将插件安装到默认目录。
+ `%PROGRAMFILES%\Amazon\SessionManagerPlugin\bin\`
1. 验证安装是否成功。有关信息，请参阅[验证 Session Manager 插件安装](install-plugin-verify.md)。
**注意**
如果 Windows 无法找到可执行文件，您需要重新打开命令提示符或手动将安装目录添加到 `PATH` 环境变量。有关信息，请参阅故障排除主题 [Session Manager 插件未自动添加到命令行路径（Windows）](session-manager-troubleshooting.md#windows-plugin-env-var-not-set)。
# 在 macOS 上安装 Session Manager 插件
选择以下主题之一，在 macOS 上安装 Session Manager 插件。
**注意**
签名的安装程序是一个签名的 `.pkg` 文件。捆绑的安装程序使用 `.zip` 文件。文件解压缩后，您可以使用二进制文件安装插件。
## 使用已签名的安装程序在 macOS 上安装 Session Manager 插件
本节介绍如何使用已签名的安装程序在 macOS 上安装 Session Manager 插件。
**要使用已签名的安装程序安装 Session Manager 插件 (macOS)，请执行以下步骤：**
1. 下载已签名的安装程序。
------
#### [ x86\$164 ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"
```
------
#### [ 搭载 Apple 硅芯片的 Mac ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"
```
------
1. 运行安装命令。如果命令失败，确认 `/usr/local/bin` 文件夹是否存在。如果不存在，创建后再次运该此命令。
```
sudo installer -pkg session-manager-plugin.pkg -target /
sudo ln -s /usr/local/sessionmanagerplugin/bin/session-manager-plugin /usr/local/bin/session-manager-plugin
```
1. 验证安装是否成功。有关信息，请参阅[验证 Session Manager 插件安装](install-plugin-verify.md)。
## 在 macOS 上安装 Session Manager 插件
本节介绍如何使用捆绑安装程序在 macOS 上安装 Session Manager 插件。
**重要**
请注意以下重要信息。
默认情况下，安装程序需要 sudo 访问权限才能运行，因为脚本会将插件安装到 `/usr/local/sessionmanagerplugin` 系统目录中。如果不想使用 sudo 安装插件，则手动更新安装程序脚本，将插件安装到不需要 sudo 访问权限的目录中。
捆绑安装程序不支持安装到包含空格的路径。
**要使用捆绑安装程序安装 Session Manager 插件 (macOS)，请执行以下步骤：**
1. 下载捆绑安装程序。
------
#### [ x86\$164 ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
```
------
#### [ 搭载 Apple 硅芯片的 Mac ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
```
------
1. 解压缩程序包。
```
unzip sessionmanager-bundle.zip
```
1. 运行安装命令。
```
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin
```
**注意**
该插件需要 Python 3.10 或更高版本。默认情况下，安装脚本在系统默认版本的 Python 下运行。如果已安装 Python 的可选版本并希望使用该版本安装 Session Manager 插件，请使用该版本按 Python 可执行文件的绝对路径运行安装脚本。示例如下：
```
sudo /usr/local/bin/python3.11 sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin
```
安装程序在 `/usr/local/sessionmanagerplugin` 中安装 Session Manager 插件，并在 `/usr/local/bin` 目录中创建符号链接 `session-manager-plugin`。这样，不必在用户的 `$PATH` 变量中指定安装目录。
要查看 `-i` 和 `-b` 选项的说明，请使用 `-h` 选项。
```
./sessionmanager-bundle/install -h
```
1. 验证安装是否成功。有关信息，请参阅[验证 Session Manager 插件安装](install-plugin-verify.md)。
**注意**
如果需要卸载此插件，请按照所示顺序运行以下两个命令。
```
sudo rm -rf /usr/local/sessionmanagerplugin
```
```
sudo rm /usr/local/bin/session-manager-plugin
```
# 在 Linux 上安装 Session Manager 插件
本节包含有关验证Session Manager插件安装程序包的签名，以及在以下 Linux 发行版上安装插件的信息：
+ Amazon Linux 2
+ AL2023
+ RHEL
+ Debian Server
+ Ubuntu Server
**Topics**
+ [验证 Session Manager 插件的签名](install-plugin-linux-verify-signature.md)
+ [在 Amazon Linux 2、Amazon Linux 2023 和 Red Hat Enterprise Linux 发行版上安装 Session Manager 插件](install-plugin-linux.md)
+ [在 Debian Server 和 Ubuntu Server 上安装 Session Manager 插件](install-plugin-debian-and-ubuntu.md)
# 验证 Session Manager 插件的签名
适用于 Linux 实例的 Session Manager 插件 RPM 和 Debian 安装包是以加密方式签名的。您可以使用公有密钥验证插件二进制文件和软件包是否为未修改的原始包。如果文件有任何更改或损坏，则验证将失败。您可以使用 GNU Privacy Guard（GPG）工具验证安装包的签名。以下信息适用于 Session Manager 插件版本 1.2.707.0 或更高版本。
完成以下步骤以验证 Session Manager 插件安装包的签名。
**Topics**
+ [步骤 1：下载 Session Manager 插件安装包](#install-plugin-linux-verify-signature-installer-packages)
+ [步骤 2：下载关联的签名文件](#install-plugin-linux-verify-signature-packages)
+ [步骤 3：安装 GPG 工具](#install-plugin-linux-verify-signature-packages-gpg)
+ [步骤 4：验证 Linux 服务器上的 Session Manager 插件安装包](#install-plugin-linux-verify-signature-packages)
## 步骤 1：下载 Session Manager 插件安装包
下载您要验证的 Session Manager 插件安装包。
**Amazon Linux 2、AL2023 和 RHEL RPM 软件包**
------
#### [ x86\$164 ]
```
curl -o "session-manager-plugin.rpm" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm"
```
------
#### [ ARM64 ]
```
curl -o "session-manager-plugin.rpm" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm"
```
------
**Debian Server 和 Ubuntu Server Deb 软件包**
------
#### [ x86\$164 ]
```
curl -o "session-manager-plugin.deb" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb"
```
------
#### [ ARM64 ]
```
curl -o "session-manager-plugin.deb" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_arm64/session-manager-plugin.deb"
```
------
## 步骤 2：下载关联的签名文件
下载安装包后，请下载相关的签名文件以进行软件包验证。为了提供额外的保护，以防止未经授权的复制或使用软件包内的 session-manager-plugin 二进制文件，我们还提供了二进制签名，您可以使用该签名来验证单个二进制文件。您可以根据自己的安全需求来选择使用这些二进制签名。
**Amazon Linux 2、AL2023 和 RHEL 签名软件包**
------
#### [ x86\$164 ]
软件包：
```
curl -o "session-manager-plugin.rpm.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm.sig"
```
二进制文件：
```
curl -o "session-manager-plugin.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.sig"
```
------
#### [ ARM64 ]
软件包：
```
curl -o "session-manager-plugin.rpm.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm.sig"
```
二进制文件：
```
curl -o "session-manager-plugin.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.sig"
```
------
**Debian Server 和 Ubuntu Server Deb 签名软件包**
------
#### [ x86\$164 ]
软件包：
```
curl -o "session-manager-plugin.deb.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb.sig"
```
二进制文件：
```
curl -o "session-manager-plugin.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.sig"
```
------
#### [ ARM64 ]
软件包：
```
curl -o "session-manager-plugin.deb.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_arm64/session-manager-plugin.deb.sig"
```
二进制文件：
```
curl -o "session-manager-plugin.sig" "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_arm64/session-manager-plugin.sig"
```
------
## 步骤 3：安装 GPG 工具
要验证 Session Manager 插件的签名，您必须在系统上安装 GNU 隐私保护（GPG）工具。此验证过程需要使用 GPG 版本 2.1 或更高版本。可以运行以下命令查看 GPG 版本：
```
gpg --version
```
如果您的 GPG 版本低于 2.1，则请在继续验证过程之前进行版本更新。对于大多数系统，您可以使用软件包管理程序更新 GPG 工具。例如，在受支持的 Amazon Linux 和 RHEL 版本上，您可以使用以下命令：
```
sudo yum update
sudo yum install gnupg2
```
在支持的 Ubuntu Server 和 Debian Server 系统上，您可以使用以下命令：
```
sudo apt-get update
sudo apt-get install gnupg2
```
在继续验证过程之前，请确保您具有所需的 GPG 版本。
## 步骤 4：验证 Linux 服务器上的 Session Manager 插件安装包
请按照以下程序验证 Linux 服务器上的 Session Manager 插件安装包。
**注意**
Amazon Linux 2 不支持 gpg 工具版本 2.1 或更高版本。如果以下程序不适用于您的 Amazon Linux 2 实例，请在将签名安装到您的 Amazon Linux 2 实例上之前，在其他平台上验证签名。
1. 复制以下公有密钥并将其保存到名为 session-manager-plugin.gpg 的文件。
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
mFIEZ5ERQxMIKoZIzj0DAQcCAwQjuZy+IjFoYg57sLTGhF3aZLBaGpzB+gY6j7Ix
P7NqbpXyjVj8a+dy79gSd64OEaMxUb7vw/jug+CfRXwVGRMNtIBBV1MgU1NNIFNl
c3Npb24gTWFuYWdlciA8c2Vzc2lvbi1tYW5hZ2VyLXBsdWdpbi1zaWduZXJAYW1h
em9uLmNvbT4gKEFXUyBTeXN0ZW1zIE1hbmFnZXIgU2Vzc2lvbiBNYW5hZ2VyIFBs
dWdpbiBMaW51eCBTaWduZXIgS2V5KYkBAAQQEwgAqAUCZ5ERQ4EcQVdTIFNTTSBT
ZXNzaW9uIE1hbmFnZXIgPHNlc3Npb24tbWFuYWdlci1wbHVnaW4tc2lnbmVyQGFt
YXpvbi5jb20+IChBV1MgU3lzdGVtcyBNYW5hZ2VyIFNlc3Npb24gTWFuYWdlciBQ
bHVnaW4gTGludXggU2lnbmVyIEtleSkWIQR5WWNxJM4JOtUB1HosTUr/b2dX7gIe
AwIbAwIVCAAKCRAsTUr/b2dX7rO1AQCa1kig3lQ78W/QHGU76uHx3XAyv0tfpE9U
oQBCIwFLSgEA3PDHt3lZ+s6m9JLGJsy+Cp5ZFzpiF6RgluR/2gA861M=
=2DQm
-----END PGP PUBLIC KEY BLOCK-----
```
1. 将公有密钥导入到您的密钥环中。返回的密钥值应为 `2C4D4AFF6F6757EE`。
```
$ gpg --import session-manager-plugin.gpg
gpg: key 2C4D4AFF6F6757EE: public key "AWS SSM Session Manager (AWS Systems Manager Session Manager Plugin Linux Signer Key)" imported
gpg: Total number processed: 1
gpg: imported: 1
```
1. 运行以下命令验证指纹。
```
gpg --fingerprint 2C4D4AFF6F6757EE
```
命令输出的指纹应与以下内容匹配。
```
7959 6371 24CE 093A D501 D47A 2C4D 4AFF 6F67 57EE
```
```
pub nistp256 2025-01-22 [SC]
7959 6371 24CE 093A D501 D47A 2C4D 4AFF 6F67 57EE
uid [ unknown] AWS SSM Session Manager (AWS Systems Manager Session Manager Plugin Linux Signer Key)
```
如果指纹不匹配，则请勿安装插件。联系 AWS 支持。
1. 验证安装程序包签名。将 *signature-filename* 和 *downloaded-plugin-filename* 替换为下载签名文件和 session-manager-plugin 时指定的值，如本主题前面的表中所列。
```
gpg --verify signature-filename downloaded-plugin-filename
```
例如，对于 Amazon Linux 2 上的 x86\$164 架构，命令如下所示：
```
gpg --verify session-manager-plugin.rpm.sig session-manager-plugin.rpm
```
该命令会返回类似以下内容的输出。
```
gpg: Signature made Mon Feb 3 20:08:32 2025 UTC gpg: using ECDSA key 2C4D4AFF6F6757EE
gpg: Good signature from "AWS Systems Manager Session Manager (AWS Systems Manager Session Manager Plugin Linux Signer Key)" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7959 6371 24CE 093A D501 D47A 2C4D 4AFF 6F67 57EE
```
如果输出包含短语 `BAD signature`，则检查是否正确执行了此过程。如果您继续获得该响应，则请联系 AWS 支持 且不要安装该软件包。有关信任的警告消息并不意味着签名无效，只是您尚未验证公有密钥而已。只有当您或您信任的某个人对密钥进行了签名，密钥才是可信的。如果输出包含短语 `Can't check signature: No public key`，则验证您下载的 Session Manager 插件是版本 1.2.707.0 或更高版本。
# 在 Amazon Linux 2、Amazon Linux 2023 和 Red Hat Enterprise Linux 发行版上安装 Session Manager 插件
按照以下步骤在 Amazon Linux 2、Amazon Linux 2023 (AL2023) 和 RHEL 发行版上安装 Session Manager 插件
1. 下载和安装 Session Manager 插件 RPM 软件包。
------
#### [ x86\$164 ]
在 Amazon Linux 2 和 RHEL 7 上，运行以下命令：
```
sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm
```
在 AL2023 以及 RHEL 8 和 9 上，运行以下命令：
```
sudo dnf install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm
```
------
#### [ ARM64 ]
在 Amazon Linux 2 和 RHEL 7 上，运行以下命令：
```
sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm
```
在 AL2023 以及 RHEL 8 和 9 上，运行以下命令：
```
sudo dnf install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_arm64/session-manager-plugin.rpm
```
------
1. 验证安装是否成功。有关信息，请参阅[验证 Session Manager 插件安装](install-plugin-verify.md)。
**注意**
如果需要卸载此插件，请运行 `sudo yum erase session-manager-plugin -y`
# 在 Debian Server 和 Ubuntu Server 上安装 Session Manager 插件
1. 下载 Session Manager 插件 deb 软件包。
------
#### [ x86\$164 ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"
```
------
#### [ ARM64 ]
```
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_arm64/session-manager-plugin.deb" -o "session-manager-plugin.deb"
```
------
1. 运行安装命令。
```
sudo dpkg -i session-manager-plugin.deb
```
1. 验证安装是否成功。有关更多信息，请参阅 [验证 Session Manager 插件安装](install-plugin-verify.md)。
**注意**
如果需要卸载此插件，请运行 `sudo dpkg -r session-manager-plugin`
# 验证 Session Manager 插件安装
运行以下命令验证是否已成功安装 Session Manager 插件。
```
session-manager-plugin
```
如果安装成功，将返回以下消息。
```
The Session Manager plugin is installed successfully. Use the AWS CLI to start a session.
```
您还可以通过在 [AWS Command Line Interface](https://aws.amazon.com/cli/)（AWS CLI）中运行 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html) 命令来测试安装。在下面的命令中，将 *instance-id* 替换为您自己的信息。
```
aws ssm start-session --target instance-id
```
仅当您已安装并配置了 AWS CLI，而且 Session Manager 管理员已授予您使用 Session Manager 访问目标托管式节点所需的 IAM 权限时，此命令才有效。
# GitHub 上的 Session Manager 插件
[https://github.com/aws/session-manager-plugin](https://github.com/aws/session-manager-plugin) 上提供 Session Manager 插件的源代码，便于您根据需要调整插件。我们鼓励您针对要包含的更改提交[提取请求](https://github.com/aws/session-manager-plugin/blob/mainline/CONTRIBUTING.md)。但是，Amazon Web Services 不支持运行此软件的已修改副本。
# （可选）开启 Session Manager 插件日志记录
Session Manager 插件包括一个允许对运行的会话进行日志记录的选项。默认情况下，日志记录处于关闭状态。
如果允许日志记录，则 Session Manager 插件会在本地计算机上为应用程序活动 (`session-manager-plugin.log`) 和错误 (`errors.log`) 创建日志文件。
**Topics**
+ [开启 Session Manager 插件的日志记录（Windows）](#configure-logs-windows)
+ [启用 Session Manager 插件的日志记录（Linux 和 macOS）](#configure-logs-linux)
## 开启 Session Manager 插件的日志记录（Windows）
1. 找到插件的 `seelog.xml.template` 文件。
默认位置是 `C:\Program Files\Amazon\SessionManagerPlugin\seelog.xml.template`。
1. 将文件名更改为 `seelog.xml`。
1. 打开文件，然后将 `minlevel="off"` 更改为 `minlevel="info"` 或 `minlevel="debug"`。
**注意**
默认情况下，有关打开数据通道和重新连接会话的日志条目在 **INFO** (信息) 级别记录。数据流（数据包和确认）条目在 **DEBUG** (调试) 级别记录。
1. 更改要修改的其他配置选项。可以更改的选项包括：
+ **调试级别**：您可以将调试级别从 `formatid="fmtinfo"` 更改为 `formatid="fmtdebug"`。
+ **日志文件选项**：您可以更改日志文件选项，包括日志的存储位置，但日志文件名除外。
**重要**
不要更改文件名，否则日志记录无法正常工作。
```
```
1. 保存该文件。
## 启用 Session Manager 插件的日志记录（Linux 和 macOS）
1. 找到插件的 `seelog.xml.template` 文件。
默认位置是 `/usr/local/sessionmanagerplugin/seelog.xml.template`。
1. 将文件名更改为 `seelog.xml`。
1. 打开文件，然后将 `minlevel="off"` 更改为 `minlevel="info"` 或 `minlevel="debug"`。
**注意**
默认情况下，有关打开数据通道和重新连接会话的日志条目在 **INFO** (信息) 级别记录。数据流（数据包和确认）条目在 **DEBUG** (调试) 级别记录。
1. 更改要修改的其他配置选项。可以更改的选项包括：
+ **调试级别**：您可以将调试级别从 `formatid="fmtinfo"` 更改为 `outputs formatid="fmtdebug"`。
+ **日志文件选项**：您可以更改日志文件选项，包括日志的存储位置，但日志文件名除外。
**重要**
不要更改文件名，否则日志记录无法正常工作。
```
```
**重要**
如果使用指定的默认目录存储日志，则必须使用 **sudo** 运行会话命令，或者给安装插件的目录指定完全读写权限。要绕过这些限制，请更改存储日志的位置。
1. 保存该文件。
# 启动会话
您可以使用 AWS Systems Manager 控制台、Amazon Elastic Compute Cloud (Amazon EC2) 控制台、AWS Command Line Interface (AWS CLI) 或 SSH 启动会话。
**Topics**
+ [启动会话（Systems Manager 控制台）](#start-sys-console)
+ [开启会话（Amazon EC2 控制台）](#start-ec2-console)
+ [启动会话 (AWS CLI)](#sessions-start-cli)
+ [启动会话 (SSH)](#sessions-start-ssh)
+ [启动会话（端口转发）](#sessions-start-port-forwarding)
+ [启动会话（至远程主机的端口转发）](#sessions-remote-port-forwarding)
+ [启动会话（交互式和非交互式命令）](#sessions-start-interactive-commands)
## 启动会话（Systems Manager 控制台）
您可以使用 AWS Systems Manager 控制台启动与账户中的托管式节点进行的会话。
**注意**
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
**启动会话（Systems Manager 控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择 **Start session (启动会话)**。
1. （可选）在**会话原因**字段中输入会话描述。
1. 对于**目标实例**，选择要连接的托管式节点左侧的选项按钮。
如果您需要节点不在列表中，或者如果您选择了节点并收到配置错误，请参阅 [托管式节点不可用或未为 Session Manager 配置托管式节点](session-manager-troubleshooting.md#session-manager-troubleshooting-instances)，以了解故障排除步骤。
1. 选择**启动会话**立即启动会话。
–或者–
选择**下一步**查看会话选项。
1. （可选）对于**会话文档**，选择要在会话启动时运行的文档。如果您的文档支持运行时参数，则可以在每个参数字段中输入一个或多个逗号分隔的值。
1. 选择**下一步**。
1. 选择 **Start session (启动会话)**。
建立连接后，您可以像运行任何其他连接类型一样运行 Bash 命令（Linux 和 macOS）或 PowerShell 命令（Windows）。
**重要**
如果要允许用户在会话管理器控制台中启动会话时指定文档，请注意以下几点：
您必须在用户的 IAM policy 中向其授予 `ssm:GetDocument` 和 `ssm:ListDocuments` 权限。有关更多信息，请参阅 [在控制台中授予对自定义会话文档的访问权限](getting-started-restrict-access-examples.md#grant-access-documents-console-example)。
控制台仅支持将 `sessionType` 定义为 `Standard_Stream` 的会话文档。有关更多信息，请参阅 [会话文档架构](session-manager-schema.md)。
## 开启会话（Amazon EC2 控制台）
您可以使用 Amazon Elastic Compute Cloud (Amazon EC2) 控制台来启动与账户中的实例的会话。
**注意**
如果您收到一个错误，提示您无权执行一项或多项 Systems Manager 操作 (`ssm:command-name`)，则必须联系您的管理员寻求帮助。管理员是向您提供登录凭证的人。让其帮助您更新您的策略，以允许您从 Amazon EC2 控制台启动会话。如果您是管理员，请参阅 [Session Manager 的 IAM policy 示例](getting-started-restrict-access-quickstart.md) 了解更多信息。
**要启动会话（Amazon EC2 控制台），请执行以下步骤：**
1. 通过以下网址打开 Amazon EC2 控制台：[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 在导航窗格中，选择**实例**。
1. 选择实例，然后选择**连接**。
1. 对于 **Connection method (连接方法)**，选择 **Session Manager**。
1. 选择**连接**。
建立连接后，您可以像运行任何其他连接类型一样运行 Bash 命令（Linux 和 macOS）或 PowerShell 命令（Windows）。
## 启动会话 (AWS CLI)
安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
要使用 AWS CLI 运行会话命令，还必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
要使用 AWS CLI 开启会话，请运行以下命令，将 *instance-id* 替换为您自己的信息。
```
aws ssm start-session \
--target instance-id
```
有关可以与 **start-session** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)。
## 启动会话 (SSH)
要启动 Session Manager SSH 会话，托管式节点上必须安装 2.3.672.0 版本或更高版本的 SSM Agent。
**SSH 连接要求**
对于通过Session Manager使用 SSH 的会话连接，请注意以下要求和限制：
+ 必须将目标托管式节点配置为支持 SSH 连接。有关更多信息，请参阅[（可选）通过 Session Manager 允许和控制 SSH 连接的权限](session-manager-getting-started-enable-ssh-connections.md)。
+ 您必须使用与 Privacy Enhanced Mail (PEM) 证书关联的托管式节点账户进行连接，而不是用于其他类型的会话连接的 `ssm-user` 账户。例如，在适用于 Linux 和 macOS 的 EC2 实例上，默认用户为 `ec2-user`。有关确定每种实例类型的默认用户的信息，请参阅《Amazon EC2 用户指南》**中的[获取有关您的实例的信息](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connection-prereqs.html#connection-prereqs-get-info-about-instance)。
+ 日志记录不可用于通过端口转发或 SSH 连接的 Session Manager 会话。这是因为 SSH 会对 AWS CLI 和 Session Manager 端点之间建立的安全 TLS 连接中的所有会话数据进行加密，而 Session Manager 仅用作 SSH 连接的隧道。
**注意**
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
要使用 SSH 启动会话，请运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
```
ssh -i /path/my-key-pair.pem username@instance-id
```
**提示**
当您使用 SSH 启动会话时，您可以使用以下命令格式将本地文件复制到目标托管式节点。
```
scp -i /path/my-key-pair.pem /path/ExampleFile.txt username@instance-id:~
```
有关可以与 **start-session** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)。
## 启动会话（端口转发）
要启动 Session Manager 端口转发会话，必须在托管式节点上安装 2.3.672.0 版本或更高版本的 SSM Agent。
**注意**
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
要使用 AWS CLI 运行会话命令，必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
根据您的操作系统和命令行工具，放置引号的位置可能会有所不同，并可能需要转义字符。
要启动端口转发会话，请从 CLI 中运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name AWS-StartPortForwardingSession \
--parameters '{"portNumber":["80"], "localPortNumber":["56789"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name AWS-StartPortForwardingSession ^
--parameters portNumber="3389",localPortNumber="56789"
```
------
`portNumber` 是托管式节点上您希望将会话流量重定向到的远程端口。例如，您可以指定端口 `3389`，用于使用远程桌面协议（RDP）连接到 Windows 节点。如果您未指定 `portNumber` 参数，Session Manager 会将 `80` 用作默认值。
`localPortNumber` 是本地计算机上流量启动的端口，例如 `56789`。此值是您在使用客户端连接到托管式节点时输入的值。例如 **localhost:56789**。
有关可以与 **start-session** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)。
有关端口转发会话的更多信息，请参阅 *AWS 新闻博客*中的 [Port Forwarding Using AWS Systems ManagerSession Manager](https://aws.amazon.com/blogs/aws/new-port-forwarding-using-aws-system-manager-sessions-manager/)。
## 启动会话（至远程主机的端口转发）
要启动至远程主机的 Session Manager 端口转发会话，必须在托管式节点上安装 3.1.1374.0 版本或更高版本的 SSM Agent。远程主机不需要由 Systems Manager 进行管理。
**注意**
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
要使用 AWS CLI 运行会话命令，必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
根据您的操作系统和命令行工具，放置引号的位置可能会有所不同，并可能需要转义字符。
要启动端口转发会话，请从 AWS CLI 中运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["mydb.example.us-east-2.rds.amazonaws.com"],"portNumber":["3306"], "localPortNumber":["3306"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name AWS-StartPortForwardingSessionToRemoteHost ^
--parameters host="mydb.example.us-east-2.rds.amazonaws.com",portNumber="3306",localPortNumber="3306"
```
------
`host` 值表示要连接到的远程主机的主机名或 IP 地址。托管式节点和远程主机之间的常规连接和名称解析要求仍然适用。
`portNumber` 是托管式节点上您希望将会话流量重定向到的远程端口。例如，您可以指定端口 `3389`，用于使用远程桌面协议（RDP）连接到 Windows 节点。如果您未指定 `portNumber` 参数，Session Manager 会将 `80` 用作默认值。
`localPortNumber` 是本地计算机上流量启动的端口，例如 `56789`。此值是您在使用客户端连接到托管式节点时输入的值。例如 **localhost:56789**。
有关可以与 **start-session** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)。
### 通过 Amazon ECS 任务启动会话
Session Manager 支持通过 Amazon Elastic Container Service（Amazon ECS）集群中的任务启动端口转发会话。为此，请启用 ECS Exec。有关更多信息，请参阅《Amazon Elastic Container Service 开发人员指南》**中的[使用 ECS Exec 监控 Amazon Elastic Container Service 容器](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html)。
您还必须更新 IAM 中的任务角色，以包含以下权限：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel"
],
"Resource": "*"
}
]
}
```
------
要通过 Amazon ECS 任务启动端口转发会话，请从 AWS CLI 中运行以下命令。将每个*示例资源占位符*替换为您自己的信息。
**注意**
从 `target` 参数中移除 < 和 > 符号。这些符号仅供读者澄清之用。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target ecs:__ \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["URL"],"portNumber":["port_number"], "localPortNumber":["port_number"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target ecs:__ ^
--document-name AWS-StartPortForwardingSessionToRemoteHost ^
--parameters host="URL",portNumber="port_number",localPortNumber="port_number"
```
------
## 启动会话（交互式和非交互式命令）
在启动会话之前，确保您已经完成 Session Manager 的设置步骤。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
要使用 AWS CLI 运行会话命令，还必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
要启动交互式命令会话，请运行以下命令：将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm start-session \
--target instance-id \
--document-name CustomCommandSessionDocument \
--parameters '{"logpath":["/var/log/amazon/ssm/amazon-ssm-agent.log"]}'
```
------
#### [ Windows ]
```
aws ssm start-session ^
--target instance-id ^
--document-name CustomCommandSessionDocument ^
--parameters logpath="/var/log/amazon/ssm/amazon-ssm-agent.log"
```
------
有关可以与 **start-session** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/start-session.html)。
**更多信息**
+ [在 AWS Systems Manager Session Manager 中使用端口转发连接到远程主机](https://aws.amazon.com/blogs/mt/use-port-forwarding-in-aws-systems-manager-session-manager-to-connect-to-remote-hosts/)
+ [通过 AWS Systems Manager 实现 Amazon EC2 实例端口转发](https://aws.amazon.com/blogs/mt/amazon-ec2-instance-port-forwarding-with-aws-systems-manager/)
+ [通过 Session Manager 端口转发管理 AWS 托管的 Microsoft AD 资源](https://aws.amazon.com/blogs/mt/manage-aws-managed-microsoft-ad-resources-with-session-manager-port-forwarding/)
+ *AWS 新闻博客*上的 [Port Forwarding Using AWS Systems ManagerSession Manager](https://aws.amazon.com/blogs/aws/new-port-forwarding-using-aws-system-manager-sessions-manager/)。
# 结束会话
您可以使用 AWS Systems Manager 控制台或 AWS Command Line Interface（AWS CLI）结束在账户中启动的会话。如果您在控制台中选择会话的**终止**按钮或使用 AWS CLI 来调用 [TerminateSession](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_TerminateSession.html) API 操作时，Session Manager 会永久结束会话并关闭托管式节点上 Session Manager 客户端与 SSM Agent 之间的数据连接。您无法恢复已终止的会话。
如果打开的会话在 20 分钟内没有用户活动，空闲状态就会触发超时。Session Manager 不会调用 `TerminateSession`，但会关闭底层通道。您无法恢复因空闲超时而关闭的会话。
建议在使用 AWS CLI 时始终通过 `terminate-session` 命令明确终止会话，或者在使用控制台时通过**终止**按钮明确终止会话。（**终止**按钮位于会话窗口和主 Session Manager 控制台页面。） 如果仅关闭浏览器或命令窗口，则会话将在控制台中保持为**活动状态** 30 天。如果未明确终止会话或会话超时，则当时在托管式节点上运行的所有进程都将继续运行。
**Topics**
+ [结束会话（控制台）](#stop-sys-console)
+ [结束会话 (AWS CLI)](#stop-cli)
## 结束会话（控制台）
您可以使用 AWS Systems Manager 控制台结束您账户中的会话。
**结束会话（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Session Manager**。
1. 对于 **Sessions (会话)**，选择要结束的会话左侧的选项按钮。
1. 选择**终止**。
## 结束会话 (AWS CLI)
要使用 AWS CLI 结束会话，请运行以下命令。将 *session-id* 替换为您自己的信息。
```
aws ssm terminate-session \
--session-id session-id
```
有关 **terminate-session** 命令的更多信息，请参阅《AWS CLI Command Reference》的 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/terminate-session.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/terminate-session.html)。
# 查看会话历史记录
您可以使用 AWS Systems Manager 控制台或 AWS Command Line Interface (AWS CLI) 查看有关账户中的会话的信息。在控制台中，您可以查看会话详细信息，如下所示：
+ 会话 ID
+ 通过会话连接到托管式节点的用户
+ 托管式节点的 ID
+ 会话的开始和结束时间
+ 会话的状态
+ 指定用于存储会话日志的位置（如果开启）
使用 AWS CLI，您可以查看账户中会话的列表，但无法查看控制台中可用的其他详细信息。
有关记录会话历史记录的信息，请参阅 [启用和禁用会话日志记录](session-manager-logging.md)。
**Topics**
+ [查看会话历史记录（控制台）](#view-console)
+ [查看会话历史记录 (AWS CLI)](#view-history-cli)
## 查看会话历史记录（控制台）
您可以使用 AWS Systems Manager 控制台查看账户中的会话的详细信息。
**查看会话历史记录（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择 **Session history (会话历史记录)** 选项卡。
–或者–
如果 Session Manager 主页首先打开，请选择**配置首选项**，然后选择**会话历史记录**选项卡。
## 查看会话历史记录 (AWS CLI)
要使用 AWS CLI 查看账户中会话的列表，请运行以下命令。
```
aws ssm describe-sessions \
--state History
```
**注意**
此命令仅返回与使用 Session Manager 启动的目标所进行的连接的结果。它不列出通过远程桌面协议 (RDP) 或 Secure Shell 协议 (SSH) 等其他方式建立的连接。
有关可以与 **describe-sessions** 命令结合使用的其他选项的信息，请参阅《AWS CLI Command Reference》中 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-sessions.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-sessions.html)。
# 记录会话活动
除了在 Systems Manager 控制台中提供有关当前和已完成会话的信息以外，Session Manager还提供使用 AWS CloudTrail 记录您的 AWS 账户中的会话活动的功能。
CloudTrail 可以捕获通过 Systems Manager 控制台、AWS Command Line Interface (AWS CLI) 和 Systems Manager SDK 进行的 API 调用。您可以在 CloudTrail 控制台查看信息，或将其存储在指定的 Amazon Simple Storage Service (Amazon S3) 存储桶中。您可以将账户的所有 CloudTrail 日志存储在一个 Amazon S3 存储桶中。有关更多信息，请参阅 [使用 AWS CloudTrail 记录 AWS Systems Manager API 调用](monitoring-cloudtrail-logs.md)。
**注意**
对于定期的、历史的、分析性的日志文件分析，请考虑使用 [CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) 或您维护的表来查询 CloudTrail 日志。有关更多信息，请参阅《AWS CloudTrail 用户指南》**中的[查询 AWS CloudTrail 日志](https://docs.aws.amazon.com/athena/latest/ug/cloudtrail-logs.html)。
## 使用 Amazon EventBridge 监控会话活动（控制台）
使用 EventBridge，您可以设置规则来检测 AWS 资源何时发生更改。您可以创建规则来检测组织中的用户何时启动或结束会话，然后通过 Amazon SNS 接收有关此事件的通知等。
EventBridge 对 Session Manager 的支持依赖于 CloudTrail 记录的 API 操作记录。（您可以使用 CloudTrail 与 Eventbridge 集成来响应大多数 AWS Systems Manager 事件。） EventBridge 检测不到会话中发生的未进行 API 调用的操作，如 `exit` 命令。
以下步骤概述了如何在发生 Session Manager API 事件（如 **StartSession**）时通过 Amazon Simple Notification Service (Amazon SNS) 启动通知。
**要使用 Amazon EventBridge 监控会话活动（控制台），请执行以下步骤：**
1. 创建 Amazon SNS 主题，以便在发生要跟踪的 Session Manager 事件时发送通知。
有关更多信息，请参阅《Amazon Simple Notification Service 开发人员指南》**中的[创建主题](https://docs.aws.amazon.com/sns/latest/dg/CreateTopic.html)。
1. 创建 Eventbridge 规则来调用要跟踪的 Session Manager 事件类型的 Amazon SNS 目标。
要了解如何创建规则，请参阅《Amazon EventBridge 用户指南》中的[创建对事件作出反应的 Amazon EventBridge 规则](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html)。
遵循步骤创建规则时，请做出以下选择：
+ 对于 ** service**（AWS 服务），选择 **Systems Manager**。
+ 对于 **Event type**（事件类型），选择 **AWS API Call through CloudTrail**（通过 CloudTrail 进行的 API 调用）。
+ 选择**特定操作**，然后输入要接收其通知的一个或多个 Session Manager 命令（一次一个）。您可以选择 **StartSession**、**ResumeSession** 和 **TerminateSession**。（EventBridge 不支持 `Get*`、` List*` 和 `Describe*` 命令。）
+ 对于 **Select a target**（选择一个目标），选择 **SNS topic**（SNS 主题）。对于 **Topic (主题)**，选择您在步骤 1 中创建的 Amazon SNS 主题的名称。
有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)和 [Amazon Simple Notification Service 入门指南](https://docs.aws.amazon.com/sns/latest/gsg/)。****
# 启用和禁用会话日志记录
会话日志记录在 Systems Manager 控制台中记录有关当前会话和已完成会话的信息。您还可以在 AWS 账户 中记录有关会话期间运行的命令的详细信息。会话日志记录允许您执行以下操作：
+ 创建和存储会话日志以用于存档目的。
+ 生成报告，显示过去 30 天内使用 Session Manager 对托管式节点进行的每个连接的详细信息。
+ 生成有关 AWS 账户 中的会话活动的通知，例如 Amazon Simple Notification Service（Amazon SNS）通知。
+ 作为会话期间所执行操作的结果，在 AWS 资源上自动启动另一个操作，例如运行 AWS Lambda 功能、启动 AWS CodePipeline 管道或运行 AWS Systems Manager Run Command 文档。
**重要**
请注意Session Manager的以下要求和限制：
Session Manager 根据您的会话首选项，记录您在会话期间输入的命令及其输出。为了防止敏感数据（如密码）在会话日志中被查看，建议您在会话期间输入敏感数据时使用以下命令。
```
stty -echo; read passwd; stty echo;
```
```
$Passwd = Read-Host -AsSecureString
```
如果使用的是 Windows Server 2012 或更早版本，则日志中的数据可能无法以最佳方式进行格式化。建议使用 Windows Server 2012 R2 及更高版本以获得最佳的日志格式。
如果使用的是 Linux 或 macOS 托管式节点，请确保已安装 screen 实用工具。否则，日志数据可能会被截断。在 Amazon Linux 2、AL2023 和 Ubuntu Server 上，默认会安装 screen 实用工具。要手动安装 screen，请根据您的 Linux 版本，运行 `sudo yum install screen` 或 `sudo apt-get install screen`。
日志记录不可用于通过端口转发或 SSH 连接的 Session Manager 会话。这是因为 SSH 会对 AWS CLI 和 Session Manager 端点之间建立的安全 TLS 连接中的所有会话数据进行加密，而 Session Manager 仅用作 SSH 连接的隧道。
有关使用 Amazon S3 或 Amazon CloudWatch Logs 记录会话数据所需权限的更多信息，请参阅 [创建具有 Session Manager、Amazon S3 和 CloudWatch Logs 权限的 IAM 角色（控制台）](getting-started-create-iam-instance-profile.md#create-iam-instance-profile-ssn-logging)。
有关 Session Manager 的日志记录选项的更多信息，请参阅以下主题。
**Topics**
+ [使用 Amazon CloudWatch Logs 流式传输会话数据（控制台）](session-manager-logging-cwl-streaming.md)
+ [使用 Amazon S3 记录会话数据（控制台）](session-manager-logging-s3.md)
+ [使用 Amazon CloudWatch Logs 记录会话数据（控制台）](session-manager-logging-cloudwatch-logs.md)
+ [配置会话日志记录到磁盘](session-manager-logging-disk.md)
+ [调整Session Manager临时日志文件在磁盘上的存储时间](session-manager-logging-disk-retention.md)
+ [禁用 CloudWatch Logs 和 Amazon S3 中的 Session Manager 日志记录](session-manager-enable-and-disable-logging.md)
# 使用 Amazon CloudWatch Logs 流式传输会话数据（控制台）
您可以向 Amazon CloudWatch Logs 持续发送会话数据日志流。在流式传输会话数据时，将包括必要的详细信息，例如用户在会话中运行的命令、运行命令的用户的 ID，以及将会话数据流式传输到 CloudWatch Logs 的时间戳。流式传输会话数据时，日志采用 JSON 格式，以帮助您与现有的日志记录解决方案相集成。交互式命令不支持流式传输会话数据。
**注意**
要从 Windows Server 托管式节点流式传输会话数据，必须安装 PowerShell 5.1 或更高版本。默认情况下，Windows Server 2016 及更高版本已安装了所需的 PowerShell 版本。但是，默认情况下，Windows Server 2012 和 2012 R2 没有安装所需的 PowerShell 版本。如果您尚未在 PowerShell 2012 或 2012 R2 托管式节点上更新 Windows Server，可以使用 Run Command 执行此操作。有关使用 Run Command 更新 PowerShell 的信息，请参阅 [使用 Run Command 更新 PowerShell](run-command-tutorial-update-software.md#rc-console-pwshexample)。
**重要**
如果您在 Windows Server 托管式节点上配置了 **PowerShell 转录**策略设置，则将无法流式传输会话数据。
**要使用 Amazon CloudWatch Logs 流式传输会话数据（控制台），请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中 **CloudWatch logging (CloudWatch 日志记录)** 下 **Enable (启用)** 旁边的复选框。
1. 选择 **Stream session logs (流式传输会话日志)** 选项。
1. （推荐）选中 **Allow only encrypted CloudWatch log groups (仅允许加密的 CloudWatch 日志组)** 旁边的复选框。否则，日志数据将使用为日志组指定的服务器端加密密钥加密。如果您希望加密发送到 CloudWatch Logs 的日志数据，请清除此复选框。如果日志组不允许加密，也必须清除此复选框。
1. 对于 **CloudWatch logs (CloudWatch Logs 日志)**，要指定 AWS 账户中现有的 CloudWatch Logs 日志组来上传会话日志，请选择以下选项之一：
+ 在文本框中输入已在账户中创建的用于存储会话日志数据的日志组的名称。
+ **Browse log groups (浏览日志组)**：选择已在账户中创建的用于存储会话日志数据的日志组。
1. 选择**保存**。
# 使用 Amazon S3 记录会话数据（控制台）
您可以选择将会话日志数据存储在指定的 Amazon Simple Storage Service (Amazon S3) 存储桶中，以便用于调试和故障排除。默认选项是将日志发送到加密的 Amazon S3 存储桶。系统将使用为存储桶指定的密钥执行加密，可以是 AWS KMS key或 Amazon S3 服务器端加密 (SSE) 密钥 (AES-256)。
**重要**
当通过安全套接字 (SSL) 使用虚拟托管类型存储桶时，SSL 通配符证书仅匹配不包含句点的存储桶。要解决此问题，请使用 HTTP 或编写自己的证书验证逻辑。在使用虚拟托管类型存储桶时，建议您不要在存储桶名称中使用句点（“.”）。
**Amazon S3 存储桶加密**
要将日志发送到 Amazon S3 存储桶并进行加密，必须在存储桶上允许加密。有关 Amazon S3 存储桶加密的更多信息，请参阅 [Amazon S3 默认 S3 存储桶加密](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html)。
**客户托管密钥**
如果使用自己管理的 KMS 密钥来加密存储桶，则附加到实例的 IAM 实例配置文件必须具有读取此密钥的显式权限。如果使用 AWS 托管式密钥，则实例不需要此显式权限。有关为实例配置文件提供使用密钥的权限的更多信息，请参阅《AWS Key Management Service 开发人员指南》中的[允许密钥用户使用密钥](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-users)。**
请按照以下步骤配置 Session Manager，以将会话日志存储在 Amazon S3 存储桶中。
**注意**
您也可以使用 AWS CLI 指定或更改将会话数据发送到的 Amazon S3 存储桶。有关信息，请参阅[更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md)。
**要使用 Amazon S3 记录会话数据（控制台），请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中 **S3 logging (S3 日志记录)** 下 **Enable (启用)** 旁边的复选框。
1. （推荐）选中 **Allow only encrypted S3 buckets (仅允许加密的 S3 存储桶)** 旁边的复选框。开启此选项后，将使用为存储桶指定的服务器端加密密钥对日志数据进行加密。如果不需要加密发送到 Amazon S3 的日志数据，请清除此复选框。如果 S3 存储桶不允许加密，也必须清除此复选框。
1. 对于 **S3 bucket name (S3 存储桶名称)**，请选择以下选项之一：
**注意**
在使用虚拟托管类型存储桶时，建议您不要在存储桶名称中使用句点（“.”）。有关 Amazon S3 存储桶命名约定的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[存储桶限制和局限性](https://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html#bucketnamingrules)。
+ **Choose a bucket name from the list (从列表中选择存储桶名称)**：选择已在账户中创建的用于存储会话日志数据的 Amazon S3 存储桶。
+ **Enter a bucket name in the text box (在文本框中输入存储桶名称)**：输入已在账户中创建的用于存储会话日志数据的 Amazon S3 存储桶名称。
1. （可选）对于 **S3 key prefix (S3 键前缀)**，输入现有或新文件夹的名称，以便将日志存储在所选的存储桶中。
1. 选择**保存**。
有关使用 Amazon S3 和 Amazon S3 存储桶的更多信息，请参阅 *[Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)*和 *[Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)*。
# 使用 Amazon CloudWatch Logs 记录会话数据（控制台）
借助 Amazon CloudWatch Logs，您可以监控、存储和访问各种 AWS 服务的日志文件。您可以将会话日志数据发送到 CloudWatch Logs 日志组，以便用于调试和故障排除。默认选项是使用您的 KMS 密钥在加密后发送日志数据，但您可以将数据发送到日志组（加密或不加密）。
请按照以下步骤配置 AWS Systems Manager Session Manager，以便在会话结束时将会话日志数据发送到 CloudWatch Logs 日志组。
**注意**
您也可以使用 AWS CLI 指定或更改将会话数据发送到的 CloudWatch Logs 日志组。有关信息，请参阅[更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md)。
**要使用 Amazon CloudWatch Logs 记录会话数据（控制台），请执行以下步骤：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 选中 **CloudWatch logging (CloudWatch 日志记录)** 下 **Enable (启用)** 旁边的复选框。
1. 选择 **Upload session logs (上传会话日志)** 选项。
1. （推荐）选中 **Allow only encrypted CloudWatch log groups (仅允许加密的 CloudWatch 日志组)** 旁边的复选框。否则，日志数据将使用为日志组指定的服务器端加密密钥加密。如果您希望加密发送到 CloudWatch Logs 的日志数据，请清除此复选框。如果日志组不允许加密，也必须清除此复选框。
1. 对于 **CloudWatch logs (CloudWatch Logs 日志)**，要指定 AWS 账户中现有的 CloudWatch Logs 日志组来上传会话日志，请选择以下选项之一：
+ **Choose a log group from the list (从列表中选择日志组)**：选择已在账户中创建的日志组来存储会话日志数据。
+ **Enter a log group name in the text box (在文本框中输入日志组名称)**：输入已在您的账户中创建的用于存储会话日志数据的日志组的名称。
1. 选择**保存**。
有关使用 CloudWatch Logs 的更多信息，请参阅 [Amazon CloudWatch Logs 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)。**
# 配置会话日志记录到磁盘
在启用Session Manager日志记录到 CloudWatch 或 Amazon S3 后，会话期间执行的所有命令（以及这些命令产生的输出）都将记录到目标实例磁盘上的临时文件中。临时文件的名称为 `ipcTempFile.log`。
`ipcTempFile.log` 由 SSM Agent 配置文件中的 `SessionLogsDestination` 参数控制。此参数接受以下值：
+ **disk**：如果指定此参数并且*启用*会话日志记录到 CloudWatch 或 Amazon S3，则 SSM Agent 将创建 `ipcTempFile.log` 临时日志文件并将会话命令和输出记录到磁盘。Session Manager会在会话期间或结束后将此日志上传到 CloudWatch 或 S3，具体取决于日志记录配置。然后根据为 SSM Agent `SessionLogsRetentionDurationHours` 配置参数指定的持续时间删除日志。
如果指定此参数并*禁用*会话日志记录到 CloudWatch 和 Amazon S3，则 SSM Agent 仍会在 `ipcTempFile.log` 文件中记录命令历史记录和输出。然后将根据为 SSM Agent `SessionLogsRetentionDurationHours` 配置参数指定的持续时间删除该文件。
+ **none**：如果指定此参数并且*启用*会话日志记录到 CloudWatch 或 Amazon S3，则日志记录到磁盘的工作方式与您指定 `disk` 参数时完全相同。当启用会话日志记录到 CloudWatch 或 Amazon S3 时，SSM Agent 需要临时文件。
如果指定此参数并*禁用*会话日志记录到 CloudWatch 或 Amazon S3，则 SSM Agent 不会创建 `ipcTempFile.log` 文件。
使用以下过程启用或禁用在启动会话时在磁盘上创建 `ipcTempFile.log` 临时日志文件。
**启用或禁用在磁盘上创建Session Manager临时日志文件**
1. 在您的实例上安装 SSM Agent 或升级到版本 3.2.2086 或更高版本。有关如何检查代理版本号的信息，请参阅[正在检查 SSM Agent 版本号](ssm-agent-get-version.md)。有关如何手动安装代理的信息，请在以下部分中找到适合您的操作系统的过程：
+ [在适用于 Linux 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-linux.md)
+ [在适用于 macOS 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-macos.md)
+ [在适用于 Windows Server 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-windows.md)
1. 连接到您的实例并在以下位置找到 `amazon-ssm-agent.json` 文件。
+ **Linux**：/etc/amazon/ssm/
+ **macOS**：/opt/aws/ssm/
+ **Windows Server**：C:\$1Program Files\$1Amazon\$1SSM
如果文件 `amazon-ssm-agent.json` 不存在，请将 `amazon-ssm-agent.json.template` 的内容复制到同一目录中的新文件中。将新文件命名为 `amazon-ssm-agent.json`。
1. 为 `SessionLogsDestination` 参数指定 `none` 或 `disk`。保存更改。
1. [重启](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-status-and-restart.html) SSM Agent。
如果为 `SessionLogsDestination` 参数指定了 `disk`，则可以通过启动新会话，然后在以下位置找到 `ipcTempFile.log` 来验证 SSM Agent 是否创建了临时日志文件：
+ **Linux**：/var/lib/amazon/ssm/*目标 ID*/session/orchestration/*会话 ID*/Standard\$1Stream/ipcTempFile.log
+ **macOS**：/opt/aws/ssm/data/*目标 ID*/session/orchestration/*会话 ID*/Standard\$1Stream/ipcTempFile.log
+ **Windows Server**：C:\$1ProgramData\$1Amazon\$1SSM\$1InstanceData\$1*目标 ID*\$1session\$1orchestration\$1*会话 ID*\$1Standard\$1Stream\$1ipcTempFile.log
**注意**
默认情况下，临时日志文件会在实例上保存 14 天。
如果您想要更新多个实例中的 `SessionLogsDestination` 参数，我们建议您创建一个指定新配置的 SSM 文档。然后，您可以使用 Systems Manager Run Command 在实例上实施更改。有关更多信息，请参阅 [Writing your own AWS Systems Manager documents (blog)](https://aws.amazon.com/blogs/mt/writing-your-own-aws-systems-manager-documents/) 和[在托管节点上运行命令](running-commands.md)。
# 调整Session Manager临时日志文件在磁盘上的存储时间
在启用Session Manager日志记录到 CloudWatch 或 Amazon S3 后，会话期间执行的所有命令（以及这些命令产生的输出）都将记录到目标实例磁盘上的临时文件中。临时文件的名称为 `ipcTempFile.log`。在会话期间或会话完成后，Session Manager会将此临时日志上传到 CloudWatch 或 S3。然后根据为 SSM Agent `SessionLogsRetentionDurationHours` 配置参数指定的持续时间删除临时日志。默认情况下，临时日志文件将在实例上的下列位置保存 14 天：
+ **Linux**：/var/lib/amazon/ssm/*目标 ID*/session/orchestration/*会话 ID*/Standard\$1Stream/ipcTempFile.log
+ **macOS**：/opt/aws/ssm/data/*目标 ID*/session/orchestration/*会话 ID*/Standard\$1Stream/ipcTempFile.log
+ **Windows Server**：C:\$1ProgramData\$1Amazon\$1SSM\$1InstanceData\$1*目标 ID*\$1session\$1orchestration\$1*会话 ID*\$1Standard\$1Stream\$1ipcTempFile.log
使用下面的步骤调整Session Manager临时日志文件在磁盘上的存储时间。
**调整 `ipcTempFile.log` 文件在磁盘上的存储时间**
1. 连接到您的实例并在以下位置找到 `amazon-ssm-agent.json` 文件。
+ **Linux**：/etc/amazon/ssm/
+ **macOS**：/opt/aws/ssm/
+ **Windows Server**：C:\$1Program Files\$1Amazon\$1SSM
如果文件 `amazon-ssm-agent.json` 不存在，请将 `amazon-ssm-agent.json.template` 的内容复制到同一目录中的新文件中。将新文件命名为 `amazon-ssm-agent.json`。
1. 将 `SessionLogsRetentionDurationHours` 的值更改为所需的小时数。如果 `SessionLogsRetentionDurationHours` 设置为 0，则将在会话期间创建临时日志文件，并在会话完成后删除该文件。此设置应确保日志文件在会话结束后不会保留。
1. 保存更改。
1. [重启](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-status-and-restart.html) SSM Agent。
# 禁用 CloudWatch Logs 和 Amazon S3 中的 Session Manager 日志记录
您可以使用 Systems Manager 控制台或 AWS CLI 禁用账户中的会话日志记录。
**要禁用会话日志记录（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Session Manager**。
1. 选择**首选项**选项卡，然后选择**编辑**。
1. 要禁用 CloudWatch 日志记录，在 **CloudWatch 日志记录**部分中清除**启用**复选框。
1. 要禁用 S3 日志记录，在 **S3 日志记录**部分中，清除**启用**复选框。
1. 选择**保存**。
**要禁用会话日志记录（AWS CLI）**
要使用 AWS CLI 禁用会话日志记录，请按照 [更新 Session Manager 首选项（命令行）](getting-started-configure-preferences-cli.md) 中的说明进行操作。
在您的 JSON 文件中，确保 `s3BucketName` 和 `cloudWatchLogGroupName` 的输入不包含任何值。例如：
```
"inputs": {
"s3BucketName": "",
...
"cloudWatchLogGroupName": "",
...
}
```
或者，要禁用日志记录，您可以从 JSON 文件中删除所有 `S3*` 和 `cloudWatch*` 输入。
**注意**
根据您的配置，在您禁用 CloudWatch 或 S3 后，SSM Agent 仍可能会在磁盘上生成一个临时日志文件。有关如何禁用日志记录到磁盘的信息，请参阅[配置会话日志记录到磁盘](session-manager-logging-disk.md)。
# 会话文档架构
以下信息介绍了会话文档的架构元素。AWS Systems Manager Session Manager 使用会话文档来确定要启动哪些类型的会话，例如标准会话、端口转发会话或运行交互式命令的会话。
[schemaVersion](#version)
会话文档的架构版本。会话文档仅支持版本 1.0。
类型：字符串
必需：是
[description](#descript)
为会话文档指定的描述。例如，“用于启动与 Session Manager 的端口转发会话的文档”。
类型：字符串
必需：否
[sessionType](#type)
会话文档用于建立的会话类型。
类型：字符串
必需：是
有效值：`InteractiveCommands` \$1 `NonInteractiveCommands` \$1 `Port` \$1 `Standard_Stream`
[inputs](#in)
用于使用此会话文档建立的会话的会话首选项。用于创建 `Standard_Stream` 会话的会话文档需要此元素。
类型：StringMap
必需：否
[s3BucketName](#bucket)
您希望在会话结束时将会话日志发送到的 Amazon Simple Storage Service (Amazon S3) 存储桶。
类型：字符串
必需：否
[s3KeyPrefix](#prefix)
将日志发送到您在输入 `s3BucketName` 时指定的 Amazon S3 存储桶时使用的前缀。有关对 Amazon S3 中存储的对象使用共享前缀的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[如何在 S3 存储桶中使用文件夹？](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html)。
类型：字符串
必需：否
[s3EncryptionEnabled](#s3Encrypt)
如果设置为 `true`，则输入 `s3BucketName` 时指定的 Amazon S3 存储桶必须进行加密。
类型：布尔值
必需：是
[cloudWatchLogGroupName](#logGroup)
您希望在会话结束时将会话日志发送到的 Amazon CloudWatch Logs (CloudWatch Logs) 组名称。
类型：字符串
必需：否
[cloudWatchEncryptionEnabled](#cwEncrypt)
如果设置为 `true`，则输入 `cloudWatchLogGroupName` 时指定的日志组必须进行加密。
类型：布尔值
必需：是
[cloudWatchStreamingEnabled](#cwStream)
如果设置为 `true`，会话数据日志流将持续发送到您在输入 `cloudWatchLogGroupName` 时指定的日志组。如果设置为 `false`，会话日志将在会话结束时发送到您在输入 `cloudWatchLogGroupName` 时指定的日志组。
类型：布尔值
必需：是
[kmsKeyId](#kms)
您要用来进一步加密本地客户端与所连接的 Amazon Elastic Compute Cloud (Amazon EC2) 托管式节点之间数据的 AWS KMS key 的 ID。
类型：字符串
必需：否
[runAsEnabled](#run)
如果设置为 `true`，则必须在 `runAsDefaultUser` 输入中指定一个存在于要连接的托管式节点上的用户账户。否则，会话将无法启动。默认情况下，会话使用 AWS Systems Manager SSM Agent 创建的 `ssm-user` 账户启动。只有连接到 Linux 和 macOS 托管节点才支持“运行身份”功能。
类型：布尔值
必需：是
[runAsDefaultUser](#runUser)
当 `runAsEnabled` 输入设置为 `true` 时，用于在 Linux 和 macOS 托管节点上启动会话的用户账户的名称。您为此输入指定的用户账户必须存在于要连接的托管式节点上；否则，会话将无法启动。
类型：字符串
必需：否
[idleSessionTimeout](#timeout)
结束会话前允许处于非活动状态的时间长度。此输入以分钟为单位。
类型：字符串
有效值：1-60
必需：否
[maxSessionDuration](#maxDuration)
会话结束前允许的最长时间。此输入以分钟为单位。
类型：字符串
有效值：1-1440
必需：否
[shellProfile](#shell)
根据操作系统指定的要在会话中应用的首选项，例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。
类型：StringMap
必需：否
[windows](#win)
为 Windows Server 托管式节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。
类型：字符串
必需：否
[linux](#lin)
为 Linux 和 macOS 托管节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。
类型：字符串
必需：否
[parameters](#param)
定义文档接受的参数的对象。有关定义文档参数的更多信息，请参阅[顶级数据元素](documents-syntax-data-elements-parameters.md#top-level)中的**参数**。对于经常引用的参数，建议在 Systems Manager Parameter Store 中存储这些参数，以便进行引用。您可以在文档的这一部分引用 `String` 和 `StringList` Parameter Store 参数。您不能在文档的这一部分引用 `SecureString` Parameter Store 参数。您可以使用以下格式引用 Parameter Store 参数：
```
{{ssm:parameter-name}}
```
有关 Parameter Store 的更多信息，请参阅 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)。
类型：StringMap
必需：否
[properties](#props)
在 `StartSession` API 操作中使用的一个对象，其值由您指定。
对于用于 `InteractiveCommands` 会话的会话文档，属性对象包含要在您指定的操作系统上运行的命令。您还可以 `runAsElevated` 布尔属性来确定命令是否作为 `root` 运行。有关更多信息，请参阅[限制对会话中命令的访问](session-manager-restrict-command-access.md)。
对于用于 `Port` 会话的会话文档，属性对象包含应将流量重定向到的端口号。有关示例，请参阅本主题后文中的 `Port` 类型会话文档示例。
类型：StringMap
必需：否
`Standard_Stream` 类型会话文档示例
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Document to hold regional settings for Session Manager
sessionType: Standard_Stream
inputs:
s3BucketName: ''
s3KeyPrefix: ''
s3EncryptionEnabled: true
cloudWatchLogGroupName: ''
cloudWatchEncryptionEnabled: true
cloudWatchStreamingEnabled: true
kmsKeyId: ''
runAsEnabled: true
runAsDefaultUser: ''
idleSessionTimeout: '20'
maxSessionDuration: '60'
shellProfile:
windows: ''
linux: ''
```
------
#### [ JSON ]
```
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "",
"s3KeyPrefix": "",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": true,
"kmsKeyId": "",
"runAsEnabled": true,
"runAsDefaultUser": "",
"idleSessionTimeout": "20",
"maxSessionDuration": "60",
"shellProfile": {
"windows": "date",
"linux": "pwd;ls"
}
}
}
```
------
`InteractiveCommands` 类型会话文档示例
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Document to view a log file on a Linux instance
sessionType: InteractiveCommands
parameters:
logpath:
type: String
description: The log file path to read.
default: "/var/log/amazon/ssm/amazon-ssm-agent.log"
allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$"
properties:
linux:
commands: "tail -f {{ logpath }}"
runAsElevated: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "1.0",
"description": "Document to view a log file on a Linux instance",
"sessionType": "InteractiveCommands",
"parameters": {
"logpath": {
"type": "String",
"description": "The log file path to read.",
"default": "/var/log/amazon/ssm/amazon-ssm-agent.log",
"allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$"
}
},
"properties": {
"linux": {
"commands": "tail -f {{ logpath }}",
"runAsElevated": true
}
}
}
```
------
`Port` 类型会话文档示例
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Document to open given port connection over Session Manager
sessionType: Port
parameters:
paramExample:
type: string
description: document parameter
properties:
portNumber: anyPortNumber
```
------
#### [ JSON ]
```
{
"schemaVersion": "1.0",
"description": "Document to open given port connection over Session Manager",
"sessionType": "Port",
"parameters": {
"paramExample": {
"type": "string",
"description": "document parameter"
}
},
"properties": {
"portNumber": "anyPortNumber"
}
}
```
------
包含特殊字符的会话文档示例
------
#### [ YAML ]
```
---
schemaVersion: '1.0'
description: Example document with quotation marks
sessionType: InteractiveCommands
parameters:
Test:
type: String
description: Test Input
maxChars: 32
properties:
windows:
commands: |
$Test = '{{ Test }}'
$myVariable = \"Computer name is $env:COMPUTERNAME\"
Write-Host "Test variable: $myVariable`.`nInput parameter: $Test"
runAsElevated: false
```
------
#### [ JSON ]
```
{
"schemaVersion":"1.0",
"description":"Test document with quotation marks",
"sessionType":"InteractiveCommands",
"parameters":{
"Test":{
"type":"String",
"description":"Test Input",
"maxChars":32
}
},
"properties":{
"windows":{
"commands":[
"$Test = '{{ Test }}'",
"$myVariable = \\\"Computer name is $env:COMPUTERNAME\\\"",
"Write-Host \"Test variable: $myVariable`.`nInput parameter: $Test\""
],
"runAsElevated":false
}
}
}
```
------
# 排除 Session Manager 问题
可以使用以下信息来帮助解决 AWS Systems Manager Session Manager 问题。
**Topics**
+ [调用 TerminateSession 操作时的 AccessDeniedException](#session-manager-troubleshooting-access-denied-exception)
+ [文档处理意外失败：文档工作线程超时](#session-manager-troubleshooting-document-worker-timed-out)
+ [Session Manager 无法从 Amazon EC2 控制台连接](#session-manager-troubleshooting-EC2-console)
+ [没有启动会话的权限](#session-manager-troubleshooting-start-permissions)
+ [SSM Agent 不在线](#session-manager-troubleshooting-agent-not-online)
+ [没有更改会话首选项的权限](#session-manager-troubleshooting-preferences-permissions)
+ [托管式节点不可用或未为 Session Manager 配置托管式节点](#session-manager-troubleshooting-instances)
+ [未找到 Session Manager 插件](#plugin-not-found)
+ [Session Manager 插件未自动添加到命令行路径（Windows）](#windows-plugin-env-var-not-set)
+ [Session Manager 插件变得没有响应](#plugin-unresponsive)
+ [TargetNotConnected](#ssh-target-not-connected)
+ [启动会话后显示空白屏幕](#session-manager-troubleshooting-start-blank-screen)
+ [托管式节点在长时间运行会话期间变得没有响应](#session-manager-troubleshooting-log-retention)
+ [调用 StartSession 操作时出现错误（InvalidDocument）](#session-manager-troubleshooting-invalid-document)
## 调用 TerminateSession 操作时的 AccessDeniedException
**问题**：尝试终止会话时，Systems Manager 会返回以下错误：
```
An error occurred (AccessDeniedException) when calling the TerminateSession operation:
User: is not authorized to perform: ssm:TerminateSession on resource:
because no identity-based policy allows the ssm:TerminateSession action.
```
**解决方案 A：确认节点上已安装[最新版本的 Session Manager 插件](https://docs.aws.amazon.com/systems-manager/latest/userguide/plugin-version-history.html)**
在终端中输入以下命令，然后按 Enter。
```
session-manager-plugin --version
```
**解决方案 B：安装或重新安装最新版本的插件**
有关更多信息，请参阅 [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
**解决方案 C：尝试重新建立与节点的连接**
验证节点是否在响应请求。尝试重新建立会话。或者，在必要时，打开 Amazon EC2 控制台并验证实例的状态是否正在运行。
## 文档处理意外失败：文档工作线程超时
**问题**：启动与 Linux 主机的会话时，Systems Manager 返回以下错误：
```
document process failed unexpectedly: document worker timed out,
check [ssm-document-worker]/[ssm-session-worker] log for crash reason
```
如果您配置了SSM Agent 日志记录（如 [查看 SSM Agent 日志](ssm-agent-logs.md) 中所述），则可以在调试日志中查看更多详细信息。对于此问题，Session Manager 显示以下日志条目：
```
failed to create channel: too many open files
```
此错误通常表示运行的 Session Manager 工作线程进程过多，底层操作系统达到了极限。您有两个选项来解决此问题。
**解决方案 A：提高操作系统文件通知限制**
您可以在单独的 Linux 主机上运行以下命令来提高限制。该命令使用 Systems Manager Run Command。指定值会将 `max_user_instances` 增加到 8192。此值远高于默认值 128，但它不会占用主机资源：
```
aws ssm send-command --document-name AWS-RunShellScript \
--instance-id i-02573cafcfEXAMPLE --parameters \
"commands=sudo sysctl fs.inotify.max_user_instances=8192"
```
**解决方案 B：减少 Session Manager 在目标主机中使用的文件通知**
在单独的 Linux 主机上运行以下命令，以列出目标主机上运行的会话：
```
aws ssm describe-sessions --state Active --filters key=Target,value=i-02573cafcfEXAMPLE
```
查看命令输出，以确定不再需要的会话。您可以在单独的 Linux 主机上运行以下命令来终止这些会话：
```
aws ssm terminate-session —session-id session ID
```
或者，一旦远程服务器上不再运行会话，您可以通过在单独的 Linux 主机上运行以下命令来释放更多资源。此命令将终止远程主机上运行的所有 Session Manager 进程，从而终止与远程主机的所有会话。在运行此命令之前，请确认没有要保留的正在进行的会话：
```
aws ssm send-command --document-name AWS-RunShellScript \
--instance-id i-02573cafcfEXAMPLE --parameters \
'{"commands":["sudo kill $(ps aux | grep ssm-session-worker | grep -v grep | awk '"'"'{print $2}'"'"')"]}'
```
## Session Manager 无法从 Amazon EC2 控制台连接
**问题**：创建新实例后，Amazon Elastic Compute Cloud（Amazon EC2）控制台中的**链接**按钮 > **会话管理器**选项卡不提供连接选项。
**解决方案 A：创建实例配置文件**：如果您尚未执行此操作（按照 EC2 控制台中**会话管理器**选项卡上的信息的说明），使用Quick Setup创建 AWS Identity and Access Management（IAM）实例配置文件。Quick Setup是 AWS Systems Manager 中的一项工具。
Session Manager 需要 IAM 实例配置文件才能连接到实例。您可以使用 Quick Setup 创建[主机管理配置](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-host-management.html)，以创建实例配置文件并将其分配给实例。*主机管理配置*创建具有所需权限的实例配置文件并将其分配给实例。主机管理配置还可以启用其他 Systems Manager 工具，并创建用于运行这些工具的 IAM 角色。使用Quick Setup或主机管理配置启用的工具不会产生任何费用。[打开 Quick Setup 并创建主机管理配置](https://console.aws.amazon.com/systems-manager/quick-setup/create-configuration&configurationType=SSMHostMgmt)。
**重要**
创建主机管理配置后，Amazon EC2 可能需要几分钟来注册更改并刷新 **会话管理器**选项卡。如果选项卡在两分钟后没有显示**连接**按钮，请重新启动实例。如果重新启动后仍然看不到连接选项，请打开[快速设置功能](https://console.aws.amazon.com/systems-manager/quick-setup/create-configuration&configurationType=SSMHostMgmt)，确认只有一个主机管理配置。如果有两个主机管理配置，请删除较旧的配置并等待几分钟。
如果在创建主机管理配置后仍然无法连接，或者收到错误（包括关于 SSM Agent 的错误），请参阅以下解决方案之一：
+ [解决方案 B：没有错误，但仍然无法连接](#session-manager-troubleshooting-EC2-console-no-error)
+ [解决方案 C：关于缺失 SSM Agent 的错误](#session-manager-troubleshooting-EC2-console-no-agent)
### 解决方案 B：没有错误，但仍然无法连接
如果您创建了主机管理配置，等待了几分钟才尝试连接，但仍然无法连接，则可能需要手动将主机管理配置应用于实例。使用以下过程更新 Quick Setup 主机管理配置并将更改应用于实例。
**使用 Quick Setup 更新主机管理配置**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Quick Setup**。
1. 在**配置**列表中，选择您创建的**主机管理配置**。
1. 选择**操作**，然后选择**编辑配置**。
1. 在**目标**部分的底部附近，于**选择您希望如何定位目标**下选择**手动**。
1. 在**实例**部分中，选择您创建的实例。
1. 选择**更新**。
等待几分钟，让 EC2 刷新**会话管理器**选项卡。如果仍然无法连接或收到错误，请查看该问题的其余解决方案。
### 解决方案 C：关于缺失 SSM Agent 的错误
如果您无法使用 Quick Setup 创建主机管理配置，或者收到有关未安装 SSM Agent 的错误，则可能需要在实例上手动安装 SSM Agent。SSM Agent 是 Amazon 软件，它允许 Systems Manager 通过使用 Session Manager 连接到实例。SSM Agent 默认安装在大多数亚马逊机器映像（AMI）上。如果您的实例是从非标准 AMI 或较旧的 AMI 创建的，则可能需要手动安装代理。有关安装 SSM Agent 的过程，请参阅以下与您的实例操作系统相对应的主题。
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-windows.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-windows.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-macos.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/manually-install-ssm-agent-macos.html)
+ [AlmaLinux](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-alma.html)
+ [Amazon Linux 2 和 AL2023](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-al2.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-deb.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-deb.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-oracle.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-oracle.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rhel.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rhel.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rocky.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-rocky.html)
+ [https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-ubuntu.html](https://docs.aws.amazon.com/systems-manager/latest/userguide/agent-install-ubuntu.html)
有关 SSM Agent 的问题，请参阅 [排除 SSM Agent 问题](troubleshooting-ssm-agent.md)。
## 没有启动会话的权限
**问题**：您尝试启动会话，但系统提示您没有必要的权限。
+ **解决方案**：系统管理员尚未授予您启动 Session Manager 会话的 AWS Identity and Access Management (IAM) 策略权限。有关更多信息，请参阅[控制用户会话对实例的访问权限](session-manager-getting-started-restrict-access.md)。
## SSM Agent 不在线
**问题**：您在 Amazon EC2 实例 **Session Manager** 选项卡上看到一条消息，表明：“SSM Agent 不在线。SSM Agent 不能够连接到 Systems Manager 端点以将其自身注册到服务中。”
**解决方案**：SSM Agent 是在 Amazon EC2 实例上运行的 Amazon 软件，从而 Session Manager 可以与其建立连接。如果您看到此错误，则 SSM Agent 不能够建立与 Systems Manager 端点的连接。问题的可能原因可能是防火墙限制、路由问题或互联网连接不足。要解决此问题，请调查网络连接问题。有关更多信息，请参阅[排除 SSM Agent 问题](troubleshooting-ssm-agent.md)和[排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md)。有关 Systems Manager 端点的信息，请参阅《AWS 一般参考》中的 [AWS Systems Manager 端点和配额](https://docs.aws.amazon.com/general/latest/gr/ssm.html)。
## 没有更改会话首选项的权限
**问题**：您尝试更新组织的全局会话首选项，但系统提示您没有必要的权限。
+ **解决方案**：系统管理员尚未授予您设置 Session Manager 首选项的 IAM policy 权限。有关信息，请参阅[授予或拒绝更新 Session Manager 首选项的用户权限](preference-setting-permissions.md)。
## 托管式节点不可用或未为 Session Manager 配置托管式节点
**问题 1**：您要在 **Start a session**（启动会话）控制台页面上启动一个会话，但托管式节点不在列表中。
+ **解决方案 A**：可能尚未为 AWS Systems Manager 配置您要连接的托管式节点。有关更多信息，请参阅 [为组织设置 Systems Manager 统一控制台](systems-manager-setting-up-organizations.md)。
**注意**
如果在附加 IAM 实例配置文件时 AWS Systems Manager SSM Agent 已在托管式节点上运行，则在 **Start a session **（启动会话）控制台页面上列出该实例之前，可能需要重新启动代理。
+ **解决方案 B**：您应用于托管式节点上 SSM Agent 的代理配置可能不正确。如果代理配置不正确，托管式节点将无法到达所需的服务终端节点，或节点可能会向 Systems Manager 报告为不同的操作系统。有关更多信息，请参阅[配置 SSM Agent 以在 Linux 节点上使用代理](configure-proxy-ssm-agent.md)和[配置 SSM Agent以使用 Windows Server 实例的代理](configure-proxy-ssm-agent-windows.md)。
**问题 2**：**Start a session**（开启会话）控制台页面上的列表中显示了要连接的托管式节点，但页面报告“The instance you selected isn't configured to use Session Manager”（您选择的实例未配置为使用 ）。
+ **解决方案 A**：托管式节点已配置为可以使用 Systems Manager 服务，但附加到节点的 IAM 实例配置文件不包含Session Manager工具所需的权限。有关更多信息，请参阅[验证或创建具有 Session Manager 权限的 IAM 实例配置文件](session-manager-getting-started-instance-profile.md)。
+ **解决方案 B**：托管式节点未运行支持 Session Manager 的 SSM Agent 版本。将节点上的 SSM Agent 更新为版本 2.3.68.0 或更高版本。
根据操作系统类型，按照 [在适用于 Windows Server 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-windows.md)、[在适用于 Linux 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-linux.md) 或 [在适用于 macOS 的 EC2 实例上手动安装和卸载 SSM Agent](manually-install-ssm-agent-macos.md) 中的步骤操作，手动更新托管式节点上的 SSM Agent。
或者，使用 Run Command 文档 `AWS-UpdateSSMAgent` 一次性更新一个或多个托管式节点上的代理版本。有关信息，请参阅[使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
**提示**
为了让代理始终保持最新状态，建议使用以下方法之一按照定义的自动计划将 SSM Agent更新为最新版本：
作为 State Manager 关联的一部分运行 `AWS-UpdateSSMAgent`。有关信息，请参阅[演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)。
运行 `AWS-UpdateSSMAgent` 作为维护时段的一部分。有关使用维护时段的信息，请参阅 [使用控制台创建和管理维护时段](sysman-maintenance-working.md) 和 [教程：使用 AWS CLI 创建和配置维护时段](maintenance-windows-cli-tutorials-create.md)。
+ **解决方案 C**：托管式节点无法到达必要的服务终端节点。您可以使用由 AWS PrivateLink 提供支持的接口端点连接到 Systems Manager 端点，以提高托管式节点的安保状况。使用接口端点的替代方法是，在托管式节点上允许出站互联网访问。有关更多信息，请参阅[使用 PrivateLink 为 Session Manager 设置 VPC 端点](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-privatelink.html)。
+ **解决方案 D**：托管式节点的可用 CPU 或内存资源有限。尽管您的托管式节点可能正常运行，但是如果该节点没有足够的可用资源，则您无法建立会话。有关更多信息，请参阅[对无法访问的实例进行故障排除](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-console.html)。
## 未找到 Session Manager 插件
要使用 AWS CLI 运行会话命令，还必须在本地计算机上安装 Session Manager 插件。有关信息，请参阅[为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
## Session Manager 插件未自动添加到命令行路径（Windows）
在 Windows 上安装 Session Manager 插件时，`session-manager-plugin` 可执行文件应自动添加到操作系统的 `PATH` 环境变量中。如果在运行检查是否正确安装了 Session Manager 插件的命令后命令失败 (`aws ssm start-session --target instance-id`)，则需要使用以下过程进行手动设置。
**修改您的 PATH 变量 (Windows)**
1. 按 Windows 键并输入 **environment variables**。
1. 选择 **Edit environment variables for your account**（编辑您账户的环境变量）。
1. 选择 **PATH**，然后选择 **Edit**。
1. 向 **Variable value (变量值)** 字段添加路径，用分号分隔，如下例所示：*`C:\existing\path`*;*`C:\new\path`*
*`C:\existing\path`* 表示字段中已存在的值。*`C:\new\path`* 表示要添加的路径，如以下示例所示。
+ **64 位计算机**：`C:\Program Files\Amazon\SessionManagerPlugin\bin\`
1. 选择 **OK**（确定）两次以应用新设置。
1. 关闭任何运行的命令提示符并重新打开。
## Session Manager 插件变得没有响应
如果您的本地计算机上安装了防病毒软件，在端口转发会话期间，可能会停止转发流量。在某些情况下，防病毒软件会干扰 Session Manager 插件，从而导致进程死锁。要解决此问题，请在防病毒软件中设置允许 Session Manager 插件或将其排除在外。有关 Session Manager 插件的默认安装路径的信息，请参阅 [为 AWS CLI 安装 Session Manager 插件](session-manager-working-with-install-plugin.md)。
## TargetNotConnected
**问题**：您尝试启动会话，但系统返回错误消息：“An error occurred (TargetNotConnected) when calling the StartSession operation: *InstanceID* isn't connected.”（调用 StartSession 操作时发生错误 (TargetNotConnected)：InstanceID 未连接。）
+ **解决方案 A**：如果会话的指定目标托管式节点未完全配置为与 Session Manager 一起使用，则会返回此错误。有关信息，请参阅[设置 Session Manager](session-manager-getting-started.md)。
+ **解决方案 B**：如果您尝试在位于不同 AWS 账户 或 AWS 区域 的托管式节点上启动会话，也会返回此错误。
## 启动会话后显示空白屏幕
**问题**：在您启动会话后，Session Manager 显示空白屏幕。
+ **解决方案 A**：如果托管式节点上的根卷已满，则可能出现此问题。由于磁盘空间不足，节点上的 SSM Agent 停止工作。要解决此问题，请使用 Amazon CloudWatch 从操作系统中收集指标和日志。有关更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
+ **解决方案 B**：如果您使用包含不匹配端点和区域对的链接访问控制台，则会显示空白屏幕。例如，在以下控制台 URL 中，`us-west-2` 是指定的端点，但 `us-west-1` 是指定的 AWS 区域。
```
https://us-west-2.console.aws.amazon.com/systems-manager/session-manager/sessions?region=us-west-1
```
+ **解决方案 C**：托管式节点正在使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 Amazon S3 存储桶或 Amazon CloudWatch Logs 日志组，但 VPC 中不存在 `s3` 网关端点或 `logs` 接口端点。如果您的托管式节点使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 Amazon S3 存储桶，则需要格式为 **`com.amazonaws.region.s3`** 的 `s3` 端点。或者，如果您的托管式节点使用 VPC 终端节点连接到 Systems Manager，并且您的 Session Manager 首选项将会话输出写入 CloudWatch Logs 日志组，则需要格式为 **`com.amazonaws.region.logs`** 的 `logs` 端点。有关更多信息，请参阅 [为 Systems Manager 创建 VPC 端点](setup-create-vpc.md#create-vpc-endpoints)。
+ **解决方案 D**：您在会话首选项中指定的日志组或 Amazon S3 存储桶已删除。要解决此问题，请使用有效的日志组或 S3 存储桶更新会话首选项。
+ **解决方案 E**：您在会话首选项中指定的日志组或 Amazon S3 存储桶未加密，但您已将 `cloudWatchEncryptionEnabled` 或 `s3EncryptionEnabled` 输入设置为 `true`。要解决此问题，请使用加密的日志组或 Amazon S3 存储桶更新会话首选项，或将 `cloudWatchEncryptionEnabled` 或 `s3EncryptionEnabled` 输入设置为 `false`。此方案仅适用于使用命令行工具创建会话首选项的客户。
## 托管式节点在长时间运行会话期间变得没有响应
**问题**：在长时间运行会话期间，托管式节点变得没有响应或崩溃。
**解决方案**：减少 Session Manager 的 SSM Agent 日志保留时间。
**要减少会话的 SSM Agent 日志保留时间，请执行以下步骤：**
1. 在 Linux 的 `/etc/amazon/ssm/` 目录或 Windows 的 `C:\Program Files\Amazon\SSM` 中找到 `amazon-ssm-agent.json.template`。
1. 将 `amazon-ssm-agent.json.template` 的内容复制到同一目录中名为 `amazon-ssm-agent.json` 的新文件中。
1. 减小 `SSM` 属性中 `SessionLogsRetentionDurationHours` 值的默认值，然后保存该文件。
1. 重启 SSM Agent。
## 调用 StartSession 操作时出现错误（InvalidDocument）
**问题**：使用 AWS CLI 启动会话时，您会收到以下错误。
```
An error occurred (InvalidDocument) when calling the StartSession operation: Document type: 'Command' is not supported. Only type: 'Session' is supported for Session Manager.
```
**解决方案**：您为 `--document-name` 参数指定的 SSM 文档不是*会话*文档。请按照以下过程在 AWS 管理控制台 中查看会话文档列表。
**查看会话文档列表**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在**类别**列表中，选择**会话文档**。
# AWS Systems Manager State Manager
State Manager（AWS Systems Manager 中的一项工具）是一项安全并且可扩展的配置管理服务，可以自动将托管式节点和其他 AWS 资源保持在定义的状态。要开始使用 State Manager，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/state-manager)。在导航窗格中，请选择 **State Manager**。
**注意**
State Manager 和 Maintenance Windows 可在托管式节点上执行一些相似类型的更新。您选择哪一项取决于您是需要自动执行系统合规性，还是在指定的时间段内执行高优先级、时效性强的任务。
有关更多信息，请参阅 [在 State Manager 和 Maintenance Windows 之间选择](state-manager-vs-maintenance-windows.md)。
## 我的组织如何从 State Manager 获益？
通过使用预配置的 Systems Manager 文档（SSM 文档），State Manager 可以为管理节点提供以下好处：
+ 在启动时通过特定软件引导启动节点。
+ 按照既定计划下载和更新代理，包括 SSM Agent。
+ 配置网络设置。
+ 将节点加入 Microsoft Active Directory 域。
+ 在 Linux、macOS 和 Windows Server 托管节点的整个生命周期内对这些实例运行脚本。
要管理其他 AWS 资源的配置偏移，可搭配使用 Automation（Systems Manager 中的一项工具）与State Manager来执行以下类型的任务：
+ 将 Systems Manager 角色附上 Amazon Elastic Compute Cloud (Amazon EC2) 实例，以使其成为*托管式节点*。
+ 对安全组强制实施所需的入口和出口规则。
+ 创建或删除 Amazon DynamoDB 备份。
+ 创建或删除 Amazon Elastic Block Store (Amazon EBS) 快照。
+ 关闭 Amazon Simple Storage Service (Amazon S3) 存储桶的读写权限。
+ 开启、重新开启或停止托管式节点和 Amazon Relational Database Service (Amazon RDS) 实例。
+ 将修补程序应用到 Linux、macOS 和 Windows AMIs。
有关使用 State Manager 与自动化运行手册的信息，请参阅 [使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
## 谁应该使用 State Manager？
State Manager 适用于任何希望改进其 AWS 资源管理和治理并减少配置偏移的 AWS 客户。
## State Manager 具有哪些功能？
State Manager 的主要功能包括以下方面：
+
**State Manager 关联**
State Manager *关联*是指分配给 AWS 资源的配置。该配置定义要在资源上保持的状态。例如，关联可以指定必须在托管式节点上安装并运行防病毒软件，或必须关闭特定端口。
关联指定了何时应用关联的配置和目标的计划。例如，防病毒软件的关联可能会每天在 AWS 账户中的所有托管式节点上运行一次。如果该软件未安装在节点上，则关联可以指示 State Manager 安装该软件。如果已安装该软件，但未运行服务，则关联可以指示 State Manager 开启服务。
+
**灵活的调度选项**
State Manager 在关联运行时提供以下调度选项：
+ **立即或延迟处理**
在创建关联时，原定设置下，系统会立即在指定的资源上运行该关联。在初始运行后，关联会根据定义的计划按周期运行：
通过使用控制台中的 **Apply association only at the next specified Cron interval**（仅在下一个指定的 Cron 周期应用关联）或命令行中的 `ApplyOnlyAtCronInterval` 参数，可以指示 State Manager 不要立即运行关联。
+ **Cron 和 Rate 表达式**
创建关联时，您可以指定 State Manager 何时应用该配置的计划。State Manager 支持标准的 cron 和 rate 表达式，以便在关联运行时进行调度。State Manager 还支持使用星期几和数字符号（\$1）的 cron 表达式，进而指定将在一个月的第 *n* 天运行某个关联，此外还支持在表达式中使用（L）符号来指示该月最后 *X* 天。
**注意**
State Manager 目前不支持在 cron 表达式中为关联指定月数。
要进一步控制关联运行的时间，例如，如果您想在星期二补丁后两天运行关联，可以指定偏移量。*偏移量*定义了在计划日期之后等待多少天再运行关联。
有关构建 cron 和 rate 表达式的信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
+
**多种目标选项**
关联还可以指定关联的目标。State Manager 支持通过使用标签、AWS Resource Groups、单个节点 ID 或当前 AWS 区域 和 AWS 账户 中的所有托管式节点来将 AWS 资源设为目标。
+
**Amazon S3 支持**
将关联运行的命令输出存储在您选择的 Amazon S3 存储桶中。有关更多信息，请参阅 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
+
**EventBridge 支持**
在 Amazon EventBridge 规则中，支持将此 Systems Manager 工具作为*事件*类型和*目标*类型。有关更多信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md) 和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
## 使用 State Manager 是否需要收取费用？
State Manager 不收取额外费用。
**Topics**
+ [我的组织如何从 State Manager 获益？](#state-manager-benefits)
+ [谁应该使用 State Manager？](#state-manager-who)
+ [State Manager 具有哪些功能？](#state-manager-features)
+ [使用 State Manager 是否需要收取费用？](#state-manager-cost)
+ [了解 State Manager 的工作方式](state-manager-about.md)
+ [在 Systems Manager 中使用关联。](state-manager-associations.md)
+ [创建运行 MOF 文件的关联](systems-manager-state-manager-using-mof-file.md)
+ [创建运行 Ansible Playbook 的关联](systems-manager-state-manager-ansible.md)
+ [创建运行 Chef 配方的关联](systems-manager-state-manager-chef.md)
+ [演练：使用 AWS CLI 自动更新 SSM Agent](state-manager-update-ssm-agent-cli.md)
+ [演练：在适用于 Windows Server 的 EC2 实例上自动更新半虚拟化驱动程序](state-manager-update-pv-drivers.md)
**更多信息**
+ [使用 Amazon EC2 Systems Manager 和 Windows PowerShell DSC 来防止配置偏差](https://aws.amazon.com/blogs/mt/combating-configuration-drift-using-amazon-ec2-systems-manager-and-windows-powershell-dsc/)
+ [使用 State Manager 在 Auto Scaling 组中配置 Amazon EC2 实例](https://aws.amazon.com/blogs/mt/configure-amazon-ec2-instances-in-an-auto-scaling-group-using-state-manager/)
# 了解 State Manager 的工作方式
State Manager（AWS Systems Manager 中的一项工具）是一项安全并且可扩展的服务，可以自动将[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)基础设施中的托管式节点保持在定义的状态。
State Manager 运行方式如下：
**1. 确定要应用于 AWS 资源的状态。**
是否要确保您的托管式节点已配置特定应用程序，如防病毒或防恶意软件应用程序？ 是否要自动执行更新 SSM Agent 或其他 AWS 软件包（如 `AWSPVDriver`）的过程？ 是否需要确保特定端口已关闭或打开？ 要开启使用 State Manager，请确定要应用于 AWS 资源的状态。要应用的状态可决定您使用哪个 SSM 文档来创建 State Manager 关联。
State Manager *关联*是指分配给 AWS 资源的配置。该配置定义要在资源上保持的状态。例如，关联可以指定必须在托管式节点上安装并运行防病毒软件，或必须关闭特定端口。
关联指定了何时应用关联的配置和目标的计划。例如，防病毒软件的关联可能会每天在 AWS 账户中的所有托管式节点上运行一次。如果该软件未安装在节点上，则关联可以指示 State Manager 安装该软件。如果已安装该软件，但未运行服务，则关联可以指示 State Manager 开启服务。
**2. 确定预配置的 SSM 文档能否帮助您在 AWS 资源上创建所需的状态。**
Systems Manager 包含几十个预先配置的 SSM 文档，可用来创建关联。预先配置的文档已准备就绪，可执行常见任务，例如安装应用程序、配置 Amazon CloudWatch 、运行 AWS Systems Manager 自动化、运行 PowerShell 和 Shell 脚本、将托管式节点加入 Active Directory 的目录服务域等。
您可以在 [Systems Manager 控制台](https://console.aws.amazon.com/systems-manager/documents)查看所有 SSM 文档。您可以选择文档的名称以了解更多有关每个文档的详情。以下是两个示例：[https://console.aws.amazon.com/systems-manager/documents/AWS-ConfigureAWSPackage/description](https://console.aws.amazon.com/systems-manager/documents/AWS-ConfigureAWSPackage/description) 和 [https://console.aws.amazon.com/systems-manager/documents/AWS-InstallApplication/description](https://console.aws.amazon.com/systems-manager/documents/AWS-InstallApplication/description)。
**3. 创建关联。**
您可以使用 Systems Manager 控制台、AWS Command Line Interface(AWS CLI)，AWS Tools for Windows PowerShell (Tools for Windows PowerShell) 或 Systems Manager API 创建关联。当创建关联时，需要指定以下信息：
+ 关联的名称。
+ SSM 文档的参数（例如，要在节点上安装的应用程序或要运行的脚本的路径）。
+ 关联目标。您可以通过指定标签、选择单个节点 ID 或在 AWS Resource Groups 中选择一个组来将托管式节点设为目标。您还可以将当前 AWS 区域 和 AWS 账户 中的*所有*托管式节点设为目标。如果目标包含超过 1000 个节点，系统将使用每小时节流机制。这意味着您可能会观察到状态聚合计数存在偏差，因为聚合过程每小时运行一次，且仅在节点的执行状态发生变化时才会运行。
+ 该关联用来代表您执行操作的角色。状态管理器将在向节点分派配置时代入此角色并调用所需的 API。有关设置自定义提供的角色的信息，请参阅[为 `AssociationDispatchAssumeRole` 设置角色](#setup-assume-role)。如果未提供任何角色，则将使用 [Systems Manager 的服务相关角色](https://docs.aws.amazon.com/systems-manager/latest/userguide/using-service-linked-roles.html)。
**注意**
建议您定义一个自定义 IAM 角色，从而完全控制状态管理器在代表您执行操作时所拥有的权限。
状态管理器中对服务相关角色的支持将逐步停用。将来，依赖服务相关角色的关联可能需要更新后才能继续正常运行。
有关管理自定义提供的角色使用情况的信息，请参阅[使用 `ssm:AssociationDispatchAssumeRole` 管理 AssociationDispatchAssumeRole 的使用情况](#context-key-assume-role)。
+ 关于应用状态的时间或频率的计划。您可以指定 cron 或 rate 表达式。有关使用 cron 和 rate 表达式创建计划的更多信息，请参阅 [适用于关联的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md#reference-cron-and-rate-expressions-association)。
**注意**
State Manager 目前不支持在 cron 表达式中为关联指定月数。
运行命令以创建关联时，Systems Manager 将指定的信息（计划、目标、SSM 文档和参数）绑定到目标资源。当系统尝试访问所有目标并*立即* 应用关联中指定的状态时，关联的状态最初会显示“待处理”。
如果您创建计划在之前的关联仍在运行时运行的新关联，那么之前的关联将超时，系统会运行新关联。
Systems Manager 会报告在资源中创建关联之请求的状态。您可以在控制台中或（对于托管式节点）使用 [DescribeInstanceAssociationsStatus](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstanceAssociationsStatus.html) API 操作查看状态详细信息。如果在创建关联时选择将命令输出写入到 Amazon Simple Storage Service (Amazon S3)，则还可以在指定的 Amazon S3 存储桶中查看此输出。
有关更多信息，请参阅 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
在关联运行期间由 SSM 文档发起的 API 操作未登录 AWS CloudTrail。
**4. 监控并更新。**
创建关联之后，State Manager 根据关联中定义的计划重新应用配置。您可以在控制台的 [State Manager 页面](https://console.aws.amazon.com/systems-manager/state-manager)上或通过直接调用在您创建关联时由 Systems Manager 生成的关联 ID 来查看关联的状态。有关更多信息，请参阅 [查看关联历史记录](state-manager-associations-history.md)。您可以更新您的关联文档并根据需要重新应用它们。您也可以创建多个关联版本。有关更多信息，请参阅 [编辑和创建关联的新版本](state-manager-associations-edit.md)。
## 了解何时将关联应用于资源
在创建关联时，您需要指定用于定义配置的 SSM 文档、目标资源列表，以及应用配置的计划。默认情况下，State Manager 在您创建关联时运行该关联，然后根据您的计划运行该关联。State Manager 还会尝试在以下情况下运行关联：
+ **关联编辑** – State Manager 在用户编辑并将其更改保存到以下任何关联字段 `DOCUMENT_VERSION`、`PARAMETERS`、`SCHEDULE_EXPRESSION`、`OUTPUT_S3_LOCATION` 中后运行关联。
+ **文档编辑** – State Manager 在用户编辑并将更改保存到用于定义关联的配置状态的 SSM 文档中后运行关联。具体来说，关联在对文档进行以下编辑之后运行：
+ 用户指定了一个新的 `$DEFAULT` 文档版本，该关联使用 `$DEFAULT` 版本创建。
+ 用户更新文档，然后使用 `$LATEST` 版本创建了关联。
+ 用户删除创建关联时指定的文档。
+ **手动启动** – State Manager 在用户从 Systems Manager 控制台启动或以编程的方式启动时运行关联。
+ **目标更改** – State Manager 在目标节点上发生以下任何活动后运行关联：
+ 托管式节点第一次联机。
+ 托管式节点在错过了计划的关联运行后联机。
+ 托管式节点被停止超过 30 天后联机。
**注意**
State Manager不跨AWS 账户监视关联中使用的文档或包。如果您在一个账户中更新文档或包，则该更新不会导致在第二个账户中运行关联。您必须在第二个账户中手动运行关联。
**防止关联在目标更改时运行**
在某些情况下，您可能不希望关联在由托管节点组成的目标发生变化时运行，而只根据其指定的计划运行。
**注意**
运行自动化运行手册会产生费用。如果与自动化运行手册的关联以您账户中的所有实例为目标，并且您定期启动大量实例，则运行手册将在启动时在每个实例上运行。这可能会导致自动化费用上升。
要防止某个关联在该关联的目标发生更改时运行，请选中**仅在下一个指定的 cron 间隔内应用关联**复选框。此复选框位于**创建关联**和**编辑关联**页面的**指定计划**区域。
此选项适用于包含自动化运行手册或 SSM 文档的关联。
## 关于使用自动化运行手册进行目标更新
为了在检测到新的目标节点时应用使用自动化运行手册创建的关联，必须满足下面的条件：
+ 关联必须由[Quick Setup](systems-manager-quick-setup.md)配置创建。Quick Setup是 AWS Systems Manager 中的一项工具。目前不支持由其他进程创建的关联。
+ 自动化运行手册必须明确针对资源类型 `AWS::EC2::Instance` 或 `AWS::SSM::ManagedInstance`。
+ 关联必须同时指定参数和目标。
在控制台中，当您选择一个速率控制执行时，系统会显示**参数**和**目标**字段。
![\[控制台中显示了用于速率控制执行的参数和目标选项\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sm_Rate_control_execution_options.png)
当您使用 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociation.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociation.html)、[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociationBatch.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociationBatch.html) 或 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateAssociation.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateAssociation.html) API 操作时，您可以使用 `AutomationTargetParameterName` 和 `Targets` 输入指定这些值。在每个 API 操作中，您还可以通过将 `ApplyOnlyAtCronInterval` 参数设置为 `true`，防止关联在目标每次更改时运行。
有关使用控制台来控制关联何时运行的信息，包括避免自动化执行成本意外高昂的详细信息，请参阅[了解何时将关联应用于资源](#state-manager-about-scheduling)。
## 为 `AssociationDispatchAssumeRole` 设置角色
要设置状态管理器为了代表您执行操作而将代入的自定义分派代入角色，这些角色应信任 `ssm.amazonaws.com` 并具有调用 `ssm:SendCommand` 或 `ssm:StartAutomationExecution` 所需的权限（具体取决于关联使用案例）。
示例信任策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"ssm.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
## 使用 `ssm:AssociationDispatchAssumeRole` 管理 AssociationDispatchAssumeRole 的使用情况
对于状态管理器为了代表您执行操作而将代入的自定义分派代入角色，要管理其使用情况，请使用 `ssm:AssociationDispatchAssumeRole` 条件键。此条件用于控制是否可以在不指定自定义分派代入角色的情况下创建或更新关联。
在以下示例策略中，`"Allow"` 语句仅在指定了 `AssociationDispatchAssumeRole` 参数时才向该关联授予创建和更新 API 的权限。如果 API 请求中没有此参数，则此策略不会授予创建或更新关联的权限：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:CreateAssociation",
"ssm:UpdateAssociation",
"ssm:CreateAssociationBatch"
],
"Resource": "*",
"Condition": {
"StringLike": {
"ssm:AssociationDispatchAssumeRole": "*"
}
}
}
]
}
```
# 在 Systems Manager 中使用关联。
本节将介绍如何使用 AWS Systems Manager 控制台、AWS Command Line Interface (AWS CLI) 和 AWS Tools for PowerShell 来创建和管理 State Manager 关联。
**Topics**
+ [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)
+ [创建关联](state-manager-associations-creating.md)
+ [编辑和创建关联的新版本](state-manager-associations-edit.md)
+ [删除关联](systems-manager-state-manager-delete-association.md)
+ [运行 Auto Scaling 组](systems-manager-state-manager-asg.md)
+ [查看关联历史记录](state-manager-associations-history.md)
+ [使用 IAM 处理关联](systems-manager-state-manager-iam.md)
# 了解 State Manager 关联中的目标和速率控制
本主题介绍State Manager工具。此工具可帮助您将关联部署到数十个或数百个节点，同时控制在计划时间运行关联的节点数。State Manager是 AWS Systems Manager 中的一项工具。
## 使用目标
在创建 State Manager 关联时，选择在 Systems Manager 控制台中的**Targets**（目标）部分中要配置哪些节点，如下所示。
![\[创建 State Manager 关联时用于将节点设为目标的不同选项\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-targets.png)
如果使用命令行工具（如AWS Command Line Interface (AWS CLI)）创建关联，请指定 `targets` 参数。通过将节点设为目标，您可以配置数十个、数百个或数千个具有关联的节点，而无需指定或选择单个节点 ID。
每个托管节点最多可以有 20 个关联作为目标。
State Manager 在创建关联时包括以下目标选项。
**指定标签**
使用此选项可指定分配给节点的标签键和（可选）标签值。在您运行请求时，系统会在与指定标签键和值匹配的所有节点上查找并尝试创建关联。如果您指定了多个标签值，则关联将至少具有其中一个标签值的任何节点设为目标。当系统最初创建关联时，它将运行关联。在此初始运行之后，系统将根据您指定的计划运行关联。
如果您创建新节点并将指定的标签键和值分配给这些节点，系统会自动应用关联，立即运行它，然后根据计划运行它。这在关联使用命令或策略文档时适用，如果关联使用自动化运行手册，则不适用。如果从节点中删除指定的标签，系统将不再在这些节点上运行关联。
**注意**
如果您将自动化运行手册与 State Manager 结合使用，但由于标记限制的原因，您无法实现特定目标，请考虑将自动化运行手册与 Amazon EventBridge 结合使用。有关更多信息，请参阅 [基于 EventBridge 事件运行自动化](running-automations-event-bridge.md)。有关将 State Manager 与自动化运行手册结合使用的信息，请参阅[使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
作为最佳实践，我们建议在创建使用命令或策略文档的关联时使用标签。我们还建议在创建运行自动扩缩组的关联时使用标签。有关更多信息，请参阅 [运行 Auto Scaling 组](systems-manager-state-manager-asg.md)。
**注意**
请注意以下信息。
在 AWS 管理控制台中使用标签创建定位节点的关联时，只能为自动关联指定一个标签键，为命令关联指定五个标签键。关联中指定的*所有*标签键当前都必须分配给该节点。如果没有分配给该节点，则 State Manager 无法将该节点作为关联目标。
如果要使用控制台，*并且*希望通过对自动关联使用多个标签键，对命令关联使用五个标签键来定位节点，请将标签键分配给 AWS Resource Groups 组并将节点添加到该组。然后，在创建 State Manager 关联时您可以在**目标**列表中选择**资源组**选项。
您可以使用 AWS CLI 指定最多五个标签键。如果使用 AWS CLI，则 `create-association` 命令中指定的*所有*标签键当前都必须分配给该节点。如果没有分配给该节点，则 State Manager 无法将该节点作为关联目标。
**手动选择节点**
使用此选项可手动选择要在其中创建关联的节点。**Instances**（实例）窗格显示当前 AWS 账户 和 AWS 区域 中所有的 Systems Manager 托管式节点。您可以根据需要手动选择任意多个节点。当系统最初创建关联时，它将运行关联。在此初始运行之后，系统将根据您指定的计划运行关联。
**注意**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
**选择资源组**
使用此选项可在基于 AWS Resource Groups 标签或基于 AWS CloudFormation 堆栈的查询返回的所有节点上创建关联。
以下为有关将关联的 Resource Groups 设为目标的详细信息。
+ 如果向组添加新节点，系统会自动将这些节点映射到将资源组设为目标的关联。当系统发现更改时，即会将关联应用于这些节点。在此初始运行之后，系统将根据您指定的计划运行关联。
+ 如果您创建了以资源组为目标的关联，并且为该组指定了 `AWS::SSM::ManagedInstance` 资源类型，那么根据设计，该关联将在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的 Amazon Elastic Compute Cloud（Amazon EC2）实例和非 EC2 节点上运行。
反之亦然。如果您创建了以资源组为目标的关联，并且为该组指定了 `AWS::EC2::Instance` 资源类型，那么根据设计，该关联将同时在[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 节点和（Amazon EC2）实例上运行。
+ 如果您创建了将某个资源组作为目标的关联，则分配给该资源组的标签键不得超过五个，或者为任何一个标签键指定的值不得超过五个。如果这些条件中的任何一个适用于分配给您的资源组的标签和键，则该关联将无法运行并返回 `InvalidTarget` 错误。
+ 如果您使用标签创建以资源组为目标的关联，则无法为标签值选择**（空值）**选项。
+ 如果删除资源组，则该组中的所有实例将不再运行关联。作为最佳实践，删除将该组设为目标的关联。
+ 您只能将关联的单个资源组设为目标。不支持多个组或嵌套组。
+ 创建关联后，State Manager 会使用资源组中资源的相关信息定期更新关联。如果您向资源组添加新资源，则系统何时将关联应用于新资源的计划取决于多个因素。您可以在 Systems Manager 控制台的 State Manager 页面上决定关联的状态。
**警告**
有权创建将 Amazon EC2 实例资源组设为目标的关联的 AWS Identity and Access Management (IAM) 用户、组或角色自动具有组中所有实例的根级控制权。应只允许受信任的管理员创建关联。
有关 Resource Groups 的详细信息，请参阅[什么是 AWS Resource Groups ?](https://docs.aws.amazon.com/ARG/latest/userguide/)中的*AWS Resource Groups 用户指南*。
**选择所有节点**
使用此选项可将当前 AWS 账户 和 AWS 区域 中的所有节点设为目标。在您运行请求时，系统会在当前 AWS 账户 和 AWS 区域 中的所有节点上查找并尝试创建关联。当系统最初创建关联时，它将运行关联。在此初始运行之后，系统将根据您指定的计划运行关联。如果您创建新节点，系统会自动应用关联，立即运行它，然后根据计划运行它。
## 使用速率控制
您可以通过指定并发值和错误阈值来控制关联在节点上的执行。并发值用于指定允许同时运行该关联的节点数量。错误阈值指定关联执行可以失败的次数，超过该次数后 Systems Manager 向已配置该关联的每个节点发送命令来停止运行该关联。此命令停止关联运行，直至下一次计划执行。并发和错误阈值功能统称为*速率控制*。
![\[创建 State Manager 关联时不同的速率控制选项\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-rate-controls.png)
**并发**
并发通过允许您指定只有特定数量的节点可以一次处理一个关联，来帮助限制对节点的影响。您可以指定绝对数量的节点（例如 20），也可以指定目标节点集百分比（例如 10%）。
State Manager 并发具有以下限制：
+ 如果选择使用目标创建关联，但不指定并发值，则State Manager 自动强制实施 50 个节点的最大并发。
+ 如果在使用并发的关联运行时，与目标条件匹配的新节点变为线上状态，则新节点将在未超出并发值时运行关联。如果超出并发值，则会在当前的关联执行间隔内忽略这些节点。在满足并发要求的情况下，这些节点将在下一个计划间隔内运行关联。
+ 如果更新一个使用并发的关联，并且在更新时有一个或多个节点在处理该关联，则允许正在运行该关联的任何节点完成。尚未开始的关联将停止。关联运行完成后，因为关联已更新，所以所有目标节点都将立即再次运行该关联。当关联再次运行时,将强制执行并发值。
**错误阈值**
错误阈值指定允许关联执行失败的次数，超过该次数后 Systems Manager 向已配置该关联的每个节点发送命令。此命令停止关联运行，直至下一次计划执行。您可以指定绝对数量的错误（如 10），也可以指定目标集百分比（如 10%）。
例如，如果指定错误的绝对数为 3，则 State Manager 将在返回第四个错误时发送停止命令。如果指定 0，则 State Manager 将在返回第一个错误结果后发送停止命令。
如果为 50 个关联指定错误阈值 10%，则 State Manager 将在返回第六个错误时发送停止命令。在达到错误阈值时，允许完成已经运行的关联，但是其中一些关联可能失败。要确保错误数不超过为错误阈值指定的数量，请将 **Concurrency (并发)** 值设置为 1，以便一次只处理一个关联。
State Manager 错误阈值具有以下限制：
+ 为当前间隔强制实施错误阈值。
+ 有关每个错误的信息（包括步骤级别详细信息）都记录在关联历史记录中。
+ 如果选择使用目标创建关联，但不指定错误阈值，则 State Manager 自动强制实施 100% 失败的阈值。
# 创建关联
State Manager（AWS Systems Manager 中的一项工具）可以帮助您将 AWS 资源保持在您定义的状态，并减少配置偏移。为此，State Manager 会使用关联。*关联*是指分配给 AWS 资源的配置。该配置定义要在资源上保持的状态。例如，关联可以指定必须在托管式节点上安装并运行防病毒软件，或必须关闭特定端口。
关联指定了何时应用关联的配置和目标的计划。例如，防病毒软件的关联可能会每天在 AWS 账户中的所有托管式节点上运行一次。如果该软件未安装在节点上，则关联可以指示 State Manager 安装该软件。如果已安装该软件，但未运行服务，则关联可以指示 State Manager 开启服务。
**警告**
创建关联时，可以选择托管式节点的 AWS 资源组作为关联的目标。如果 AWS Identity and Access Management (IAM) 用户、组或角色有权限创建将托管式节点资源组设为目标的关联，则该用户、组或角色将自动具有组中所有节点的根级控制权。只允许受信任的管理员创建关联。
**关联目标和速率控制**
关联将指定哪些托管节点或目标应该接收关联。State Manager 包括的一些功能可帮助您将托管节点设置为目标，并控制如何将关联部署到这些目标。有关目标和速率控制的更多信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
**为关联添加标签**
通过使用命令行工具（如 AWS CLI 或 AWS Tools for PowerShell）创建关联时，可以将标签指定给关联。不支持使用 Systems Manager 控制台将标签添加到关联。
**运行关联**
默认情况下，State Manager 将在您创建关联后立即运行关联，然后根据您定义的计划运行。
该系统还会根据以下规则运行关联：
+ State Manager 在间隔期间会尝试在所有指定或目标节点上运行关联。
+ 如果在某个周期内未运行某一关联（例如，由于并发值限制了可以同时处理关联的节点数），State Manager 将尝试在下一个周期运行该关联。
+ State Manager 将在更改关联的配置、目标节点、文档或参数后运行关联。有关更多信息，请参阅 [了解何时将关联应用于资源](state-manager-about.md#state-manager-about-scheduling)。
+ State Manager 会记录所有已跳过间隔的历史记录。可在 **Execution History (执行历史记录)** 选项卡上查看历史记录。
## 为关联制定计划
您可以安排关联以基本间隔（如*每 10 小时*）运行，也可以使用自定义 cron 和费率表达式创建更高级的计划。您还可以在首次创建关联时阻止关联运行。
**使用 cron 和 rate 表达式为关联运行制定计划**
除了标准 cron 和 rate 表达式外，State Manager 还支持多种 cron 表达式，其中包括在一周中的某一天运行关联，以及用于指定在一个月中的第 *n* 天运行关联的数字符号（\$1）。以下是一个在每月的第三个星期二 23:30 UTC 运行 cron 计划的示例：
`cron(30 23 ? * TUE#3 *)`
以下是一个在每月的第二个星期四在 UTC 午夜运行的示例：
`cron(0 0 ? * THU#2 *)`
State Manager 还支持 (L) 符号来表示一个月的最后一个 *X* 天。以下是一个在每月的最后一个星期二 UTC 午夜运行 cron 计划的示例：
`cron(0 0 ? * 3L *)`
要进一步控制关联运行的时间，例如，如果您想在星期二补丁后两天运行关联，可以指定偏移量。*偏移量*定义了在计划日期之后等待多少天再运行关联。例如，如果指定的 cron 计划为 `cron(0 0 ? * THU#2 *)`，则可以在 **Schedule offset**（计划偏移量）字段中指定数字 3，以便在每月的第二个星期四之后的每个星期天运行关联。
**注意**
要使用偏移量，必须在控制台中选择**仅在下一个指定的 Cron 周期应用关联**，或从命令行指定 `ApplyOnlyAtCronInterval` 参数。在激活其中任一选项后，State Manager 不会在您创建关联后立即运行该关联。
有关 cron 和 rate 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
## 创建关联（控制台）
以下过程介绍了如何使用 Systems Manager 控制台创建 State Manager 关联。
**注意**
请注意以下信息。
此过程描述如何创建使用 `Command` 或 `Policy` 文档来将托管式节点设为目标的关联。有关创建使用自动化运行手册以将节点或其他类型 AWS 资源设为目标的关联的信息，请参阅 [使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
创建关联时，您可以使用 AWS 管理控制台 指定最多五个标签键。当前必须将为关联指定的*所有*标签键分配给该节点。如果没有分配给该节点，则 State Manager 无法将该节点作为关联目标。
**创建 State Manager 关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择 **Create association（创建关联）**。
1. 在**名称** 字段中指定名称。
1. 在**文档**列表中，选择文档名称旁边的选项。请注意文档类型。此过程适用于 `Command` 和 `Policy` 文档。有关创建使用自动化运行手册的关联的信息，请参阅 [使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
**重要**
如果该文档是从其他账户共享的，则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是共享自另一个账户，即使 Systems Manager 控制台显示已处理该文档的新版本，状态管理器仍会运行该文档的 `default` 版本。如果要使用共享自另一个账户的文档的新版本来运行关联，则必须将文档版本设置为 `default`。
1. 对于 **Parameters (参数)**，请指定所需的输入参数。
1. （可选）对于**关联分派代入角色**，请从下拉列表中选择一个角色。状态管理器将使用此角色代表您执行操作。有关设置自定义提供的角色的信息，请参阅[为 `AssociationDispatchAssumeRole` 设置角色](state-manager-about.md#setup-assume-role)
**注意**
建议您定义一个自定义 IAM 角色，从而完全控制状态管理器在代表您执行操作时所拥有的权限。
状态管理器中对服务相关角色的支持将逐步停用。将来，依赖服务相关角色的关联可能需要更新后才能继续正常运行。
有关管理自定义提供的角色使用情况的信息，请参阅[使用 `ssm:AssociationDispatchAssumeRole` 管理 AssociationDispatchAssumeRole 的使用情况](state-manager-about.md#context-key-assume-role)。
1. （可选）选择一个 CloudWatch 警报以应用于您的关联进行监控。
**注意**
请注意与该步骤相关的以下信息。
警报列表最多显示 100 个警报。如果您未在列表中看到您的警报，请使用 AWS Command Line Interface 创建关联。有关更多信息，请参阅 [创建关联（命令行）](#create-state-manager-association-commandline)。
要将 CloudWatch 警报附加到命令，创建关联的 IAM 主体必须具有 `iam:createServiceLinkedRole` 操作的权限。有关 CloudWatch 警报的更多信息，请参阅[使用 Amazon CloudWatch 警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。
如果您的警报激活，任何待处理的命令调用或自动化都不会运行。
1. 对于 **Targets (目标)**，选择一个选项。有关使用目标的信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
**注意**
为了在检测到新的目标节点时应用使用自动化运行手册创建的关联，必须满足某些条件。有关信息，请参阅[关于使用自动化运行手册进行目标更新](state-manager-about.md#runbook-target-updates)。
1. 在 **Specify schedule (指定计划)** 部分中，选择 **On Schedule (按计划)** 或 **No schedule (无计划)**。如果选择 **On Schedule (按计划)**，则可使用提供的按钮为关联创建 cron 或 rate 计划。
如果您不希望关联在创建后立即运行，请选中 **Apply association only at the next specified Cron interval (仅在下一个指定的 Cron 周期应用关联)**。
1. （可选）在 **Schedule offset**（计划偏移量）字段中，指定一个介于 1 和 6 之间的数字。
1. 在**高级选项**部分使用**合规性严重性**选择关联的严重级别，然后使用**更改日历**选择关联的更改日历。
合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅 [关于 State Manager 关联合规性](compliance-about.md#compliance-about-association)。
更改日历确定关联何时运行。如果日历已关闭，则不应用关联。如果日历处于打开状态，则相应地运行关联。有关更多信息，请参阅 [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md)。
1. 在 **Rate control**（速率控制）部分中，选择用于控制如何在多个节点上运行关联的选项。有关使用速率控制的更多信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
在**并发**部分中，选择一个选项：
+ 选择 **targets (目标)** 输入可同时运行关联的目标的绝对数量。
+ 选择 **percentage (百分比)** 输入可同时运行关联的目标集的百分比。
在**错误阈值**部分中，选择一个选项：
+ 选择 **errors (错误)** 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
+ 选择 **percentage (百分比)** 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
以下是为关联打开 Amazon S3 输出所需的最低权限。您可以通过将 IAM policy 附加到账户内的用户或角色，以进一步限制访问权限。Amazon EC2 实例配置文件至少应具有一个具有 `AmazonSSMManagedInstanceCore` 托管策略和以下内联策略的 IAM 角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
------
对于最低权限，导出到的 Amazon S3 存储桶必须具有 Amazon S3 控制台定义的默认设置。有关创建存储桶的更多信息，请转至 *Amazon S3 用户指南*中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)。
**注意**
在关联运行期间由 SSM 文档发起的 API 操作未登录 AWS CloudTrail。
1. 选择**创建关联**。
**注意**
如果您删除已创建的关联，则该关联将不再在该关联的任何目标上运行。
## 创建关联（命令行）
以下过程介绍了如何使用 AWS CLI（在 Linux 或 Windows Server 上）或 Tools for PowerShell 创建 State Manager 关联。本节包括几个示例，说明如何使用目标和速率控制。通过目标和速率控制，您可以将关联分配给数十个或数百个节点，同时控制这些关联的执行。有关目标和速率控制的更多信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
**重要**
此过程描述如何创建使用 `Command` 或 `Policy` 文档来将托管式节点设为目标的关联。有关创建使用自动化运行手册以将节点或其他类型 AWS 资源设为目标的关联的信息，请参阅 [使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
**开始前的准备工作**
`targets` 参数是一组搜索条件，使用您指定的 `Key`,`Value` 组合将节点设为目标。如果您计划使用 `targets` 参数在数十个或数百个节点上创建关联，请在开始该过程之前查看以下设置目标选项。
通过指定 ID 将特定节点设为目标
```
--targets Key=InstanceIds,Values=instance-id-1,instance-id-2,instance-id-3
```
```
--targets Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
```
通过使用标签将实例设为目标
```
--targets Key=tag:tag-key,Values=tag-value-1,tag-value-2,tag-value-3
```
```
--targets Key=tag:Environment,Values=Development,Test,Pre-production
```
通过使用 AWS Resource Groups 将节点设为目标
```
--targets Key=resource-groups:Name,Values=resource-group-name
```
```
--targets Key=resource-groups:Name,Values=WindowsInstancesGroup
```
在当前 AWS 账户 和 AWS 区域 将所有的实例设为目标
```
--targets Key=InstanceIds,Values=*
```
**注意**
请注意以下信息。
如果该文档是从其他账户共享的，则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是共享自另一个账户，即使 Systems Manager 控制台显示已处理该文档的新版本，状态管理器仍会运行该文档的 `default` 版本。如果要使用共享自另一个账户的文档的新版本来运行关联，则必须将文档版本设置为 `default`。
State Manager 不支持 [TargetLocation](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_TargetLocation.html) 的 `IncludeChildOrganizationUnits`、`ExcludeAccounts`、`TargetsMaxErrors`、`TargetsMaxConcurrency`、`Targets`、`TargetLocationAlarmConfiguration` 参数。
您可以使用 AWS CLI 指定最多五个标签键。如果使用 AWS CLI，则 `create-association` 命令中指定的*所有*标签键当前都必须分配给该节点。如果没有分配给该节点，则 State Manager 无法将该节点作为关联目标。
当创建关联时，需要指定计划运行的时间。使用 cron 或 rate 表达式指定计划。有关 cron 和 rate 表达式的更多信息，请参阅 [适用于关联的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md#reference-cron-and-rate-expressions-association)。
为了在检测到新的目标节点时应用使用自动化运行手册创建的关联，必须满足某些条件。有关信息，请参阅[关于使用自动化运行手册进行目标更新](state-manager-about.md#runbook-target-updates)。
**创建关联**
1. 安装并配置 AWS CLI 或 AWS Tools for PowerShell（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 使用以下格式创建一个命令以创建 State Manager 关联。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--name document_name \
--document-version version_of_document_applied \
--instance-id instances_to_apply_association_on \
--parameters (if any) \
--targets target_options \
--association-dispatch-assume-role arn_of_role_to_be_used_when_dispatching_configurations \
--schedule-expression "cron_or_rate_expression" \
--apply-only-at-cron-interval required_parameter_for_schedule_offsets \
--schedule-offset number_between_1_and_6 \
--output-location s3_bucket_to_store_output_details \
--association-name association_name \
--max-errors a_number_of_errors_or_a_percentage_of_target_set \
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
--compliance-severity severity_level \
--calendar-names change_calendar_names \
--target-locations aws_region_or_account \
--tags "Key=tag_key,Value=tag_value"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--name document_name ^
--document-version version_of_document_applied ^
--instance-id instances_to_apply_association_on ^
--parameters (if any) ^
--targets target_options ^
--association-dispatch-assume-role arn_of_role_to_be_used_when_dispatching_configurations ^
--schedule-expression "cron_or_rate_expression" ^
--apply-only-at-cron-interval required_parameter_for_schedule_offsets ^
--schedule-offset number_between_1_and_6 ^
--output-location s3_bucket_to_store_output_details ^
--association-name association_name ^
--max-errors a_number_of_errors_or_a_percentage_of_target_set ^
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
--compliance-severity severity_level ^
--calendar-names change_calendar_names ^
--target-locations aws_region_or_account ^
--tags "Key=tag_key,Value=tag_value"
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-Name document_name `
-DocumentVersion version_of_document_applied `
-InstanceId instances_to_apply_association_on `
-Parameters (if any) `
-Target target_options `
-AssociationDispatchAssumeRole arn_of_role_to_be_used_when_dispatching_configurations `
-ScheduleExpression "cron_or_rate_expression" `
-ApplyOnlyAtCronInterval required_parameter_for_schedule_offsets `
-ScheduleOffSet number_between_1_and_6 `
-OutputLocation s3_bucket_to_store_output_details `
-AssociationName association_name `
-MaxError a_number_of_errors_or_a_percentage_of_target_set
-MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
-ComplianceSeverity severity_level `
-CalendarNames change_calendar_names `
-TargetLocations aws_region_or_account `
-Tags "Key=tag_key,Value=tag_value"
```
------
以下示例在已贴标签 `"Environment,Linux"` 的节点上创建关联。该关联在每个星期日 2:00 UTC 时使用 `AWS-UpdateSSMAgent` 文档更新目标节点上的 SSM Agent。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name Update_SSM_Agent_Linux \
--targets Key=tag:Environment,Values=Linux \
--name AWS-UpdateSSMAgent \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--compliance-severity "MEDIUM" \
--schedule-expression "cron(0 2 ? * SUN *)" \
--max-errors "5" \
--max-concurrency "10"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name Update_SSM_Agent_Linux ^
--targets Key=tag:Environment,Values=Linux ^
--name AWS-UpdateSSMAgent ^
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--compliance-severity "MEDIUM" ^
--schedule-expression "cron(0 2 ? * SUN *)" ^
--max-errors "5" ^
--max-concurrency "10"
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-AssociationName Update_SSM_Agent_Linux `
-Name AWS-UpdateSSMAgent `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-Target @{
"Key"="tag:Environment"
"Values"="Linux"
} `
-ComplianceSeverity MEDIUM `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-MaxConcurrency 10 `
-MaxError 5
```
------
以下示例通过指定通配符值 (\$1) 来将节点 ID 指定为目标。这允许 Systems Manager 在当前 AWS 账户 和 AWS 区域 中的*所有*节点上创建关联。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。此关联使用了计划偏移量，这意味着将在指定的 cron 计划后两天运行。其还包括 `ApplyOnlyAtCronInterval` 参数，该参数是使用计划偏移量所必需的，这意味着关联在创建后不会立即运行。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name Update_SSM_Agent_Linux \
--name "AWS-UpdateSSMAgent" \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--targets "Key=instanceids,Values=*" \
--compliance-severity "MEDIUM" \
--schedule-expression "cron(0 2 ? * SUN#2 *)" \
--apply-only-at-cron-interval \
--schedule-offset 2 \
--max-errors "5" \
--max-concurrency "10" \
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name Update_SSM_Agent_Linux ^
--name "AWS-UpdateSSMAgent" ^
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--targets "Key=instanceids,Values=*" ^
--compliance-severity "MEDIUM" ^
--schedule-expression "cron(0 2 ? * SUN#2 *)" ^
--apply-only-at-cron-interval ^
--schedule-offset 2 ^
--max-errors "5" ^
--max-concurrency "10" ^
--apply-only-at-cron-interval
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-AssociationName Update_SSM_Agent_All `
-Name AWS-UpdateSSMAgent `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-Target @{
"Key"="InstanceIds"
"Values"="*"
} `
-ScheduleExpression "cron(0 2 ? * SUN#2 *)" `
-ApplyOnlyAtCronInterval `
-ScheduleOffset 2 `
-MaxConcurrency 10 `
-MaxError 5 `
-ComplianceSeverity MEDIUM `
-ApplyOnlyAtCronInterval
```
------
以下示例在 Resource Groups 中的节点上创建关联。该组名为“HR-Department”。该关联在每个星期日 2:00 UTC 时使用 `AWS-UpdateSSMAgent` 文档更新目标节点上的 SSM Agent。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。此关联按指定的 cron 计划运行。它不会在创建后立即运行。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name Update_SSM_Agent_Linux \
--targets Key=resource-groups:Name,Values=HR-Department \
--name AWS-UpdateSSMAgent \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--compliance-severity "MEDIUM" \
--schedule-expression "cron(0 2 ? * SUN *)" \
--max-errors "5" \
--max-concurrency "10" \
--apply-only-at-cron-interval
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name Update_SSM_Agent_Linux ^
--targets Key=resource-groups:Name,Values=HR-Department ^
--name AWS-UpdateSSMAgent ^
-association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--compliance-severity "MEDIUM" ^
--schedule-expression "cron(0 2 ? * SUN *)" ^
--max-errors "5" ^
--max-concurrency "10" ^
--apply-only-at-cron-interval
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-AssociationName Update_SSM_Agent_Linux `
-Name AWS-UpdateSSMAgent `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-Target @{
"Key"="resource-groups:Name"
"Values"="HR-Department"
} `
-ScheduleExpression "cron(0 2 ? * SUN *)" `
-MaxConcurrency 10 `
-MaxError 5 `
-ComplianceSeverity MEDIUM `
-ApplyOnlyAtCronInterval
```
------
以下示例创建一个关联，该关联在已标记特定节点 ID 的节点上运行。当更改日历处于打开状态时，该关联使用 SSM Agent 文档在目标节点上更新 SSM Agent。关联在运行时检查日历状态。如果日历在启动时关闭，并且关联仅运行一次，则不会再次运行，因为关联运行窗口已通过。如果日历处于打开状态，则相应地运行关联。
**注意**
如果在更改日历关闭时将新节点添加到关联所依据的标签或 resource groups，则在更改日历打开后，关联将应用于这些节点。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name CalendarAssociation \
--targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" \
--name AWS-UpdateSSMAgent \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" \
--schedule-expression "rate(1day)"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name CalendarAssociation ^
--targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" ^
--name AWS-UpdateSSMAgent ^
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" ^
--schedule-expression "rate(1day)"
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-AssociationName CalendarAssociation `
-Target @{
"Key"="tag:instanceids"
"Values"="i-0cb2b964d3e14fd9f"
} `
-Name AWS-UpdateSSMAgent `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" `
-ScheduleExpression "rate(1day)"
```
------
以下示例创建一个关联，该关联在已标记特定节点 ID 的节点上运行。该关联在每个星期日 2:00 时使用 SSM Agent 文档更新目标节点上的 SSM Agent。此关联仅在更改日历打开时按指定的 cron 计划运行。创建关联时，它会检查日历状态。如果日历已关闭，则不应用关联。当应用关联的时间间隔从星期日凌晨 2:00 开始时，关联将检查日历是否处于打开状态。如果日历处于打开状态，则相应地运行关联。
**注意**
如果在更改日历关闭时将新节点添加到关联所依据的标签或 resource groups，则在更改日历打开后，关联将应用于这些节点。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--association-name MultiCalendarAssociation \
--targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" \
--name AWS-UpdateSSMAgent \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--association-name MultiCalendarAssociation ^
--targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" ^
--name AWS-UpdateSSMAgent ^
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" ^
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ PowerShell ]
```
New-SSMAssociation `
-AssociationName MultiCalendarAssociation `
-Name AWS-UpdateSSMAgent `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-Target @{
"Key"="tag:instanceids"
"Values"="i-0cb2b964d3e14fd9f"
} `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" `
-ScheduleExpression "cron(0 2 ? * SUN *)"
```
------
**注意**
如果您删除已创建的关联，则该关联将不再在该关联的任何目标上运行。此外，如果指定了 `apply-only-at-cron-interval` 参数，还可以重置此选项。要执行此操作，请在从命令行更新关联时指定 `no-apply-only-at-cron-interval` 参数。此参数会强制关联在更新后立即运行，以及按照指定的周期运行。
# 编辑和创建关联的新版本
您可以编辑 State Manager 关联以指定新名称、计划、严重级别、目标或其他值。对于基于 SSM 命令类型文档的关联，您也可以选择将命令输出写入 Amazon Simple Storage Service（Amazon S3）存储桶。编辑关联后，State Manager 将创建新版本。您可以在编辑后查看不同的版本，如以下过程中所述。
**注意**
为了在检测到新的目标节点时应用使用自动化运行手册创建的关联，必须满足某些条件。有关信息，请参阅[关于使用自动化运行手册进行目标更新](state-manager-about.md#runbook-target-updates)。
以下过程介绍了如何使用 Systems Manager 控制台、AWS Command Line Interface (AWS CLI) 和 AWS Tools for PowerShell (Tools for PowerShell) 编辑和创建关联的新版本。
**重要**
如果该文档是从其他账户共享的，则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是从其他账户共享的，则 State Manager 始终会运行文档的 `default` 版本，即使 Systems Manager 控制台显示已处理了该文档的新版本。如果要使用共享自另一个账户的文档的新版本来运行关联，则必须将文档版本设置为 `default`。
## 编辑关联（控制台）
以下过程介绍了如何使用 Systems Manager 控制台编辑和创建关联的新版本。
**注意**
对于使用 SSM 命令文档而非自动化运行手册的关联，此过程要求您具有对现有 Amazon S3 存储桶的写入权限。如果您之前未使用 Amazon S3，请注意使用 Amazon S3 会产生费用。有关如何创建存储桶的信息，请参阅[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)。
**编辑 State Manager 关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择现有的关联，然后选择**编辑**。
1. 重新配置关联以满足当前要求。
有关与 `Command` 和 `Policy` 文档的关联选项的信息，请参阅 [创建关联](state-manager-associations-creating.md)。有关与自动化运行手册的关联选项的信息，请参阅 [使用 State Manager 关联调度自动化](scheduling-automations-state-manager-associations.md)。
1. 选择**保存更改**。
1. （可选）若要查看关联信息，在**关联**页面中，选择已编辑的关联的名称，然后选择**版本**选项卡。系统将列出您已创建和编辑的关联的每个版本。
1. （可选）若要查看基于 SSM `Command` 文档的关联输出，请执行以下操作：
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 选择您指定用于存储命令输出的 Simple Storage Service (Amazon S3) 存储桶的名称，然后选择以运行关联的节点的 ID 命名的文件夹。(如果您选择将输出存储在存储桶中的文件夹内，请先打开它。)
1. 下拉多个级别至 `stdout` 文件夹中的 `awsrunPowerShell` 文件。
1. 选择**打开**或**下载**查看主机名。
## 编辑关联（命令行）
以下过程介绍了如何使用 AWS CLI（在 Linux 或 Windows Server 上）或 AWS Tools for PowerShell 编辑和创建关联的新版本。
**编辑 State Manager 关联**
1. 安装并配置 AWS CLI 或 AWS Tools for PowerShell（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 使用以下格式创建一个命令，以编辑和创建现有 State Manager 关联的新版本。将每个*示例资源占位符*替换为您自己的信息。
**重要**
当您调用 `[https://docs.aws.amazon.com/cli/latest/reference/ssm/desupdatecribe-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/desupdatecribe-association.html)` 时，系统会从请求中删除所有可选参数，并用这些参数的 null 值覆盖关联。这是设计使然。即使没有更改参数，您也必须在调用中指定所有可选参数，包括 `--name` 参数。在调用此操作之前，建议先调用 `[https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-association.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-association.html)` 操作，并记下 `update-association` 调用所需的所有可选参数。
------
#### [ Linux & macOS ]
```
aws ssm update-association \
--name document_name \
--document-version version_of_document_applied \
--instance-id instances_to_apply_association_on \
--parameters (if any) \
--targets target_options \
--association-dispatch-assume-role arn_of_role_to_be_used_when_dispatching_configurations \
--schedule-expression "cron_or_rate_expression" \
--schedule-offset "number_between_1_and_6" \
--output-location s3_bucket_to_store_output_details \
--association-name association_name \
--max-errors a_number_of_errors_or_a_percentage_of_target_set \
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
--compliance-severity severity_level \
--calendar-names change_calendar_names \
--target-locations aws_region_or_account
```
------
#### [ Windows ]
```
aws ssm update-association ^
--name document_name ^
--document-version version_of_document_applied ^
--instance-id instances_to_apply_association_on ^
--parameters (if any) ^
--targets target_options ^
--association-dispatch-assume-role arn_of_role_to_be_used_when_dispatching_configurations ^
--schedule-expression "cron_or_rate_expression" ^
--schedule-offset "number_between_1_and_6" ^
--output-location s3_bucket_to_store_output_details ^
--association-name association_name ^
--max-errors a_number_of_errors_or_a_percentage_of_target_set ^
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
--compliance-severity severity_level ^
--calendar-names change_calendar_names ^
--target-locations aws_region_or_account
```
------
#### [ PowerShell ]
```
Update-SSMAssociation `
-Name document_name `
-DocumentVersion version_of_document_applied `
-InstanceId instances_to_apply_association_on `
-Parameters (if any) `
-Target target_options `
-AssociationDispatchAssumeRole arn_of_role_to_be_used_when_dispatching_configurations `
-ScheduleExpression "cron_or_rate_expression" `
-ScheduleOffset "number_between_1_and_6" `
-OutputLocation s3_bucket_to_store_output_details `
-AssociationName association_name `
-MaxError a_number_of_errors_or_a_percentage_of_target_set
-MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
-ComplianceSeverity severity_level `
-CalendarNames change_calendar_names `
-TargetLocations aws_region_or_account
```
------
以下示例更新现有关联以将名称更改为 `TestHostnameAssociation2`。新的关联版本每小时运行一次，并将命令输出写入到指定的 Amazon S3 存储桶中。
------
#### [ Linux & macOS ]
```
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name TestHostnameAssociation2 \
--parameters commands="echo Association" \
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--schedule-expression "cron(0 */1 * * ? *)"
```
------
#### [ Windows ]
```
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name TestHostnameAssociation2 ^
--parameters commands="echo Association" ^
--association-dispatch-assume-role arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--schedule-expression "cron(0 */1 * * ? *)"
```
------
#### [ PowerShell ]
```
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName TestHostnameAssociation2 `
-Parameter @{"commands"="echo Association"} `
-AssociationDispatchAssumeRole "arn:aws:iam::123456789012:role/myAssociationDispatchAssumeRole" `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-S3Location_OutputS3KeyPrefix logs `
-S3Location_OutputS3Region us-east-1 `
-ScheduleExpression "cron(0 */1 * * ? *)"
```
------
以下示例更新现有关联以将名称更改为 `CalendarAssociation`。新关联在日历打开时运行，并将命令输出写入指定的 Amazon S3 存储桶。
------
#### [ Linux & macOS ]
```
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name CalendarAssociation \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
```
------
#### [ Windows ]
```
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name CalendarAssociation ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
```
------
#### [ PowerShell ]
```
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName CalendarAssociation `
-AssociationName OneTimeAssociation `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
```
------
以下示例更新现有关联以将名称更改为 `MultiCalendarAssociation`。当日历打开并将命令输出写入指定的 Amazon S3 存储桶时，新关联将运行。
------
#### [ Linux & macOS ]
```
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name MultiCalendarAssociation \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
```
------
#### [ Windows ]
```
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name MultiCalendarAssociation ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
```
------
#### [ PowerShell ]
```
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName MultiCalendarAssociation `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
```
------
1. 要查看关联的新版本，请运行以下命令。
------
#### [ Linux & macOS ]
```
aws ssm describe-association \
--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE
```
------
#### [ Windows ]
```
aws ssm describe-association ^
--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE
```
------
#### [ PowerShell ]
```
Get-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE | Select-Object *
```
------
系统将返回类似于以下内容的信息。
------
#### [ Linux & macOS ]
```
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3Region": "us-east-1"
}
},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}
```
------
#### [ Windows ]
```
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3Region": "us-east-1"
}
},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}
```
------
#### [ PowerShell ]
```
AssociationId : b85ccafe-9f02-4812-9b81-01234EXAMPLE
AssociationName : TestHostnameAssociation2
AssociationVersion : 2
AutomationTargetParameterName :
ComplianceSeverity :
Date : 5/31/2019 2:47:18 PM
DocumentVersion : $DEFAULT
InstanceId :
LastExecutionDate : 5/31/2019 3:26:40 PM
LastSuccessfulExecutionDate : 5/31/2019 3:26:40 PM
LastUpdateAssociationDate : 5/31/2019 3:26:29 PM
MaxConcurrency :
MaxErrors :
Name : AWS-RunPowerShellScript
OutputLocation : Amazon.SimpleSystemsManagement.Model.InstanceAssociationOutputLocation
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
Parameters : {[commands, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
ScheduleExpression : cron(0 */1 * * ? *)
Status :
Targets : {tag:Environment}
```
------
# 删除关联
可以使用以下过程，通过使用 AWS Systems Manager 控制台删除关联。
**删除关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择某一关联，然后选择**删除**。
通过从 AWS Systems Manager 控制台运行自动化，可以在单个操作中删除多个关联。当您选择多个关联进行删除时，State Manager 会启动自动化运行手册起始页面，并将关联 ID 作为输入参数值输入。
**要在单个操作中删除多个关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择要删除的每个关联，然后选择**删除**。
1. （可选）在**其他输入参数**区域中，选择您希望自动化在运行时使用的*代入角色*的 Amazon 资源名称（ARN）。要创建新的代入角色，请选择**创建**。
1. 选择**提交**。
# 运行 Auto Scaling 组
使用关联运行 Auto Scaling 组时的最佳做法是使用标记目标。不使用标签可能会导致您达到关联限制。
如果所有节点都使用相同的键和值进行标记，则您只需要一个关联即可运行 Auto Scaling 组。以下过程介绍了如何创建关联。
**创建运行 Auto Scaling 组的关联**
1. 确保 Auto Scaling 组中的所有节点都使用相同的键和值进行标记。有关标签节点的更多说明，请参阅*AWS Auto Scaling 用户指南*中的[标记 Auto Scaling 组和实例](https://docs.aws.amazon.com//autoscaling/ec2/userguide/autoscaling-tagging.html)。
1. 通过使用 [在 Systems Manager 中使用关联。](state-manager-associations.md) 中的过程来创建关联。
如果您在控制台中使用，请选择**目标**字段中的**指定实例标签**返回的子位置类型。对于**实例标签**，请输入 Auto Scaling 组的**标记**键和值。
如果您使用的是AWS Command Line Interface(AWS CLI)，请指定其中键和值与您标记节点的内容相匹配的`--targets Key=tag:tag-key,Values=tag-value`。
# 查看关联历史记录
您可以使用 [DescribeAssociationExecutions](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeAssociationExecutions.html) API 操作查看特定关联 ID 的所有执行。使用此操作可查看State Manager关联的状态、详细状态、结果、上次执行时间以及其他信息。State Manager是 AWS Systems Manager 中的一项工具。此 API 操作还包括筛选条件，帮助您根据指定的条件快速找到关联。例如，您可以指定一个确切的日期和时间，并使用 GREATER\$1THAN 筛选条件以查看在该指定的日期和时间之后处理的那些执行。
例如，如果一个关联执行失败，则可使用 [DescribeAssociationExecutionTargets](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeAssociationExecutionTargets.html) API 操作来深入了解特定执行的详细信息。此操作将为您显示资源，例如节点 ID、关联运行的位置和各种关联状态。您可以查看哪些资源或节点无法运行关联。利用资源 ID，您随后可以查看命令执行详细信息，以了解命令中的哪个步骤已失败。
本节中的示例还包括有关如何在创建时使用 [StartAssociationsOnce](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartAssociationsOnce.html) API 操作运行一次关联的信息。在调查失败的关联执行时，可以使用此 API 操作。如果发现一个关联失败，则可以在资源上进行更改，然后立即运行关联以查看对资源所做的更改是否可让关联成功运行。
**注意**
在关联运行期间由 SSM 文档发起的 API 操作未登录 AWS CloudTrail。
## 查看关联历史记录（控制台）
使用以下过程可查看特定关联 ID 的执行历史记录，然后查看一个或多个资源的执行详细信息。
**查看特定关联 ID 的执行历史记录**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 选择 **State Manager**。
1. 在 **Association id (关联 ID)** 字段中，选择要查看其历史记录的关联。
1. 选择 **View details (查看详细信息)** 按钮。
1. 选择 **Execution history (执行历史记录)** 选项卡。
1. 选择要查看其资源级别执行详细信息的关联。例如，选择显示 **Failed (失败)** 状态的关联。然后，您可以查看无法运行关联的节点的执行详细信息。
使用搜索框筛选条件以找到要查看其详细信息的执行。
![\[筛选 State Manager 关联执行的列表。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sysman-state-executions-filter.png)
1. 选择执行 ID。此时将打开 **Association execution targets (关联执行目标)** 页面。此页面显示所有已运行关联的资源。
1. 选择一个资源 ID 以查看有关此资源的特定信息。
使用搜索框筛选条件以找到要查看其详细信息的资源。
![\[筛选 State Manager 关联执行目标的列表。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sysman-state-executions-targets-filter.png)
1. 如果您正在调查无法运行的关联，则在创建时可使用 **Apply association now (立即应用关联)** 按钮来运行一次关联。在对无法运行关联的资源进行更改后，在导航位置提示中选择 **Association ID (关联 ID)** 链接。
1. 选择 **Apply association now (立即应用关联)** 按钮。在执行完成后，验证关联执行是否成功。
## 查看关联历史记录（命令行）
以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）（在 Linux 或 Windows Server 上）或 AWS Tools for PowerShell 查看特定关联 ID 的执行历史记录。然后，该过程介绍了如何查看一个或多个资源的执行详细信息。
**查看特定关联 ID 的执行历史记录**
1. 安装并配置 AWS CLI 或 AWS Tools for PowerShell（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 运行以下命令以查看特定关联 ID 的执行列表。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-executions \
--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
```
**注意**
此命令包含一个筛选条件，可将结果限定为仅在特定日期和时间之后发生的那些执行。如果要查看特定关联 ID 的所有执行，请删除 `--filters` 参数和 ` Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN` 值。
------
#### [ Windows ]
```
aws ssm describe-association-executions ^
--association-id ID ^
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN
```
**注意**
此命令包含一个筛选条件，可将结果限定为仅在特定日期和时间之后发生的那些执行。如果要查看特定关联 ID 的所有执行，请删除 `--filters` 参数和 ` Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN` 值。
------
#### [ PowerShell ]
```
Get-SSMAssociationExecution `
-AssociationId ID `
-Filter @{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="GREATER_THAN"}
```
**注意**
此命令包含一个筛选条件，可将结果限定为仅在特定日期和时间之后发生的那些执行。如果要查看特定关联 ID 的所有执行，请删除 `-Filter` 参数和 ` @{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="GREATER_THAN"}` 值。
------
系统将返回类似于以下内容的信息。
------
#### [ Linux & macOS ]
```
{
"AssociationExecutions":[
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"CreatedTime":1523986028.219,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"CreatedTime":1523984226.074,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"CreatedTime":1523982404.013,
"AssociationVersion":"1"
}
]
}
```
------
#### [ Windows ]
```
{
"AssociationExecutions":[
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"CreatedTime":1523986028.219,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"CreatedTime":1523984226.074,
"AssociationVersion":"1"
},
{
"Status":"Success",
"DetailedStatus":"Success",
"AssociationId":"c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId":"ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"CreatedTime":1523982404.013,
"AssociationVersion":"1"
}
]
}
```
------
#### [ PowerShell ]
```
AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/18/2019 2:00:50 AM
DetailedStatus : Success
ExecutionId : 76a5a04f-caf6-490c-b448-92c02EXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}
Status : Success
AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/11/2019 2:00:54 AM
DetailedStatus : Success
ExecutionId : 791b72e0-f0da-4021-8b35-f95dfEXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}
Status : Success
AssociationId : c336d2ab-09de-44ba-8f6a-6136cEXAMPLE
AssociationVersion : 1
CreatedTime : 8/4/2019 2:01:00 AM
DetailedStatus : Success
ExecutionId : ecec60fa-6bb0-4d26-98c7-140308EXAMPLE
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=1}
Status : Success
```
------
您可以使用一个或多个筛选条件来限制结果。以下示例返回在特定日期和时间之前运行的所有关联。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-executions \
--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=LESS_THAN
```
------
#### [ Windows ]
```
aws ssm describe-association-executions ^
--association-id ID ^
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=LESS_THAN
```
------
#### [ PowerShell ]
```
Get-SSMAssociationExecution `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-Filter @{"Key"="CreatedTime";"Value"="2019-06-01T19:15:38.372Z";"Type"="LESS_THAN"}
```
------
下面返回在特定日期和时间之后*成功* 运行的所有关联。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-executions \
--association-id ID \
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN Key=Status,Value=Success,Type=EQUAL
```
------
#### [ Windows ]
```
aws ssm describe-association-executions ^
--association-id ID ^
--filters Key=CreatedTime,Value="2018-04-10T19:15:38.372Z",Type=GREATER_THAN Key=Status,Value=Success,Type=EQUAL
```
------
#### [ PowerShell ]
```
Get-SSMAssociationExecution `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-Filter @{
"Key"="CreatedTime";
"Value"="2019-06-01T19:15:38.372Z";
"Type"="GREATER_THAN"
},
@{
"Key"="Status";
"Value"="Success";
"Type"="EQUAL"
}
```
------
1. 运行以下命令可查看已运行特定执行的所有目标。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-execution-targets \
--association-id ID \
--execution-id ID
```
------
#### [ Windows ]
```
aws ssm describe-association-execution-targets ^
--association-id ID ^
--execution-id ID
```
------
#### [ PowerShell ]
```
Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE
```
------
您可以使用一个或多个筛选条件来限制结果。以下示例返回有关所有无法运行特定关联的目标的信息。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-execution-targets \
--association-id ID \
--execution-id ID \
--filters Key=Status,Value="Failed"
```
------
#### [ Windows ]
```
aws ssm describe-association-execution-targets ^
--association-id ID ^
--execution-id ID ^
--filters Key=Status,Value="Failed"
```
------
#### [ PowerShell ]
```
Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE `
-Filter @{
"Key"="Status";
"Value"="Failed"
}
```
------
以下示例返回有关无法运行关联的特定托管式节点的信息。
------
#### [ Linux & macOS ]
```
aws ssm describe-association-execution-targets \
--association-id ID \
--execution-id ID \
--filters Key=Status,Value=Failed Key=ResourceId,Value="i-02573cafcfEXAMPLE" Key=ResourceType,Value=ManagedInstance
```
------
#### [ Windows ]
```
aws ssm describe-association-execution-targets ^
--association-id ID ^
--execution-id ID ^
--filters Key=Status,Value=Failed Key=ResourceId,Value="i-02573cafcfEXAMPLE" Key=ResourceType,Value=ManagedInstance
```
------
#### [ PowerShell ]
```
Get-SSMAssociationExecutionTarget `
-AssociationId 14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE `
-ExecutionId 76a5a04f-caf6-490c-b448-92c02EXAMPLE `
-Filter @{
"Key"="Status";
"Value"="Success"
},
@{
"Key"="ResourceId";
"Value"="i-02573cafcfEXAMPLE"
},
@{
"Key"="ResourceType";
"Value"="ManagedInstance"
}
```
------
1. 如果您正在调查无法运行的关联，则可使用 [StartAssociationsOnce](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartAssociationsOnce.html) API 操作来立即运行且仅运行一次关联。在更改关联无法运行的资源后，运行以下命令以立即运行关联，并且仅运行一次。
------
#### [ Linux & macOS ]
```
aws ssm start-associations-once \
--association-id ID
```
------
#### [ Windows ]
```
aws ssm start-associations-once ^
--association-id ID
```
------
#### [ PowerShell ]
```
Start-SSMAssociationsOnce `
-AssociationId ID
```
------
# 使用 IAM 处理关联
State Manager（AWS Systems Manager 中的一项工具）使用[目标](systems-manager-state-manager-targets-and-rate-controls.md#systems-manager-state-manager-targets-and-rate-controls-about-targets)选择要使用哪些实例配置关联。最初，关联是通过指定文档名称（`Name`）和实例 ID（`InstanceId`)创建的。这会在文档和实例或托管式节点之间创建关联。通过这些参数标识的关联。这些参数现在已弃用，但仍受支持。资源 `instance` 和 `managed-instance` 作为资源添加到具有 `Name` 和 `InstanceId` 的操作中。
AWS Identity and Access Management (IAM) 策略实施行为取决于指定的资源类型。State Manager 操作的资源仅根据传入的请求强制执行。State Manager 不会对账户中的资源属性进行深入检查。只有当请求参数包含指定的策略资源时，才会根据策略资源验证请求。例如，如果您在资源块中指定了一个实例，则如果请求使用 `InstanceId` 参数，策略会强制执行。不会为`InstanceId` 检查账户中每项资源的 `Targets` 参数。
以下是一些具有混淆的行为的情况：
+ [DescribeAssociation](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_DescribeActivations.html)、[DeleteAssociation](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_DeleteAssociation.html) 和 [UpdateAssociation](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_UpdateAssociation.html) 使用 `instance`、`managed-instance` 和 `document` 资源来指定已弃用的引用关联的方式。这包括所有使用已弃用使用的 `InstanceId` 参数创建的关联。
+ [CreateAssociation](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_CreateAssociation.html)、[CreateAssociationBatch](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_CreateAssociationBatch.html) 和 [UpdateAssociation](https://docs.aws.amazon.com//systems-manager/latest/APIReference/API_UpdateAssociation.html) 使用 `instance` 和 `managed-instance` 资源来指定已弃用的引用关联的方式。这包括所有使用已弃用的 `InstanceId` 参数创建的关联。`document` 资源类型是已弃用的引用关联方式的一部分，并且是关联的实际属性。这意味着您可以根据文档名称为 `Create` 和 `Update` 操作构建具有 `Allow` 或 `Deny` 权限的 IAM 策略。
有关将 IAM 策略与 Systems Manager 配合使用的更多信息，请参阅 *服务授权参考*中的 [对 AWS Systems Manager 进行身份和访问管理](security-iam.md) 或者[操作、资源和条件键 AWS Systems Manager](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssystemsmanager.html)。
# 创建运行 MOF 文件的关联
您可以使用 `AWS-ApplyDSCMofs` SSM 文档运行托管对象格式（MOF）文件，通过 State Manager（AWS Systems Manager 中的一个工具）在 Windows Server 托管节点上强制执行期望状态。`AWS-ApplyDSCMofs` 文档有两种执行模式。在第一种模式下，您可以配置关联来扫描并报告托管式节点是否处于指定 MOF 文件中定义的期望状态。在第二种模式下，您可以运行 MOF 文件并根据 MOF 文件中定义的资源及其值更改节点的配置。`AWS-ApplyDSCMofs` 文档允许您从 Amazon Simple Storage Service (Amazon S3)、本地共享或具有 HTTPS 域的安全网站下载和运行 MOF 配置文件。
State Manager 在每个关联运行期间记录并报告每个 MOF 文件执行的状态。State Manager 还将每个 MOF 文件执行的输出报告为合规性事件，可在 [AWS Systems Manager 合规性](https://console.aws.amazon.com/systems-manager/compliance)页面上查看该事件。
MOF 文件执行基于 Windows PowerShell Desired State Configuration(PowerShell DSC) 构建而成。PowerShell DSC 是一个声明性平台，用于配置、部署和管理 Windows 系统。PowerShell DSC 允许管理员用名为 DSC 配置的简单文本文档来描述其需要的服务器配置方式。PowerShell DSC 配置是一个专门的 PowerShell 脚本，该脚本描述任务是什么但不描述如何执行任务。运行配置会生成一个 MOF 文件。该 MOF 文件可以应用于一台或多台服务器，以在这些服务器中实现所需配置。PowerShell DSC 资源执行强制实施配置的实际工作。有关更多信息，请参阅 [Windows PowerShell Desired State Configuration Overview](https://download.microsoft.com/download/4/3/1/43113F44-548B-4DEA-B471-0C2C8578FBF8/Quick_Reference_DSC_WS12R2.pdf)。
**Topics**
+ [使用 Amazon S3 存储构件](#systems-manager-state-manager-using-mof-file-S3-storage)
+ [解析 MOF 文件中的凭证](#systems-manager-state-manager-using-mof-file-credentials)
+ [在 MOF 文件中使用令牌](#systems-manager-state-manager-using-mof-file-tokens)
+ [创建运行 MOF 文件的关联的先决条件](#systems-manager-state-manager-using-mof-file-prereqs)
+ [创建运行 MOF 文件的关联](#systems-manager-state-manager-using-mof-file-creating)
+ [排查创建运行 MOF 文件的关联时出现的问题](#systems-manager-state-manager-using-mof-file-troubleshooting)
+ [查看 DSC 资源合规性详细信息](#systems-manager-state-manager-viewing-mof-file-compliance)
## 使用 Amazon S3 存储构件
如果使用 Amazon S3 存储 PowerShell 模块、MOF 文件、合规性报告或状态报告，则 AWS Systems Manager SSM Agent使用的 AWS Identity and Access Management (IAM) 角色必须拥有存储桶的 `GetObject` 和 `ListBucket` 权限。如果您不提供这些权限，系统将返回*拒绝访问* 错误。以下是有关在 Amazon S3 中存储构件的重要信息。
+ 如果存储桶位于不同的 AWS 账户 中，请创建一个存储桶资源策略，向该账户（或 IAM 角色）授予 `GetObject` 和 `ListBucket` 权限。
+ 如果要使用自定义 DSC 资源，则可从 Amazon S3 存储桶中下载这些资源。您也可以从 PowerShell 库中自动安装这些资源。
+ 如果使用 Amazon S3 作为模块源，请以 Zip 文件形式上传该模块，采用以下区分大小写的格式：*ModuleName*\$1*ModuleVersion*.zip。例如：MyModule\$11.0.0.zip。
+ 所有文件都必须位于存储桶根中。不支持文件夹结构。
## 解析 MOF 文件中的凭证
可使用 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) 或 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md) 来解析凭证。这样，可以设置自动凭证轮换。DSC 也可以自动将凭证传播到服务器，而不必重新部署 MOF。
要在配置中使用 AWS Secrets Manager 密钥，请创建一个 PSCredential 对象，其中用户名是包含凭证的密钥的 SecretId 或 SecretARN。可为密码指定任意值。该值将被忽略。以下为示例。
```
Configuration MyConfig
{
$ss = ConvertTo-SecureString -String 'a_string' -AsPlaintext -Force
$credential = New-Object PSCredential('a_secret_or_ARN', $ss)
Node localhost
{
File file_name
{
DestinationPath = 'C:\MyFile.txt'
SourcePath = '\\FileServer\Share\MyFile.txt'
Credential = $credential
}
}
}
```
请使用配置数据中的 PsAllowPlaintextPassword 设置来编译 MOF。因为凭证只包含一个标签，所以可以这样做。
在 Secrets Manager 中，确保节点具有 IAM 托管式策略和（可选的）密钥资源策略（如果存在）中的 GetSecretValue 访问权限。要使用 DSC，密钥必须采用以下格式。
```
{ 'Username': 'a_name', 'Password': 'a_password' }
```
密钥可以具有其他属性（例如，用于轮换的属性），但它至少需具有用户名和密码属性。
建议使用多用户轮换方法，这样，您有两组不同的用户名和密码，轮换 AWS Lambda 函数会轮流使用这两组用户名和密码。此方法允许您有多个活动账户，消除了在轮换期间锁定用户的风险。
## 在 MOF 文件中使用令牌
通过令牌可以在编译 MOF *之后* 修改资源属性值。这样，您可以在需要相似配置的多台服务器上重用通用 MOF 文件。
令牌替换仅适用于 `String` 类型的资源属性。但是，如果资源具有嵌套的 CIM 节点属性，它也会从该 CIM 节点的 `String` 属性中解析令牌。不能将令牌替换用于数字或数组。
例如，考虑以下场景：您使用的是 xComputerManagement 资源，并且您希望使用 DSC 重命名计算机。通常，您需要对该计算机使用一个专用的 MOF 文件。但是，有了令牌支持，您可以创建一个 MOF 文件并将其应用于您的所有节点。在 `ComputerName` 属性中，不必将计算机名称硬编码到 MOF 中，您可以使用实例标签类型的令牌。在 MOF 解析期间会解析此值。请参阅以下示例。
```
Configuration MyConfig
{
xComputer Computer
{
ComputerName = '{tag:ComputerName}'
}
}
```
然后，您可以在 Systems Manager 控制台中的托管式节点上设置标签，或在 Amazon EC2 控制台中设置 Amazon Elastic Compute Cloud (Amazon EC2) 标签。运行该文档时，脚本将 \$1tag:ComputerName\$1 令牌替换为实例标签的值。
您还可以将多个标签组合到单个属性中，如下面的示例所示。
```
Configuration MyConfig
{
File MyFile
{
DestinationPath = '{env:TMP}\{tag:ComputerName}'
Type = 'Directory'
}
}
```
您可以使用以下 5 种不同类型的令牌：
+ **标签**：Amazon EC2 或托管式节点标签。
+ **tagb64**：与标签相同，但系统使用 base64 对值解码。这样您可以在标签值中使用特殊字符。
+ **env**：解析环境变量。
+ **ssm**：Parameter Store 值。仅支持字符串和安全字符串类型。
+ **tagssm**：与标签相同，但如果未在节点上设置标签，系统将尝试从同名的 Systems Manager 参数中解析值。如果需要“原定设置全局值”，但希望能够在单个节点（例如，一站式部署）中覆盖该值时，此令牌很有用。
以下是使用 `ssm` 令牌类型的 Parameter Store 示例。
```
File MyFile
{
DestinationPath = "C:\ProgramData\ConnectionData.txt"
Content = "{ssm:%servicePath%/ConnectionData}"
}
```
令牌通过使 MOF 文件变为通用和可重用，在减少冗余代码方面发挥了重要作用。如果可以避免特定于服务器的 MOF 文件，则无需 MOF 构建服务。MOF 构建服务会增加成本、减少调配时间并增加分组节点之间因编译其 MOF 时在编译服务器上安装的模块版本不同而产生配置偏差的风险。
## 创建运行 MOF 文件的关联的先决条件
在创建用于运行 MOF 文件的关联之前，请验证托管式节点是否已安装以下必备组件：
+ Windows PowerShell 5.0 或更高版本。有关更多信息，请参阅 Microsoft.com 上的 [Windows PowerShell 系统要求](https://docs.microsoft.com/en-us/powershell/scripting/install/windows-powershell-system-requirements?view=powershell-6)。
+ [AWS Tools for Windows PowerShell](https://aws.amazon.com/powershell/) 1.5.13 版或更高版本。
+ SSM Agent 2.2 或更高版本。
## 创建运行 MOF 文件的关联
**创建运行 MOF 文件的关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择 **State Manager**，然后选择 **创建关联**。
1. 在**名称** 字段中指定名称。您可以自由选择，但我们建议您这样做。名称可以帮助了解您在创建关联时为关联考虑的用途。名称不得包含空格。
1. 在 **Command (文档)** 列表中，选择 **`AWS-ApplyDSCMofs`**。
1. 在 **Parameters (参数)** 部分中，指定您选择的必需和可选输入参数。
1. **Mofs To Apply (要应用的 Mof)**：指定要在此关联运行时运行的一个或多个 MOF 文件。使用逗号分隔 MOF 文件的列表。Systems Manager 会遍历 MOF 文件列表，并按照逗号分隔列表中指定的顺序运行这些文件。
+ Amazon S3 存储桶名。存储桶名称必须使用小写字母。可使用以下格式指定此信息：
```
s3:amzn-s3-demo-bucket:MOF_file_name.mof
```
如果要指定 AWS 区域，请使用以下格式：
```
s3:bucket_Region:amzn-s3-demo-bucket:MOF_file_name.mof
```
+ 安全的网站。可使用以下格式指定此信息。
```
https://domain_name/MOF_file_name.mof
```
见下列。
```
https://www.example.com/TestMOF.mof
```
+ 本地共享中的文件系统。可使用以下格式指定此信息。
```
\server_name\shared_folder_name\MOF_file_name.mof
```
见下列。
```
\StateManagerAssociationsBox\MOFs_folder\MyMof.mof
```
1. **Service Path (服务路径)**：（可选）服务路径可以是要将报告和状态信息写入到的 Amazon S3 存储桶前缀。服务路径也可以是用于基于 Parameter Store 参数的标签的路径。在解析基于参数的标签时，系统将使用 \$1ssm:%servicePath%/*parameter\$1name*\$1 将 servicePath 值注入参数名称中。例如，如果服务路径是“WebServers/Production”，则系统将该参数解析为：WebServers/Production/*parameter\$1name*。在同一账户中运行多个环境时，此服务路径很有用。
1. **Report Bucket Name (报告存储桶名称)**：（可选）输入要写入合规性数据的 Amazon S3 存储桶的名称。报告以 JSON 格式保存在此存储桶中。
**注意**
您可以用存储桶所在的区域作为存储桶名称的前缀。下面是一个示例：us-west-2:MyMOFBucket。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
1. **操作模式**：选择：选择 State Manager 行为时运行 **`AWS-ApplyDSCMofs`** 关联：
+ **Apply**（应用）：更正不合规的节点配置。
+ **ReportOnly**：不更正节点配置，但录入所有合规性数据并报告不合规节点。
1. **Status Bucket Name (状态存储桶名称)**：（可选）输入要将 MOF 执行状态信息写入到的 Amazon S3 存储桶的名称。这些状态报告是节点的最新合规性运行的单例摘要。这意味着，下次关联运行 MOF 文件时，将覆盖该报告。
**注意**
您可以用存储桶所在的区域作为存储桶名称的前缀。示例如下：`us-west-2:amzn-s3-demo-bucket`。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
1. **Module Source Bucket Name (模块源存储桶名称)**：（可选）输入包含 PowerShell 模块文件的 Amazon S3 存储桶的名称。如果您指定**无**中，为下一个选项选择**真**，**允许 PS Gallery 模块源**。
**注意**
您可以用存储桶所在的区域作为存储桶名称的前缀。示例如下：`us-west-2:amzn-s3-demo-bucket`。如果对不包括 us-east-1 在内的特定区域中的 Amazon S3 端点使用代理，则必须用区域作为存储桶名称的前缀。如果存储桶名称不含前缀，它会使用 us-east-1 端点自动发现存储桶区域。
1. **Allow PS Gallery Module Source (允许 PS 库模块源)**：（可选）选择 **True** 从 [https://www.powershellgallery.com/](https://www.powershellgallery.com/) 下载 PowerShell 模块。如果选择 **假**，请为上一个选项 **ModuleSourceBucketName** 指定源。
1. **Proxy Uri (代理 URI)**：（可选）使用此选项可从代理服务器下载 MOF 文件。
1. **Reboot Behavior ()**：（可选）如果 MOF 文件执行需要重启，请指定以下重启行为之一：
+ **AfterMof**：在所有 MOF 执行完成后重启节点。即使多个 MOF 执行请求重启，系统也会等到所有 MOF 执行完成才重启。
+ **Immediately**（立即）：只要 MOF 执行请求，即重启节点。如果实例运行请求重启的多个 MOF 文件，则会多次重启该节点。
+ **Never**（从不）：即使 MOF 执行明确请求重启，节点也不重启。
1. **Use Computer Name For Reporting (将计算机名称用于报告)**：（可选）启用此选项可在报告合规性信息时使用计算机的名称。原定设置值为 **false**，这意味着系统在报告合规性信息时会使用节点 ID。
1. **Enable Verbose Logging (启用详细日志记录)**：（可选）建议在首次部署 MOF 文件时启用详细日志记录。
**重要**
启用后，详细日志记录会向 Amazon S3 存储桶中写入比标准关联执行日志记录更多的数据。这可能会导致性能变慢，并且 Amazon S3 的存储费用可能会变高。要缓解存储大小问题，建议在 Amazon S3 存储桶中启用生命周期策略。有关更多信息，请参阅 [Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-lifecycle.html)中的*如何为 S3 Bucket 创建生命周期策略？*。
1. **Enable Debug Logging (启用调试日志记录)**：（可选）建议启用调试日志记录排除 MOF 故障。我们还建议您在正常使用时禁用此选项。
**重要**
启用后，调试日志记录会向 Amazon S3 存储桶中写入比标准关联执行日志记录更多的数据。这可能会导致性能变慢，并且 Amazon S3 的存储费用可能会变高。要缓解存储大小问题，建议在 Amazon S3 存储桶中启用生命周期策略。有关更多信息，请参阅 [Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-lifecycle.html)中的*如何为 S3 Bucket 创建生命周期策略？*。
1. **Compliance Type (合规性类型)**：（可选）指定要在报告合规性信息时使用的合规性类型。默认的合规性类型为 **Custom:DSC (自定义:DSC)**。如果创建多个运行 MOF 文件的关联，请确保为每个关联指定不同的合规性类型。否则，使用 **Custom:DSC** 的每个其他关联都将覆盖现有的合规性数据。
1. **Pre Reboot Script (重启前脚本)**：（可选）指定在配置指示需要重启时要运行的脚本。该脚本将在重启之前运行。该脚本必须为单行。使用分号分隔其他行。
1. 在 **Targets (目标)** 部分中，选择 **Specifying tags (指定标签)** 或 **Manually Selecting Instance (手动选择实例)**。如果选择使用标签将资源设置为目标，请在提供的字段中输入标签键和标签值。有关使用目标的更多信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
1. 在 **Specify schedule (指定计划)** 部分中，选择 **On Schedule (按计划)** 或 **No schedule (无计划)**。如果选择 **On Schedule (按计划)**，则可使用提供的按钮为关联创建 cron 或 rate 计划。
1. 在 **Advanced options (高级选项)** 部分中：
+ 在 **Compliance severity (合规性严重级别)** 中，选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅 [关于 State Manager 关联合规性](compliance-about.md#compliance-about-association)。
1. 在 **Rate control**（速率控制）部分，配置用于跨托管式节点机群运行 State Manager 关联的选项。有关这些选项的详细信息，请参阅[了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
在**并发**部分中，选择一个选项：
+ 选择 **targets (目标)** 输入可同时运行关联的目标的绝对数量。
+ 选择 **percentage (百分比)** 输入可同时运行关联的目标集的百分比。
在**错误阈值**部分中，选择一个选项：
+ 选择 **errors (错误)** 以输入 State Manager 停止对其他目标运行关联之前允许的错误的绝对数量。
+ 选择 **percentage (百分比)** 以输入 State Manager 停止对其他目标运行关联之前允许的错误的百分比。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 选择**创建关联**。
State Manager 在指定的节点或目标中创建并立即运行关联。在初始执行后，关联根据定义的计划和以下规则按间隔运行：
+ State Manager 对间隔开启时处于线上状态的节点运行关联，并跳过离线节点。
+ State Manager 在间隔期间会尝试对所有已配置的节点运行关联。
+ 如果在某个周期内未运行某一关联（例如，由于并发值限制了可以同时处理关联的节点数），State Manager 将尝试在下一个周期运行该关联。
+ State Manager 会记录所有已跳过间隔的历史记录。可在 **Execution History (执行历史记录)** 选项卡上查看历史记录。
**注意**
`AWS-ApplyDSCMofs` 是 Systems Manager 命令文档 这意味着，您也可以使用 Run Command（AWS Systems Manager 中的一项工具）运行此文档。有关更多信息，请参阅 [AWS Systems Manager Run Command](run-command.md)。
## 排查创建运行 MOF 文件的关联时出现的问题
本部分包含的信息可帮助您解决在创建运行 MOF 文件的关联时遇到的问题。
**启用增强的日志记录**
解决问题的第一步是启用增强型日志记录。具体来说，是执行以下操作：
1. 验证关联是否配置是将命令输出写入 Amazon S3 或 Amazon CloudWatch Logs (CloudWatch)。
1. 将 **Enable Verbose Logging (启用详细日志记录)** 参数设置为 True。
1. 将 **Enable Debug Logging (启用调试日志记录)** 参数设置为 True。
启用详细和调试日志记录后，**Stdout** 输出文件将包含有关脚本执行的详细信息。此输出文件可帮助您确定脚本失败的位置。**Stderr** 输出文件包含在脚本执行期间发生的错误。
**创建运行 MOF 文件的关联时的常见问题**
本节包含有关在创建运行 MOF 文件的关联时出现的常见问题的信息以及解决这些问题的步骤。
**我的 MOF 未应用**
如果 State Manager 未能将关联应用到您的节点，请首先查看 **Stderr** 输出文件。此文件可以帮助您了解问题的根本原因。另外，请确认：
+ 此节点具有与 MOF 相关的所有 Simple Storage Service (Amazon S3) 存储桶所需访问权限。具体来说：
+ **s3:GetObject permissions (s3:GetObject 权限)**：这是私有 Amazon S3 存储桶中的 MOF 文件和 Amazon S3 存储桶中的自定义模块必需的权限。
+ **s3:PutObject permission (s3:PutObject 权限)**：在将合规性报告和合规性状态写入 Amazon S3 存储桶时需要此权限。
+ 如果使用标签，则需确保该节点具有所需的 IAM policy。使用标签需要实例 IAM 角色具有允许 `ec2:DescribeInstances` 和 `ssm:ListTagsForResource` 操作的策略。
+ 确保该节点已分配预期的标签或 SSM 参数。
+ 请确保标签或 SSM 参数不包含拼写错误。
+ 尝试对节点本地应用 MOF，以确保 MOF 文件本身没有问题。
**我的 MOF 似乎失败了，但 Systems Manager 执行成功**
如果 `AWS-ApplyDSCMofs` 文档成功运行，则 Systems Manager 执行状态将显示 **Success (成功)**。此状态并不反映节点针对 MOF 文件中的配置要求的合规性状态。要查看节点的合规性状态，请查看合规性报告。您可以查看 Amazon S3 报告存储桶中的 JSON 报告。这适用于 Run Command 和 State Manager 执行。此外，对于State Manager ，您可以在 Systems Manager 合规性页面上查看合规性详细信息。
**Stderr 状态：尝试访问服务时名称解析失败**
此错误指示脚本无法访问远程服务。最有可能的情况是，该脚本无法访问 Amazon S3 。当脚本尝试将合规性报告或合规性状态写入文档参数中提供的 Amazon S3 存储桶时，通常会发生此问题。通常，当计算环境使用包含允许清单的防火墙或透明代理时，会出现此错误。要解决此问题，请执行以下操作：
+ 将特定于区域的存储桶语法用于所有 Amazon S3 存储桶参数。例如，**Mofs to Apply (要应用的 Mof)** 参数的格式应如下所示：
s3:*bucket-region*:*amzn-s3-demo-bucket*:*mof-file-name*.mof。
示例如下：` s3:us-west-2:amzn-s3-demo-bucket:my-mof.mof`
报告、状态和模块源存储桶名称的格式应如下所示：
*bucket-region*:*amzn-s3-demo-bucket*。下面是一个示例：`us-west-1:amzn-s3-demo-bucket;`
+ 如果特定于区域的语法无法解决此问题，请确保目标节点可以访问所需区域中的 Simple Storage Service (Amazon S3)。对此进行确认：
1. 在相应的 Amazon S3 区域中查找 Amazon S3 的端点名称。有关更多信息，请参阅《Amazon Web Services 一般参考》**中的 [Amazon S3 Service Endpoints](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。
1. 登录目标节点并运行以下 ping 命令。
```
ping s3.s3-region.amazonaws.com
```
如果 ping 命令失败，则意味着 Simple Storage Service (Amazon S3) 已关闭或防火墙/透明代理阻止访问 Simple Storage Service (Amazon S3) 区域，或节点无法访问 Internet。
## 查看 DSC 资源合规性详细信息
在运行 `AWS-ApplyDSCMofs` 文档时指定的 Amazon S3 **状态存储桶**中 Systems Manager 捕获有关 DSC 资源失败的合规性信息。在 Amazon S3 存储桶中搜索有关 DSC 资源失败的信息可能需要很长时间。相反，您可以在 Systems Manager **Compliance (合规性)** 页面上查看该信息。
**合规性资源摘要**部分显示失败的资源数。在以下示例中，**ComplianceType** 是 **Custom:DSC**，并且一个资源不合规。
**注意**
Custom:DSC 是 `AWS-ApplyDSCMofs` 文档中的默认 **ComplianceType** 值。该值是可自定义的。
![\[查看合规性页面的合规性资源摘要部分中的计数。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-mof-detailed-status-3.png)
**Details overview for resources (资源的详细概述)** 部分显示有关具有不合规 DSC 资源的 AWS 资源的信息。该部分还包括 MOF 名称、脚本执行步骤以及用于查看详细状态信息的**查看输出**链接（如果适用）。
![\[查看 MOF 执行资源失败的合规性详细信息\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-mof-detailed-status-1.png)
**查看输出**链接显示详细状态的最后 4,000 个字符。Systems Manager 将异常作为第一个元素，然后将扫描详细消息，并在前面添加尽可能多的内容，直至达到 4,000 个字符的配额。该过程显示在引发异常之前输出的日志消息，这些消息是用于故障排除的最相关消息。
![\[查看 MOF 资源合规性问题的详细输出\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-mof-detailed-status-2.png)
有关如何查看合规性信息的信息，请参阅 [AWS Systems Manager Compliance](systems-manager-compliance.md)。
**影响合规性报告的情况**
如果 State Manager 关联失败，则不会报告合规性数据。更具体地说，如果 MOF 无法处理，则 Systems Manager 不会报告任何合规性项目，因为关联失败。例如，如果 Systems Manager 尝试从节点没有权限访问的 Simple Storage Service (Amazon S3) 存储桶中下载 MOF，则关联失败，并且不会报告合规性数据。
如果第二个 MOF 中的资源失败， Systems Manager 将*不会*报告合规性数据。例如，如果 MOF 尝试在不存在的驱动器上创建一个文件，Systems Manager 将报告合规性，因为 `AWS-ApplyDSCMofs` 文档可以完全处理，这意味着关联成功运行。
# 创建运行 Ansible Playbook 的关联
您可以使用 `AWS-ApplyAnsiblePlaybooks` SSM 文档创建运行 Ansible Playbook 的State Manager关联。State Manager是 AWS Systems Manager 中的一项工具。本文档为运行 Playbook 提供了以下好处：
+ 支持运行复杂的 Playbook
+ 支持从 GitHub 和 Amazon Simple Storage Service（Amazon S3）下载 Playbook
+ 支持压缩的 PlayBook 结构
+ 增强的日志记录
+ 捆绑 Playbook 时可以指定要运行的 Playbook
**注意**
Systems Manager 包括两个 SSM 文档，使您能够创建运行 Ansible Playbook 的 State Manager 关联：`AWS-RunAnsiblePlaybook` 和 `AWS-ApplyAnsiblePlaybooks`。`AWS-RunAnsiblePlaybook` 文档已被弃用。它在 Systems Manager 中仍然提供，用于传统用途。由于此处介绍的增强功能，我们建议您使用 `AWS-ApplyAnsiblePlaybooks` 文档。
运行 Ansible Playbook 的关联在 macOS 中不受支持。
**支持运行复杂的 Playbook**
`AWS-ApplyAnsiblePlaybooks` 文档支持捆绑的复杂 Playbook，因为它会在执行指定的主 Playbook 之前将整个文件结构复制到本地目录中。您可以在 Zip 文件或目录结构中提供源 Playbook。Zip 文件或目录可以存储在 GitHub 或 Amazon S3 中。
**支持从 GitHub 下载 Playbook**
`AWS-ApplyAnsiblePlaybooks` 文档使用 `aws:downloadContent` 插件下载 Playbook 文件。文件可以存储在 GitHub 中的单个文件中，也可以存储为一组组合 Playbook 文件。要从 GitHub 下载内容，请以 JSON 格式指定有关 GitHub 存储库的信息。见下列。
```
{
"owner":"TestUser",
"repository":"GitHubTest",
"path":"scripts/python/test-script",
"getOptions":"branch:master",
"tokenInfo":"{{ssm-secure:secure-string-token}}"
}
```
**支持从 Amazon S3** 下载 Playbook
您还可以将 Ansible Playbook 作为单个 .zip 文件或目录结构存储和下载到 Amazon S3 中。要从 Amazon S3 下载内容，您必须指定该文件的路径。以下是两个示例。
**示例 1：下载特定 Playbook 文件**
```
{
"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml"
}
```
**示例 2：下载目录的内容**
```
{
"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/ansible/webservers/"
}
```
**重要**
如果指定 Amazon S3，托管式节点上的 AWS Identity and Access Management（IAM）实例配置文件必须包含 S3 存储桶的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
**支持压缩的 PlayBook 结构**
`AWS-ApplyAnsiblePlaybooks` 文档使您可以在下载的捆绑包中运行压缩的 .zip 文件。该文档检查下载的文件是否包含 .zip 格式的压缩文件。如果找到 .zip 文件，则文档将自动解压缩文件，然后运行指定的 Ansible 自动化。
**增强的日志记录**
`AWS-ApplyAnsiblePlaybooks` 文档包括一个可选参数，用于指定不同级别的日志记录。指定 -v 来表示低详细程度，-vv 或 –vvv 表示中等详细程度，-vvvv 表示调试级别日志记录。这些选项直接映射到 Ansible 详细程度选项。
**捆绑 Playbook 时可以指定要运行的 Playbook**
`AWS-ApplyAnsiblePlaybooks` 文档包含一个必需参数，用于指定捆绑多个 PlayBook 时要运行哪个 PlayBook。此选项为运行 PlayBook 提供了灵活性，以支持不同的使用案例。
## 了解安装的依赖项
如果您为 **InstallDependencies** 参数指定为 **True**，则 Systems Manager 会验证您的节点上是否安装了以下依赖项。
+ **Ubuntu Server/Debian Server**：Apt-get（程序包管理）、Python 3、Ansible、Unzip
+ **Amazon Linux** 支持的版本：Ansible
+ **RHEL**：Python 3、Ansible、Unzip
如果找不到这些依赖项中的一个或多个，则 Systems Manager 将自动安装它们。
## 创建运行 Ansible Playbook 的关联（控制台）
以下过程介绍了如何使用 Systems Manager 控制台创建 State Manager 关联，以便使用 `AWS-ApplyAnsiblePlaybooks` 文档运行 Ansible Playbook。
**创建运行 Ansible Playbook 的关联（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择** Create Association**，然后选择 **State Manager**。
1. 对于 **Name （名称）**，请指定一个名称，该名称可帮助您记住关联的用途。
1. 在 **Document (文档)** 列表中，选择 **`AWS-ApplyAnsiblePlaybooks`**。
1. 在 **Parameters (参数)** 部分中，对于 **Source Type (源类型)**，选择 **GitHub** 或 **S3**。
**GitHub**
如果选择 **GitHub**，则采用以下格式输入存储库信息。
```
{
"owner":"user_name",
"repository":"name",
"path":"path_to_directory_or_playbook_to_download",
"getOptions":"branch:branch_name",
"tokenInfo":"{{(Optional)_token_information}}"
}
```
**S3**
如果选择 **S3**，则采用以下格式输入路径信息：
```
{
"path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download"
}
```
1. 对于 **Install Dependencies (安装依赖项)**，请选择一个选项。
1. （可选）对于 **Playbook File (PlayBook 文件)**，输入文件名。如果 Zip 文件包含 Playbook，则必须指定 Zip 文件的相对路径。
1. （可选）对于**额外变量**，请输入希望 State Manager 在运行时发送到 Ansible 的变量。
1. （可选）对于 **Check (检查)**，选择一个选项。
1. （可选）对于 **Verbose (详细)**，选择一个选项。
1. 对于 **Targets (目标)**，选择一个选项。有关使用目标的信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
1. 在 **Specify schedule (指定计划)** 部分中，选择 **On schedule (按计划)** 或 **No schedule (无计划)**。如果选择 **On schedule (按计划)**，则可使用提供的按钮为关联创建 cron 或 rate 计划。
1. 在 **高级选项** 部分中，对于**合规性严重级别**，选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅 [关于 State Manager 关联合规性](compliance-about.md#compliance-about-association)。
1. 在 **Rate control**（速率控制）部分，配置用于在托管式节点机群中运行 State Manager 关联的选项。有关使用速率控制的信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
在**并发**部分中，选择一个选项：
+ 选择 **targets (目标)** 输入可同时运行关联的目标的绝对数量。
+ 选择 **percentage (百分比)** 输入可同时运行关联的目标集的百分比。
在**错误阈值**部分中，选择一个选项：
+ 选择 **errors (错误)** 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
+ 选择 **percentage (百分比)** 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 选择**创建关联**。
**注意**
如果使用标签在一个或多个目标节点上创建关联，然后从某一节点中删除标签，则该节点将不再运行该关联。该节点不再与 State Manager 文档关联。
## 创建运行 Ansible Playbook 的关联（CLI）
以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）创建 State Manager 关联，以便使用 `AWS-ApplyAnsiblePlaybooks` 文档运行 Ansible Playbook。
**创建运行 Ansible Playbook 的关联（CLI）**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令之一来创建运行 Ansible Playbook 的关联，该关联使用标签将节点设为目标。将每个*示例资源占位符*替换为您自己的信息。命令（A）指定 GitHub 作为源类型。命令 (B) 指定 Amazon S3 作为源类型。
**(A) GitHub 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"],"TimeoutSeconds":["3600"]}' \
--association-name "name" \
--schedule-expression "cron_or_rate_expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"], "TimeoutSeconds":["3600"]}' ^
--association-name "name" ^
--schedule-expression "cron_or_rate_expression"
```
------
见下列。
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets "Key=tag:OS,Values=Linux" \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
**(B) S3 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \
--association-name "name" \
--schedule-expression "cron_or_rate_expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^
--association-name "name" ^
--schedule-expression "cron_or_rate_expression"
```
------
见下列。
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets "Key=tag:OS,Values=Linux" \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
**注意**
State Manager 关联不支持所有的 cron 和 rate 表达式。有关为关联创建 cron 和 rate 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
系统将尝试在节点上创建关联并立即应用状态。
1. 运行以下命令查看您刚才创建的关联的更新状态。
```
aws ssm describe-association --association-id "ID"
```
# 创建运行 Chef 配方的关联
使用 `AWS-ApplyChefRecipes` SSM 文档创建运行 Chef 配方的State Manager关联。State Manager是 AWS Systems Manager 中的一项工具。可以使用 `AWS-ApplyChefRecipes` SSM 文档定位基于 Linux 的 Systems Manager 托管式节点。本文档为运行 Chef 配方提供了以下好处：
+ 支持多个版本的 Chef（Chef 11 到 Chef 18）。
+ 在目标节点上自动安装 Chef 客户端软件。
+ （可选）在目标节点上运行 [Systems Manager 合规性检查](systems-manager-compliance.md)，并将合规性检查的结果存储在 Amazon Simple Storage Service (Amazon S3) 存储桶中。
+ 在文档的单次运行中运行多个说明书和配方。
+ （可选）在 `why-run` 模式下运行配方，以显示哪些配方会在未进行更改的情况下在目标节点上发生更改。
+ （可选）将自定义 JSON 属性应用于 `chef-client` 运行。
+ （可选）应用存储在指定位置源文件中的自定义 JSON 属性。
您可以使用 [Git](#state-manager-chef-git)、[GitHub](#state-manager-chef-github)、[HTTP](#state-manager-chef-http) 或 [Amazon S3](#state-manager-chef-s3) 存储桶作为您在 `AWS-ApplyChefRecipes` 文档中指定的 Chef 说明书和配方的下载源。
**注意**
运行 Chef 配方的关联在 macOS 上不受支持。
## 开始使用
在创建 `AWS-ApplyChefRecipes` 文档之前，请准备好 Chef 说明书和说明书存储库。如果尚未获得要使用的 Chef 说明书，则可以从使用 AWS 为您准备的测试 `HelloWorld` 说明书开始。默认情况下，`AWS-ApplyChefRecipes` 文档已指向此说明书。您的说明书的设置应类似于以下目录结构。在以下示例中，`jenkins` 和 `nginx` 是 Chef 网站上的 [https://supermarket.chef.io/](https://supermarket.chef.io/) 中提供的 Chef 说明书的示例。
虽然 AWS 无法正式支持 [https://supermarket.chef.io/](https://supermarket.chef.io/) 网站上的说明书，但其中的许多说明书将与 `AWS-ApplyChefRecipes` 文档结合使用。以下是在测试社群说明书时需要确认的标准示例：
+ 说明书应支持您的目标 Systems Manager 托管式节点的基于 Linux 的操作系统。
+ 说明书将适用于您使用的 Chef 客户端版本（Chef 11 到 Chef 18）。
+ 说明书与 Chef Infra Client 兼容，并且不需要 Chef 服务器。
验证您是否能访问 `Chef.io` 网站，以便在运行列表中指定的任何说明书都能在 Systems Manager 文档（SSM 文档）运行时安装。支持使用嵌套的 `cookbooks` 文件夹，但这不是必需的；您可以将说明书直接存储在根级别下。
```
└── cookbooks (optional level)
├── jenkins
│ ├── metadata.rb
│ └── recipes
└── nginx
├── metadata.rb
└── recipes
```
**重要**
在创建运行 Chef 配方的 State Manager 关联之前需注意，文档运行时会在 Systems Manager 托管式节点上安装 Chef 客户端软件，除非将 **Chef 客户端版本**的值设置为 `None`。此操作使用 Chef 中的安装脚本代表您安装 Chef 组件。在运行 `AWS-ApplyChefRecipes` 文档之前，请确保您的企业能够遵守任何适用的法律要求，包括适用于对 Chef 软件的使用的许可条款。有关更多信息，请参阅 [Chef 网站](https://www.chef.io/)。
Systems Manager 可以向 S3 存储桶、Systems Manager 控制台发送合规性报告，或者提供合规性结果以响应 Systems Manager API 命令。要运行 Systems Manager 合规性报告，附上 Systems Manager 托管式节点的实例配置文件必须具有写入到 S3 存储桶的权限。该实例配置文件必须有权使用 Systems Manager `PutComplianceItem` API。有关 Systems Manager 合规性的更多信息，请参阅 [AWS Systems Manager Compliance](systems-manager-compliance.md)。
### 记录文档运行
当您通过使用 State Manager 关联运行 Systems Manager 文档（SSM 文档）时，您可以配置关联以选择文档运行的输出，并且可以将输出发送到 Amazon S3 或 Amazon CloudWatch Logs（CloudWatch Logs）。要帮助在关联运行完后轻松进行故障排除，请验证是否已将关联配置为将命令输出写入 Amazon S3 存储桶或 CloudWatch Logs 。有关更多信息，请参阅 [在 Systems Manager 中使用关联。](state-manager-associations.md)。
## 运行配方时向目标应用 JSON 属性
您可以为 Chef 客户端指定 JSON 属性，以便在关联运行期间应用于目标节点。设置关联时，您可以提供原始 JSON，也可以提供存储在 Amazon S3 中的 JSON 文件路径。
如果您想自定义配方的运行方式而无需修改配方本身，请使用 JSON 属性，例如：
+ **覆盖少量属性**
使用自定义 JSON 可以避免维护一个配方的多个版本，以适应细微差异。
+ **提供变量值**
使用自定义 JSON 指定可能随运行而变化的值。例如，如果您的 Chef 说明书配置了接受付款的第三方应用程序，则可以使用自定义 JSON 指定付款端点 URL。
**在原始 JSON 中指定属性**
以下是可用于为 Chef 配方指定自定义 JSON 属性的格式示例。
```
{"filepath":"/tmp/example.txt", "content":"Hello, World!"}
```
**指定 JSON 文件的路径**
以下是可用于为 Chef 配方指定自定义 JSON 属性路径的格式示例。
```
{"sourceType":"s3", "sourceInfo":"someS3URL1"}, {"sourceType":"s3", "sourceInfo":"someS3URL2"}
```
## 使用 Git 作为说明书源
`AWS-ApplyChefRecipes` 文档使用 [aws:downloadContent](documents-command-ssm-plugin-reference.md#aws-downloadContent) 插件下载 Chef 说明书。要从 Git 下载内容，请以 JSON 格式指定有关 Git 存储库的信息，如下例所示。将每个 *example-resource-placeholder* 替换为您自己的信息。
```
{
"repository":"GitCookbookRepository",
"privateSSHKey":"{{ssm-secure:ssh-key-secure-string-parameter}}",
"skipHostKeyChecking":"false",
"getOptions":"branch:refs/head/main",
"username":"{{ssm-secure:username-secure-string-parameter}}",
"password":"{{ssm-secure:password-secure-string-parameter}}"
}
```
## 使用 GitHub 作为说明书源
`AWS-ApplyChefRecipes` 文档使用 [aws:downloadContent](documents-command-ssm-plugin-reference.md#aws-downloadContent) 插件下载说明书。要从 GitHub 下载内容，请以 JSON 格式指定有关 GitHub 存储库的信息，如下例所示。将每个 *example-resource-placeholder* 替换为您自己的信息。
```
{
"owner":"TestUser",
"repository":"GitHubCookbookRepository",
"path":"cookbooks/HelloWorld",
"getOptions":"branch:refs/head/main",
"tokenInfo":"{{ssm-secure:token-secure-string-parameter}}"
}
```
## 使用 HTTP 作为说明书源
您可以在自定义 HTTP 位置将 Chef 说明书存储为单个 `.zip` 或 `tar.gz` 文件，也可以存储为目录结构。要从 HTTP 下载内容，请以 JSON 格式指定文件或目录的路径，如下例所示。将每个 *example-resource-placeholder* 替换为您自己的信息。
```
{
"url":"https://my.website.com/chef-cookbooks/HelloWorld.zip",
"allowInsecureDownload":"false",
"authMethod":"Basic",
"username":"{{ssm-secure:username-secure-string-parameter}}",
"password":"{{ssm-secure:password-secure-string-parameter}}"
}
```
## 使用 Amazon S3 作为说明书源
您还可以将 Chef 说明书作为单个 `.zip` 或 `tar.gz` 文件或者目录结构存储和下载到 Amazon S3 中。要从 Amazon S3 下载内容，请以 JSON 格式指定文件的路径，如下例所示。将每个 *example-resource-placeholder* 替换为您自己的信息。
**示例 1：下载特定说明书**
```
{
"path":"https://s3.amazonaws.com/chef-cookbooks/HelloWorld.zip"
}
```
**示例 2：下载目录的内容**
```
{
"path":"https://s3.amazonaws.com/chef-cookbooks-test/HelloWorld"
}
```
**重要**
如果您指定 Simple Storage Service (Amazon S3)，则必须使用 `AmazonS3ReadOnlyAccess` 策略配置托管式节点上的 AWS Identity and Access Management (IAM) 实例配置文件。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
## 创建运行 Chef 配方的关联（控制台）
以下过程介绍了如何使用 Systems Manager 控制台创建 State Manager 关联，以便使用 `AWS-ApplyChefRecipes` 文档运行 Chef 说明书。
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择 **State Manager**，然后选择** Create Association**。
1. 对于 **Name (名称)**，请输入一个名称，该名称可帮助您记住关联的用途。
1. 在 **Document (文档)** 列表中，选择 **`AWS-ApplyChefRecipes`**。
1. 在**参数**中，对于**源类型**，选择 **Git**、**GitHub**、**HTTP** 或 **S3**。
1. 对于**源信息**，请使用您在步骤 6 中选择的**源类型**的适当格式输入说明书源信息。有关更多信息，请参阅以下主题：
+ [使用 Git 作为说明书源](#state-manager-chef-git)
+ [使用 GitHub 作为说明书源](#state-manager-chef-github)
+ [使用 HTTP 作为说明书源](#state-manager-chef-http)
+ [使用 Amazon S3 作为说明书源](#state-manager-chef-s3)
1. 在 **Run list (运行列表)** 中，按以下格式列出要运行的配方，并用逗号将每个配方分隔开，如下所示。请不要在逗号后面包含空格。将每个 *example-resource-placeholder* 替换为您自己的信息。
```
recipe[cookbook-name1::recipe-name],recipe[cookbook-name2::recipe-name]
```
1. （可选）指定希望 Chef 客户端传递给目标节点的自定义 JSON 属性。
1. 在 **JSON 属性内容**中，添加希望 Chef 客户端传递给目标节点的任何属性。
1. 在 **JSON 属性来源**中，将路径添加到希望 Chef 客户端传递给目标节点的任何属性中。
有关更多信息，请参阅 [运行配方时向目标应用 JSON 属性](#apply-custom-json-attributes)。
1. 对于 **Chef 客户端版本**，请指定 Chef 版本。有效值为 `11` 到 `18` 或 `None`。如果您指定 `11` 到 `18` 之间的一个数字（包含这两个数字），则 Systems Manager 会在目标节点上安装正确的 Chef 客户端版本。如果您指定 `None`，则在运行文档的配方之前，Systems Manager 不会在目标节点上安装 Chef 客户端。
1. （可选）对于 **Chef 客户端参数**，请指定您正在使用的 Chef 版本所支持的其他参数。要了解有关支持的参数的更多信息，请在运行 Chef 客户端的节点上运行 `chef-client -h`。
1. （可选）启用 **Why-run** 以显示在配方运行时对目标节点进行的更改，这不会实际更改目标节点。
1. 对于 **Compliance severity (合规性严重性)**，请选择要报告的 Systems Manager 合规性结果的严重性。合规性报告指示关联状态是合规还是不合规以及您在指定的严重级别。将合规性报告存储在一个 S3 存储桶中，您已将该存储桶指定为 **Compliance report bucket (合规性报告存储桶)** 参数的值（步骤 14）。有关合规性的更多信息，请参阅本指南中的 [了解有关合规性的详细信息](compliance-about.md)。
合规性扫描测量 Chef 配方和节点资源中指定的配置之间的偏离。有效值为 `Critical`、`High`、`Medium`、`Low`、`Informational`、`Unspecified` 或 `None`。要跳过合规性报告，请选择 `None`。
1. 对于 **Compliance type (合规性类型)**，请指定要报告其结果的合规性类型。有效值为 `Association`（对于 State Manager 关联）或 `Custom:` *自定义类型*。默认值为 `Custom:Chef`。
1. 对于**合规性报告存储桶**，输入 S3 存储桶的名称，该存储桶用于存储此文档执行的每个 Chef 运行的相关信息，包括资源配置和合规性结果。
1. 在 **Rate control**（速率控制）中，配置用于在托管式节点机群中运行 State Manager 关联的选项。有关使用速率控制的信息，请参阅 [了解 State Manager 关联中的目标和速率控制](systems-manager-state-manager-targets-and-rate-controls.md)。
在 **Concurrency (并发)** 中，选择一个选项：
+ 选择 **targets (目标)** 输入可同时运行关联的目标的绝对数量。
+ 选择 **percentage (百分比)** 输入可同时运行关联的目标集的百分比。
在 **Error threshold (错误阈值)** 中，选择一个选项：
+ 选择 **errors (错误)** 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
+ 选择 **percentage (百分比)** 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. 选择**创建关联**。
## 创建运行 Chef 配方的关联（CLI）
以下过程介绍了如何使用 AWS Command Line Interface (AWS CLI) 创建 State Manager 关联，以便使用 `AWS-ApplyChefRecipes` 文档运行 Chef 说明书。
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令之一来创建关联，该关联通过具有指定标签的目标节点来运行 Chef 说明书。使用适合您说明书源类型和操作系统的命令。将每个 *example-resource-placeholder* 替换为您自己的信息。
1. **Git 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
--association-name "name" \
--schedule-expression "cron-or-rate-expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["Git"],"SourceInfo":["{\"repository\":\"repository-name\", \"getOptions\": \"branch:branch-name\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' ^
--association-name "name" ^
--schedule-expression "cron-or-rate-expression"
```
------
1. **GitHub 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner-name\", \"repository\": \"name\", \"path\": \"path-to-directory-or-cookbook-to-download\", \"getOptions\": \"branch:branch-name\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
--association-name "name" \
--schedule-expression "cron-or-rate-expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner-name\", \"repository\": \"name\", \"path\": \"path-to-directory-or-cookbook-to-download\", \"getOptions\": \"branch:branch-name\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json}"], "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' ^
--association-name "name" ^
--schedule-expression "cron-or-rate-expression"
```
------
见下列。
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets Key=tag:OS,Values=Linux \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ChefRecipeTest\", \"repository\": \"ChefCookbooks\", \"path\": \"cookbooks/HelloWorld\", \"getOptions\": \"branch:master\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' \
--association-name "MyChefAssociation" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets Key=tag:OS,Values=Linux ^
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ChefRecipeTest\", \"repository\": \"ChefCookbooks\", \"path\": \"cookbooks/HelloWorld\", \"getOptions\": \"branch:master\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' ^
--association-name "MyChefAssociation" ^
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
1. **HTTP 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
--association-name "name" \
--schedule-expression "cron-or-rate-expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["HTTP"],"SourceInfo":["{\"url\":\"url-to-zip-file|directory|cookbook\", \"authMethod\": \"auth-method\", \"username\": \"{{ ssm-secure:username-secure-string-parameter }}\", \"password\": \"{{ ssm-secure:password-secure-string-parameter }}\"}"], "RunList":["{\"recipe[cookbook-name-1::recipe-name]\", \"recipe[cookbook-name-2::recipe-name]\"}"], "JsonAttributesContent": ["{custom-json-content}"], "JsonAttributesSources": "{\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-1\"}, {\"sourceType\":\"s3\", \"sourceInfo\":\"s3-bucket-endpoint-2\"}", "ChefClientVersion": ["version-number"], "ChefClientArguments":["{chef-client-arguments}"], "WhyRun": boolean, "ComplianceSeverity": ["severity-value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["s3-bucket-name"]}' \
--association-name "name" ^
--schedule-expression "cron-or-rate-expression"
```
------
1. **Amazon S3 源**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_cookbook_to_download\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["amzn-s3-demo-bucket"]}' \
--association-name "name" \
--schedule-expression "cron_or_rate_expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_cookbook_to_download\"}"], "RunList":["{\"recipe[cookbook_name1::recipe_name]\", \"recipe[cookbook_name2::recipe_name]\"}"], "JsonAttributesContent": ["{Custom_JSON}"], "ChefClientVersion": ["version_number"], "ChefClientArguments":["{chef_client_arguments}"], "WhyRun": true_or_false, "ComplianceSeverity": ["severity_value"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["amzn-s3-demo-bucket"]}' ^
--association-name "name" ^
--schedule-expression "cron_or_rate_expression"
```
------
见下列。
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" \
--targets "Key=tag:OS,Values= Linux" \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-bucket/HelloWorld\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' \
--association-name "name" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyChefRecipes" ^
--targets "Key=tag:OS,Values= Linux" ^
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-bucket/HelloWorld\"}"], "RunList":["{\"recipe[HelloWorld::HelloWorldRecipe]\", \"recipe[HelloWorld::InstallApp]\"}"], "JsonAttributesContent": ["{\"state\": \"visible\",\"colors\": {\"foreground\": \"light-blue\",\"background\": \"dark-gray\"}}"], "ChefClientVersion": ["14"], "ChefClientArguments":["{--fips}"], "WhyRun": false, "ComplianceSeverity": ["Medium"], "ComplianceType": ["Custom:Chef"], "ComplianceReportBucket": ["ChefComplianceResultsBucket"]}' ^
--association-name "name" ^
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
系统将创建关联，除非指定的 cron 或 rate 表达式阻止，否则系统将在目标节点上运行该关联。
**注意**
State Manager 关联不支持所有的 cron 和 rate 表达式。有关为关联创建 cron 和 rate 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
1. 运行以下命令，查看您刚才创建的关联的状态。
```
aws ssm describe-association --association-id "ID"
```
## 查看 Chef 资源合规性详细信息
Systems Manager 在运行 `AWS-ApplyChefRecipes` 文档时指定的 Amazon S3 **合规性报告存储桶**值中捕获有关 Chef 托管资源的合规性信息。在 S3 存储桶中搜索有关 Chef 资源失败的信息可能需要很长时间。相反，您可以在 Systems Manager **Compliance (合规性)** 页面上查看该信息。
Systems Manager 合规性扫描收集在最近一次 Chef 运行中创建或检查的托管式节点上的资源的相关信息。资源可以包括文件、目录、`systemd` 服务、`yum` 软件包、模板化文件、`gem` 软件包和依赖说明书等。
**合规性资源摘要**部分显示失败的资源数。在以下示例中，**ComplianceType** 是 **Custom:Chef**，并且一个资源不合规。
**注意**
`Custom:Chef` 是 `AWS-ApplyChefRecipes` 文档中的默认 **ComplianceType** 值。该值是可自定义的。
![\[查看计数合规性页面合规性资源摘要部分中的计数。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-chef-compliance-summary.png)
**Details overview for resources (资源的详细概述)**部分显示有关不合规的 AWS 资源的信息。此部分还包括对其运行合规性的 Chef 资源类型、问题的严重性、合规性状态以及指向更多信息的链接（如适用）。
![\[查看 Chef 托管资源失败的合规性详细信息\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/state-manager-chef-compliance-details.png)
**(View output) 查看输出** 显示详细状态的最后 4,000 个字符。Systems Manager 先将异常作为第一个元素，查找详细消息，并显示它们，直至达到 4000 个字符的配额。该过程显示在引发异常之前输出的日志消息，这些消息是用于故障排除的最相关消息。
有关如何查看合规性信息的信息，请参阅 [AWS Systems Manager Compliance](systems-manager-compliance.md)。
**重要**
如果 State Manager 关联失败，则不会报告合规性数据。例如，如果 Systems Manager 尝试从节点没有权限访问的 S3 存储桶中下载 Chef 说明书，则关联将失败，并且 Systems Manager 不会报告合规性数据。
# 演练：使用 AWS CLI 自动更新 SSM Agent
以下过程将指导您完成使用 AWS Command Line Interface 创建 State Manager 关联的过程。关联会根据您指定的计划自动更新 SSM Agent。有关 SSM Agent 的更多信息，请参阅 [使用 SSM Agent](ssm-agent.md)。若要使用控制台自定义 SSM Agent，请参阅 [自动更新 SSM Agent](ssm-agent-automatic-updates.md#ssm-agent-automatic-updates-console)。
要获得有关 SSM Agent 更新的通知，请在 GitHub 上订阅 [SSM Agent 发布说明](https://github.com/aws/amazon-ssm-agent/blob/master/RELEASENOTES.md)页面。
**开始前的准备工作**
在完成以下过程之前，请确认您至少有一个适用于 Linux、macOS ，或针对 Systems Manager 而配置的 Windows Server 的 Amazon Elastic Compute Cloud (Amazon EC2)实例正在运行。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
如果您使用 AWS CLI 或 AWS Tools for Windows PowerShell 创建关联，请使用 `--Targets` 参数将实例指定为目标，如以下示例所示。不要使用 `--InstanceID` 参数。`--InstanceID` 参数是一个旧参数。
**创建关联以实现 SSM Agent 的自动更新**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令，通过使用 Amazon Elastic Compute Cloud (Amazon EC2) 标签将实例设为目标来创建关联。将每个*示例资源占位符*替换为您自己的信息。`Schedule` 参数可以设置一个计划，以在每周日凌晨 2:00 (UTC) 运行 关联。
State Manager 关联不支持所有的 cron 和 rate 表达式。有关为关联创建 cron 和 rate 表达式的更多信息，请参阅 [参考：适用于 Systems Manager 的 Cron 和 Rate 表达式](reference-cron-and-rate-expressions.md)。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--targets Key=tag:tag_key,Values=tag_value \
--name AWS-UpdateSSMAgent \
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--targets Key=tag:tag_key,Values=tag_value ^
--name AWS-UpdateSSMAgent ^
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
您可以通过在以逗号分隔的列表中指定实例 ID 来将多个实例设为目标。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--targets Key=instanceids,Values=instance_ID,instance_ID,instance_ID \
--name AWS-UpdateSSMAgent \
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
#### [ Windows ]
```
aws ssm create-association ^
--targets Key=instanceids,Values=instance_ID,instance_ID,instance_ID ^
--name AWS-UpdateSSMAgent ^
--schedule-expression "cron(0 2 ? * SUN *)"
```
------
您可以指定要更新到的 SSM Agent 版本。
------
#### [ Linux & macOS ]
```
aws ssm create-association \
--targets Key=instanceids,Values=instance_ID,instance_ID,instance_ID \
--name AWS-UpdateSSMAgent \
--schedule-expression "cron(0 2 ? * SUN *)" \
--parameters version=ssm_agent_version_number
```
------
#### [ Windows ]
```
aws ssm create-association ^
--targets Key=instanceids,Values=instance_ID,instance_ID,instance_ID ^
--name AWS-UpdateSSMAgent ^
--schedule-expression "cron(0 2 ? * SUN *)" ^
--parameters version=ssm_agent_version_number
```
------
系统将返回类似于以下内容的信息。
```
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 2 ? * SUN *)",
"Name": "AWS-UpdateSSMAgent",
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"AssociationId": "123..............",
"DocumentVersion": "$DEFAULT",
"LastUpdateAssociationDate": 1504034257.98,
"Date": 1504034257.98,
"AssociationVersion": "1",
"Targets": [
{
"Values": [
"TagValue"
],
"Key": "tag:TagKey"
}
]
}
}
```
系统将尝试在实例上创建关联并在创建后应用状态。关联状态显示 `Pending`。
1. 运行以下命令查看您创建的关联的更新状态。
```
aws ssm list-associations
```
如果您的实例*没有*运行 SSM Agent 的最新版本，则状态将显示 `Failed`。发布 SSM Agent 的新版本时，关联将自动安装新代理，而且状态将显示 `Success`。
# 演练：在适用于 Windows Server 的 EC2 实例上自动更新半虚拟化驱动程序
Amazon Windows Server Amazon Machine Images（AMIs）包含一系列驱动程序，以允许访问虚拟化硬件。Amazon Elastic Compute Cloud (Amazon EC2) 使用这些驱动程序将实例存储和 Amazon Elastic Block Store (Amazon EBS) 卷映射到其设备。我们建议您安装最新的驱动程序来提高适用于 Windows Server 的 EC2 实例的稳定性和性能。有关半虚拟化驱动程序的更多信息，请参阅 [AWS 半虚拟化驱动程序](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/xen-drivers-overview.html#xen-driver-awspv)。
以下演练介绍如何配置State Manager关联，以便在驱动程序可用时自动下载和安装新的 AWS 半虚拟化驱动程序。State Manager是 AWS Systems Manager 中的一项工具。
**开始前的准备工作**
在完成以下过程之前，请确认您至少有一个适用于 Windows Server 的 Amazon EC2 实例（针对 Systems Manager 配置）正在运行。有关更多信息，请参阅 [为 AWS Systems Manager 设置托管节点](systems-manager-setting-up-nodes.md)。
**创建自动更新半虚拟化驱动程序的 State Manager 关联**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **State Manager**。
1. 选择 **Create association（创建关联）**。
1. 在**名称**字段中，输入关联的描述性名称。
1. 在 **Document (文档)** 列表中，选择 `AWS-ConfigureAWSPackage`。
1. 在**参数**区域中，执行以下操作：
+ 对于**操作**，选择**安装**。
+ 适用于**安装类型**中，选择**卸载并重新安装**。
**注意**
此程序包不支持就地升级。必须卸载程序包进行重新安装。
+ 对于**名称**，请输入 **AWSPVDriver**。
无需为**版本**和**其他参数**输入任何内容。
1. 在 **Targets**（目标）部分中，通过指定标签、手动选择实例或边缘设备或指定资源组，选择要在其上运行此操作的托管式节点。
**提示**
如果未列出您希望看到的托管式节点，请参阅 [排除托管式节点可用性的问题](fleet-manager-troubleshooting-managed-nodes.md) 以获取故障排除技巧。
**注意**
如果您选择使用标签将实例设为目标，并指定映射到 Linux 实例的标签，则关联在 Windows Server 实例上将成功，但在 Linux 实例上将失败。关联的总体状态将显示 **Failed**。
1. 在**指定计划**区域中，选择是按照配置的计划运行关联，还是只运行一次。更新的半虚拟化驱动程序每年发布若干次，因此如果需要，您可以计划每月运行一次关联。
1. 在**高级选项**中，为**合规性严重级别**选择关联的严重级别。合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅 [关于 State Manager 关联合规性](compliance-about.md#compliance-about-association)。
1. 对于 **Rate control（速率控制）**：
+ 对于 **Concurrency**（并发），请指定要同时运行该命令的托管式节点的数量或百分比。
**注意**
如果您通过指定应用于托管式节点的标签或指定 AWS Resource Groups 来选择目标，但不确定有多少个托管式节点已被设为目标，则可通过指定百分比来限制可同时运行该文档的目标的数量。
+ 对于 **Error threshold**（错误阈值），请指定当命令在一定数量或百分比的节点上失败后，何时在其他托管式节点上停止运行该命令。例如，如果您指定三个错误，Systems Manager 将在收到第四个错误时停止发送该命令。仍在处理该命令的托管式节点也可能发送错误。
1. （可选）对于 **Output options (输出选项)**，要将命令输出保存到文件，请选中 **Enable writing output to S3 (启用将输出写入 S3)** 方框。在方框中输入存储桶和前缀（文件夹）名称。
**注意**
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)或[为混合环境创建 IAM 服务角色](hybrid-multicloud-service-role.md)。此外，如果指定的 S3 存储桶位于不同的 AWS 账户 中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。
1. （可选）在 **CloudWatch 警报**部分中，为**警报名称**选择 CloudWatch 警报来应用到关联，以便进行监控。
**注意**
请注意与该步骤相关的以下信息。
警报列表最多显示 100 个警报。如果您未在列表中看到您的警报，请使用 AWS Command Line Interface 创建关联。有关更多信息，请参阅 [创建关联（命令行）](state-manager-associations-creating.md#create-state-manager-association-commandline)。
要将 CloudWatch 警报附加到命令，创建关联的 IAM 主体必须具有 `iam:createServiceLinkedRole` 操作的权限。有关 CloudWatch 警报的更多信息，请参阅[使用 Amazon CloudWatch 警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。
如果您的警报激活，任何待处理的命令调用或自动化都不会运行。
1. 选择 **Create Association**，然后选择 **Close**。系统将尝试在实例上创建关联并立即应用状态。
如果您在一个或多个适用于 Windows Server 的 Amazon EC2 实例上创建了关联，状态将更改为 **Success (成功)**。如果未为 Systems Manager 配置实例，或无意中将 Linux 实例设为了目标，则状态将显示 **Failed (失败)**。
如果状态为 **Failed (失败)**，则选择关联 ID，选择**资源**选项卡并验证关联是否已在适用于 Windows Server 的 EC2 实例上成功创建。如果适用于 Windows Server 的 EC2 实例显示 **Failed (失败)** 状态，请验证 SSM Agent 是否在该实例上运行，并验证该实例是否配置有适用于 Systems Manager 的 AWS Identity and Access Management (IAM) 角色。有关更多信息，请参阅 [为组织设置 Systems Manager 统一控制台](systems-manager-setting-up-organizations.md)。