There are many ways to get involved in Bcfg2 development. Here we will outline some things that can help you get familiar with the various areas of the Bcfg2 code.
Check out a copy of the code:
svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2
Create link to src/lib:
cd bcfg2
ln -s src/lib Bcfg2
Add bcfg2/src/sbin to your PATH environment variable
Add bcfg2 to your PYTHONPATH environment variable
This page describes the step-by-step process of writing a client tool driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it.
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 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. |
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 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 |
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'''
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())
Generator plugins contribute to literal client configurations
Structure Plugins contribute to abstract client configurations
Signal metadata capabilities
Connector Plugins augment client metadata instances
Signal probe capability
Signal statistics handling capability
Signal decision handling capability
Interact with various version control systems
If you would like to define your own Metadata plugin (to extend/change functionality of the existing Metadata plugin), here are the steps to do so. We will call our new plugin MyMetadata.
Add MyMetadata.py
__revision__ = '$Revision$'
import Bcfg2.Server.Plugins.Metadata
class MyMetadata(Bcfg2.Server.Plugins.Metadata.Metadata):
'''This class contains data for bcfg2 server metadata'''
__version__ = '$Id$'
__author__ = 'bcfg-dev@mcs.anl.gov'
def __init__(self, core, datastore, watch_clients=True):
Bcfg2.Server.Plugins.Metadata.Metadata.__init__(self, core, datastore, watch_clients)
Add MyMetadata to src/lib/Server/Plugins/__init__.py
Replace Metadata with MyMetadata in the plugins line of bcfg2.conf
One of the areas where everyone can help is with the documentation. Insert verbiage on how people can help.