summaryrefslogtreecommitdiffstats
path: root/doc/reports/dynamic.txt
blob: 1ec41af64ccfa74b4aac56a8b7a1e0028c28be58 (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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
.. -*- mode: rst -*-

.. _server-reports-dynamic:

==============================
Bcfg2 Dynamic Reporting System
==============================

.. versionadded:: 0.8.2

Installation
============

Prerequisites
-------------

* sqlite3
* pysqlite2
* `Django <http://www.djangoproject.com>`_
* mod-python

Install
-------

Be sure to include the specified fields included in the example
``bcfg2.conf`` file. These can be specified in either ``/etc/bcfg2.conf``,
if it is readable by the webserver user, or ``/etc/bcfg2-web.conf``. Any
database supported by Django can be used. If you are not using sqlite
(the default choice), please see the :ref:`alternative-databases`
section below.

.. note::

    Distributed environments can share a single remote database for
    reporting.

The recommended statistics plugin is DBStats. To use it, add it to the
**plugins** line in your ``bcfg2.conf``.  Alternatively, the Statistics
plugin can be used in conjunction with a crontab entry to run
``/usr/sbin/bcfg2-admin reports load_stats``.

Detailed installation instructions can be found :ref:`here <server-reports-install>`.

.. _dynamic-http-install:

Apache configuration for web-based reports
------------------------------------------

.. note::

    Reports no longer needs to be installed at the root URL for a given
    host. Therefore, reports no longer require their own virtual host.

    In order to make this work, you will need to specify your web prefix
    by adding a **web_prefix** setting in the [statistics] section of
    your ``bcfg2.conf``.

An example site config is included below for the vhost "reports.mcs.anl.gov"::

    <VirtualHost reports.mcs.anl.gov>
            ServerAdmin webmaster@mcs.anl.gov
            ServerName reports.mcs.anl.gov
            DocumentRoot /var/www/reports
            <Directory /var/www/reports>
                    Order deny,allow
                    Deny from all
                    Allow from localhost #you may want to change this
                    AllowOverride None
            </Directory>

            # Possible values include: debug, info, notice, warn, error, crit,
            # alert, emerg.
            LogLevel warn

            ServerSignature Off

            # Stop TRACE/TRACK vulnerability
            <IfModule mod_rewrite.c>
                    RewriteEngine on
                    RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK)
                    RewriteRule .* - [F]
            </IfModule>
    <Location "/">
            SetHandler python-program
            PythonHandler django.core.handlers.modpython
            SetEnv DJANGO_SETTINGS_MODULE Bcfg2.Server.Reports.settings
            PythonDebug On
    </Location>
    <Location "/site_media/">
            SetHandler None
    </Location>
    </VirtualHost>

The first three lines of this configuration must be customized per site.

The ``bcfg2-tarball/reports/site_media/`` directory needs to be copied
to ``/var/www/reports/site_media/`` It could live anywhere; as long as
the contents are accessible on the virtual host at ``/site_media/``.

At this point you should be able to point your web browser to the
virtualhost you created and see the new reports

Example WSGI configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^

entry.wsgi::

    import os, sys
    os.environ['DJANGO_SETTINGS_MODULE'] = 'Bcfg2.Server.Reports.settings'
    import django.core.handlers.wsgi
    application = django.core.handlers.wsgi.WSGIHandler()

Apache conf::

    Alias /bcfg2reports/site_media "/path/to/site_media"
    <Directory /path/to>
        Order deny,allow
        Allow from all
        AllowOverride None
    </Directory>
    # If Python is installed in a non-standard prefix:
    #WSGIPythonHome /python/prefix
    #WSGIPythonPath /python/prefix/lib/python2.6/site-packages
    WSGIScriptAlias /bcfg2reports "/another/path/to/entry.wsgi"

.. _alternative-databases:

Notes on Alternative Databases
------------------------------

If you choose to use a different database, you'll need to edit
``/etc/bcfg2.conf``. These fields should be updated in the [statistics]
section:

* database_engine

  * ex: database_engine = mysql
  * ex: database_engine = postgresql_psycopg2

