(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, 111 insertions, 0 deletions

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