| 1 | == Overview == |
| 2 | |
| 3 | Installation of the new reporting system requires installation of a python module and configuration of the Apache webserver with a virtual host. Additionally, until fully integrated, periodically an "import script" must be executed via Cron or similar mechanism. |
| 4 | |
| 5 | Versions 0.9.5pre1 and greater no longer need to be installed at the root url for a given host, and therefore no longer require their own virtual host. |
| 6 | |
| 7 | == Prerequisites == |
| 8 | |
| 9 | * sqlite3 |
| 10 | * pysqlite2 |
| 11 | * [http://www.djangoproject.com Django] 0.96.x |
| 12 | * mod-python |
| 13 | |
| 14 | == Install == |
| 15 | '''setup bcfg2.conf or bcfg2-web.conf''' |
| 16 | |
| 17 | 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. This changed in 0.9.5. |
| 18 | |
| 19 | |
| 20 | '''Install skeleton database''' |
| 21 | |
| 22 | Inside the {{{bcfg2-tarball/examples/}}} directory from the tarball you will find {{{brpt.sqlite}}}. Copy this file to <path-to-bcfg2-repository>/etc/brpt.sqlite |
| 23 | |
| 24 | If you are not using sqlite (the default choice), please see the "Notes on Alternative Databases" section below. |
| 25 | |
| 26 | At this point we can import statistics date in to the database from your {{{clients.xml}}} and {{{statistics.xml}}} files. |
| 27 | |
| 28 | execute the following: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py }}} |
| 29 | |
| 30 | (''Versions 0.8.7 and prior must specify: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py-c <repo>/Metadata/clients.xml -s <repo>/etc/statistics.xml}}} '') |
| 31 | |
| 32 | It might be a good idea to write a 1-line shell script to execute this very long command; it is only an interim measure until the {{{/etc/statistics.xml}}} file is obsoleted. |
| 33 | |
| 34 | At this point you shouldn't get any errors or tracebacks. Common problems include incorrect installation of the pysqlite2 module. |
| 35 | |
| 36 | '''Next we configure Apache:''' |
| 37 | |
| 38 | An example site config is included below for the vhost "reports.mcs.anl.gov": |
| 39 | {{{ |
| 40 | <VirtualHost reports.mcs.anl.gov> |
| 41 | ServerAdmin [email protected] |
| 42 | ServerName reports.mcs.anl.gov |
| 43 | DocumentRoot /var/www/reports |
| 44 | <Directory /var/www/reports> |
| 45 | Order deny,allow |
| 46 | Deny from all |
| 47 | Allow from localhost #you may want to change this |
| 48 | AllowOverride None |
| 49 | </Directory> |
| 50 | |
| 51 | # Possible values include: debug, info, notice, warn, error, crit, |
| 52 | # alert, emerg. |
| 53 | LogLevel warn |
| 54 | |
| 55 | ServerSignature Off |
| 56 | |
| 57 | # Stop TRACE/TRACK vulnerability |
| 58 | <IfModule mod_rewrite.c> |
| 59 | RewriteEngine on |
| 60 | RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) |
| 61 | RewriteRule .* - [F] |
| 62 | </IfModule> |
| 63 | <Location "/"> |
| 64 | SetHandler python-program |
| 65 | PythonHandler django.core.handlers.modpython |
| 66 | SetEnv DJANGO_SETTINGS_MODULE Bcfg2.Server.Reports.settings |
| 67 | PythonDebug On |
| 68 | </Location> |
| 69 | <Location "/site_media/"> |
| 70 | SetHandler None |
| 71 | </Location> |
| 72 | </VirtualHost> |
| 73 | }}} |
| 74 | |
| 75 | The first three lines of this configuration must be customized per site. |
| 76 | |
| 77 | 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/}}}. |
| 78 | |
| 79 | At this point you should be able to point your web browser to the virtualhost you created '''and see the new reports'''. |
| 80 | |
| 81 | One final step is to configure your system to import statistics data regularly. |
| 82 | execute the following: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py }}} |
| 83 | |
| 84 | (''Versions 0.8.7 and prior must specify: {{{python .../site-packages/Bcfg2/Server/Reports/importscript.py-c <repo>/Metadata/clients.xml -s <repo>/etc/statistics.xml}}} '') |
| 85 | |
| 86 | on a regular basis, perhaps as often as every 5 or 10 minutes or as infrequent as daily, so your reports are always up to date. |
| 87 | |
| 88 | == Notes on Alternative Databases == |
| 89 | If you choose to use a different database, you'll need to edit settings.py from inside of the brpt module. Instructions on this process can be found on the Django website. The provided sqlite database file is pre-populated with the appropriate tables, if you choose a different database engine, you will need to run "python manage.py syncdb" from the brpt module directory to configure it before importing any data. As of vers 0.9.5, these settings are moved to the more appropriate /etc/bcfg2.conf |
| 90 | |
| 91 | |
| 92 | ''If you encounter any problems or have suggestions for these instructions feedback is welcome and encouraged.'' |