cf sketch manual

TODO: revise when cf-sketch is ready.

cf-sketch is a tool that allows you to manage sketches from the CFEngine Design Center. This includes searching, installing, configuring, activating, and uninstalling them.

Basic information

Concepts:

• You can install cf-sketch on any machine, be it a CFEngine client or policy hub. The default installation target will vary as described below under "Terms".
• By default, cf-sketch looks for sketches in the Design Center GitHub repository, located at [https://github.com/cfengine/design-center]. You can add your own repositories in addition (or instead of) the default.
• Sketches may be installed but not activated. This means the files are there, but the sketch has not been configured nor activated for execution by CFEngine.
• A single sketch may be activated more than once, with different parameters.
• To integrate sketches into the execution flow of your existing CFEngine policies, you need to generate a runfile using the cf-sketch command. The runfile sets all the appropriate parameters for active sketches, and calls the appropriate bundles.

Definitions:

• A Sketch is a reusable piece of CFEngine policy, normally composed of one or more CFEngine bundles, and possibly other support structures and files.
• The installation target is the directory under which all the sketches will be installed. If you run it on a CFEngine policy hub, it will by default install sketches under /var/cfengine/masterfiles/sketches/. If you run it on a CFEngine client, it will install them under /var/cfengine/inputs/sketches/. If you run it as a non-root user, it will install under $HOME/.cfagent/inputs/sketches/. The installation target can be changed using the --install-target command-line option to cf-sketch.
• cf-sketch repository: a directory hierarchy with sketches in it, local or remote. This is where sketches are obtained from, to be installed on the local system.
• Parameters: data external to cfengine and the sketch, which is used to configure the sketch. Equivalent to subroutine parameters in traditional programming languages.
• Parameter metadata: a way for the sketch to declare that it uses certain parameters, and possibly their default values.
• Sketch entry point and entry bundle: the single way to run a sketch externally. The entry point is a file; the entry bundle is a bundle in that file that has parameter metadata. This is how cf-sketch knows what should be invoked for running the sketch.
• Sketch installation: this is how sketches are installed in the installation target directory.
• Sketch activation: this is how installed sketches are configured with a specific set of parameters.
• Runfile generation: the runfile is a CFEngine file that contains all the data and code to run all the activated sketches.

Typical cf-sketch workflow

See Getting started with cfsketch for installation instructions.

See all the sketches available in the default install source (the install source can be changed using the --install-source command-line option):

cf-sketch --search all

The special value all lists all the sketches, but the argument can also be an arbitrary regular expression (-s is shorthand for --search):

cf-sketch -s utilities

Once you have found the sketch you want to use, you need to install it:

cf-sketch --install VCS::vcs_mirror

The VCS::vcs_mirror sketch allows you to set up a checkout from a version-control repository, for the moment only git is supported).

Once a sketch is installed, you need to activate it by providing the necessary parameters for its operation. The parameters file is expected to be in JSON format, and it can be either the path of a local file, or a URL:

cf-sketch --activate VCS::vcs_mirror=https://raw.github.com/cfengine/design-center/master/sketches/utilities/vcs_mirror/params/cfengine-copbl.json

If you examine the contents of the cfengine-copbl.json file, you will see that it contains the parameters needed by the sketch:

# wget -q -O- https://raw.github.com/cfengine/design-center/master/sketches/utilities/vcs_mirror/params/cfengine-copbl.json
{
 "activated": true,
 "path": "/tmp/cfengine-copbl",
 "origin":"https://github.com/cfengine/copbl.git",
 "branch": "master",
 "vcs": "/usr/bin/git"
}

You can use cf-sketch to get a description of the API (expected parameters and their default values) for a sketch:

cf-sketch --api VCS::vcs_mirror

You can also generate this description in JSON format. This output can be used as the starting point for generating a specification that can be loaded using --activate:

cf-sketch --api VCS::vcs_mirror --json

You can ask cf-sketch to show you all the activated sketches, including their parameters:

cf-sketch --list-activations

You can activate the same sketch multiple times, as long as you use different parameter values:

cf-sketch -a VCS::vcs_mirror=https://raw.github.com/cfengine/design-center/master/sketches/utilities/vcs_mirror/params/cfengine-core.json

Note that the parameter values are brought in at the moment of activation --- if the source file changes after activation, those changes will not be reflected in the activated sketch.

Once you have activated the sketches you want, you need to generate the runfile that will instruct CFEngine to execute all those sketches with the appropriate parameters:

cf-sketch --generate

The default name of the runfile is cf-sketch-runfile.cf, and it will be installed under the default installation target, as described above under "Basic information". Feel free to examine this file to see how it is setting up the parameters and invoking the sketches. A more detailed description of the runfile can be found at cf–sketch runfile description.

You can run the generated runfile by hand to see it in action:

cf-agent -KI -f /var/cfengine/masterfiles/cf-sketch-runfile.cf

Once you want to put your sketches in production, you need to use the --no-standalone option:

cf-sketch --generate --no-standalone

Then you can load the runfile from your promises.cf file, and include the cfsketch_run bundle in your bundlesequence. For example:

