.. -*- mode: rst -*- .. _server-reports-dynamic: ============================== Bcfg2 Dynamic Reporting System ============================== Installation ============ Prerequisites ------------- * sqlite3 * pysqlite2 * `Django `_ * mod-python Install ------- Be sure to include the specified fields included 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. Distributed environments can share a single remote database for reporting. Run ``/usr/sbin/bcfg2-admin reports init`` to initialize the database. If you're using sqlite, make sure the webserver can write to the database. 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``. Restart the Bcfg2 server. Run a client in dryrun mode in order to get the client's statistics loaded into the database. .. _dynamic-http-install: Installation of 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":: ServerAdmin webmaster@mcs.anl.gov ServerName reports.mcs.anl.gov DocumentRoot /var/www/reports Order deny,allow Deny from all Allow from localhost #you may want to change this AllowOverride None # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn ServerSignature Off # Stop TRACE/TRACK vulnerability RewriteEngine on RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) RewriteRule .* - [F] SetHandler python-program PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE Bcfg2.Server.Reports.settings PythonDebug On SetHandler None 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" Order deny,allow Allow from all AllowOverride None # 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 past statistics information. [[Image(summary_cal.jpg, 30%, right)]] * More recent data concerning hosts. The import script may be run quite often, updating the database that contains all statistics information. In the future we anticipate development of a database based statistics module for the server that will allow statistics updates to happen immediately as configuration changes happen. * Additional information display in reports. Primarily, reasons for configuration item verification failure are now accessible. This additional data is provided only by the most recent client. * Instead of static pages, pages are generated on the fly, allowing users to drill down to find out about a specific host, rather than have 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 dependancies and makes installation and more difficult. This should become less of a problem over time as Django is packaged and we develop a better installation process for a web app. This should become clear when reading the Installation section that follows. Usage ===== You can use these new reports in tandem with the old system. Currently the new reporting system simply periodically runs an importer script via cron. This imports the XML statistics and clients files to the relational database, building historical information. In the future, a new statistics module in the server will allow direct writing to the database whenever a configuration interaction occurs, which will make the reports always up to date. bcfg2-admin reports (command line script) ----------------------------------------- The bcfg2-admin tool provides management and maintenance capabilities for the reporting database. A few useful `Django `_ 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 =========== [[Image(summary_cal.jpg, 30%)]] [[Image(node_dropdown.jpg, 30%)]] [[Image(item_detail.jpg, 30%)]]