Merge branch 'master' of git.mcs.anl.gov:bcfg2

2 files changed, 54 insertions, 175 deletions

diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt
index d8d3b1b34..1dd4f6db0 100644
--- a/doc/appendix/guides/fedora.txt
+++ b/doc/appendix/guides/fedora.txt
@@ -12,22 +12,33 @@ This guide is work in progess.
 
 
 This is a complete getting started guide for Fedora. With this
-document you should be able to install a Bcfg2 server, a Bcfg2 client, 
+document you should be able to install a Bcfg2 server, a Bcfg2 client,
 and change the ``/etc/motd`` file on the client.
 
+Prerequisites
+=============
+
+To setup a configuration management system based on Bcfg2 only a few
+prerequisites need to be fullfilled.
+
+* A server machine that can host the Bcfg2
+* Internet access for the installation process
+* A working network with DNS
+
+
 Install Bcfg2 From RPM
 ======================
 
-The fastest way to get Bcfg2 onto your system is to use ``yum`` 
-or PackageKit. ``
-um`` will pull all dependencies of Bcfg2 
+The fastest way to get Bcfg2 onto your system is to use ``yum``
+or PackageKit. ``yum`` will pull all dependencies of Bcfg2
 automatically in. ::
 
   $ su -c 'yum install bcfg2-server bcfg2'
 
-Your system should now have the necessary software to use Bcfg2. 
+Your system should now have the necessary software to use Bcfg2.
 The next step is to set up your Bcfg2 :term:`repository`.
 
+
 Initialize your repository
 ==========================
 
@@ -38,14 +49,14 @@ is a tool which allows you to automate this:
 .. code-block:: sh
 
     # bcfg2-admin init
-    Store bcfg2 configuration in [/etc/bcfg2.conf]: 
-    Location of bcfg2 repository [/var/lib/bcfg2]: 
+    Store bcfg2 configuration in [/etc/bcfg2.conf]:
+    Location of bcfg2 repository [/var/lib/bcfg2]:
     Directory /var/lib/bcfg2 exists. Overwrite? [y/N]:y
-    Input password used for communication verification (without echoing; leave blank for a random): 
+    Input password used for communication verification (without echoing; leave blank for a random):
     What is the server's hostname: [config01.local.net]
