These notes are a bit rough because they have been copied more-or-less directly from my old wiki that was just for my own consumption. They are from when I finally set-up icinga at home. Note that the configuration has moved on substantially since these notes were written, however as it is in a git repository I have not made any more notes or blog posts about it, to date.

Installation

Debian

Install the required packages (on master and clients):

apt-get install icinga2 monitoring-plugins

On the master, install the web-frontend packages (assuming I have already set-up a postgres database server):

apt-get install icingaweb2 icinga2-ido-pgsql icingacli

Setup

Web

Enable the ido-pgsql feature (the Debian package will have already set-up the user, icinga’s configuration and run the initial database creation script):

icinga2 feature enable ido-pgsql

Enable the API:

icinga2 api setup

Add a web user to the api user configuration (below the existing root one) in /etc/icinga2/conf.d/api-users.conf:

object ApiUser "icingaweb2" {
  password = "<some api password>"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}

Restart icinga2:

systemctl restart icinga2

Setup NGINX and php5-fpm, then add configuration for icinga:

location ~ ^/icinga/(.*)? {
  auth_basic "Icinga";
  auth_basic_user_file /etc/icingaweb2/htpasswd;
  alias /usr/share/icingaweb2/public;
  index index.php;
  #rewrite ^/$ /dashboard;
  try_files $1 $uri $uri/ /icinga/index.php$is_args$args;
  location ~ ^/icinga/index\.php(.*)$ {
    fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
    fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
    fastcgi_param REMOTE_USER $remote_user;
  }
}

Ensure that required php modules are available:

apt-get install php-pgsql php-curl

Create /etc/icingaweb2/htpasswd using htpasswd (or similar).

Configure icingaweb2

Find the icinga2 db password from /etc/icinga2/features-enabled/ido-pgsql.conf.

Create /etc/icingaweb2/resources.ini:

[icinga2-db]
type = "db"
db = "pgsql"
username = "icinga2"
password = "<some password>"
dbname = "icinga2"
host = "/var/run/postgresql"

…and /etc/icingaweb2/config.ini:

[logging]
log = "syslog"
level = "ERROR"
application = "icingaweb2"
 
[global]
config_backend = "ini"
/etc/icingaweb2/authentication.ini
[autologin]
backend = "external"
/etc/icingaweb2/roles.ini
[admins]
users = "icingaadmin"
permissions = "*"

Setup monitoring plug-in

Enable the monitoring plug-in:

icingacli module list | grep -q ^monitoring || icingacli module enable monitoring

Configure it:

/etc/icingaweb2/modules/monitoring/config.ini:

[security]
protected_customvars = "*pw*,*pass*,community"

/etc/icingaweb2/modules/monitoring/backends.ini:

[icinga2-db]
type = "ido"
resource = "icinga2-db"

/etc/icingaweb2/modules/monitoring/commandtransports.ini:

[icinga2]
transport = "api"
host = "127.0.0.1"
port = "5665"
username = "icingaweb2"
password = "<api password>"

Master

Certificates

First thing we need is some ssl certificates. I had problems using the proper OpenSSL way of generating a certificate, via an intermediary CA beneath my trusted root. I therefore resorted to using icinga’s tools.

Master

On the master create a new CA - the ca certificate and key will be in /var/lib/icinga2/ca/ca.{crt,key}:

icinga2 pki new-ca

Then create a host certificate for the local host (certificate and key will be in the current directory):

icinga2 pki new-cert --cn ds9.home.entek.org.uk --key ds9.home.entek.org.uk.key --csr ds9.home.entek.org.uk.csr

Finally, generate the signed certificate:

icinga2 pki sign-csr --csr ds9.home.entek.org.uk.csr --cert ds9.home.entek.org.uk.crt

The ca certificate needs copying to /etc/icinga2/pki/ca.crt.

The host certificate and key need to go in /etc/icinga2/pki/<hostname>.{crt,key}.

Clients

Generate a sign a host certificate per the above.

The ca certificate also gets copied to /etc/icinga2/pki/ca.crt.

The host certificate and key go in /etc/icinga2/pki/<hostname>.{crt,key}.

Zones configuration

Create the zones configuration file, /etc/icinga2/zones.conf:

# This node endpoint
object Endpoint "master.localdomain" {
  host = "master.localdomain"
}

object Zone "master" {
  endpoints = [ "master.localdomain" ]
}

object Endpoint "server1.localdomain" {
  host = "server1.localdomain" // the master will actively try to connect to the client
}

object Zone "server1.localdomain" {
  endpoints = [ "server1.localdomain" ]
  parent = "master"
}

object Endpoint "server2.localdomain" {
  host = "server2.localdomain" // the master will actively try to connect to the client
}

object Zone "server2.localdomain" {
  endpoints = [ "server2.localdomain" ]
  parent = "master"
}

/* sync global commands */
object Zone "global-templates" {
  global = true
}

Create the required directories for the master:

mkdir /etc/icinga2/zones.d/global-templates /etc/icinga2/zones.d/master

Copy the default configuration from /etc/icinga/conf.d to the right place:

cp /etc/icinga2/conf.d/* /etc/icinga2/zones.d/global-templates/
mv /etc/icinga2/zones.d/global-templates/hosts.conf /etc/icinga2/zones.d/master/
rm /etc/icinga2/zones.d/global-templates/satellite.conf

Notifications

Send to real person

By default Icinga2 sends notifications to root@localhost. To change this, add a new user to the users.conf file (I also added a new group for users who receive notification):

object User "laurence" {
  import "generic-user"

  display_name = "<my full name>"
  groups = [ "notifyusers" ]

  email = "<my email address>"
}

object UserGroup "notifyusers" {
  display_name = "Users who receive alerts"
}

Then in each hosts.conf change the mail notification group from ‘icingaadmins’ to ‘notifyusers’, or delete vars.notification[“mail”] from all the hosts.conf and add it to the “generic-host” template in templates.conf instead (since they’re all identical):

/* Define notification mail attributes for notification apply rules in `notifications.conf`. */
vars.notification["mail"] = {
  /* The UserGroup `notifyusers` is defined in `users.conf`. */
  groups = [ "notifyusers" ]
}

Reduce frequency

By default Icinga2 will send notifications once every 30 minutes. 1 notification per outage is enough for me. To change this, simply add interval = 0 to the notification settings in notifications.conf:

apply Notification "mail-notifications" to Host {
  import "mail-host-notification"

  interval = 0

  user_groups = host.vars.notification.mail.groups
  users = host.vars.notification.mail.users

  assign where host.vars.notification.mail
}

apply Notification "mail-notifications" to Service {
  import "mail-service-notification"

  interval = 0

  user_groups = host.vars.notification.mail.groups
  users = host.vars.notification.mail.users

  assign where host.vars.notification.mail
}