------------------------------
        OpenPOM how-to 
------------------------------

  Copyright 2010, Exosec
  Licensed under GPL Version 2.
  http://www.gnu.org/licenses/


1) Requirements
---------------

Either:
  - Nagios (http://nagios.org/) installation with a contact_name admin 
  - Icinga (http://www.icinga.org/)

- MySQL 
- NdoUtils  (NDOUtils : http://www.nagios.org/download/addons)
- A web server (Apache/Apache2) with php5


2) Configure NdoUtils
---------------------

After NdoUtils install don't forget to add the broker in nagios or icinga conf.

event_broker_options=-1
broker_module=/usr/lib/ndoutils/ndomod-mysql-3x.o config_file=/etc/nagios3/ndomod.cfg

Grant access to your Ndo MySQL base (assume name is ndoutils)

mysql> grant select on ndoutils.* to 'openpom'@'127.0.0.1' identified by 'my_password';
mysql> flush privileges;

For performance reason you have to set up index on some ndoutils tables.
Connect to your mysql server and use the correct database then inject these lines :
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `comment_source` );
ALTER TABLE `nagios_hosts` ADD INDEX ( `display_name` );
ALTER TABLE `nagios_hosts` ADD INDEX ( `address` );
ALTER TABLE `nagios_services` ADD INDEX ( `display_name` );
ALTER TABLE `nagios_notifications` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_notifications` ADD INDEX ( `start_time` );
ALTER TABLE `nagios_notifications` ADD INDEX ( `end_time` );
ALTER TABLE `nagios_downtimehistory` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_downtimehistory` ADD INDEX ( `scheduled_end_time` );
ALTER TABLE `nagios_downtimehistory` ADD INDEX ( `entry_time` );
ALTER TABLE `nagios_acknowledgements` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_acknowledgements` ADD INDEX ( `entry_time` );
ALTER TABLE `nagios_statehistory` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_statehistory` ADD INDEX ( `state_time` );
ALTER TABLE `nagios_contactnotifications` ADD INDEX ( `notification_id` );
ALTER TABLE `nagios_contactnotifications` ADD INDEX ( `contact_object_id` );
ALTER TABLE `nagios_flappinghistory` ADD INDEX ( `event_time` );
ALTER TABLE `nagios_flappinghistory` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_scheduleddowntime` ADD INDEX ( `object_id` );

ALTER TABLE `nagios_commenthistory` ADD INDEX ( `object_id` );
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `entry_time` );
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `author_name` );
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `deletion_time` );
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `entry_type` );
ALTER TABLE `nagios_commenthistory` ADD INDEX ( `comment_data` );
ALTER TABLE `nagios_contactgroup_members` ADD INDEX ( `contactgroup_id` );
ALTER TABLE `nagios_contactgroups` ADD INDEX ( `contactgroup_object_id` );
ALTER TABLE `nagios_contacts` ADD INDEX ( `contact_object_id` );
ALTER TABLE `nagios_downtimehistory` ADD INDEX ( `actual_end_time` );
ALTER TABLE `nagios_host_contactgroups` ADD INDEX ( `host_id` );
ALTER TABLE `nagios_hostgroup_members` ADD INDEX ( `hostgroup_id` );
ALTER TABLE `nagios_hostgroup_members` ADD INDEX ( `host_object_id` );
ALTER TABLE `nagios_hostgroups` ADD INDEX ( `hostgroup_object_id` );
ALTER TABLE `nagios_objects` ADD INDEX ( `objecttype_id` );
ALTER TABLE `nagios_objects` ADD INDEX ( `name1` );
ALTER TABLE `nagios_scheduleddowntime` ADD INDEX ( `downtime_type` );
ALTER TABLE `nagios_service_contactgroups` ADD INDEX ( `service_id` );
ALTER TABLE `nagios_service_contactgroups` ADD INDEX ( `contactgroup_object_id` );
ALTER TABLE `nagios_services` ADD INDEX ( `host_object_id` );



3) Configure OpenPom
--------------------

Adjust the following variables in config.php:

/* SQL */
$SQL_HOST           = "127.0.0.1";
$SQL_USER           = "openpom";
$SQL_PASSWD         = "my_password";
$SQL_DB             = "ndoutils";

/* NAGIOS OR ICINGA VARIABLES */
$EXEC_CMD           = "./send-order";
$CMD_FILE           = "/usr/local/nagios/var/rw/nagios.cmd";
$LINK               = "/" . $BACKEND . "/cgi-bin/extinfo.cgi";
$LOG                = "/" . $BACKEND . "/cgi-bin/showlog.cgi";

!!! Check that you have the right to write in the nagios or icinga cmd file !!!
chown :www-data /usr/local/nagios/var/rw/nagios.cmd
chmod g+w /usr/local/nagios/var/rw/nagios.cmd
or with sudo add this to your sudoers :
www-data  ALL=(ALL) NOPASSWD: PATH/send-order

Configure the queue in send-order script : MAX_EXTCMD=10 (default) it allow to send 10 external commands to nagios max before a sleep of 5 seconds


4) Configure Apache2
--------------------

4.1) Apache global authentification
-----------------------------------

  Alias       /openpom    /var/www/openpom
  <Directory /var/www/openpom>
     Options ExecCGI Indexes
     AllowOverride None
     Order allow,deny
     Allow from all

     AuthName "OpenPom Access"
     AuthType Basic
     AuthUserFile  /etc/nagios/http-passwd
     AuthGroupFile /etc/nagios/http-group
     Require groupe nagios
     Satisfy Any

     SetEnv REMOTE_USER root
  </Directory>

!!! The REMOTE_USER user name must match a contact_name in nagios or icinga contact.cfg !!!

4.2) Apache local authentification
-----------------------------------

  Alias       /openpom            /var/www/openpom
  <Directory /var/www/openpom>
     Options ExecCGI Indexes
     AllowOverride None
     Order allow,deny
     Allow from all

     AuthName "OpenPom Access"
     AuthType Basic
     AuthUserFile  /etc/nagios/http-passwd
     Require valid-user
  </Directory>


Add your user:password with htpasswd in /etc/nagios/http-passwd

!!! The user name must match a contact_name in nagios or icinga contact.cfg !!!


5) Graph
--------

You can show graph from external sources (like rrdgraph, pnp, cacti, ...)
Edit config.php and add the following two arrays:

/**
 * SHOW GRPAH FROM EXTERNAL SOURCE
 *  
 * Default images are generated by Nagios' trends.cgi 
 * Image at URI defined in $GRAPH_HOST will be displayed for hosts
 * Image at URI defined in $GRAPH_SVC will be displayed for services
 * 
 * Keywords:
 * @@define_host@@ will be replaced by the selected host name
 * @@define_service@@ will be replaced by the selected service name
 */
$GRAPH_HOST = '/' . $BACKEND . '/cgi-bin/trends.cgi' 
  . '?createimage'
  . '&backtrack=4'
  . '&zoom=4'
  . '&host=@@define_host@@';

$GRAPH_SVC = '/' . $BACKEND . '/cgi-bin/trends.cgi'
  . '?createimage'
  . '&backtrack=4'
  . '&zoom=4'
  . '&host=@@define_host@@'
  . '&service=@@define_service@@';

/* POPUP CONTENT WHEN CLICKING ON THE GRAPH ICON
 * 
 * Default is to use the graph.php provided with OpenPOM which display the
 * image defined in $GRAPH_HOST or $GRAPH_SVC (respectively for an host or
 * a service) and a very basic period selector.
 *  
 * Periods available are defined in the array $GRAPH_POPUP_PERIODS where each
 * element is an array of 2 elements defining the start and end value of the
 * period. The start/end values must be valid string for passing to PHP's  
 * strtotime() function.
 * 
 * See PHP documentation for more information:
 * http://www.php.net/manual/en/datetime.formats.php
 * 
 * The start/end timestamps are passed to the URI defined in $GRAPH_HOST and
 * $GRAPH_SVC. The name of the parameters used to pass them are defined 
 * repectively in $GRAPH_POPUP_PARAM_START and $GRAPH_POPUP_PARAM_END. 
 */
$GRAPH_POPUP_HOST = 'graph.php?host=@@define_host@@';
$GRAPH_POPUP_SVC = 'graph.php?host=@@define_host@@&service=@@define_service@@';
$GRAPH_POPUP_WIDTH = 800;
$GRAPH_POPUP_HEIGHT = 400;

$GRAPH_POPUP_PERIODS = array(
  'Day'   => array('-1 day',    'now'), 
  'Week'  => array('-1 week',   'now'), 
  'Month' => array('-1 month',  'now'), 
  'Year'  => array('-1 year',   'now'));

$GRAPH_POPUP_DEFAULT = 'Week';
$GRAPH_POPUP_PARAM_START = 't1';
$GRAPH_POPUP_PARAM_END = 't2';


6) Note
-------

Supported Navigators :
  - Firefox >= 3.X
  - IE > 6
  - Opera >= 10
  - Chrome

Advanced filtering :
search by column h:host_name s:service_name i:ip_address o:output g:group_name
operators : 
 ! negation
 * wildcard
 & and
 | or

7) Contributors
---------------

Sylvain Choisnard  - schoisnard@exosec.fr
Benoit  Dolez      - bdolez@exosec.fr
Thierry Fournier   - tfournier@exosec.fr
Bertrand Jacquin   - bjacquin@exosec.fr
Alexandre Bray     - abray@exosec.fr
Julien Thomas      - jthomas@exosec.fr

