tyler.durden
/
icingaweb2
mirror of https://github.com/Icinga/icingaweb2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: Introduce modules chapter

This commit is contained in:
Johannes Meyer 2021-04-12 13:06:04 +02:00
parent 95e20d443c
commit 75cd997f06
1 changed files with 69 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
doc/08-Modules.md Normal file
View File

@ -0,0 +1,69 @@
# Modules
## Installation
A module should be installed in one of the [configured module paths](03-Configuration.md#general-configuration).
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**
```sh
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**
```sh
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`)