Adding upstream version 1.1.0.upstream/1.1.0upstream

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

16 files changed, 265 insertions, 0 deletions

diff --git a/doc/01-Installation.md b/doc/01-Installation.md
new file mode 100644
index 0000000..0841623
--- /dev/null
+++ b/doc/01-Installation.md
@@ -0,0 +1,68 @@
+<a id="Installation"></a>Installation
+=====================================
+
+Requirements
+------------
+
+* Icinga Web 2 (&gt;= 2.4.1)
+* PHP (&gt;= 5.6 or 7.x)
+
+The Icinga Web 2 `monitoring` module needs to be configured and enabled.
+
+Installation from .tar.gz
+-------------------------
+
+Download the latest version and extract it to a folder named `map`
+in one of your Icinga Web 2 module path directories.
+
+You might want to use a script as follows for this task:
+```sh
+ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
+REPO_URL="https://github.com/nbuchwitz/icingaweb2-module-map"
+TARGET_DIR="${ICINGAWEB_MODULEPATH}/map"
+MODULE_VERSION="1.1.0"
+URL="${REPO_URL}/archive/v${MODULE_VERSION}.tar.gz"
+install -d -m 0755 "${TARGET_DIR}"
+wget -q -O - "$URL" | tar xfz - -C "${TARGET_DIR}" --strip-components 1
+```
+
+Installation from GIT repository
+--------------------------------
+
+Another convenient method is the installation directly from our GIT repository.
+Just clone the repository to one of your Icinga Web 2 module path directories.
+It will be immediately ready for use:
+
+```sh
+ICINGAWEB_MODULEPATH="/usr/share/icingaweb2/modules"
+REPO_URL="https://github.com/nbuchwitz/icingaweb2-module-map"
+TARGET_DIR="${ICINGAWEB_MODULEPATH}/map"
+git clone "${REPO_URL}" "${TARGET_DIR}"
+```
+
+You can now directly use our current GIT master or check out a specific version.
+
+Enable the newly installed module
+---------------------------------
+
+Enable the `map` module either on the CLI by running
+
+```sh
+icingacli module enable map
+```
+
+Or go to your Icinga Web 2 frontend, choose `Configuration` -&gt; `Modules`...
+
+![Choose Configuration - Modules](screenshot/01_installation/101_menu-configuration-modules.png)
+
+...choose the `map` module and `enable` it:
+
+![Enable the module](screenshot/01_installation/102_enable-module.png)
+
+It might afterwards be necessary to refresh your web browser to be sure that
+newly provided styling is loaded.
+
+Getting started with the map
+---------------------------------------------
+
+That's it, *Map* is now ready for use. Please read more on [adding markers to your map](02-Add-Items-to-map.md).
diff --git a/doc/02-Add-Items-to-map.md b/doc/02-Add-Items-to-map.md
new file mode 100644
index 0000000..d925db7
--- /dev/null
+++ b/doc/02-Add-Items-to-map.md
@@ -0,0 +1,51 @@
+# Add markers to your map
+
+## Add coordinates to a host object in Icinga 2
+
+Add a custom attribute called `geolocation` to any host you want to display on the map. Its value consists of WGS84 coordinates in the following format:
+
+```
+vars.geolocation = "<latitude>,<longitude>"
+```
+
+In order to highlight the host's coordinate, hold the CTRL key and click on the desired map location. A popup will show you the coordinates of the clicked point in the correct geolocation format, so you could just copy & paste the text.
+
+### Example of a host object
+
+```
+object Host "db-in-la" {
+  check_command = "hostalive"
+  address = "192.168.33.5"
+  vars.geolocation = "34.052234,-118.243685"
+}
+```
+
+Don't forget to reload your icinga2 daemon after adding items to your config.
+
+### Assign coordinates in a more generic way
+
+There is also an [article](https://www.icinga.com/2017/08/16/integrate-maps-into-icinga/) in the icinga blog describing a more automated way of adding coordinates by matching your hostname conventions.
+
+### Assign different marker icons
+
+Add a custom attribute called `map_icon` to an object already having the custom attribute `geolocation`. Its value must be a name of an icon from the iconfont used in Icinga Web 2 which you can find at /icingaweb2/doc/style/font when you enable the doc module.
+
+```
+vars.map_icon = "print"
+```
+
+Markers will look like the following example showing the icons sitemap, flapping and wifi.
+
+![Marker icons](screenshot/02_getting-started/0207_marker-icons.png)
+
+
+## Using the Icinga Director
+
+If you're using the [Icinga Director](https://github.com/icinga/icingaweb2-module-director), you could use the new [mapDatatype](https://github.com/nbuchwitz/icingaweb2-module-mapDatatype) plugin. This plugin enables you to directly selected your coordinates on a map.
+
+![Using the Icinga Director](screenshot/director-plugin.png)
+
+
+## What's next?
+
+After adding the first markers to your map, you wan't to [explore the map](03-Exploring-the-map.md).
diff --git a/doc/03-Exploring-the-map.md b/doc/03-Exploring-the-map.md
new file mode 100644
index 0000000..ac99b08
--- /dev/null
+++ b/doc/03-Exploring-the-map.md
@@ -0,0 +1,99 @@
+# Exploring the map
+
+Once you enable the *Host Map* module, it will pop up in your menu in the ``Maps`` section.
+When you click on it, it will show you a map:
+
+![Map overview](screenshot/02_getting-started/0201_map-overview.png)
+
+## Basic usage
+
+Every host is represented by a colored marker, which indicates the overall host state.
+
+Markers are grouped into clusters, depending on their location and the zoom level. Every cluster marker has a label with the number of clustered markers.
+
+![Clustered map](screenshot/02_getting-started/0202_sub-cluster.png)
+
+By clicking on the icon, the cluster expands and the underlying host markers will be visible:
+
+![Expanded cluster](screenshot/02_getting-started/0203-cluster-expanded.png)
+
+To show more details about a host click on the host marker. If you want to show the host in the detail view of the `monitoring module` just click on the eye icon.
+
+![Marker popup](screenshot/02_getting-started/0204_marker-popup.png)
+
+### Control elements
+
+In the upper left corner of the map there are six control elements:
+ 
+![Control elements](screenshot/02_getting-started/0205_control-elements.png)
+
+## Filtering host objects
+
+The usual icingaweb2 filter syntax can be used to filter the set of hosts being displayed. Filters have to be appended to the url (eg. `?host=web*`)
+
+**Filter examples:**
+
+| Filter expression | Description |
+| ----------------------------------------------------- | ------------ |
+| hostgroup_name=customer1&_host_environment=production | Show all hosts of hostgroup `customer1` of where the custom variable environment is equal to `production` |
+| _host_customer=(max-corp\|icinga)                     | Show all hosts where the custom variable `customer` is set to `max-corp` or `icinga` |
+| host_in_downtime=0&host_acknowledged=0 | Don't show acknowledged or objects in downtime |
+
+
+## Dashboard integration
+
+To add a map widget to a dashboard (or a new one) click on the `Add to dashboard` button as shown above. Any filters which are applied to the current view, are also stored in the dashlet.
+
+
+## Settings
+
+Besides the global map configuration in the module settings, it is possible to override these settings per user or per each map.
+
+The following parameters could be overriden:
+
+| Parameter | 
+| --- |
+| min_zoom |
+| max_zoom |
+| max_native_zoom |
+| disable_cluster_at_zoom |
+| default_zoom |
+| default_long |
+| default_lat |
+| stateType |
+| cluster_problem_count |
+| tile_url |
+
+Hierarchy: ``Module Config < User Config < Map Config``
+
+### Map specific overrides
+
+All config parameters above could be changed for the specific map by adding it to the URL. Use the ampersand sign for concatenation of multiple parameters.
+
+Example: ``/icingaweb2/map?default_zoom=20&default_long=13.370324&default_lat=52.500859``
+
+### User specific overrides
+
+The way in which a user-specific configuration can be stored depends on how Icinga Web 2 manages its configuration.
+
+#### File
+
+Add a new section named ``map`` to your users Icinga Web 2 configuration (``/etc/icingaweb2/preferences/<USERNAME>/config.ini``) and put in the parameters you would like to override.
+
+#### Database
+
+You need to manually insert an entry in the users database configuration for each parameter you'd like to change:
+
+```sql
+insert into icingaweb_user_preference values ("USER", "map", "default_zoom", 5, "2018-08-23 08:52:19", "2018-08-23 08:52:19");
+insert into icingaweb_user_preference values ("USER", "map", "default_lat", "29.87", "2018-08-23 08:52:19", "2018-08-23 08:52:19");
+insert into icingaweb_user_preference values ("USER", "map", "default_long", "-88.90", "2018-08-23 08:52:19", "2018-08-23 08:52:19");
+```
+
+### Disable clustering
+In some environments it is desired not to cluster the markers.
+The cluster function can be deactivated with the configuration option ``disable_cluster_at_zoom``, either at a certain zoom level (e.g. ``disable_cluster_at_zoom=10`` or completely (``disable_cluster_at_zoom=1``)
+
+### Show number of problems instead of totals
+
+Set ``cluster_problem_count`` to ``1`` to show the number of problems in the cluster instead of the marker count.
\ No newline at end of file
diff --git a/doc/04-Filter.md b/doc/04-Filter.md
new file mode 100644
index 0000000..44501db
--- /dev/null
+++ b/doc/04-Filter.md
@@ -0,0 +1,47 @@
+# Filter Map Object
+
+The map module allows you to filter objects by using the Icinga Web 2 filter syntax.
+
+## Special Filters
+
+### objectType
+
+This filter could be used to show only hosts, services or both object types.
+
+**Example URL:** ``/icingaweb2/map?objectType=host``
+
+**Allows values:** 
+
+| Values | Description |
+| ------ | ----------- |
+| ``all`` | Show both (hosts & services) on the map |
+| ``host`` | Show only hosts on the map |
+| ``service`` | Show only services on the map |
+
+### problems
+
+If you only want to see hosts or services with states distinct from ``OK``, use this filter.
+
+**Example URL:** ``/icingaweb2/map?problems``
+
+
+## Filtering host objects
+
+The usual icingaweb2 filter syntax can be used to filter the set of hosts being displayed. Filters have to be appended to the url (eg. `?host=web*`)
+
+**Filter examples:**
+
+| Filter expression | Description |
+| ----------------------------------------------------- | ------------ |
+| hostgroup_name=customer1&_host_environment=production | Show all hosts of hostgroup `customer1` of where the custom variable environment is equal to `production` |
+| _host_customer=(max-corp\|icinga)                     | Show all hosts where the custom variable `customer` is set to `max-corp` or `icinga` |
+
+### Change default parameters
+
+It's possible to change the parameters ``default_zoom``, ``default_long`` and ``default_lat`` for a map by adding the parameters to the url:
+
+```map?default_zoom=20&default_long=13.370324&default_lat=52.500859```
+
+## Dashboard integration
+
+To add a map widget to a dashboard (or a new one) click on the `Add to dashboard` button as shown above. Any filters which are applied to the current view, are also stored in the dashlet.
diff --git a/doc/screenshot/01_installation/101_menu-configuration-modules.png b/doc/screenshot/01_installation/101_menu-configuration-modules.png
new file mode 100644
index 0000000..a7ab5ad
--- /dev/null
+++ b/doc/screenshot/01_installation/101_menu-configuration-modules.png
diff --git a/doc/screenshot/01_installation/102_enable-module.png b/doc/screenshot/01_installation/102_enable-module.png
new file mode 100644
index 0000000..2c421f6
--- /dev/null
+++ b/doc/screenshot/01_installation/102_enable-module.png
diff --git a/doc/screenshot/02_getting-started/0201_map-overview.png b/doc/screenshot/02_getting-started/0201_map-overview.png
new file mode 100644
index 0000000..51e7eec
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0201_map-overview.png
diff --git a/doc/screenshot/02_getting-started/0202_sub-cluster.png b/doc/screenshot/02_getting-started/0202_sub-cluster.png
new file mode 100644
index 0000000..6a876d5
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0202_sub-cluster.png
diff --git a/doc/screenshot/02_getting-started/0203-cluster-expanded.png b/doc/screenshot/02_getting-started/0203-cluster-expanded.png
new file mode 100644
index 0000000..c62530c
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0203-cluster-expanded.png
diff --git a/doc/screenshot/02_getting-started/0204_marker-popup.png b/doc/screenshot/02_getting-started/0204_marker-popup.png
new file mode 100644
index 0000000..57bc67e
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0204_marker-popup.png
diff --git a/doc/screenshot/02_getting-started/0205_control-elements.png b/doc/screenshot/02_getting-started/0205_control-elements.png
new file mode 100644
index 0000000..3b83c63
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0205_control-elements.png
diff --git a/doc/screenshot/02_getting-started/0206-split-window.png b/doc/screenshot/02_getting-started/0206-split-window.png
new file mode 100644
index 0000000..20a7b3c
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0206-split-window.png
diff --git a/doc/screenshot/02_getting-started/0207_marker-icons.png b/doc/screenshot/02_getting-started/0207_marker-icons.png
new file mode 100644
index 0000000..597e0fc
--- /dev/null
+++ b/doc/screenshot/02_getting-started/0207_marker-icons.png
diff --git a/doc/screenshot/dashlets.png b/doc/screenshot/dashlets.png
new file mode 100644
index 0000000..23c1968
--- /dev/null
+++ b/doc/screenshot/dashlets.png
diff --git a/doc/screenshot/director-plugin.png b/doc/screenshot/director-plugin.png
new file mode 100644
index 0000000..08a1df8
--- /dev/null
+++ b/doc/screenshot/director-plugin.png
diff --git a/doc/screenshot/map-module.png b/doc/screenshot/map-module.png
new file mode 100644
index 0000000..e9f4f2b
--- /dev/null
+++ b/doc/screenshot/map-module.png