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

Merge pull request #4348 from Icinga/feature/add-basic-module-documentation 

Add basic module documentation
This commit is contained in:
Johannes Meyer 2021-04-13 09:48:27 +02:00 committed by GitHub
parent 95e20d443c 184e37390f
commit 7fd7efceb4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 97 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
doc/01-About.md
View File

@ -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 <a id="about-monitoring"></a>
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 <a id="about-installation"></a>
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 <a id="about-documentation"></a>
## 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 <a id="about-monitoring"></a>
> **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 <a id="about-documentation"></a>
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 <a id="about-translation"></a>
### Translation <a id="about-translation"></a>
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.

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`)