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.
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.:
Several variables are pre-defined inside Genshi XML templates:
|repo||The path to the Bcfg2 repository on the filesystem|
<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.
The Genshi XML templating language is described in depth at Genshi. The XML schema reference follows.
Most Genshi templating directives can be used either as standalone elements or as attributes on existing elements. This attribute group defines the attribute directives.
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.
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.
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.
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.)
<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.
|privkey.xml and pubkey.xml||Yes||Yes||Yes||Yes |
|sslcert.xml and sslkey.xml||Yes||Yes||Yes||Yes|
|Metadata groups.xml||Yes ||No||No||Yes|
|||info.xml also supports conditional Path tags; see info.xml for more.|
|||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.|
|||The semantics of Group tags in groups.xml is slightly different; see groups.xml for details.|
|||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.|