Skip to content

Upgrading Icinga Notifications

Some Icinga Notifications upgrades require manual intervention, others do not. If you need to intervene, the release notes will point you to the specific upgrade section on this page.

Please note that version upgrades are incremental. If you are upgrading across multiple versions, make sure to follow the steps for each of them.

Database Schema Upgrades

Certain Icinga Notifications version upgrades require a database schema upgrade. If the upgrade section of the specific Icinga Notifications release mentions a schema upgrade, this section will guide you through the process of applying the schema upgrade.

First, stop the Icinga Notifications daemon.

systemctl stop icinga-notifications

Locate the required schema upgrade files in /usr/share/icinga-notifications/schema/mysql/upgrades/ for MySQL/MariaDB or in /usr/share/icinga-notifications/schema/pgsql/upgrades/ for PostgreSQL. The schema upgrade files are named after the new Icinga Notifications release and are mentioned in the specific section below. If you have skipped multiple Icinga Notifications releases, apply all schema versions in their order, starting with the earliest release.

The following commands would apply a sample version 0.1.2 schema upgrade to the notifications database as the notifications user. Please modify them for your setup and the schema upgrade you want to apply.

Important

For PostgreSQL, the schema upgrade must be applied by the notifications PostgreSQL user, since this user owns the current tables and would own any new table created by the schema upgrade. If you are unsure whether your PostgreSQL user is named notifications, as stated in the installation section, you can list the Owner for each table in the notifications database via \d in psql.

$ psql -U postgres notifications -c '\d'
                        List of relations
 Schema |               Name               |   Type   |    Owner
--------+----------------------------------+----------+--------------
 public | available_channel_type           | table    | notifications
 public | browser_session                  | table    | notifications
 public | channel                          | table    | notifications
[ . . . ]

This shortened output shows that notfications is the Owner and needs to be set as -U notifications in the following upgrade command.

  • MySQL/MariaDB: 
    mysql -u notifications -p notifications < /usr/share/icinga-notifications/schema/mysql/upgrades/0.1.2.sql
  • PostgreSQL: 
    psql -v ON_ERROR_STOP=1 -U notifications notifications < /usr/share/icinga-notifications/schema/pgsql/upgrades/0.1.2.sql

Afterwards, restart Icinga Notifications.

systemctl start icinga-notifications

Upgrading to Icinga Notifications v1.0.0

This Icinga Notifications release is the first stable release. Since the 0.2.0 preview, event rules are evaluated by Icinga Notifications again, the HTTP API is versioned, and the configuration was restructured. Thus, some manual changes are necessary, as described below.

Requirements

Version 1.0.0 of Icinga Notifications is released alongside - Icinga Notifications Web 1.0.0, - Icinga DB 1.6.0, - Icinga DB Web 1.5.0, and - Icinga 2 2.16.6.

If you are using Icinga DB as an Icinga Notifications source, start with upgrading Icinga DB and following its upgrading documentation. Same goes for Icinga DB Web and its upgrading documentation.

For MySQL, at least version 8.0 is now required. The requirements for MariaDB and PostgreSQL remain unchanged.

Ensure that the new requirements are met before updating Icinga Notifications.

Schema

The upgrade script 1.0.0.sql must be applied as described in the schema upgrade section.

Configuration Changes

The Icinga Notifications configuration options have been restructured. The listen and debug-password options were moved into the new listener section and renamed to address and debug_password, respectively. The channels-dir option was renamed to channels_dir. In addition to debug_password, the debug_password_file field was introduced.

The icingaweb2-url global option has been dropped without replacement and you will have to remove it from your config. Icinga Notifications no longer builds any URLs on its own and can therefore no longer complete an event’s relative url. The field itself stays optional, but if an event carries one, /v1/process-event now rejects anything but an absolute URL.

If you are using Icinga DB as a source, you have to configure Icinga DB’s notifications.icingaweb2_url.

Please make sure to update your configuration file accordingly to ensure that Icinga Notifications continues to function properly after the upgrade. Below is an example of how to update your configuration file usually located at /etc/icinga-notifications/config.yml.

# Before (v0.2.0)

listen: "localhost:5680"
debug-password: "my-debug-password"

icingaweb2-url: http://localhost/icingaweb2
channels-dir: /usr/libexec/icinga-notifications/channels

# After (v1.0.0), note that icingaweb2-url is gone

channels_dir: /usr/libexec/icinga-notifications/channels

