README

#*********************************************************#
#                                                         #
#            README for Monitoring UI-Plugin              #
#                                                         #
#*********************************************************#

What is Monitoring UI-Plugin?
=============================

This UI-Plugin for oVirt and RHEV integrates a existing Nagios or Icinga 
monitoring solution into oVirt and RHEV and displays detailed service status
information for data centers, clusters, hosts, storage domains, virtual 
machines and pools including performance graphs.


Contributions / Help
====================

Read documentation in the wiki: https://github.com/monitoring-ui-plugin/development/wiki

Send email to r.koch@ovido.at if you have questions regarding use
of this software. Please include the following information in your email:
* OS type and version
* Browser type and version
* Perl version
* Nagios or Icinga version
* oVirt or RHEV version

To submit patches of suggest improvements, send email to r.koch@ovido.at.


Updating
========

* Version 0.0.1 -> 0.1
Delete the old installation and install new version (see below).

# rm -rf /data/www/ovirt-monitoring
# rm -rf /etc/httpd/conf.d/ovirt-monitoring.conf
# rm -rf /usr/share/ovirt-engine/ui-plugins/monitoring-files
# rm -rf /usr/share/ovirt-engine/ui-plugins/ovirt-monitoring.json


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

0. Make sure that the following requirements are met:
* Perl
* Perl-Modules:
    CGI
    CGI::Carp
    CGI::Fast
    Log::Log4perl
    Template
    YAML::Syck
    File::Spec
    Carp
    JSON::PP
    DBI			# for MySQL and PostgreSQL support
    DBD::Pg     # for IDOutils PostgreSQL support
    # only required for mk-livestatus support:
    Digest::MD5
    Encode
    JSON::XS
    IO::Socket::INET
    IO::Socket::UNIX
    Socket
    Config
    Time::HiRes
    Scalar::Util
* Icinga or Nagios or other clone which supports IDO/NDOUtils or mk-livestatus
* IDO/NDOutils or mk-livestatus added to your monitoring system
* PNP4Nagios (optional)
* oVirt >= 3.2 or RHEV >= 3.2


1. Install required Perl modules (you can skip this if you install the Monitoring
UI-Plugin RPM with yum as dependencies are resolved automatically):

1.1. Basic modules
# yum install perl perl-CGI perl-Log-Log4perl perl-Template-Toolkit perl-JSON perl-YAML-Syck

1.2. For MySQL backend support
# yum install perl-DBI

1.3. For PostgreSQL backend support
# yum install perl-DBD-Pg

1.4. For mk-livestatus backend support
# yum install perl-JSON-XS 

1.5. For FastCGI support
# yum install mod_fcgid


2. Install Icinga/Nagios (if not already available)
See Icinga documentation: http://docs.icinga.org/latest/en/
See Nagios documentation: http://nagios.sourceforge.net/docs/nagioscore/3/en/toc.html


3. Define Hosts and Services (if not already done)
As described in Nagios and/or Icinga documentation


4. Make monitoring results accessible via one of the following providers:

4.1. mk-livestatus for Icinga/Nagios
See mk-livestatus documentation: http://mathias-kettner.de/checkmk_livestatus.html

4.2. NDOUtils for Nagios
See http://nagios.sourceforge.net/docs/ndoutils/NDOUtils.pdf

4.3. IDOUtils for Icinga
See http://docs.icinga.org/1.9/en/quickstart-idoutils.html


5. Install Monitoring UI-Plugin
Build RPM from Spec-File or from Sources:

5.1. RPM Build
# rpmbuild -ba monitoring-ui-plugin.spec
# yum localinstall monitoring-ui-plugin*.rpm

5.2. Install from Sources
$ tar xfzv monitoring-ui-plugin-*.tar.gz
$ cd monitoring-ui-plugin-*
$ ./configure
$ make
# make install

6. Configure Monitoring UI-Plugin
The configurations files are located (unless changed in ./configure call):
* /etc/monitoring-ui-plugin (when installed from RPM)
* /usr/local/monitoring-ui-plugin/etc (when installed from sources)

The main configuration file is monitoring-ui.yml and is well documented.
Have a look at this file.

For a quickstart:
- check that data_dir, lib_dir and site_url are set correct / detected
correct from the configure script.
- set the url to pnp4nagios if you want graphs
- configure the provider


7. Configure your webserver
The configuration depends on how you installed oVirt/RHEV.

If oVirt/RHEV 3.2 is listening on ports 80/443 you have to exclude monitoring-ui
url from ProxyPass.
To do this edit /etc/httpd/conf.d/ovirt-engine.conf

  ProxyPass /monitoring-ui !
  ProxyPass / ajp://localhost:8702/ retry=5 timeout=3600

If oVirt/RHEV 3.2 is listening on other ports you properly have to start httpd as
it's most likely not running and change url in monitoring-ui.json to point to port
80/443 of your webserver:
Edit /usr/share/ovirt-engine/ui-plugins/monitoring-ui.json

 "url": "https://engine.example.com:443/monitoring-ui/cgi/monitoring-ui.cgi",

For oVirt 3.3 no ProxyPass excludes are required anymore.

Make sure monitoring-ui.conf matches the paths you configured in monitoring-ui.yml!


Documentation
=============

Short documentation on how to use this plugin.

Detailed documentation can be found on the project website
https://github.com/ovido/monitoring-ui-plugin/wiki

Log into oVirt Webadmin Portal and select a data center, cluster, host 
storage domain, virtual machine or pool.
A new subtab labeled "Monitoring Details" appears. In this new subtab 
you can see all service checks for this item with service output and 
status information.

On the right side detailed information and performance graphs (if PNP4nagios
is installed) are provided.