diff options
author | Narayan Desai <desai@mcs.anl.gov> | 2008-01-16 16:21:17 +0000 |
---|---|---|
committer | Narayan Desai <desai@mcs.anl.gov> | 2008-01-16 16:21:17 +0000 |
commit | 377f83a1e9a60d4938f56ad4ac271ae7cb9f44c6 (patch) | |
tree | 93fe4f0af2fa3f32d0f8c0734c76c434d6a5e8c5 /doc/reports.xml | |
parent | edc64aa3053503d4da9476034ba0495e80e49e47 (diff) | |
download | bcfg2-377f83a1e9a60d4938f56ad4ac271ae7cb9f44c6.tar.gz bcfg2-377f83a1e9a60d4938f56ad4ac271ae7cb9f44c6.tar.bz2 bcfg2-377f83a1e9a60d4938f56ad4ac271ae7cb9f44c6.zip |
remove stale documentation
git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@4247 ce84e21b-d406-0410-9b95-82705330c041
Diffstat (limited to 'doc/reports.xml')
-rw-r--r-- | doc/reports.xml | 246 |
1 files changed, 0 insertions, 246 deletions
diff --git a/doc/reports.xml b/doc/reports.xml deleted file mode 100644 index 1587c88d4..000000000 --- a/doc/reports.xml +++ /dev/null @@ -1,246 +0,0 @@ -<chapter id='chap:reports'> - <title>BCFG2 Reports</title> - - <para> - Reports play an important role in effectively managing systems - with BCFG. There are two primary functions they fulfill; providing - otherwise unobtainable information, and presenting common - information in a compact, effective format that allows for easier - admistration. Reports can contain system statistics, discrepancies - between specified and actual configuration, invalid configuration - notices, and auditing information, among other things. </para> - - <para> - The flexible XML configuration file allows reports to be configured - to deliver only the information that is important. Additional reports - can easily be created, providing site-specific capability to manage - at record effiency. The capability to harvest information regarding - statistics, configuration, and problems in a single location should - prove to be powerful. - </para> - - <section id='sec:reports-how'> - <title>How it works</title> - - <para> - The BCFG2 Reporting System consists of a number of elements - including the <command>bcfg2-build-reports</command> Executable, a - configuration file, and XSLT transform - files. <command>bcfg2-build-reports</command> reads a default - configuration file (or a config file specified on the command - line) then prepares and delivers the reports according to the - format defined in the transform files. It is expected that this - executable will be run by the adminstrator periodically via - <command>cron</command> or similar facility. The executable can - also be run manually on demand for a special sort of report that - needs to be generated immediately. </para> - - <para> - <command>bcfg2-build-reports</command> gets the data it reports from a - number of sources. <filename>Metadata/clients.xml</filename> - contains information about if a host is currently pingable or - not. <command>bcfg2-ping-sweep</command> will be run - automatically by <command>bcfg2-build-reports</command> if the - <filename>Metadata/clients.xml</filename> file is out of date - with pingability information. - </para> - - <para> - The next place <command>bcfg2-build-reports</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 maintainance is required - on this file. Most of the information in the predefined reports - come from this file. - </para> - - <para> - Finally <command>bcfg2-build-reports</command> is able to pull information - from the <filename>Metadata/groups.xml</filename> file as well. - This allows reports to describe the configured profile for each client. - </para> - </section> - - <section id='sec:report-types'> - <title>Report Types</title> - - <para> - There are a number of report types and delivery styles to - present and transmit the reported data. The reporting structure - lends itself best to structuring reports around groups of - machines. For any group of machines any number of reports are - generated. Each report may be delivered via Mail, WWW, or 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. It is easy to create your own - custom report using XSLT. Tables describing report types and - report delivery mechanisms follow: </para> - - <table id='table:report-types'> - <title>Bcfg2 Report Types</title> - <tgroup cols='2'> - <colspec colnum='1' colwidth='1*'/> - <colspec colnum='2' colwidth='4*'/> - <thead> - <row><entry>Report Type</entry><entry>Description</entry></row> - </thead> - <tbody> - <row><entry>Overview-Stats</entry> - <entry> - <para> - This report provides information about a large number - of machines and their states. It is often found to be - useful when the constituent machines are simply - specified as All Nodes, which gives an overall outlook - on your network's health. It makes sense to get this - report via any mechanism. - </para> - </entry></row> - <row><entry>Nodes-Digest</entry> - <entry> - <para> - This report 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> - </entry></row> - <row><entry>Nodes-Individual</entry> - <entry> - <para> - This report includes details about each node, but - information is separated in to separate sections (such - as separate e-mails or RSS articles) for delivery. - This works well with e-mail (using filters on the - client side) and for error detection (getting e-mail - when there is a problem. 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> - </entry></row> - </tbody> - </tgroup> - </table> - - <table id='table:report-delivery'> - <title>Bcfg2 Report Delivery Mechanisms</title> - <tgroup cols='2'> - <colspec colnum='1' colwidth='1*'/> - <colspec colnum='2' colwidth='3*'/> - <thead> - <row><entry>Name</entry><entry>Description</entry></row> - </thead> - <tbody> - <row><entry>www</entry><entry>an XHTML file</entry></row> - <row><entry>rss</entry><entry>an RSS file <comment>(links do - not point at real web links, since they may not exist)</comment></entry></row> - <row><entry>mail</entry><entry>A plaintext e-mail - message</entry></row> - </tbody> - </tgroup> - </table> - - </section> - - <section id='sec:reports-configuration'> - <title>Configuration</title> - - <para>The <filename>report-configuration.xml</filename> file is - the standard file that the <command>bcfg2-build-reports</command> - executable uses when it is run without any command line - arguments. Alternate configuration files, formatted identically, - can be used by specifing -c flag. This can be useful for - running different types of reports at different intervals. For - example:</para> - - <programlisting> - Run this hourly: bcfg2-build-reports -c WebAndRssReport-config.xml - Run this daily: bcfg2-build-reports -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, or by a Python Regular - Expression describing a group of hostnames. ".*" is especially helpful - to describe all hosts. More information can be found about such Regexes - at: <ulink url="http://docs.python.org/lib/re-syntax.html"/>.</para> - - <para>Any number of <![CDATA[<Delivery/>]]> elements can be - defined for a given report. A delivery consists of a mechanism - and type. The mechanism would be something like Mail or Web, - and the type would describe the intended content of the - report. Some are tailored to overall machine health, while - others could be best fit for auditing purposes</para> - - <para>Finally, each <![CDATA[<Delivery/>]]> element contains one - or more <![CDATA[<Destination/>]]> elements. In the case of an - RSS or WWW report, the destination should be a complete path to - the output file including the file's name. In e-mail based - reports the destination should be a valid e-mail address.</para> - - </section> - - <section id='sec:reports-quick-start'> - <title>Reporting Quick Start</title> - - <para> - The following configuration will generate two separate reports - and deliver them in a number of different ways. For more - information on exactly what each section does, please refer to - the Configuration section above. </para> - - <example id='ex:report-config'> - <title>etc/report-configuration.xml</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> - Once configured correctly, just wait for the e-mail or view the - outputed html files with a web browser. - <command>bcfg2-build-reports</command> to recieve your reports - immediately, or configure cron to run it perodically. E-mail - reports will deliver the appropriate content directly to your - mail client, and the html files should be viewable with any web - browser. It is suggested those files be accessable via a - webserver for convenience to other interested parties. - - </para> - - <mediaobject> - <imageobject> - <imagedata fileref='./images/composed.tif'/> - </imageobject> - - <caption> - <para>Examples of the performance and overview reports.</para> - </caption> - </mediaobject> - </section> -</chapter> |