From 7c6c1e10f3cc62acc919123d0067a8a9720aeffa Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Sun, 24 Jan 2010 18:47:00 +0000 Subject: doc: Add a lot more unsorted stuff from the wiki Signed-off-by: Sol Jerome git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5703 ce84e21b-d406-0410-9b95-82705330c041 --- doc/unsorted/developing_for_bcfg2.txt | 111 ++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 doc/unsorted/developing_for_bcfg2.txt (limited to 'doc/unsorted/developing_for_bcfg2.txt') 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()) -- cgit v1.2.3-1-g7c22