-    Input the server location [https://config01.local.net:6789]: 
+    Input the server location [https://config01.local.net:6789]:
     Input base Operating System for clients:
-    1: Redhat/Fedora/RHEL/RHAS/Centos
+    1: Red Hat/Fedora/RHEL/RHAS/Centos
     2: SUSE/SLES
     3: Mandrake
     4: Debian
@@ -68,7 +79,7 @@ Change responses as necessary.
 Start the server
 ================
 
-You are now ready to start your bcfg2 server for the first time::
+You are now ready to start your Bcfg2 server for the first time::
 
     $ su -c '/etc/init.d/bcfg2-server start'
     Starting Configuration Management Server: bcfg2-server     [  OK  ]
@@ -90,12 +101,12 @@ Run ``bcfg2`` to be sure you are able to communicate with the server:
 .. code-block:: sh
 
     $ su -c 'bcfg2 -vqne'
-     
+
     /usr/lib/python2.6/site-packages/Bcfg2/Client/Tools/rpmtools.py:23: DeprecationWarning: the md5 module is deprecated; use hashlib instead
       import md5
     Loaded plugins: presto, refresh-packagekit
     Loaded tool drivers:
-     Action     Chkconfig  POSIX      YUMng     
+     Action     Chkconfig  POSIX      YUMng
     Extra Package imsettings-libs 0.108.0-2.fc13.i686.
     Extra Package PackageKit-device-rebind 0.6.4-1.fc13.i686.
     ...
@@ -114,11 +125,11 @@ Run ``bcfg2`` to be sure you are able to communicate with the server:
     Incorrect entries:	0
     Total managed entries:	0
     Unmanaged entries:	1314
-     Package:ConsoleKit                         Package:jasper-libs                        Package:pcsc-lite-libs                    
-     Package:ConsoleKit-libs                    Package:java-1.5.0-gcj                     Package:perf                              
-    ...                        
-     Package:iw                                 Package:pcre                               Service:sshd                              
-     Package:jack-audio-connection-kit          Package:pcsc-lite                          Service:udev-post                         
+     Package:ConsoleKit                         Package:jasper-libs                        Package:pcsc-lite-libs
+     Package:ConsoleKit-libs                    Package:java-1.5.0-gcj                     Package:perf
+    ...
+     Package:iw                                 Package:pcre                               Service:sshd
+     Package:jack-audio-connection-kit          Package:pcsc-lite                          Service:udev-post
 
 The ``bcfg2.conf`` file contains only standard plugins so far.
 
@@ -161,17 +172,17 @@ The ``bcfg2.conf`` file contains only standard plugins so far.
 Add the machines to Bcfg2
 -------------------------
 
-``bcfg2-admin`` can be used to add a machine to Bcfg2 easily. You 
+``bcfg2-admin`` can be used to add a machine to Bcfg2 easily. You
 need to know the Fully Qualified Domain Name (FQDN) of ever system
-you want to control through Bcfg2. ::  
+you want to control through Bcfg2. ::
 
-   bcfg2-admin client add <FQDN machine> 
+   bcfg2-admin client add <FQDN machine>
 
 Bring your first machine under Bcfg2 control
 --------------------------------------------
 
-Now it is time to get the first machine's configuration into the 
-Bcfg2 repository. The server will be the first machine. It's 
+Now it is time to get the first machine's configuration into the
+Bcfg2 repository. The server will be the first machine. It's
 already in the ``Metadata/client.xml``.
 
 
@@ -181,13 +192,13 @@ Setup the `Packages`_ plugin
 .. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages
 
 First, replace **Pkgmgr** with **Packages** in the plugins
-line of ``bcfg2.conf``. Then create `Packages/` directory in 
+line of ``bcfg2.conf``. Then create `Packages/` directory in
 ``/var/lib/bcfg2`` ::
 
     $ su -c 'mkdir /var/lib/bcfg2/Packages'
 
-Create a ``config.xml`` file for the packages in 
-``/var/lib/bcfg2/Packages`` with the following content.  Choose a 
+Create a ``config.xml`` file for the packages in
+``/var/lib/bcfg2/Packages`` with the following content.  Choose a
 mirror near your location according the `Mirror list`_ .
 
 .. _Mirror list: http://mirrors.fedoraproject.org/publiclist/
@@ -229,11 +240,11 @@ something like this
        <Group name='suse'/>
        <Group name='mandrake'/>
        <Group name='solaris'/>
-    </Groups>    
+    </Groups>
 
 .. note::
-    When editing your xml files by hand, it is useful to occasionally 
-    run ``bcfg2-repo-validate`` to ensure that your xml validates 
+    When editing your xml files by hand, it is useful to occasionally
+    run ``bcfg2-repo-validate`` to ensure that your xml validates
     properly.
 
 Add a probe
@@ -241,7 +252,7 @@ Add a probe
 
 The next step for the client will be to have the proper
 arch group membership. For this, we will make use of the
-:ref:`server-plugins-grouping-dynamic_groups` capabilities of 
+:ref:`server-plugins-grouping-dynamic_groups` capabilities of
 the Probes plugin. Add **Probes** to your plugins line in ``bcfg2.conf``
 and create the Probe:
 
@@ -271,7 +282,7 @@ Start managing packages
 +++++++++++++++++++++++
 
 Add a base-packages bundle. Let's see what happens when we just populate
-it with the *yum* package. Create the ``base-packages.xml`` in your 
+it with the *yum* package. Create the ``base-packages.xml`` in your
 ``Bundler/`` directory with a entry for ``yum``.
 
 .. code-block:: xml
@@ -295,22 +306,22 @@ Now if we run the client, we can see what this has done for us.::
 
     output
 
-As you can see, the Packages plugin has generated the dependencies 
-required for the yum package automatically. The ultimate goal should 
-be to move all the packages from the **Unmanaged** entries section 
-to the **Managed** entries section. So, what exactly *are* those 
+As you can see, the Packages plugin has generated the dependencies
+required for the yum package automatically. The ultimate goal should
+be to move all the packages from the **Unmanaged** entries section
+to the **Managed** entries section. So, what exactly *are* those
 Unmanaged entries?::
 
     output
 
-Now you can go through these and continue adding the packages you 
-want to your Bundle. After a while, I ended up with a minimal bundle 
+Now you can go through these and continue adding the packages you
+want to your Bundle. After a while, I ended up with a minimal bundle
 that looks like this
 
 .. code-block:: xml
 
     <Bundle name='base-packages'>
-            
+
     </Bundle>
 
 Now when I run the client, you can see I have only one unmanaged
@@ -319,8 +330,8 @@ package::
     outout
 
 The gpg-pubkey packages are special in that they are not really
-packages. Currently, the way to manage them is using 
-:ref:`BoundEntries <boundentries>`. So, after adding them, our 
+packages. Currently, the way to manage them is using
+:ref:`BoundEntries <boundentries>`. So, after adding them, our
 Bundle now looks like this
 
 .. note:: This does not actually control the contents of the files,
@@ -352,7 +363,7 @@ Bundle now looks like this
 
 To actually push the gpg keys out via Bcfg2, you will need to manage
 the files as well. This can be done by adding Path entries for each
-of the gpg keys you want to manage 
+of the gpg keys you want to manage
 
 .. code-block:: xml
 
@@ -452,12 +463,12 @@ Git
 .. _Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
 
 Adding the :ref:`server-plugins-version-git` plugins can preserve
-versioning information. The first step is to add *Git* to your 
+versioning information. The first step is to add *Git* to your
 plugin line::
 
     plugins = Base,Bundler,Cfg,...,Git
 
-For tracking the configuration files in the ``/var/lib/bcfg2`` 
+For tracking the configuration files in the ``/var/lib/bcfg2``
 directory a git repository need to be established::
 
     git init
diff --git a/doc/appendix/guides/using-bcfg2-info.txt b/doc/appendix/guides/using-bcfg2-info.txt
deleted file mode 100644
index b2354652f..000000000
--- a/doc/appendix/guides/using-bcfg2-info.txt
+++ /dev/null
@@ -1,132 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _appendix-guides-using_bcfg2_info:
-
-================
-Using bcfg2-info
-================
-
-``bcfg2-info`` is a tool for introspecting server functions. It is
-useful for understanding how the server is interpreting your
-repository. It consists of the same logic executed by the server to
-process the repository and produce configuration specifications, just
-without all of the network communication code. Think of ``bcfg2-info``
-as ``bcfg2-server`` on a stick. It is a useful location to do testing
-and staging of new configuration rules, prior to deployment. This is
-particularly useful when developing templates, or developing Bcfg2
-plugins.
-
-Getting Started
-===============
-
-First, fire up the bcfg2-info interpreter.
-
-.. code-block:: none
-
-     [0:464] bcfg2-info
-     Loading experimental plugin(s): Packages
-     NOTE: Interfaces subject to change
-     Handled 8 events in 0.006s
-     Handled 4 events in 0.035s
-     Welcome to bcfg2-info
-     Type "help" for more information
-     >
-
-At this point, the server core has been loaded up, all plugins have
-been loaded, and the ``bcfg2-info`` has both read the initial state of
-the Bcfg2 repository, as well as begun monitoring it for changes. Like
-*bcfg2-server*, ``bcfg2-info`` monitors the repository for changes,
-however, unlike *bcfg2-server*, it does not process change events
-automatically. File modification events can be processed by explicitly
-calling the **update** command. This will process the events,
-displaying the number of events processed and the amount of time taken
-by this processing. If no events are available, no message will be
-displayed. For example, after a change to a file in the repository:
-
-.. code-block:: none
-
-     >update
-     Handled 1 events in 0.001s
-     > update
-     >
-
-This explicit update process allows you to control the update process,
-as well as see the precise changes caused by repository
-modifications.
-
-``bcfg2-info`` has several builtin commands that display the state of
-various internal server core state. These are most useful for
-examining the state of client metadata, either for a single client, or
-for clients overall.
-
-**clients**
-     displays a list of clients, along with their profile groups
-**groups**
-     displays a list of groups, the inheritance hierarchy, profile
-     status, and category name, if there is one.
-**showclient**
-     displays full metadata information for a client, including
-     profile group, group memberships, bundle list, and any connector
-     data, like Probe values or Property info.
-
-Debugging Configuration Rules
-=============================
-
-In addition to the commands listed above for viewing client metadata,
-there are also commands which can shed light on the configuration
-generation process. Recall that configuration generation occurs in
-three major steps:
-
-1) Resolve client metadata
-2) Build list of entries for the configuration
-3) Bind host-specific version of each entry
-
-Step *1* can be viewed with the commands presented in the previous
-section. The latter two steps can be examined using the following
-commands.
-
-**showentries**
-     displays a list of entries (optionally filtered by type) that
-     appear in a client's configuration specification
-
-**buildfile**
-     Perform the entry binding process on a single entry, displaying
-     its results. This command is very useful when developing
-     configuration file templates.
-
-**build**
-     Build the full configuration specification and write it to a
-     file.
-
-**mappings**
-     displays the entries handled by the plugins loaded by the server
-     core. This command is useful when the server reports a bind
-     failure for an entry.
-
-Debugging and Developing Bcfg2
-==============================
-
-``bcfg2-info`` loads a full Bcfg2 server core, so it provides the ideal
-environment for developing and debugging Bcfg2. Because it is hard to
-automate this sort of process, we have only implemented two commands
-in ``bcfg2-info`` to aid in the process.
-
-**profile**
-     The profile command produces python profiling information for
-     other ``bcfg2-info`` commands. This can be used to track
-     performance problems in configuration generation.
-
-**debug**
-     The debug command exits the ``bcfg2-info`` interpreter loop and drops
-     to a python interpreter prompt. The Bcfg2 server core is available
-     in this namespace as "self". Full documentation for the server core
-     is out of scope for this document. This capability is most useful
-     to call into plugin methods, often with setup calls or the enabling
-     of diagnostics.
-
-     It is possible to return to the ``bcfg2-info`` command loop by
-     exiting the python interpreter with ^D.
-
-     There is built-in support for IPython in ``bcfg2-info``. If IPython
-     is installed, dropping into debug mode in ``bcfg2-info`` will use
-     the IPython interpreter by default.