这是新的《CloudFormation 模板参考指南》**。请更新您的书签和链接。有关开始使用 CloudFormation 的帮助，请参阅《AWS CloudFormation 用户指南》[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。

# cfn-hup
<a name="cfn-hup"></a>

`cfn-hup` 帮助程序作为一个进程守护程序，旨在检测资源元数据中出现的变更，并在检测到变更时运行用户指定的操作。通过此项操作，您可以通过 `UpdateStack` API 操作对您正在运行的 Amazon EC2 实例进行配置更新。

有关更多信息，请参阅《AWS CloudFormation 用户指南》**中的[更新 CloudFormation 堆栈](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/updating.stacks.walkthrough.html)教程。

**Topics**
+ [语法](#cfn-hup-Syntax)
+ [选项](#cfn-hup-options)
+ [cfn-hup.conf 配置文件](#cfn-hup-config-file)
+ [`hooks.conf` 配置文件](#cfn-hup-hook-file)
+ [`hooks.d` 目录](#cfn-hup-hooks-dir)
+ [示例](#cfn-hup-examples)
+ [相关资源](#cfn-hup-related-resources)

## 语法
<a name="cfn-hup-Syntax"></a>

```
cfn-hup --config|-c config.dir \
        --no-daemon \
        --verbose|-v
```

## 选项
<a name="cfn-hup-options"></a>


| 名称 | 描述 | 必填 | 
| --- | --- | --- | 
|   `--config\|-c config.dir`   |  指定 `cfn-hup` 脚本寻找 `cfn-hup.conf` 和 `hooks.d` 目录的路径。在 Windows 中，默认路径为 `system_drive\cfn`。在 Linux 中，默认路径为 `/etc/cfn`。  |  否  | 
|   `--no-daemon`   |  指定该选项可运行 `cfn-hup` 脚本一次，然后退出。  |  否  | 
|   `-v, --verbose `   |  指定该选项可使用详细模式。  |  否  | 

## cfn-hup.conf 配置文件
<a name="cfn-hup-config-file"></a>

`cfn-hup.conf` 文件存储堆栈的名称和 `cfn-hup` 进程守护程序的目标 AWS 凭证。

`cfn-hup.conf` 文件采用以下格式：

```
[main]
stack=<stack-name-or-id>
```


| 名称 | 描述 | 必填 | 
| --- | --- | --- | 
|   `stack`   |  堆栈名称或 ID。 *类型*：字符串  |  是  | 
|   `credential-file`   |  仅用户可用凭证文件，与用于命令行工具的格式相同。 *类型*：字符串 *条件*：`role` 参数替代该参数。  |  否  | 
|   `role`   |  与实例关联的 IAM 角色的名称。 *类型*：字符串  |  否  | 
|   `region`   |  包含堆栈的 AWS 区域的名称。 *示例*：us-east-2  |  否  | 
|   `umask`   |  `cfn-hup` 进程守护程序使用的 `umask`。 指定此值时可选择带或不带前导 0。在两种情况下，它都会被解释为八进制数（与 Linux `umask` 命令相似）。该参数在 Windows 中无效。 *类型*：介于 `0` 和 `0777` 之间的八进制整数 *默认值*：`022`，版本 1.4–22 及更高版本。`022` 的默认值会覆盖组和全球写权限，因此 `cfn-hup` 进程守护程序创建的文件在默认情况下不支持组和全球写入。版本 1.4-21 及更低版本的默认值为 `0`，不覆盖任何值。  |  否  | 
|   `interval`   |  用于检查资源元数据更改的时间间隔（以分钟为单位）。 *类型*：整数 *默认值*：`15`  |  否  | 
|   `verbose`   |  指定是否要使用详细日志记录。 *类型*：布尔值 *默认值*：`false`  |  否  | 

## `hooks.conf` 配置文件
<a name="cfn-hup-hook-file"></a>

`cfn-hup` 进程守护程序定期调用的用户操作已在 `hooks.conf` 配置文件中予以定义。`hooks.conf` 文件采用以下*格式*：

```
[hookname]
triggers=post.add or post.update or post.remove
path=Resources.<logicalResourceId> (.Metadata or .PhysicalResourceId)(.<optionalMetadatapath>)
action=<arbitrary shell command>
runas=<runas user>
```

操作运行时，它会在当前环境（`cfn-hup` 所在环境）的副本中运行，此时 `CFN_OLD_METADATA` 设定为由路径指定的元数据的先前值，且 `CFN_NEW_METADATA` 设定为当前值。

挂钩配置文件仅可通过 `cfn-hup` 进程守护程序启动加载，因此需要进程守护程序才能重新启动新的挂钩。以前元数据值的缓存存储在 `/var/lib/cfn-hup/data/metadata_db` – 您可以删除该缓存以强制 `cfn-hup` 再次运行所有 `post.add` 操作。


| 名称 | 描述 | 必填 | 
| --- | --- | --- | 
|   `hookname`   |  此挂钩的唯一名称。 *类型*：字符串  |  是  | 
|   `triggers`   |  待检测条件的逗号分隔列表。 *有效值*：`post.add`、`post.update` 或 `post.remove` *示例*：`post.add, post.update`  |  是  | 
|   `path`   |  元数据对象路径。支持元数据块中的随机深度路径。  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AWSCloudFormation/latest/TemplateReference/cfn-hup.html)  |  是  | 
|   `action`   |  按照既定运行的任意 Shell 程序命令。  |  是  | 
|   `runas`   |  运行命令的用户身份。`cfn-hup` 会使用 su 命令切换至该用户。  |  是  | 

## `hooks.d` 目录
<a name="cfn-hup-hooks-dir"></a>

要通过部署变更通知挂钩支持若干应用程序组合，`cfn-hup` 要支持位于挂钩配置目录中名为 `hooks.d` 的目录。您可以将一个或多个附加挂钩配置文件置于 `hooks.d` 目录之中。附加挂钩文件必须使用与 `hooks.conf` 文件相同的版式。

`cfn-hup` 进程守护程序将解析并加载此目录中的所有文件。如果 `hooks.d` 中的任何挂钩与 `hooks.conf` 中的挂钩同名，则这些挂钩将会合并（这表示，对于这两个文件都指定的数值，`hooks.d` 会覆盖 `hooks.conf`）。

## 示例
<a name="cfn-hup-examples"></a>

在以下示例中，在更改与 `LaunchConfig` 资源关联的 `AWS::CloudFormation::Init` 资源时，CloudFormation 触发 `cfn-auto-reloader.conf` 挂钩文件。

### JSON
<a name="cfn-hup-example.json"></a>

```
...
    "LaunchConfig": {
      "Type" : "AWS::AutoScaling::LaunchConfiguration",
      "Metadata" : {
        "AWS::CloudFormation::Init" : {
...
              "/etc/cfn/hooks.d/cfn-auto-reloader.conf": {
                "content": { "Fn::Join": [ "", [
                  "[cfn-auto-reloader-hook]\n",
                  "triggers=post.update\n",
                  "path=Resources.LaunchConfig.Metadata.AWS::CloudFormation::Init\n",
                  "action=/opt/aws/bin/cfn-init -v ",
                          "         --stack ", { "Ref" : "AWS::StackName" },
                          "         --resource LaunchConfig ",
                          "         --configsets wordpress_install ",
                          "         --region ", { "Ref" : "AWS::Region" }, "\n",
                  "runas=root\n"
                ]]},          
                "mode"  : "000400",
                "owner" : "root",
                "group" : "root"
              }
...
```

### YAML
<a name="cfn-hup-example.yaml"></a>

```
...
  LaunchConfig:
    Type: AWS::AutoScaling::LaunchConfiguration
    Metadata:
      AWS::CloudFormation::Init:
...
            /etc/cfn/hooks.d/cfn-auto-reloader.conf:
              content: !Sub |
                [cfn-auto-reloader-hook]
                triggers=post.update
                path=Resources.LaunchConfig.Metadata.AWS::CloudFormation::Init
                action=/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}
                runas=root
              mode: "000400"
              owner: "root"
              group: "root"
...
```

## 相关资源
<a name="cfn-hup-related-resources"></a>

您也可以访问我们的 GitHub 存储库下载使用 `cfn-hup` 的[示例模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html#sample-templates)，包括以下模板。
+  [InstanceWithCfnInit.yaml](https://github.com/aws-cloudformation/aws-cloudformation-templates/blob/main/EC2/InstanceWithCfnInit.yaml) 
+  [AutoScalingRollingUpdates.yaml](https://github.com/aws-cloudformation/aws-cloudformation-templates/blob/main/AutoScaling/AutoScalingRollingUpdates.yaml)