.. -*- mode: rst -*-

.. _development-writing_specification:

===========================
Writing Bcfg2 Specification
===========================

Bcfg2 specifications are logically divided in to three areas:

* Metadata
* Abstract
* Literal

The metadata portion of the configuration assigns a client to its profile
group and to its non-profile groups. The profile group is assigned
in ``Metadata/clients.xml`` and the non profile group assignments are in
``Metadata/groups.xml``.

The group memberships contained in the metadata are then used to constuct
an abstract configuration for the client. An abstract configuration for
a client identifies the configuration entities (packages, configuration
files, service, etc) that a client requires, but it does not identify
them explicitly. For instance an abstract configuration may identify
that a client needs the Bcfg2 package with

.. code-block:: xml

    <Package name=bcfg2/>

but this does not explicitly identify that an RPM package version
0.9.2 should be loaded from http://rpm.repo.server/bcfg2-1.0.1-0.1.rpm.
The abstract configuration is defined in the xml configuration files
for the Base and Bundles plugins.

A combination of a clients metadata (group memberships) and abstract
configuration is then used to generate the clients literal configuration.
For instance the above abstract configuration entry may generate a
literal configuration of


.. code-block:: xml

    <Package name='bcfg2' version='1.0.1-0.1' type='yum'/>

A clients literal configuration is generated by a number of plugins that
handle the different configuration entities.


.. figure:: specification_overview.png
   :width:  60%
   :alt:    Specification overview
   :align:  center