Appendix C. CFEngine 3.5.2 Agent Promise Attributes

Aleksey Tsalolikhin

hello@verticalsysadmin.com

CFEngine is designed to be comprehensive and to let you model nearly any aspect of system configuration. There are tens of promise types and hundreds of unique promise attributes to enable modeling the desired configuration. The purpose of this Appendix is to facilitate learning and to serve as reference.

To make this sea of options navigable, this Appendix lists the promise types and attributes affecting the agent (the part of CFEngine that actually makes changes to your system) in a short format (name and synopsis only).

For full details, please consult the Promise Types and Attributes section of the CFEngine documentation.

Don’t let the complexity of hundreds of promise attributes scare you—CFEngine 3 is designed to address the challenges of Knowledge Management, including complexity, and allows you to summarize and abstract the underlying details, to the extent of Webserver("on") to configure a web server.

But if you need to configure your web server a special way, the below details will enable you to do so. Have fun getting under the hood of your system configuration and getting greasy to the elbows!

Attributes of Promises Common to All CFEngine Components

Attributes of “classes” Promises

scope	Scope of the class set by this promise (namespace or bundle).
and	Combine class sources with AND
dist	Generate a probabilistic class distribution (from strategies in cfengine 2)
expression	Evaluate string expression of classes in normal form
or	Combine class sources with inclusive OR
persistence	Make the class persistent (cached) to avoid reevaluation, time in minutes
not	Evaluate the negation of string expression in normal form
select_class	Select one of the named list of classes to define based on host identity
xor	Combine class sources with XOR

Attributes of “defaults” Promises

if_match_regex	If this regular expression matches the current value of the variable, replace it with default
string	A scalar string
slist	A list of scalar strings

Attributes of “meta” Promises

slist

A list of scalar strings

Attributes of “reports” Promises

friend_pattern		Regular expression to keep selected hosts from the friends report list
intermittency		Real number threshold [0,1] of intermittency about current peers, report above
lastseen		Integer time threshold in hours since current peers were last seen, report absence
printfile	file_to_print	Path name to the file that is to be sent to standard output
	number_of_lines	Integer maximum number of lines to print from selected file*)
report_to_file		The path and filename to which output should be appended
bundle_return_value_index		The promiser is to be interpreted as a phrase value that the caller can accept as a result for this bundle; in other words, a return value with array index defined by this attribute.
showstate		List of services about which status reports should be reported to standard output

Attributes of “vars” Promises

string	A scalar string
int	A scalar integer
real	A scalar real number
slist	A list of scalar strings
ilist	A list of integers
rlist	A list of real numbers
policy	The policy for (dis)allowing (re)definition of variables

Attributes that Can Be Used in Any Promise

action	action_policy	Whether to repair or report about non-kept promises
	audit	True/false switch for detailed audit records of this promise
	background	True/false switch for parallelizing the promise repair
	expireafter	Number of minutes before a repair action is interrupted and retried
	ifelapsed	Number of minutes before next allowed assessment of promise
	logstring	A message to be written to the log when a promise verification leads to a repair
	log_level	The reporting level sent to syslog
	log_kept	This should be filename of a file to which log_string will be saved, if undefined it goes to the system logger
	log_priority	The priority level of the log message, as interpreted by a syslog server
	log_repaired	This should be filename of a file to which log_string will be saved, if undefined it goes to the system logger
	log_failed	This should be filename of a file to which log_string will be saved, if undefined it goes to the system logger
	measurement_class	If set performance will be measured and recorded under this identifier
	report_level	The reporting level for standard output for this promise
	value_kept	A real number value attributed to keeping this promise
	value_repaired	A real number value attributed to reparing this promise
	value_notkept	A real number value (possibly negative) attributed to not keeping this promise
