diff --git a/doc/01-About.md b/doc/01-About.md index 01965f9cb..19b614949 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -3,19 +3,6 @@ Icinga Web 2 is a powerful PHP framework for web applications that comes in a clean and reduced design. It's fast, responsive, accessible and easily extensible with modules. -## The monitoring module - -This is the core module for most Icinga Web 2 users. - -It provides an intuitive user interface for monitoring with Icinga 2. -Especially there are lots of list and detail views (e.g. for hosts and services) -you can sort and filter depending on what you want to see. - -You can also control the monitoring process itself by sending external commands to Icinga. -Most such actions (like rescheduling a check) can be done with just a single click. - -More details about this module can be found in [this chapter](../modules/monitoring/doc/01-About.md#monitoring-module-about). - ## Installation Icinga Web 2 can be installed easily from packages from the official package repositories. @@ -55,7 +42,33 @@ They can be stored either in a database or in .ini files. See [here](07-Preferences.md#preferences) for more information about a user's preferences and how to configure their storage type. -## Documentation +## Modules + +Modules extend Icinga Web 2 with additional functionality. They allow the integration of +capabilities into existing views and even other modules. Be it a graph provider such as +[Graphite](https://github.com/Icinga/icingaweb2-module-graphite) or a UI for the Icinga 2 +configuration like the [Director](https://github.com/Icinga/icingaweb2-module-director). + +See [here](08-Modules.md#modules) for information on how to install and configure modules. + +### The monitoring module + +> **Note for Icinga DB Users** +> +> This module is only for the IDO backend. Use [Icinga DB Web](https://github.com/Icinga/icingadb-web) instead. + +This is the core module for most Icinga Web 2 users. + +It provides an intuitive user interface for monitoring with Icinga 2. +There are lots of list and detail views (e.g. for hosts and services) +you can sort and filter depending on what you want to see. + +You can also control the monitoring process itself by sending external commands to Icinga. +Most such actions (like rescheduling a check) can be done with just a single click in the UI. + +More details about this module can be found in [this chapter](../modules/monitoring/doc/01-About.md#monitoring-module-about). + +### Documentation With the documentation module you can read the documentation of the framework (and any module) directly in the user interface. @@ -63,7 +76,7 @@ The module can also export the documentation to PDF. More details about this module can be found in [this chapter](../modules/doc/doc/01-About.md#doc-module-about). -## Translation +### Translation Icinga Web 2 and all modules by Icinga utilize gettext to provide translations into other languages from the default English (en_US). However, the actual language specific files (locales) are not separately included in every project. diff --git a/doc/08-Modules.md b/doc/08-Modules.md new file mode 100644 index 000000000..6c81c5bed --- /dev/null +++ b/doc/08-Modules.md @@ -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/`. (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`)