it now builds

2005/09/02 10:05:36-05:00 anl.gov!desai
Rename: doc/reports.txt -> doc/reports.xml

(Logical change 1.294)


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

1 files changed, 176 insertions, 0 deletions

diff --git a/doc/reports.xml b/doc/reports.xml
index e69de29bb..61739528e 100644
--- a/doc/reports.xml
+++ b/doc/reports.xml
@@ -0,0 +1,176 @@
+<chapter>
+  <title>The BCFG2 Reporting System</title>
+
+  <section>
+    <title>Quick Start</title>
+
+  <para>Example report config</para>
+  <para>put this line in cron to run nightly</para>
+  <para>wait for the mail, check your website </para>
+  <para>be sure sources are in your web directory.</para>
+</section>
+
+  <section>
+    <title>Concepts -- Why to report, big picture</title>
+
+    <para>So you'll recive a report-- however you might get it--and
+      it'll contain any sort of info, like general net health, or specific
+      node broken packages, or... whatever. You choose. This will help you
+      correct your configuratin file, and audit things, and fix any nodes
+      that got all hosed.
+    </para>
+  </section>
+
+  <section>
+    <title>How it all works</title>
+
+    <para>The BCFG2 Reporting System consists of a number of
+      elements. The core is the StatReports Executable. StatReports reads
+      a default configuration file (or a config file specified on the
+      command line) then prepares and delivers the reports specified in
+      the configuration file. It is expected that this executable will be
+      run by the adminstrator periodically via CRON or similar
+      facilty. The executable can also be run manually on demand for a
+      special sort of report that needs to be generated immediately.
+    </para>
+    
+    <para>
+      StatReports gets the data it reports from a number of
+      sources. The hostinfo.xml file is specific to the reporting system
+      and generated by the executable python script "GenerateHostInfo." 
+      Hostinfo.xml contains information about if a host is currently
+      pingable or not, and a mapping of short hostnames to
+      FQDNs. GenerateHostInfo will be run automatically by StatReports if
+      the hostinfo.xml file is older than 23.5 hours. This number is
+      chosen, because it is likely an administrator will recieve reports
+      daily about the status of hosts and if they had run BCFG the
+      previous night. It is possible to execute GenerateHostInfo to update
+      the hostinfo.xml file at any interval via cron, but it does take
+      some time to complete, so be sure to give it a few minutes. This
+      will only likely be of use if your BCFG clients are set to update
+      more often than nightly and you would like reports after each run.
+    </para>
+    
+    <para>
+      The next place StatReports gets data from is the statistics.xml
+      file. This file is maintained by bcfgd, and is updated whenever a
+      client updates, therefore is always up to date, and no
+      maintainence is required on this file.
+    </para>
+    
+    <para>
+      Finally StatReports is able to get any information out of the
+      Metadata.xml file. This will likely be most useful in the future
+      where the range of reports will include auditing style reports,
+      that must include configuration information.
+    </para>	
+  </section>
+
+  <section>
+    <title>Reports</title>
+    
+    <para>
+      There are a number of report types, and a number of delivery
+      styles. It is expected that reports be laid out around a group
+      of machines. For any group of machines it can be defined that
+      there be any number of reports generated, with different
+      options. For each of those reports, each can be delivered by
+      Mail, WWW, or via RSS (or any combination of the three.) In the
+      future, additional report types will be added, and if necessary,
+      additional types of deliveries will be created.
+    </para>
+
+    <para>Here is a list of the report types currently defined.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>Overview-Stats</term>
+	<listitem>
+	  <para>
+	    This report provides informatoin about a large number of
+	    machines and their states. It is often found to be useful
+	    when the group of machines it is connected with is simply
+	    All Nodes, which gives an overall outlook on your
+	    network's health. It makes sense to get this report via
+	    any mechanism
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Nodes-Digest</term>
+	<listitem>
+	  <para>
+	    This is a report that includes details about each node,
+	    specifically what packages, files, etc are broken, and
+	    other node specific info. It makes sense to recieve this
+	    via any mechanism
+	    </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>Nodes-Individual</term>
+	<listitem>
+	  <para>
+	    This report includes details about each node, but
+	    information is separated in to separate sections (such as
+	    separate e-mails or RSS articles) before sending. This
+	    works well with e-mail filters and error
+	    detection. Currently WWW is not a supported delivery
+	    mechanism for this type of report, because it is not
+	    completely clear how such a report could be used.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Here is a list of possible delivery mechanisms.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>www</term>
+	<listitem>
+	  <para>
+	    This delivery produces HTML reports which can be delivered
+	    via the WWW. it is important that you copy the directory:
+	    install-root/share/bcfg2/reports/web-rprt-srcs in to the
+	    same directory as you will be serving web pages from. It
+	    includes CSS and JavaScript files necessary to properly
+	    view the www files.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>rss</term>
+	<listitem>
+	  <para>
+	    This delivery type also should be written to some area
+	    that is likely web accessable. It is plain Rss-- One
+	    Caveat-- the "Article Link" does not actually point to any
+	    web information, because it is not clear that a
+	    corresponding web page exists for any given rss article.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>mail</term>
+	<listitem>
+	  <para>
+	    Mail is simple plaintext e-mail that is sent to the
+	    specified recipients directly from the machine on which
+	    BCFG is running by opening a pipe to sendmail.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section>
+    <title>Configuration</title>
+    
+    <para>How to setup the config file, how to setup groups of machines</para>
+
+    <para>http://docs.python.org/lib/re-syntax.html</para>
+
+    <para>How to write your own reports</para>
+  </section>
+</chapter>
\ No newline at end of file