diff options
author | Narayan Desai <desai@mcs.anl.gov> | 2005-02-14 20:52:58 +0000 |
---|---|---|
committer | Narayan Desai <desai@mcs.anl.gov> | 2005-02-14 20:52:58 +0000 |
commit | 46d519d33e2c50568aa4640252db7edb02222181 (patch) | |
tree | 4c845a9762f798ecf5f7f2dc58179ac0738a2e46 | |
parent | f540f2f06c2c54c5b46b453cdd0b612921fa837b (diff) | |
download | bcfg2-46d519d33e2c50568aa4640252db7edb02222181.tar.gz bcfg2-46d519d33e2c50568aa4640252db7edb02222181.tar.bz2 bcfg2-46d519d33e2c50568aa4640252db7edb02222181.zip |
(Logical change 1.204)
git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@867 ce84e21b-d406-0410-9b95-82705330c041
-rw-r--r-- | doc/concepts.xml | 110 | ||||
-rw-r--r-- | doc/generators.xml | 181 | ||||
-rw-r--r-- | doc/install.xml | 111 | ||||
-rw-r--r-- | doc/manual.xml | 60 |
4 files changed, 462 insertions, 0 deletions
diff --git a/doc/concepts.xml b/doc/concepts.xml index e69de29bb..f8fd60e26 100644 --- a/doc/concepts.xml +++ b/doc/concepts.xml @@ -0,0 +1,110 @@ +<chapter> + <title>Design Goals & Concepts</title> + + <para> + Bcfg2 was designed with several goals in mind. This section will + describe those goals, and how they were manifested in the + design. This section will also define important concepts used in + Bcfg2. + </para> + + <section> + <title>Goals</title> + + <itemizedlist> + <listitem> + <para> + Model configurations using declarative + semantics. Declarative semantics maximize the utility of + configuration management tools; they provide the most + flexibility for the tool to determine the right course of + action in any given situation. This means that users can + focus on the task of describing the desired configuration, + while leaving the task of transitioning clients states to + the tool. + </para> + </listitem> + <listitem> + <para> + Configuration descriptions should be comprehensive. This + means that configurations served to the client should be + sufficent to reproduce all desired functionality. This + assumption allows the use of heuristics to detect extra + configuration, aiding in reliable, comprehensive + configuration definitions. + </para> + </listitem> + <listitem> + <para> + Provide a flexible approach to user interactions. Most + configuration management systems take a rigid approach to + user interactions; that is, either the client system is + always correct, or the central system is. This means that + users are forced into an overly proscribed model where the + system asserts where correct data is. Configuration data + modification is frequently undertaken on both the + configuration server and clients. Hence, the existance of a + single canonical data location can easily pose a problem + during normal tool use. + </para> + <para> + Bcfg2 takes a different approach. The default assumption is + that data on the server is correct, however, the client has + options to run in two other modes. If the Bcfg2 client is + run in dry run mode, it can help to reconcile differences + between current client state and the configuration described + on the server. + </para> + <para> + The Bcfg2 client also searches for extra configuration; that + is, configuration that is not specified by the configuration + description. When extra configuration is found, either + configuration has been removed from the configuration + description on the server, or manual configuration has + occurred on the client. Options related to two-way + verification and removal are useful for configuration + reconciliation when interactive access is used. + </para> + </listitem> + <listitem> + <para> + Generators, and administrative applications. + </para> + </listitem> + <listitem> + <para> + Imcremental operations. + </para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Important Concepts</title> + <variablelist> + <varlistentry> + <term>Bundles</term> + <listitem> + <para> + Bundles are groups of interdependent configuration + elements. Service configurations including software, + configuration files, and service activations are a good + example of bundles. When any of these components are + modified, all should be re-checked, and any associated + services should be restarted. We refer to this process as + coherent reconfiguration; this guarentees that all + configuration changes are active before reconfiguration + has completed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Metadata</term> + <listitem> + <para/> + </listitem> + </varlistentry> + </variablelist> + </section> + +</chapter>
\ No newline at end of file diff --git a/doc/generators.xml b/doc/generators.xml index e69de29bb..ee7a6a8be 100644 --- a/doc/generators.xml +++ b/doc/generators.xml @@ -0,0 +1,181 @@ +<chapter> + <title>Generators</title> + + <para>Generators are modules are are loaded by the Bcfg2 server, + based on directives in <filename>/etc/bcfg2.conf</filename>. They + provide concrete, fully-specified configuration entries for + clients. This chapter documents the function and usage of generators + bundled with Bcfg2 releases. It also describes the interface used to + communicate with generators; modeles implementing this interface can + provide configuration elements for clients based on any + representation or requirements that may exist. + </para> + + <section> + <title>Bundled Generators</title> + + <para>This section describes the generators that come bundled with + Bcfg2. As a general rule, generators requiring more than one + configuration file will use a generator specific directory in the + configuration repository. + </para> + + <section> + <title>Cfg</title> + <para> + The Cfg generator provides a configuration file repository + that uses literal file contents to provide client-tailored + configuration file entries. The Cfg generator chooses which + data to provide for a given client based on the aspect-based + metadata system used for high-level client configuration. + </para> + <para> + The Cfg repository is structured much like the filesystem + hierarchy being configured. Each configuration file being + served has a corresponding directory in the configuration + repository. These directories have the same relative path as + the absolute path of the configuration file on the target + system. For example, if Cfg was serving data for the + configuration file <filename>/etc/services</filename>, then + its directory would be in the relative path + <filename>./etc/services</filename> inside of the Cfg + repository. + </para> + <para> + Inside of this file-specific directory, three types of files + may exist. Base files are complete instances of configuration + file. Deltas are differences between a base file and the + target file contents. Base files and deltas are tagged with + metadata specifiers, which describe which groups of clients + the fragment pertains to. Configuration files are constructed + by finding the most specific base file and applying any more + specific deltas. + </para> + <para> + Specifiers are embedded in fragment filenames. For example, in + the fragment <filename>services.C99_webserver</filename>, + "C99_webserver" is the specifier. This specifier applies to + the class (C) webserver with a priority of 99. Other metadata + categories which can be used include bundle (B), profile (P), + hostname (H), attribute (A), and image (I). These are ordered + from least to most specific: image, profile, class, bundle, + and hostname. Global files are the least specific. Priorities + are used as to break ties. + </para> + <para> + Info files, named <filename>:info</filename> are used to + specify target configuration file metadata, such as owner, + group and permissions. If no <filename>:info</filename> is + provided, targets are installed with default + information. Default metadata is root ownership, root group + memberships, and 0644 file permissions. + </para> + <example> + <title>Cfg generator :info files</title> + <programlisting> + owner:root + group:root + perms:0755 + </programlisting> + </example> + + <example> + <title>Cfg file repository example</title> + <programlisting> + $ ls + :info passwd passwd.C99_chiba-login + passwd.H_bio-debian passwd.H_cvstest passwd.H_foxtrot + passwd.H_reboot passwd.H_rudy2 passwd.C99_netserv + passwd.B99_tacacs-server.cat passwd.H_adenine + </programlisting> + </example> + + <para> + In the previous example, there exists files with each of the + characteristics mentioned above. All files ending in ".cat" + are deltas; ones with ".H_" are host specific files. There + exists a base file, a <filename>:info</filename> file, two + class-specified base files, and a bundle-specified base file. + </para> + </section> + + <section> + <title>Pkgmgr</title> + <para/> + </section> + + </section> + + <section> + <title>The Generator API</title> + <para> + The Bcfg2 core has a well-formed API used to call + generators. This mechanism allows all stock generators to be + runtime selected; no stock generators are required. The + generator API has two main functions. The first is communication + to the Bcfg2 core: the list of entries a particular generator + can bind must be communicated to the core so that the proper + generator can be called. The second function is the actual + production of client-specific configuration element data; this + data is then included in client configurations. + </para> + + <para> + The inventory function is provided by a python dictionary, + called __provides__ in each generator object. This dictionary + has a key for each type of configuration entry (ConfigFile, + Package, Directory, SymLink, Service), whose value is a + dictionary indexed by configuration element name. For example, + the data path to information about the service "sshd" could be + reached at __provides__['Service']['sshd']. The value of each of + these keys is a function that can be called to bind + client-specific values to a configuration entry. This function + is used in the next section. + </para> + + <para> + The handler function located by the __provides__ dictionary is + called with a static API. The function prototype for each of + these handlers is: + </para> + + <example> + <title>The Generator handler API</title> + <programlisting> + def Handler(self, entry, metadata): + generator logic here + </programlisting> + </example> + + <para> + The data supplied upon handler invokation includes two + parts. The first is the entry. This is a ElementTree.Element + object, which already contains the configuration element type + (ie Service) and name. All other data is bound into this object + in this function. The range of data bound depends on the data + type. The other data provided to handlers is client metadata, + information about the current client, including hostname, image, + profile, classes and bundles. The metadata is typically used to + choose entry contents. + </para> + </section> + + <section> + <title>Writing a Generator</title> + <para> + Writing a generator is a fairly straightforward task. At a high + level, generators are instantiated by the Bcfg2 core, and then + used to provide configuration entry contents. This means that + the two points where control passes into a generator from Bcfg2 + are during initial object instantiation, and every time a + generator-provided configuration entry is bound. + </para> + + <para> + Currently, generators must be written in python. They can + perform arbitrary operations, hence, a generator could be + written that executed logic in another language, but this + functionality is currently not implemented. + </para> + </section> +</chapter>
\ No newline at end of file diff --git a/doc/install.xml b/doc/install.xml index e69de29bb..83c7d824e 100644 --- a/doc/install.xml +++ b/doc/install.xml @@ -0,0 +1,111 @@ +<chapter> + <title>Installing Bcfg2</title> + + <sect1> + <title>Pre-requisites</title> + <para> + Bcfg2 is written in python using several modules not included + with most distributions. SSSlib, available from + ftp://ftp.mcs.anl.gov/pub/sss/, provides communication + abstraction. Element Tree, available from http://www.effbot.org + provides convenient XML handling. Bcfg2 uses FAM to coherently + cache files and update them when they change. + </para> + <para>ElementTree can be downloaded from + http://www.effbot.org/downloads. It can be installed by running + the setup script against the python installation. + </para> + + <programlisting>$ python setup.py build +running build +running build_py +creating build +creating build/lib +creating build/lib/elementtree +copying elementtree/ElementInclude.py -> build/lib/elementtree +copying elementtree/ElementPath.py -> build/lib/elementtree +copying elementtree/ElementTree.py -> build/lib/elementtree +copying elementtree/HTMLTreeBuilder.py -> build/lib/elementtree +copying elementtree/SgmlopXMLTreeBuilder.py -> build/lib/elementtree +copying elementtree/SimpleXMLTreeBuilder.py -> build/lib/elementtree +copying elementtree/SimpleXMLWriter.py -> build/lib/elementtree +copying elementtree/TidyHTMLTreeBuilder.py -> build/lib/elementtree +copying elementtree/TidyTools.py -> build/lib/elementtree +copying elementtree/XMLTreeBuilder.py -> build/lib/elementtree +copying elementtree/__init__.py -> build/lib/elementtree +$ python setup.py install +... + </programlisting> + <para>SSSlib can be downloaded from + ftp://ftp.mcs.anl.gov/pub/sss. It can either be built from source + or prebuilt packages can be downloaded from the same location. + </para> + </sect1> + <sect1> + <title>Bcfg2 Installation</title> + <para> + </para> + </sect1> + <sect1> + <title>Bcfg2 Initial Setup and Testing</title> + <para>Once the Bcfg2 software is installed, the configuration file + and repository must be created. The example configuration file in + <filename>bcfg2/examples/bcfg2.conf</filename> can be used, with + minor modifications. + </para> + <example> + <title>bcfg2.conf</title> + <programlisting>[server] + repository = /disks/bcfg2 + structures = Bundler,Base + generators = SSHbase,Cfg,Pkgmgr,Svcmgr + metadata = /disks/bcfg2/etc + </programlisting> + </example> + <para>This configuration file sets the location of the + configuration repository. It also activates two structures, and + four generators. Structures are components that generate + abstract configuration fragments. These are the form of the + configuration. Generators provide client-specific values for + each configuration settings contained in all abstract + configuration fragments. Both of these are described in Section + ???.</para> + </sect1> + <sect1> + <title>Daemon Configuration</title> + <para>Bcfg2 uses SSSlib, the + communication libraries from the Scalable Systems Software project + for communication abstraction. This library provides a unified + messaging interface on top of several wire protocols with + different authentication and encryption mechanisms. The default + protocol is "challenge" which is a challenge response protocol + with no data encryption. (SSL protection will be configured + later). SSSlib also includes service location functionality; + this allows software to locate components by name, regardless of + their respective network locations. This function is provided + with both static and dynamic implementations. Static component + location setup will be sufficient for most Bcfg2 deployments. + </para> + + <para> + Static component lookups depend on the file + <filename>/etc/sss.conf</filename>. This file contains + information about static service locations. This file must be + the same on the server and all clients for communication to work + properly. A location definition for the bcfg2 component will + allow all clients to find and connect to it. + </para> + <example> + <title>/etc/sss.conf</title> + <programlisting> + <![CDATA[ <locations> + <location component="bcfg2" host="bcfgserver" + port="8052" protocol="challenge" schema_version="1.0" tier="1"/> + </locations>]]> + </programlisting> + </example> + <para>This allows SSSlib to locate the bcfg2 component on the + machine bcfgserver, port 8052, with the wire protocol "challenge". + </para> + </sect1> +</chapter>
\ No newline at end of file diff --git a/doc/manual.xml b/doc/manual.xml index e69de29bb..159f98d3b 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -0,0 +1,60 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[ +<!ENTITY concepts SYSTEM "concepts.xml"> +<!ENTITY install SYSTEM "install.xml"> +<!ENTITY generators SYSTEM "generators.xml"> +]> +<book id="bcfg2"> + <bookinfo> + <title>Bcfg2 Manual</title> + <author> + <firstname>Narayan</firstname> + <surname>Desai</surname> + <email>desai@mcs.anl.gov</email> + </author> + <affiliation> + <orgname>Argonne National Laboratory</orgname> + <orgdiv>MCS Division</orgdiv> + </affiliation> + <date>February 2, 2005</date> + <releaseinfo>$Revision$</releaseinfo> + <pubdate>February 2005</pubdate> + <copyright> + <year>2005</year> + <holder>Argonne National Laboratory</holder> + </copyright> + + <legalnotice> + <para> + This manual is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + </para> + <para> + This is distributed in the hope that it will be useful, + but <emphasis>without any warranty</emphasis>; without even the + implied warranty of <emphasis>merchantability</emphasis> or + <emphasis>fitness for a particular purpose</emphasis>. See the + GNU General Public License for more details. + </para> + </legalnotice> + + <revhistory> + <revision> + <revnumber>0.6.4</revnumber> + <date>2005/02/01 11:38:27</date> + <revremark> + $Id$ + </revremark> + </revision> + </revhistory> + </bookinfo> + + <toc/> + +&concepts; +&install; +&generators; +</book>
\ No newline at end of file |