.. -*- mode: rst -*-

.. _appendix-files-ntp:

.. Author: Jason Pepas

ntp example
===========

Here is a series of example configurations for Bcfg2, each introducing
another layer of functionality.

* After each change, run ``bcfg-repo-validate -v``
* Run the server with ``bcfg2-server -v``
* Update the client with ``bcfg2 -v -d -n`` (will not actually make
  client changes) 

Package only
------------

Our example starts with the bare minimum configuration setup. We have
a client, a profile group, a list of packages, and a base configuration.

``Metadata/clients.xml``:

.. code-block:: xml

    <Clients version='3.0'>
    <Client profile='fedora' pingable='N' pingtime='0' name='foo.bar.com'/>
    </Clients>

``Metadata/groups.xml``:

.. code-block:: xml

    <Groups version='3.0'>
    <Group profile='true' name='fedora' toolset='rh'/>
    </Groups>

``Base/base.xml``:

.. code-block:: xml

    <Base>
    <Group name='fedora'>
    <Package name='ntp'/>
    </Group>
    </Base>

``Pkgmgr/packages.xml``:

.. code-block:: xml

    <PackageList type='rpm' priority='0'>
    <Package name='ntp' version='4.2.0.a.20050816-11.FC5'/>
    </PackageList>

Add service
-----------

Configure the service, and add it to the base.

``Svcmgr/services.xml``:

.. code-block:: xml

    <Services priority='0'>
    <Service name='ntpd' status='on'/>
    </Services>

``Base/base.xml``:

.. code-block:: xml

    <Base>
    <Group name='fedora'>
    <Package name='ntp'/>
    <Service name='ntpd'/>
    </Group>
    </Base>

Add config file
---------------

Setup an ``etc/`` directory structure, and add it to the base.::

     # cat Cfg/etc/ntp.conf/ntp.conf 
     server ntp1.utexas.edu

``Base/base.xml``:

.. code-block:: xml

    <Base>
     <Group name='fedora'>
     <Package name='ntp'/>
     <Service name='ntpd'/>
     <Path name='/etc/ntp.conf'/>
     </Group>
    </Base>

Create a bundle
---------------

The above configuration layout works fine for a single service, but
that method of organization would quickly become a nightmare as you
approach the number of packages, services, and config files required
to represent a fully configured host. Bundles allow the grouping of
related configuration entries that are used to provide a single
service. This is done for several reasons:

* Grouping related things in one place makes it easier to add those
  entries for multiple groups of clients
* Grouping entries into bundles makes their validation occur
  collectively. This means that config files can override the
  contents of packages. Also, config files are rechecked after
  packages are upgraded, so that they can be repaired if the
  package install clobbered them.
* Services associated with a bundle get restarted whenever any entity
  in that bundle is modified. This ensures that new configuration 
  files and software are used after installation. 

The config file, package, and service are really all related
components describing the idea of an ntp client, so they should be 
logically grouped together. We use a bundle to accomplish this.

``Bundler/ntp.xml``:

.. code-block:: xml

    <Bundle name='ntp' version='2.0'>
    <Package name='ntp'/>
    <Service name='ntpd'/>
    <Path name='/etc/ntp.conf'/>
    </Bundle>

After this bundle is created, it must be associated with a group
(or groups). Add a bundle child element to the group(s) which should
install this bundle.

``Metadata/groups.xml``:

.. code-block:: xml

     <Groups>
    ...
     <Group name='fedora'>
       <Bundle name='ntp'/>
     </Group>
    ...
     </Groups>

Once this bundle is created, a client reconfigure will install
these entries. If any are modified, then the *ntpd* service will
be restarted. If you only want ntp configurations to be updated (and
nothing else), the bcfg2 client can be run with a ``-b <bundle name>``
option that will only update entries in the specified bundle.