doc: Clarify dynamic reports installation/documentation

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

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

5 files changed, 126 insertions, 119 deletions

diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt
index a6994e714..01c264233 100644
--- a/doc/getting_started/index.txt
+++ b/doc/getting_started/index.txt
@@ -42,7 +42,7 @@ Misc/Others
 Reporting
 =========
 
-* `Reports`
+* :ref:`server-reports-index`
 
 Examples
 ========
diff --git a/doc/index.txt b/doc/index.txt
index c9a8efc73..54c8176c2 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -41,18 +41,24 @@ Architecture
 ------------
 
 Bcfg2 provides a declarative interface to system configuration. It was
-designed and implemented in-house at Argonne National Laboratory, but has matured to the
-point that external sites have begun using it. Its configuration
-specifications describe a literal configuration goal state for
-clients. In this architecture, the Bcfg2 client tool is responsible
+designed and implemented in-house at Argonne National Laboratory, but
+has matured to the point that external sites have begun using it. Its
+configuration specifications describe a literal configuration goal state
+for clients. In this architecture, the Bcfg2 client tool is responsible
 for determining what, if any, configuration operations must occur and
-then performing those operations. The client also uploads statistics and client
-configuration state information. The design and implementation of the reporting system is described in a separate [wiki:Reports page].
+then performing those operations. The client also uploads statistics and
+client configuration state information. The design and implementation
+of the reporting system is described in a separate
+:ref:`page <server-reports-index>`.
 
 Server
 ^^^^^^
 
-The role of the bcfg2 server is rendering a client-specific target configuration description from a global specification. The specification consists of a directory structure containing data for a variety of server plugins. The bcfg2 server has a plugin interface that can be used to interpret parts configuration specification.
+The role of the bcfg2 server is rendering a client-specific target
+configuration description from a global specification. The specification
+consists of a directory structure containing data for a variety of server
+plugins. The bcfg2 server has a plugin interface that can be used to
+interpret parts configuration specification.
 
 Client
 ^^^^^^
diff --git a/doc/quickstart/ubuntu.txt b/doc/quickstart/ubuntu.txt
index 2761187c6..1881007ff 100644
--- a/doc/quickstart/ubuntu.txt
+++ b/doc/quickstart/ubuntu.txt
@@ -471,74 +471,81 @@ Now we run the client and see there are no more unmanaged entries! ::
 Dynamic (web) Reports
 ---------------------
 
