.. -*- 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 *<Client />* tags, each of which
describe one host. A sample file is below:

.. code-block:: xml

    <Clients version="3.0">
      <Client profile="backup-server" name="backup.example.com"/>
      <Client profile="console-server" name="con.example.com"/>
      <Client profile="kerberos-master" name="kdc.example.com"/>
      <Client profile="mail-server" name="mail.example.com"/>
      <Client name='foo' address='10.0.0.1'>
          <Alias name='foo-mgmt' address='10.1.0.1'/>
      </Client>
    </Clients>

.. 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 ``<Client>`` 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 ``<Client>`` 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 <server-database>`.

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

    <Groups>
      <Group name='mail-server' profile='true'
                                comment='Top level mail server group' >
        <Bundle name='mail-server'/>
        <Bundle name='mailman-server'/>
        <Group name='apache-server'/>
        <Group name='nfs-client'/>
        <Group name='server'/>
        <Group name='rhel5'>
          <Group name='sendmail-server'/>
        </Group>
        <Group name='rhel6'>
          <Group name='postfix-server'/>
        </Group>
      </Group>
      <Group name='rhel'>
        <Group name='selinux-enabled'/>
      </Group>
      <Group name='oracle-server'>
        <Group name='selinux-enabled' negate='true'/>
      </Group>
      <Client name='foo.eample.com'>
        <Group name='oracle-server'/>
        <Group name='apache-server'/>
      </Client>
    </Groups>

A Group or Client 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

    <Groups>
      <Group name="foo-server">
        <Group name="apache-server"/>
        <Group name="selinux-enabled"/>
      </Group>
      <Group name="apache-server">
        <Group name="selinux-enabled"/>
      </Group>
      <Group name="every-server">
        <Group name="selinux-enabled"/>
      </Group>
      <Client name="foo.example.com">
        <Group name="selinux-enabled" negate="true"/>
      </Client>

.. 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 <http://www.w3.org/TR/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

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

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.

Probes
======

The metadata plugin includes client-side probing functionality. This
is fully documented :ref:`here <server-plugins-probes-index>`.

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`.

+------------+------------------------------------------------+---------------+
| Attribute  | Description                                    | Value         |
+============+================================================+===============+
| hostname   | Client hostname                                | String        |
+------------+------------------------------------------------+---------------+
| profile    | Client profile                                 | String        |
+------------+------------------------------------------------+---------------+
| aliases    | Client aliases                                 | List          |
+------------+------------------------------------------------+---------------+
| addresses  | Adresses this client is known by               | List          |
+------------+------------------------------------------------+---------------+
| groups     | Groups this client is a member of              | List          |
+------------+------------------------------------------------+---------------+
| categories | Categories of this clients groups              | List          |
+------------+------------------------------------------------+---------------+
| uuid       | uuid identifier for this client                | String        |
+------------+------------------------------------------------+---------------+
| password   | bcfg password for this client                  | String        |
+------------+------------------------------------------------+---------------+
| connectors | connector plugins known to this client         | List          |
+------------+------------------------------------------------+---------------+
| query      | `MetadataQuery`_ object                        | MetadataQuery |
+------------+------------------------------------------------+---------------+


+-----------------------------+------------------------------------------------+-------------------+
| Method                      | Description                                    | Value             |
+=============================+================================================+===================+
| inGroup(group)              | True if this client is a memnber of 'group'    | Boolean           |
+-----------------------------+------------------------------------------------+-------------------+
| group_in_category(category) | Returns the group in 'category' if the client  | String            |
|                             | is a member of 'category', otherwise ''        |                   |
+-----------------------------+------------------------------------------------+-------------------+

MetadataQuery
-------------

This class provides query methods for the metadata of all clients
known to the Bcfg2 server.  Note that ``*by_groups()`` and
``*by_profiles()`` behave differently; for a client to be included in
the return value of a ``by_groups()`` method, it must be a member of
*all* groups listed in the argument; for a client to be included in
the return value of a ``by_profiles()`` method, it must have any group
listed as its profile group.

+------------------------------+------------------------------------------------+-------------------+
| Method                       | Description                                    | Value             |
+==============================+================================================+===================+
| by_name(client)              | Get ClientMetadata object for 'client'         | ClientMetadata    |
+------------------------------+------------------------------------------------+-------------------+
| by_groups(groups)            | Get ClientMetadata object for clients in all   | List of           |
|                              | listed groups                                  | ClientMetadata    |
+------------------------------+------------------------------------------------+-------------------+
| by_profiles(client)          | Get ClientMetadata objects for clients whose   | List of           |
|                              | profile matches any listed profile group       | ClientMetadata    |
+------------------------------+------------------------------------------------+-------------------+
| names_by_groups(groups)      | Get the names of all clients in all listed     | List of strings   |
|                              | groups                                         |                   |
+------------------------------+------------------------------------------------+-------------------+
| names_by_profiles(profiles)  | Get the names of clients whose profile matches | List of strings   |
|                              | any listed profile group                       |                   |
+------------------------------+------------------------------------------------+-------------------+
| all_clients()                | All known client hostnames                     | List of strings   |
+------------------------------+------------------------------------------------+-------------------+
| all_groups()                 | All known group names                          | List of strings   |
+------------------------------+------------------------------------------------+-------------------+
| all_groups_in_category(cat)  | The names of all groups in category 'cat'      | List of strings   |
+------------------------------+------------------------------------------------+-------------------+
| all()                        | Get ClientMetadata for all clients             | List of           |
|                              |                                                | ClientMetadata    |
+------------------------------+------------------------------------------------+-------------------+