$OpenBSD: README-main,v 1.32 2018/09/04 12:53:16 espie Exp $

+-----------------------------------------------------------------------
| Running icinga 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:

   # su -m _icinga -c "/usr/local/bin/icinga -v /etc/icinga/icinga.cfg"

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

Use the rcctl command to enable automatic startup on boot for icinga

   # rcctl enable icinga

To start icinga, reboot or start it manually:

   # rcctl start icinga


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. You should also clear
the cache by running "/var/www/icinga-web/bin/clearcache.sh".

The 1.11.0 update enables CSRF protection for cmd.cgi by default;
if using external programs (like Nagstamon or aNag) to access the classic
UI, you may need to set disable_cmd_cgi_csrf_protection=1 in cgi.cfg.


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

If you're using OpenBSD's default chroot environment for httpd or nginx
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 /var/www/etc/
   ln -s /var/www/etc/icinga /etc
   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

To display times in your local timezone, you will also need to provide
a suitable /var/www/etc/localtime; due to the chroot, a symbolic link cannot
be used here, instead the file can be copied:

   cp /usr/share/zoneinfo/Antarctica/South_Pole /var/www/etc/localtime

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

Two web-based user interfaces are available for Icinga. They are provided
in their own packages; one or both must be installed separately ("pkg_add
icinga-cgi" or "pkg_add icinga-web").

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

   httpd and nginx don't support CGI scripts directly; instead the slowcgi(8)
   wrapper must be used. Use the rcctl command to enable it at startup and
   reboot or start it manually:

      # rcctl enable slowcgi
      # rcctl start slowcgi

   For nginx, add a configuration section like this to /etc/nginx/nginx.conf:

   location /icinga/ {
	alias		/icinga-cgi/;
	satisfy		any;
	allow		127.0.0.1/32;
	allow		::1/128;
	auth_basic	"Icinga Access";
	auth_basic_user_file /etc/icinga/htpasswd.users;
   }
   location /cgi-bin/icinga/ {
	satisfy		any;
	allow		127.0.0.1/32;
	allow		::1/128;
	root		/;
	auth_basic	"Icinga Access";
	auth_basic_user_file /etc/icinga/htpasswd.users;
	try_files	$uri =404;
	fastcgi_pass	unix:run/slowcgi.sock;
	fastcgi_param	REMOTE_USER $remote_user;
	include		fastcgi_params;
   }

   The example above permits access from the local machine without password,
   and requires HTTP basic authentication from other locations.

   For httpd, add a configuration section like this to /etc/httpd.conf:

      location "/cgi-bin/icinga/*cgi" {
              fastcgi
              root "/"
              authenticate with "/etc/icinga/htpasswd.users"
      }

   And create a symbolic link in the htdocs directory:

      # ln -s ../icinga-cgi icinga

   The examples above require HTTP basic authentication. The password file can
   be created as follows:

      # htpasswd /etc/icinga/htpasswd.users <username>

   When done, reload the web server:

      # rcctl reload nginx

      or

      # rcctl reload httpd

   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 "ido2db" to the pkg_scripts line
   in /etc/rc.conf.local _before_ icinga.

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

      # rcctl start ido2db

   2.3) Enable the "broker_module=/usr/local/lib/idomod.so ..." line in
   /etc/icinga/icinga.cfg and restart icinga:

      # rcctl restart icinga

   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) Enable icinga-web for your web server. If using Apache, an
   httpd.conf snippet is provided and can be enabled as follows:

      # ln -s ../modules.sample/icinga-web.conf /var/www/conf/modules

   2.7) Currently, icinga-web is not tested to work in a web server chroot
   environment. You may have success by symlinking /var/www/var/www to
   /var/www (mkdir -p /var/www/var && ln -s ../.. /var/www/var/www).
   This topic will be revisited in a future version of this package.

   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 by adding the following to /etc/rc.conf.local:

	icinga_flags=-d /etc/nagios/nagios.cfg

You will need to merge the settings between Nagios' and Icinga's cgi.cfg
files. sdiff(1) 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.
