$OpenBSD: README,v 1.4 2018/09/04 12:46:17 espie Exp $

+-----------------------------------------------------------------------
| Running icinga-web2 on OpenBSD
+-----------------------------------------------------------------------

Web User Interface
==================

The main Icinga 2 program should be configured first. Several features
are required for use with Icinga Web 2: either an "ido" database module
or "livestatus", and also "command". Consult Icinga documentation
about using "icinga2 feature enable" to do this, for configuration
details, database schema, etc.

The majority of Icinga Web 2 configuration is web-based and simple,
but a few things will need to be setup FIRST, in particular to cope
with the use of a chroot jail for OpenBSD webservers and PHP.

- OpenBSD's PHP packages use the Suhosin extension. Add the following
to /etc/php-7.0.ini:

   suhosin.executor.include.whitelist = zend.view

This is needed otherwise Suhosin will block "zend.view://" pseudo-URLs
from being used with PHP's "include" function.

- To cope with the chroot jail normally used with OpenBSD's PHP/web
servers, create a symlink:

   # mkdir -p /var/www/var
   # ln -s .. /var/www/var/www
   # ls -l /var/www/var/www
   lrwxr-xr-x  1 root  daemon  2 Feb  2 01:01 /var/www/var/www -> ..

(Icinga-web2 has CLI scripts which are run outside the chroot jail,
and PHP webpages which are run inside the jail; this allows paths like
"/var/www/icinga-web2" to work in both cases).

- If using PostgreSQL, install php-pgsql and php-pdo_pgsql.

- If using php-fpm, configure it to run scripts as the _icingaweb2
user, and set the /tmp directory. You may add this to /etc/php-fpm.conf:

   [icingaweb2]
   user = _icingaweb2
   group = _icingaweb2
   listen = /var/www/run/php-fpm-icingaweb2.sock
   listen.owner = www
   listen.group = www
   listen.mode = 0660
   pm = dynamic
   pm.max_children = 20
   pm.start_servers = 4
   pm.min_spare_servers = 2
   pm.max_spare_servers = 5
   chroot = /var/www
   env[TMP] = /icinga-web2/tmp
   env[TMPDIR] = /icinga-web2/tmp

(If instead of php-fpm you use Apache with mod_php, you will need to
add the userid running PHP scripts to the _icingaweb2 group).

- Configure your webserver to pass requests to icingaweb2's front
controller. An example for nginx (remember to "rcctl reload nginx"
after adding), using the above php-fpm section:

   location ~ ^/icingaweb2/index\.php(.*)$ {
       fastcgi_pass   unix:run/php-fpm-icingaweb2.sock;
       fastcgi_index index.php;
       include fastcgi_params;
       fastcgi_param SCRIPT_FILENAME /icinga-web2/public/index.php;
       fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
       fastcgi_param REMOTE_USER $remote_user;
   }

   location ~ ^/icingaweb2(.+)? {
       alias /var/www/icinga-web2/public;
       index index.php;
       try_files $1 $uri $uri/ /icingaweb2/index.php$is_args$args;
   }

Using icingacli, create the config directory and a token to allow setup:

   # /var/www/icinga-web2/bin/icingacli setup config directory --group _icingaweb2
   # /var/www/icinga-web2/bin/icingacli setup token create

Open the web interface http://localhost/icingaweb2/. Paste in the token
that was displayed on-screen in the above step and proceed to the web-based
part of the configuration.
