You may have recognized that Icinga 2 v2.7 introduced new notification scripts. These came out of the interest we’ve seen in community scripts. So we decided to bring these scripts into Icinga 2 v2.7 making them available for everyone.
The scripts were designed to act as drop-in replacement with old 2.6.x configuration. Unfortunately several environment variables had been renamed. Testers didn’t catch this, so here is a summary for you what to fix and change in your scripts during an upgrade.
Note: These changes will be released in 2.7.1, still this requires your manual interaction beforehand. This advisory is to keep you informed and your notifications safe.
The scripts support both: command line parameters and environment variables. Find all details about changes below.
Environment variables (<= 2.6.x)
These changes were applied to the scripts in v2.7. This requires your notification commands being updated.
mail-host-notification.sh changes:
- HOSTALIAS changed to HOSTDISPLAYNAME
- HOSTNAME is new
mail-service-notification.sh changes:
- SERVICEDESC changed to SERVICENAME
- HOSTALIAS changed to HOSTDISPLAYNAME
- HOSTNAME is new
A complete example has been added as comment into the existing command.conf file. Please adopt that in your (cluster) configuration zones, if existing. More details on this change is documented here.
/*
* If you prefer to use the notification scripts with environment
* variables instead of command line parameters, you can use
* the following commands. They have been updated from < 2.7
* to support the new notification scripts and should help
* with an upgrade.
* Remove the comment blocks and comment the notification commands above.
*/
/*
object NotificationCommand "mail-host-notification" {
command = [ SysconfDir + "/icinga2/scripts/mail-host-notification.sh" ]
env = {
NOTIFICATIONTYPE = "$notification.type$"
HOSTDISPLAYNAME = "$host.display_name$"
HOSTNAME = "$host.name$"
HOSTADDRESS = "$address$"
HOSTSTATE = "$host.state$"
LONGDATETIME = "$icinga.long_date_time$"
HOSTOUTPUT = "$host.output$"
NOTIFICATIONAUTHORNAME = "$notification.author$"
NOTIFICATIONCOMMENT = "$notification.comment$"
HOSTDISPLAYNAME = "$host.display_name$"
USEREMAIL = "$user.email$"
}
}
object NotificationCommand "mail-service-notification" {
command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
env = {
NOTIFICATIONTYPE = "$notification.type$"
SERVICENAME = "$service.name$"
HOSTNAME = "$host.name$"
HOSTDISPLAYNAME = "$host.display_name$"
HOSTADDRESS = "$address$"
SERVICESTATE = "$service.state$"
LONGDATETIME = "$icinga.long_date_time$"
SERVICEOUTPUT = "$service.output$"
NOTIFICATIONAUTHORNAME = "$notification.author$"
NOTIFICATIONCOMMENT = "$notification.comment$"
HOSTDISPLAYNAME = "$host.display_name$"
SERVICEDISPLAYNAME = "$service.display_name$"
USEREMAIL = "$user.email$"
}
}
*/
Parameter support (new in 2.7)
Please use the provided notification objects and notification commands found in /etc/icinga2/conf.d/{command,notification}.conf files. In case you need to change certain parameters, please refer to the updated notification documentation.
The notification apply rules (your own!) don’t need any change, unless you want to add new custom attributes added in v2.7. Â If you made any changes to the command configuration, compare them with the new version before replacing them. Many of you might have put the notification commands into a global zone for config syncs, verify them there.
/* Notification Commands
*
* Please check the documentation for all required and
* optional parameters.
*/
object NotificationCommand "mail-host-notification" {
command = [ SysconfDir + "/icinga2/scripts/mail-host-notification.sh" ]
arguments += {
"-4" = "$notification_address$"
"-6" = "$notification_address6$"
"-b" = "$notification_author$"
"-c" = "$notification_comment$"
"-d" = {
required = true
value = "$notification_date$"
}
"-f" = {
value = "$notification_from$"
description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
}
"-i" = "$notification_icingaweb2url$"
"-l" = {
required = true
value = "$notification_hostname$"
}
"-n" = {
required = true
value = "$notification_hostdisplayname$"
}
"-o" = {
required = true
value = "$notification_hostoutput$"
}
"-r" = {
required = true
value = "$notification_useremail$"
}
"-s" = {
required = true
value = "$notification_hoststate$"
}
"-t" = {
required = true
value = "$notification_type$"
}
"-v" = "$notification_logtosyslog$"
}
vars += {
notification_address = "$address$"
notification_address6 = "$address6$"
notification_author = "$notification.author$"
notification_comment = "$notification.comment$"
notification_type = "$notification.type$"
notification_date = "$icinga.long_date_time$"
notification_hostname = "$host.name$"
notification_hostdisplayname = "$host.display_name$"
notification_hostoutput = "$host.output$"
notification_hoststate = "$host.state$"
notification_useremail = "$user.email$"
}
}
object NotificationCommand "mail-service-notification" {
command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
arguments += {
"-4" = "$notification_address$"
"-6" = "$notification_address6$"
"-b" = "$notification_author$"
"-c" = "$notification_comment$"
"-d" = {
required = true
value = "$notification_date$"
}
"-e" = {
required = true
value = "$notification_servicename$"
}
"-f" = {
value = "$notification_from$"
description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
}
"-i" = "$notification_icingaweb2url$"
"-l" = {
required = true
value = "$notification_hostname$"
}
"-n" = {
required = true
value = "$notification_hostdisplayname$"
}
"-o" = {
required = true
value = "$notification_serviceoutput$"
}
"-r" = {
required = true
value = "$notification_useremail$"
}
"-s" = {
required = true
value = "$notification_servicestate$"
}
"-t" = {
required = true
value = "$notification_type$"
}
"-u" = {
required = true
value = "$notification_servicedisplayname$"
}
"-v" = "$notification_logtosyslog$"
}
vars += {
notification_address = "$address$"
notification_address6 = "$address6$"
notification_author = "$notification.author$"
notification_comment = "$notification.comment$"
notification_type = "$notification.type$"
notification_date = "$icinga.long_date_time$"
notification_hostname = "$host.name$"
notification_hostdisplayname = "$host.display_name$"
notification_servicename = "$service.name$"
notification_serviceoutput = "$service.output$"
notification_servicestate = "$service.state$"
notification_useremail = "$user.email$"
notification_servicedisplayname = "$service.display_name$"
}
}
Hosts without IPv4 address
One of our users told us that he’s been running an IPv6 network, and as such HOSTADDRESS should become optional again. His pull request has been reviewed and will make it into 2.7.1. The notification scripts are located in /etc/icinga2/scripts and therefore you can safely edit them, packages won’t override your changes.
Other suggestions
Christian cleaned the scripts for mobile view, thank you. Michael fixed a problem where an empty $HOSTNAME environment variable could lead into the system’s local name in your notification emails. Thank you all for your kind patches.
Conclusion
Please follow announcement blogposts and Changelogs prior to upgrading a major versions. It may not have been clear enough this time, sorry about that.
We won’t change the scripts again for 2.8.x, so you’re safe to look into git master for the latest and greatest (scripts, commands.conf, notifications.conf).
2.7.1 will be released once we’ve tested patches waiting for a backport. Some of them are resolved in git master waiting for testers, e.g. #5078 and #5513. Chime in and help out if you can, thanks in advance 🙂
