diff options
Diffstat (limited to 'doc')
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 (>= 2.4.1) +* PHP (>= 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` -> `Modules`... + + + +...choose the `map` module and `enable` it: + + + +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. + + + + +## 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. + + + + +## 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: + + + +## 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. + + + +By clicking on the icon, the cluster expands and the underlying host markers will be visible: + + + +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. + + + +### Control elements + +In the upper left corner of the map there are six control elements: + + + +## 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew file mode 100644 index 0000000..e9f4f2b --- /dev/null +++ b/doc/screenshot/map-module.png |
