diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/client-driver.txt | 16 | ||||
| -rw-r--r-- | doc/development/documentation.txt | 37 | ||||
| -rw-r--r-- | doc/development/emacs_snippet.txt | 60 | ||||
| -rw-r--r-- | doc/development/index.txt | 25 | ||||
| -rw-r--r-- | doc/development/plugin-types.txt | 46 | ||||
| -rw-r--r-- | doc/development/plugins.txt | 172 | ||||
| -rw-r--r-- | doc/development/server.txt | 83 | ||||
| -rw-r--r-- | doc/development/setup.txt | 2 | ||||
| -rw-r--r-- | doc/development/vim_snippet.txt | 65 | ||||
| -rw-r--r-- | doc/development/writing_plugins.txt | 104 | ||||
| -rw-r--r-- | doc/development/writing_specification.txt | 54 |
11 files changed, 201 insertions, 463 deletions
diff --git a/doc/development/client-driver.txt b/doc/development/client-driver.txt index 19da9cb67..cc065dd32 100644 --- a/doc/development/client-driver.txt +++ b/doc/development/client-driver.txt @@ -10,20 +10,20 @@ driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it. #. Pick a name for the driver. In this case, we picked the name RPM. -#. Add "RPM" to the ``__all__ list`` in ``src/lib/Client/Tools/__init__.py`` +#. Add "RPM" to the ``__all__`` list in ``src/lib/Client/Tools/__init__.py`` #. Create a file in ``src/lib/Client/Tools`` with the same name (RPM.py) -#. Create a class in this file with the same name (``class RPM``) +#. Create a class in this file with the same name (class RPM) - * If it handles ``Package`` entries, subclass ``Bcfg2.Client.Tools.PkgTool`` + * If it handles **Package** entries, subclass ``Bcfg2.Client.Tools.PkgTool`` (from here referenced as branch [P]) - * If it handles ``Service`` entries, subclass ``Bcfg2.Client.Tools.SvcTool`` + * If it handles **Service** entries, subclass ``Bcfg2.Client.Tools.SvcTool`` (from here referenced as branch [S]) - * Otherwise, ``subclass Bcfg2.Client.Tools.Tool`` (from here referenced + * Otherwise, subclass ``Bcfg2.Client.Tools.Tool`` (from here referenced as branch [T]) #. Set ``__name__`` to "RPM" #. Add any required executable programs to ``__execs__`` -#. Set ``__handles__`` to a list of (``entry.tag``, ``entry.get('type')``) +#. Set ``__handles__`` to a list of (**entry.tag**, **entry.get('type')**) tuples. This determines which entries the Tool module can be used on. In this case, we set ``__handles__ = [('Package', 'rpm')]``. #. Add verification. This method should return True/False depending @@ -46,9 +46,9 @@ an existing driver, and the process that was used to create it. all-at-once installations, followed, in the case of failures, by single installations. To enable this support, set the pkgtype attribute to the package type handled by this driver. Set the - ``pkgtool`` to a tuple ("command string %s", ("per-package string + pkgtool to a tuple ("command string %s", ("per-package string format", [list of package entry fields])). For RPM, we have - ``setup pkgtool = ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))`` + setup ``pkgtool = ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))`` #. Implement entry removal diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt index 8223670b8..0f75b9bba 100644 --- a/doc/development/documentation.txt +++ b/doc/development/documentation.txt @@ -19,22 +19,23 @@ The wiki .. _MCS: http://www.mcs.anl.gov/ .. _Argonne National Laboratory: http://www.anl.gov/ -A python-based Trac_ instance is used for the Bcfg2 website. The -Wiki_ part of the website can be edited after you have successful -logged in. For the login is a vaild OpenID provider needed and an -interaction from an administrator. Please request your access to -the Wiki_ on the :ref:`mailinglist` or in the :ref:`ircchannel`. +A python-based Trac_ instance is used for the Bcfg2 development +website. The Wiki_ part of the website can be edited after you +have successfully logged in. In order to login, a vaild OpenID +provider is needed. Please request your access to the Wiki_ on the +:ref:`help-mailinglist` or in the :ref:`help-irc`. The manual ---------- .. _rst: http://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: http://sphinx.pocoo.org -.. _Docutils: +.. _Docutils: -The source for the manual is located in the `doc/` directory in the -SVN repository or in the source tarball. All files are written in -rst_ (ReStructuredText). For the build process we are using Sphinx_. +The source for the manual is located in the ``doc/`` directory in the +git repository or in the source tarball. All files are written in +rst_ (ReStructuredText) format. Sphinx_ is used to build the +documentation from the restructured text sources. Building the Manual ^^^^^^^^^^^^^^^^^^^ @@ -42,7 +43,7 @@ Building the Manual * Install the prerequisites. Docutils_ and Sphinx_ are needed to build. * For Debian (Lenny) the tools are available in the `backports <http://www.backports.org/dokuwiki/doku.php?id=instructionst>`_ repository; installation can be done with the following:: - + apt-get -t lenny-backports install python-sphinx * The needed tools for Fedora based systems are in the `Fedora Package Collection <https://admin.fedoraproject.org/pkgdb>`_; installation can be done easily with Yum:: @@ -56,20 +57,14 @@ Building the Manual * Download the source. Please refer to :ref:`source` for more details. -* Building the HTML version, run the following command in the `doc/` directory. The output will appear in `../build/sphinx/html`:: +* Build the HTML version by running the following command in the + top level of the source directory. The output will appear in + ``build/sphinx/html``:: python setup.py build_sphinx * Building the PDF version :: - - python setup.py build_sphinx --builder=latex + + python setup.py build_sphinx --builder=latex cd build/sphinx/latex make - -The latest version of the manual -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The latest version of the manual can always be found -`on the Four Kitchens server <http://doc.bcfg2.fourkitchens.com/>`_. - -This is an auto-updated from the `Launchpad mirror <https://code.launchpad.net/~vcs-imports/bcfg2/trunk>`_. diff --git a/doc/development/emacs_snippet.txt b/doc/development/emacs_snippet.txt deleted file mode 100644 index 2905a2b45..000000000 --- a/doc/development/emacs_snippet.txt +++ /dev/null @@ -1,60 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-emacs_snippet: - -====================== -Emacs + YASnippet mode -====================== - -This page describes using emacs with YASnippet mode with a set of -snippets that allow quick composition of bundles and base files. -More snippets are under development. - -#. Download YASnippet from http://code.google.com/p/yasnippet/ -#. Install it into your emacs load path (typically ~/.emacs.d/site-lisp) -#. Add YASnippet initialization to your .emacs (remember to re-byte-compile it if needed) - - .. code-block:: cl - - (require 'yasnippet-bundle) - - ;;; Bcfg2 snippet - - (yas/define-snippets 'sgml-mode - '( - ("<Bundle" "<Bundle name='${1:bundlename}' version='2.0'> - $0 - </Bundle>" nil) - ("<Base" "<Base> - $0 - </Base>" nil) - ("<Group" "<Group name='${1:groupname}> - $0 - </Group>" nil) - ("<Config" "<ConfigFile name='${1:filename}'/> - $0" nil) - ("<Service" "<Service name='${1:svcname}'/> - $0" nil) - ("<Package" "<Package name='${1:packagename}'/> - $0" nil) - ("<Action" "<Action name='${1:name}'/> - $0" nil) - ("<Directory" "<Directory name='${1:name}'/> - $0" nil) - ("<SymLink" "<SymLink name='${1:name}'/> - $0" nil) - ("<Permissions" "<Permissions name='${1:name}'/> - $0" nil) - ) - ) - -#. One quick M-x eval-current-buffer, and this code is enabled - -Each of these snippets activates on the opening element, ie <Bundle. -After this string is entered, but before entering a space, press <TAB>, -and the snippet will be expanded. The template will be inserted into -the text with a set of input prompts, which default to overwrite mode -and can be tabbed through. - -The code above only works for bundles and base, but will be expanded -to support other xml files as well. diff --git a/doc/development/index.txt b/doc/development/index.txt index 222978c98..352000dc8 100644 --- a/doc/development/index.txt +++ b/doc/development/index.txt @@ -6,19 +6,12 @@ Bcfg2 Development ================= -There are several ways users can contribute to the Bcfg2 project. +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. -* Developing code -* Testing prereleases -* Reporting bugs -* Adding to the common repository -* Improving the wiki and writing documentation - -This section will outline some things that can help you get familiar -with the various areas of the Bcfg2 code. - -Send patches to the :ref:`mailinglist` or create a trac +Send patches to the :ref:`help-mailinglist` or create a trac `ticket <https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_ with the patch included. In order to submit a ticket via the trac system, you will need to create a session by clicking on the @@ -33,22 +26,16 @@ The source tree can be checked out by running:: git clone git://git.mcs.anl.gov/bcfg2.git Users wishing to contribute on a regular basis can apply for direct -git access. Mail the :ref:`mailinglist` for details. +git access. Mail the :ref:`help-mailinglist` for details. .. toctree:: :maxdepth: 1 - + tips setup client-driver plugins - writing_plugins - plugin-types - writing_specification - server testing documentation docstyleguide - emacs_snippet - vim_snippet diff --git a/doc/development/plugin-types.txt b/doc/development/plugin-types.txt deleted file mode 100644 index 5f0a4771a..000000000 --- a/doc/development/plugin-types.txt +++ /dev/null @@ -1,46 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-plugin-types: - -Server Plugin Types -------------------- - -Generator -^^^^^^^^^ - -Generator plugins contribute to literal client configurations - -Structure -^^^^^^^^^ - -Structure Plugins contribute to abstract client configurations - -Metadata -^^^^^^^^ - -Signal metadata capabilities - -Connector -^^^^^^^^^ - -Connector Plugins augment client metadata instances - -Probing -^^^^^^^ - -Signal probe capability - -Statistics -^^^^^^^^^^ - -Signal statistics handling capability - -Decision -^^^^^^^^ - -Signal decision handling capability - -Version -^^^^^^^ - -Interact with various version control systems diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index b6debba24..709b9fcec 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -3,7 +3,7 @@ .. _development-plugins: Bcfg2 Plugin development ------------------------- +======================== While the Bcfg2 server provides a good interface for representing general system configurations, its plugin interface offers the ability @@ -12,7 +12,7 @@ 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 @@ -43,3 +43,171 @@ The following table describes the various functions of bcfg2 plugins. | | expose internal functions. | +--------------------+---------------------------------------------+ +Server Plugin Types +------------------- + +Generator +^^^^^^^^^ + +Generator plugins contribute to literal client configurations + +Structure +^^^^^^^^^ + +Structure Plugins contribute to abstract client configurations + +Metadata +^^^^^^^^ + +Signal metadata capabilities + +Connector +^^^^^^^^^ + +Connector Plugins augment client metadata instances + +Probing +^^^^^^^ + +Signal probe capability + +Statistics +^^^^^^^^^^ + +Signal statistics handling capability + +Decision +^^^^^^^^ + +Signal decision handling capability + +Version +^^^^^^^ + +Interact with various version control systems + +Writing Bcfg2 Server 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()) + +Example Metadata plugin +^^^^^^^^^^^^^^^^^^^^^^^ + +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 + + .. code-block:: python + + __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 diff --git a/doc/development/server.txt b/doc/development/server.txt deleted file mode 100644 index 0f594422e..000000000 --- a/doc/development/server.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-server-plugins: - -Writing Server Plugins ----------------------- - -Metadata -^^^^^^^^ - -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 - - .. code-block:: python - - __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 - -.. _development-server-packages: - -Packages --------- - -In order to support a given client package tool driver, that driver -must support use of the auto value for the version attribute in Package -entries. In this case, the tool driver views the current state of -available packages, and uses the underlying package manager's choice of -correct package version in lieu of an explicit, centrally-specified, -version. This support enables Packages to provide a list of Package -entries with version='auto'. Currently, the APT and YUMng drivers support -this feature. Note that package management systems without any network -support cannot operate in this fashion, so RPMng and SYSV will never be -able to use Packages. Emerge, Zypper, IPS, and Blastwave all have the -needed features to be supported by Packages, but support has not yet -been written. - -Packages fills two major functions in configuration generation. The first -is to provide entry level binding support for Package entries included -in client configurations. This function is quite easy to implement; -Packages determines (based on client group membership) if the package -is available for the client system, and which type it has. Because -version='auto' is used, no version determination needs to be done. - -The second major function is more complex. Packages ensures that client -configurations include all package-level prerequisites for package entries -explicitly included in the configuration. In order to support this, -Packages needs to directly process network data for package management -systems (the network sources for apt or yum, for examples), process -these files, and build data structures describing prerequisites and the -providers of those functions/paths. To simplify implementations of this, -there is a generic base class (Bcfg2.Server.Plugins.Packages.Source) -that provides a framework for fetching network data via HTTP, processing -those sources (with subclass defined methods for processing the specific -format provided by the tool), a generic dependency resolution method, -and a caching mechanism that greatly speeds up server/bcfg2-info startup. - -Each source type must define: - -* a get_urls attribute (and associated urls property) that describes - the URLS where to get data from. -* a read_files method that reads and processes the downloaded files - -Sources may define a get_provides method, if provides are complex. For -example, provides in rpm can be either rpm names or file paths, so -multiple data sources need to be multiplexed. - -The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a -relatively simple implementation of a source. diff --git a/doc/development/setup.txt b/doc/development/setup.txt index 08a85dac1..8729ee76e 100644 --- a/doc/development/setup.txt +++ b/doc/development/setup.txt @@ -8,7 +8,7 @@ Environment setup for development * Check out a copy of the code:: - svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 + git clone git://git.mcs.anl.gov/bcfg2.git * Create link to ``src/lib``:: diff --git a/doc/development/vim_snippet.txt b/doc/development/vim_snippet.txt deleted file mode 100644 index a01c1cfda..000000000 --- a/doc/development/vim_snippet.txt +++ /dev/null @@ -1,65 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-vim_snippet: - -=================== -Vim Snippet Support -=================== - -This page describes using vim with snipMate and a set of snippets -that allow quick composition of bundles and base files. - -#. Download snipMate from http://www.vim.org/scripts/script.php?script_id=2540 -#. Install it using the install instructions (unzip snipMate.zip -d ~/.vim or equivalent, e.g. $HOME\vimfiles on Windows) -#. Add the following to ``~/.vim/snippets/xml.snippets`` - - .. code-block:: cl - - # Bundle - snippet <Bundle - <Bundle name='${1:bundlename}'> - ${2} - </Bundle> - # Base - snippet <Base - <Base> - ${1} - </Base> - # Group - snippet <Group - <Group name='${1:groupname}'> - ${2} - </Group> - # ConfigFile - snippet <Config - <ConfigFile name='${1:filename}'/> - # Service - snippet <Service - <Service name='${1:svcname}'/> - # Package - snippet <Package - <Package name='${1:packagename}'/> - # Action - snippet <Action - <Action name='${1:name}'/> - # Directory - snippet <Directory - <Directory name='${1:name}'/> - # SymLink - snippet <SymLink - <SymLink name='${1:name}'/> - # Permissions - snippet <Permissions - <Permissions name='${1:name}'/> - - -#. Save and start editing away! - -Each of these snippets activates on the opening element, ie <Bundle>. -After this string is entered, but before entering a space, press <TAB>, -and the snippet will be expanded. The template will be inserted into -the text with a set of input prompts, which default to overwrite mode -and can be tabbed through. - -The code above only works for bundles and base, but will be expanded -to support other xml files as well. diff --git a/doc/development/writing_plugins.txt b/doc/development/writing_plugins.txt deleted file mode 100644 index 40e077e43..000000000 --- a/doc/development/writing_plugins.txt +++ /dev/null @@ -1,104 +0,0 @@ -.. -*- 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()) - diff --git a/doc/development/writing_specification.txt b/doc/development/writing_specification.txt deleted file mode 100644 index 4e1c03483..000000000 --- a/doc/development/writing_specification.txt +++ /dev/null @@ -1,54 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-writing_specification: - -=========================== -Writing Bcfg2 Specification -=========================== - -Bcfg2 specifications are logically divided in to three areas: - -* Metadata -* Abstract -* Literal - -The metadata portion of the configuration assigns a client to its profile -group and to its non-profile groups. The profile group is assigned -in ``Metadata/clients.xml`` and the non profile group assignments are in -``Metadata/groups.xml``. - -The group memberships contained in the metadata are then used to constuct -an abstract configuration for the client. An abstract configuration for -a client identifies the configuration entities (packages, configuration -files, service, etc) that a client requires, but it does not identify -them explicitly. For instance an abstract configuration may identify -that a client needs the Bcfg2 package with - -.. code-block:: xml - - <Package name=bcfg2/> - -but this does not explicitly identify that an RPM package version -0.9.2 should be loaded from http://rpm.repo.server/bcfg2-1.0.1-0.1.rpm. -The abstract configuration is defined in the xml configuration files -for the Base and Bundles plugins. - -A combination of a clients metadata (group memberships) and abstract -configuration is then used to generate the clients literal configuration. -For instance the above abstract configuration entry may generate a -literal configuration of - - -.. code-block:: xml - - <Package name='bcfg2' version='1.0.1-0.1' type='yum'/> - -A clients literal configuration is generated by a number of plugins that -handle the different configuration entities. - - -.. figure:: specification_overview.png - :width: 60% - :alt: Specification overview - :align: center - |