這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](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>

會在 `hooks.conf` 組態檔案中定義 `cfn-hup` 常駐程式定期呼叫的使用者動作。`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_tw/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)