diff options
author | Narayan Desai <desai@mcs.anl.gov> | 2005-09-02 15:24:33 +0000 |
---|---|---|
committer | Narayan Desai <desai@mcs.anl.gov> | 2005-09-02 15:24:33 +0000 |
commit | 1901f35837b78788b503b182f73a8d2f59e728fa (patch) | |
tree | e325e849cbd6114214fc968aa414ed99e3a6271e /doc/reports.xml | |
parent | b9fcc87d7741e4f33bfa8f66842028ee845b7e33 (diff) | |
download | bcfg2-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.xml | 176 |
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 |