doc: Rearrange document structure and add client tools

Signed-off-by: Sol Jerome <solj@ices.utexas.edu>

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5669 ce84e21b-d406-0410-9b95-82705330c041

17 files changed, 363 insertions, 20 deletions

diff --git a/doc/plugins/generators/account.txt b/doc/plugins/generators/account.txt
index e07cef8b6..9a2718ce5 100644
--- a/doc/plugins/generators/account.txt
+++ b/doc/plugins/generators/account.txt
@@ -18,7 +18,7 @@ User access data is stored in three files in the Account directory:
 * rootlist (a list of user:host pairs for scoped root privs)
 * useraccess (a list of user:host pairs for login access)
 
-SSH keys are stored in files named $username.key; these are installed into root's authorized keys for users in the superusers list as well as for the pertitent users in the rootlike file (for the current system). 
+SSH keys are stored in files named $username.key; these are installed into root's authorized keys for users in the superusers list as well as for the pertitent users in the rootlike file (for the current system).
 
 Authentication data is read in from (static|dyn).(passwd|group) The static ones are for system local ones, while the dyn. versions are for external synchronization (from ldap/nis/etc)
 There is also a static.limits.conf that provides the limits.conf header and any static entries.
diff --git a/doc/plugins/generators/cfg.txt b/doc/plugins/generators/cfg.txt
index 8ef9b17dc..e4e342842 100644
--- a/doc/plugins/generators/cfg.txt
+++ b/doc/plugins/generators/cfg.txt
@@ -89,7 +89,7 @@ info.xml files
 
 This feature is included in version 0.9.5pre3 and newer of the bcfg2 server.
 
-info.xml files add the ability to specify different sets of file metadata on a group by group basis. These files are XML, and work similarly to those used by [wiki:Plugins/Rules Rules] or [wiki:Plugins/Pkgmgr Pkgmgr]. 
+info.xml files add the ability to specify different sets of file metadata on a group by group basis. These files are XML, and work similarly to those used by [wiki:Plugins/Rules Rules] or [wiki:Plugins/Pkgmgr Pkgmgr].
 
 The following specifies a different global set of permissions (root/sys/0651) than on clients in group webserver (root/root/0652)
 
diff --git a/doc/plugins/generators/decisions.txt b/doc/plugins/generators/decisions.txt
index 17bc5c66c..079e748f9 100644
--- a/doc/plugins/generators/decisions.txt
+++ b/doc/plugins/generators/decisions.txt
@@ -4,9 +4,9 @@
 Decisions
 =========
 
-This page describes the Decisions plugin. The client has support for a centralized set of per-entry installation decisions. This approach is needed when particular changes are deemed "high risk"; this gives the ability to centrally specify these changes, but only install them on clients when administrator supervision is available. Because collaborative configuration is one of the remaining hard issues in configuration management, these issues typically crop up in environments with several administrators and much configuration variety. 
+This page describes the Decisions plugin. The client has support for a centralized set of per-entry installation decisions. This approach is needed when particular changes are deemed "high risk"; this gives the ability to centrally specify these changes, but only install them on clients when administrator supervision is available. Because collaborative configuration is one of the remaining hard issues in configuration management, these issues typically crop up in environments with several administrators and much configuration variety.
 
-In these cases, the client can be configured to run in either a whitelist or blacklist mode, wherein a list of entries is downloaded from the server. The client uses this list to determine which incorrect entries should be corrected during the current run of the installation tool. The Decision plugin is the only stock plugin that generates entries for client's whitelists or blacklists. 
+In these cases, the client can be configured to run in either a whitelist or blacklist mode, wherein a list of entries is downloaded from the server. The client uses this list to determine which incorrect entries should be corrected during the current run of the installation tool. The Decision plugin is the only stock plugin that generates entries for client's whitelists or blacklists.
 
 The Decision plugin uses a directory in the bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to files managed by Cfg, probes, TCheetah, and TGenshi. File basenames are either whitelist or blacklist. These files have a simple format; the following is an example.
 
