From 1901f35837b78788b503b182f73a8d2f59e728fa Mon Sep 17 00:00:00 2001 From: Narayan Desai Date: Fri, 2 Sep 2005 15:24:33 +0000 Subject: 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 --- doc/reports.xml | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) (limited to 'doc') 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 @@ + + The BCFG2 Reporting System + +
+ Quick Start + + Example report config + put this line in cron to run nightly + wait for the mail, check your website + be sure sources are in your web directory. +
+ +
+ Concepts -- Why to report, big picture + + 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. + +
+ +
+ How it all works + + 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. + + + + 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. + + + + 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. + + + + 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. + +
+ +
+ Reports + + + 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. + + + Here is a list of the report types currently defined. + + + + Overview-Stats + + + 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 + + + + + Nodes-Digest + + + 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 + + + + + Nodes-Individual + + + 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. + + + + + + Here is a list of possible delivery mechanisms. + + + + www + + + 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. + + + + + rss + + + 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. + + + + + mail + + + 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. + + + + +
+ +
+ Configuration + + How to setup the config file, how to setup groups of machines + + http://docs.python.org/lib/re-syntax.html + + How to write your own reports +
+ \ No newline at end of file -- cgit v1.2.3-1-g7c22