Functions
Functions take zero or more values as arguments and return a value.
Argument values need to be of the type and range as documented for each
function. Some functions are documented with a ...
, in which case they
take an arbitrary amount of arguments.
They can return scalar and list values:
vars:
"random" int => randomint("0", "100");
"list" slist => readstringlist("/tmp/listofstring", "#.*", "\s", 10, 400);
In addition, functions with return type boolean
evaluate to true
or
false
. The class on the left-hand side is set if the function evaluates to
true. If the function evaluates to false, then the class remains unchanged.
bundle agent test
{
vars:
"five" int => "5";
"seven" " int => "7";
classes:
"ok" expression => islessthan("$(five)","$(seven)");
reports:
ok::
"$(five) is smaller than $(seven)";
!ok::
"$(seven) is smaller than $(five)";
}
Underneath, CFEngine functions that return boolean
will actually
return a context expression like any
or !any
which will then be
deemed true or false by the CFEngine evaluator. Note the truth of a
context expression or the result of a function call may change during
evaluation, but a class, once defined, will stay defined.
Functions that return a boolean
can thus sometimes be used in places
where a string is accepted as well, but this behavior is not clearly
defined or supported. Use at your own discretion.
Function caching
During convergence, CFEngine's evaluation model will evaluate functions multiple times, which can be a performance concern.
Some system functions are particularly expensive:
execresult()
andreturnszero()
for shell executionregldap()
,ldapvalue()
, andldaplist()
for LDAP querieshost2ip()
andip2host()
for DNS queriesreadtcp()
for TCP interactionshubknowledge()
, andremotescalar()
for hub queries
When enabled cached functions are not executed on every pass of convergence. Instead, the function will only be executed once during the agent evaluation step and its result will be cached until the end of that agent execution.
Note: Function caching is per-process, so results will not be cached between
separate components e.g. cf-agent
, cf-serverd
and cf-promises
.
Additionally functions are cached by hashing the function arguments. If you have
the exact same function call in two different promises (it does not matter if
they are in the same bundle or not) only the first executed function will be
cached. That cached result will be re-used for other identical function
occurrences.
Function caching can be disabled by setting cache_system_functions
in body
common control to false
.
Function Skipping
If a variable passed to a function is unable to be resolved the function will be skipped. The function will be evaluated during a later pass when all variables passed as arguments are able to be resolved. The function will never be evaluated if any argument contains a variable that never resolves.
List of all functions
There are a large number of functions built into CFEngine. The following tables might make it easier for you to find the function you need.