Normal ordering

Table of contents

CFEngine takes a pragmatic point of view to ordering. When promisingscalarattributes and properties, ordering is irrelevant and should not be considered.More complex patterned data structures require ordering to be preserved, e.g.editing in files. CFEngine solves this in a two-part strategy:

CFEngine maintains a default order of promise-types. This is based on a simplelogic of what needs to come first, e.g. it makes no sense to create somethingand then delete it, but it could make sense to delete and then create (anequilibrium). This is called normal ordering and is described below. You canoverride normal ordering in exceptional circumstances by making a promise in aclass context and defining that class based on the outcome of another promise,or using thedepends_on promise attribute.

Agent normal ordering

CFEngine tries to keep variable and class promises before starting to considerany other kind of promise. In this way, global variables and classes can be set.

If you set variables based on classes that are determined by other variables,then you introduce an order dependence to the resolution that might benon-unique.Since CFEngine starts trying to converge values as soon aspossible, it is best to define variables in bundles before using them, i.e.as early as possible in your configuration. In order to make sure all globalvariables and classes are available early enough policy pre-evaluation step wasintroduced.

Policy evaluation overview

CFEngine policy evaluation is done in several steps:

Classes provided as a command line argument (-D option) are read and set.
Environment detection and hard classes discovery is done.
Persistent classes are loaded.
Policy sanity check using cf-promises -c (full-check) is performed.
Pre-evaluation step is taking place.
Exact policy evaluation is done.

For more information regarding each step please see the detailed descriptionbelow.

Policy evaluation details

Before exact evaluation of promises takes place first command line parametersare read and all classes defined using-D parameter are set. Next,environment detection takes place and hard classes are discovered. Whenenvironment detection is complete all the persistent classes are loaded and apolicy sanity check is performed using cf-promises.

cf-promises policy validation step

In this step policy is validated andclasses andvars promises areevaluated. Note that cached functions are executed here, and then again duringthe normal agent execution. Variables and classes resolved in this step do notpersist into the following evaluation step, so all functions will run againduring Agent pre-evaluation.

Agent pre-evaluation step

In order to support expansion of variables in body common control inputs andmake sure all needed classes and variables are determined before they areneeded in normal evaluation, pre-evaluation takes place immediately beforepolicy evaluation.

During pre-evaluation files are loaded based on ordering in body common control(first) and body file control (after body common control). This means thatfiles included in body common control are loaded and parsed before filesplaced in body file control. This is important from a common bundlesevaluation perspective as bundles placed in files included in body commoncontrol inputs will be evaluated before bundles from file control inputs.

The following steps are executed per-bundle for each file parsed, in this order:

if it's a common bundle, evaluatevars promises
if it's a common bundle, evaluateclasses promises
evaluatevars promises(for details seePolicyResolve() in the C code)

This is done because classes placed in common bundlesare global whereas classes placed in agent bundles are local (by default) tothe bundle where those are defined. This means that common bundlesclasses need these extra steps in order to be resolved for the next steps.

After all policy files are parsed and pre-evaluated, the above pre-evaluationsequence runs once again inorder to help resolve dependencies between classes and vars placed indifferent files.

Agent evaluation step

After pre-evaluation is complete normal evaluation begins.

In this step CFEngine executes agent promise bundles in the strict orderdefined by the bundlesequence (possibly overridden by the-b or--bundlesequence command line option). If the bundlesequence is not providedvia command line argument or is not present in body common control agent willattempt to execute a bundle namedmain. If bundlemain is not defined, theagent will error and exit.

Within a bundle, the promise types are executed in a round-robin fashionaccording to so-callednormal ordering (essentially deletion first, followedby creation). The actual sequence continues for up to three iterations of thefollowing, converging towards a final state:

Withinedit_line bundles in files promises,the normal ordering is:

The order of promises within one of the above types follows their top-downordering within the bundle itself. In vars this can be used to override thevalue of a variable, if you have two vars promises with the same name, thelast one will override the first one. The order may be overridden by making apromise depend on a class that is set by another promise, or by using thedepends_on attribute in the promise.

Note: The evaluation order of common bundles areclasses, thenvariables and finallyreports. All common bundles are evaluated regardlessif they are placed inbundlesequence or not. Placing common bundles inbundlesequence will cause classes and variables to be evaluated again, and isgenerally good practice to make sure evaluation works properly.

Server normal ordering

As with the agent, common bundles are executed before any server bundles;following this all server bundles are executed (thebundlesequence is onlyused for cf-agent). Within a server bundle, the promise types are unambiguous.Variables and classes are resolved in the same way as the agent. Onconnection, access control must be handled first, then a role request might bemade once access has been granted. Thus ordering is fully constrained byprocess with no additional freedoms.

Within a server bundle, the normal ordering is:

Monitor normal ordering

As with the agent, common bundles are executed before any monitor bundles;following this all monitor bundles are executed (thebundlesequence is onlyused for cf-agent). Variables and classes are resolved in the same way as theagent.

Within a monitor bundle, the normal ordering is: