This is the new *CloudFormation Template Reference Guide*. Please update your bookmarks and links. For help getting started with CloudFormation, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).
# cfn-hup
The `cfn-hup` helper is a daemon that detects changes in resource metadata and runs user-specified actions when a change is detected. This allows you to make configuration updates on your running Amazon EC2 instances through the `UpdateStack` API action.
For more information, see the [ Updating a CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/updating.stacks.walkthrough.html) tutorial in the *AWS CloudFormation User Guide*.
**Topics**
+ [
## Syntax
](#cfn-hup-Syntax)
+ [
## Options
](#cfn-hup-options)
+ [
## cfn-hup.conf configuration file
](#cfn-hup-config-file)
+ [
## `hooks.conf` configuration file
](#cfn-hup-hook-file)
+ [
## `hooks.d` directory
](#cfn-hup-hooks-dir)
+ [
## Examples
](#cfn-hup-examples)
+ [
## Related resources
](#cfn-hup-related-resources)
## Syntax
```
cfn-hup --config|-c config.dir \
--no-daemon \
--verbose|-v
```
## Options
| Name | Description | Required |
| --- | --- | --- |
| `--config\|-c config.dir` | Specifies the path that the `cfn-hup` script looks for the `cfn-hup.conf` and the `hooks.d` directories. On Windows, the default path is `system_drive\cfn`. On Linux, the default path is `/etc/cfn`. | No |
| `--no-daemon` | Specify this option to run the `cfn-hup` script once and exit. | No |
| `-v, --verbose ` | Specify this option to use verbose mode. | No |
## cfn-hup.conf configuration file
The `cfn-hup.conf` file stores the name of the stack and the AWS credentials that the `cfn-hup` daemon targets.
The `cfn-hup.conf` file uses the following format:
```
[main]
stack=
```
| Name | Description | Required |
| --- | --- | --- |
| `stack` | A stack name or ID. *Type*: String | Yes |
| `credential-file` | An owner-only credential file, in the same format used for the command line tools. *Type*: String *Condition*: The `role` parameter supersedes this parameter. | No |
| `role` | The name of an IAM role that's associated with the instance. *Type*: String | No |
| `region` | The name of the AWS Region containing the stack. *Example*: us-east-2 | No |
| `umask` | The `umask` used by the `cfn-hup` daemon. This value can be specified with or without a leading 0. In both cases, it's interpreted as an octal number (similar to the Linux `umask` command). This parameter has no effect on Windows. *Type*: Octal integer between `0` and `0777` *Default*: `022`, version 1.4–22 and higher. The default value of `022` masks group and world write permissions, so files created by the `cfn-hup` daemon aren't group or world writable by default. The default value for versions 1.4 –21 and earlier is `0`, which masks nothing. | No |
| `interval` | The interval used to check for changes to the resource metadata in minutes. *Type*: Integer *Default*: `15` | No |
| `verbose` | Specifies whether to use verbose logging. *Type*: Boolean *Default*: `false` | No |
## `hooks.conf` configuration file
The user actions that the `cfn-hup` daemon calls periodically are defined in the `hooks.conf` configuration file. The `hooks.conf` file uses the following *format*:
```
[hookname]
triggers=post.add or post.update or post.remove
path=Resources. (.Metadata or .PhysicalResourceId)(.)
action=
runas=
```
When the operation is run, it is run in a copy of the current environment (that `cfn-hup` is in), with `CFN_OLD_METADATA` set to the previous metadata value specified by path, and `CFN_NEW_METADATA` set to the current value.
The hooks configuration file is loaded at `cfn-hup` daemon start up only, so new hooks will require the daemon to be restarted. A cache of previous metadata values is stored at `/var/lib/cfn-hup/data/metadata_db`— you can delete this cache to force `cfn-hup` to run all `post.add` actions again.
| Name | Description | Required |
| --- | --- | --- |
| `hookname` | A unique name for this hook. *Type*: String | Yes |
| `triggers` | A comma-delimited list of conditions to detect. *Valid values*: `post.add`, `post.update`, or `post.remove` *Example*: `post.add, post.update` | Yes |
| `path` | The path to the metadata object. Supports an arbitrarily deep path within the Metadata block. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/cfn-hup.html) | Yes |
| `action` | An arbitrary shell command that is run as given. | Yes |
| `runas` | A user to run the commands as. `cfn-hup` uses the su command to switch to the user. | Yes |
## `hooks.d` directory
To support composition of several applications deploying change notification hooks, `cfn-hup` supports a directory named `hooks.d` that is located in the hooks configuration directory. You can place one or more additional hooks configuration files in the `hooks.d` directory. The additional hooks files must use the same layout as the `hooks.conf` file.
The `cfn-hup` daemon parses and loads each file in this directory. If any hooks in the `hooks.d` directory have the same name as a hook in `hooks.conf`, the hooks will be merged (meaning `hooks.d` will overwrite `hooks.conf` for any values that both files specify).
## Examples
In the following examples, CloudFormation triggers the `cfn-auto-reloader.conf` hooks file when you change the `AWS::CloudFormation::Init` resource that is associated with the `LaunchConfig` resource.
### JSON
```
...
"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
```
...
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"
...
```
## Related resources
You can also visit our GitHub repository to download [sample templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html#sample-templates) that use `cfn-hup`, including the following 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)