From 71c679e1a0105490bd5845a15de5e8f1a32e2166 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 11 Sep 2012 10:32:30 -0400 Subject: Cfg: documented all Cfg modules, added development docs --- doc/development/cfg.txt | 100 +++++++++++++++++++++++++++++++++++++++++++ doc/development/packages.txt | 52 ++++++++++++++++++++++ doc/development/plugins.txt | 14 ++++++ 3 files changed, 166 insertions(+) create mode 100644 doc/development/cfg.txt create mode 100644 doc/development/packages.txt (limited to 'doc/development') diff --git a/doc/development/cfg.txt b/doc/development/cfg.txt new file mode 100644 index 000000000..7d27efb12 --- /dev/null +++ b/doc/development/cfg.txt @@ -0,0 +1,100 @@ +.. -*- mode: rst -*- + +.. _development-cfg: + +========================= + Cfg Handler Development +========================= + +The :ref:`server-plugins-generators-cfg` plugin offers multiple +handlers to handle different entries in different ways. Writing a new +Cfg handler is a relatively simple way to add significant new features +to Cfg. + +Each new Cfg handler must be contained in its own module in +``Bcfg2.Server.Plugins.Cfg``, and the module and class name must be +identical. The name should start with ``Cfg``, and should clearly +indicate which of the handler types it is. A handler class may +implement more than one handler type.a + +Cfg Handler Types +================= + +There are four different types of Cfg handlers. A new handler must +inherit either from one of these classes, or from an existing handler. + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgFilter +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgInfo +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgVerifier + +Cfg Handler Base Class +====================== + +In addition to the interfaces defined above, all Cfg handlers inherit +from CfgBaseFileMatcher. + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher + + +Cfg Exceptions +============== + +Cfg handlers may produce the following exceptions: + +.. autoexception:: Bcfg2.Server.Plugins.Cfg.CfgVerificationError + +In addition, Cfg handlers may produce the following base plugin +exceptions: + +.. autoexception:: Bcfg2.Server.Plugin.exceptions.PluginExecutionError + :noindex: + +.. autoexception:: Bcfg2.Server.Plugin.exceptions.PluginInitError + :noindex: + +Accessing Configuration Options +=============================== + +.. autoattribute:: Bcfg2.Server.Plugins.Cfg.SETUP + +Existing Cfg Handlers +===================== + +Generators +---------- + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgPlaintextGenerator.CfgPlaintextGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.CfgGenshiGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.CfgCheetahGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenshiGenerator.CfgEncryptedGenshiGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedCheetahGenerator.CfgEncryptedCheetahGenerator + +Filters +------- + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgCatFilter.CfgCatFilter +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgDiffFilter.CfgDiffFilter + +Info Handlers +------------- + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgDefaultInfo +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgInfoXML.CfgInfoXML +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgLegacyInfo.CfgLegacyInfo + +Verifiers +--------- + +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgExternalCommandVerifier.CfgExternalCommandVerifier + +Other Cfg Objects +================= + +These other objects comprise the remainder of the Cfg plugin, and are +included for completeness. + +.. autoattribute:: Bcfg2.Server.Plugins.Cfg.DEFAULT_INFO +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEntrySet +.. autoclass:: Bcfg2.Server.Plugins.Cfg.Cfg diff --git a/doc/development/packages.txt b/doc/development/packages.txt new file mode 100644 index 000000000..f85bced38 --- /dev/null +++ b/doc/development/packages.txt @@ -0,0 +1,52 @@ +Developing for Packages +======================= + +.. note:: + + This data is old and incomplete, and needs badly to be rewritten. + +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/plugins.txt b/doc/development/plugins.txt index 59582e255..183126053 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -11,6 +11,18 @@ 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. +Several plugins themselves have pluggable backends, and for narrow +cases you may want to develop a backend for an existing plugin rather +than an entirely new plugin. See the following pages for more +information: + +.. toctree:: + :maxdepth: 1 + + cfg + packages + + Bcfg2 Plugins ------------- @@ -41,6 +53,8 @@ Plugin ^^^^^^ .. autoclass:: Bcfg2.Server.Plugin.base.Plugin + :members: name, __author__, experimental, deprecated, conflicts, + sort_order, __rmi__, init_repo, shutdown :inherited-members: :show-inheritance: -- cgit v1.2.3-1-g7c22