Common XML Features

Most of the XML files in Bcfg2 have a common set of features that are supported. These are described in some detail below, and a precise rundown of which features are supported by which files is provided.

Group and Client tags

These allow the portions of an XML document inside a Client or Group tag to only apply to the given client group. That is, they can be thought of as conditionals, where the following are roughly equivalent:

<Group name="group1">
  <Path name="/etc/foo.conf"/>
</Group>

And:

If client is a member of group1 then
    Manage the abstract path "/etc/foo.conf"

Nested Group and Client tags are conjunctive (logical AND). For instance, the following are roughly equivalent:

<Group name="group1">
  <Client name="foo.example.com">
    <Package name="bar"/>
  </Client>
  <Package name="baz"/>
</Group>

And:

If client is a member of group1 and has hostname "foo.example.com" then
    Manage the abstract package "bar"
If client is a member of group1 then
    Manage the abstract package "baz"

There is no convenient else; you must specify all conditions explicitly. To do this, Group and Client tags may be negated, as in:

<Group name="group1">
  <Service name="foo"/>
</Group>
<Group name="group1" negate="true">
  <Service name="bar"/>
</Group>

This is roughly equivalent to:

If client is a member of group1 then
    Manage the abstract service "foo"
If client is not a member of group 1 then
    Manage the abstract service "bar"

Or, more compactly:

If client is a member of group1 then

Manage the abstract service “foo”

Else

Manage the abstract service “bar”

As an example, consider the following bundle:

<Bundle>
  <Path glob='/etc/ssh/*'/>
  <Group name='rpm'>
    <Package name='openssh'/>
    <Package name='openssh-askpass'/>
    <Service name='sshd'/>
    <Group name='fedora' >
       <Group name='fedora14' negate='true'>
         <Package name='openssh-clients'/>
       </Group>
       <Package name='openssh-server'/>
    </Group>
  </Group>
  <Group name='deb'>
    <Package name='ssh'/>
    <Service name='ssh'/>
  </Group>
  <Client name='trust.example.com'>
    <Path name='/etc/ssh/shosts.equiv'/>
  </Client>
</Bundle>

In this bundle, most of the entries are common to all systems. Clients in group deb get one extra package and service, while clients in group rpm get two extra packages and an extra service. In addition, clients in group fedora and group rpm get one extra package entries, unless they are not in the fedora14 group, in which case, they get an extra package. The client trust.example.com gets one extra file that is not distributed to any other clients.

