summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNarayan Desai <desai@mcs.anl.gov>2005-02-14 20:52:58 +0000
committerNarayan Desai <desai@mcs.anl.gov>2005-02-14 20:52:58 +0000
commit46d519d33e2c50568aa4640252db7edb02222181 (patch)
tree4c845a9762f798ecf5f7f2dc58179ac0738a2e46
parentf540f2f06c2c54c5b46b453cdd0b612921fa837b (diff)
downloadbcfg2-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.xml110
-rw-r--r--doc/generators.xml181
-rw-r--r--doc/install.xml111
-rw-r--r--doc/manual.xml60
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