How to configure notifications in Icinga2 Director

I’m using Icinga2 for a long time, but recently installed a new system and using Director for the first time. I know how to configure notifications in Icinga2 config files, but getting them working in Director (with Director options only) is a bit of a challenge.

Here is a step-by-step to get simple mail notifications working. From there it should be easier to configure more advanced notifications.

Start with logging in into Icinga Web.

Time Period(s)

For the next steps we need at least one Time Period. Go to Icinga Director -> Timeperiods -> Timeperiods.

Add a new TimePeriod. To make things easy my first entry contains all weekdays and covers the entire day. Name’s Always.

The Always TimePeriod covers all weekdays:

User Account(s)

Go to Icinga Director -> Users/Contacts -> User Templates.

Add a new template. In my case I named it generic-director-user-template.

Use the Always time period (or select another one if you have multiple time periods defined), and under State and transition type filters select the States and Transition types the user should receive notifications for. In the simplest case just select all options. Don’t forget to enable Send notifications, either in the template or in every single user account based on this template.

Go to Icinga Director -> Users/Contacts -> Users/Contacts.

Add a new user. In Imports use the previously created generic-director-user-template. Also add an email address. You can select different States and Transition types for the user, if nothing is defined then the template settings will be used.

I already defined a couple extra properties (contact details for Telegram and Pushover) in the user templates, they are hidden in Custom properties.

Commands

Before sending emails we need to verify that sending mails is even possible. First of all the host where Icinga2 runs on needs to be able to send mails. That’s usually done by installing a MTA (like Postfix, Exim or such), and the configuration of the MTA is not covered in this blog posting.

Next verify that the scripts mail-host-notification.sh and mail-service-notification.sh are installed. On Debian they are usually installed in /etc/icinga2/scripts/:

-rwxr-xr-x 1 root root 4373 Dez 16  2020 /etc/icinga2/scripts/mail-host-notification.sh
-rwxr-xr-x 1 root root 4758 Dez 16  2020 /etc/icinga2/scripts/mail-service-notification.sh

The scripts are installed by the icinga2-common package. Next verify that these scripts are correctly configured in Director:

Go to Icinga Director -> Commands -> External Commands.

Find the mail-host-notification and the mail-service-notification entries, they should be pre-configured (Director did import them upon the initial setup from Icinga2). Make sure that the “command” entry has the full path to above script:

1
2
3
4
5

object NotificationCommand "mail-host-notification" {
    import "plugin-notification-command"
    command = [ "/etc/icinga2/scripts/mail-host-notification.sh" ]
 ...
}

Notification(s)

Now we have all prerequisites for creating notifications. First another template:

Go to Icinga Director -> Notifications -> Notification Templates.

Create two new templates: host-notification-default-template and service-notification-default-template.

For the host template, make sure that Notification command is mail-host-notification, and under States select the entries for Hosts (Up and Down). Also select the Transition types.

Follow the same procedure for service-notification-default-template, except that the Notification command is mail-service-notification and the States are for Services, not for Hosts (OK, Warning, Critical and Unknown).

Now it’s time to define the actual notifications:

Go to Icinga Director -> Notifications -> Notifications.

Create two new entries: Host Notification and Service Notification.

For the Host Notifications, select host-notification-default-template as Import. Select one or multiple users who shall receive the notifications. Apply to must be Hosts. Finally the notification must be applied to some hosts, that happens in the Assign where section. This section can have very elaborate conditions, in my simple demo I’m just assigning it to all hosts which have notifications enabled. States and Transition types can be selected here, or will be imported from the template.

Important: the host.enable_notifications is a boolean, therefore the condition must be changed to is true or is false:

Defining the Service Notification works similar, except that the Import changes to service-notification-default-template, Apply to changes to Services and the Assignment now covers both host and service notifications.

Deployment

Go to Icinga Director -> Deployments.

And deploy your new config. From here the notifications should work.