diff options
Diffstat (limited to 'doc')
24 files changed, 826 insertions, 0 deletions
diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 0000000..a13333e --- /dev/null +++ b/doc/01-About.md @@ -0,0 +1,64 @@ +# Icinga DB Web + +Icinga DB is a set of components for publishing, synchronizing and +visualizing monitoring data in the Icinga ecosystem, consisting of: + +* Icinga DB Web which connects to both a Redis server and a database to view and work with monitoring data +* Icinga 2 with its [Icinga DB feature](https://icinga.com/docs/icinga-2/latest/14-features/#icinga-db) enabled, + responsible for publishing monitoring configuration, check results, + states changes and history items to the Redis server +* And the [Icinga DB daemon](https://icinga.com/docs/icinga-db/latest/01-About/), + which synchronizes monitoring data between the Redis server and the database + + + +## Features + +Icinga DB Web offers a modern and streamlined design to provide a clear and +concise overview of your monitoring environment, also with dark and light mode support. + + + +### Various List Layouts + +The view switcher allows to control the level of detail displayed in host and service list views: + + + +### Search with Autocomplete + +The search bar in list views can be used for everything from simple searches to creating complex filters. +It allows full keyboard control and also supports contextual auto-completion. +In addition, there is an editor for easier filter creation. + + + +### Clean Detail Views + +Host and service detail views are structured to make best use of available space. +Related information is grouped and important information is at the top for instant access without having to scroll down. + + + +### Modal Dialogs + +Any interaction that requires user input, such as acknowledging problems, scheduling downtimes, etc., +shows a modal dialog over the current view to preserve context and focus on interaction. + + + +### Bulk Operations + +Bulk interactions such as scheduling downtimes for multiple objects, acknowledging multiple problems, etc. +are easily accomplished with the `Continue With` control that operates on filtered lists. + + + +## Installation + +To install Icinga DB Web see [Installation](02-Installation.md). + +## License + +Icinga DB Web and the Icinga DB Web documentation are licensed under the terms of the +GNU General Public License Version 2. diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..1e68342 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,28 @@ +<!-- {% if index %} --> +# Installing Icinga DB Web + +The recommended way to install Icinga DB Web is to use prebuilt packages for +all supported platforms from our official release repository. +Please follow the steps listed for your target operating system, +which guide you through setting up the repository and installing Icinga DB Web. + +To upgrade an existing Icinga DB Web installation to a newer version, +see the [Upgrading](05-Upgrading.md) documentation for the necessary steps. + + + +Before installing Icinga DB Web, make sure you have installed the +[Icinga DB daemon](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/). + +<!-- {% else %} --> +<!-- {% if not icingaDocs %} --> + +## Installing the Package + +If the [repository](https://packages.icinga.com) is not configured yet, please add it first. +Then use your distribution's package manager to install the `icingadb-web` package +or install [from source](02-Installation.md.d/From-Source.md). +<!-- {% endif %} --> + +This concludes the installation. Now proceed with the [configuration](03-Configuration.md). +<!-- {% endif %} --><!-- {# end else if index #} --> diff --git a/doc/02-Installation.md.d/From-Source.md b/doc/02-Installation.md.d/From-Source.md new file mode 100644 index 0000000..b430d16 --- /dev/null +++ b/doc/02-Installation.md.d/From-Source.md @@ -0,0 +1,17 @@ +# Installing Icinga DB Web from Source + +Please see the Icinga Web documentation on +[how to install modules](https://icinga.com/docs/icinga-web-2/latest/doc/08-Modules/#installation) from source. +Make sure you use `icingadb` as the module name. The following requirements must also be met. + +### Requirements + +* PHP (≥7.2) +* MySQL or PostgreSQL PDO PHP libraries +* The following PHP modules must be installed: `cURL`, `dom`, `json`, `libxml` +* [Icinga DB](https://github.com/Icinga/icingadb) +* [Icinga Web 2](https://github.com/Icinga/icingaweb2) (≥2.9) +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥0.13) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.12) + +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..ce24277 --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,67 @@ +# Configuration + +If Icinga Web has been installed but not yet set up, please visit Icinga Web and follow the web-based setup wizard. +For Icinga Web setups already running, log in to Icinga Web with a privileged user and follow the steps below to +configure Icinga DB Web: + +If you have previously used the monitoring module, there is an option to [migrate](10-Migration.md) some settings. + +## Database Configuration + +Connection configuration for the database to which Icinga DB synchronizes monitoring data. + +1. Create a new resource for the Icinga DB database via the `Configuration → Application → Resources` menu. + +2. Configure the resource you just created as the database connection for the Icinga DB Web module using the + `Configuration → Modules → icingadb → Database` menu. + +## Redis Configuration + +Connection configuration for the Redis server where Icinga 2 writes check results. +This data is used to display the latest state information in Icinga DB Web. + +1. Configure the connection to the Redis server through the `Configuration → Modules → icingadb → Redis` menu. + +!!! info + + If you are running a high-availability Icinga 2 setup, + also configure the secondary master's Redis connection details. + Icinga DB Web then uses this connection if the primary one is not available. + +## Command Transport Configuration + +In order to acknowledge problems, force checks, schedule downtimes, etc., +Icinga DB Web needs access to the Icinga 2 API. +For this you need an `ApiUser` object with at least the following permissions on the Icinga 2 side: + +* `actions/*` +* `objects/query/*` +* `objects/modify/*` +* `status/query` + +!!! tip + + For single-node setups it is recommended to manage API credentials in the `/etc/icinga2/conf.d/api-users.conf` file. + If you are running a high-availability Icinga 2 setup, please manage the credentials in the master zone. + +1. Please add the following Icinga 2 configuration and change the password accordingly: + ``` + object ApiUser "icingadb-web" { + password = "CHANGEME" + permissions = [ "actions/*", "objects/modify/*", "objects/query/*", "status/query" ] + } + ``` +2. Restart Icinga 2 for these changes to take effect. +3. Then configure a command transport for Icinga DB Web + using the credentials you just created via the `Configuration → Modules → icingadb → Command Transports` menu. + +!!! info + + If you are running a high-availability Icinga 2 setup, + also configure the secondary master's API command transport. + Icinga DB Web then uses this transport if the primary one is not available. + +## Security + +To grant users permissions to run commands and restrict them to specific views, +see the [Security](04-Security.md) documentation for the necessary steps. diff --git a/doc/04-Security.md b/doc/04-Security.md new file mode 100644 index 0000000..d3e7545 --- /dev/null +++ b/doc/04-Security.md @@ -0,0 +1,142 @@ +# Security + +Icinga DB Web allows users to send commands to Icinga. Users may be restricted to a specific set of commands, +by use of **permissions**. + +The same applies to routes, objects and variables. To these, users can be restricted by use of **restrictions**. + +## Permissions + +> **Restricted Command Permissions:** +> +> If a role [limits users](#filters) to a specific set of results, the command +> permissions or refusals of the very same role only apply to these results. + +| Name | Allow... | +|------------------------------------------------|----------------------------------------------------------------------------------| +| icingadb/command/* | all commands | +| icingadb/command/schedule-check | to schedule host and service checks | +| icingadb/command/schedule-check/active-only | to schedule host and service checks (Only on objects with active checks enabled) | +| icingadb/command/acknowledge-problem | to acknowledge host and service problems | +| icingadb/command/remove-acknowledgement | to remove problem acknowledgements | +| icingadb/command/comment/* | to add and delete host and service comments | +| icingadb/command/comment/add | to add host and service comments | +| icingadb/command/comment/delete | to delete host and service comments | +| icingadb/command/downtime/* | to schedule and delete host and service downtimes | +| icingadb/command/downtime/schedule | to schedule host and service downtimes | +| icingadb/command/downtime/delete | to delete host and service downtimes | +| icingadb/command/process-check-result | to process host and service check results | +| icingadb/command/feature/instance | to toggle instance-wide features | +| icingadb/command/feature/object/* | to toggle all features on host and service objects | +| icingadb/command/feature/object/active-checks | to toggle active checks on host and service objects | +| icingadb/command/feature/object/passive-checks | to toggle passive checks on host and service objects | +| icingadb/command/feature/object/notifications | to toggle notifications on host and service objects | +| icingadb/command/feature/object/event-handler | to toggle event handlers on host and service objects | +| icingadb/command/feature/object/flap-detection | to toggle flap detection on host and service objects | +| icingadb/command/send-custom-notification | to send custom notifications for hosts and services | +| icingadb/object/show-source | to view an object's source data. (May contain sensitive data!) | + +## Restrictions + +### Filters + +Filters limit users to a specific set of results. + +> **Note:** +> +> Filters from multiple roles will widen available access. + +| Name | Description | +|--------------------------|------------------------------------------------------------------------| +| icingadb/filter/objects | Restrict access to the Icinga objects that match the filter | +| icingadb/filter/hosts | Restrict access to the Icinga hosts and services that match the filter | +| icingadb/filter/services | Restrict access to the Icinga services that match the filter | + +`icingadb/filter/objects` will only allow users to access matching objects. This applies to all objects, +not just hosts or services. It should be one or more [filter expressions](#filter-expressions). + +`icingadb/filter/hosts` will only allow users to access matching hosts and services. Other objects remain +unrestricted. It should be one or more [filter expressions](#filter-expressions). + +`icingadb/filter/services` will only allow users to access matching services. Other objects remain unrestricted. +It should be one or more [filter expressions](#filter-expressions). + +### Denylists + +Denylists prevent users from accessing information and in some cases will block them entirely from it. + +> **Note:** +> +> Denylists from multiple roles will further limit access. + +Name | Description +-----------------------------|------------------------------------------------------------------ +icingadb/denylist/routes | Prevent access to routes that are part of the list +icingadb/denylist/variables | Hide custom variables of Icinga objects that are part of the list + +`icingadb/denylist/routes` will block users from accessing defined routes and from related information elsewhere. +For example, if `hostgroups` are part of the list a user won't have access to the hostgroup overview nor to a host's +groups shown in its detail area. This should be a comma separated list. Possible values are: hostgroups, servicegroups, +users, usergroups + +`icingadb/denylist/variables` will block users from accessing certain custom variables. A user affected by this won't +see that those variables even exist. This should be a comma separated list of [variable paths](#variable-paths). It is +possible to use [match patterns](#match-patterns). + +### Protections + +Protections prevent users from accessing actual data. They will know that there is something, but not what exactly. + +> **Note:** +> +> Denylists from multiple roles will further limit access. + +Name | Description +---------------------------|----------------------------------------------------------------------------- +icingadb/protect/variables | Obfuscate custom variable values of Icinga objects that are part of the list + +`icingadb/protect/variables` will replace certain custom variable values with `***`. A user affected by this will still +be able to see the variable names though. This should be a comma separated list of [variable paths](#variable-paths). +It is possible to use [match patterns](#match-patterns). + +### Formats + +#### Filter Expressions + +These consist of one or more [filter expressions](https://icinga.com/docs/icinga-web-2/latest/doc/06-Security/#filter-expressions). + +Allowed columns are: + +* host.name +* service.name +* hostgroup.name +* servicegroup.name +* host.user.name +* service.user.name +* host.usergroup.name +* service.usergroup.name +* host.vars.[\<variable path\>](#variable-paths) +* service.vars.[\<variable path\>](#variable-paths) + +#### Match Patterns + +Match patterns allow a very simple form of wildcard matching. Use `*` in any place to match zero or any characters. + +#### Variable Paths + +Icinga DB Web allows to express any custom variable depth in variable paths. So they may be not just names. + +Consider the following variables: + +``` +vars.os = "Linux" +vars.team = { + name = "Support", + on-site = ["mo", "tue", "wed", "thu", "fr"] +} +``` + +To reference `vars.os`, use `os`. To reference `vars.team.name`, use `team.name`. To reference `vars.team.on-site`, +use `team.on-site[0]` for the first list position and `team.on-site[4]` for the last one. + +Combined with a [match pattern](#match-patterns) it is also possible to perform a *contains* check: `team.on-site[*]` diff --git a/doc/05-Upgrading.md b/doc/05-Upgrading.md new file mode 100644 index 0000000..007a4c1 --- /dev/null +++ b/doc/05-Upgrading.md @@ -0,0 +1,37 @@ +# Upgrading Icinga DB Web + +Specific version upgrades are described below. Please note that version upgrades are incremental. +If you are upgrading across multiple versions, make sure to follow the steps for each of them. + +## Upgrading to Icinga DB Web v1.1 + +**Breaking Changes** + +We've extended our filter syntax to include new signs for *like* and *unlike* comparisons. These are `~` and `!~`, +respectively. The *equal* (`=`) and *unequal* (`!=`) operators won't perform any wildcard matching anymore due to +this. If you have dashboards, navigation items or bookmarks that attempt to perform wildcard matching with *equal*/ +*unequal* comparisons, the migration widget in the top right will toggle and suggest you an automatically transformed +alternative. + +Please note that due to our release process, this change already affects installations of Icinga DB Web v1.0.x. + +The module's migration command already performs the transformations necessary once you migrate navigation items, +dashboards and roles. (As described in the [Migration](10-Migration.md) chapter.) If you already migrated such +manually in the past, and you don't want to perform the entire migration again, you can use the following command +to only transform filters of such: + +`icingacli icingadb migrate filter [--no-backup]` + +By default, this creates backups of menu items, dashboards and roles. Pass `--no-backup` to disable this. + +## Upgrading to Icinga DB Web v1.0 + +**Requirements** + +* You need at least Icinga DB version 1.0.0 to run Icinga DB Web v1.0.0. + +**Configuration Changes** + +* The restrictions `icingadb/blacklist/routes` and `icingadb/blacklist/variables` have been renamed to + `icingadb/denylist/routes` and `icingadb/denylist/variables` respectively. If you use this restriction, + make sure to adjust `/etc/icingaweb2/roles.ini` accordingly. diff --git a/doc/09-Automation.md b/doc/09-Automation.md new file mode 100644 index 0000000..f514188 --- /dev/null +++ b/doc/09-Automation.md @@ -0,0 +1,233 @@ +# Automation + +It is possible to issue command actions without a browser. To do so, a form needs to be submitted by a tool such as +cUrl. This is also used in the example below. + +## Request Format + +The request is required to be an Icinga Web API request. For this it is necessary to transmit the `Accept` HTTP header +and set it to `application/json`. In addition to this, the request must be authenticated using the `Basic` schema. + +All endpoints support filters. To issue commands only for specific items, define a filter in the request's query string. +If this filter is omitted, all items are affected. + +The options need to be transmitted in the request body as `multipart/form-data`. + +## Response Format + +If the request succeeds, the HTTP response code is `200` and the response body contains a JSON object such as this: + +```json +{ + "status": "success", + "data": [ + { + "type": "success", + "message": "Added comment successfully" + } + ] +} +``` + +If there's something wrong with the options, the HTTP response code is `422` and the response body contains a JSON +object such as this: + +```json +{ + "status": "fail", + "data": { + "comment": [], + "expire": [], + "expire_time": ["The expire time must not be in the past"] + } +} +``` + +## Example + +```shell +USER="icingaadmin" +PASSWORD="icinga" +BASEURL="http://localhost/icingaweb2" +FILTER="host.name=docker-master" +curl -H "Accept: application/json" -u $USER:$PASSWORD "$BASEURL/icingadb/hosts/add-comment?$FILTER" \ + -F "comment=kaput" -F "expire_time=2023-10-05T20:00:00" -F "expire=y" +``` + +## Option Types + +### Text + +A simple text message. May contain newlines. + +### Number + +An integer value. + +### BoolEnum + +A string with the value of `y` for `true` and `n` for `false`. + +### DateTime + +A date time string in the following format: `Y-m-d\TH:i:s` + +The timezone this is interpreted in depends on the user who's transmitting the request. +To change this, log in as this user and change its preference setting. + +### State + +| Value | Description | Applicable To | +|-------|----------------|----------------| +| 0 | UP / OK | Host / Service | +| 1 | DOWN / WARNING | Host / Service | +| 2 | CRITICAL | Service | +| 3 | UNKNOWN | Service | + +### PerfData + +Please have a look at the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html#AEN201). + +### ChildOption + +| Value | Description | +|-------|-----------------------------------------------------| +| 0 | Do nothing with child hosts | +| 1 | Schedule triggered downtime for all child hosts | +| 2 | Schedule non-triggered downtime for all child hosts | + +## Endpoints + +### Acknowledge Problem + +#### Routes + +* icingadb/hosts/acknowledge +* icingadb/services/acknowledge + +#### Options + +| Option | Required | Type | Depends On | +|-------------|----------|----------|------------| +| comment | y | Text | - | +| persistent | n | BoolEnum | - | +| notify | n | BoolEnum | - | +| sticky | n | BoolEnum | - | +| expire | n | BoolEnum | - | +| expire_time | y | DateTime | expire | + +### Add Comment + +#### Routes + +* icingadb/hosts/add-comment +* icingadb/services/add-comment + +#### Options + +| Option | Required | Type | Depends On | +|-------------|----------|----------|------------| +| comment | y | Text | - | +| expire | n | BoolEnum | - | +| expire_time | y | DateTime | expire | + +### Check Now + +#### Routes + +* icingadb/hosts/check-now +* icingadb/services/check-now + +#### Options + +None. + +### Process Check Result + +#### Routes + +* icingadb/hosts/process-checkresult +* icingadb/services/process-checkresult + +#### Options + +| Option | Required | Type | +|----------|----------|----------| +| status | y | State | +| output | y | Text | +| perfdata | n | PerfData | + +### Remove Acknowledgement + +#### Routes + +* icingadb/hosts/remove-acknowledgement +* icingadb/services/remove-acknowledgement + +#### Options + +None. + +### Schedule Check + +#### Routes + +* icingadb/hosts/schedule-check +* icingadb/services/schedule-check + +#### Options + +| Option | Required | Type | +|-------------|----------|----------| +| check_time | y | DateTime | +| force_check | n | BoolEnum | + +### Schedule Host Downtime + +#### Routes + +* icingadb/hosts/schedule-downtime + +#### Options + +| Option | Required | Type | Depends On | +|---------------|----------|-------------|------------| +| comment | y | Text | - | +| start | y | DateTime | - | +| end | y | DateTime | - | +| flexible | n | BoolEnum | - | +| hours | y | Number | flexible | +| minutes | y | Number | flexible | +| all_services | n | BoolEnum | - | +| child_options | n | ChildOption | - | + +### Schedule Service Downtime + +#### Routes + +* icingadb/services/schedule-check + +#### Options + +| Option | Required | Type | Depends On | +|----------|----------|-------------|------------| +| comment | y | Text | - | +| start | y | DateTime | - | +| end | y | DateTime | - | +| flexible | n | BoolEnum | - | +| hours | y | Number | flexible | +| minutes | y | Number | flexible | + +### Send Custom Notification + +#### Routes + +* icingadb/hosts/send-custom-notification +* icingadb/services/send-custom-notification + +#### Options + +| Option | Required | Type | +|---------|----------|----------| +| comment | y | Text | +| forced | n | BoolEnum | 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 diff --git a/doc/11-Concepts.md b/doc/11-Concepts.md new file mode 100644 index 0000000..35f7350 --- /dev/null +++ b/doc/11-Concepts.md @@ -0,0 +1,78 @@ +# Views + +## List Items +Each list that is shown in the web interface consists of list items that follow this basic schema: + + +### Visual +Each element has a so-called visual. It's purpose is to highlight certain elements in long lists and give an intuitive overview about the underlying objects' condition. +In the case of host or service lists, the state is displayed. This makes it obvious if and where there are problems that need to be taken care of, immediately from the overview. + +### Title +The title briefly describes the state of the list element as an addition to the visual. For example, it contains the information that a host is currently DOWN state. While the visual gives an intuitive impression, the title explains what exactly happened. + +### Meta +The meta area provides additional details, usually displays of time. In the host and service lists, you can see how long the object has been in its current state. + +### Caption +The caption area contains detailed information about the list item. In the case of hosts and services this would be the check output. For comments and downtimes the comment texts of the user are displayed here. To make the default list view compact and consistent, long texts are truncated to a maximum of two lines. + +## Different detail degrees + +The level of detail of the host and service lists is selectable - the above image shows the default list item, but there are two more iterations: + +In the compact mode the entire list item is displayed in one single line. +Given, that there is enough space, the caption is placed in the same line as the rest and trimmed to fit. + + +The detailed mode displays the entire caption, which makes it possible to react to problems directly from the list view. + + +## Overdue Items + +In host and service lists overdue checks are highlighted. This makes it immediately apparent which objects may no longer be up-to-date. The red badge contains information about how long the check has been overdue. + + +## Downtimes +Downtime lists have an extra information to be displayed: the progress. +How far along the downtime is, is immeadiately visible via the progress bar at the top of each list item. +In the visual it is displayed how much time is left until the downtime ends. + + + +# Modal +The modal element introduces short interaction dialogues. For actions in the detail area, a modal dialog will appear. This preserves the left list column and thus the content better. + + +### Utility +The utility or close button is one of three ways to close the modal without confirming your changes. It's also possible to just click outside it's borders or press the escape key to return to the previous page. + +### Title +The title specifies the target, e.g. an action like: Acknowledge Problem, Add Comment or Schedule Downtime. + +### Hint +The hint explains more about how to interact with the modal and what is asked of you. It goes into detail about the consequences from an action to your environment + +### Form +The form is the main focus of the modal. It takes the call to action out of the normal page flow and makes it easy to focus on the task at hand. + +### Submit +With the submit button you apply the selections you made in the form and return to where you left off. + +# Details + +## Check statistics +Information about check execution is available in a handy graph that makes it possible to get all of the information at a glance. + + +### Descriptions and Values +Instead of having a table with the different check information there is a header that lays out the information in an intuitive way, giving weight to more important bits of data and their values. + +### Graph +The graphical element makes it easier to see, whether the check is on time or late. It's easy to immediately see the configured check interval and have a better grasp on how up-to-date the current state is. + +### Indicator +The indicator visualises where the current time fits in for orientation. + +### Specifics +The specifics put the exact times of the execution points in relation to each other. There are both the full timestamps and the passed time immediately visible. diff --git a/doc/res/CheckStatisticsAnatomy.jpg b/doc/res/CheckStatisticsAnatomy.jpg Binary files differnew file mode 100644 index 0000000..de3dc43 --- /dev/null +++ b/doc/res/CheckStatisticsAnatomy.jpg diff --git a/doc/res/ListAnatomyOverdue.jpg b/doc/res/ListAnatomyOverdue.jpg Binary files differnew file mode 100644 index 0000000..35120fd --- /dev/null +++ b/doc/res/ListAnatomyOverdue.jpg diff --git a/doc/res/ListItemAnatomy.jpg b/doc/res/ListItemAnatomy.jpg Binary files differnew file mode 100644 index 0000000..b24c92b --- /dev/null +++ b/doc/res/ListItemAnatomy.jpg diff --git a/doc/res/ListItemAnatomyCompact.jpg b/doc/res/ListItemAnatomyCompact.jpg Binary files differnew file mode 100644 index 0000000..faa474c --- /dev/null +++ b/doc/res/ListItemAnatomyCompact.jpg diff --git a/doc/res/ListItemAnatomyDetailed.jpg b/doc/res/ListItemAnatomyDetailed.jpg Binary files differnew file mode 100644 index 0000000..1772f80 --- /dev/null +++ b/doc/res/ListItemAnatomyDetailed.jpg diff --git a/doc/res/ListItemDowntimeAnatomy.jpg b/doc/res/ListItemDowntimeAnatomy.jpg Binary files differnew file mode 100644 index 0000000..ebe40a1 --- /dev/null +++ b/doc/res/ListItemDowntimeAnatomy.jpg diff --git a/doc/res/ModalAnatomy.jpg b/doc/res/ModalAnatomy.jpg Binary files differnew file mode 100644 index 0000000..c59e0fe --- /dev/null +++ b/doc/res/ModalAnatomy.jpg diff --git a/doc/res/continue-with-preview.png b/doc/res/continue-with-preview.png Binary files differnew file mode 100644 index 0000000..30fada7 --- /dev/null +++ b/doc/res/continue-with-preview.png diff --git a/doc/res/icingadb-architecture.png b/doc/res/icingadb-architecture.png Binary files differnew file mode 100644 index 0000000..3d55ff7 --- /dev/null +++ b/doc/res/icingadb-architecture.png diff --git a/doc/res/icingadb-dashboard.png b/doc/res/icingadb-dashboard.png Binary files differnew file mode 100644 index 0000000..521eb39 --- /dev/null +++ b/doc/res/icingadb-dashboard.png diff --git a/doc/res/icingadb-web.png b/doc/res/icingadb-web.png Binary files differnew file mode 100644 index 0000000..05a3e31 --- /dev/null +++ b/doc/res/icingadb-web.png diff --git a/doc/res/modal-dialog-preview.png b/doc/res/modal-dialog-preview.png Binary files differnew file mode 100644 index 0000000..1cc1901 --- /dev/null +++ b/doc/res/modal-dialog-preview.png diff --git a/doc/res/searchbar-completion-preview.png b/doc/res/searchbar-completion-preview.png Binary files differnew file mode 100644 index 0000000..a847d63 --- /dev/null +++ b/doc/res/searchbar-completion-preview.png diff --git a/doc/res/service-detail-preview.png b/doc/res/service-detail-preview.png Binary files differnew file mode 100644 index 0000000..6d74d70 --- /dev/null +++ b/doc/res/service-detail-preview.png diff --git a/doc/res/view-switcher-preview.png b/doc/res/view-switcher-preview.png Binary files differnew file mode 100644 index 0000000..cc65d95 --- /dev/null +++ b/doc/res/view-switcher-preview.png |
