Migration¶

If you previously used the monitoring module, (built into Icinga Web 2) you may want to migrate your existing configuration, custom dashboards and navigation items as well as permissions or restrictions.

If that is the case, this chapter has you covered.

Configuration¶

Command Transports¶

Icinga DB Web still uses the same configuration format for command transports. This means that the file /etc/icingaweb2/modules/monitoring/commandtransports.ini can simply be copied over to /etc/icingaweb2/modules/icingadb/commandtransports.ini.

But note that Icinga DB Web doesn’t support the commandfile (local and remote) anymore. Remove all sections that do not define transport=api.

Protected Customvars¶

The rules previously configured at Configuration -> Modules -> monitoring -> Security have moved into the roles configuration as a new restriction. This is called icingadb/protect/variables and accepts the same rules. Just copy them over.

The monitoring module provides two custom navigation item types: host-action and service-action Icinga DB Web does the same, though uses different type names to achieve that: icingadb-host-action and icingadb-service-action

With Icinga DB Web 1.1, its migrate command allows you to migrate these navigation items automatically:

icingacli icingadb migrate navigation --user=<name> [--no-backup] [--override]

By default, this only migrates navigation items of specific users and keeps the old ones. The --user switch expects a username, with optional wildcards (*) to match multiple users. --user=* matches all users. Pass --no-backup to fully remove the old monitoring navigation items.

A similar version of this command has already been available since Icinga Web 2.9.4. Due to this, the new command allows you to perform the migration from scratch again with the --override switch. (Provided you still have the old navigation items.) Otherwise, already migrated items are ignored. That’s also a difference to the previous command, which duplicated items instead.

Dashboards¶

The dashboard item configuration does not change since it is related to Icinga Web. However, items that reference views of the monitoring module should be changed in order to permanently reference views of Icinga DB Web.

With Icinga DB Web 1.1, its migrate command allows you to migrate such dashboard items automatically:

icingacli icingadb migrate dashboard --user=<name> [--no-backup]

By default, this only migrates dashboards of specific users and creates backups. The --user switch expects a username, with optional wildcards (*) to match multiple users. --user=* matches all users. Pass --no-backup to disable backup creation. Please note, if you do so, that this makes resetting changes more difficult.

Automation¶

For those who integrate Icinga Web into e.g. custom dashboards, there is also a way to automate the migration of urls. An API endpoint in Icinga DB Web allows for this:

/icingaweb2/icingadb/migrate/monitoring-url

If you POST a JSON list there, you’ll get a JSON list back with the transformed urls in it. The returned list is ordered the same and any unrecognized url is left unchanged:

Input:

[
    "/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)",
    "/icingaweb2/businessprocess/process/show?config=production"
]

Output:

[
    "/icingaweb2/icingadb/services?hostgroup.name=prod-hosts|(host.vars.env=prod&host.vars.stage!=testing)",
    "/icingaweb2/businessprocess/process/show?config=production"
]

cURL example:
curl -s -HContent-Type:application/json -HAccept:application/json -u icingaadmin:icinga http://localhost/icingaweb2/icingadb/migrate/monitoring-url -d '["/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)","/icingaweb2/businessprocess/process/show?config=production"]'

Views and Exports¶

Url Parameter `addColumns`¶

The host and service list of the monitoring module allows to show/export additional information per object by using the URL parameter addColumns. Icinga DB Web has a very similar but much enhanced parameter: columns

If you pass this to the host and service list of Icinga DB Web, you’ll get an entirely different view mode in which you have full control over the information displayed. The parameter accepts a comma separated list of columns. This list also defines the order in which the columns are shown.

As of now, there is no dedicated control in the UI to conveniently choose those columns. You can use all columns however, which are valid in the search bar as well. The migration widget, that’s shown if you have access to monitoring and Icinga DB Web, also assists you by providing an example set of columns conveying the same information shown in the monitoring module lists.

Access Control¶

`monitoring/filter/objects`¶

This is now icingadb/filter/objects but still accepts the same filter syntax. Only the columns have changed or support for them has been dropped. Check the table below for details:

Old Column Name	New Column Name
instance_name	-
host_name	host.name
hostgroup_name	hostgroup.name
service_description	service.name
servicegroup_name	servicegroup.name
_host_customvar	host.vars.customvar
_service_customvar	service.vars.customvar

`monitoring/blacklist/properties`¶

This is now icingadb/denylist/variables. However, it does not accept the same rules as monitoring/blacklist/properties. It still accepts a comma separated list of GLOB like filters, but with some features removed:

No distinction between host and service variables (host.vars. and service.vars. prefixes are no longer keywords)
No ** to cross multiple level boundaries at once (a.**.d does not differ from a.*.d)
Dots are not significant (foo.*.oof and foo*oof will both match foo.bar.oof)

Check the security chapter for more details.

Permissions¶

The command permissions have not changed. It is only the module identifier that has changed of course: monitoring/command/* is now icingadb/command/*

The no-monitoring/contacts permission (or fake refusal) is now a restriction: icingadb/denylist/routes. Add users,usergroups to it to achieve the same effect.

Perform The Migration¶

To apply the necessary changes automatically, Icinga DB Web 1.1 provides this command:

icingacli icingadb migrate role [--role=<name>] [--group=<name>] [--override] [--no-backup]

By default, this only migrates roles with matching names or matching groups, doesn’t change roles that were already manually migrated and creates backups. Either --role or --group must be passed, but not both. Both accept wildcards and just * matches all roles. Pass --override to forcefully update roles that appear to be already migrated. Please note that this will reset changes made to Icinga DB Web’s rules, which were not equally applied to their monitoring module counterparts. Pass --no-backup to disable backup creation. Please note, if you do so, that this makes resetting changes more difficult.

With respect to permissions, the command will only migrate the command permissions. If a role grants full or general access to the monitoring module, this is not automatically migrated. You have to adjust this manually. It gives you the chance to review the performed changes, before letting them loose on your users. Please also take in mind, that Icinga DB Web handles permissions and restrictions differently. Our blog provides details on that: https://icinga.com/blog/2021/04/07/web-access-control-redefined/#icingadb-permission-linkage