1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<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>
|
