Components

Table of contents

While promises to configure your system are entirely user-defined, thedetails of the operational behavior of the CFEngine software is ofcourse hard-coded. You can still configure the details of thisbehavior using thecontrol promise bodies. Control behavior isdefined in bodies because the actual promises are fixed and you onlychange their details within sensible limits.

See theintroductionfor a high-level overview of theCFEngine components, and each component's reference documentation for thedetails about the specific control bodies.

Common control

Thecommon control body refers to those promises that arehard-coded into all the components of CFEngine, and thereforeaffect the behavior of all the components.

code

bodycommoncontrol{inputs=>{"update.cf","library.cf"};bundlesequence=>{update("policy_host.domain.tld"),"main","cfengine2"};goal_categories=>{"goals","targets","milestones"};goal_patterns=>{"goal_.*","target.*"};output_prefix=>"cfengine>";version=>"1.2.3";}

bundlesequence

Description: Thebundlesequence contains promise bundlesto verify, in a specific order.

Thebundlesequence determines which of the compiled bundles will be executedbycf-agent and in what order they will be executed. The list refers to thenames of bundles (which might be parameterized, function-like objects).

The default value forbundlesequence is{ "main" }.

Abundlesequence may also be specified using the-b or--bundlesequence command line option.

Type:slist

Allowed input range:.*

Example:

code

bodycommoncontrol{bundlesequence=>{update("policy_host.domain.tld"),"main","cfengine2"};}

Note: Onlycommon andagent bundles are allowed to be listed in thebundlesequence.

The order in which you execute bundles can affect the outcome ofyour promises. In general you should always define variables beforeyou use them.

Thebundlesequence is like a genetic makeup of a machine. Thebundles act like characteristics of the systems. If you wantdifferent systems to have differentbundlesequences, distinguishthem with classes

code

webservers::bundlesequence=>{"main","web"};others::bundlesequence=>{"main","otherstuff"};

If you want to add a basic common sequence to all sequences, thenuse global variable lists to do this:

code

bodycommoncontrol{webservers::bundlesequence=>{@(g.bs),"web"};others::bundlesequence=>{@(g.bs),"otherstuff"};}bundlecommong{vars:"bs"slist=>{"main","basic_stuff"};}

History: The default to{ "main" } was introduced in version 3.7.0, so ifyou expect your policies to be run by older version, you'll need an explicitbundlesequence.

bwlimit

Description: Coarse control of bandwidth any cf-serverd or cf-agent processwill sendout. In Bytes/sec.

Bandwidth limit is meant to set an upper bound of traffic coming out of CFEngineagents or servers, as a countermeasure against network abuse from them. The limitis applied to all interfaces (in total), a single process at a time. It canprevent network being flooded by CFEngine traffic when large files or many agentshit a single cf-serverd.

For more fine-grained control, please use operating system (eg. iptables)facilities.

Note: Bandwidth limiting is currently not supported on Windows.

Type:float

Default value: none (no limit)

Example:

code

bodycommoncontrol{bwlimit=>"10M";}

In this example, bwlimit is set to 10MBytes/sec = 80Mbit/s meaning thatCFEngine would only consume up to ~80% of any 100Mbit ethernet interface.

cache_system_functions

Description: Controls the caching of the results of systemfunctions, e.g.execresult() andreturnszero() for shell execution andldapvalue() and friends for LDAP queries. Without this setting,CFEngine's evaluation model will evaluate functions multiple times,which is a performance concern. SeeFunctions.

Although you can override this tofalse, in practice you shouldalmost never need to do so. The effect of having ittrue (thedefault) is that the expensive functions will be run just once andthen their result will be cached.

Note that caching is per-process so results will not be cached betweenruns of e.g.cf-agent andcf-promises.

Type:boolean

Default value: true

Example:

code

cache_system_functions=>"true";

See also:ifelapsed in action bodies

History:- Introduced in version 3.6.0.

domain

Description: Thedomain string specifies the domain name for this host.

There is no standard, universal or reliable way of determining theDNS domain name of a host, so it can be set explicitly to simplifydiscovery and name-lookup.

Type:string

Allowed input range:.*

Example:

code

bodycommoncontrol{domain=>"example.org";}

goal_patterns

Description: Contains regular expressions that match promisees/topicsconsidered to be organizational goals

It is used as identifier to mark business and organizational goals inCFEngine Enterprise. CFEngine uses this to match promisees that representbusiness goals in promises.

Type:slist

Allowed input range: (arbitrary string)

Example:

code

bodycommoncontrol{goal_patterns=>{"goal_.*","target.*"};}

History: Was introduced in version 3.1.5, Nova 2.1.0 (2011)

ignore_missing_bundles

Description: Determines whether to ignore missing bundles.

Ifignore_missing_bundles is set to true, if any bundles in the bundlesequence do not exist, ignore and continue.

Type:boolean

Default value: false

Example:

code

ignore_missing_bundles=>"true";

Notes:

This authorizes the bundlesequence to contain possibly"nonexistent" pluggable modules. It defaults to false, whereuponundefined bundles cause a fatal error in parsing, and a transitionto failsafe mode.

ignore_missing_inputs

Description: If any input files do not exist, ignore and continue

The inputs lists determines which files are parsed by CFEngine.Normally stringent security checks are made on input files toprevent abuse of the system by unauthorized users.

Sometimes however, it is appropriate to consider the automatic plug-in ofmodules that might or might not exist. This option permits CFEngineto list possible files that might not exist and continue 'besteffort' with those that do exist. The default of all Booleans isfalse, so the normal behavior is to signal an error if an input isnot found.

Type:boolean

Default value: false

Example:

code

ignore_missing_inputs=>"true";

inputs

Description: Theinputs slist contains additional filenames to parse for promises.

The filenames specified are all assumed to be in the same directoryas the file which references them (this is usually$(sys.workdir)/inputs, but may be overridden by the-f or--file command line option.

Type:slist

Allowed input range:.*

Example:

code

bodycommoncontrol{inputs=>{"update.cf","library.cf"};}

See also:inputs inbody file control

Notes:

If no filenames are specified, no other filenames will be included in thecompilation process.

Library contents are checked for duplication by path and by hash. Forexample, if you putlibrary.cf twice in yourinputs, the duplicatelibrary.cf is noticed because the same path is included twice. Averbose-level message is emitted but otherwise there is no error.

In addition, if you include a file once with path/x/y/z.cf andagain with path/x/./y/z.cf, the duplicate file will be rejectedregardless of any path tricks or symbolic links. The contents arehashed, so the same file can't be included twice.

lastseenexpireafter

Description: The value oflastseenexpireafter is the number of minutesafter which last-seen entries are purged. It is anenterprise-only feature.

Type:int

Allowed input range:0,99999999999

Default value: One week

Note: This value affects thehostsseen() function and license counting bycf-hub in the Enterprise edition.

Example:

code

bodycommoncontrol{lastseenexpireafter=>"72";}

See also:hostsseen(),cf-hub

output_prefix

Description: The string prefix for standard output

Type:string

Allowed input range: (arbitrary string)

Example:

code

bodycommoncontrol{output_prefix=>"my_cf3";}

Notes:

On native Windows versions of CFEngine (Enterprise), thisstring is also prefixed messages in the event log.

package_inventory

Description: List of package module bodies to query for package lists.

Defines the list ofpackage module bodies which will be queries forpackage lists, for use inpackagematching(),packageupdatesmatching() and inEnterprise inventory reporting.

Type:slist

Allowed input range: (body names)

Example:

code

bodycommoncontrol{package_inventory=>{"apt_get"};}

package_module

Description: The default package module body to use.

Defines the default package module body to use forpackage promises,if none is specified in the promise.

Type:string

Allowed input range: (body name)

Example:

code

bodycommoncontrol{package_module=>"apt_get";}

protocol_version

Description: Defines the protocol to use for all outgoing connections.

Type: (menu option)

Allowed input range:

1
classic
2
tls
3
cookie
latest

Default value: undefined

Note:protocol_version can be specified at the individual promise levelusing thebody copy_from protocol_versionattribute. When undefined (the default) peers automatically negotiate the latest protocol version.

History:

Introduced in CFEngine 3.6.0 withprotocol_version1 (classic) andprotocol_version2 (tls)
Addedprotocol_version3 (cookie) in CFEngine 3.15.0

require_comments

Description: Therequire_comments menu option policy warns aboutpromises that do not have comment documentation.

When true,cf-promises will report loudly on promises that do not havecomments. Variables promises are exempted from this rule, sincethey may be considered self-documenting. This may be used as a policy QualityAssurance measure, to remind policy makers to properly document theirpromises.

Type:boolean

Default value: false

Example:

code

bodycommoncontrol{common::require_comments=>"true";}

site_classes

Description: Asite_classes contains classes that will representgeographical site locations for hosts. These should be defined elsewhere inthe configuration in a classes promise.

This list is used to match against topics when connectinginferences about host locations in the knowledge map. Normally anyCFEngine classes promise whose name is defined as a thing or topicunder classlocations:: will be assumed to be a location definingclassifier. This list will add alternative class contexts forinterpreting location.

Type:slist

Allowed input range:[a-zA-Z0-9_!&@@$|.()\[\]{}:]+

Each string is expected to be a class.

Example:

code

bodycommoncontrol{site_classes=>{"datacenters","datacentres"};# locations is by default}

History: Was introduced in version 3.2.0, Nova 2.1.0 (2011)

syslog_host

Description: Thesyslog_host contains the name or address of ahost to which syslog messages should be sent directly by UDP.

This is the hostname or IP address of a local syslog service to which allCFEngine's components may promise to send data.

Type:string

Allowed input range:[a-zA-Z0-9_$(){}.:-]+

Default value:localhost

Example:

code

bodycommoncontrol{syslog_host=>"syslog.example.org";syslog_port=>"514";}

syslog_port

Description: The value ofsyslog_port represents the port numberof a UDP syslog service.

It is the UDP port of a local syslog service to which all CFEngine'scomponents may promise to send data.

Type:int

Allowed input range:0,99999999999

Default value:514

Example:

code

bodycommoncontrol{syslog_host=>"syslog.example.org";syslog_port=>"514";}

system_log_level

Description: The minimum log level required for log messages to go to the system log (e.g. syslog, Windows Event Log).

Type:string

Allowed Input range:(critical|error|warning|notice|info)

Default value: (unspecified)

Example:

Prevent messages lower thancritical on Windows.

code

bodycommoncontrol{@ifminimum_version(3.18.1)windows::system_log_level=>"critical";cfengine::@endif}

History:

Introduced in 3.19.0, 3.18.1

tls_ciphers

Description: List of ciphers allowed when makingoutgoing connections from components other thancf-serverd.

For a list of possible ciphers, see man page for "openssl ciphers".

Type:string

Allowed input range: (arbitrary string)

Default value: undefined

Example:

code

bodycommoncontrol{# Use one of these ciphers when making outbound connectionstls_ciphers=>"AES128-SHA";}

History: Introduced in CFEngine 3.7.0

tls_min_version

Description: Minimum tls version to allow foroutgoing connections from components other thancf-serverd.

Type:string

Allowed input range: (arbitrary string)

Default value: 1.0

code

bodycommoncontrol{# Allow only TLSv1.1 or higher for outgoing connectionstls_min_version=>"1.1";}

History: Introduced in CFEngine 3.7.0

version

Description: Theversion string contains the scalar version of theconfiguration.

It is is used in error messages and reports.

Type:string

Allowed input range: (arbitrary string)

This string should not contain the colon ':' character, as this hasa special meaning in the context of knowledge management. Thisrestriction might be lifted later.

Example:

code

bodycommoncontrol{version=>"1.2.3";}

Deprecated attributes in body common control

The following attributes were functional in previous versionsof CFEngine, but today they are deprecated, either becausetheir functionality is being handled trasparently or becauseit doesn't apply to current CFEngine version.