summaryrefslogtreecommitdiffstats
path: root/doc/reports.xml
diff options
context:
space:
mode:
authorNarayan Desai <desai@mcs.anl.gov>2005-09-02 15:24:33 +0000
committerNarayan Desai <desai@mcs.anl.gov>2005-09-02 15:24:33 +0000
commit1901f35837b78788b503b182f73a8d2f59e728fa (patch)
treee325e849cbd6114214fc968aa414ed99e3a6271e /doc/reports.xml
parentb9fcc87d7741e4f33bfa8f66842028ee845b7e33 (diff)
downloadbcfg2-1901f35837b78788b503b182f73a8d2f59e728fa.tar.gz
bcfg2-1901f35837b78788b503b182f73a8d2f59e728fa.tar.bz2
bcfg2-1901f35837b78788b503b182f73a8d2f59e728fa.zip
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
Diffstat (limited to 'doc/reports.xml')
-rw-r--r--doc/reports.xml176
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