summaryrefslogtreecommitdiffstats
path: root/doc/reports.xml
blob: 23493658e12f030d967dd195f7b66d7441da8f25 (plain)
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>
  <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>
    <title>How it works</title>

    <para>
      The BCFG2 Reporting System consists of a number of elements
      including the <command>StatReports</command> Executable, a
      configuration file, and XSLT transform
      files. <command>StatReports</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>StatReports</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>GenerateHostInfo</command> will be run
      automatically by <command>StatReports</command> if the
      <filename>Metadata/clients.xml</filename> file is out of date
      with pingability information.
    </para>
    
    <para>
      The next place <command>StatReports</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>StatReports</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>
    <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>
      <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>
      <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>
    <title>Configuration</title>
    
    <para>The <filename>report-configuration.xml</filename> file is
      the standard file that the <command>StatReports</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: StatReports -c WebAndRssReport-config.xml
      Run this daily: StatReports -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>
    <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>
  <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>StatReports</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>