dc runfile description

Design Center runfiles

The Design Center API will generate a runfile (configured by config.json; see Introduction to Design Center API) that calls all the activated sketches with their parameters.

The runfile can be standalone or not.

If this looks complicated, don't worry. Design Center's goal is to abstract these details from you and let you get on with writing policy.

Standalone setup

A standalone runfile will contain this body:

body common control
{
      bundlesequence => { cfsketch_g, cfsketch_run };
      inputs => { @(cfsketch_g.inputs) };
}

If you don't want a standalone runfile, you'll need to provide something like this in your primary promises.cf file.

Run environments

The runfile begins with all the run environments. For instance, cf-sketch in expert mode will create something like this run environment:

# environment cf_sketch_testing
bundle common cf_sketch_testing
{
  vars:
      "activated" string => "1";
      "env_vars" slist => { "activated", "test", "verbose" };
      "test" string => "1";
      "verbose" string => "1";
  classes:
      "runenv_cf_sketch_testing_activated" expression => "any";
      "runenv_cf_sketch_testing_test" expression => "any";
      "runenv_cf_sketch_testing_verbose" expression => "any";
}

This says "I want my sketch to run everywhere, always be in test mode, and always be verbose." (You can use the --activated X and --test Y options to cf-sketch in expert mode to change either of the above to a CFEngine class or context.)

Runfile inputs

bundle common cfsketch_g
{
  vars:
      # Files that need to be loaded for the activated sketches and
      # their dependencies.
      "inputs" slist => { "sketches/libraries/dclib/library.cf", "sketches/libraries/copbl/cfengine_stdlib.cf", "sketches/security/limits/main.cf" };
}

Next, the cfsketch_g bundle defines a list variable called @(cfsketch_g.inputs) that contains the list of files that need to be loaded for the sketches to execute properly (this is taken from the sketches' interface definitions). This variable will be used in the policy's inputs attribute to make sure all the appropriate files are loaded, if the runfile is standalone. If it's not, this is merely decorative.

The runfile's filter_inputs parameter in config.json can filter out some inputs from this list.

Runfile entry point

The entry point to call the sketches is a bundle called cfsketch_run. This bundle will call the entry bundles for all the activated sketches and set up their parameters.

Here's an example: a single activation of the Security::limits sketch.

bundle agent cfsketch_run
{
  vars:

      # array 'metadata' from definition sketch metadata, activation ___001_Security_security_limits_limits
      "___001_Security_security_limits_limits_metadata[authors]" slist => { "Nick Anderson <nick@cmdln.org>", "Ted Zlatanov <tzz@lifelogs.com>" };
      "___001_Security_security_limits_limits_metadata[depends]" slist => { "CFEngine::dclib", "CFEngine::stdlib" };
      "___001_Security_security_limits_limits_metadata[license]" string => "MIT";
      "___001_Security_security_limits_limits_metadata[location]" string => "/home/tzz/.cfagent/inputs/sketches/security/limits";
      "___001_Security_security_limits_limits_metadata[manifest]" slist => { "README.md", "changelog", "main.cf", "params/example.json", "test.cf" };
      "___001_Security_security_limits_limits_metadata[manifest_cf]" slist => { "main.cf", "test.cf" };
      "___001_Security_security_limits_limits_metadata[manifest_docs]" slist => { "README.md" };
      "___001_Security_security_limits_limits_metadata[manifest_exe]" slist => { "cf_null" };
      "___001_Security_security_limits_limits_metadata[manifest_extra]" slist => { "changelog", "params/example.json" };
      "___001_Security_security_limits_limits_metadata[name]" string => "Security::security_limits";
      "___001_Security_security_limits_limits_metadata[tags]" slist => { "cfdc" };
      "___001_Security_security_limits_limits_metadata[version]" string => "1.2";

      # array 'domains' from definition parameter definition from /home/tzz/source/design-center/tools/test/../../sketches/security/limits/params/example.json, activation ___001_Security_security_limits_limits
      "___001_Security_security_limits_limits_domains[*][-][maxlogins]" string => "100";
      "___001_Security_security_limits_limits_domains[*][soft][core]" string => "1024";

  methods:
    any::
      "cfsketch_g" usebundle => "cfsketch_g";
      "cf_sketch_testing" usebundle => "cf_sketch_testing";

    runenv_cf_sketch_testing_activated::
      "___001_Security_security_limits_limits" usebundle => cfdc_security_limits:limits("cf_sketch_testing", "default:cfsketch_run.___001_Security_security_limits_limits_metadata", "/etc/security/limits.conf", "default:cfsketch_run.___001_Security_security_limits_limits_domains", "", ""), ifvarclass => "linux", useresult => "return____001_Security_security_limits_limits";

  reports:
    cfengine::
      "activation ___001_Security_security_limits_limits returned filename = $(return____001_Security_security_limits_limits[filename])";
      "activation ___001_Security_security_limits_limits could not run because it requires classes linux" ifvarclass => "inform_mode.!(linux)";
}

Note all the metadata passed to the bundle in an array. This is how Design Center communicates with the bundle.