.. -*- mode: rst -*-

.. _development-plugins:

Bcfg2 Plugin development
========================

While the Bcfg2 server provides a good interface for representing
general system configurations, its plugin interface offers the ability
to implement configuration interfaces and representation tailored to
problems encountered by a particular site. This chapter describes what
plugins are good for, what they can do, and how to implement them.

Bcfg2 Plugins
-------------

Bcfg2 plugins are loadable python modules that the Bcfg2 server loads at
initialization time. These plugins can contribute to the functions already
offered by the Bcfg2 server or can extend its functionality. In general,
plugins will provide some portion of the configuration for clients, with a
data representation that is tuned for a set of common tasks. Much of the
core functionality of Bcfg2 is implemented by several plugins, however,
they are not special in any way; new plugins could easily supplant one
or all of them.

Server Plugin Types
-------------------

A plugin must implement at least one of the interfaces described
below.  Each interface is available as a class in
:mod:``Bcfg2.Server.Plugin``.  In most cases, a plugin must also
inherit from :class:`Bcfg2.Server.Plugin.Plugin`, which is the base
Plugin object (described below).  Some of the interfaces listed below
are themselves Plugin objects, so your custom plugin would only need
to inherit from the plugin type.

Plugin
^^^^^^

.. autoclass:: Bcfg2.Server.Plugin.Plugin
   :inherited-members:
   :show-inheritance:

   .. automethod:: Bcfg2.Server.Plugin.Plugin.__init__

With the exceptions of :class:`Bcfg2.Server.Plugin.Statistics` and
:class:`Bcfg2.Server.Plugin.ThreadedStatistics`, the plugin interfaces
listed below do **not** inherit from Plugin; they simply provide
interfaces that a given plugin may or must implement.

Interfaces
^^^^^^^^^^

.. automodule:: Bcfg2.Server.Plugin.interfaces

Exposing XML-RPC Functions
--------------------------

Plugins can expose XML-RPC functions that can then be called with
:ref:`bcfg2-admin xcmd <server-admin-xcmd>`.  Note that there is
absolutely no access control beyond the initial authentication, so
take care to not expose any data or behavior via XML-RPC that you
would not want all of your clients to be able to see or use.

To expose a function, simply add its name to the ``__rmi__`` class
attribute.  (RMI stands for "Remote Method Invocation.")  Consider
this example from the :ref:`server-plugins-generators-packages`
plugin:

.. code-block:: python

    class Packages(Bcfg2.Server.Plugin.Plugin,
                   Bcfg2.Server.Plugin.StructureValidator,
                   Bcfg2.Server.Plugin.Generator,
                   Bcfg2.Server.Plugin.Connector,
                   Bcfg2.Server.Plugin.ClientRunHooks):
        name = 'Packages'
        conflicts = ['Pkgmgr']
        __rmi__ = Bcfg2.Server.Plugin.Plugin.__rmi__ + ['Refresh', 'Reload']

    def Refresh(self):
        self._load_config(force_update=True)
        return True

    def Reload(self):
        self._load_config()
        return True

This exposes two functions, ``Refresh`` and ``Reload``, in addition to
any default methods that are already exposed.  To call one of these
functions, you could run::

    bcfg2-admin xcmd Packages.Refresh

Plugin Helper Classes
---------------------

.. automodule:: Bcfg2.Server.Plugin.helpers

Plugin Exceptions
-----------------

.. automodule:: Bcfg2.Server.Plugin.exceptions