summaryrefslogtreecommitdiffstats
path: root/doc/10-Migration.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/10-Migration.md160
1 files changed, 160 insertions, 0 deletions
diff --git a/doc/10-Migration.md b/doc/10-Migration.md
new file mode 100644
index 0000000..a8ed80f
--- /dev/null
+++ b/doc/10-Migration.md
@@ -0,0 +1,160 @@
+# 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.
+
+## Navigation
+
+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:**
+```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, 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](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.
+
+### 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