Modules

Installation

A module should be installed in one of the configured module paths. The default path in most installations is /usr/share/icingaweb2/modules.

Each directory in there contains the files for a particular module. The directory’s name has to be the one that is provided by the module’s documentation. If there is none provided, it is usually the name of the module in all lowercase. Some modules may use a name prefixed with icingaweb2-module-. If this is the case, the directory’s name should be that, but without the prefix. (e.g. icingaweb2-module-map turns into /usr/share/icingaweb2/modules/map)

Note:

Remember to ensure that your web-server can access those files. Though, read permission only.

Once a module’s files are in place, it needs to be enabled first before it can be used. This can either be done in the UI at Configuration -> Modules or by using the icingacli: icingacli module enable map

In order for other non-admin users to access the module’s functionality, it is required to permit access first. This is done by granting the permission module/<module-name>. (e.g. module/map)

Module Specific Instructions

A module may require further installation steps. Whether these need to be performed before enabling the module, should be provided by the module’s documentation. In any case, don’t forget to apply these as well, otherwise the module will most likely not function correctly.

Examples

There are sample installation instructions provided for your convenience:

Sample Tarball installation

MODULE_NAME="map"
MODULE_VERSION="v1.1.0"
MODULE_AUTHOR="nbuchwitz"
MODULES_PATH="/usr/share/icingaweb2/modules"
MODULE_PATH="${MODULES_PATH}/${MODULE_NAME}"
RELEASES="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}/archive"
mkdir "$MODULE_PATH" \
&& wget -q $RELEASES/${MODULE_VERSION}.tar.gz -O - \
   | tar xfz - -C "$MODULE_PATH" --strip-components 1
icingacli module enable "${MODULE_NAME}"

Sample GIT installation

MODULE_NAME="map"
MODULE_VERSION="v1.1.0"
MODULE_AUTHOR="nbuchwitz"
REPO="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}"
MODULES_PATH="/usr/share/icingaweb2/modules"
git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}"
icingacli module enable "${MODULE_NAME}"

Configuration

A module may also require configuration. Most modules provide additional tabs at their configuration page. This is accessible in the UI at Configuration -> Modules. If not, and something isn’t working, check the module’s documentation again for hints.

If you need access to a module’s configuration files directly, they should be in a subdirectory modules of Icinga Web 2’s configuration directory. That is usually /etc/icingaweb2/modules. Each directory in there should be named the same as its installation path. (e.g. /etc/icingaweb2/modules/map)