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
|
<chapter>
<title>The BCFG2 Reporting System</title>
<section>
<title>Quick Start</title>
<para>Example report config</para>
<para>put this line in cron to run nightly</para>
<para>wait for the mail, check your website </para>
<para>be sure sources are in your web directory.</para>
</section>
<section>
<title>Concepts -- Why to report, big picture</title>
<para>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.
</para>
</section>
<section>
<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
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.
</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
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.
</para>
<para>
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.
</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
where the range of reports will include auditing style reports,
that must include configuration information.
</para>
</section>
<section>
<title>Reports</title>
<para>
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.
</para>
<para>Here is a list of the report types currently defined.</para>
<variablelist>
<varlistentry>
<term>Overview-Stats</term>
<listitem>
<para>
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
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Nodes-Digest</term>
<listitem>
<para>
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
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Nodes-Individual</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Here is a list of possible delivery mechanisms.</para>
<variablelist>
<varlistentry>
<term>www</term>
<listitem>
<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
same directory as you will be serving web pages from. It
includes CSS and JavaScript files necessary to properly
view the www files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>rss</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>mail</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Configuration</title>
<para>How to setup the config file, how to setup groups of machines</para>
<para>http://docs.python.org/lib/re-syntax.html</para>
<para>How to write your own reports</para>
</section>
</chapter>
|
