Are you familiar with CFEngines special variables?
Probably you are familiar with sys variables like sys.fqhost (the fully qualified host name) and sys.policy_hub (the IP address of the machine the host is bootstrapped to) but I want to highlight a few other special variables you may not be so familiar with.
sys Sys variables are derived from the system discovery done by the agent as it initializes.
sys.os_release - A data structure derived from /etc/os-release /etc/os-release, introduced by systemd provides a nice record of the current distributions release information.1 CFEngine prefers information from this file for determining system classification like the definition of the redhat and debian classes. The file can also be extended with custom keys, like I have done on my system to set NORTHERN_TECH_OWNER=Nick Anderson. Since files information is exposed as a data container in this sys variable it can be useful for influencing policy behavior, like selecting additional Augments to load.2
Did you know that CFEngine has namespaces? Let’s see how they can facilitate policy sharing while avoiding “duplicate definitions of bundle” errors.
Most of the Masterfiles Policy Framework (MPF) and policy examples for CFEngine use the default namespace. However, body file control allows you to specify a namespace that applies for the rest of the file or until it’s set again by another body file control.
Let’s consider a contrived example. Say we have two policy files (policy-1.cf, policy-2.cf) for different services. In each policy file, we want to have a bundle where we store settings related to that policy. Traditionally this would be handled by using some bundle naming convention, so we might have bundle agent policy_1_settings and bundle agent policy_2_settings. Using namespaces you can keep your bundle names brief and use different namespaces to avoid “duplicate definitions of bundle” errors.
Did you know you can include one policy file from another?
Traditionally you specify the files you want to make up a policy set using inputs in body common control found in your policy entry (promises.cf by default).
body common control { # Paths are relative to $(sys.policy_entry_dirname) if not # fully qualified inputs => { "path/to/policy-1.cf", "path/to/policy-2.cf", }; } body file control lets you specify additional inputs from any file that’s included in the policy and those files can include other files.
Ever want to run just a one or a few select bundles from your policy?
While developing policy it’s common to run cf-agent -KI so that you can quickly iterate on changes and the run the policy without locks. But if you are focused on select bundles you may not need the full policy to run, you can use the --bundlesequence option to specify one or more bundles overriding the bundlesequence defined in body common control.
Ever wanted to make sure a promise only runs if some other promise has succeeded?
Consider this contrived example with two reports type promises, It's Friday! and I love CFEngine Feature Friday. Per normal ordering1, these two promises will be emitted in the written order.
/tmp/feature-friday-7.cf bundle agent feature_friday { reports: "It's Friday, Friday"; "Gotta get down on Friday"; } command cf-agent --no-lock --bundlesequence feature_friday --file /tmp/feature-friday-7.cf output R: It's Friday! R: I love CFEngine Feature Friday. If we want them in the opposite order, we could either change the order or define classes based on the results of the promises. But today’s feature, depends_on, lets us influence the ordering using a more lightweight method via handle.
Will your policy work? cf-promises can check the CFEngine policy for syntax errors and give you an overview of the host’s context.
It’s always a good idea to check your policy for syntax errors.
Consider this policy file:
/tmp/feature-friday-6.cf bundle agent feature_friday { reports: "$(this.promise_filename)" printfile => cat( "$(this.promise_filename)" ) } Can you spot the error? Let’s see if cf-promises can help:
command cf-promises -f /tmp/feature-friday-6.cf output /tmp/feature-friday-6.cf:6:2: error: syntax error } ^ /tmp/feature-friday-6.cf:6:2: error: Check previous line, Expected ';', got '}' } ^ error: There are syntax errors in policy files The output tells us that there is a syntax error near line 6, column 2. A semicolon (;) was expected but instead, a closing curly brace (}) was found. We are missing the semicolon that terminates the promise for bundle feature_friday_6 which is called as a methods promise.
When you want to inspect both the return code and output from a command execresult_as_data() might be the function you are searching for.
Most CFEngine policy writers have used execresult() and returnszero(). They are useful when you want to do something based on the output of a command or based on its successful execution (returning zero). For example:
/tmp/feature-friday-3.cf bundle agent __main__ { vars: "hostname" string => execresult( "$(paths.hostname)", "useshell" ); classes: "my_command_returned_zero" expression => returnszero( "$(paths.hostname)", "noshell" ); reports: "$(hostname)"; my_command_returned_zero:: "$(paths.hostname) returned 0"; } command cf-agent --no-lock --log-level info --file /tmp/feature-friday-3.cf output precision-5570 R: precision-5570 R: /bin/hostname returned 0 But, sometimes, you care about specific return codes. However, you might also want to consider the output from a command. execresult_as_data() facilitates inspecting both output and return code from a command’s execution, by returning a data structure. Let’s take a look.
Have you ever wanted some hosts to organize themselves into different groups, but without spending time to worry about assigning a specific group?
Cody, Craig, and Nick talk about using the select_class feature in CFEngine. Nick implements automatic assignment of a maintainer for each host:
You want to assign a maintainer to each host that should be the primary point of contact. Some hosts should may have a specific maintainer, but generally, you don’t care about the relationship between the person and the actual function of the machine. It’s okay if the groups are not perfectly balanced. First we provide a list of maintainers to select from.
Ever wanted to manipulate a string - temporarily - for an individual promise? Check out the with attribute and its special, $(with) variable.
Sometimes you need some variation on a string for a specific case. Traditionally, to achieve this you’d simply define another variable.
Here is a contrived example:
I have a string, nginx and I want to emit a report that contains both the string itself and the upper case version of the string.
Looking for a way to concisely set a variable conditionally? Have you heard of ifelse()?
In CFEngine, traditionally class expressions are used to constrain promises to different contexts. Setting a variable to different values based on context might look like this:
/tmp/feature-friday-1.cf bundle agent __main__ { vars: "MyVariable" string => "My Default value"; redhat_8|centos_8|rocky_8:: "MyVariable" string => "My value for EL 8"; ubuntu_22:: "MyVariable" string => "My value for Ubuntu 22"; any:: "MyVariable" string => "My value on Friday", if => "Friday"; reports: "It's $(sys.date) and I am running on $(sys.os_release[PRETTY_NAME])"; "MyVariable is '$(MyVariable)'"; } command cf-agent --no-lock --log-level info --file /tmp/feature-friday-1.cf output R: It's Mon Mar 11 12:36:41 2024 and I am running on Ubuntu 22.04.4 LTS R: MyVariable is 'My value for Ubuntu 22' That’s great, lots of flexibility, but with an increasing number of options the policy can get quite long and it’s easier for a human interpreter to lose track of the context. The same can be achieved in a single statement using ifelse().