classes	scope	Scope of the class set by this promise (namespace or bundle).
	promise_repaired	A list of classes to be defined globally
	repair_failed	A list of classes to be defined globally
	repair_denied	A list of classes to be defined globally
	repair_timeout	A list of classes to be defined globally
	promise_kept	A list of classes to be defined globally
	cancel_kept	A list of classes to be cancelled if the promise is kept
	cancel_repaired	A list of classes to be cancelled if the promise is repaired
	cancel_notkept	A list of classes to be cancelled if the promise is not kept for any reason
	kept_returncodes	A list of return codes indicating a kept command-related promise
	repaired_returncodes	A list of return codes indicating a repaired command-related promise
	failed_returncodes	A list of return codes indicating a failed command-related promise
	persist_time	A number of minutes the specified classes should remain active
	timer_policy	Whether a persistent class restarts its counter when rediscovered
comment		A comment about this promise’s real intention that follows through the program
depends_on		A list of promise handles that this promise builds on or depends on somehow (for knowledge management)
handle		A unique id-tag string for referring to this as a promisee elsewhere
ifvarclass		Extended classes ANDed with context
meta		Promise meta-data, e.g. author, revision date, version, etc.

Attributes of Promises Specific to the Agent

Attributes of “commands” Promises

args		Alternative string of arguments for the command (concatenated with promiser string)
contain	useshell	true/false embed the command in a shell environment
	umask	The umask value for the child process
	exec_owner	The user name or id under which to run the process
	exec_group	The group name or id under which to run the process
	exec_timeout	Timeout in seconds for command completion
	chdir	Directory for setting current/base directory for the process
	chroot	Directory of root sandbox for process
	preview	true/false preview command when running in dry-run mode (with -n)
	no_output	true/false discard all output from the command

Attributes of “databases” Promises

database_server	db_server_owner	User name for database connection
	db_server_password	Clear text password for database connection
	db_server_host	Hostname or address for connection to database, blank means localhost
	db_server_type	The dialect of the database server
	db_server_connection_db	The name of an existing database to connect to in order to create/manage other databases
database_type		The type of database that is to be manipulated
database_operation		The nature of the promise - to be or not to be
database_columns		A list of column definitions to be promised by SQL databases
database_rows		An ordered list of row values to be promised by SQL databases
registry_exclude		A list of regular expressions to ignore in key/value verification

Attributes of “guest_environments” Promises

environment_host		A class indicating which physical node will execute this guest machine
environment_interface	env_addresses	The IP addresses of the environment’s network interfaces
	env_name	The hostname of the virtual environment
	env_network	The hostname of the virtual network
environment_resources	env_cpus	Number of virtual CPUs in the environment
	env_memory	Amount of primary storage (RAM) in the virtual environment (KB)
	env_disk	Amount of secondary storage (DISK) in the virtual environment (MB)
	env_baseline	The path to an image with which to baseline the virtual environment
	env_spec	A string containing a technology specific set of promises for the virtual instance
environment_state		The desired dynamical state of the specified environment
environment_type		Virtual environment type

Attributes of “files” Promises

acl	aces	Native settings for access control entry
	acl_directory_inherit	Access control list type for the affected file system
	acl_default	The access control list type for the affected file system is determined by acl_default.
	acl_method	Editing method for access control list
	acl_type	Access control list type for the affected file system
	specify_inherit_aces	Native settings for access control entry
	specify_default_aces	The slist specify_default_aces specifies the native settings for access control entry.
	acl_inherit	Controls inheritance behavior on Windows.
changes	hash	Hash files for change detection
	report_change	Specify criteria for change warnings
	update_hashes	Update hash values immediately after change warning
	report_diffs	Generate reports summarizing the major differences between individual text files
