Namespaces

Table of contents

By default all promises are made in thedefault namespace. Specifying a namespaceplaces the bundle or body in a different namespace to allow re-use of commonnames. Using namespaces makes it easier to share and consume policy from otherauthors.

Like bundle names and classes, namespaces may only contain alphanumeric andunderscore characters (a-zA-Z0-9_).

Declaration

Namespaces are declared withbody file control. Anamespace applies within a single file to all subsequently defined bodies and bundlesfollowing the namespace declaration until a different namespace has beendeclared or until the end of the file.

code

bundleagent__main__{methods:"Main in my_namespace namespace"usebundle=>my_namespace:main;"Main in your_namespace namespace"usebundle=>your_namespace:main;"my_bundle in default namespace"usebundle=>my_bundle;reports:"Inside$(this.namespace):$(this.bundle)";}bodyfilecontrol{namespace=>"my_namespace";}bundleagentmain{reports:"Inside$(this.namespace):$(this.bundle)";}bodyfilecontrol{namespace=>"your_namespace";}bundleagentmain{reports:"Inside$(this.namespace):$(this.bundle)";}bodyfilecontrol{namespace=>"default";}bundleagentmy_bundle{reports:"Inside$(this.namespace):$(this.bundle)";}

code

R: Inside my_namespace:mainR: Inside your_namespace:mainR: Inside default:my_bundleR: Inside default:main

This policy can be found in/var/cfengine/share/doc/examples/namespace_declaration.cfand downloaded directly fromgithub.

Notes:

Multiple namespaces can be declared within the same file
The same namespace can be declared in multiple files
The same namespace can be declared in the same file multiple times

Methods|usebundle

Methods promises assume you are referring to a bundle in the same namespace asthe promiser. To refer to a bundle in another namespace youmust specify thenamespace by prefixing the bundle name with the namespace followed by a colon(:).

code

