summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoey Hagedorn <hagedorn@mcs.anl.gov>2005-09-15 05:51:48 +0000
committerJoey Hagedorn <hagedorn@mcs.anl.gov>2005-09-15 05:51:48 +0000
commit816b1b06ef34c4167197f3574b97c69e78942242 (patch)
treedbd04416d7118b5dcd65e250767790910fd5a1da
parent0735907eeb12cf7168f9efc9e914b6d29ed48a2e (diff)
downloadbcfg2-816b1b06ef34c4167197f3574b97c69e78942242.tar.gz
bcfg2-816b1b06ef34c4167197f3574b97c69e78942242.tar.bz2
bcfg2-816b1b06ef34c4167197f3574b97c69e78942242.zip
Lots of new docs, quickstart is done
(Logical change 1.314) git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@1280 ce84e21b-d406-0410-9b95-82705330c041
-rw-r--r--doc/reports.xml137
1 files changed, 104 insertions, 33 deletions
diff --git a/doc/reports.xml b/doc/reports.xml
index 6b1e47926..9f9a46516 100644
--- a/doc/reports.xml
+++ b/doc/reports.xml
@@ -2,21 +2,51 @@
<title>The BCFG2 Reporting System</title>
<section>
- <title>Quick Start</title>
+ <title>Reporting Quick Start</title>
+
+ <example>
+ <title><filename>report-configuration.xml</filename></title>
+ <programlisting><![CDATA[<Reports>
+ <Report name='core_stats' good='Y' modified='Y'>
+ <Delivery mechanism='mail' type='nodes-digest'>
+ <Destination address='user@domain.tld'/>
+ <Destination address='user@otherdomain.tld'/>
+ </Delivery>
+ <Delivery mechanism='www' type='nodes-digest'>
+ <Destination address='/var/www/core_stats.html'/>
+ </Delivery>
+ <Machine name='.*'/>
+ </Report>
+
+ <Report name='stats_for_a_machines' good='N' modified='Y'>
+ <Delivery mechanism='mail' type='nodes-digest'>
+ <Destination address='user@domain.tld'/>
+ </Delivery>
+ <Delivery mechanism='mail' type='overview-stats'>
+ <Destination address='user@otherdomain.tld'/>
+ </Delivery>
+ <Machine name='a.*'/>
+ <Machine name='x-aim'/>
+ </Report>
+ </Reports>]]>
+ </programlisting>
+ </example>
+
+ <para>This configuration will generate two separate reports and deliver
+ them a number of different ways. For more information on exactly what
+ each section does, please refer to the Configuration section below</para>
- <para>Example report config:</para>
- <para>Example Report Configuration Here</para>
<para>In order to run reports, you need to run the following command
- regularly via <command>Cron</command>:
- <command>GenerateHostInfo</command></para>
+ regularly via <command>Cron</command>:
+ <command>GenerateHostInfo</command></para>
<para>Once configured correctly, just wait for the e-mail or check
- look at the output html files with a web browser. You can run
- <command>GenerateHostInfo</command> by hand if you would like
- in order to try it out immediately. If you are trying to view a
- HTML file and find that it doesn't work as expected, make sure
- that the required source directory is in the same directory. They
- are static, but might need to be moved from /(prefix)/share/bcfg2/
- in to the directory from which you are viewing your reports.</para>
+ look at the output html files with a web browser. You can run
+ <command>GenerateHostInfo</command> by hand if you would like
+ in order to try it out immediately. If you are trying to view a
+ HTML file and find that it doesn't work as expected, make sure
+ that the required source directory is in the same directory. They
+ are static, but might need to be moved from <![CDATA[prefix]]>/share/bcfg2/
+ in to the directory from which you are viewing your reports.</para>
</section>
<section>
@@ -34,49 +64,59 @@
<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
+ elements. The core is the <command>StatReports</command>
+ Executable. <command>StatReports</command> 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
+ run by the adminstrator periodically via <command>cron</command>
+ 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
+ <command>StatReports</command> gets the data it reports from a number of
+ sources. The <filename>hostinfo.xml</filename>
+ file is specific to the reporting system
+ and generated by the executable python script <command>GenerateHostInfo
+ </command>.
+ <filename>Hostinfo.xml</filename> 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
+ FQDNs. <command>GenerateHostInfo</command> will be run automatically
+ by <command>StatReports</command> if the <filename>hostinfo.xml</filename>
+ 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
+ previous night. It is possible to execute
+ <command>GenerateHostInfo</command> to update the
+ <filename>hostinfo.xml</filename> 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
+ The next place <command>StatReports</command> gets data from is the
+ <filename>statistics.xml</filename>
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
+ Finally <command>StatReports</command> is able to get any information
+ out of the <filename>metadata.xml</filename> 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 Types</title>
+ <title>Report Types</title>
<para>
There are a number of report types, and a number of delivery
@@ -141,10 +181,10 @@
<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
+ <![CDATA[<prefix>]]>/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.
+ view the WWW files.
</para>
</listitem>
</varlistentry>
@@ -153,10 +193,10 @@
<listitem>
<para>
This delivery type also should be written to some area
- that is likely web accessable. It is plain Rss-- One
+ 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.
+ corresponding web page exists for any given RSS article.
</para>
</listitem>
</varlistentry>
@@ -176,10 +216,41 @@
<section>
<title>Configuration</title>
- <para>How to setup the config file, how to setup groups of machines</para>
+ <para>The <filename>report-configuration.xml</filename> file is the
+ standard file that is used
+ whenever the <command>StatReports</command> executable is run without any
+ command line arguments. Alternate configuration files, formatted
+ identically, can be used instead with the -c flag. This can be useful
+ for running different types of reports at different intervals. For
+ example:</para>
+ <programlisting>
+ Run this hourly: StatReports -c WebAndRssReport-config.xml
+ Run this daily: StatReports -c emailReports-config.xml
+ </programlisting>
+
+ <para>The <filename>report-configuration.xml</filename>
+ file is structured with a root
+ <![CDATA[<Reports/>]]> tag at the top level. Within this tag any number
+ of
+ <![CDATA[<Report/>]]> tags can be inserted. Each report is structured
+ around a group of machines. <![CDATA[<Machine/>]]> tags may individually
+ reference a machine by hostname (not FQDN), or also by a Python Regular
+ Expression. More information can be found about such Regexes at:
+ http://docs.python.org/lib/re-syntax.html.</para>
+
+ <para>Any number of <![CDATA[<Delivery/>]]> elements can be made for a
+ given
+ report. A delivery consists of a mechanism and a type.
+ The mechanism would be
+ something like Mail or Web, and they type would reference the content
+ of the report. Some are tailored to overall machine health, while
+ others could be best fit for auditing purposes</para>
- <para>http://docs.python.org/lib/re-syntax.html</para>
+ <para>Finally, each <![CDATA[<Delivery/>]]> contains one or more
+ <![CDATA[<Destination/>]]> tags. In the
+ case of an RSS or WWW report, the destination should be a complete path
+ to the output file. In e-mail based reports the destination should be
+ a complete e-mail address.</para>
- <para>Writing Custom Reports</para>
</section>
</chapter> \ No newline at end of file