Promises

Table of contents

One concept in CFEngine should stand out from the rest as being the mostimportant: promises. Everything else is just an abstraction that allows us todeclare promises and model the various actors in the system.

Everything is a promise

Everything in CFEngine 3 can be interpreted as a promise. Promises can be madeabout all kinds of different subjects, from file attributes, to the executionof commands, to access control decisions and knowledge relationships. If youare managing a system that serves web pages you may define a promise that port80 needs to be open on a web server. This same web server may also define apromise that a particular directory has a particular set of permissions andthe proper owner to serve web pages via Apache.

This simple but powerful idea allows a very practical uniformity in CFEnginesyntax.

Promise types

Thepromise_type defines what kind of object is making the promise. The typedictates how CFEngine interprets the promise body. These promise types arestraightforward: Thefiles promise type deals with file permissions and filecontent, and thepackages promise type allows you to work with packagingsystems such as rpm and apt.

Some promise types are common to all CFEngine components, while others canonly be executed by one of them.cf-serverd cannot keeppackages promises,andcf-agent cannot keepaccess promises. See thePromise type reference for a comprehensivelist of promise types.

The promiser

The promiser is an object affected by a promise, and this can be anything: afile, a port on a network. It is the entity that is making a promise that acertain fact will be true. These facts are listed in the form ofattributes andvalues. A file could promise that a permissionattribute has a particular value (i.e. 775 permission value) and that an ownerattribute has another value (i.e. "root").

When a promise is made in CFEngine it is made to another entity - apromisee. A promisee is an optional part of a promise declaration. Thepromisee can help provide insight into the system's configuration, and maybecome relevant as your system grows in complexity.

Theclasses in a promise control the conditions that make the promisevalid. Examples are the operating system on which the policy is executed, orthe day of the week. More about that in theclasses and decisionmaking section.

Not all of these elements are necessary every time, but when you combine themthey enable a wide range of behavior.

Promise example

code

# Promise typefiles:"/home/mark/tmp/test_plain"->"system blue team",create=>"true",perms=>owner("@(usernames)"),comment=>"Hello World";

In this example, the promise is about a file namedtest_plain in thedirectory/home/mark/tmp, and the promise is made to some entity namedsystem blue team. Thecreate attribute instructs CFEngine to create thefile if it doesn't exist. It has a list of owners that is defined by avariable named "usernames" (see the documentation aboutBodies for more details on this lastexpression).

The comment attribute in this example can be added to any promise. It has noactual function other than to provide more information to the user in errortracing and auditing.

This is a promise that will affect the state of a file on the filesystem. InCFEngine you can do this without having to execute thetouch,chmod, andchown commands. CFEngine is declarative: you declare a contract (or apromise) that you want CFEngine to keep and you leave the details up to thetool.

Promise locking

When a promise is validated (has an outcome of kept or repaired) it is lockedforbody agent control ifelapsed minutes (1 by default). Locks are based on ahash of the promise (promiser, associated attributes, and context).

Promise locks can be useful for controlling frequency.

access,classes,defaults,meta,roles andvars type promises do notparticipate in locking.

Promise attributes

Promise attributes have a type and a value. The type can be any of thedatatypes that are allowed for variables, and in addition

Boolean - allowed input values are
- "true"/"false"
- "on"/"off"
- "yes"/"no"
irange[min, max] andrrange[min, max] - a range of integer or realvalues, created via theirange() andrrange()functions
clist - a list of classes or class expressions. Note that theseattributes can take both strings (which are evaluated as class expressions)and functions that return typeclass
Menu option - one value from a list of values
bodytype - a complex set ofattributes expressed in a separate, reusable block
bundletype - a separate bundlethat is used as a sub-routine or a sub-set of promises

Note: The language does not specifically disallow the use of the sameattribute multiple times within a given promise. As a general rule the lastdefinition wins but the behavior is not clearly defined and this should beavoided.

For example, the following promises use the same attribute multiple times.

code

bundleagentbad_example{classes:"myclass"expression=>"cfengine",expression=>"my_other_class";files:"/tmp/example"perms=>m(600),perms=>owner("root"),perms=>group("root");}