.. -*- mode: rst -*-

.. _server-plugins-properties:

==========
Properties
==========

The Properties plugin is a connector plugin that adds information from
properties files into client metadata instances.

Enabling Properties
===================

First, ``mkdir /var/lib/bcfg2/Properties``. Each property XML file goes
in this directory. Each will automatically be cached by the server,
and reread/reparsed upon changes. Add **Properties** to your ``plugins``
line in ``/etc/bcfg2.conf``.

Data Structures
===============

Properties adds a new dictionary to client metadata instances that maps
property file names to PropertyFile instances. PropertyFile instances
contain parsed XML data as the "data" attribute.

The XML data in a property file is arbitrary, but a matching ``.xsd``
file can be created to assign a schema to a property file, which will
be checked when running ``bcfg2-repo-validate``.  For instance, given::

    Properties/dns-config.xml
    Properties/dns-config.xsd

``dns-config.xml`` will be validated against ``dns-config.xsd``.

Usage
=====

Specific property files can be referred to in
templates as ``metadata.Properties[<filename>]``. The
data attribute is an LXML element object. (Documented
`here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_)

Currently, only one access method is defined for this data, ``Match``.
``Match`` parses the Group and Client tags in the file and returns a
list of elements that apply to the client described by a set of
metadata.  (See :ref:`server-plugins-structures-bundler-index` for
more details on how Group and Client tags are parsed.)  For instance::

    {% python
    ntp_servers = [el.text
                   for el in metadata.Properties['ntp.xml'].Match(metadata):
                   if el.tag == "Server"]
    %}

As we formulate more common use cases, we will add them to the
!PropertyFile class as methods. This will simplify templates.

Accessing Properties contents from TGenshi
==========================================

Access contents of ``Properties/auth.xml``::


    ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text}