Adding upstream version 0.3.3.upstream/0.3.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

19 files changed, 540 insertions, 0 deletions

diff --git a/doc/01-Introduction.md b/doc/01-Introduction.md
new file mode 100644
index 0000000..84d9661
--- /dev/null
+++ b/doc/01-Introduction.md
@@ -0,0 +1,51 @@
+Introduction
+============
+
+Top Level View is a hierarchy based status view for Icinga Web 2.
+
+You can define a hierarchical structure containing hosts, services and hostgroups.
+And the view presents you an overview of the overall status of the sub-hierarchies.
+
+With a caching layer, this view can aggregate thousands of status objects and make
+them easily available for overview and drill down.
+
+This view extends the status logic and behavior of Icinga Web 2 a bit,
+please see later chapters on details.
+
+## Requirements
+
+* Icinga Web 2 >= 2.5.0
+  * and its monitoring module
+
+## Installation
+
+The view is a simple module for Icinga Web 2, and can be installed via git or a tarball.
+
+Only other requirement is PHP YAML (which is needed for the configuration format), make
+sure to reload your web server after installing the module.
+
+    # on RHEL and compatible
+    yum install php-pecl-yaml
+    systemctl reload httpd.service
+
+    # on Debian / Ubuntu
+    apt-get install php-yaml
+    systemctl reload apache2.service
+
+You should download the latest released tarball from [GitHub](https://github.com/Icinga/icingaweb2-module-toplevelview/releases).
+
+    tar xf icingaweb2-module-toplevelview-0.x.x.tar.gz
+    mv icingaweb2-module-toplevelview-0.x.x/ /usr/share/icingaweb2/modules/toplevelview
+
+Or if you prefer use git.
+
+    git clone https://github.com/Icinga/icingaweb2-module-toplevelview.git \
+      /usr/share/icingaweb2/modules/toplevelview
+
+Enable the module in the web interface, or via CLI:
+
+    icingacli module enable toplevelview
+
+## Permissions
+
+TODO
diff --git a/doc/02-Behavior.md b/doc/02-Behavior.md
new file mode 100644
index 0000000..ae2444b
--- /dev/null
+++ b/doc/02-Behavior.md
@@ -0,0 +1,101 @@
+Behavior
+========
+
+Top Level View uses additional status logic for it's views.
+
+This does not affect the overall status behavior of Icinga 2 or Icinga Web 2,
+but it is important to understand the differences.
+
+## Worst status on top
+
+The main responsibility of TLV is to show you the worst status on top.
+
+Worst status is defined in the following order:
+
+* critical_unhandled
+* warning_unhandled
+* unknown_unhandled
+* critical_handled
+* warning_handled
+* unknown_handled
+* ok
+* downtime_handled
+* missing
+
+In addition counter badges will present you indepth details over the
+status below a tile or tree element.
+
+Similar to Icinga Web 2 you can easily see unhandled problems by the strength of color.
+
+![Unhandled problems](screenshots/colors-unhandled.png)
+![Handled problems](screenshots/colors-handled.png)
+
+## SOFT states
+
+While the normal monitoring views will always show you all current states,
+the Top Level Views will only show hard states.
+
+Which means, as long as the object doesn't have reached a hard state, the
+node should be OK and green.
+
+## Handled and Unhandled
+
+Icinga Web 2 introduced an handled state to every host and service.
+
+By default handled would be true if:
+
+* Problem has been acknowledged
+* Object is in downtime
+
+In Top Level View, a few things are different:
+
+* Downtimes are handled special (see next topic)
+* Notification settings can influence a status (see next topic)
+* Flapping means the state is handled
+
+## Downtime and Notification Periods 
+
+Since downtime and notification settings are essential for alerting,
+Top Level Views tries to integrate these into its status logic.
+
+The following behaviors will trigger the downtime logic:
+
+* Host or Service is in an active downtime
+* Notifications are disabled for the host or service
+* Host or Service is out of its notification period
+
+If those conditions are met:
+
+* TLV counts the service as `downtime_active`
+* TLV ignored non-OK states and marks them as `downtime_handled`
+
+## Additional Features
+
+Some features can be enabled by view, and control some additional behavior.
+
+### Host always handled
+
+Option `host_never_unhandled`
+ 
+Every host problem is set to unhandled by default.
+
+This helps when alerting is mostly based on service states, and the host
+is only a container.
+
+This was a behavior of the old Top Level View, and is enabled on convert.  
+
+### Enabling notification period
+
+Option `notification_periods`
+
+Checks the configured notification_period and handles "out of period" as downtime active state.
+
+This was a behavior of the old Top Level View, and is enabled on convert.  
+
+Also see [limitations](90-Limits.md) for this setting.
+
+### Ignoring certain notification periods
+
+Option `ignored_notification_periods`
+
+This notification periods will be ignored for "out of period" checking, see above.
diff --git a/doc/10-User-Guide.md b/doc/10-User-Guide.md
new file mode 100644
index 0000000..29d7917
--- /dev/null
+++ b/doc/10-User-Guide.md
@@ -0,0 +1,65 @@
+User Guide
+==========
+
+This guide wants to help you understand the basic usage of the module.
+And how to access its data quickly.
+
+To understand the status behavior, see the [chapter about behavior](02-Behavior.md).
+
+## Finding problems
+
+Unhandled problems can be identified based on color saturation of the tiles.
+
+In addition counters show you how many states of what kind lay below.  
+
+![Unhandled colors](screenshots/colors-unhandled.png)
+
+![Handled colors](screenshots/colors-handled.png)
+
+## Drilling down
+
+When you click on tiles in the topmost tile view, you drill down into a
+tree view of that tile.
+
+The tree view is collapsing everything that is in an OK state. So you the
+problems first.
+
+![](screenshots/tiles-tree-problems.png)
+
+In this view everything can be expanded via the arrow handle or a click
+on the title area.
+
+Deeper branches can be opened in a new view by clicking on the title text, but
+this is only needed to filter the shown data.
+
+Every Icinga status object, a host, service or hostgroup is a single tile
+here.
+
+Counters are meant to give you an indication about how many problems, or
+even objects are there. 
+
+## Viewing Icinga details
+
+By clicking on an Icinga tile you get dropped into the Monitoring module,
+which allows you to see all details and interact with the object (e.g. for
+acknowledging the problem).
+
+Clicking on a service ![tile](screenshots/tile-service.png) will bring you
+service detail view, same goes for hosts.
+
+![](screenshots/tree-service.png)
+
+The hostgroup ![tile](screenshots/tile-hostgroup.png) gives 2 options,
+default will take you to a service overview for that hostgroup, sorted by problems.
+
+While clicking on the `X hosts` link in the tile brings you an overview
+over hosts in that group.
+
+![](screenshots/tree-hostgroup.png)
+
+## Note about caching
+
+Please be aware that the data display in Top Level View is cached, for 60
+seconds by default.
+
+Latest state changes will only be reflected after that caching time.
diff --git a/doc/20-Editor.md b/doc/20-Editor.md
new file mode 100644
index 0000000..28dd5c2
--- /dev/null
+++ b/doc/20-Editor.md
@@ -0,0 +1,26 @@
+Config Editor
+=============
+
+The module ships a very basic configuration editor,
+which allows to to edit the bare YAML configuration within the web interface.
+
+Please also see the [chapter on config format](21-Config-Format.md).
+
+## Saving
+
+You have 2 options on saving:
+
+* Save to session - so you can test and review your edit
+* Save to disk - it is stored to disk and visible for everyone
+
+When you have saved changes to your session, but not yet disk, the interface
+reminds you of that.
+
+Also you can cancel an edit with a button below the editor, and return to disk state.
+
+## History
+
+Config history is saved to disk, so it can be restored manually. 
+But there is not interface yet.
+
+See `/etc/icingaweb2/modules/toplevelview/views/<name>/*.yml`.
diff --git a/doc/21-Config-Format.md b/doc/21-Config-Format.md
new file mode 100644
index 0000000..33236e5
--- /dev/null
+++ b/doc/21-Config-Format.md
@@ -0,0 +1,192 @@
+Configuration Format
+====================
+
+The configuration format is based on YAML.
+
+    YAML is a human friendly data serialization standard for all programming languages.
+
+It is an easy way to define data in a hierarchy, and still being able to view and modify it as a human.
+
+For details on the format see [yaml.org](http://yaml.org/).
+
+The configuration is structured in a hierarchical object structure like:
+
+    root object -> children (array) -> objects -> more children 
+
+Every node is unique in the tree, but names can be repeated. An Icinga objects can be inserted multiple times.
+
+## Example
+
+Best to understand it is to start with an example.
+
+```yaml
+name: View Name
+children:
+- name: Section 1
+  children:
+  - name: Tile 1
+    children:
+    - host: localhost
+    - host: localhost
+      service: disk
+    - host: localhost
+      service: ssh
+  - name: Tile 2
+    - hostgroup: linux-servers
+  - name: Tile 3
+- name: Section 2
+  - name: Tile 1
+  - name: Tile 2
+  - name: 'Tile 3: The return of long names' # some values should be quoted
+```
+
+## Layers
+
+The first three layers have a special meaning for the view.
+
+1. Root Node - defines the name of the view
+2. Sections - defines the sections in the tile view
+3. Tiles - builds tiles in the tile view
+
+Everything below is only visible via the tree view, and every Icinga node should be below the 3rd level.
+
+## Nodes
+
+Every node is an object in YAML, while the object attribute `children` is an array of all children objects
+for that node.
+
+Indention does matter as far as it defines the levels and structure of the objects. (Please use no soft tabs!)
+
+Every node can have multiple attributes, they are partially validated, and unknown keys just get ignored.
+
+### Name nodes
+
+Default node type is a simple named node that gets status from deeper nodes.
+
+The root node itself has also only a name, but can contain options mentioned below.
+
+Attributes:
+* `name: Test` user readable name of the object
+
+### Icinga Host
+
+Brings in the host state of an individual Icinga host.
+
+Attributes:
+* `host: localhost` hostname in Icinga
+* `type: host` (optional - detected by key attribute)
+
+### Icinga Service
+
+Brings in the service state of an individual Icinga service.
+
+Attributes:
+* `host: localhost` hostname in Icinga
+* `service: servicename` servicename in Icinga
+* `type: service` (optional - detected by key attribute)
+
+### Icinga Hostgroup
+
+Brings in the hostgroup summary state.
+
+Attributes:
+* `hostgroup: linux-servers` hostname in Icinga
+* `type: hostgroup` (optional - detected by key attribute)
+
+## Options
+
+Additional options are available to control status behavior of
+the respective view.
+
+* `host_never_unhandled` (boolean) Controls the host not being displayed as an unhandled problem. See [behavior](02-Behavior.md#host-always-handled) (Default: false)
+* `notification_periods` (boolean) Controls checking notification_period to be in_period. See [behavior](02-Behavior.md#enabling-notification-period) (Default: false)
+
+These options are just set on the root node:
+
+```yaml
+name: Test Config with Options
+host_never_unhandled: true
+children:
+- name: Section 1
+```
+
+## Examples
+
+Here is a longer example from a testing configuration
+
+```yaml
+name: Test
+children:
+- name: Single Objects
+  children:
+  - name: OK
+    children:
+    - host: host_ok
+    - host: host_ok
+      service: s_ok
+    - host: host_s_soft
+    - host: host_s_soft
+      service: s_critical_soft
+  - name: DOWN
+    children:
+    - host: host_down
+    - host: host_down
+      service: s_critical
+  - name: CRITICAL
+    children:
+    - host: host_s_critical
+    - host: host_s_critical
+      service: s_critical
+  - name: WARNING
+    children:
+    - host: host_s_warning
+    - host: host_s_warning
+      service: s_warning
+- name: Single Objects Handled
+  children:
+  - name: CRITICAL handled
+    children:
+    - host: host_s_critical_handled
+    - host: host_s_critical_handled
+      service: s_critical_handled
+  - name: WARNING handled
+    children:
+    - host: host_s_warning_handled
+    - host: host_s_warning_handled
+      service: s_warning_handled
+- name: Hostgroups
+  children:
+  - name: OK
+    children:
+    - hostgroup: HG_OK
+    - hostgroup: HG_SOFT
+  - name: DOWN
+    children:
+    - hostgroup: HG_DOWN
+  - name: CRITICAL
+    children:
+    - hostgroup: HG_CRITICAL
+  - name: WARNING
+    children:
+    - hostgroup: HG_WARNING
+- name: TLV Missing
+  children:
+  - name: Partially missing
+    children:
+    - host: host_ok
+    - name: missing
+  - name: Missing with problems
+    children:
+    - host: host_down
+    - name: missing
+  - name: Missing with handled
+    children:
+    - host: host_down_handled
+    - name: missing
+  - name: Empty
+    children:
+    - name: nothing here
+  - name: Notexisting Object
+    children:
+    - host: notexisting
+```
\ No newline at end of file
diff --git a/doc/90-Limits.md b/doc/90-Limits.md
new file mode 100644
index 0000000..60dc2c7
--- /dev/null
+++ b/doc/90-Limits.md
@@ -0,0 +1,27 @@
+Limits of this module
+=====================
+
+A few notes about compatibility to Icinga 2.
+
+## Notification Period
+
+Currently Icinga 2 does not publish `notification_period` to the IDO, due
+to the new notification logic.
+
+When `notification_period` is `NULL`, TLV will treat the object as **in period**
+to avoid problems here.
+
+This feature is disabled by default, see [config format](21-Config-Format.md#options) and
+[behavior](02-Behavior.md#enabling-notification-period).
+
+### Period ranges in Icinga 2
+
+The publishing of the individual ranges is buggy in Icinga 2 and can not be used here!
+
+See [Icinga2 #4659](https://github.com/Icinga/icinga2/issues/4659).
+
+### Period ranges in general
+
+Not all types of ranges are published to IDO.
+
+**Only the very basic range type is supported:** Weekday start and end time
diff --git a/doc/91-Custom-Styling.md b/doc/91-Custom-Styling.md
new file mode 100644
index 0000000..f9bb494
--- /dev/null
+++ b/doc/91-Custom-Styling.md
@@ -0,0 +1,48 @@
+Custom Styling
+==============
+
+With a custom theme you can change style and colors of the Top Level View.
+
+Here are a few examples.
+
+## Blinking unhandled
+
+So that unhandled problems are more visible.
+
+```less
+.container.icinga-module.module-toplevelview {
+  .tlv-status-tile.unhandled {
+    animation: blinker 1.5s linear infinite;
+  }
+}
+
+@keyframes blinker {
+  50% {
+    opacity: 0.2;
+  }
+}
+```
+
+## Dark fullscreen
+
+When you open the TLV in fullscreen mode, background will be dark.
+
+```less
+.fullscreen-layout {
+  .container.icinga-module.module-toplevelview {
+    color: #eee;
+    a:visited {
+      color: inherit;
+    }
+    background: #333;
+
+    .controls {
+      background: inherit;
+
+      .active {
+        color: #333;
+      }
+    }
+  }
+}
+```
diff --git a/doc/99-Screenshots.md b/doc/99-Screenshots.md
new file mode 100644
index 0000000..04a7cda
--- /dev/null
+++ b/doc/99-Screenshots.md
@@ -0,0 +1,30 @@
+Screenshots
+===========
+
+Tile view with lots of objects:
+
+![](screenshots/tiles.png)
+
+Tile and Tree view with problems:
+
+![](screenshots/tiles-tree-problems.png)
+
+Tree view with no problems (all collapsed):
+
+![](screenshots/tiles-tree-noproblems.png)
+
+Tree view with no problems (expanded by user):
+
+![](screenshots/tiles-tree-noproblems-expanded.png)
+
+Tree view problems on a hostgroup, and the hostgroup details:
+
+![](screenshots/tree-hostgroup.png)
+
+Tree view problems on services, and the service details:
+
+![](screenshots/tree-service.png)
+
+Overview over all defined views, and the open editor:
+
+![](screenshots/overview-and-editor.png)
diff --git a/doc/screenshots/colors-handled.png b/doc/screenshots/colors-handled.png
new file mode 100644
index 0000000..2256dd7
--- /dev/null
+++ b/doc/screenshots/colors-handled.png
diff --git a/doc/screenshots/colors-unhandled.png b/doc/screenshots/colors-unhandled.png
new file mode 100644
index 0000000..5becad5
--- /dev/null
+++ b/doc/screenshots/colors-unhandled.png
diff --git a/doc/screenshots/overview-and-editor.png b/doc/screenshots/overview-and-editor.png
new file mode 100644
index 0000000..e81a203
--- /dev/null
+++ b/doc/screenshots/overview-and-editor.png
diff --git a/doc/screenshots/tile-hostgroup.png b/doc/screenshots/tile-hostgroup.png
new file mode 100644
index 0000000..d8e9ca5
--- /dev/null
+++ b/doc/screenshots/tile-hostgroup.png
diff --git a/doc/screenshots/tile-service.png b/doc/screenshots/tile-service.png
new file mode 100644
index 0000000..adee05d
--- /dev/null
+++ b/doc/screenshots/tile-service.png
diff --git a/doc/screenshots/tiles-tree-noproblems-expanded.png b/doc/screenshots/tiles-tree-noproblems-expanded.png
new file mode 100644
index 0000000..5ec6c9d
--- /dev/null
+++ b/doc/screenshots/tiles-tree-noproblems-expanded.png
diff --git a/doc/screenshots/tiles-tree-noproblems.png b/doc/screenshots/tiles-tree-noproblems.png
new file mode 100644
index 0000000..b3e1145
--- /dev/null
+++ b/doc/screenshots/tiles-tree-noproblems.png
diff --git a/doc/screenshots/tiles-tree-problems.png b/doc/screenshots/tiles-tree-problems.png
new file mode 100644
index 0000000..921a700
--- /dev/null
+++ b/doc/screenshots/tiles-tree-problems.png
diff --git a/doc/screenshots/tiles.png b/doc/screenshots/tiles.png
new file mode 100644
index 0000000..e94557f
--- /dev/null
+++ b/doc/screenshots/tiles.png
diff --git a/doc/screenshots/tree-hostgroup.png b/doc/screenshots/tree-hostgroup.png
new file mode 100644
index 0000000..6d327f2
--- /dev/null
+++ b/doc/screenshots/tree-hostgroup.png
diff --git a/doc/screenshots/tree-service.png b/doc/screenshots/tree-service.png
new file mode 100644
index 0000000..ae185f6
--- /dev/null
+++ b/doc/screenshots/tree-service.png