Group/Hostname	Entry
all	/etc/ssh/*
rpm	Package openssh
rpm	Package openssh-askpass
rpm	Service sshd
rpm AND fedora	Package openssh-server
rpm AND fedora AND NOT fedora14	Package openssh-clients
deb	Package ssh
deb	Service ssh
trust.example.com	/etc/ssh/shosts.equiv

Genshi templating

Genshi XML templates allow you to use the Genshi templating system to dynamically generate XML file content for a given client. Genshi templating can be enabled on a file by adding the Genshi namespace to the top-level tag, e.g.:

<Bundle xmlns:py="http://genshi.edgewall.org/">

Several variables are pre-defined inside Genshi XML templates:

Name	Description
metadata	Client metadata
repo	The path to the Bcfg2 repository on the filesystem

Note

<Group> and <Client> tags can be used inside templates as of Bcfg2 1.2, but they do not behave the same as using a Genshi conditional, e.g.:

<py:if test="'groupname' in metadata.groups">
</py:if>

The conditional is evaluated when the template is rendered, so code inside the conditional is not executed if the conditional fails. A <Group> tag is evaluated after the template is rendered, so code inside the tag is always executed. This is an important distinction: if you have code that will fail on some groups, you must use a Genshi conditional, not a <Group> tag. The same caveats apply to <Client> tags.

Genshi XML Template Reference

The Genshi XML templating language is described in depth at Genshi. The XML schema reference follows.

Genshi Tags

group py:genshiElements

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This element group defines the standalone tags.

Elements:

element py:with

Attributes:

Name	Description	Values	Required	Default
py:vars	A semicolon-delimited list of variables to define and their values.	string	Yes	None

Any arbitrary child elements allowed

Text content:

Any

element py:replace

Attributes:

Name	Description	Values	Required	Default
py:value	The value to replace the contents with.	string	Yes	None

Any arbitrary child elements allowed

Text content:

Any

element py:choose

Attributes:

Name	Description	Values	Required	Default
py:test	If test is set, the child py:when directives are tested for equality to the value of the expression.	string	No	None

Child elements:

• element py:when

  The when directive is used inside py:chooseType or choose to handle a single specific condition.

  Attributes:

  Name	Description	Values	Required	Default
  py:test	The statement giving the value to test	string	Yes	None

  Any arbitrary child elements allowed

  Text content:

  Any

• element py:otherwise

  Any arbitrary child elements allowed

  Text content:

  Any

Text content:

Any

element py:for

Attributes:

Name	Description	Values	Required	Default
py:each	The loop iterator	string	Yes	None

Any arbitrary child elements allowed

Text content:

Any

element py:if

Attributes:

Name	Description	Values	Required	Default
py:test	The statement giving the value to test	string	Yes	None

Any arbitrary child elements allowed

Text content:

Any

element py:match

Attributes:

Name	Description	Values	Required	Default
py:path	XPath expression to search for in the template.	string	Yes	None
py:buffer	Whether the matched content should be buffered in memory. Buffering can improve performance a bit at the cost of needing more memory during rendering. Buffering is required for match templates that contain more than one invocation of the select() function. If there is only one call, and the matched content can potentially be very long, consider disabling buffering to avoid excessive memory use.	true | false	No	true
py:once	Whether the engine should stop looking for more matching elements after the first match. Use this on match templates that match elements that can only occur once in the stream, such as the <head> or <body> elements in an HTML template, or elements with a specific ID.	true | false	No	false
py:recursive	Whether the match template should be applied to its own output. Note that once implies non-recursive behavior, so this attribute only needs to be set for match templates that don’t also have once set.	true | false	No	true

Any arbitrary child elements allowed

Text content:

Any

element py:def

Attributes:

Name	Description	Values	Required	Default
py:function	The function prototype	string	Yes	None

Any arbitrary child elements allowed

Text content:

Any

Genshi Attributes

attributeGroup py:genshiAttrs

Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This attribute group defines the attribute directives.

Name	Description	Values	Required	Default
py:attrs	attrs directive	string	No	None
py:choose	choose directive	string	No	None
py:content	content directive	string	No	None
py:def	def directive	string	No	None
py:for	for directive	string	No	None
py:if	if directive	string	No	None
py:match	match directive	string	No	None
py:otherwise	The otherwise directive is used inside py:chooseType or choose to handle all conditions not handled by a py:when.	string	No	None
py:replace	replace directive	string	No	None
py:strip	strip directive	string	No	None
py:when	The when directive is used inside py:chooseType or choose to handle a single specific condition.	string	No	None
py:with	with directive	string	No	None

Encryption

You can encrypt data in XML files to protect that data from other people who need access to the repository. The data is decrypted transparently on-the-fly by the server.

Note

This feature is not intended to secure the files against a malicious attacker who has gained access to your Bcfg2 server, as the encryption passphrases are held in plaintext in bcfg2.conf. This is only intended to make it easier to use a single Bcfg2 repository with multiple admins who should not necessarily have access to each other’s sensitive data.

XML files are encrypted on a per-element basis; that is, rather than encrypting the whole file, only the character content of individual elements is encrypted. This makes it easier to track changes to the file in a VCS, and also lets unprivileged users work with the other data in the file. Only character content of an element can be encrypted; attribute content and XML elements themselves cannot be encrypted.

By default, decryption is strict; that is, if any element cannot be decrypted, parsing of the file is aborted. See Lax vs. Strict decryption for information on changing this on a global or per-file basis.

To encrypt or decrypt a file, use bcfg2-crypt.

See Bcfg2 Data Encryption for more details on encryption in Bcfg2 in general.

XInclude

New in version 0.9.0.

XInclude is a W3C specification for the inclusion of external XML documents into XML source files, allowing complex definitions to be split into smaller, more manageable pieces. For instance, in the Metadata groups.xml file, you might do:

<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="my-groups.xml" />
  <xi:include href="their-groups.xml" />
</Groups>

To enable XInclude on a file, you need only add the XInclude namespace to the top-level tag.

You can also optionally include a file that may or may not exist with the fallback tag:

<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="my-groups.xml"/>
  <xi:include href="their-groups.xml"><xi:fallback/></xi:include>
</Groups>

In this case, if their-groups.xml does not exist, no error will be raised and everything will work fine. (You can also use fallback to include a different file, or explicit content in the case that the parent include does not exist.)

XInclude can only include complete, well-formed XML files. In some cases, it may not be entirely obvious or intuitive how to structure such an included file to conform to the schema, although in general the included files should be structure exactly like the parent file.

Wildcard XInclude

New in version 1.3.1.

Bcfg2 supports an extension to XInclude that allows you to use shell globbing in the hrefs. (Stock XInclude doesn’t support this, since the href is supposed to be a URL.)

For instance:

<Groups xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="groups/*.xml"/>
</Groups>

This would include all *.xml files in the groups subdirectory.

Note that if a glob finds no files, that is treated the same as if a single included file does not exist. You should use the fallback tag, described above, if a glob may potentially find no files.

Feature Matrix

File	Group/Client	Genshi	Encryption	XInclude
ACL ip.xml	No	No	No	Yes
ACL metadata.xml	Yes	Yes	Yes	Yes
Bundler	Yes	Yes	Yes	Yes
info.xml	Yes [1]	Yes	Yes	Yes
privkey.xml and pubkey.xml	Yes	Yes	Yes	Yes [2]
authorizedkeys.xml	Yes	Yes	Yes	Yes
sslcert.xml and sslkey.xml	Yes	Yes	Yes	Yes
Decisions	Yes	Yes	Yes	Yes
Defaults	Yes	Yes	Yes	Yes
FileProbes	Yes	Yes	Yes	Yes
GroupPatterns	No	No	No	Yes
Metadata clients.xml	No	No	No	Yes
Metadata groups.xml	Yes [3]	No	No	Yes
NagiosGen	Yes	Yes	Yes	Yes
Packages	Yes	Yes	Yes	Yes
Pkgmgr	Yes	No	No	No
Properties	Yes [4]	Yes	Yes	Yes
Rules	Yes	Yes	Yes	Yes

Footnotes

[1]	info.xml also supports conditional Path tags; see info.xml for more.

[2]	XInclude is supported, but the schema has not been modified to allow including files that are structured exactly like the parent. You may need to read the schema to understand how to use XInclude properly.

[3]	The semantics of Group tags in groups.xml is slightly different; see groups.xml for details.

[4]	Group and Client tags in XML Properties are not automatic by default; they can be resolved by use of either the Match() or XMLMatch() methods, or by use of the Automatch feature. See XML Property Files for details.