1 files changed, 111 insertions, 0 deletions
diff --git a/doc/unsorted/developing_for_bcfg2.txt b/doc/unsorted/developing_for_bcfg2.txt
new file mode 100644
index 000000000..39582b520
--- /dev/null
+++ b/doc/unsorted/developing_for_bcfg2.txt
@@ -0,0 +1,111 @@
+.. -*- mode: rst -*-
+
+.. _unsorted-developing_for_bcfg2:
+
+====================
+Developing For Bcfg2
+====================
+
+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.
+
+The following table describes the various functions of bcfg2 plugins.
+
+|| '' '''Name''' '' || '' '''Description''' '' ||
+|| Probes || Plugins can issue commands to collect client-side state (like hardware inventory) to include in client configurations ||
+|| !ConfigurationEntry List || Plugins can construct a list of per-client configuration entry lists to include in client configurations. ||
+|| !ConfigurationEntry contents || Literal values for configuration entries. ||
+|| XML-RPC functions || Plugins can export function calls that expose internal functions. ||
+
+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 tied to revctl keyword expansion). || string ||
+|| __author__ || The plugin author. || string ||
+|| __rmi__ || Set of functions to be exposed as XML-RPC functions || List of function names (strings) ||
+|| Entries || Multidimentional dictionary of keys that point to the function [[BR]] used to bind literal contents for a given configuration entity. || Dictionary of !ConfigurationEntityType, Name keys and function reference values ||
+|| !BuildStructures || Function that returns a list of the structures for a given client	|| Member function ||
+|| !GetProbes || Function that returns a list of probes that a given client should execute || Member function ||
+|| !ReceiveData || Function that accepts the probe results for a given client. || Member function ||
+
+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 = {'ConfigFile':{'/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({'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())