doc: Merge Fabian's bcfg2-admin doc updates

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

23 files changed, 110 insertions, 98 deletions

diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt
index 91d36cd25..1dd4f6db0 100644
--- a/doc/appendix/guides/fedora.txt
+++ b/doc/appendix/guides/fedora.txt
@@ -12,13 +12,13 @@ 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 
+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
@@ -29,13 +29,13 @@ prerequisites need to be fullfilled.
 Install Bcfg2 From RPM
 ======================
 
-The fastest way to get Bcfg2 onto your system is to use ``yum`` 
-or PackageKit. ``yum`` 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`.
 
 
@@ -49,12 +49,12 @@ 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: Red Hat/Fedora/RHEL/RHAS/Centos
     2: SUSE/SLES
@@ -101,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.
     ...
@@ -125,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.
 
@@ -172,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``.
 
 
@@ -192,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/
@@ -240,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
@@ -252,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:
 
@@ -282,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
@@ -306,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
@@ -330,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,
@@ -363,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
 
@@ -463,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/client/index.txt b/doc/client/index.txt
index 4da039385..e232d8084 100644
--- a/doc/client/index.txt
+++ b/doc/client/index.txt
@@ -31,4 +31,3 @@ client, for a few reasons:
    metadata
    agent
    debugging
-
diff --git a/doc/client/tools.txt b/doc/client/tools.txt
index 9bec46316..676feb175 100644
--- a/doc/client/tools.txt
+++ b/doc/client/tools.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _client-tools-index:
+.. _client-tools:
 
 Client Tool Drivers
 ===================
@@ -26,6 +26,12 @@ the system.
 
 Currently these are the tool drivers that are distributed with Bcfg2:
 
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   tools/*
+
 Action
 ------
 
diff --git a/doc/help/faq/client.txt b/doc/help/faq/client.txt
index 746b0201d..636d318ad 100644
--- a/doc/help/faq/client.txt
+++ b/doc/help/faq/client.txt
@@ -15,12 +15,12 @@ on the client. Then add the following on the client.::
     [communication]
     ca = /etc/bcfg2.ca
 
-**Server failure**
-
-On Fedora 14 and above it can happen that no connection is possible.
-
-    # bcfg2 -vqne
-    Server failure: Protocol Error: 401 Unauthorized
-    Failed to download probes from bcfg2
-    Server Failure
-
+.. FIXME: What is the solution for this?
+.. **Server failure**
+..
+.. On Fedora 14 and above it can happen that no connection is possible.
+..
+..     # bcfg2 -vqne
+..     Server failure: Protocol Error: 401 Unauthorized
+..     Failed to download probes from bcfg2
+..     Server Failure
diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt
index 38b34f14d..a4ce9fb5d 100644
--- a/doc/installation/distributions.txt
+++ b/doc/installation/distributions.txt
@@ -38,7 +38,7 @@ at `CustomDebianRepository`_.
 Fedora
 ======
 
-The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to
+The fastest way to get Bcfg2 packages onto your Fedora_ system is to
 use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2
 automatically. ::
 
diff --git a/doc/server/admin/backup.txt b/doc/server/admin/backup.txt
index 1ed918082..0c4758bda 100644
--- a/doc/server/admin/backup.txt
+++ b/doc/server/admin/backup.txt
@@ -9,7 +9,7 @@ backup
 
 Create an archive of the whole Bcfg2 :term:`repository`. The archive is stored
 directly in your Bcfg2 repository (e.g. ``/var/lib/bcfg2/``) and named with 
-the current data and time::
+the current date and time::
 
     bcfg2-admin backup
 
diff --git a/doc/server/admin/bundle.txt b/doc/server/admin/bundle.txt
index 0d3ada923..101666bb9 100644
--- a/doc/server/admin/bundle.txt
+++ b/doc/server/admin/bundle.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-bundle-index:
+.. _server-admin-bundle:
 
 bundle
 ======
diff --git a/doc/server/admin/client.txt b/doc/server/admin/client.txt
index 6790cc4d0..02b46bda1 100644
--- a/doc/server/admin/client.txt
+++ b/doc/server/admin/client.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-client-index:
+.. _server-admin-client:
 
 client
 ======
@@ -9,10 +9,10 @@ Create, delete, list, or modify client entries. ::
 
     bcfg2-admin client add <client> attr1=val1 attr2=val2
 
-Allowed attributes are *profile*, *uuid*, *password*, *location*, *secure*, 
+Allowed attributes are *profile*, *uuid*, *password*, *location*, *secure*,
 and *address*.
 
-A full example is shown below:: 
+A full example is shown below::
 
     bcfg2-admin client add laptop02.example.com profile="basic"
 
@@ -26,6 +26,6 @@ With ``list`` the file ``clients.xml`` is parsed and all entries are shown::
     laptop02.example.com
 
 This is useful for a quick check after adding an entry.  If you want more
-in-depth information about a client, ``bcfg2-client clients`` can provide
-that.  Please refer to the :ref:`bcfg2-info <guide-server-bcfg2_info>` 
+in-depth information about a client, ``bcfg2-info clients`` can provide
+that.  Please refer to the :ref:`bcfg2-info <server-bcfg2-info>`
 section for further details.
diff --git a/doc/server/admin/compare.txt b/doc/server/admin/compare.txt
index a12ce91be..6a770055e 100644
--- a/doc/server/admin/compare.txt
+++ b/doc/server/admin/compare.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-compare-index:
+.. _server-admin-compare:
 
 compare
 =======
@@ -10,8 +10,7 @@ specification instances.::
 
     bcfg2-admin compare <file1> <file2>
 
-If you want to compare two directories recursivly then use ``-r`` as an
+If you want to compare two directories recursively then use ``-r`` as an
 option. ::
 
     bcfg2-admin compare -r <dir1> <dir2>
-
diff --git a/doc/server/admin/index.txt b/doc/server/admin/index.txt
index c04fb9772..ee03cedda 100644
--- a/doc/server/admin/index.txt
+++ b/doc/server/admin/index.txt
@@ -18,7 +18,7 @@ functionality. Available modes are listed below.
    backup
    bundle
    client
-   compare 
+   compare
    init
    minestruct
    perf
diff --git a/doc/server/admin/init.txt b/doc/server/admin/init.txt
index 3e36f09b5..0e8b3afd3 100644
--- a/doc/server/admin/init.txt
+++ b/doc/server/admin/init.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-init-index:
+.. _server-admin-init:
 
 init
 ====
@@ -9,11 +9,11 @@ Interactively initialize a new repository.  Most values are automatically
 detected or a default value is provided. ::
 
     bcfg2-admin init
-    Store bcfg2 configuration in [/etc/bcfg2.conf]: 
-    Location of bcfg2 repository [/var/lib/bcfg2]: 
-    Input password used for communication verification (without echoing; leave blank for a random): 
-    What is the server's hostname [conf01.example.com]: 
-    Input the server location [https://conf01.example.com:6789]: 
+    Store bcfg2 configuration in [/etc/bcfg2.conf]:
+    Location of bcfg2 repository [/var/lib/bcfg2]:
+    Input password used for communication verification (without echoing; leave blank for a random):
+    What is the server's hostname [conf01.example.com]:
+    Input the server location [https://conf01.example.com:6789]:
     Input base Operating System for clients:
     1: Red Hat/Fedora/RHEL/RHAS/Centos
     2: SUSE/SLES
diff --git a/doc/server/admin/minestruct.txt b/doc/server/admin/minestruct.txt
index ad0d0cbe2..d1de72426 100644
--- a/doc/server/admin/minestruct.txt
+++ b/doc/server/admin/minestruct.txt
@@ -1,14 +1,14 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-minestruct-index:
+.. _server-admin-minestruct:
 
 minestruct
 ==========
 
-Extract extra entry lists from statistics. ::
+Extract extra entry lists from statistics.::
 
     bcfg2-admin minestruct <client> [-f xml-file] [-g groups]
 
-Hierarchy of groups in which to place the extra entries in can be determined 
-with ``-g <groups>``.  And ``-f <xml-output-file>`` specify the xml file in
-which to write the extra entries.
+Hierarchy of groups in which to place the extra entries in can be
+determined with ``-g <groups>``.  The ``-f <xml-output-file>`` option
+specifies the xml file in which to write the extra entries.
diff --git a/doc/server/admin/perf.txt b/doc/server/admin/perf.txt
index 74ac5051a..9a126ec71 100644
--- a/doc/server/admin/perf.txt
+++ b/doc/server/admin/perf.txt
@@ -1,10 +1,18 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-perf-index:
+.. _server-admin-perf:
 
 perf
 ====
 
-Query server for performance data. ::
+Query server for performance data.::
 
     bcfg2-admin perf
+    ================ ========== ========== ========== =======
+    Name             Min        Max        Mean       Count
+    ================ ========== ========== ========== =======
+    RecvStats        0.000378   0.001716   0.001367   5
+    GetConfig        0.018624   0.039495   0.023589   5
+    component_lock   0.000002   0.000057   0.000016   20
+    GetProbes        0.000523   0.000666   0.000591   5
+    RecvProbeData    0.002260   0.004550   0.002979
diff --git a/doc/server/admin/pull.txt b/doc/server/admin/pull.txt
index d33347f6f..e19485d53 100644
--- a/doc/server/admin/pull.txt
+++ b/doc/server/admin/pull.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-pull-index:
+.. _server-admin-pull:
 
 pull
 ====
@@ -18,6 +18,7 @@ The following options are available:
 ``-I`` interactive
 ``-s`` stdin
 
-A full example is shown below. ::
+.. FIXME: No example yet
+.. A full example is shown below. ::
 
-    bcfg2-admin pull 
+..     bcfg2-admin pull
diff --git a/doc/server/admin/query.txt b/doc/server/admin/query.txt
index f617239ab..65851a43d 100644
--- a/doc/server/admin/query.txt
+++ b/doc/server/admin/query.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-query-index:
+.. _server-admin-query:
 
 query
 =====
diff --git a/doc/server/admin/snapshots.txt b/doc/server/admin/snapshots.txt
index 0336944ec..25a7286c2 100644
--- a/doc/server/admin/snapshots.txt
+++ b/doc/server/admin/snapshots.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-snapshots-index:
+.. _server-admin-snapshots:
 
 snapshots
 =========
diff --git a/doc/server/admin/tidy.txt b/doc/server/admin/tidy.txt
index deff43bf6..816d6cdb3 100644
--- a/doc/server/admin/tidy.txt
+++ b/doc/server/admin/tidy.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-tidy-index:
+.. _server-admin-tidy:
 
 tidy
 ====
diff --git a/doc/server/admin/viz.txt b/doc/server/admin/viz.txt
index 3556fd395..1e7712ef9 100644
--- a/doc/server/admin/viz.txt
+++ b/doc/server/admin/viz.txt
@@ -1,11 +1,11 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-viz-index:
+.. _server-admin-viz:
 
 viz
 ===
 
-Produce graphviz diagrams of metadata structures. Make sure that the 
+Produce graphviz diagrams of metadata structures. Make sure that the
 graphviz package is installed.
 
 The following command will produce a graphviz image which includes hosts,
diff --git a/doc/server/admin/xcmd.txt b/doc/server/admin/xcmd.txt
index 5a032127d..fc40f1243 100644
--- a/doc/server/admin/xcmd.txt
+++ b/doc/server/admin/xcmd.txt
@@ -1,19 +1,19 @@
 .. -*- mode: rst -*-
 
-.. _server-admin-xcmd-index:
+.. _server-admin-xcmd:
 
 xcmd
 ====
 
-XML-RPC Command Interface. ::
+XML-RPC Command Interface.::
 
     xcmd <xmlrpc method> <optional arguments>
 
-For debbbuging the following command can help::
+For debbuging the following command can help::
 
     bcfg2-admin xcmd Metadata.toggle_debug
 
-Those two examples can alos be found in the 
+Those two examples can alos be found in the
 :ref:`Package section <server-plugins-generators-packages>`.
 
 To rebuild the packages plugin cache::
diff --git a/doc/server/bcfg2-info.txt b/doc/server/bcfg2-info.txt
index b2354652f..35d176e96 100644
--- a/doc/server/bcfg2-info.txt
+++ b/doc/server/bcfg2-info.txt
@@ -1,6 +1,6 @@
 .. -*- mode: rst -*-
 
-.. _appendix-guides-using_bcfg2_info:
+.. _server-bcfg2-info:
 
 ================
 Using bcfg2-info
diff --git a/doc/server/index.txt b/doc/server/index.txt
index caf90598d..9c427a0f4 100644
--- a/doc/server/index.txt
+++ b/doc/server/index.txt
@@ -6,9 +6,10 @@
 The Bcfg2 Server
 ================
 
-The Bcfg2 server is responsible for taking a network description and
-turning it into a series of configuration specifications for particular
-clients. It also manages probed data and tracks statistics for clients.
+The Bcfg2 server is responsible for taking a comprehensive infrastructure
+description and turning it into a series of configuration specifications
+for particular clients. It also manages probed data and tracks statistics
+for clients.
 
 The Bcfg2 server takes information from two sources when generating client
 configuration specifications. The first is a pool of metadata that describes
@@ -16,7 +17,7 @@ clients as members of an aspect-based classing system. That is, clients are
 defined in terms of aspects of their behavior. The other is a file system
 repository that contains mappings from metadata to literal configuration.
 These are combined to form the literal configuration specifications for
-clients. 
+clients.
 
 .. toctree::
    :maxdepth: 2
diff --git a/man/bcfg2-admin.8 b/man/bcfg2-admin.8
index d14f0fb85..c0b8a09ce 100644
--- a/man/bcfg2-admin.8
+++ b/man/bcfg2-admin.8
@@ -19,7 +19,7 @@ Specify the location of the configuration file (if it is not in
 /etc/bcfg2.conf).
 .RE
 .SH MODES
-.PP 
+.PP
 .B init
 .RS
 Initialize a new repository (interactive).
@@ -72,7 +72,7 @@ Create a graphviz diagram of client, group and bundle information.
 .B mode
 .RS
 List all available xml bundles 'list-xml' or for all available genshi
-bundles 'list-genshi'. 'show' provides an interactive dialog to get 
+bundles 'list-genshi'. 'show' provides an interactive dialog to get
 details about the available bundles.
 .RE
 .SH CLIENT OPTIONS
@@ -190,4 +190,3 @@ Produce raw graphviz output.
 .RS
 Add a shape/color key.
 .RE
-
diff --git a/src/lib/Server/Admin/__init__.py b/src/lib/Server/Admin/__init__.py
index b76d0a77e..a22d8521a 100644
--- a/src/lib/Server/Admin/__init__.py
+++ b/src/lib/Server/Admin/__init__.py
@@ -6,7 +6,6 @@ __all__ = [
         'Client',
         'Compare',
         'Group',
-        #'Examples',
         'Init',
         'Minestruct',
         'Mode',