doc: Add server/reports sections

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

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

3 files changed, 194 insertions, 13 deletions

diff --git a/doc/unsorted/annotated_examples.txt b/doc/unsorted/annotated_examples.txt
new file mode 100644
index 000000000..99c6f774c
--- /dev/null
+++ b/doc/unsorted/annotated_examples.txt
@@ -0,0 +1,186 @@
+.. -*- mode: rst -*-
+
+.. _unsorted-annotated_examples:
+
+==================
+Annotated Examples
+==================
+
+ntp example
+===========
+
+Author: Jason Pepas 
+
+Here is a series of example configurations for bcfg2, each introducing another layer of functionality.  
+
+* After each change, run 'bcfg-repo-validate -v'.  
+* Run the server with 'bcfg2-server -v'.  
+* Update the client with 'bcfg2 -v -d -n'. (will not actually make client changes)
+
+package only
+------------
+
+Our example starts with the bare minimum configuration setup.  We have a client, a profile group, a list of packages, and a base configuration.
+
+::
+
+    # cat Metadata/clients.xml 
+    <Clients version='3.0'>
+    <Client profile='fedora' pingable='N' pingtime='0' name='foo.bar.com'/>
+    </Clients>
+
+    # cat Metadata/groups.xml 
+    <Groups version='3.0'>
+    <Group profile='true' name='fedora' toolset='rh'/>
+    </Groups>
+
+    # cat Base/base.xml 
+    <Base>
+    <Group name='fedora'>
+    <Package name='ntp'/>
+    </Group>
+    </Base>
+
+    # cat Pkgmgr/packages.xml
+    <PackageList type='rpm' priority='0'>
+    <Package name='ntp' version='4.2.0.a.20050816-11.FC5'/>
+    </PackageList>
+
+add service
+-----------
+
+Configure the service, and add it to the base.::
+
+    # cat Svcmgr/services.xml 
+    <Services priority='0'>
+    <Service name='ntpd' status='on'/>
+    </Services>
+
+    # cat Base/base.xml 
+    <Base>
+    <Group name='fedora'>
+    <Package name='ntp'/>
+    <Service name='ntpd'/>
+    </Group>
+    </Base>
+
+add config file
+---------------
+
+Setup an etc directory structure, and add it to the base.::
+
+    # cat Cfg/etc/ntp.conf/ntp.conf 
+    server ntp1.utexas.edu
+
+    # cat Base/base.xml 
+    <Base>
+    <Group name='fedora'>
+    <Package name='ntp'/>
+    <Service name='ntpd'/>
+    <ConfigFile name='/etc/ntp.conf'/>
+    </Group>
+    </Base>
+
+create a bundle
+---------------
+
+The above configuration layout works fine for a single service, but
+that method of organization would quickly become a nightmare as you
+approach the number of packages, services, and config files required
+to represent a fully configured host.  Bundles allow the grouping of
+related configuration entries that are used to provide a single
+service. This is done for several reasons:
+
+* Grouping related things in one place makes it easier to add those
+  entries for a multiple groups of clients
+* Grouping entries into bundles makes their validation occur
+  collectively. This means that config files can override the
+  contents of packages. Also, config files are rechecked after
+  packages are upgraded, so that they can be repaired if the package
+  install clobbered them. 
+* Services associated with a bundle get restarted whenever any
+  entity in that bundle is modified. This ensures that new
+  configuration files and software are used after installation.
+
+The config file, package, and
+service are really all related components describing the idea of an
+ntp client, so they should be logically grouped together.  We use a
+bundle to accomplish this.::
+
+    # cat Bundler/ntp.xml
+    <Bundle name='ntp' version='2.0'>
+    <Package name='ntp'/>
+    <Service name='ntpd'/>
+    <ConfigFile name='/etc/ntp.conf'/>
+    </Bundle>
+
+After this bundle is created, it must be associated with a group (or
+groups). Add a bundle child element to the group(s) which should install this bundle.::
+
+
+    # cat Metadata/groups.xml
+    <Groups>
+    ...
+    <Group name='fedora'>
+      <Bundle name='ntp'/>
+    </Group>
+    ...
+    </Groups>
+
+Once this bundle is created, a client reconfigure will install these
+entries. If any are modified, then the ntpd service will be
+restarted. If you only want ntp configurations to be updated (and
+nothing else), the bcfg2 client can be run with a -b <bundle name>
+option that will only update entries in the specified bundle.
+
+mysql example
+=============
+
+Author: Patrick Ruckstuhl
+
+I had some time ago to continue with putting my configuration into
+bcfg2 and maybe this helps someone else.
+
+I added a new bundle:
+
+.. code-block: xml
+
+    <Bundle name="mysql-server" version="3.0">
+       <ConfigFile name="/root/bcfg2-install/mysql/users.sh"/>
+       <ConfigFile name="/root/bcfg2-install/mysql/users.sql"/>
+       <PostInstall name="/root/bcfg2-install/mysql/users.sh"/>
+       <Package name="mysql-server-4.1"/>
+       <Service name="mysql"/>
+    </Bundle>
+
+The `users.sh` script looks like this:
+
+.. code-block: sh
+
+    #!/bin/sh
+
+    mysql --defaults-extra-file=/etc/mysql/debian.cnf mysql \
+        < /root/bcfg2-install/mysql/users.sql
+
+On debian there is a user account in `/etc/mysql/debian.cnf` automatically created, but you could also (manually) create a user in the database that has enough permissions and add the login information in a file yourself. This file looks like this::
+
+    [client]
+    host     = localhost
+    user     = debian-sys-maint
+    password = XXXXXXXXXX
+
+The `users.sql` looks like this::
+
+    DELETE FROM db;
+    INSERT INTO db VALUES ('localhost', 'phpmyadmin', 'pma', 'Y', 'Y',
+    'Y', 'Y', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N');
+
+    DELETE FROM user WHERE User <> 'debian-sys-maint';
+    INSERT INTO user VALUES ('localhost', 'root', 'XXXXXXXXXXX', 'Y', 'Y',
+    'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y',
+    'Y', 'Y', 'Y', 'Y', 'Y', '', '', '', '', 0, 0, 0);
+    INSERT INTO user VALUES ('localhost', 'pma', '', 'N', 'N', 'N', 'N',
+    'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N',
+    'N', 'N', 'N', '', '', '', '', 0, 0, 0);
+
+    FLUSH PRIVILEGES;
diff --git a/doc/unsorted/index.txt b/doc/unsorted/index.txt
index 63426c774..17feb13e6 100644
--- a/doc/unsorted/index.txt
+++ b/doc/unsorted/index.txt
@@ -13,14 +13,12 @@ list below.
 
 .. _TitleIndex: https://trac.mcs.anl.gov/projects/bcfg2/wiki/TitleIndex
 
-* `Annotated Examples`
 * `ManualPages`
 * `NewDynamicReports`
 * `NewDynamicReportsInstallation`
 * `News`
 * `Overview`
 * `ParanoidMode`
-* `Plugins`
 * `Plugins/Account`
 * `Plugins/Actions`
 * `Plugins/Bundler/examples`
@@ -66,19 +64,10 @@ list below.
 * `QuickStart3`
 * `RecentChanges`
 * `RefactorClient`
-* `Reports`
-* `Reports/Dynamic`
-* `Reports/Dynamic/Installation`
-* `Reports/Static`
-* `SandBox`
 * `SchemaEvolution`
 * `SecurityDevPlan`
 * `ServerSideOverview`
-* `TGenshi/examples`
 * `TGenshi/examples/Templated_Access`
-* `TGenshi/examples/bcfg2_cron`
-* `TGenshi/examples/clients.xml`
-* `TGenshi/examples/test`
 * `TOC`
 * `TrackingDevelopmentTrunk`
 * `Troubleshooting`
diff --git a/doc/unsorted/windows.txt b/doc/unsorted/windows.txt
index 33b45d67d..128bc52d6 100644
--- a/doc/unsorted/windows.txt
+++ b/doc/unsorted/windows.txt
@@ -15,7 +15,8 @@ Notes on possible Windows support
 Services
 ========
 
-With the exception of 32/64 bit issues, Windows Services support should be pretty trivial; it would differ from *nix services in that it would be done via WMI API calls and not a 3rd party python module or wrapping a binary.
+With the exception of 32/64 bit issues, Windows Services support should
+be pretty trivial; it would differ from \*nix services in that it would be done via WMI API calls and not a 3rd party python module or wrapping a binary.
 
 Registry
 ========
@@ -25,7 +26,8 @@ The best way of handling the registry may be to map it into a file-based represe
 Files
 =====
 
-For a first run there may be some way of utilizing [http://cygwin.com/ cygwin] to make use of the existing *nix POSIX module for manipulating files. There would probably need to be some changes to deal with the fact that open files can't be manipulated/moved/deleted at all in Windows (other than to do some registry magic that makes the changes on the next reboot).
+For a first run there may be some way of utilizing [http://cygwin.com/
+cygwin] to make use of the existing \*nix POSIX module for manipulating files. There would probably need to be some changes to deal with the fact that open files can't be manipulated/moved/deleted at all in Windows (other than to do some registry magic that makes the changes on the next reboot).
 
 Packages
 ========
@@ -39,13 +41,17 @@ Prior FLOSS Art
 
 * [http://www.autoitscript.com/autoit3/ AutoIt] - For dealing with packages that don't have a silent install option
 * [http://www.opensysadmin.com/trac/ticket/4 French Stuff]
+
  * [http://ocsinventory.sourceforge.net/ Open Computers and Software Inventory - Next Generation]
  * [http://www.glpi-project.org/spip.php?lang=en GLPI - Gestionnaire libre de parc informatique]
+
 * Javascript thing a colleague of Desai's at ANL wrote - Desai was going to see if this can be released
 * [http://sial.org/howto/cfengine/windows/ Managing Windows with CFEngine and Perl]
 * [http://www.dmst.aueb.gr/dds/sw/outwit/ Outwit] - Small unixy utilities for Windows stuff like the registry and clipboard
 * [http://www.cfengine.org/docs/cfengine-NT/ Porting cfengine to Windows NT]
 * [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click] - Tobi Oetiker's stuff
+
  * [http://isg.ee.ethz.ch/tools/realmen/res/index.en.html More Prior FLOSS Art]
+
 * [http://unattended.sourceforge.net/ Unattended] - Bare Metal Installs, Package Management
 * [http://wpkg.org/ WPKG] - Package Management