summaryrefslogtreecommitdiffstats
path: root/doc/10-Migration.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 12:36:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 12:36:40 +0000
commita0901c4b7f2db488cb4fb3be2dd921a0308f4659 (patch)
treefafb393cf330a60df129ff10d0059eb7b14052a7 /doc/10-Migration.md
parentInitial commit. (diff)
downloadicingadb-web-a0901c4b7f2db488cb4fb3be2dd921a0308f4659.tar.xz
icingadb-web-a0901c4b7f2db488cb4fb3be2dd921a0308f4659.zip
Adding upstream version 1.0.2.upstream/1.0.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/10-Migration.md')
-rw-r--r--doc/10-Migration.md132
1 files changed, 132 insertions, 0 deletions
diff --git a/doc/10-Migration.md b/doc/10-Migration.md
new file mode 100644
index 0000000..a7742f3
--- /dev/null
+++ b/doc/10-Migration.md
@@ -0,0 +1,132 @@
+# 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.
+
+## Dashboards and Navigation
+
+![Url Migration Preview](res/url-migration-preview.png)
+
+The dashboard and menu item configuration does not change since these are related
+to Icinga Web 2. However, if you've used the monitoring module's urls and you want
+to update them, this might be straight forward if it's only the url path that needs
+to change. Complex filters though can be cumbersome to rewrite.
+
+That is why we provided the migration widget shown above. It will show up for every
+monitoring module url for which there is a counterpart in Icinga DB Web. You can then
+switch to the respective view in Icinga DB Web with a single click and either use the
+new url from the address bar or add it the usual way to the dashboard and sidebar.
+
+Host and service actions on the other hand are part of the monitoring module. For them
+Icinga DB Web provides their own counterparts. You don't need to migrate them manually
+though. The `migrate` command of Icinga Web 2 (>= v2.9.4) provides an action for that:
+
+`icingacli migrate navigation [--user=<username>] [--delete]`
+
+By default this will migrate the configuration of all users and won't delete the old
+ones. It can be restricted to a single user and the removal of the old configuration
+can be enabled as well.
+
+### Automation
+
+For those who have a plethora of custom dashboards or navigation items there is also
+a way to automate the migration of these urls. There is an API endpoint in Icinga DB
+Web that the very same widget from above utilizes:
+
+`/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 not recognized url is left
+unchanged:
+
+**Input:**
+```json
+[
+ "/icingaweb2/monitoring/list/services?hostgroup_name=prod-hosts|(_host_env=prod&_host_stage!=testing)",
+ "/icingaweb2/businessprocess/process/show?config=production"
+]
+```
+
+**Output**:
+```json
+[
+ "/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 mentioned earlier also assists you by providing an
+example set of columns conveying the same information shown in the monitoring module lists.
+
+## Restrictions
+
+### `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](04-Security.md#variable-paths) 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.