.. -*- mode: rst -*-

.. _development-write-plugins:

Writing Bcfg2 Plugins
=====================

Bcfg2 plugins are python classes that subclass from
Bcfg2.Server.Plugin.Plugin. Several plugin-specific values must be set
in the new plugin. These values dictate how the new plugin will behave
with respect to the above four functions.  The following table describes
all important member fields.

+-----------------+-----------------------------------+--------------------------+
| Name            | Description                       | Format                   |
+=================+===================================+==========================+
| __name__        | The name of the plugin            | string                   |
+-----------------+-----------------------------------+--------------------------+
| __version__     | The plugin version (generally     | string                   |
|                 | tied to revctl keyword expansion) |                          |
+-----------------+-----------------------------------+--------------------------+
| __author__      | The plugin author.                | string                   |
+-----------------+-----------------------------------+--------------------------+
| __author__      | The plugin author.                | string                   |
+-----------------+-----------------------------------+--------------------------+
| __rmi__         | Set of functions to be exposed as | List of function names   |
|                 | XML-RPC functions                 | (strings)                |
+-----------------+-----------------------------------+--------------------------+
| Entries         | Multidimentional dictionary of    | Dictionary of            |
|                 | keys that point to the function   | ConfigurationEntityType, |
|                 | used to bind literal contents for | Name keys, and function  |
|                 | a given configuration entity.     | reference values         |
+-----------------+-----------------------------------+--------------------------+
| BuildStructures | Function that returns a list of   | Member function          |
|                 | the structures for a given client |                          |
+-----------------+-----------------------------------+--------------------------+
| GetProbes       | Function that returns a list of   | Member function          |
|                 | probes that a given client should |                          |
|                 | execute                           |                          |
+-----------------+-----------------------------------+--------------------------+
| ReceiveData     | Function that accepts the probe   | Member function          |
|                 | results for a given client.       |                          |
+-----------------+-----------------------------------+--------------------------+

Example Plugin
--------------

.. code-block:: python

    import Bcfg2.Server.Plugin
    class MyPlugin(Bcfg2.Server.Plugin.Plugin):
       '''An example plugin'''
       # All plugins need to subclass Bcfg2.Server.Plugin.Plugin
       __name__ = 'MyPlugin'
       __version__ = '1'
       __author__ = 'me@me.com'
       __rmi__ = ['myfunction']
       # myfunction is not available remotely as MyPlugin.myfunction

       def __init__(self, core, datastore):
           Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore)
           self.Entries = {'Path':{'/etc/foo.conf': self.buildFoo}}

       def myfunction(self):
           '''function for xmlrpc rmi call'''
           #do something
           return True

       def buildFoo(self, entry, metadata):
           '''Bind per-client information into entry based on metadata'''
           entry.attrib.update({'type':'file', 'owner':'root', 'group':'root', 'perms':'644'})
           entry.text = '''contents of foo.conf'''

Example Connector
-----------------

.. code-block:: python

    import Bcfg2.Server.Plugin

    class Foo(Bcfg2.Server.Plugin.Plugin,
             Bcfg2.Server.Plugin.Connector):
        '''The Foo plugin is here to illustrate a barebones connector'''
        name = 'Foo'
        version = '$Revision: $'
        experimental = True

        def __init__(self, core, datastore):
            Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore)
            Bcfg2.Server.Plugin.Connector.__init__(self)
            self.store = XMLFileBacked(self.data, core.fam)

        def get_additional_data(self, metadata):

            mydata = {}
            for data in self.store.entries['foo.xml'].data.get("foo", []):

                mydata[data] = "bar"

            return  dict([('mydata', mydata)])

        def get_additional_groups(self, meta):
            return self.cgroups.get(meta.hostname, list())