doc: Massive update

3 files changed, 228 insertions, 251 deletions

diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt
index 2c05c5238..786c70290 100644
--- a/doc/getting_started/index.txt
+++ b/doc/getting_started/index.txt
@@ -2,57 +2,245 @@
 
 .. _getting_started-index:
 
-===========
-Using Bcfg2
-===========
+===============
+Getting started
+===============
 
-These are many of the resources available to help new users get started.
+The steps below should get you from just thinking about a
+configuration management system to an operational installation of
+Bcfg2. If you get stuck, be sure to check the :ref:`mailinglist`
+or to drop in on our :ref:`ircchannel`.
 
-* For the impatient there is the :ref:`quickstart-index` page.
-* :ref:`help-index` has information when you are troubleshooting or need to ask a question.
-* If you find anything wrong or missing please :ref:`report-a-bug` to let us know.
+Get and Install Bcfg2 Server
+============================
 
-.. toctree::
-   :maxdepth: 2
+We recommend running the server on a Linux machine for ease of
+deployment due to the availability of packages for the dependencies.
 
-   using-bcfg2-info
-   using-bcfg2-with-centos
+First, you need to download and install Bcfg2. The section 
+:ref:`installation-index` in this manual describes the steps to take. 
+To start, you will need to install the server on one machine and the
+client on one or more machines. Yes, your server can also be a client
+(and should be by the time your environment is fully managed).
 
-Must Reads
-==========
+.. _Bcfg2 download page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download
+.. _Install page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Install
+
+Set up Repository
+=================
+
+The next step after installing the Bcfg2 packages is to configure the
+server. You can easily set up a personalized default configuration by
+running, on the server, ::
+
+    bcfg2-admin init
 
-* `Documentation`
-* `WritingSpecification`
-* `Bcfg2 Architecture <Doc/Architecture>`
-* `ServerSideOverview`
-* `UpgradeTesting`
-* `Troubleshooting`
-* `Bcfg2 Server Plugins <Plugins>`
+You will be presented with a series of questions that will build a
+Bcfg2 configuration file in ``/etc/bcfg2.conf``, set up a skeleton
+repository (in ``/var/lib/bcfg2`` by default), help you create ssl
+certificates, and do any other similar tasks needed to get you
+started.
+
+Once this process is done, you can start the Bcfg2 server::
+
+    /etc/init.d/bcfg2-server start
+
+You can try it out by running the Bcfg2 client on the same machine,
+acting like it is your first client.
+
+.. note::
+
+   The following command will tell the client to run in no-op mode,
+   meaning it will only check the client against the repository and
+   report any changes it sees. It won't make any changes (partially
+   because you haven't populated the repository with any
+   yet). However, nobody is perfect - you can make a typo, our
+   software can have bugs, monkeys can break in and hit enter before
+   you are done. Don't run this command on a production system if you
+   don't know what it does and aren't prepared for the
+   consequences. We don't know of anybody having problems with it
+   before, but it is better to be safe than sorry.
+
+And now for the command::
+
+       bcfg2 -q -v -n
 
-Misc/Others
-===========
+That can be translated as "bcfg2 quick verbose no-op". The output
+should be something similar to::
 
-* `Probes <Plugins/Probes>`
-* `AgentMode`
-* `DynamicGroups`
-* `Client Tool Drivers <ClientTools>`
-* `Developing for Bcfg2 <DevelopingForBcfg2>`
-* `Howtos`
+    Loaded tool drivers:
+     Chkconfig    POSIX        PostInstall  RPM
 
