.. -*- mode: rst -*-

.. _server-configurationentries:

=====================
Configuration Entries
=====================

The full semantics of each configuration entry is documented with the
:ref:`server-plugins-generators-rules` plugin.

.. _boundentries:

Bound Entries
=============

This feature is a mechanism to specify a full entry at once from
a bundle. Traditionally, entries are defined in two stages. First,
an abstract entry is defined in a bundle. This entry includes a type
(the XML tag) and a name attribute. Then this entry is bound for
a client, providing the appropriate instance of that entry for the
client. Specifying a bound entry short-circuits this process; the only
second stage processing on Bound entries is to remove the "Bound" prefix
from the element tag. The use of a bound entry allows the single stage
definition of a complete entry. Bound entries can be used for any type.

Example:

.. code-block:: xml

    <Bundle name='ntp'>
       <BoundPackage name='ntp' type='deb' version='1:4.2.4p4+dfsg-3ubuntu2.1'/>
    </Bundle>

Fun and Profit using altsrc
===========================

Altsrc is a generic, bcfg2-server-side mechanism for performing
configuration entry name remapping for the purpose of data binding.

Use Cases
---------

* Equivalent configuration entries on different architectures with
  different names

* Mapping entries with the same name to different bind results in a
  configuration (two packages with the same name but different types)

* A single configuration entry across multiple specifications
  (multi-plugin, or multi-repo)

Examples
--------

* Consider the case of ``/etc/hosts`` on linux and ``/etc/inet/hosts``
  on solaris. These files contain the same data in the same format,
  and should typically be synchronized, however, exist in different
  locations. Classically, one would need to create one entry for each
  in :ref:`server-plugins-generators-cfg` or
  :ref:`server-plugins-generators-tcheetah` and perform manual
  synchronization. Or, you could use symlinks and pray. Altsrc is
  driven from the bundle side. For example:

  .. code-block:: xml

      <Bundle name='netinfo'>
         <Group name='solaris'>
           <Path name='/etc/inet/hosts' altsrc='/etc/hosts'/>
         </Group>
         <Group name='linux'>
           <Path name='/etc/hosts'/>
         </Group>
      </Bundle>

  In this case, when a solaris host gets the 'netinfo' bundle, it will
  get the first Path entry, which includes an altsrc parameter. This
  will cause the server to bind the entry as if it were a Path
  called ``/etc/hosts``. This configuration entry is still called
  ``/etc/inet/hosts``, and is installed as such.

* On encap systems, frequently multiple packages of the same name, but
  of different types will exist. For example, there might be an openssl
  encap package, and an openssl rpm package. This can be dealt with
  using a bundle like:

  .. code-block:: xml

      <Bundle name='openssl'>
         <Package name='openssl' altsrc='openssl-encap'/>
         <Package name='openssl' altsrc='openssl-rpm'/>
      </Bundle>

  This bundle will bind data for the packages "openssl-encap" and
  "openssl-rpm", but will be delivered to the client with both packages
  named "openssl" with different types.

* Finally, consider the case where there exist complicated, but
  completely independent specifications for the same configuration
  entry but different groups of clients. The following bundle will
  allow the use of two different
  :ref:`server-plugins-generators-tcheetah` templates
  ``/etc/firewall-rules-external`` and
  ``/etc/firewall-rules-internal`` for different clients based on
  their group membership.

  .. code-block:: xml

      <Bundle name='firewall'>
         ...
         <Group name='conduit'>
           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-external'/>
         </Group>
         <Group name='internal'>
           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-internal'/>
         </Group>
      </Bundle>

* Consider the case where a variety of files can be constructed by a
  single template (:ref:`server-plugins-generators-tcheetah` or
  :ref:`server-plugins-generators-tgenshi-index`). It would be
  possible to copy this template into the proper location for each
  file, but that requires proper synchronization upon modification and
  knowing up front what the files will all be called. Instead, the
  following bundle allows the use of a single template for all proper
  config file instances.

  .. code-block:: xml

      <Bundle name='netconfig'>
        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth0' altsrc='/etc/ifcfg-template'/>
        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth1' altsrc='/etc/ifcfg-template'/>
        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth2' altsrc='/etc/ifcfg-template'/>
      </Bundle>

  altsrc can be used as a parameter for any entry type, and can be
  used in any structure, including
  :ref:`server-plugins-structures-bundler-index`.