• Examples and tutorials

Examples and tutorials

Links to examples

• Example snippets: This section is divided into topical areas and includes many examples of policy and promises. Each of the snippets can be easily copied or downloaded to a policy server and used as is.

Note: CFEngine also includes a small set of examples by default, which can be found in/var/cfengine/share/doc/examples.

• Enterprise API examples
• Tutorials

See also:

• Tutorial for running examples
  • "Hello world" policy example
  • Activate a bundle manually
  • Make the example stand alone
  • Make the example an executable script
  • Integrating the example into your main policy

Tutorial for running examples

In this tutorial, you will perform the following:

• Create a simple "Hello World!" example policy file
• Make the example a standalone policy
• Make the example an executable script
• Add the example to the main policy file (promises.cf)

Note if your CFEngine administrator has enabled continuous deployment of the policy from a Version control System, your changes may be overwritten!

"Hello world" policy example

Policies containbundles, which are collections of promises. Apromise is a declaration ofintent. Bundles allow related promises to be grouped together, as illustrated in the steps that follow.

Following these steps, you will login to your policy server via the SSH protocol, use the vi command line editor to create a policy file named hello_world.cf, and create a bundle that calls a promise to display some text.

1. Log into a running server machine using ssh (PuTTY may be used if using Windows).
2. Typesudo su for super user (enter your password if prompted).
3. To get to themasterfiles directory, typecd /var/cfengine/masterfiles.
4. Create the file with the command:vi hello_world.cf
5. In the vi editor, enteri for "Insert" and enter the following content (ie. copy and paste from a text editor):cf3[file=hello_world.cf]bundle agent hello_world{ reports: any:: "Hello World!";}
6. Exit the "Insert" mode by pressing the "esc" button. This will return to the command prompt.
7. Save the changes to the file by typing:w then "Enter".
8. Exit vi by typing:q then "Enter".

In the policy file above, we have defined anagent bundle namedhello_world. Agentbundles are only evaluated bycf-agent, theagent component of CFEngine.

This bundlepromises toreport on anyclass of hosts.

Activate a bundle manually

Activate the bundle manually by executing the following command at prompt:

/var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world

This command instructs CFEngine to ignorelocks, loadthehello_world.cf policy, and activate thehello_world bundle. See the output below:

/var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world

2013-08-20T14:03:43-0500   notice: R: Hello World!

As you get familiar with CFEngine, you'll probably start shortening this command to this equivalent:

/var/cfengine/bin/cf-agent -Kf ./hello_world.cf -b hello_world

Note the full path to the binary in the above command. CFEngine stores its binaries in/var/cfengine/binon Linux and Unix systems. Your path might vary depending on your platform and the packages your are using.CFEngine uses /var because it is one of the Unix file systems that resides locally.Thus, CFEngine can function even if everything else fails(your other file systems, your network, and even system binaries) and possibly repair problems.

Make the example stand alone

Instead of specifying the bundle sequence on the command line (as it was above), abody commoncontrol section can be added tothe policy file. Thebody common control refers to those promises that are hard-coded intoall CFEngine components and therefore affect the behavior of all components. Note that only onebody common control is allowed per agent activation.

Go back into vi by typing "vi" at the prompt. Then typei to insertbody common control tohello_world.cf. Place it abovebundle agent hello_world, asshown in the following example:

bodycommoncontrol{bundlesequence=>{"hello_world"};}bundleagenthello_world{reports:any::"Hello World!";}

Now press "esc" to exit the "Insert" mode, then type:w to save the file changes and "Enter".Exit vi by typing:q then "Enter." This will return to the prompt.

Execute the following command:

/var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf

notice: R: Hello World!

Note: It may be necessary to add a reference to the standard library within the body common control section, and remove thebundlesequence line.Example:

bodycommoncontrol{inputs=>{"libraries/cfengine_stdlib.cf",};}

Make the example an executable script

Add the#! marker ("shebang") tohello_world.cf in order to invoke CFEngine policy as an executable script:Again type "vi" then "Enter" theni to insert the following:

#!/var/cfengine/bin/cf-agent --no-lock

Add it beforebody common control, as shown below:

#!/var/cfengine/bin/cf-agent --no-lockbodycommoncontrol{bundlesequence=>{"hello_world"};}bundleagenthello_world{reports:any::"Hello World!";}

Now exit "Insert" mode by pressing "esc". Save file changes by typing:w then "Enter"then exit vi by typing:q then "Enter". This will return to the prompt.

Make the policy file executable:

chmod +x ./hello_world.cf

And it can now be run directly:

./hello_world.cf

2013-08-20T14:39:34-0500   notice: R: Hello World!

Integrating the example into your main policy

Make the example policy part of your main policy bydoing the following on your policy server:

1. Ensure the example is located in/var/cfengine/masterfiles.

2. If the example contains abody common control section, delete it. Thatsection will look something like this:

   code

   bodycommoncontrol{bundlesequence=>{"hello_world"};}

You cannot have duplicate control bodies (i.e. twoagent control bodies, one in the main file and onein the example) as CFEngine won't know which itshould use and they may conflict.

To resolve this, copy the contents of the control body section from theexample into the identically named control body section in the main policyfile/var/cfengine/masterfiles/promises.cfand then remove the control bodyfrom the example.

1. Insert the example's bundle name in thebundlesequence sectionof the main policy file/var/cfengine/masterfiles/promises.cf:

   code

   bundlesequence=>{..."hello_world",...};

2. Insert the policy file name in theinputs section of the main policy file/var/cfengine/masterfiles/promises.cf:

   code

   inputs=>{..."hello_world.cf",...};

3. You must also remove any inputs section from the example thatincludes the external library:

   code

   inputs=>{"libraries/cfengine_stdlib.cf"};

   This is necessary, sincecfengine_stdlib.cf is already includedin the inputs section of the master policy.

4. The example policy will now be executed every five minutes along with the restof your main policy.

Notes: You may have to fill the example with data before it will work.For example, the LDAP query inactive_directory.cf needs a domain name.In the variable declaration, replace "cftesting" with your domain name:

vars:# NOTE: Edit this to your domain, e.g. "corp""domain_name"string=>"cftesting";

Still need help?

Chat

Ask a question on Github

Mailing list