-Reporting
-=========
+    Phase: initial
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      242
+
+
+    Phase: final
+    Correct entries:        0
+    Incorrect entries:      0
+    Total managed entries:  0
+    Unmanaged entries:      242
+
+Perfect! We have started out with an empty configuration, and none of
+our configuration elements are correct. It doesn't get much cleaner
+than that. But what about those unmanaged entries? Those are the extra
+configuration elements (probably all packages at the moment) that
+still aren't managed. Your goal now is to migrate each of those plus
+any it can't see up to the "Correct entries" line.
+
+Populate Repository
+===================
+
+Finally, you need to populate your repository. Unfortunately, from
+here on out we can't write up a simple recipe for you to follow to get
+this done. It is very dependent on your local configuration, your
+configuration management goals, the politics surrounding your
+particular machines, and many other similar details. We can, however,
+give you guidance.
+
+After the above steps, you should have a toplevel repository structure
+that looks like::
+
+    bcfg-server:~ # ls /var/lib/bcfg2
+    Bundler/  Cfg/  Metadata/  Pkgmgr/  Rules/  SSHbase/  etc/
+
+The place to start is the Metadata directory, which contains two
+files: ``clients.xml`` and ``groups.xml``. Your current
+``clients.xml`` will look pretty close to:
+
+.. code-block:: xml
+
+   <Clients version="3.0">
+      <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/>
+   </Clients>
+
+The ``clients.xml`` file is just a series of ``<Client />`` tags, each
+of which describe one host you manage. Right now we only manage one
+host, the server machine we just created. This machine is bound to the
+``basic`` profile, is pingable, has a pingtime of ``0``, and has the
+name ``bcfg-server.example.com``. The two "ping" parameters don't
+matter to us at the moment, but the other two do. The name parameter
+is the fully qualified domain name of your host, and the profile
+parameter maps that host into the ``groups.xml`` file.
+
+Our simple ``groups.xml`` file looks like:
+
+.. code-block:: xml
+
+   <Groups version='3.0'>
+      <Group profile='true' public='false' name='basic'>
+         <Group name='suse'/>
+      </Group>
+      <Group name='ubuntu' toolset='debian'/>
+      <Group name='debian' toolset='debian'/>
+      <Group name='redhat' toolset='rh'/>
+      <Group name='suse' toolset='rh'/>
+      <Group name='mandrake' toolset='rh'/>
+      <Group name='solaris' toolset='solaris'/>
+   </Groups>
+
+There are two types of groups in Bcfg: profile groups
+(``profile='true'``) and non-profile groups
+(``profile='false'``). Profile groups can act as top-level groups to
+which clients can bind, while non-profile groups only exist as members
+of other groups. In our simple starter case, we have a profile group
+named ``basic``, and that is the group that our first client bound
+to. Our first client is a SuSE machine, so it contains the ``suse``
+group. Of course, ``bcfg2-admin`` isn't smart enough to fill out the
+rest of your config, so the ``suse`` group further down is empty.
+
+Let's say the first thing we want to set up on our machine is the
+message of the day. To do this, we simply need to create a Bundle and
+add that Bundle to an appropriate group. In this simple example, we
+start out by adding
+
+.. code-block:: xml
+
+   <Bundle name='motd'/>
+
+to the ``basic`` group.
+
+Next, we create a motd.xml file in the Bundler directory:
+
+.. code-block:: xml
+
+   <Bundle name='motd' version='2.0'>
+     <Path name='/etc/motd' />
+   </Bundle>
+
+Now when we run the client, we get slightly different output::
+
+    Loaded tool drivers:
+     Chkconfig    POSIX        PostInstall  RPM
+    Incomplete information for entry Path:/etc/motd; cannot verify
+
+    Phase: initial
+    Correct entries:        0
+    Incorrect entries:      1
+    Total managed entries:  1
+    Unmanaged entries:      242
+
+    In dryrun mode: suppressing entry installation for:
+     Path:/etc/motd
+
+    Phase: final
+    Correct entries:        0
+    Incorrect entries:      1
+    Total managed entries:  1
+    Unmanaged entries:      242
+
+We now have an extra unmanaged entry, bringing our total number of
+managed entries up to one. To manage it we need to copy ``/etc/motd``
+to ``/var/lib/bcfg2/Cfg/etc/motd/``. Note the layout of that path: all
+plain-text config files live in the Cfg directory. The directory
+structure under that directory directly mimics your real filesystem
+layout, making it easy to find and add new files. The last directory
+is the name of the file itself, so in this case the full path to the
+motd file would be ``/var/lib/bcfg2/Cfg/etc/motd/motd``. Copy your
+real ``/etc/motd`` file to that location, run the client again, and
+you will find that we now have a correct entry::
+
+    Loaded tool drivers:
+     Chkconfig    POSIX        PostInstall  RPM
+
+    Phase: initial
+    Correct entries:        1
+    Incorrect entries:      0
+    Total managed entries:  1
+    Unmanaged entries:      242
+
+
+    Phase: final
+    Correct entries:        1
+    Incorrect entries:      0
+    Total managed entries:  1
+    Unmanaged entries:      242
+
+Done! Now we just have 242 (or more) entries to take care of!
+
+:ref:`server-plugins-structures-bundler-index` is a relatively easy
+directory to populate. You can find many samples of Bundles in the
+`Bundle Repository`_, many of which can be used without editing.
+
+.. _Bundle Repository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/examples
+
+Next Steps
+==========
 
