BCFG2 Reports
Reports play an important role in effectively managing systems
with BCFG. There are two primary functions they fulfill; providing
otherwise unobtainable information, and presenting additional
helpful information to allow for easier admistration. Reports
can contain information including system statistics, discrepancies
between specified and actual configuration, invalid configuration,
and auditing information among other things.
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.
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. Metadata/clients.xml
contains information about if a host is currently pingable or
not. GenerateHostInfo will be run
automatically by StatReports if the
Metadata/clients.xml file is older than
23.5 hours. We chose this interval due to our normal use of
reports; clients run bcfg2, in general, once a day after which
reports are delivered to administrators. It is possible to
execute GenerateHostInfo to update the
Metadata/clients.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
maintainance is required on this file.
Finally StatReports is able to get information
out of the Metadata/groups.xml file as well.
This allows reports to describe the configured profile for each client.
Report Types
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. Tables
describing report types and report delivery mechanisms follow.
Bcfg2 Report Types
Report TypeDescription
Overview-Stats
This report provides information 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 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
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.
Bcfg2 Report Delivery Mechanisms
NameDescription
wwwXHTML file
rssAn RSS file (links do
not point at real web links, since they may not exist)
mailA plaintext email
message
Configuration
The report-configuration.xml file is the
standard file that is used
whenever the StatReports 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:
Run this hourly: StatReports -c WebAndRssReport-config.xml
Run this daily: StatReports -c emailReports-config.xml
The report-configuration.xml
file is structured with a root
]]> tag at the top level. Within this tag any number
of
]]> tags can be inserted. Each report is structured
around a group of machines. ]]> 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:
.
Any number of ]]> 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
Finally, each ]]> contains one or more
]]> 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.
Reporting Quick Start
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 above.
etc/report-configuration.xml
]]>
Once configured correctly, just wait for the e-mail or view the
outputed html files with a web browser. You can run
StatReports by hand if you would like in
order to try it out immediately.
Examples of the performance and overview reports.