.. -*- mode: rst -*-
.. _server-plugins-grouping-metadata:
========
Metadata
========
The metadata mechanism has two types of information, client metadata
and group metadata. The client metadata describes which top level
group a client is associated with.The group metadata describes groups
in terms of what bundles and other groups they include. Group data and
clients' memberships are reflected in the `groups.xml`_ and
`clients.xml`_ files, respectively.
Usage of Groups in Metadata
===========================
Clients are assigned membership of groups in the Metadata
descriptions. Clients can be directly assigned to *'profile'* or
*'public'* groups. Client membership of all other groups is by those
groups being associated with the profile or public groups. This file
can be indirectly modified from clients through use of the ``-p`` flag
to ``bcfg2``.
Clients are associated with profile groups in `clients.xml`_
as shown below.
.. _server-plugins-grouping-metadata-clients-xml:
clients.xml
===========
The ``clients.xml`` file contains the mappings of Profile Groups
to clients. The file is just a series of ```` tags, each of which
describe one host. A sample file is below:
.. code-block:: xml
.. xml:schema:: clients.xsd
For detailed information on client authentication see
:ref:`appendix-guides-authentication`
.. _server-plugins-grouping-metadata-clients-database:
Clients Database
----------------
.. versionadded:: 1.3.0
It is also possible to store client records in a database rather than
writing back to `clients.xml`_. This provides several advantages:
* `clients.xml`_ will never be written by the server, removing an
area of contention between the user and server.
* `clients.xml`_ can be removed entirely for many sites.
* The Bcfg2 client list can be queried by other machines without
obtaining and parsing `clients.xml`_.
* A single client list can be shared amongst multiple Bcfg2 servers.
In general, storing clients in the database works almost the same as
`clients.xml`_. `groups.xml`_ is parsed identically. If
`clients.xml`_ is present, it is parsed, but ```` tags in
`clients.xml`_ *do not* assert client existence; they are only used
to set client options *if* the client exists (in the database). That
is, the two purposes of `clients.xml`_ -- to track which clients
exist, and to set client options -- have been separated.
With the improvements in `groups.xml`_ parsing in 1.3, client groups
can now be set directly in `groups.xml`_ with ```` tags. (See
:xml:type:`clientType` for more details.) As a result, `clients.xml`_
is only necessary if you need to set options (e.g., aliases, floating
clients, per-client passwords, etc.) on clients.
To use the database backend instead of `clients.xml`_, set
``use_database`` in the ``[metadata]`` section of ``bcfg2.conf`` to
``true``. You will also need to configure the :ref:`Global Server
Database Settings `.
The `clients.xml`_-based model remains the default.
groups.xml
==========
The ``groups.xml`` file contains Group and Profile definitions. Here's
a simple ``groups.xml`` file:
.. code-block:: xml
A Group tag that does not contain any child tags is a declaration of
membership; a Group or Client tag that does contain children is a
conditional. So the example above does not assign either the
``rhel5`` or ``rhel6`` groups to machines in the ``mail-server``
group, but conditionally assigns the ``sendmail-server`` or
``postfix-server`` groups depending on the OS of the client.
(Presumably in this example the OS groups are set by a probe.)
Consequently, a client that is RHEL 5 and a member of the
``mail-server`` profile group would also be a member of the
``apache-server``, ``nfs-client``, ``server``, and ``sendmail-server``
groups; a RHEL 6 client that is a member of the ``mail-server``
profile group would be a member of the ``apache-server``,
``nfs-client``, ``server``, and ``postfix-server`` groups.
Client tags in `groups.xml`_ allow you to supplement the profile
group declarations in `clients.xml`_ and/or client group assignments
with the :ref:`server-plugins-grouping-grouppatterns` plugin. They
should be used sparingly. (They are more useful when you are using
the database backend for client records.)
You can also declare that a group should be negated; this allows you
to set defaults and override them efficiently. Negation is applied
after other group memberships are calculated, so it doesn't matter how
many times a client is assigned to a group or how many times it is
negated; a single group negation is sufficient to remove a client from
that group. For instance, in the following example,
``foo.example.com`` is **not** a member of ``selinux-enabled``, even
though it is a member of the ``foo-server`` and ``every-server``
groups:
.. code-block:: xml
.. note::
Nested Group conditionals, Client tags, and negated Group tags are
all new in 1.3.0.
.. xml:schema:: metadata.xsd
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. The `Metadata`_ plugin supports the use of XInclude
specifications to split the `clients.xml`_ and `groups.xml`_
files. This mechanism allows the following specification to produce
useful results:
.. code-block:: xml
Each of the included groups files has the same format. These files are
properly validated by ``bcfg2-lint``. This mechanism is useful for
composing group definitions from multiple sources, or setting
different permissions in an svn repository.
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.)
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.
Probes
======
The metadata plugin includes client-side probing functionality. This
is fully documented :ref:`here `.
Metadata Caching
================
.. versionadded:: 1.3.0
Client metadata can be cached in order to improve performance. This
is particularly important if you have lots of templates that use
metadata from other clients (e.g., with the `MetadataQuery`_ interface
described below. See :ref:`server-caching` for a full description of
the caching features available.
.. _server-plugins-grouping-metadata-clientmetadata:
ClientMetadata
==============
A special client metadata class is available to
:ref:`server-plugins-generators-cfg-genshi` and
:ref:`server-plugins-generators-cfg-cheetah`.
.. autoclass:: Bcfg2.Server.Plugins.Metadata.ClientMetadata
MetadataQuery
-------------
.. autoclass:: Bcfg2.Server.Plugins.Metadata.MetadataQuery