-* :ref:`server-reports-index`
+Several other utilities can help from this point on:
 
-Examples
-========
+``bcfg2-info`` is a utility that instantiates a copy of the Bcfg2 server
+core (minus the networking code) for examination. From this, you can
+directly query:
 
-* `Demo Repository <GroupNames>`
-* `Plugins/Bundler/examples`
-* `Plugins/Probes/examples`
-* `Plugins/TGenshi/examples`
+* Client Metadata
+* Which entries are provided by particular plugins
+* Client Configurations
 
-Man Pages
-=========
+Run ``bcfg2-info``, and type help and the prompt when it comes up.
 
-* `Manual Pages <ManualPages>`
+``bcfg2-admin`` can perform a variety of repository maintenance
+tasks. Run ``bcfg2-admin`` help for details.
diff --git a/doc/getting_started/using-bcfg2-info.txt b/doc/getting_started/using-bcfg2-info.txt
deleted file mode 100644
index 1fab0ea07..000000000
--- a/doc/getting_started/using-bcfg2-info.txt
+++ /dev/null
@@ -1,132 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _getting_started-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.
diff --git a/doc/getting_started/using-bcfg2-with-centos.txt b/doc/getting_started/using-bcfg2-with-centos.txt
deleted file mode 100644
index 93875d4c5..000000000
--- a/doc/getting_started/using-bcfg2-with-centos.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _EPEL: http://fedoraproject.org/wiki/EPEL
-.. _RPMForge: https://rpmrepo.org/RPMforge
-
-.. _getting_started-using_bcfg2-with-centos:
-
-=======================
-Using Bcfg2 With CentOS
-=======================
-
-This section covers specific topics for using Bcfg2 with CentOS. Most
-likely the tips on this page also apply to other members of the Red Hat
-family of Linux operating systems.
-
-From Source
-+++++++++++
-
-Install Prerequisities
-######################
-
-While you can go about building all these things from source, this
-how to will try and meet the dependencies using packages from EPEL_
-or RPMforge_. The *el5* package should be compatible with CentOS 5.x.
-
-EPEL_::
-
-    [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm
-
-RPMforge_::
-
-    [root@centos ~]# rpm -Uvh http://dag.wieers.com/rpm/packages/rpmforge-release/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm
-
-.. note::
-
-    Be careful with `mixing package repositories
-    <http://fedoraproject.org/wiki/EPEL/FAQ#What_about_compatibility_with_other_third_party_repositories.3F>`_.
-
-Now you can install the rest of the prerequisites::
-
-    [root@centos ~]# yum install python-genshi python-cheetah python-lxml
-
-Build Packages from source
-##########################
-
-* After installing git, clone the master branch::
-
-    [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git
-
-* Install the ``fedora-packager`` package ::
-
-    [root@centos ~]# yum install fedora-packager
-
-* A directory structure for the RPM build process has to be established. ::
-
-    [you@centos ~]$ rpmdev-setuptree
-
-* Change to the *redhat* directory of the checked out Bcfg2 source::
-
-    [you@centos ~]$ cd bcfg2/redhat/
-
-* In the particular directory is a Makefile which will do the job of building the RPM packages. You can do this as root, but it's not recommanded::
-
-    [you@centos redhat]$ make
-
-* Now the new RPM package can be installed.  Please adjust the path to your RPM package::
-
-    [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm
-
-Install Packages from Package repository
-########################################
-
-To install the bcfg2-server and bcfg2 from a package repository, just
-use Yum to do it::
-
-    [root@centos ~]# yum install bcfg2-server bcfg2
-
-.. toctree::
-    :hidden: