Writing CFEngine policy

Table of contents

To define new Desired States in CFEngine, you need to write policy files. These are plain text-files, traditionally with a.cf extension.

/var/cfengine/inputs and promises.cf

In CFEngine,cf-agent executes all policies.cf-agent runs every 5 minutesby default, and it executes policies found locally in the/var/cfengine/inputsdirectory. The default policy entry is a file calledpromises.cf. In this fileyou normally reference bundles and other policy files.

Bundles, promise types, and classes oh my!

These concepts are core to CFEngine so they are covered in brief here. For moredetailed information see the Language concepts section of the Reference manual.

Bundles

Bundles are re-usable and blocks of CFEngine policy. The following defines abundle calledmy_test, and it is a bundle for the agent.

code

bundleagentmy_test{# ...}

A bundle contains one or more promise types.

Promise types

Think of a promise type as a way to abstract yourself away from details. Forinstance, there is a promise type called users. This promise type allows you tomanage local users on your system. Instead of using low-level commands to manageusers, with the promise type, you only have one simple syntax that works acrossall operating systems.

The most frequently used promise types arevars,classes,files,packages,users,services,commands andreports. Whenever you want todo some file configuration for example, you would use the files promise type.The following policy ensures the existence of the/tmp/hello-world file:

code

files:"/tmp/hello-world"create=>"true";

When defining desired states it is important to be clear about when and whereyou want this policy to apply. For that, CFEngine has the concept of classes.

Classes

Aclass is an identifier which is used by the agent to decide when and where apart of a policy shall run. A class can either be user-defined, a so calledsoft-class, or it can be a hard class which is automatically discovered anddefined by cf-agent during each run. Popular classes includeany which meansany or all hosts,policy_server which means the host is a policy server. Thereare more than 50 hard classes, and combined with regular expressions this givesyou very granular control.

To see a list of available classes on your host, just type the following command:

command

cf-promises --show-classes

Running policy

Now let's put the bundle, promise type and class components together in afinal policy. As for classes we will use linux to define that the file/tmp/hello-world must exists on all hosts of typelinux:

my_test.cf

bundleagentmy_test{files:linux::"/tmp/hello-world"create=>"true";}bundleagent__main__{methods:"my_test";}

Let's save this policy in/tmp/my-policy.cf.

You can now run this policy either in Distributed (client-server) System or in aStand Alone system. The next two sections will cover each of the options.

Option#1: Running the policy on a stand alone system

Since CFEngine is fully distributed we can run policies locally. This can comein handy as the result of a run is instant, especially during the design phasewhere you would like to test out various policies.

To run the file locally, you can log into any of your hosts that has CFEngineinstalled and follow these steps. For this tutorial, use your Policy Server forthis as it is the same cf-agent that runs on the hosts as on the Policy Server.

Tip: Whenever you make or modify a policy, you can use thecf-promisescommand to run a syntax check:

command

cf-promises -f /tmp/my-policy.cf

Unless you get any output, the syntax is correct. Now, to run this policy, simply type:

command

cf-agent -Kf /tmp/my-policy.cf

As you can see, the response is immediate! Running CFEngine locally like this isideal for testing out new policies. To check that the file has been successfullycreated type:

command

ls /tmp/hello-world -l

If you want to see what the agent is doing during its run, you can run the agentin verbose mode. Try:

command

cf-agent -Kf /tmp/my-policy.cf --verbose

In a Stand Alone system, to make and run a policy remember to:

Option#2: Running the Policy on a Distributed System

CFEngine is designed for large-scale systems. It is fully distributed whichmeans that all the logic and decision making takes place on the end-points, orhosts as we call them in CFEngine. The hosts fetch their policies from onecentral distribution point. To continue with this option you need to haveCFEngine running on at least one host and one policy server.

The CFEngine Server typically acts as a policy distribution point. On each host,the cf-agent process runs regularly. This process will by default, every 5minutes, try to connect to cf-serverd on the policy server to check for policyupdates.

By defaultcf-serverd will serve policy from the/var/cfengine/masterfilesdirectory. When the content changes, cf-agent will download the updated files to/var/cfengine/inputs before executing them locally.

This means that by default you should store all your policies in the/var/cfengine/masterfiles directory on your policy server. So, now create/var/cfengine/masterfiles/my-policy.cf with the content of the test policypreviously authored.

NOTE: We recommend that you use a version control system to store the auditlog of your policy.

Now we need to tell CFEngine that there is a new policy in town:

Create/var/cfengine/masterfiles/def.json with the following content:

def.json

{"inputs":["my-policy.cf"]}

On the policy server you can run the following command to make sure the syntaxis correct.

command

cf-promises -cf /var/cfengine/masterfiles/promises.cf

After some period of time (CFEngine runs by default every 5 minutes), log in toany of the bootstrapped clients and you will find the/tmp/-hello-world filethere.

Whenever a host connects to the Policy Server, the host will ensure that it hasthemy-policy.cf file from the masterfiles directory exists in the localinputs directory.def.json will also be downloaded with the newinstruction that there is a new policy. Within 5 minutes, whether you have 5Linux hosts or 50,000 Linux hosts, they will all have the/tmp/hello-world fileon their system. Yeah!

If you delete the file, it will be restored by CFEngine at its next run. We callthis a promise repaired. If the file exists during a run, the result would bepromise kept.

Congratulations! You now have the basic knowledge needed to write and runCFEngine policies. Let's continue with an example on how to manage users. Clickhere to continue.