An augments file can be used to define variables and classes to the execution of all CFEngine components before any parsing or evaluation happen. It’s a JSON data file, so you should view and edit it with a JSON-aware editor if possible.This is a convenient way to override defaults defined in the Masterfiles Policy Framework without modifying the shipped policy itself.
The file def.json
is found like the policy file to be run:
$(sys.inputdir)/def.json
because
$(sys.inputdir)/promises.cf
is used-f /dirname/myfile.cf
, it’s in /dirname/def.json
-f ./myfile.cf
, it’s in ./def.json
Values will be expanded, so you can use the variables from [Special Variables][].
An augments file can contain the following keys:
Any filenames you put here will appear in the def.augments_inputs
variable.
The standard set of masterfiles refers to this variable and will autoload those
files.
Any variables you put here will be put in the def
bundle scope. Thus:
"vars":
{
"phone": "22-333-4444",
"myplatform": "$(sys.os)",
}
results in the variable def.phone
with value 22-333-4444
being defined, and
def.myplatform
with the value of your current OS. Again, note that this
happens before policy is parsed or evaluated.
You can see the list of variables thus defined in the output of cf-promises
--show-vars
(see [Components and Common Control][]). They will be tagged with
the tag source=augments_file
. For instance, the above two variables (assuming
you placed the data in $(sys.inputdir)/def.json
) result in
cf-promises --show-vars=default:def
...
default:def.myplatform linux source=augments_file
default:def.phone 22-333-4444 source=augments_file
Variables of other types than string can be defined too, like in this example
"vars" : {
"str1" : "string 1",
"num1" : 5,
"num2" : 3.5
"slist1" : ["sliststr1", "sliststr2"]
"array1" : {
"idx1" : "val1",
"idx2" : "val2"
}
}
Any class defined via augments will be evaluated and installed as
[hard classes][Classes and Decisions]. Each element
of the array is tested against currently defined classes
as an [anchored regular expression][anchored] unless the string ends with ::
indicating it should be interpreted as a
[class expression][Classes and Decisions].
Note that augments is processed at the very beginning of agent evaluation. You can use any hard classes, [persistent classes][Classes and Decisions] , or classes defined earlier in the augments list. Test carefully, custom [soft classes][Classes and Decisions] may not be defined early enough for use. Thus:
"classes":
{
"augments_class_from_regex_my_always": [ "any" ],
"augments_class_from_regex_my_other_apache": [ "server[34]", "debian.*" ],
"augments_class_from_regex_my_other_always": [ "augments_class_from_regex_my_always" ],
"augments_class_from_regex_when_MISSING_not_defined": [ "^(?!MISSING).*" ]
"augments_class_from_regex": [ "cfengine_\\d+" ],
"augments_class_from_single_class_as_regex": [ "cfengine" ],
"augments_class_from_single_class_as_expression": [ "cfengine::" ],
"augments_class_from_classexpression_and": [ "cfengine.cfengine_3::" ],
"augments_class_from_classexpression_not": [ "!MISSING::" ],
"augments_class_from_classexpression_or": [ "cfengine|cfengine_3::" ],
"augments_class_from_classexpression_complex": [ "(cfengine|cfengine_3).!MISSING::" ]
}
results in
augments_class_from_rgex_my_always
being always defined.
augments_class_from_regex_my_other_apache
will be defined if the classes
server3
or server4
are defined, or if any class starting with debian
is
defined.
augments_class_from_regex_my_other_always
will be defined because
augments_class_from_regex_my_always
is listed first and always defined.
augments_class_from_regex_when_MISSING_not_defined
will be defined if the
class MISSING
is not defined.
augments_class_from_single_class_as_regex
will be defined because the class
cfengine
is always defined.
augments_class_from_single_class_as_expression
will be defined because
cfengine
is defined when interpreted as a class expression.
augments_class_from_classexpression_and
will be defined because the class
cfengine
and the class cfengine_3
are defined and the class expression
cfengine.cfengine_3::
evaluates to true.
augments_class_from_classexpression_not
will be defined because the class
expression !MISSING::
evaluates to false since the class MISSING
is not
defined.
augments_class_from_classexpression_or
will be defined because the class
expression cfengine|cfengine_3::
evaluates to true since at least one of
cfengine
or cfengine_3
will always be defined by cfengine 3 agents.
augments_class_from_classexpression_complex
will be defined because the
class expression (cfengine|cfengine_3).!MISSING::
evaluates to true since at
least one of cfengine
or cfengine_3
will always be defined by cfengine 3
agents and MISSING
is not defined.
You can see the list of classes thus defined through def.json
in the output
of cf-promises --show-classes
(see [Components and Common Control][]). They
will be tagged with the tags source=augments_file,hardclass
. For instance:
% cf-promises --show-classes=my_
...
augments_class_from_regex_my_always source=augments_file,hardclass
augments_class_from_regex_my_other_always source=augments_file,hardclass
augments_class_from_regex_my_other_apache source=augments_file,hardclass
See also:
classesmatching()
,
classmatch()
, countclassesmatching()
A list of file names that should be merged using mergedata()
semantic
Example:
Here we merge a platform specific augments on to the def.json
loaded next to
the policy entry and see what the resulting variable values will
be.
The def.json
next to the policy entry:
{
"vars":{
"my_var": "defined in def.json",
"my_other_var": "Defined ONLY in def.json"
},
"augments": [
"/var/cfengine/augments/$(sys.flavor).json"
]
}
The platform specific augments on a CentOS 6 host:
/var/cfengine/augments/centos_6.json
:
{
"vars": {
"my_var": "Overridden in centos_6.json",
"centos_6_var": "Defined ONLY in centos_6.json"
}
}
The expected values of the variables defined in the def bundle scope:
R: def.my_var == Overridden in centos_6.json
R: def.my_other_var == Defined ONLY in def.json
R: def.centos_6_var == Defined ONLY in centos_6.json
::
suffix) to classes keyaugments
keydef.json
parsing in core agent and load def.json
if present next to policy entryinputs
key, load def.json
if present next to policy entrydef.json
parsing moved from policy to core agent for resolution of classes and variables to be able to affect control bodies