copy_from	source	Reference source file from which to copy
	servers	List of servers in order of preference from which to copy
	collapse_destination_dir	true/false Place files in subdirectories into the root destination directory during copy
	compare	Menu option policy for comparing source and image file attributes
	copy_backup	Menu option policy for file backup/version control
	encrypt	true/false use encrypted data stream to connect to remote host
	check_root	true/false check permissions on the root directory when depth_search
	copylink_pattern	List of patterns matching files that should be copied instead of linked
	copy_size	Integer range of file sizes that may be copied
	findertype	Menu option for default finder type on MacOSX
	linkcopy_patterns	List of patterns matching files that should be replaced with symbolic links
	link_type	Menu option for type of links to use when copying
	force_update	true/false force copy update always
	force_ipv4	true/false force use of ipv4 on ipv6 enabled network
	portnumber	Port number to connect to on server host
	preserve	true/false whether to preserve file permissions on copied file
	purge	true/false purge files on client that do not match files on server when a depth_search is used
	stealth	true/false whether to preserve time stamps on copied file
	timeout	Connection timeout, seconds
	trustkey	true/false trust public keys from remote server if previously unknown
	type_check	true/false compare file types before copying and require match
	verify	true/false verify transferred file by hashing after copy (resource penalty)
create		true/false whether to create non-existing file
delete	dirlinks	Menu option policy for dealing with symbolic links to directories during deletion
	rmdirs	true/false whether to delete empty directories during recursive deletion
depth_search	depth	Maximum depth level for search
	exclude_dirs	List of regexes of directory names NOT to include in depth search
	include_basedir	true/false include the start/root dir of the search results
	include_dirs	List of regexes of directory names to include in depth search
	rmdeadlinks	true/false remove links that point to nowhere
	traverse_links	true/false traverse symbolic links to directories
	xdev	true/false exclude directories that are on different devices
edit_defaults	edit_backup	Menu option for backup policy on edit changes
	empty_file_before_editing	Baseline memory model of file to zero/empty before commencing promised edits
	inherit	If true this causes the sub-bundle to inherit the private classes of its parent
	max_file_size	Do not edit files bigger than this number of bytes
	recognize_join	Join together lines that end with a backslash, up to 4kB limit
	rotate	How many backups to store if rotate edit_backup strategy is selected. Defaults to 1.
edit_line		Specifies name of edit_line bundle
edit_template		The name of a special CFEngine template file to expand
edit_xml		Specifies name of edit_xml bundle
file_select	leaf_name	List of regexes that match an acceptable name
	path_name	List of pathnames to match acceptable target
	search_mode	A list of mode masks for acceptable file permissions
	search_size	Integer range of file sizes
	search_owners	List of acceptable user names or ids for the file, or regexes to match
	search_groups	List of acceptable group names or ids for the file, or regexes to match
	search_bsdflags	String of flags for bsd file system flags expected set
	ctime	Range of change times (ctime) for acceptable files
	mtime	Range of modification times (mtime) for acceptable files
	atime	Range of access times (atime) for acceptable files
	exec_regex	Matches file if this regular expression matches any full line returned by the command
	exec_program	Execute this command on each file and match if the exit status is zero
	file_types	List of acceptable file types from menu choices
	issymlinkto	List of regular expressions to match file objects
	file_result	Logical expression combining classes defined by file search criteria
link_from	copy_patterns	A set of patterns that should be copied and synchronized instead of linked
	link_children	true/false whether to link all directory’s children to source originals
	link_type	The type of link used to alias the file
	source	The source file to which the link should point
	when_linking_children	Policy for overriding existing files when linking directories of children
	when_no_source	Behaviour when the source file to link to does not exist
move_obstructions		true/false whether to move obstructions to file-object creation
pathtype		Menu option for interpreting promiser file object
perms	bsdflags	List of menu options for bsd file system flags to set
	groups	List of acceptable groups of group ids, first is change target
	mode	File permissions (like posix chmod)
	owners	List of acceptable owners or user ids, first is change target
	rxdirs	true/false add execute flag for directories if read flag is set
rename	disable	true/false automatically rename and remove permissions
	disable_mode	The permissions to set when a file is disabled
	disable_suffix	The suffix to add to files when disabling (.cfdisabled)
	newname	The desired name for the current file
	rotate	Maximum number of file rotations to keep
repository		Name of a repository for versioning
touch		true/false whether to touch time stamps on file
transformer		Command (with full path) used to transform current file (no shell wrapper used)