@@ -24,6 +24,6 @@ The Decision plugin uses a directory in the bcfg2 repository called Decisions. F
     vim: ft=xml
     -->
 
-This example, included as a whitelist due to its name, enables all services, and the path entry named /etc/apt/apt.conf to be installed on systems running in whitelist mode; all other entry installation will be surpressed. 
+This example, included as a whitelist due to its name, enables all services, and the path entry named /etc/apt/apt.conf to be installed on systems running in whitelist mode; all other entry installation will be surpressed.
 
 When a client askes for its whitelist or blacklist, all of the files pertaining to that client of the correct type are aggregated into a single list. This list is sent to the client. Note that this list is only generated when a client is run with the appropriate option (-l (whitelist|blacklist)); client behavior is not controlled unless this option is used.
diff --git a/doc/plugins/generators/hostbase.txt b/doc/plugins/generators/hostbase.txt
index 4b85fecd0..a03dd2f82 100644
--- a/doc/plugins/generators/hostbase.txt
+++ b/doc/plugins/generators/hostbase.txt
@@ -34,9 +34,9 @@ Create the hostbase database and a user.  For MySQL users::
 
     mysql> CREATE DATABASE hostbase
     mysql> quit
-    
+
     systemprompt#:  mysql -u root hostbase
-    mysql> GRANT ALL PRIVILEGES ON *.* TO hostbaseuser@mycomputer.private.net IDENTIFIED 
+    mysql> GRANT ALL PRIVILEGES ON *.* TO hostbaseuser@mycomputer.private.net IDENTIFIED
            BY 'password' WITH GRANT OPTION;
     mysql> quit
 
@@ -164,7 +164,7 @@ Authentication
 Edit Django settings
 --------------------
 
-Django allows for custom authentication backends to its login procedure.  Hostbase has an NIS authentication backend that verifies a user to be in the unix group allowed to modify Hostbase.  
+Django allows for custom authentication backends to its login procedure.  Hostbase has an NIS authentication backend that verifies a user to be in the unix group allowed to modify Hostbase.
 
 To enable this feature:
  * first edit your {{{Hostbase/settings.py}}} file and uncomment the line {{{'Hostbase.backends.NISBackend',}}} in the list of {{{AUTHENTICATION_BACKENDS}}}
diff --git a/doc/plugins/generators/nagiosgen.txt b/doc/plugins/generators/nagiosgen.txt
index 55b6063a5..fd33fe374 100644
--- a/doc/plugins/generators/nagiosgen.txt
+++ b/doc/plugins/generators/nagiosgen.txt
@@ -4,7 +4,7 @@
 NagiosGen
 =========
 
-This page describes the installation and use of the [http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py NagiosGen] plugin. 
+This page describes the installation and use of the [http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py NagiosGen] plugin.
 
 Update /etc/bcfg2.conf, adding NagiosGen to plugins::
 
@@ -55,7 +55,7 @@ Create default host, and group specs in:
             retain_status_information       1
             retain_nonstatus_information    1
             is_volatile                     0
-    
+
             check_period                    24x7
             max_check_attempts              4
             check_interval                  5
diff --git a/doc/plugins/generators/packages.txt b/doc/plugins/generators/packages.txt
index 837a6b14a..c7ac2deea 100644
--- a/doc/plugins/generators/packages.txt
+++ b/doc/plugins/generators/packages.txt
@@ -1,4 +1,4 @@
-.. -*- mode: rst -*-
+.. _plugins-generators-packages:
 
 ========
 Packages
diff --git a/doc/plugins/generators/pkgmgr.txt b/doc/plugins/generators/pkgmgr.txt
index b6940f9b1..fc15fad79 100644
--- a/doc/plugins/generators/pkgmgr.txt
+++ b/doc/plugins/generators/pkgmgr.txt
@@ -1,4 +1,4 @@
-.. -*- mode: rst -*-
+.. _plugins-generators-pkgmgr:
 
 ======
 Pkgmgr
