doc: Correct Snapshots plugin documentation (Reported by m4z on IRC)

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

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

1 files changed, 145 insertions, 11 deletions

diff --git a/doc/server/snapshots/index.txt b/doc/server/snapshots/index.txt
index a961aa167..ca8af2663 100644
--- a/doc/server/snapshots/index.txt
+++ b/doc/server/snapshots/index.txt
@@ -2,21 +2,155 @@
 
 .. _server-snapshots-index:
 
+===============
 Bcfg2 Snapshots
 ===============
 
-Bcfg2's reporting system is its killer feature. It allows administrators
-to gain a broad understanding of the configuration state of their entire
-environment. It summarizes
+.. versionadded:: 1.0.0
+
+This page describes the Snapshots plugin. This plugin is meant to replace
+the older :ref:`server-reports-dynamic`. It stores various
+aspects of a client's state when the client checks into the server.
+
+Before you begin
+================
+
+Make sure you have version 0.5 or greater of sqlalchemy.
+
+On CentOS/RHEL 5
+----------------
+
+* Download a tarball of SQLAlchemy.
+* Extract and build the RPM::
+
+      tar xzf SQLAlchemy-0.5.6.tar.gz
+      cd SQLAlchemy-0.5.6
+      python setup.py bdist_rpm
+
+* Copy the RPM in ``SQLAlchemy-0.5.6/dist/`` to your Yum repository,
+  and rebuild the repository using ``createrepo``.
+* Clear the Yum cache::
+
+      sudo yum clean all
+
+* Install SQLAlchemy::
+
+      sudo yum install SQLAlchemy
+
+* Manage the package in Bcfg2 as you would any other package.
+
+Configuration
+=============
+
+* A database location needs to be added to ``bcfg2.conf``. Three drivers
+  are currently supported; mysql, postgres, and sqlite. When using the
+  sqlite driver, only the driver and database lines are required.
+
+  * For MySQL::
+
+        [snapshots]
+        driver = mysql
+        database = snapshots
+        user = snapshots
+        password = snapshots
+        host = dbserver
+
+  * For SQLite::
+
+        [snapshots]
+        driver = sqlite
+        database = /var/lib/bcfg2/var/snapshots.sqlite
+
+* The database needs to be initialized.::
+
+      $ bcfg2-admin snapshots init
+      2009-03-22 21:40:24,683 INFO sqlalchemy.engine.base.Engine.0x...3e2c PRAGMA table_info("connkeyval")
+      PRAGMA table_info("connkeyval")
+      2009-03-22 21:40:24,684 INFO sqlalchemy.engine.base.Engine.0x...3e2c ()
+      ()
+      2009-03-22 21:40:24,686 INFO sqlalchemy.engine.base.Engine.0x...3e2c PRAGMA table_info("package")
+      PRAGMA table_info("package")
+      2009-03-22 21:40:24,687 INFO sqlalchemy.engine.base.Engine.0x...3e2c ()
+      ()
+      .....
+      COMMIT
+
+* The Snapshots plugin needs to be enabled for the bcfg2-server (by adding
+  Snapshots to the plugins line in ``/etc/bcfg2.conf``). Once done,
+  this will cause the the server to store statistics information when
+  clients run.
+
+Using the reports interface
+===========================
+
+All hosts::
+
+    $ bcfg2-admin snapshots reports -a
+
+    ============= ========= ========================================== ============================
+    Client        Correct   Revision                                   Time
+    ============= ========= ========================================== ============================
+    bcfg2client   True      f46ac7773712bd3c3cfb765ae5d2a3b2a37ac9b7   2009-04-23 11:27:54.378941
+    ============= ========= ========================================== ============================
+
+List bad entries for a single host::
+
+    $ bcfg2-admin snapshots reports -b bcfg2client
+    Bad entries:
+     Package:nscd
+     Package:cupsys
+     File:/etc/ldap.conf
+
+List extra entries for a single host::
+
+    $ bcfg2-admin snapshots reports -e bcfg2client
+    Extra entries:
+     Package:python-pyxattr
+     Package:librsync1
+     Package:python-pylibacl
+     Package:gcc-4.2-multilib
+     Package:nxlibs
+     Package:freenx-session-launcher
+     Package:dx-doc
+     Package:dirdiff
+     Package:libhdf4g
+     Package:nxclient
+     Package:freenx-rdp
+     Package:freenx-vnc
+     Package:libxml2-dev
+     Package:mysql-client
+     Package:mysql-client-5.0
+     Package:libxcompext3
+     Package:lib32gomp1
+     Package:dx
+     Package:freenx-media
+     Package:dxsamples
+     Package:gcc-multilib
+     Package:rdiff-backup
+     Package:libdbd-mysql-perl
+     Package:libxcomp3
+     Package:freenx-server
+     Package:smbfs
+     Package:planner
+     Package:nxagent
+     Package:libc6-dev-i386
+     Package:libfltk1.1-dev
+     Package:freenx
+     Package:libdx4
+     Package:libxcompshad3
+     Service:freenx-server
 
-* Configuration changes and when they were made
-* Discrepancies between the specification and current client states
+Detailed view of hosts for a particular date::
 
-  * Clients can be grouped by misconfiguration type
+    $ bcfg2-admin snapshots reports --date 2009 5 30
+    ============= ========= ========================================== ============================
+    Client        Correct   Revision                                   Time
+    ============= ========= ========================================== ============================
+    bcfg2client   False     10c1a12c62c57c0861cc453b8d2640c4839a7357   2009-05-29 10:52:34.701056
 
-* Configuration entries that are not specified
-* Overall client summaries according to these types
+TODO/Wishlist
+=============
 
-There are two systems, the old system, which builds static reports based
-on a series of XSLT stylesheets and a new dynamic reporting system that
-uses django and a database backend.
+* Identify per-client changes in correctness over time
+* Detailed view for a particular date
+* Track entry changes over time (glibc updated on these dates to these versions)