diff options
Diffstat (limited to 'doc')
30 files changed, 789 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..b78987c --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,273 @@ +<!-- {% 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 from_source %} --> +## Adding Icinga Package Repository + +The recommended way to install Icinga DB Web is to use prebuilt packages from our official release repository. + +!!! tip + + If you install Icinga DB Web on a node that has Icinga 2, Icinga DB or Icinga Web installed via packages, + proceed to [installing the Icinga DB Web package](#installing-icinga-db-web-package) as + the repository is already configured. + +Here's how to add the official release repository: + +<!-- {% if amazon_linux %} --> +<!-- {% if not icingaDocs %} --> +### Amazon Linux 2 Repository +<!-- {% endif %} --> +!!! info + + A paid repository subscription is required for Amazon Linux 2 repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription). + + Don't forget to fill in the username and password section with appropriate credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` +<!-- {% endif %} --> + +<!-- {% if centos %} --> +<!-- {% if not icingaDocs %} --> +### CentOS Repository +<!-- {% endif %} --> +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` +<!-- {% endif %} --> + +<!-- {% if debian %} --> +<!-- {% if not icingaDocs %} --> +### Debian Repository +<!-- {% endif %} --> + +```bash +apt-get update +apt-get -y install apt-transport-https wget gnupg + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - + +DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ + echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \ + /etc/apt/sources.list.d/${DIST}-icinga.list + echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \ + /etc/apt/sources.list.d/${DIST}-icinga.list + +apt-get update +``` +<!-- {% endif %} --> + +<!-- {% if rhel %} --> +<!-- {% if not icingaDocs %} --> +### RHEL Repository +<!-- {% endif %} --> +!!! info + + A paid repository subscription is required for RHEL repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription). + + Don't forget to fill in the username and password section with appropriate credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/subscription/rhel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +<!-- {% if not icingaDocs %} --> +### SLES Repository +<!-- {% endif %} --> +!!! info + + A paid repository subscription is required for SLES repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription). + + Don't forget to fill in the username and password section with appropriate credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key + +zypper ar https://packages.icinga.com/subscription/sles/ICINGA-release.repo +zypper ref +``` +<!-- {% endif %} --> + +<!-- {% if ubuntu %} --> +<!-- {% if not icingaDocs %} --> +### Ubuntu Repository +<!-- {% endif %} --> + +```bash +apt-get update +apt-get -y install apt-transport-https wget gnupg + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - + +. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \ + echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \ + /etc/apt/sources.list.d/${DIST}-icinga.list + echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \ + /etc/apt/sources.list.d/${DIST}-icinga.list + +apt-get update +``` +<!-- {% endif %} --> + +## Installing Icinga DB Web Package + +Use your distribution's package manager to install the `icingadb-web` package as follows: + +<!-- {% if amazon_linux %} --> +<!-- {% if not icingaDocs %} --> +#### Amazon Linux 2 +<!-- {% endif %} --> +```bash +yum install icingadb-web +``` +<!-- {% endif %} --> + +<!-- {% if centos %} --> +<!-- {% if not icingaDocs %} --> +#### CentOS +<!-- {% endif %} --> +!!! info + + Note that installing Icinga DB Web is only supported on CentOS 7 as CentOS 8 is EOL. + +```bash +yum install icingadb-web +``` +<!-- {% endif %} --> + +<!-- {% if debian or ubuntu %} --> +<!-- {% if not icingaDocs %} --> +#### Debian / Ubuntu +<!-- {% endif %} --> +```bash +apt-get install icingadb-web +``` +<!-- {% endif %} --> + +<!-- {% if rhel %} --> +#### RHEL 8 or Later + +```bash +dnf install icingadb-web +``` + +#### RHEL 7 + +```bash +yum install icingadb-web +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +<!-- {% if not icingaDocs %} --> +#### SLES +<!-- {% endif %} --> +```bash +zypper install icingadb-web +``` +<!-- {% endif %} --> + +<!-- {% else %} --><!-- {# end if not from_source #} --> +<!-- {% if not icingaDocs %} --> +## Installing Icinga DB Web from Source +<!-- {% endif %} --> + +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.10) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥0.11) +<!-- {% endif %} --><!-- {# end else if not from_source #} --> + +## Configuring Icinga DB Web + +<!-- {% if not from_source %} --> +The Icinga Web PHP framework is required to configure and run the Icinga DB Web module. +Package installations of `icingadb-web` already set up the necessary dependencies. +If Icinga Web has not been installed or set up before, +you have completed the instructions here and can proceed to +<!-- {% if amazon_linux %} --> +[install the web server on Amazon Linux](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/06-Amazon-Linux/#install-the-web-server), +<!-- {% endif %} --> +<!-- {% if centos %} --> +[install the web server on CentOS](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/03-CentOS/#install-the-web-server), +<!-- {% endif %} --> +<!-- {% if debian %} --> +[install the web server on Debian](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/01-Debian/#install-the-web-server), +<!-- {% endif %} --> +<!-- {% if rhel %} --> +[install the web server on RHEL](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/04-RHEL/#install-the-web-server), +<!-- {% endif %} --> +<!-- {% if sles %} --> +[install the web server on SLES](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/05-SLES/#install-the-web-server), +<!-- {% endif %} --> +<!-- {% if ubuntu %} --> +[install the web server on Ubuntu](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/02-Ubuntu/#install-the-web-server), +<!-- {% endif %} --> +which will then take you to the web-based setup wizard, which also covers the configuration of Icinga DB Web. +<!-- {% endif %} --><!-- {# end if not from_source #} --> + +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 the Icinga DB Web module: + +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. +3. Configure the connection to the Redis server through the `Configuration → Modules → icingadb → Redis` menu. +4. 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 appropriate permissions on the Icinga 2 side: + +!!! 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. + +If you have previously used the monitoring module, there is an option to [migrate](10-Migration.md) some settings. +<!-- {% endif %} --><!-- {# end else if index #} --> diff --git a/doc/02-Installation.md.d/01-Amazon-Linux.md b/doc/02-Installation.md.d/01-Amazon-Linux.md new file mode 100644 index 0000000..c4b2b50 --- /dev/null +++ b/doc/02-Installation.md.d/01-Amazon-Linux.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on Amazon Linux +<!-- {% set amazon_linux = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/02-CentOS.md b/doc/02-Installation.md.d/02-CentOS.md new file mode 100644 index 0000000..5f4a05b --- /dev/null +++ b/doc/02-Installation.md.d/02-CentOS.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on CentOS +<!-- {% set centos = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/03-Debian.md b/doc/02-Installation.md.d/03-Debian.md new file mode 100644 index 0000000..3097e4d --- /dev/null +++ b/doc/02-Installation.md.d/03-Debian.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on Debian +<!-- {% set debian = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/04-RHEL.md b/doc/02-Installation.md.d/04-RHEL.md new file mode 100644 index 0000000..bf88576 --- /dev/null +++ b/doc/02-Installation.md.d/04-RHEL.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on RHEL +<!-- {% set rhel = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/05-SLES.md b/doc/02-Installation.md.d/05-SLES.md new file mode 100644 index 0000000..7396fef --- /dev/null +++ b/doc/02-Installation.md.d/05-SLES.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on SLES +<!-- {% set sles = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/06-Ubuntu.md b/doc/02-Installation.md.d/06-Ubuntu.md new file mode 100644 index 0000000..9f6f9ff --- /dev/null +++ b/doc/02-Installation.md.d/06-Ubuntu.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web on Ubuntu +<!-- {% set ubuntu = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/07-From-Source.md b/doc/02-Installation.md.d/07-From-Source.md new file mode 100644 index 0000000..3fb55f6 --- /dev/null +++ b/doc/02-Installation.md.d/07-From-Source.md @@ -0,0 +1,3 @@ +# Installing Icinga DB Web from Source +<!-- {% set from_source = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..3f807cf --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,63 @@ +# Configuration + +Icinga DB Web is configured via the web interface. Below you will find an overview of the necessary 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..c6653d9 --- /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, +contacts, contactgroups + +`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..7bb3efd --- /dev/null +++ b/doc/05-Upgrading.md @@ -0,0 +1,16 @@ +# 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.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/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 + + + +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. 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/url-migration-preview.png b/doc/res/url-migration-preview.png Binary files differnew file mode 100644 index 0000000..759bfb1 --- /dev/null +++ b/doc/res/url-migration-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 |
