doc: Merge in documentation updates for base plugin from m4z

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

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

1 files changed, 61 insertions, 0 deletions

diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt
index 21244172e..47fba8334 100644
--- a/doc/server/plugins/structures/base.txt
+++ b/doc/server/plugins/structures/base.txt
@@ -8,8 +8,69 @@ 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 :ref:`server-plugins-structures-bundler-index` page
 for details.
+
+If you have lots of unconnected items (for instance: software packages
+whose configuration wasn't modified, and that are also not depended
+on by other packages; or single directories or files not belonging
+to a package), using Bundles in Metadata would clutter or enlarge
+your ``Metadata/groups.xml`` file, because they all would need to be
+explicitly specified. ``Base/`` on the other hand is the perfect place
+to put these items.
+
+Without using Base, you would be forced to put them directly
+into your group definitions in ``groups.xml``, either as many
+small bundles (substantially enlarging it) or into something like
+``Bundler/unrelated-entries.xml``. Using the latter is especially bad
+if you mix packages and services in your Bundle, since for any updated
+package in that bundle, the now-related services would be restarted.
+
+The Base entries can still be assigned based on group membership, but when
+they aren't part of a group, each and every client gets the entry. So Base is
+also a great place to put entries that a large number of your clients will
+get.
+
+For example, you could have a file ``Base/packages.xml``
+
+.. code-block:: xml
+
+    <Base>
+        <Package name='acpid'/>
+        <Package name='auditd'/>
+        [...]
+        <Group name='openSUSE11.2'>
+            <Package name='syslog-ng'/>
+        </Group>
+        <Group name='openSUSE11.3'>
+            <Package name='rsyslog'/>
+        </Group>
+        [...]
+        <Package name='zlib'/>
+    </Base>
+
+.. note::
+
+    You don't have to reference to the files in Base from anywhere. As long
+    as you include ``Base`` in your ``plugins = ...`` line in ``bcfg2.conf``,
+    these are included automatically.
+
+.. note::
+
+    Your Base files have to match the pattern ``Base/*.xml`` to be included.
+
+
+The decision when to use Base and when to use Bundler depends on the
+configuration entry in question, and what you are trying to achieve.
+
+Base is mainly used for cases where you don't want/need to explicitly
+include particular configuration items. Let's say all your machines are
+various linux distributions. In this case, you may want to manage the
+``/etc/hosts`` file using Base instead of Bundler since you will not have
+to include any Bundles in your Metadata. However, you could alternatively
+have a base 'linux' group that all the clients inherit which includes a
+'linux' Bundle with the ``/etc/hosts`` configuration entry.