listener:
  address: "localhost:5680"
  debug_password: "my-debug-password"
  # debug_password_file: "/path/to/password/file"

Channels

The Rocket.Chat channel was removed.

Custom channel plugins must be adapted to the reworked channel plugin protocol, which now follows JSON-RPC 2.0, sends versioned notification requests, and lets Icinga Notifications manage the plugin state.

Custom Sources

If you are submitting events from another source than Icinga DB, adapt it to the /v1/process-event endpoint. Event rules are no longer referenced by the source via rule_ids and rules_version. Instead, the source submits the object’s relations, which are evaluated against the event rules’ object filters. Furthermore, name and summary are now required, the incident field decides which event rules are evaluated, and a successfully queued event is answered with HTTP 204.

Icinga Notifications Web

The Icinga Notifications Web module was developed alongside Icinga Notifications. This came with a few changes as well, as documented below.

Permissions

The Notifications → Configuration menu entry no longer exists. Incidents, History, Event Rules, Schedules, Contacts and Contact Groups are now separate entries under Notifications. Channels, sources and the database connection remain available as tabs under Configuration → Modules → notifications.

The new permissions notifications/view/incidents and notifications/view/history control access to incidents and the notification history. Existing roles do not have them. Add them to all roles whose users need to keep seeing incidents in Icinga Notifications Web.

Warning

Restricting users to certain objects is not supported. Only grant these permissions to users who are allowed to see all events and incidents. Regular users should work with incidents in the web integration of the source. See Access Control.

Removed Features

  • The Events list and the event detail view have been removed. The daemon no longer stores events. Use the incident history and the notification history to analyze its behavior.
  • The channel type Rocket.Chat has been removed. Make sure no contact uses it as default channel and no event rule notifies through it.

Event Rules

Event rules are now bound to a source type instead of an individual source. A rule applies to all sources of that type. Deleting a source only deletes its event rules if it is the last source of its type.

If your event rules still contain filters in the format used before v1.0, they are marked in Notifications → Event Rules as outdated. Click on the rule to migrate its filter. Review the converted filter and save it. This is only possible if the integration of the source supports it.

Event rules can now be of the type escalation rule or notification rule. Existing rules are escalation rules.

Sources

Source integrations are now able to provide assistance as part of their own configuration UI to set up their own source. A source maintained this way is shown as locked and read-only in Icinga Notifications Web.

Upgrading to Icinga Notifications v0.2.0

This Icinga Notifications release moves the Icinga event source from Icinga 2 to Icinga DB. For this change, Icinga DB is now a required component and some manual changes are necessary, as described below.

Requirements

Version 0.2.0 of Icinga Notifications is released alongside - Icinga Notifications Web 0.2.0, - Icinga DB 1.5.0, and - Icinga DB Web 1.3.0.

Ensure that the new requirements are met before updating Icinga Notifications.

Schema

The upgrade script 0.2.0.sql must be applied as described in the schema upgrade section.

Configuration Changes

Please apply the following changes in this order to migrate from an Icinga 2 source to an Icinga DB source.

Start with removing the api-timeout option from Icinga Notifications configuration file /etc/icinga-notifications/config.yml. This entry was used to access the Icinga 2 API and became obsolete.

If you have created an ApiUser solely for Icinga Notifications in the Icinga 2 configuration somewhere under /etc/icinga2/, delete it.

After applying these changes, please restart Icinga 2 and Icinga Notifications.

systemctl restart icinga2 icinga-notifications

Now log into Icinga Web 2, navigate to the module configuration, and open notifications. Select the Sources tab and update the username and password for each former Icinga 2 source, being an Icinga DB source now.

Update the Icinga DB configuration file /etc/icingadb/config.yml for each new Icinga DB source and add the new notifications configuration option. - The url points to your Icinga Notifications API, allowing Icinga DB to submit events. When running Icinga Notifications on the same host as Icinga DB, this is typically http://localhost:5680/. - The username and password are used to authenticate the Icinga DB source. These are the login credentials just configured in Icinga Notifications Web.

Now, restart Icinga DB.

systemctl restart icingadb

Back in Icinga Web 2, click on Notifications in the left sidebar, select Configuration, and open the Event Rules tab. With this update, rules are now bound to sources. Thus, check for each rule that they apply to the desired source by selecting the rule and editing it via the edit icon right to its name. In case some rules of yours should apply to multiple sources, please duplicate these rules.

The migration should be finished now. Please take a look at the other configuration options and verify that Icinga Notifications works as intended. Thanks for following this migration.