* database_name
* database_user
* database_password
* database_host
* database_port (optional)

Summary and Features
====================

The new reporting system was implemented to address a number of
deficiencies in the previous system. By storing statistics data in a
relational database, we are now able to view and analyze more information
about the state of the configuration, including information about previous
configuration. Specific features in the new system include:

* The ability to look at a :ref:`reports-calendar-summary` with past
  statistics information.
* More recent data concerning hosts.
* Additional information display in reports. Primarily, reasons for
  :ref:`configuration item verification failure <reports-item-detail>`
  are now accessible.
* Instead of static pages, pages are generated on the fly, allowing
  users to drill down to find out about a :ref:`specific host
  <reports-node-dropdown>`, rather than only having one huge page with
  too much information.

Planned improvements include
============================

* Accounts, customized displays for each admin. And privacy of config data.
* Config browsing capabilities; to look at your config in an interesting way.
* Fixing all the known bugs from below.

Unfortunately with all the improvements, there are a few less exciting
elements about the new reporting system. The new reporting system
moves away from static pages and towards a real web application, which
causes mainly problems with dependencies and makes installation more
difficult. This should become less of a problem over time as we develop
a better installation process for a web application.

Usage
=====

bcfg2-admin reports (command line script)
-----------------------------------------

The bcfg2-admin tool provides management and maintenance capabilities for
the reporting database.  A few useful `Django <http://www.djangoproject.com>`_
commands are provided as well.

* init: Initialize a new database
* load_stats: Load statistics data from the Statistics plugin into the
  database. This was importscript.py.
* scrub: Scrub the database for duplicate reasons.
* update: Apply any updates to the reporting database. Unlike the syncdb
  command, this will modify existing tables.

Django commands
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* syncdb:  Create the tables for any models not installed.  Django will
  not modify any existing tables.
* sqlall:  Print the sql statements used to create the database.  Note:
  This does not show the fixture data.
* validate:  Validate the database against the current models.

bcfg2-reports (command line script)
-----------------------------------

bcfg2-reports allows you to retrieve data from the database about clients,
and the states of their current interactions. It also allows you to
change the expired/unexpired states.

The utility runs as a standalone application. It does, however, use the
models from ``/src/lib/Server/Reports/reports/models.py``.

A number of different options can be used to change what bcfg2-reports
displays::

    Usage: python bcfg2-reports [option] ...

    Options and arguments (and corresponding environment variables):
    -a                     : shows all hosts, including expired hosts
    -b NAME                : single-host mode - shows bad entries from the
                             current interaction of NAME
    -c                     : shows only clean hosts
    -d                     : shows only dirty hosts
    -e NAME                : single-host mode - shows extra entries from the
                             current interaction of NAME
    -h                     : shows help and usage info about bcfg2-reports
    -s NAME                : single-host mode - shows bad and extra entries from
                             the current interaction of NAME
    -x NAME                : toggles expired/unexpired state of NAME
    --badentry=KIND,NAME   : shows only hosts whose current interaction has bad
                             entries in of KIND kind and NAME name; if a single
                             argument ARG1 is given, then KIND,NAME pairs will be
                             read from a file of name ARG1
    --extraentry=KIND,NAME : shows only hosts whose current interaction has extra
                             entries in of KIND kind and NAME name; if a single
                             argument ARG1 is given, then KIND,NAME pairs will be
                             read from a file of name ARG1
    --fields=ARG1,ARG2,... : only displays the fields ARG1,ARG2,...
                             (name,time,state)
    --sort=ARG1,ARG2,...   : sorts output on ARG1,ARG2,... (name,time,state)
    --stale                : shows hosts which haven't run in the last 24 hours

Screenshots
===========

.. _reports-calendar-summary:

Calendar Summary
----------------

.. image:: summary_cal.jpg
   :alt: Calendar summary

.. _reports-item-detail:

Item detail
-----------

.. image:: item_detail.jpg
   :alt: Item detail

Node dropdown
-------------

.. _reports-node-dropdown:

.. image:: node_dropdown.jpg
   :alt: Node dropdown