summaryrefslogtreecommitdiffstats
path: root/doc/install.xml
diff options
context:
space:
mode:
authorNarayan Desai <desai@mcs.anl.gov>2006-01-23 22:35:40 +0000
committerNarayan Desai <desai@mcs.anl.gov>2006-01-23 22:35:40 +0000
commitedca0b698637c3fd0a70af7e4752a46afca938d3 (patch)
tree658fad717833200ccb4e3725c811ccce7c10fc8d /doc/install.xml
parent8ca8a153dfc6bd81ede9f5cff1ee3f111ae053ee (diff)
downloadbcfg2-edca0b698637c3fd0a70af7e4752a46afca938d3.tar.gz
bcfg2-edca0b698637c3fd0a70af7e4752a46afca938d3.tar.bz2
bcfg2-edca0b698637c3fd0a70af7e4752a46afca938d3.zip
last step of repo switches
git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@1716 ce84e21b-d406-0410-9b95-82705330c041
Diffstat (limited to 'doc/install.xml')
-rw-r--r--doc/install.xml197
1 files changed, 87 insertions, 110 deletions
diff --git a/doc/install.xml b/doc/install.xml
index 13cf2847f..27b88c636 100644
--- a/doc/install.xml
+++ b/doc/install.xml
@@ -5,8 +5,8 @@
<title>Pre-requisites</title>
<para>
Bcfg2 is written in python using several modules not included
- with most distributions. Element Tree, available from
- http://www.effbot.org provides convenient XML handling.
+ with most distributions. lxml provides convenient xml
+ handling. M2crypto wraps openssl calls for https support.
</para>
<para>
@@ -16,125 +16,95 @@
use SSL functions.
</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>lxml is required for xml parsing. It can be downloaded from
+ http://www.codespeak.net/lxml. It, in turn, requires libxml2,
+ libxslt, and pyrex.
</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>
The python fam binding can be downloaded from
python-fam.sourceforge.net. FAM (on several linux distributions)
has been depricated in favor of gamin. The Bcfg server will
autodetect which modules are available, and use appropriate file
- caching logic.
- </para>
- </sect1>
- <sect1>
- <title>Bcfg2 Installation</title>
- <para>
+ caching logic. It can be installed by running the setup.py script.
</para>
+
+ <table>
+ <title>Bcfg2 Software Prerequisites</title>
+ <tgroup cols='3'>
+ <colspec colnum='1' colwidth='2*'/>
+ <colspec colnum='2' colwidth='5*'/>
+ <colspec colnum='3' colwidth='8*'/>
+ <thead>
+ <row><entry>Name</entry><entry>Description</entry><entry>URL</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>lxml</entry><entry>XML
+ Processing</entry><entry><ulink
+ url="http://codespeak.net/lxml"/></entry></row>
+ <row><entry>pyrex</entry><entry>C to Python language
+ interoperability (needed for lxml)</entry><entry><ulink
+ url="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex"/></entry></row>
+ <row><entry>M2Crypto</entry>
+ <entry>OpenSSL bindings for Python</entry><entry><ulink
+ url="http://wiki.osafoundation.org/bin/view/Projects/MeTooCrypto"/></entry></row>
+ <row><entry>Swig</entry>
+ <entry>C to Python language interoperability (needed for
+ M2Crypto)</entry><entry><ulink
+ url="http://www.swig.org"/></entry></row>
+ <row><entry>Fam</entry><entry>File Alteration
+ Monitor</entry><entry><ulink
+ url="http://oss.sgi.com"/></entry></row>
+ <row><entry>Gamin</entry><entry>Alternate File Alteration
+ Monitor</entry><entry><ulink
+ url="http://www.gnome.org/~veillard/gamin/"/></entry></row>
+ <row><entry>Python-fam</entry><entry>Python bindings for fam
+ (not needed with
+ gamin)</entry><entry><ulink url="http://python-fam.sourceforge.net"/></entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
</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.
+ minor modifications. This should be placed in
+ <filename>/etc/bcfg2.conf</filename>. If it is placed in another
+ location, each program takes a command line argument to specify
+ its alternate location.
</para>
+
<example>
- <title>bcfg2.conf</title>
+ <title>/etc/bcfg2.conf</title>
<programlisting>[server]
- repository = /disks/bcfg2
- structures = Bundler,Base
- generators = SSHbase,Cfg,Pkgmgr,Svcmgr
- metadata = /disks/bcfg2/etc
- </programlisting>
+repository = /disks/bcfg2
+structures = Bundler,Base
+generators = SSHbase,Cfg,Pkgmgr,Svcmgr</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".
+ This configuration file sets the top level location of the
+ configuration repository. It also activates two structures, and
+ four generators. Both structures and generators are instances of
+ Bcfg2 server plugins. Structures generate abstract configuration
+ fragments. These form the inventory of the
+ configuration. Generators provide client-specific literal values
+ for each configuration entity contained in the abstract
+ configuration.
</para>
</sect1>
- <sect1>
- <title>New-Style XML-RPC Deployments</title>
- <para>
- A new version of the Bcfg2 software is in testing that will
- provide simplified and standards compliant communications
- facilities. Instead of the use of SSSlib for communication, the
- server and clients can use HTTPS XML-RPC instead. This has
- required reimplementing the server and providing XML-RPC support
- for the client, but provides drastically simplified setup for
- new installs.
- </para>
+ <sect1>
+ <title>Daemon Configuration</title>
<para>
- The prerequisite list now includes ElementTree, M2Crypto (for
- SSL functions) and Python 2.2 or newer. ElementTree and M2Crypto
- are both python modules that can be easily installed and are
- already packaged for many Linux distributions.
+ Bcfg2 uses XML-RPC over HTTPS for all communications.
+ All communications occur over this transport. HTTPS provides
+ data security, while an embedded username and password provide
+ authentication.
</para>
<sect2>
@@ -146,33 +116,40 @@ $ python setup.py install
</para>
<programlisting>
-openssl req -x509 -nodes -days 1000 -newkey rsa:1024 -out server.pem -keyout server.pem
+openssl req -x509 -nodes -days 1000 -newkey rsa:1024 \
+ -out bcfg2.key -keyout bcfg2.key
</programlisting>
- <para>This command will generate an SSL key including both an
- RSA key and a certificate. This is suitable for use with the
- Bcfg2 XML-RPC server.</para>
+ <para>
+ This command will generate an SSL key including both an
+ RSA key and a certificate. This is suitable for use with the
+ Bcfg2 server. The path to this key should be put in the
+ bcfg2 configuration file in section communication, setting
+ key.
+ </para>
</sect2>
<sect2>
- <title>Communication Bootstrapping</title>
+ <title>Client Communication Setup</title>
<para>
The Bcfg2 client must be able to find the server's
location. This is accomplished through the use of the
communication settings in <filename>/etc/bcfg2.conf</filename>
- Two settings for the this section are required: protocol and
- server url.
+ Several settings must be included in this file: the server
+ url, a username and a password.
</para>
<example>
- <title>Bcfg2 XML-RPC Communication Settings</title>
- <programlisting>
- [communication]
- protocol = xmlrpc/ssl
- url = https://localhost:9443
- </programlisting>
+ <title>/etc/bcfg2.conf</title>
+ <programlisting>[communication]
+protocol = xmlrpc/ssl
+password = pwd
+user = root
+
+[components]
+bcfg2 = https://bcfg2server:8765</programlisting>
</example>
</sect2>
</sect1>