(Logical change 1.204)

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

1 files changed, 110 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