cfn-hup - AWS CloudFormation
SyntaxOptionscfn-hup.conf configuration filehooks.conf configuration filehooks.d directoryExamplesRelated resources

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.

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=<stack-name-or-id>
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.<logicalResourceId> (.Metadata or .PhysicalResourceId)(.<optionalMetadatapath>)
action=<arbitrary shell command>
runas=<runas user>

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.

Path format options

  • Resources.<LogicalResourceId>— monitor the last updated time of the resource, triggering on any change to the resource.

  • Resources.<LogicalResourceId>.PhysicalResourceId— monitor the physical ID of the resource, triggering only when the associated resource identity changes (such as a new EC2 instance).

  • Resources.<LogicalResourceId>.Metadata(.optional path)— monitor the metadata of a resource for changes (a metadata subpath may be specified to an arbitrarily deep level to monitor specific values).

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" : {
        "QBVersion": {"Ref": "paramQBVersion"},
        "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:
      QBVersion: !Ref paramQBVersion
      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"
...

For a sample template, see Deploying applications on Amazon EC2 with CloudFormation in the AWS CloudFormation User Guide.