-First, `aptitude install python-django apache2 libapache2-mod-python`.
-
- * Now we need to create the sqlite database::
-
-    root@lucid:~# python /usr/share/pyshared/Bcfg2/Server/Reports/manage.py syncdb
-    Creating table auth_permission
-    Creating table auth_group
-    Creating table auth_user
-    Creating table auth_message
-    Creating table django_content_type
-    Creating table django_session
-    Creating table django_site
-    Creating table django_admin_log
-    Creating table reports_client
-    Creating table reports_ping
-    Creating table reports_interaction
-    Creating table reports_reason
-    Creating table reports_entries
-    Creating table reports_entries_interactions
-    Creating table reports_performance
-    Creating table reports_internaldatabaseversion
-
-    You just installed Django's auth system, which means you don't have any superusers defined.
-    Would you like to create one now? (yes/no): no
-    Installing index for auth.Permission model
-    Installing index for auth.Message model
-    Installing index for admin.LogEntry model
-    Installing index for reports.Client model
-    Installing index for reports.Ping model
-    Installing index for reports.Interaction model
-    Installing index for reports.Entries model
-    Installing index for reports.Entries_interactions model
-
- * Add DBStats to the plugins line of bcfg2.conf. The resulting [server] section should look something like this::
-
-    [server]
-    repository = /var/lib/bcfg2
-    plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,Rules,SSHbase
-
- * Start/restart the bcfg2 server
- * Run the bcfg2 client in order to populate the statistics database (this run should take a bit longer since you are uploading the client statistics to the database).
- * Download the static reports content::
-
-    root@lucid:~# cd /var/www/
-    root@lucid:/var/www# svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/reports
-
- * Configure Apache using [wiki:Reports/Dynamic/Installation#ConfigureApache] as a guide
- * Copy server/statistics sections of bcfg2.conf to /etc/bcfg2-web.conf (make sure it is world-readable). You should then have something like this::
-
-    [server]
-    repository = /var/lib/bcfg2
-    plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,Rules,SSHbase
-
-    [statistics]
-    sendmailpath = /usr/lib/sendmail
-    database_engine = sqlite3
-    # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'.
-    database_name =
-    # Or path to database file if using sqlite3.
-    #<repository>/etc/brpt.sqlite is default path if left empty
-    database_user =
-    # Not used with sqlite3.
-    database_password =
-    # Not used with sqlite3.
-    database_host =
-    # Not used with sqlite3.
-    database_port =
-    # Set to empty string for default. Not used with sqlite3.
-    web_debug = True
-
- * Restart apache and point a browser to your bcfg2 server
+First, run ``aptitude install python-django apache2
+libapache2-mod-python``.
+
+* Now we need to create the sqlite database::
+
+      root@lucid:~# python /usr/share/pyshared/Bcfg2/Server/Reports/manage.py syncdb
+      Creating table auth_permission
+      Creating table auth_group
+      Creating table auth_user
+      Creating table auth_message
+      Creating table django_content_type
+      Creating table django_session
+      Creating table django_site
+      Creating table django_admin_log
+      Creating table reports_client
+      Creating table reports_ping
+      Creating table reports_interaction
+      Creating table reports_reason
+      Creating table reports_entries
+      Creating table reports_entries_interactions
+      Creating table reports_performance
+      Creating table reports_internaldatabaseversion
+
+      You just installed Django's auth system, which means you don't have any superusers defined.
+      Would you like to create one now? (yes/no): no
+      Installing index for auth.Permission model
+      Installing index for auth.Message model
+      Installing index for admin.LogEntry model
+      Installing index for reports.Client model
+      Installing index for reports.Ping model
+      Installing index for reports.Interaction model
+      Installing index for reports.Entries model
+      Installing index for reports.Entries_interactions model
+
+* Add DBStats to the plugins line of bcfg2.conf. The resulting [server]
+  section should look something like this::
+
+      [server]
+      repository = /var/lib/bcfg2
+      plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,Rules,SSHbase
+
+* Start/restart the bcfg2 server
+* Run the bcfg2 client in order to populate the statistics database
+  (this run should take a bit longer since you are uploading the client
+  statistics to the database).
+* Download the static reports content::
+
+      root@lucid:~# cd /var/www/
+      root@lucid:/var/www# svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/reports
+
+* Configure Apache using
+* :ref:`dynamic-http-install` as a guide
+* Copy server/statistics sections of bcfg2.conf to
+  ``/etc/bcfg2-web.conf`` (make sure it is world-readable). You should
+  then have something like this::
+
+      [server]
+      repository = /var/lib/bcfg2
+      plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,Rules,SSHbase
+
+      [statistics]
+      sendmailpath = /usr/lib/sendmail
+      database_engine = sqlite3
+      # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'.
+      database_name =
+      # Or path to database file if using sqlite3.
+      #<repository>/etc/brpt.sqlite is default path if left empty
+      database_user =
+      # Not used with sqlite3.
+      database_password =
+      # Not used with sqlite3.
+      database_host =
+      # Not used with sqlite3.
+      database_port =
+      # Set to empty string for default. Not used with sqlite3.
+      web_debug = True
+
+* Restart apache and point a browser to your bcfg2 server
diff --git a/doc/server/reports/dynamic.txt b/doc/server/reports/dynamic.txt
index a5c748481..b866ba574 100644
--- a/doc/server/reports/dynamic.txt
+++ b/doc/server/reports/dynamic.txt
@@ -9,17 +9,6 @@ Bcfg2 Dynamic Reporting System
 Installation
 ============
 
-Overview
---------
-
-Installation of the new reporting system requires installation of a
-python module and configuration of the Apache webserver with a virtual
-host. Additionally, until fully integrated, periodically an "import
-script" must be executed via Cron or similar mechanism.
-
-Reports no longer needs to be installed at the root URL for a given
-host. Therefore, reports no longer require their own virtual host.
-
 Prerequisites
 -------------
 
@@ -31,30 +20,32 @@ Prerequisites
 Install
 -------
 
-'''setup bcfg2.conf or bcfg2-web.conf'''
-
 Be sure to include the specified fields included the example bcfg2.conf
 file. These can be specified in either ``/etc/bcfg2.conf``, if it is readable
 by the webserver user, or ``/etc/bcfg2-web.conf``.
 
-'''Install skeleton database'''
-
 Inside the ``bcfg2-tarball/examples/`` directory from the
 tarball you will find ``brpt.sqlite``. Copy this file to
-<path-to-bcfg2-repository>/etc/brpt.sqlite
+``<path-to-bcfg2-repository>/etc/brpt.sqlite``.
+
+If you are not using sqlite (the default choice), please see the
+:ref:`alternative-databases` section below.
 
-If you are not using sqlite (the default choice), please see the "Notes
-on Alternative Databases" section below.
+The recommended statistics plugin is DBStats. To use it, add it to the
+``plugins`` line in your bcfg2.conf.
 
-At this point we can import statistics date in to the database from your
-``clients.xml`` and ``statistics.xml`` files.
+Restart the bcfg2 server. Run a client in dryrun mode in order to get
+the client's statistics loaded into the database.
 
-execute the following: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py }}}
+.. _dynamic-http-install:
 
