From ea22d56e7cc1774f4d103e8138a569c4e20fec3a Mon Sep 17 00:00:00 2001
From: Sol Jerome <solj@ices.utexas.edu>
Date: Mon, 23 Aug 2010 15:56:36 +0000
Subject: doc: Add the rest of the altsrc documentation for Ticket #923

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

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@6029 ce84e21b-d406-0410-9b95-82705330c041
---
 doc/server/plugins/structures/altsrc.txt | 47 ++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/server/plugins/structures/altsrc.txt b/doc/server/plugins/structures/altsrc.txt
index a84e9c72e..fd7978efb 100644
--- a/doc/server/plugins/structures/altsrc.txt
+++ b/doc/server/plugins/structures/altsrc.txt
@@ -6,8 +6,12 @@
 Fun and Profit using altsrc
 ===========================
 
+.. versionadded:: 0.9.5
+
 Altsrc is a generic, bcfg2-server-side mechanism for performing
 configuration entry name remapping for the purpose of data binding.
+Altsrc can be used as a parameter for any entry type, and can be used
+in any structure, including Bundler and Base.
 
 Use Cases
 =========
@@ -52,3 +56,46 @@ Examples
   using a bundle like:
 
   .. code-block:: xml
+
+      <Bundle name='openssl'>
+         <Package name='openssl' altsrc='openssl-encap'/>
+         <Package name='openssl' altsrc='openssl-rpm'/>
+      </Bundle>
+
+  This bundle will bind data for the packages "openssl-encap" and
+  "openssl-rpm", but will be delivered to the client with both packages
+  named "openssl" with different types.
+
+* Finally, consider the case where there exist complicated, but
+  completely independent specifications for the same configuration entry
+  but different groups of clients. The following bundle will allow the
+  use of two different TCheetah templates /etc/firewall-rules-external
+  and /etc/firewall-rules-internal for different clients based on their
+  group membership.
+
+  .. code-block:: xml
+
+      <Bundle name='firewall'>
+         ...
+         <Group name='conduit'>
+           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-external'/>
+         </Group>
+         <Group name='internal'>
+           <Path name='/etc/firewall-rules' altsrc='/etc/firewall-rules-internal'/>
+         </Group>
+      </Bundle>
+
+* Consider the case where a variety of files can be constructed by a
+  single template (TCheetah or TGenshi). It would be possible to copy
+  this template into the proper location for each file, but that requires
+  proper synchronization upon modification and knowing up front what
+  the files will all be called. Instead, the following bundle allows
+  the use of a single template for all proper config file instances.
+
+  .. code-block:: xml
+
+      <Bundle name='netconfig'>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth0' altsrc='/etc/ifcfg-template'/>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth1' altsrc='/etc/ifcfg-template'/>
+        <Path name='/etc/sysconfig/network-scripts/ifcfg-eth2' altsrc='/etc/ifcfg-template'/>
+      </Bundle>
-- 
cgit v1.2.3-1-g7c22