diff --git a/doc/plugins/generators/sshbase.txt b/doc/plugins/generators/sshbase.txt
index 65fe1cca7..4741fc8eb 100644
--- a/doc/plugins/generators/sshbase.txt
+++ b/doc/plugins/generators/sshbase.txt
@@ -21,13 +21,13 @@ Interacting with SSHbase
 Aliases
 =======
 
-As of 1.0pre4, SSHbase has support for Aliases listed in clients.xml. The address for the entries are specified either through DNS (e.g. a CNAME), or via the address attribute to the Alias.
+SSHbase has support for Aliases listed in clients.xml. The address for the entries are specified either through DNS (e.g. a CNAME), or via the address attribute to the Alias.
 
 Getting started
 ===============
 
 #. Add SSHbase to the generators line (plugins line in 1.0 or greater) in /etc/bcfg2.conf and restart the server -- This enables the SSHbase plugin in the bcfg2 server.
-#. Add ConfigFile entries for /etc/ssh/ssh_known_hosts, and /etc/ssh/ssh_host_dsa_key, etc to a bundle or base.
+#. Add Path entries for /etc/ssh/ssh_known_hosts, and /etc/ssh/ssh_host_dsa_key, etc to a bundle or base.
 #. Enjoy.
 
 At this point, SSHbase will generate new keys for any client without a recorded key in the repository, and will generate an ssh_known_hosts file appropriately.
@@ -35,4 +35,4 @@ At this point, SSHbase will generate new keys for any client without a recorded
 Blog post
 =========
 
