Promises

According to the cfengine documentation: A promise is the documentation or definition of an intention to act or behave in some manner. They are the rules which CFEngine clients are responsible for implementing.

Or, in other words, a promise tells cf-agent what it should do. Note that cf-agent runs on the client hosts, typically once every five minutes (see cf-execd).

Here are some examples:

1. Copy a file from the cfengine hub to a particular filesystem location on the client. Commonly this promise includes the caveat: "if the existing file is different to the one on the server". This sort of promise is good for setting up configuration files in /etc, for example.
2. Execute a command or script when a file is changed (such as by an instance of preceding example). This sort of promise is good for kicking (reloading or restarting) a daemon when there's a configuration file change, such as when an automounter configuration file changes.

Promises are stored in the file /var/lib/cfengine3/inputs/promises.cf on each client and, indeed, it is a promise in this file that causes cf-agent to check for and download a new instance of the file when it changes on the hub.

Promises are stored in "bundles". These are simply collections of related promises, such as promises related to the /etc/hostname file, or to the abovementioned automounter configuration, or to the LDAP configuration, etc.

Types of promises

Promise type	Description
files	Actions on files or directories, including creating, copying, editing and deleting
commands	Running external commands or scripts
reports	Outputting messages to the message log
classes	Setting cfengine classes

All actions can be conditional, i.e., performed only when certain specified conditions are true.