$OpenBSD: README-main,v 1.11 2012/10/18 20:04:58 sthen Exp $

+-----------------------------------------------------------------------
| Running icinga-1.8.4 on OpenBSD
+-----------------------------------------------------------------------

Getting Started
===============

The main documentation for Icinga is provided in HTML format as part of
the icinga-cgi package, see /var/www/icinga-cgi/docs/en/index.html
or at http://docs.icinga.org/latest/en/. 

The included sample configuration carries out some simple checks
on the local machine; these should work as-is.

You may check your configuration file format before starting Icinga:

   $ sudo -u _icinga /usr/local/bin/icinga -v /etc/icinga/icinga.cfg

This will parse all configuration files and warn about any problems
which have been identified.

To enable automatic startup on boot for icinga, add it to pkg_scripts
in /etc/rc.conf.local, for example:

   pkg_scripts="${pkg_scripts} icinga"

To start icinga, reboot or start it manually:

   $ sudo /etc/rc.d/icinga start


Upgrading from a previous version
=================================

If you are using IDODB, you will need to update the database schema.
Typically you will just need to apply updates from
/usr/local/share/examples/icinga/db/<yourrdbms>/upgrade/, but
see /var/www/icinga-cgi/docs/en/upgrading_idoutils.html or
http://docs.icinga.org/latest/en/upgrading_idoutils.html for more
information.

If upgrading from IDODB 1.6.1 or earlier, update your broker_module
setting in /etc/icinga/icinga.cfg; the plugin was renamed from
/usr/local/bin/idomod.o to /usr/local/lib/idomod.so in 1.7.0.

If upgrading from an earlier version of icinga-web (the PHP API-based
web interface), you will need to apply updates to the icinga_web database
schema from /var/www/icinga-web/etc/schema/updates.


Chroot Considerations
=====================

If you're using OpenBSD's default chroot environment for httpd with
the icinga-cgi package, some files will need to be moved inside the
jail and symbolic links created.

   mkdir -p /var/www/etc /var/www/var/log
   mv /etc/icinga/icinga /var/www/etc/
   ln -s /var/www/etc/icinga /etc/icinga
   mv /var/icinga /var/www/var/
   ln -s /var/www/var/icinga /var
   mv /var/log/icinga /var/www/var/log/
   ln -s /var/www/var/log/icinga /var/log


Web User-Interfaces
===================

Two web-based user interfaces are available for Icinga:

1) icinga-cgi: the classic (but improved) Nagios-style interface

   To enable icinga-cgi, link the provided httpd.conf snippet:

      $ sudo ln -s /var/www/conf/modules.sample/icinga-cgi.conf \
         /var/www/conf/modules

   You may wish to modify this file.  By default it uses HTTP basic
   authentication; you can create the password file as follows:

      $ sudo touch /etc/icinga/htpasswd.users
      $ sudo htpasswd /etc/icinga/htpasswd.users <username>

   When done, restart the web server:

      $ sudo /rc.d/httpd restart

   You should then be able to access the web interface at
   http://localhost/icinga/


2) icinga-web: new API-based interface

   2.1) Setup the icinga database. For details see:
   /usr/local/share/examples/icinga/db/README

   2.2) Enable the ido2db daemon. Add it to the pkg_scripts line
   in /etc/rc.conf.local before icinga, for example:

      pkg_scripts="${pkg_scripts} ido2db icinga"

   Afterwards, you can start it by rebooting, or manually:

      $ sudo /etc/rc.d/ido2db start

   2.3) Enable the broker_module idomod.so in /etc/icinga/icinga.cfg
   and restart icinga:

      $ sudo /etc/rc.d/icinga restart

   Now you should see in the icinga logfile, that icinga is storing
   information in the db.

   2.4) Setup the icinga_web database (change the password!):

      mysql -u root -p <<EOF
      CREATE DATABASE icinga_web;
      GRANT USAGE ON *.* TO 'icinga_web'@'localhost'
         IDENTIFIED BY 'icinga_web_password';
      GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX
         ON icinga_web.* TO 'icinga_web'@'localhost';
      FLUSH PRIVILEGES;
      \u icinga_web
      \. /var/www/icinga-web/etc/schema/mysql.sql
      EOF

   2.5) Change the db settings accordingly for both icinga and for
   icinga_web in /var/www/icinga-web/etc/conf.d/databases.xml.

   2.6) To enable icinga-web, link the provided httpd.conf snippet:

      $ sudo ln -s /var/www/conf/modules.sample/icinga-web.conf \
         /var/www/conf/modules

   2.7) Currently, icinga-web is not tested to work with the httpd
   chroot environment. So before you start httpd, ensure that you've
   added "-u" to httpd_flags in /etc/rc.d/httpd.

      $ sudo /etc/rc.d/httpd start

   You should then be able to access the web interface at

      http://localhost/icinga-web/

   using user 'root' and 'password' as password. Change the default
   password in the preferences as soon as possible!.

   If you want to use the classic interface from within icinga-web
   you have to install the icinga-cgi package. The reporting component
   of icinga-web depends on external software which is not installed
   by default.


Moving from Nagios
==================

The configuration format is compatible with Nagios.  If you'd like
to move across with minimal changes, you can point Icinga at your
existing configuration files:

	echo 'icinga_flags="-d /etc/nagios/nagios.cfg"' >> /etc/rc.conf.local
	echo 'pkg_scripts="${pkg_scripts} icinga' >> /etc/rc.conf.local

You will need to merge the settings between Nagios' and Icinga's
cgi.cfg files.  sdiff(1), as used by sysmerge(8), can help with this.
main_config_file and some other settings (admin usernames etc) should
be taken from the Nagios file, whereas the various web-related settings
(url_html_path, physical_html_path, etc) need to point to the Icinga files.