-At this point you shouldn't get any errors or tracebacks. Common problems
-include incorrect installation of the pysqlite2 module.
+Installation of web-based Reports
+---------------------------------
 
-'''Next we configure Apache:'''
+.. note::
+
+    Reports no longer needs to be installed at the root URL for a given
+    host. Therefore, reports no longer require their own virtual host.
 
 An example site config is included below for the vhost "reports.mcs.anl.gov"::
 
@@ -94,16 +85,14 @@ An example site config is included below for the vhost "reports.mcs.anl.gov"::
 
 The first three lines of this configuration must be customized per site.
 
-The {{{bcfg2-tarball/reports/site_media/}}} directory needs to be copied to {{{/var/www/reports/site_media/}}} It could live anywhere; as long as the contents are accessible on the virtual host at {{{/site_media/}}}. 
-
-At this point you should be able to point your web browser to the virtualhost you created '''and see the new reports'''.
-
-One final step is to configure your system to import statistics data regularly. 
-execute the following: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py }}}
+The ``bcfg2-tarball/reports/site_media/`` directory needs to be copied
+to ``/var/www/reports/site_media/`` It could live anywhere; as long as
+the contents are accessible on the virtual host at ``/site_media/``. 
 
-(''Versions 0.8.7 and prior must specify: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py-c <repo>/Metadata/clients.xml -s <repo>/etc/statistics.xml}}} '')
+At this point you should be able to point your web browser to the
+virtualhost you created and see the new reports
 
-on a regular basis, perhaps as often as every 5 or 10 minutes or as infrequent as daily, so your reports are always up to date.
+.. _alternative-databases:
 
 Notes on Alternative Databases
 ------------------------------
@@ -116,9 +105,6 @@ you will need to run "python manage.py syncdb" from the brpt module
 directory to configure it before importing any data. As of vers 0.9.5,
 these settings are moved to the more appropriate /etc/bcfg2.conf
 
-
-''If you encounter any problems or have suggestions for these instructions feedback is welcome and encouraged.''
-
 Summary and Features
 ====================
 
@@ -128,10 +114,19 @@ relational database, we are now able to view and analyze more information
 about the state of the configuration, including information about previous
 configuration. Specific features in the new system include:
 
-* The ability to look at past statistics information. [[Image(summary_cal.jpg, 30%, right)]]
-* More recent data concerning hosts. The import script may be run quite often, updating the database that contains all statistics information. In the future we anticipate development of a database based statistics module for the server that will allow statistics updates to happen immediately as configuration changes happen.
-* Additional information display in reports. Primarily, reasons for configuration item verification failure are now accessible. This additional data is provided only by the most recent client. 
-* Instead of static pages, pages are generated on the fly, allowing users to drill down to find out about a specific host, rather than have one huge page with too much information.
+* The ability to look at past statistics information.
+  [[Image(summary_cal.jpg, 30%, right)]]
+* More recent data concerning hosts. The import script may be run quite
+  often, updating the database that contains all statistics
+  information. In the future we anticipate development of a database
+  based statistics module for the server that will allow statistics
+  updates to happen immediately as configuration changes happen.
+* Additional information display in reports. Primarily, reasons for
+  configuration item verification failure are now accessible. This
+  additional data is provided only by the most recent client.
+* Instead of static pages, pages are generated on the fly, allowing
+  users to drill down to find out about a specific host, rather than
+  have one huge page with too much information.
 
 Planned improvements include
 ============================
diff --git a/doc/unsorted/howtos.txt b/doc/unsorted/howtos.txt
index d8af1d36b..bc9c75970 100644
--- a/doc/unsorted/howtos.txt
+++ b/doc/unsorted/howtos.txt
@@ -11,7 +11,6 @@ Here are several howtos that describe different aspects of Bcfg2 deployment
 * [wiki:Authentication] - a description of the bcfg2 authentication infrastructure
 * AnnotatedExamples - a description of basic bcfg2 specification operations
 * EncapPackages, EncapReadme, EncapInstall, EncapHowto - building encap packages
-* NewDynamicReports - Howto set up new reporting system first released in 0.8.2
 * BuildingDebianPackages - How to build debian packages
 * [wiki:Gentoo] - Issues specific to running bcfg2 on Gentoo
 * [wiki:Plugins/TCheetah TCheetah] - Howto use the TCheetah template plugin