.. -*- mode: rst -*-
.. _xml-features:
=====================
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.
.. _xml-group-client-tags:
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:
.. code-block:: xml
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:
.. code-block:: xml
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:
.. code-block:: xml
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 :ref:`bundle
`:
.. code-block:: xml
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/ssh_host_dsa_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_rsa_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_dsa_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_rsa_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_key`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_host_key.pub`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/sshd_config`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_config`` |
+------------------------+-----------------------------------+
| all | ``/etc/ssh/ssh_known_hosts`` |
+------------------------+-----------------------------------+
| ``rpm`` | Package ``openssh`` |
+------------------------+-----------------------------------+
| ``rpm`` | Package ``openssh-askpass`` |
+------------------------+-----------------------------------+
| ``rpm`` | Service ``sshd`` |
+------------------------+-----------------------------------+
| ``rpm`` AND ``fedora`` | Package ``openssh-server`` |
+------------------------+-----------------------------------+
| ``rpm`` AND ``fedora`` | Package ``openssh-clients`` |
| AND NOT ``fedora14`` | |
+------------------------+-----------------------------------+
| ``deb`` | Package ``ssh`` |
+------------------------+-----------------------------------+
| ``deb`` | Service ``ssh`` |
+------------------------+-----------------------------------+
| ``trust.example.com`` | ``/etc/ssh/shosts.equiv`` |
+------------------------+-----------------------------------+
.. _xml-genshi-templating:
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.:
.. code-block:: xml
Several variables are pre-defined inside Genshi XML templates:
+-------------+--------------------------------------------------------+
| Name | Description |
+=============+========================================================+
| metadata | :ref:`Client metadata |
| | ` |
+-------------+--------------------------------------------------------+
| repo | The path to the Bcfg2 repository on the filesystem |
+-------------+--------------------------------------------------------+
.. note::
```` and ```` 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.::
The conditional is evaluated when the template is rendered, so
code inside the conditional is not executed if the conditional
fails. A ```` 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 ````
tag. The same caveats apply to ```` tags.
.. _xml-genshi-reference:
Genshi XML Template Reference
-----------------------------
The Genshi XML templating language is described in depth at `Genshi
`_. The XML schema reference follows.
Genshi Tags
~~~~~~~~~~~
.. xml:group:: genshiElements
:namespace: py
Genshi Attributes
~~~~~~~~~~~~~~~~~
.. xml:attributegroup:: genshiAttrs
:namespace: py
.. _xml-encryption:
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
:ref:`server-encryption-lax-strict` for information on changing this
on a global or per-file basis.
To encrypt or decrypt a file, use :ref:`bcfg2-crypt`.
See :ref:`server-encryption` for more details on encryption in Bcfg2
in general.
XInclude
========
.. versionadded:: 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 :ref:`server-plugins-grouping-metadata`
``groups.xml`` file, you might do:
.. code-block:: xml
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:
.. code-block:: xml
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
~~~~~~~~~~~~~~~~~
.. versionadded:: 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:
.. code-block:: xml
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 |
+=================================================+==============+========+============+============+
| :ref:`ACL ip.xml ` | No | No | No | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`ACL metadata.xml | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Bundler | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`info.xml ` | Yes [#f1]_ | Yes | Yes | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`privkey.xml and pubkey.xml | Yes | Yes | Yes | Yes [#f2]_ |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`authorizedkeys.xml | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Decisions | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Defaults | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`FileProbes | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`GroupPatterns | No | No | No | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Metadata clients.xml | No | No | No | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Metadata groups.xml | Yes [#f3]_ | No | No | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`NagiosGen | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Packages | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Pkgmgr | Yes | No | No | No |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Properties | Yes [#f4]_ | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`Rules ` | Yes | Yes | Yes | Yes |
+-------------------------------------------------+--------------+--------+------------+------------+
| :ref:`SSLCA cert.xml and key.xml | Yes | Yes | Yes | Yes |
| ` | | | | |
+-------------------------------------------------+--------------+--------+------------+------------+
.. rubric:: Footnotes
.. [#f1] ``info.xml`` also supports conditional Path tags; see
:ref:`server-info` for more.
.. [#f2] 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.
.. [#f3] The semantics of Group tags in ``groups.xml`` is slightly
different; see
:ref:`server-plugins-grouping-metadata-groups-xml` for
details.
.. [#f4] 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
:ref:`server-plugins-connectors-properties-automatch`
feature. See :ref:`server-plugins-connectors-properties-xml`
for details.