(Logical change 1.204)

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@867 ce84e21b-d406-0410-9b95-82705330c041

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