-[http://www.ducea.com/2008/08/24/using-the-bcfg2-sshbase-plugin/]
+http://www.ducea.com/2008/08/24/using-the-bcfg2-sshbase-plugin/
diff --git a/doc/plugins/grouping/metadata.txt b/doc/plugins/grouping/metadata.txt
index 2c169318f..f9ad44954 100644
--- a/doc/plugins/grouping/metadata.txt
+++ b/doc/plugins/grouping/metadata.txt
@@ -3,3 +3,145 @@
 ========
 Metadata
 ========
+
+The metadata mechanism has two types of information, client metadata and group metadata. The client metadata describes which top level group a client is associated with.The group metadata describes groups in terms of what bundles and other groups they include. Each aspect grouping and clients' memberships are reflected in the Metadata/groups.xml and Metadata/clients.xml files, respectively.
+
+Usage of Groups in Metadata
+===========================
+
+Clients are assigned membership of groups in the Metadata descriptions. Clients can be directly assigned to 'profile' or 'public' groups.  Client membership of all other groups is by those groups being associated with the profile or public groups. This file can be indirectly modified from clients through use of the -p flag to bcfg2.
+
+Clients are associated with profile groups in Metadata/clients.xml as shown below.
+
+Metadata/clients.xml
+====================
+
+The Metadata/clients.xml file contains the mappings of Profile Groups to clients. The
+file is just a series of <Client /> tags, each of which describe one host. A sample
+file is below:
+
+.. code-block:: xml
+
+    <Clients version="3.0">
+      <Client profile="backup-server" pingable="Y" pingtime="0" name="backup.example.com"/>
+      <Client profile="console-server" pingable="Y" pingtime="0" name="con.example.com"/>
+      <Client profile="kerberos-master" pingable="Y" pingtime="0" name="kdc.example.com"/>
+      <Client profile="mail-server" pingable="Y" pingtime="0" name="mail.example.com"/>
+      <Client name='foo' address='10.0.0.1' pingable='N' pingtime='-1'>
+          <Alias name='foo-mgmt' address='10.1.0.1'/>
+      </Client>
+    </Clients>
+
+Clients Tag
+-----------
+
+The Clients tag has the following possible attributes:
+
+|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
+|| version || Client schema version || String ||
+
+Client Tag
+----------
+
+Each entry in clients.xml '''must''' have the following properties:
+|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
+|| name || Host name of client.  This needs do be the name (possibly a FQDN) returned by a reverse lookup on the connecting IP address. || String ||
+|| profile || Profile group name to associate this client with || String ||
+
+Additionally, the following properties can be specified:
+|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
+|| Alias || Alternative name and address for the client || XML Element ||
+|| address || Establishes an extra ip address that resolves to this client || ip address ||
+|| location || Requires requests to come from an IP address that matches the client record || fixed|floating ||
+|| password  || Establishes a per-node password that can be used instead of the global password || String ||
+|| pingable || If the client is pingable (deprecated; for old reporting system) || (Y|N) ||
+|| pingtime || Last time the client was pingable (deprecated; for old reporting system) || String ||
+|| secure || Requires the use of the per-client password for this client || true|false ||
+|| uuid || Establishes a per-node name that can be used to bypass dns-based client resolution || String ||
+
+
+For detailed information on client authentication see [wiki:Authentication]
+
+Metadata/groups.xml
+-------------------
+
+The Metadata/groups.xml file contains Group and Profile definitions. Here's a simple
+Metadata/groups.xml file:
+
+.. code-block:: xml
+
+    <Groups version='3.0'>
+      <Group name='mail-server' profile='true'
+                                public='false'
+                                comment='Top level mail server group' >
+        <Bundle name='mail-server'/>
+        <Bundle name='mailman-server'/>
+        <Group name='apache-server'/>
+        <Group name='rhel-as-4-x86'/>
+        <Group name='nfs-client'/>
+        <Group name='server'/>
+      </Group>
+      <Group name='rhel-as-4-x86' toolset='rh'>
+         <Group name='rhel'/>
+      </Group>
+      <Group name='apache-server'/>
+      <Group name='nfs-client'/>
+      <Group name='server'/>
+      <Group name='rhel'/>
+    </Groups>
+
+
+Nested/chained groups definitions are conjunctive (logical and). For instance, in
+the above example, a client associated with the Profile Group 'mail-server' is
+also a member of the apache-server, rhel-as-4-x86, nfs-client, server and rhel
+groups.
+
+Groups describe clients in terms for abstract, disjoint aspects. Groups can be
+combined to form complex descriptions of clients that use configuration commonality
+and inheritance. Groups have several attributes, described below:
+
+
+Metadata Groups Tag
+-------------------
+
+The Groups tag has the following possible attributes:
+
+|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
+|| version || Group schema version || String ||
+|| origin || URL of master version (for common repo) || String ||
+|| revision || Master version control revision || String ||
+
+Metadata Group Tag
+------------------
+
+The Group Tag has the following possible attributes:
+
+|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
+|| name || Name of the group || String ||
+|| profile || If a client can be directly associated with this group || (True|False*) ||
+|| public || If a client can freely associate itself with this group.  For use with bcfg2 -p option on the client. || (True|False*) ||
+|| toolset || Describes which client-side logic should be used to make configuration changes || (rh|debian|solaris|aix|auto|gentoo) ||
+|| category || A group can only contain one instance of a group in any category. This provides the basis for representing groups which are conjugates of one another in a rigorous way. It also provides the basis for negation. || String ||
+|| default || Set as the profile to use for clients that are not associated with a profile in clients.xml. || (True|False*) ||
+|| comment || English text description of group || String ||
+
+Groups can also contain other groups and bundles.
+
+Use of XInclude
+===============
+
+[http://www.w3.org/TR/xinclude/ XInclude] is a W3C specification for the inclusion of external XML documents into XML source files. Much like the use of #include in C, this allows complex definitions to be split into smaller, more manageable pieces. As of bcfg2-0.9.0pre1, the Metadata plugin supports the use of XInclude specifications to split the clients.xml and groups.xml files. This mechanism allows the following specification to produce useful results:
+
+.. code-block:: xml
+
+    <Groups version='3.0' xmlns:xi="http://www.w3.org/2001/XInclude">
+     <xi:include href="my-groups.xml" />
+     <xi:include href="their-groups.xml" />
+    </Groups>
+
+Each of the included groups files has the same format. These files are properly validated by bcfg2-repo-validate. This mechanism is useful for composing group definitions from multiple sources, or setting different permissions in an svn repository.
+
+Probes
+======
+
+The metadata plugin includes client-side probing functionality. This is fully documented [wiki:Probes here].
diff --git a/doc/plugins/probes.txt b/doc/plugins/probes.txt
index b6b69d754..a888b776d 100644
--- a/doc/plugins/probes.txt
+++ b/doc/plugins/probes.txt
@@ -6,7 +6,7 @@ Probes
 
 At times you need to gather information from a client machine before you can generate its configuration.  For example, if some of your machines have both a local scratch disk and a system disk while others only have the system disk, you would want to know this information to correctly generate an `/etc/auto.master` autofs config file for each type.  Here we will look at how to do this.
 
-First you will need to set up the TCheetah plugin, as described on the [wiki:Plugins/TCheetah TCheetah Plugin] page.
+First you will need to set up the TCheetah plugin, as described on the :doc:`generators/tcheetah` page.
 
 Next, we need to create a `Probes` directory in our toplevel repository location::
 
@@ -60,14 +60,18 @@ With all of these pieces in place, the following series of events will happen wh
 #. Server hands `/etc/auto.master` down to the client
 #. Client puts file contents in place.
 
-Now we have a nicely dynamic `/etc/auto.master` that can gracefully handle machines with different numbers of disks.  All that's left to do is to add the `/etc/auto.master` to a Bundle::
+Now we have a nicely dynamic `/etc/auto.master` that can gracefully handle machines with different numbers of disks.  All that's left to do is to add the `/etc/auto.master` to a Bundle:
+
+.. code-block:: xml
 
     <ConfigFile name='/etc/auto.master'/>
 
 Other examples
 ==============
 
-Dynamically assign a group based on the Ubuntu version::
+Dynamically assign a group based on the Ubuntu version:
+
+.. code-block:: sh
 
     #!/bin/sh
 
@@ -75,7 +79,9 @@ Dynamically assign a group based on the Ubuntu version::
     . /etc/lsb-release
     echo group:$DISTRIB_CODENAME
 
-Detect if the server is a Linux-VServer host::
+Detect if the server is a Linux-VServer host:
+
+.. code-block:: sh
 
     #!/bin/sh
 
diff --git a/doc/plugins/statistics/dbstats.txt b/doc/plugins/statistics/dbstats.txt
index 4afca4afe..001067974 100644
--- a/doc/plugins/statistics/dbstats.txt
+++ b/doc/plugins/statistics/dbstats.txt
@@ -3,3 +3,5 @@
 =======
 DBStats
 =======
+
+
diff --git a/doc/plugins/structures/base.txt b/doc/plugins/structures/base.txt
index ead775c10..b63ee5cc9 100644
--- a/doc/plugins/structures/base.txt
+++ b/doc/plugins/structures/base.txt
@@ -3,3 +3,5 @@
 ====
 Base
 ====
+
+The Base plugin is a structure plugin that provides the ability to add lists of unrelated entries into client configuration entry inventories. Base works much like Bundler in its file format. The main difference between Base and Bundler is that Base files are included in all clients' configuration whereas bundles must be included explicitly in your Metadata. See the :doc:`bundler` page for details.
diff --git a/doc/plugins/structures/bundler.txt b/doc/plugins/structures/bundler.txt
index 1efbca878..9d663e90c 100644
--- a/doc/plugins/structures/bundler.txt
+++ b/doc/plugins/structures/bundler.txt
@@ -1,5 +1,139 @@
-.. -*- mode: rst -*-
+.. _plugins-structures-bundler:
 
 =======
 Bundler
 =======
+
+Bundler is used to describe groups of inter-dependent configuration entries, such as the combination of packages, configuration files, and service activations that comprise typical Unix daemons. Bundles are used to add groups of configuration entries to the inventory of client configurations, as opposed to describing particular versions of those entries. For example, a bundle could say that the configuration file "/etc/passwd" should be included in a configuration, but will not describe the particular version of "/etc/passwd" that a given client will receive.
+
+Groups can be used inside of bundles to differentiate which entries particular clients will recieve; this is useful for the case where entries are named differently across systems; for example, one linux distro may have a package called openssh while another uses the name ssh. Configuration entries nested inside of Group elements only apply to clients who are a member of those groups; multiply nested groups must all apply. Also, groups may be negated; entries included in such groups will only apply to clients who are not a member of said group.
+
+The following is an annotated copy of a bundle:
+
+.. code-block:: xml
+
+    <Bundle revision='$Revision: 2668 $' name='ssh' version='2.0'
+            origin='https://svn.mcs.anl.gov/repos/bcfg/trunk/repository/Bundler/ssh.xml'>
+      <ConfigFile name='/etc/ssh/ssh_host_dsa_key'/>
+      <ConfigFile name='/etc/ssh/ssh_host_rsa_key'/>
+      <ConfigFile name='/etc/ssh/ssh_host_dsa_key.pub'/>
+      <ConfigFile name='/etc/ssh/ssh_host_rsa_key.pub'/>
+      <ConfigFile name='/etc/ssh/ssh_host_key'/>
+      <ConfigFile name='/etc/ssh/ssh_host_key.pub'/>
+      <ConfigFile name='/etc/ssh/sshd_config'/>
+      <ConfigFile name='/etc/ssh/ssh_config'/>
+      <ConfigFile name='/etc/ssh/ssh_known_hosts'/>
+      <Group name='rpm'>
+        <Package name='openssh'/>
+        <Package name='openssh-askpass'/>
+        <Service name='sshd'/>
+        <Group name='fedora' >
+           <Group name='fc4' negate='true'>
+             <Package name='openssh-clients'/>
+           </Group>
+           <Package name='openssh-server'/>
+        </Group>
+      </Group>
+      <Group name='deb'>
+        <Package name='ssh'/>
+        <Service name='ssh'/>
+      </Group>
+    </Bundle>
+
+In this bundle, most of the entries are common to all systems. Clients in group "deb" get one extra package and service, while clients in group "rpm" get two extra packages and an extra service. In addition, clients in group "fedora" and group "rpm" get one extra package entries, unless they are not in the fc4 group, in which case, they get an extra package. Notice that this file doesn't describe which versions of these entries that clients should get, only that they should get them. (Admittedly, this example is slightly contrived, but demonstrates how group entries can be used in bundles)
+
+|| '' '''Group''' '' || '' '''Entry''' '' ||
+|| all || /etc/ssh/ssh_host_dsa_key ||
+|| all || /etc/ssh/ssh_host_rsa_key ||
+|| all || /etc/ssh/ssh_host_dsa_key.pub ||
+|| all || /etc/ssh/ssh_host_rsa_key.pub ||
+|| all || /etc/ssh/ssh_host_key ||
+|| all || /etc/ssh/ssh_host_key.pub ||
+|| all || /etc/ssh/sshd_config ||
+|| all || /etc/ssh/ssh_config ||
+|| all || /etc/ssh/ssh_known_hosts ||
+|| rpm || Package openssh ||
+|| rpm || Package openssh-askpass ||
+|| rpm || Service sshd ||
+|| rpm and fedora || Package openssh-server ||
+|| rpm and fedora and not fc4 || Package openssh-clients ||
+|| deb || Package ssh ||
+|| deb || Service ssh ||
+
+Genshi templates
+================
+
+Genshi templates are used by adding a Genshi xml-style template to the Bundler directory with a `.genshi` file extension. Version 0.4 or newer of genshi is required.
+
+Motivation
+----------
+
+Static Bundles have served us relatively well, but have a relatively weak set of interal per-client differentiation mechanisms. In static Bundles, the group hierarchy (from the perspective of the current client) is available for use via boolean constraints with negation. This notion does not mesh well with the use of Probes, which can result in freeform data. In the presence of probe results, clients can have a wide array of data, and rendering down to a boolean logic may not always be desirable. Moreover, while static Bundles allow entry inclusion or exclusion based on group memberships, they do not allow programatic entry rendering. Hence, Genshi templates not only provide more control options, but it also provide the ability to perform new entry rendering operations.
+
+The [http://genshi.edgewall.org/ Genshi templating system] is used internally.
+
+Use
+---
+
+Bcfg uses the Genshi API for templates, and performs a XML format stream rendering of the template into an lxml entry, which is included in the client configuration. Client metadata is avilable inside of the template using the 'metadata' name. Note that only the markup Genshi template format can be used, as the target output format is XML.
+
+An Genshi template looks much like a Bundler file, except the Bundle tag has an additional `xmlns:py` attribute. See the examples.
+
+Examples
+--------
+
+In some cases, configuration files need to include the client's hostname in their name. The following template produces such a config file entry.
+
+.. code-block:: xml
+
+    <Bundle name='foo'  xmlns:py="http://genshi.edgewall.org/">
+        <Path name='/etc/package-${metadata.hostname}'/>
+    </Bundle>
+
+Depending on the circumstance, these configuration files can either be handled by individual entries in :doc:`../generators/cfg`, :doc:`../generators/tcheetah`, or :doc:`../generators/tgenshi`, or can be mapped to a single entry by using the [wiki:altsrc] feature.
+
+In this example, configuration file names are built using probed results from the client. getmac is a probe that gathers client MAC addresses and returns them in a newline delimited string.
+
+.. code-block:: xml
+
+    <Bundle name='networkinterfaces' xmlns:py="http://genshi.edgewall.org/">
+        <?python
+          files = $metadata.Probes["getmacs"].split("\n")
+        ?>
+        <Path py:for="file in files" name="/etc/sysconfig/network/ifcfg-eth-${file}" altsrc='/etc/ifcfg-template'/>
+    </Bundle>
+
+.. note::
+   * The use of the altsrc directive causes all ifcfg files to be handled by the same plugin and entry.
+   * The <?python ?> blocks have only been available in genshi since 0.4 (http://genshi.edgewall.org/ticket/84)
+
+If you want a file to be only on a per-client basis, you can use an if declaration:
+
+.. code-block:: xml
+
+    <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/">
+         <Path name="/etc/bacula/bconsole.conf"/>
+         <Path name="/etc/bacula/bacula-fd.conf"/>
+         <Path name="/etc/bacula/bacula-sd.conf"/>
+         <Path py:if="metadata.hostname == 'foo.bar.com'" name="/etc/bacula/bacula-dir.conf"/>
+    </Bundle>
+
+or alternately:
+
+.. code-block:: xml
+
+    <Bundle name='bacula' xmlns:py="http://genshi.edgewall.org/">
+        <Path name="/etc/bacula/bconsole.conf"/>
+        <Path name="/etc/bacula/bacula-fd.conf"/>
+        <Path name="/etc/bacula/bacula-sd.conf"/>
+        <py:if test="metadata.hostname == 'foo.bar.com'">
+            <Path name="/etc/bacula/bacula-dir.conf"/>
+        </py:if>
+    </Bundle>
+
+The latter form is preferred if the if block contains multiple files. While this example is simple, the test in the if block can in fact be any python statement.
+
+Examples
+--------
+
+See [wiki:Plugins/Bundler/examples this] page for more Bundler examples.
diff --git a/doc/plugins/version/bzr.txt b/doc/plugins/version/bzr.txt
index 83bea745e..d4e624daf 100644
--- a/doc/plugins/version/bzr.txt
+++ b/doc/plugins/version/bzr.txt
@@ -3,3 +3,21 @@
 ===
 Bzr
 ===
+
+Why use the Bazaar plugin
+=========================
+
+The Bazaar plugin is useful if you would like to track changes to your bcfg2 repository using a `Bazaar <http://bazaar-vcs.org/>`_ backend. Currently, it enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server.
+
+How to enable the Bazaar plugin
+===============================
+
+Simply add "Bzr" to your plugins line in /etc/bcfg2.conf::
+
+    [server]
+    plugins = Base,Bundler,Cfg,...,Bzr
+
+Usage notes
+===========
+
+Unlike other VCS plugins for BCFG2, the Bazaar plugin checks whether there are uncommitted changes to the repository. If there are, this plugin appends a "+" after the version number. Essentially, this means you're using that version, "plus" some changes.
diff --git a/doc/plugins/version/fossil.txt b/doc/plugins/version/fossil.txt
index 893ab266e..d77e45693 100644
--- a/doc/plugins/version/fossil.txt
+++ b/doc/plugins/version/fossil.txt
@@ -3,3 +3,16 @@
 ======
 Fossil
 ======
+
+Why use the Fossil plugin
+=========================
+
+The Fossil plugin is useful if you would like to track changes to your bcfg2 repository using a `Fossil SCM <http://fossil-scm.org>`_ backend. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server.
+
+How to enable the Fossil plugin
+===============================
+
+Simply add "Fossil" to your plugins line in /etc/bcfg2.conf::
+
+    [server]
+    plugins = Base,Bundler,Cfg,...,Fossil
diff --git a/doc/plugins/version/git.txt b/doc/plugins/version/git.txt
index 621c64127..1b538f475 100644
--- a/doc/plugins/version/git.txt
+++ b/doc/plugins/version/git.txt
@@ -3,3 +3,16 @@
 ===
 Git
 ===
+
+Why use the Git plugin
+======================
+
+The Git plugin is useful if you would like to track changes to your bcfg2 repository using a `Git <http://git-scm.com/>`_ backend. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server.
+
+How to enable the Git plugin
+============================
+
+The Git plugin uses `Dulwich <http://samba.org/~jelmer/dulwich/>`_ to interface with git repositories. Therefore, you will need to install Dulwich on the bcfg2 server first. Once installed, simply add Git to your plugins line in /etc/bcfg2.conf::
+
+    [server]
+    plugins = Base,Bundler,Cfg,...,Git
diff --git a/doc/plugins/version/svn.txt b/doc/plugins/version/svn.txt
index cfe44c707..e5ceb7aef 100644
--- a/doc/plugins/version/svn.txt
+++ b/doc/plugins/version/svn.txt
@@ -3,3 +3,16 @@
 ===
 Svn
 ===
+
+Why use the Svn plugin
+======================
+
+The Svn plugin is useful if you would like to track changes to your bcfg2 repository using a `Subversion <http://subversion.tigris.org/>`_ backend. It deprecates the previous Subversion integration mentioned here at ftp://ftp.mcs.anl.gov/pub/bcfg/papers/directing-change-with-bcfg2.pdf. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server.
+
+How to enable the Svn plugin
+============================
+
+Simply add Svn to your plugins line in /etc/bcfg2.conf::
+
+    [server]
+    plugins = Base,Bundler,Cfg,DBStats,Decisions,Metadata,NagiosGen,Pkgmgr,Probes,Rules,SSHbase,TGenshi,Svn