Attributes of Promises in edit_line Bundles

Attributes of Any Promises in edit_line Bundles

select_region		Restrict edit_line promise to a specific region of a file.
select_region	include_start_delimiter	Whether to include the section delimiter
	include_end_delimiter	Whether to include the section delimiter
	select_start	Regular expression matching start of edit region
	select_end	Regular expression matches end of edit region from start

Attributes of “delete_lines” promises in edit_line bundles

delete_select	delete_if_startwith_from_list	Delete line if it starts with a string in the list
	delete_if_not_startwith_from_list	Delete line if it DOES NOT start with a string in the list
	delete_if_match_from_list	Delete line if it fully matches a regex in the list
	delete_if_not_match_from_list	Delete line if it DOES NOT fully match a regex in the list
	delete_if_contains_from_list	Delete line if a regex in the list match a line fragment
	delete_if_not_contains_from_list	Delete line if a regex in the list DOES NOT match a line fragment
not_matching		true/false negate match criterion

Attributes of “insert_lines” Promises in edit_line Bundles

expand_scalars		Expand any unexpanded variables
insert_type		Type of object the promiser string refers to
insert_select	insert_if_startwith_from_list	Insert line if it starts with a string in the list
	insert_if_not_startwith_from_list	Insert line if it DOES NOT start with a string in the list
	insert_if_match_from_list	Insert line if it fully matches a regex in the list
	insert_if_not_match_from_list	Insert line if it DOES NOT fully match a regex in the list
	insert_if_contains_from_list	Insert line if a regex in the list match a line fragment
	insert_if_not_contains_from_list	Insert line if a regex in the list DOES NOT match a line fragment
location	before_after	Menu option, point cursor before of after matched line
	first_last	Menu option, choose first or last occurrence of match in file
	select_line_matching	Regular expression for matching file line location
whitespace_policy		Criteria for matching and recognizing existing lines

Attributes of “field_edits” Promises in edit_line Bundles

edit_field	allow_blank_fields	true/false allow blank fields in a line (do not purge)
	extend_fields	true/false add new fields at end of line if necessary to complete edit
	field_operation	Menu option policy for editing subfields
	field_separator	The regular expression used to separate fields in a line
	field_value	Set field value to a fixed value
	select_field	Integer index of the field required 0..n (default starts from 1)
	start_fields_from_zero	If set, the default field numbering starts from 0
	value_separator	Character separator for subfields inside the selected field

Attributes of “replace_patterns” Promises in edit_line Bundles

replace_with	occurrences	Menu option to replace all occurrences or just first (NB the latter is non-convergent)
	replace_value	Value used to replace regular expression matches in search

Attributes of Promises in edit_xml Bundles

Attributes of any promises in edit_xml bundles

build_xpath	Build an XPath within the XML file
select_xpath	Select the XPath node in the XML file to edit

Attributes of “build_xpath” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “delete_tree” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “insert_tree” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “delete_attribute” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “set_attribute” Promises in edit_xml Bundles

attribute_value

Value of the attribute to be inserted into the XPath node of the XML file

Attributes of “delete_text” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “set_text” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “insert_text” Promises in edit_xml Bundles

This promise type does not have any attributes.

Attributes of “methods” Promises

inherit	If true this causes the sub-bundle to inherit the private classes of its parent
usebundle	Take on and evaluate the specified bundle of promises.
useresult	Specify the name of a local variable to contain any result/return value from the child.

Attributes of “packages” Promises

package_architectures		Select the architecture for package selection
package_method	package_add_command	Command to install a package to the system
	package_arch_regex	Regular expression with one backreference to extract package architecture string
	package_changes	Menu option - whether to group packages into a single aggregate command
	package_delete_command	Command to remove a package from the system
	package_delete_convention	This is how the package manager expects the package to be referred to in the deletion part of a package update, e.g. $(name)
	package_file_repositories	A list of machine-local directories to search for packages
	package_installed_regex	Regular expression which matches packages that are already installed
	package_default_arch_command	Command to detect the default packages’ architecture
	package_list_arch_regex	Regular expression with one backreference to extract
	package_list_command	Command to obtain a list of available packages
	package_list_name_regex	Regular expression with one backreference to extract package name string
	package_list_update_command	Command to update the list of available packages (if any)
	package_list_update_ifelapsed	The ifelapsed locking time in between updates of the package list
	package_list_version_regex	Regular expression with one backreference to extract package version string
	package_name_convention	This is how the package manager expects the package to be referred to, e.g. $(name).$(arch)
	package_name_regex	Regular expression with one backreference to extract package name string
	package_noverify_regex	Regular expression to match verification failure output
	package_noverify_returncode	Integer return code indicating package verification failure
	package_patch_arch_regex	Regular expression with one backreference to extract update architecture string
	package_patch_command	Command to update to the latest patch release of an installed package
	package_patch_installed_regex	Regular expression which matches packages that are already installed
	package_patch_list_command	Command to obtain a list of available patches or updates
	package_patch_name_regex	Regular expression with one backreference to extract update name string
	package_patch_version_regex	Regular expression with one backreference to extract update version string
	package_update_command	Command to update to the latest version a currently installed package
	package_verify_command	Command to verify the correctness of an installed package
	package_version_regex	Regular expression with one backreference to extract package version string
	package_multiline_start	Regular expression which matches the start of a new package in multiline output
	package_commands_useshell	Whether to use shell for commands in this body
	package_version_less_command	Command to check whether first supplied package version is less than second one
	package_version_equal_command	Command to check whether first supplied package version is equal to second one
package_policy		Criteria for package installation/upgrade on the current system
package_select		A criterion for first acceptable match relative to “package_version”
package_version		Version reference point for determining promised version

Attributes of “processes” Promises

process_count	in_range_define	List of classes to define if the matches are in range
	match_range	Integer range for acceptable number of matches for this process
	out_of_range_define	List of classes to define if the matches are out of range
process_select	command	Regular expression matching the command/cmd field of a process
	pid	Range of integers matching the process id of a process
	pgid	Range of integers matching the parent group id of a process
	ppid	Range of integers matching the parent process id of a process
	priority	Range of integers matching the priority field (PRI/NI) of a process
	process_owner	List of regexes matching the user of a process
	process_result	Boolean class expression returning the logical combination of classes set by a process selection test
	rsize	Range of integers matching the resident memory size of a process, in kilobytes
	stime_range	Range of integers matching the start time of a process
	ttime_range	Range of integers matching the total elapsed time of a process
	tty	Regular expression matching the tty field of a process
	threads	Range of integers matching the threads (NLWP) field of a process
	vsize	Range of integers matching the virtual memory size of a process, in kilobytes
process_stop		A command used to stop a running process
restart_class		A class to be defined globally if the process is not running, so that a command: rule can be referred to restart the process
signals		A list of menu options representing signals to be sent to a process

Attributes of “services” Promises

service_policy		Policy for cfengine service status
service_dependencies		A list of services on which the named service abstraction depends
service_method	service_args	Parameters for starting the service as command
	service_autostart_policy	Should the service be started automatically by the OS
	service_bundle	Name of a bundle describing how to handle a service
	service_type	Service abstraction type
	service_dependence_chain	Menu option for specifying how to handle dependencies and dependent services

Attributes of “storage” Promises

mount	edit_fstab	true/false add or remove entries to the file system table (“fstab”)
	mount_type	Protocol type of remote file system
	mount_source	Path of remote file system to mount
	mount_server	Hostname or IP or remote file system server
	mount_options	List of option strings to add to the file system table (“fstab”)
	unmount	true/false unmount a previously mounted filesystem
volume	check_foreign	true/false verify storage that is mounted from a foreign system on this host
	freespace	Absolute or percentage minimum disk space that should be available before warning
	sensible_size	Minimum size in bytes that should be used on a sensible-looking storage device
	sensible_count	Minimum number of files that should be defined on a sensible-looking storage device
	scan_arrivals	true/false generate pseudo-periodic disk change arrival distribution