bundleagent__main__{methods:# Call the bundle named main within the example_space namespace."example_space:main";}bodyfilecontrol{namespace=>"example_space";}bundleagentmain{methods:# Call the bundle 'my_bundle' within the current namespace"When not specified, we assume you are refering to a bundle or body within the same namespace"usebundle=>my_bundle("Called 'my_bundle' from$(this.namespace):$(this.bundle) (the same namespace).");# Call the bundle 'my_bundle' from the 'example_space' namespace"When explicitly specified, the policy reader has less congnitive burden"usebundle=>example_space:my_bundle("Called 'example_space:my_bundle'$(this.namespace):$(this.bundle) (the same namespace).");}bundleagentmy_bundle(string){reports:"In$(this.namespace):$(this.bundle)"handle=>"$(string)";"$(string)";}

code

R: In example_space:my_bundleR: Called 'my_bundle' from example_space:main (the same namespace).R: In example_space:my_bundleR: Called 'example_space:my_bundle' example_space:main (the same namespace).

This policy can be found in/var/cfengine/share/doc/examples/namespace_methods-usebundle.cfand downloaded directly fromgithub.

Bodies

Bodies are assumed to be within the same namespace as the promiser. To use a body from another namespace the namespace must be specified by prefixing the body name with the namespace followed by a colon (:).

A common mistake is forgetting to specifydefault: when using bodies from the standard library which resides in thedefault namespace.

code

bundleagent__main__{methods:"example_space:main";}bodyfilecontrol{namespace=>"example_space";}bundleagentmain{reports:# Use the 'first_line' printfile body from the current namespace"Specifying a body without explict namespace assumes the same namespace.$(const.n)Show me the first 1 line of this file"printfile=>first_line($(this.promise_filename));# Use the 'first_two_lines' printfile body from the 'default' namespace"Forgetting to prefix bodies with 'default:' is a common mistake when using the standard library.$(const.n)Show me the first 2 line of this file"printfile=>default:first_two_lines($(this.promise_filename));}bodyprintfilefirst_line(file){file_to_print=>"$(file)";number_of_lines=>"1";}bodyfilecontrol{namespace=>"default";}bodyprintfilefirst_two_lines(file){file_to_print=>"$(file)";number_of_lines=>"2";}

code

R: Specifying a body without explict namespace assumes the same namespace.Show me the first 1 line of this fileR: bundle agent __main__R: Forgetting to prefix bodies with 'default:' is a common mistake when using the standard library.Show me the first 2 line of this fileR: bundle agent __main__R: {

This policy can be found in/var/cfengine/share/doc/examples/namespace_bodies.cfand downloaded directly fromgithub.

Variables

Variables (except forSpecial variables) are assumed to be within the same scopeas the promiser but can also be referenced fully qualified with the namespace.

code

bundleagent__main__{methods:"example:demo";}bodyfilecontrol{namespace=>"example";}bundleagentdemo{vars:"color"string=>"#f5821f";reports:"Unqualified: The color is$(color)";# ENT-8817 "Bundle-qualified: The color is $(demo.color)";"Fully-qualified: The color is$(example:demo.color)";}

code

R: Unqualified: The color is #f5821fR: Fully-qualified: The color is #f5821f

This policy can be found in/var/cfengine/share/doc/examples/namespace_variable_references.cfand downloaded directly fromgithub.

Special variables are always accessible without a namespace prefix. For example,this,mon,sys, andconst fall in this category.

code

bundleagent__main__{methods:"special_variables_example:demo";}bodyfilecontrol{namespace=>"special_variables_example";}bundleagentdemo{reports:"Special Variables live in the default namespace but don't have to be fully qualified when referenced ...";"In$(this.namespace):$(this.bundle)$(const.dollar)(sys.cf_version_major) ==$(sys.cf_version_major)";"In$(this.namespace):$(this.bundle)$(default:const.dollar)(default:sys.cf_version_major) ==$(default:sys.cf_version_major)";}

code

R: Special Variables live in the default namespace but don't have to be fully qualified when referenced ...R: In special_variables_example:demo $(sys.cf_version_major) == 3R: In special_variables_example:demo $(default:sys.cf_version_major) == 3

This policy can be found in/var/cfengine/share/doc/examples/namespace_special_var_exception.cfand downloaded directly fromgithub.

Notes:

Thevariables Augments key defines variables in themain bundle of thedata namespace by default but supports seeding variablevalues in any specified namespace.

Classes

Promises can only define classes within the current namespace. Classes areunderstood to refer to classes in the current namespace if a namespace is notspecified (except for Hard classes). To refer to aclass in a different namespace prefix the class with the namespace suffixed by acolon (:).

code

bundleagent__main__{methods:"mynamespace:my_bundle";reports:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'a_bundle_scoped_class_in_my_namespaced_bundle::'";!a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'a_bundle_scoped_class_in_my_namespaced_bundle::'";a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'a_namespace_scoped_class_in_my_namespaced_bundle::'";!a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'a_namespace_scoped_class_in_my_namespaced_bundle::'";mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'";!mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'";mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::'";}bodyfilecontrol{namespace=>"mynamespace";}bundleagentmy_bundle{classes:"a_bundle_scoped_class_in_my_namespaced_bundle";"a_namespace_scoped_class_in_my_namespaced_bundle"scope=>"namespace";reports:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'a_bundle_scoped_class_in_my_namespaced_bundle::'";!a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'a_bundle_scoped_class_in_my_namespaced_bundle::'";a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'a_namespace_scoped_class_in_my_namespaced_bundle::'";!a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'a_namespace_scoped_class_in_my_namespaced_bundle::'";mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'";!mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I do not see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'";mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::"In$(this.namespace):$(this.bundle) I see 'mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::'";}

code

R: In mynamespace:my_bundle I see 'a_bundle_scoped_class_in_my_namespaced_bundle::'R: In mynamespace:my_bundle I see 'a_namespace_scoped_class_in_my_namespaced_bundle::'R: In mynamespace:my_bundle I see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'R: In mynamespace:my_bundle I see 'mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::'R: In default:main I do not see 'a_bundle_scoped_class_in_my_namespaced_bundle::'R: In default:main I do not see 'a_namespace_scoped_class_in_my_namespaced_bundle::'R: In default:main I do not see 'mynamespace:a_bundle_scoped_class_in_my_namespaced_bundle::'R: In default:main I see 'mynamespace:a_namespace_scoped_class_in_my_namespaced_bundle::'

This policy can be found in/var/cfengine/share/doc/examples/namespace_classes.cfand downloaded directly fromgithub.

Hard classes exist in all namespaces andthus can be referred to from any namespace without qualification.

code

bundleagent__main__{methods:"example:my_bundle";reports:cfengine::"From the '$(this.namespace)' namespace the class expression 'cfengine::' evaluates true";default:cfengine::"From the '$(this.namespace)' namespace the class expression 'default:cfengine::' evaluates true";"The class 'cfengine' has tags:$(with)"with=>join(", ",getclassmetatags("cfengine"));}bodyfilecontrol{namespace=>"example";}bundleagentmy_bundle{reports:cfengine::"From the '$(this.namespace)' namespace the class expression 'cfengine::' evaluates true";default:cfengine::"From the '$(this.namespace)' namespace the class expression 'default:cfengine::' evaluates true";}

code

R: From the 'example' namespace the class expression 'cfengine::' evaluates trueR: From the 'example' namespace the class expression 'default:cfengine::' evaluates trueR: From the 'default' namespace the class expression 'cfengine::' evaluates trueR: From the 'default' namespace the class expression 'default:cfengine::' evaluates trueR: The class 'cfengine' has tags: inventory, attribute_name=none, source=agent, hardclass

This policy can be found in/var/cfengine/share/doc/examples/namespace_hard_classes.cfand downloaded directly fromgithub.