body common control
{
 bundlesequence => { "main", "cfsketch_run" };

 inputs => {
            "cf-sketch-runfile.cf",
            @(cfsketch_g.inputs)
           };
}

To deactivate a sketch, you need to provide the same file name as when activating it:

cf-sketch --deactivate VCS::vcs_mirror=https://raw.github.com/cfengine/design-center/master/sketches/utilities/vcs_mirror/params/cfengine-core.json

You can also deactivate a sketch by number. The numbers are shown when you list the existing activations using the --list-activations option.

cf-sketch --deactivaten 3

Or you can deactivate all the activations of a particular sketch:

cf-sketch.pl -d VCS::vcs_mirror=all

The --deactivate option simply deactivates the sketch, but does not uninstall this. You can also completely uninstall it:

cf-sketch.pl --remove VCS::vcs_mirror

On all commands you can use the --verbose or -v flag to obtain additional information during its execution, --quiet or -q to supress all non-error output, and --force or -f to override any dependency checks (for example, to force a sketch to install on an unsupported operating system).

Below you will find a full reference of all the options available in cf-sketch.

Reference for cf-sketch

The generic usage for cf-sketch is as follows:

cf-sketch [general options] --verb [verb-arg] [verb-specific options]

Available verbs and their options

• --install (-i): install or update the given sketch.

• --api: show the arguments expected by the given sketch, including any optional arguments and their default values.

  The --json option can be used to produce the information in JSON format instead of human-readable format.

• --activate (-a): configure and activate the given sketch, which must already be installed, in the format "SKETCH=FILE" where FILE must be the path or URL of a file containing the necessary parameters for the sketch.

  The --params (-p) option is optional when activating a sketch, and lets you specify "K=V" format parameters to the sketch in addition to or on top of the activation parameters.

• --search (-s): search all source repositories for the regular expression given as an argument. If the string all is given as argument, then all the available sketches will be listed (all is equivalent to specifying .* as a regular expression).

• --list (-l): search all installed sketches for the regular expression given as anargument. If no argument is given, or the string all is specified as argument, then all the installed sketches will be listed.

• --list-activations (-la): list all activated sketches.

• --generate (-g): generate the runfile that can be used to invoke all the activated sketches, with the correct parameters.

  By default the generated runfile includes a body common control that allows it to be executed directly using cf-agent. The --no-standalone (-no-st) option can be used to modify this behavior, so that the generated file can be included from other policy file using the inputs attribute.

• --deactivate (-d): deactivate the given sketch, or all the sketches if all is given as an argument to --deactivate.

• --deactivaten (-dn): deactivate the given sketch activation by number, as given by --list-activations.

• --remove (-r): uninstall the given sketch.

• --help: Print a help message.

• --config-save: save the current option values (whether default values, or as specified in the command line or configuration file) to the configuration file specified by --configfile.

• --save-metarun FILE: save a metarun file based on the current install, remove, activate, or deactivate options (so modify the command line until it does what you want, then just --save-metarun FILE at the end). It basically encapsulates all the command-line operational parameters in a single JSON file.

• --metarun FILE: use the metarun file generated by --save-metarun.

General options

• --verbose (-v): produce additional output about the actions taken.
• --quiet (-q): supress all non-essential output.
• --force (-f): ignore all dependencies when installing, activating or deactivating sketches.
• --configfile (-cf): configuration file to use. Defaults to /etc/cf-sketch/cf-sketch.conf when running as root, and $HOME/.cf-sketch/cf-sketch.conf) when running as a regular user.
• --cfhome: directory where the cf-promises binary can be found. Defaults to /var/cfengine/bin.
• --act-file (-af): file where sketch activations are recorded. Defaults to /etc/cf-sketch/activations.conf when running as root, and $HOME/.cf-sketch/activations.conf) when running as a regular user.
• --install-source (-is): location (file path or URL) of a cfsketches catalog file that contains the list of sketches available for installation. Defaults to the current tree if cf-sketch is being run from inside a local repository (for example, a checked-out copy of the Design Center repository), or to https://raw.github.com/cfengine/design-center/master/sketches/cfsketches otherwise.
• --install-target (-it): directory where sketches will be installed. Defaults to /var/cfengine/masterfiles/sketches/ if run on a CFEngine policy hub, to /var/cfengine/inputs/sketches/ if run on a CFEngine client, and to $HOME/.cfagent/inputs/sketches/ if run as a non-root user. It needs to be writeable by the user running cf-sketch, and it can be used as an element in --repolist.
• --repolist (-rl): Comma-separated list of local directories to search for installed sketches for activation, deactivation, removal, or runfile generation. It defaults to the same value as --install-target.
• --runfile (-rf): location of the runfile. Defaults to /var/cfengine/masterfiles/cf-sketch-runfile.cf if run on a CFEngine policy hub, to /var/cfengine/inputs/cf-sketch-runfile.cf if run on a CFEngine client, and to $HOME/.cfagent/inputs/cf-sketch-runfile.cf if run as a non-root user.

Writing a sketch

See Writing DC Sketches.