Control

Control promise attributes supplement the built-in “control” promises. Control promises affect the runtime behavior of CFEngine.

Common Control

Control attributes of type “common” apply to all parts of CFEngine, e.g. monitor, server, executor, agent, etc. We include them here because they can affect the agent.

bundlesequence	Contains promise bundles to verify, in a specific order.
goal_patterns	Contains regular expressions that match promisees/topics considered to be organizational goals.
ignore_missing_bundles	Determines whether to ignore missing bundles.
ignore_missing_inputs	If any input files do not exist, ignore and continue.
inputs	The inputs slist contains additional filenames to parse for promises.
version	The version string contains the scalar version identifier of the configuration.
lastseenexpireafter	Number of minutes after which last-seen entries are purged.
output_prefix	The string prefix for standard output.
domain	The domain string specifies the domain name for this host.
require_comments	The require_comments menu option policy warns about promises that do not have comment documentation.
site_classes	A site_classes contains classes that will represent geographical site locations for hosts. These should be defined elsewhere in the configuration in a classes promise.
syslog_host	The syslog_host contains the name or address of a host to which syslog messages should be sent directly by UDP.
syslog_port	The value of syslog_port represents the port number of a UDP syslog service.
fips_mode	The fips_mode menu option policy determines whether to activate full FIPS mode restrictions.

Agent Control

Agent control promise attributes apply to the agent control promise which affects the behavior of the agent only.

abortclasses	A list of classes which if defined lead to termination of cf-agent
abortbundleclasses	A list of classes which if defined lead to termination of current bundle
addclasses	A list of classes to be defined always in the current context
agentaccess	A list of user names allowed to execute cf-agent
agentfacility	The syslog facility for cf-agent
allclassesreport	Generate allclasses.txt report
alwaysvalidate	true/false flag to determine whether configurations will always be checked before executing, or only after updates
bindtointerface	Use this interface for outgoing connections
hashupdates	true/false whether stored hashes are updated when change is detected in source
childlibpath	LD_LIBRARY_PATH for child processes
checksum_alert_time	The persistence time for the checksum_alert class
defaultcopytype	ctime or mtime differ
dryrun	All talk and no action mode
editbinaryfilesize	Integer limit on maximum binary file size to be edited
editfilesize	Integer limit on maximum text file size to be edited
environment	List of environment variables to be inherited by children
expireafter	Global default for time before on-going promise repairs are interrupted
files_single_copy	List of filenames to be watched for multiple-source conflicts
files_auto_define	List of filenames to define classes if copied
hostnamekeys	true/false label ppkeys by hostname not IP address
ifelapsed	Global default for time that must elapse before promise will be rechecked
inform	true/false set inform level default
intermittency	This option is deprecated, does nothing and is kept for backward compatibility
max_children	Maximum number of background tasks that should be allowed concurrently
maxconnections	Maximum number of outgoing connections to cf-serverd
mountfilesystems	true/false mount any filesystems promised
nonalphanumfiles	true/false warn about filenames with no alphanumeric content
repchar	The character used to canonize pathnames in the file repository
refresh_processes	Reload the process table before verifying the bundles named in this list (lazy evaluation)
default_repository	Path to the default file repository
secureinput	true/false check whether input files are writable by unauthorized users
sensiblecount	Minimum number of files a mounted filesystem is expected to have
sensiblesize	Minimum number of bytes a mounted filesystem is expected to have
skipidentify	Do not send IP/name during server connection because address resolution is broken
suspiciousnames	List of names to warn about if found during any file search
track_value	true/false switches on tracking of promise valuation
timezone	List of allowed timezones this machine must comply with
default_timeout	Maximum time a network connection should attempt to connect
verbose	true/false switches on verbose standard output

File Control

namespace

Switch to a private namespace to protect current file from duplicate definitions