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.
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
But note that Icinga DB Web doesn’t support the commandfile (local and remote) anymore. Remove all sections
that do not define
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:
Icinga DB Web does the same, though uses different type names to achieve that:
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
switch expects a username, with optional wildcards (
*) to match multiple users.
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.
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
expects a username, with optional wildcards (
*) to match multiple users.
--user=* matches all users.
--no-backup to disable backup creation. Please note, if you do so, that this makes resetting
changes more difficult.
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:
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:
[ "/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)", "/icingaweb2/businessprocess/process/show?config=production" ]
[ "/icingaweb2/icingadb/services?hostgroup.name=prod-hosts|(host.vars.env=prod&host.vars.stage!=testing)", "/icingaweb2/businessprocess/process/show?config=production" ]
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¶
The host and service list of the monitoring module allows to show/export additional information per object by using the
addColumns. Icinga DB Web has a very similar but much enhanced parameter:
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.
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|
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 (
service.vars.prefixes are no longer keywords)
**to cross multiple level boundaries at once (
a.**.ddoes not differ from
- Dots are not significant (
foo*oofwill both match
Check the security chapter for more details.
The command permissions have not changed. It is only the module identifier that has changed of course:
monitoring/command/* is now
no-monitoring/contacts permission (or fake refusal) is now a restriction:
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
--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