From 391406c85d86dc931f3fdb2483a14d0f1e7e6355 Mon Sep 17 00:00:00 2001
From: Fabian Affolter <fabian@bernewireless.net>
Date: Tue, 9 Nov 2010 00:15:43 +0100
Subject: doc: Massive update

---
 doc/development/server.txt | 83 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 doc/development/server.txt

(limited to 'doc/development/server.txt')

diff --git a/doc/development/server.txt b/doc/development/server.txt
new file mode 100644
index 000000000..0f594422e
--- /dev/null
+++ b/doc/development/server.txt
@@ -0,0 +1,83 @@
+.. -*- 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.
-- 
cgit v1.2.3-1-g7c22