.. -*- mode: rst -*-

.. _server-plugins-structures-altsrc:

======
altsrc
======

.. versionadded:: 0.9.5

Altsrc is a generic, Bcfg2 server-side mechanism for performing
configuration entry name remapping for the purpose of data binding.
Altsrc can be used as a parameter for any entry type, and can be used
in any structure.

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 Cfg and perform manual synchronization. Or, you could use
  symlinks and pray. Altsrc is driven from the bundle side. For
  example:

  .. code-block:: xml

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

* 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 templates /etc/firewall-rules-external and
  /etc/firewall-rules-internal for different clients based on their
  group membership.

  .. code-block:: xml

      <Bundle>
         ...
         <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 :ref:`Genshi <server-plugins-generators-cfg-genshi>` or
  :ref:`Cheetah <server-plugins-generators-cfg-cheetah>` template. 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>
        <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>