Merge pull request #2972 from Icinga/feature/enhance-docs-add-missing-bits
Enhance the documentation, add missing bits and fix outdated information
This commit is contained in:
lippserd
GitHub
commit
4cadc90c92
|
|
@ -7,13 +7,15 @@ It's fast, responsive, accessible and easily extensible with modules.
|
|||
|
||||
This is the core module for most Icinga Web 2 users.
|
||||
|
||||
It provides an intuitive user interface for monitoring with Icinga (1 and 2).
|
||||
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.
|
||||
|
|
@ -59,6 +61,8 @@ With the documentation module you can read the documentation of the framework (a
|
|||
|
||||
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>
|
||||
|
||||
With the translation module every piece of text in the user interface (of the framework itself and any module) can be translated to a language of your choice.
|
||||
|
|
@ -68,3 +72,5 @@ Currently provided languages:
|
|||
* German
|
||||
* Italian
|
||||
* Portuguese
|
||||
|
||||
More details about this module can be found in [this chapter](../modules/translation/doc/01-About.md#translation-module-about).
|
||||
|
|
|
|||
|
|
@ -12,14 +12,13 @@ chapter.
|
|||
|
||||
## Installing Requirements <a id="installing-requirements"></a>
|
||||
|
||||
* A web server, e.g. Apache or nginx
|
||||
* PHP >= 5.3.0 w/ gettext, intl, mbstring and OpenSSL support
|
||||
* [Icinga 2](https://www.icinga.com/products/icinga-2/) with the IDO database backend (MySQL or PostgreSQL)
|
||||
* A web server, e.g. Apache or Nginx
|
||||
* PHP >= 5.3.0 with gettext, intl, mbstring and OpenSSL support
|
||||
* Default time zone configured for PHP in the php.ini file
|
||||
* LDAP PHP library when using Active Directory or LDAP for authentication
|
||||
* Icinga 2.x w/ IDO feature enabled or Icinga 1.x w/ IDO
|
||||
* The IDO table prefix must be `icinga_` which is the default
|
||||
* MySQL or PostgreSQL PHP libraries
|
||||
* cURL PHP library when using the Icinga 2 API for transmitting external commands
|
||||
* cURL PHP library when using the Icinga 2 API as resource
|
||||
|
||||
|
||||
## Installing Icinga Web 2 from Package <a id="installing-from-package"></a>
|
||||
|
|
@ -139,6 +138,7 @@ apt-get install icingaweb2
|
|||
```
|
||||
yum install icingaweb2 icingacli
|
||||
```
|
||||
|
||||
If you have [SELinux](90-SELinux.md) enabled, the package `icingaweb2-selinux` is also required.
|
||||
For RHEL/CentOS please read the [package repositories notes](02-Installation.md#package-repositories-rhel-notes).
|
||||
|
||||
|
|
@ -188,6 +188,12 @@ You may also create a separate administrative account with all privileges instea
|
|||
Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation:
|
||||
`/icingaweb2/setup`.
|
||||
|
||||
Note for Debian: Use the same database, user and password details created above when asked.
|
||||
> **Note for Debian**
|
||||
>
|
||||
> Use the same database, user and password details created above when asked.
|
||||
|
||||
The setup wizard automatically detects the required packages. In case one of them is missing,
|
||||
e.g. a PHP module, please install the package, restart your webserver and reload the setup page.
|
||||
|
||||
If you have SELinux enabled, please ensure to either have the selinux package for Icinga Web 2
|
||||
installed, or disable it.
|
||||
|
|
|
|||
|
|
@ -3,13 +3,75 @@
|
|||
## Overview <a id="configuration-overview"></a>
|
||||
|
||||
Apart from its web configuration capabilities, the local configuration is
|
||||
stored in `/etc/icingaweb2` by default (depending on your config setup).
|
||||
stored in `/etc/icingaweb2` by default (depending on your configuration setup).
|
||||
|
||||
| File/Directory | Description/Purpose |
|
||||
| ------------------------------------------------- | ------------------- |
|
||||
| **config.ini** | general configuration (logging, preferences, etc.) |
|
||||
| [**resources.ini**](04-Resources.md) | global resources (Icinga Web 2 database for preferences and authentication, Icinga IDO database) |
|
||||
| **roles.ini** | user specific roles (e.g. `administrators`) and permissions |
|
||||
| [**authentication.ini**](05-Authentication.md) | authentication backends (e.g. database) |
|
||||
| **enabledModules** | contains symlinks to enabled modules |
|
||||
| **modules** | directory for module specific configuration |
|
||||
File/Directory | Description
|
||||
------------------------------------------------------- | ---------------------------------
|
||||
[config.ini](03-Configuration.md#configuration-general) | General configuration (global, logging, themes, etc.)
|
||||
[resources.ini](04-Resources.md#resources) | Global resources (Icinga Web 2 database for preferences and authentication, Icinga 2 IDO database)
|
||||
[roles.ini](06-Security.md#security-roles) | User specific roles (e.g. `administrators`) and permissions
|
||||
[authentication.ini](05-Authentication.md) | Authentication backends (e.g. database)
|
||||
enabledModules | Symlinks to enabled modules
|
||||
modules | Directory for module specific configuration
|
||||
|
||||
|
||||
## General Configuration <a id="configuration-general"></a>
|
||||
|
||||
Navigate into **Configuration > Application > General **.
|
||||
|
||||
This configuration is stored in the `config.ini` file in `/etc/icingaweb2`.
|
||||
|
||||
### Global Configuration <a id="configuration-general-global"></a>
|
||||
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
show\_stacktraces | **Optional.** Whether to show debug stacktraces. Defaults to `0`.
|
||||
module\_path | **Optional.** Specifies the directories where modules can be installed. Multiple directories must be separated with colons.
|
||||
config\_backend | **Optional.** Select the user preference storage. Can be set to `ini` (default), `db` or `none`. If `db` is selected, this requires the `config_resource` attribute.
|
||||
config\_resource | **Optional.** Specify a defined [resource](04-Resources.md#resources-configuration-database) name. Can only be used if `config_backend` is set to `db`.
|
||||
|
||||
|
||||
Example for storing the user preferences in the database resource `icingaweb_db`:
|
||||
|
||||
```
|
||||
[global]
|
||||
show_stacktraces = "0"
|
||||
config_backend = "db"
|
||||
config_resource = "icingaweb_db"
|
||||
module_path = "/usr/share/icingaweb2/modules"
|
||||
```
|
||||
|
||||
### Logging Configuration <a id="configuration-general-logging"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
log | **Optional.** Specifies the logging type. Can be set to `syslog`, `file` or `none`.
|
||||
level | **Optional.** Specifies the logging level. Can be set to `ERROR`, `WARNING`, `INFORMATION` or `DEBUG`.
|
||||
file | **Optional.** Specifies the log file path if `log` is set to `file`.
|
||||
application | **Optional.** Specifies the application name if `log` is set to `syslog`.
|
||||
facility | **Optional.** Specifies the syslog facility if `log` is set to `syslog`. Can be set to `user`, `local0` to `local7`. Defaults to `user`.
|
||||
|
||||
Example for more verbose debug logging into a file:
|
||||
|
||||
```
|
||||
[logging]
|
||||
log = "file"
|
||||
level = "DEBUG"
|
||||
file = "/usr/share/icingaweb2/log/icingaweb2.log"
|
||||
```
|
||||
|
||||
### Theme Configuration <a id="configuration-general-theme"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
theme | **Optional.** Choose the theme. Can be set to `Icinga`, `high-contrast`, `Winter` or your own installed theme. Defaults to `Icinga`. Note that this setting is case-sensitive because it refers to the filename of the theme.
|
||||
disabled | **Optional.** Set this to `1` if users should not be allowed to change their theme. Defaults to `0`.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
[themes]
|
||||
disabled = "1"
|
||||
theme = "Icinga"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,34 +1,49 @@
|
|||
# Resources <a id="resources"></a>
|
||||
|
||||
The configuration file `config/resources.ini` contains information about data sources that can be referenced in other
|
||||
The configuration file `resources.ini` contains information about data sources that can be referenced in other
|
||||
configuration files. This allows you to manage all data sources at one central place, avoiding the need to edit several
|
||||
different files, when the information about a data source changes.
|
||||
different files when the information about a data source changes.
|
||||
|
||||
## Configuration <a id="resources-configuration"></a>
|
||||
|
||||
Each section in `config/resources.ini` represents a data source with the section name being the identifier used to
|
||||
Each section in `resources.ini` represents a data source with the section name being the identifier used to
|
||||
reference this specific data source. Depending on the data source type, the sections define different directives.
|
||||
The available data source types are *db*, *ldap*, *ssh* and *livestatus* which will described in detail in the following
|
||||
The available data source types are `db`, `ldap` and `ssh` which will described in detail in the following
|
||||
paragraphs.
|
||||
|
||||
Type | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
db | A [database](04-Resources.md#resources-configuration-database) resource (e.g. Icinga 2 DB IDO or Icinga Web 2 user preferences)
|
||||
ldap | An [LDAP](04-Resources.md#resources-configuration-ldap) resource for authentication.
|
||||
ssh | Manage [SSH](04-Resources.md#resources-configuration-ssh) keys for remote access (e.g. command transport).
|
||||
|
||||
|
||||
### Database <a id="resources-configuration-database"></a>
|
||||
|
||||
A Database resource defines a connection to a SQL databases which can contain users and groups
|
||||
to handle authentication and authorization, monitoring data or user preferences.
|
||||
A Database resource defines a connection to a SQL database which
|
||||
can contain users and groups to handle authentication and authorization, monitoring data or user preferences.
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
type | **Required.** Specifies the resource type. Must be set to `db`.
|
||||
db | **Required.** Database type. In most cases `mysql` or `pgsql`.
|
||||
host | **Required.** Connect to the database server on the given host. For using unix domain sockets, specify `localhost` for MySQL and the path to the unix domain socket directory for PostgreSQL.
|
||||
port | **Required.** Port number to use. MySQL defaults to `3306`, PostgreSQL defaults to `5432`. Mandatory for connections to a PostgreSQL database.
|
||||
username | **Required.** The database username.
|
||||
password | **Required.** The database password.
|
||||
dbname | **Required.** The database name.
|
||||
charset | **Optional.** The character set for the database connection.
|
||||
ssl\_cert | **Optional.** The file path to the SSL certificate. Only available for the `mysql` database.
|
||||
ssl\_key | **Optional.** The file path to the SSL key. Only available for the `mysql` database.
|
||||
ssl\_ca | **Optional.** The file path to the SSL certificate authority. Only available for the `mysql` database.
|
||||
ssl\_capath | **Optional.** The file path to the directory that contains the trusted SSL CA certificates, which are stored in PEM format.Only available for the `mysql` database.
|
||||
ssl\_cipher | **Optional.** A list of one or more permissible ciphers to use for SSL encryption, in a format understood by OpenSSL. For example: `DHE-RSA-AES256-SHA:AES128-SHA`. Only available for the `mysql` database.
|
||||
|
||||
| Directive | Description |
|
||||
| ------------- | ----------- |
|
||||
| **type** | `db` |
|
||||
| **db** | Database management system. In most cases `mysql` or `pgsql`. |
|
||||
| **host** | Connect to the database server on the given host. For using unix domain sockets, specify `localhost` for MySQL and the path to the unix domain socket directory for PostgreSQL. |
|
||||
| **port** | Port number to use. Mandatory for connections to a PostgreSQL database. |
|
||||
| **username** | The username to use when connecting to the server. |
|
||||
| **password** | The password to use when connecting to the server. |
|
||||
| **dbname** | The database to use. |
|
||||
| **charset** | The character set to use for the database connection. |
|
||||
|
||||
#### Example <a id="resources-configuration-database-example"></a>
|
||||
|
||||
The name in brackets defines the resource name.
|
||||
|
||||
```
|
||||
[icingaweb-mysql-tcp]
|
||||
type = db
|
||||
|
|
@ -59,20 +74,23 @@ dbname = icingaweb
|
|||
|
||||
### LDAP <a id="resources-configuration-ldap"></a>
|
||||
|
||||
A LDAP resource represents a tree in a LDAP directory. LDAP is usually used for authentication and authorization.
|
||||
A LDAP resource represents a tree in a LDAP directory.
|
||||
LDAP is usually used for authentication and authorization.
|
||||
|
||||
| Directive | Description |
|
||||
| ----------------- | ----------- |
|
||||
| **type** | `ldap` |
|
||||
| **hostname** | Connect to the LDAP server on the given host. You can also provide multiple hosts separated by a space. |
|
||||
| **port** | Port number to use for the connection. |
|
||||
| **root_dn** | Root object of the tree, e.g. `ou=people,dc=icinga,dc=org` |
|
||||
| **bind_dn** | The user to use when connecting to the server. |
|
||||
| **bind_pw** | The password to use when connecting to the server. |
|
||||
| **encryption** | Type of encryption to use: `none` (default), `starttls`, `ldaps`. |
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
type | **Required.** Specifies the resource type. Must be set to `ldap`.
|
||||
hostname | **Required.** Connect to the LDAP server on the given host. You can also provide multiple hosts separated by a space.
|
||||
port | **Required.** Port number to use for the connection.
|
||||
root\_dn | **Required.** Root object of the tree, e.g. `ou=people,dc=icinga,dc=org`.
|
||||
bind\_dn | **Required.** The user to use when connecting to the server.
|
||||
bind\_pw | **Required.** The password to use when connecting to the server.
|
||||
encryption | **Optional.** Type of encryption to use: `none` (default), `starttls`, `ldaps`.
|
||||
|
||||
#### Example <a id="resources-configuration-ldap-example"></a>
|
||||
|
||||
The name in brackets defines the resource name.
|
||||
|
||||
```
|
||||
[ad]
|
||||
type = ldap
|
||||
|
|
@ -88,16 +106,17 @@ bind_pw = admin
|
|||
A SSH resource contains the information about the user and the private key location, which can be used for the key-based
|
||||
ssh authentication.
|
||||
|
||||
| Directive | Description |
|
||||
| ----------------- | ----------- |
|
||||
| **type** | `ssh` |
|
||||
| **user** | The username to use when connecting to the server. |
|
||||
| **private_key** | The path to the private key of the user. |
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
type | **Required.** Specifies the resource type. Must be set to `ssh`.
|
||||
user | **Required.** The username to use when connecting to the server.
|
||||
private\_key | **Required.** The path to the private key of the user.
|
||||
|
||||
#### Example <a id="resources-configuration-ssh-example"></a>
|
||||
|
||||
```
|
||||
The name in brackets defines the resource name.
|
||||
|
||||
```
|
||||
[ssh]
|
||||
type = "ssh"
|
||||
user = "ssh-user"
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
# Authentication <a id="authentication"></a>
|
||||
|
||||
**Choosing the Authentication Method**
|
||||
|
||||
With Icinga Web 2 you can authenticate against Active Directory, LDAP, a MySQL or a PostgreSQL database or delegate
|
||||
You can authenticate against Active Directory, LDAP, a MySQL or a PostgreSQL database or delegate
|
||||
authentication to the web server.
|
||||
|
||||
Authentication methods can be chained to set up fallback authentication methods
|
||||
|
|
@ -10,7 +8,9 @@ or if users are spread over multiple places.
|
|||
|
||||
## Configuration <a id="authentication-configuration"></a>
|
||||
|
||||
Authentication methods are configured in the INI file **config/authentication.ini**.
|
||||
Navigate into **Configuration > Application > Authentication **.
|
||||
|
||||
Authentication methods are configured in the `/etc/icingaweb2/authentication.ini` file.
|
||||
|
||||
Each section in the authentication configuration represents a single authentication method.
|
||||
|
||||
|
|
@ -20,9 +20,19 @@ authenticated, the next authentication method will be used.
|
|||
|
||||
## External Authentication <a id="authentication-configuration-external-authentication"></a>
|
||||
|
||||
For delegating authentication to the web server simply add `autologin` to your authentication configuration:
|
||||
Authentication to the web server can be delegated with the `autologin` section
|
||||
which specifies an external backend.
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Must be set to `external`.
|
||||
strip\_username\_regexp | **Optional.** Regular expression to strip off specific user name parts.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/authentication.ini
|
||||
|
||||
[autologin]
|
||||
backend = external
|
||||
```
|
||||
|
|
@ -32,23 +42,24 @@ If your web server is not configured for authentication though, the `autologin`
|
|||
### Example Configuration for Apache and Basic Authentication <a id="authentication-configuration-external-authentication-example"></a>
|
||||
|
||||
The following example will show you how to enable external authentication in Apache
|
||||
using **Basic access authentication**.
|
||||
using basic authentication.
|
||||
|
||||
**Creating Users**
|
||||
#### Create Basic Auth User <a id="authentication-configuration-external-authentication-example-user"></a>
|
||||
|
||||
To create users for **basic access authentication** you can use the tool `htpasswd`. In this example **.http-users** is
|
||||
the name of the file containing the user credentials.
|
||||
You can use the tool `htpasswd` to generate basic authentication credentials. This example writes the
|
||||
user credentials into the `.http-users` file.
|
||||
|
||||
The following command creates a new file with the user **icingaadmin**. `htpasswd` will prompt you for a password.
|
||||
The following command creates a new file which adds the user `icingaadmin`.
|
||||
`htpasswd` will prompt you for a password.
|
||||
If you want to add more users to the file you have to omit the `-c` switch to not overwrite the file.
|
||||
|
||||
```
|
||||
sudo htpasswd -c /etc/icingaweb2/.http-users icingaadmin
|
||||
```
|
||||
|
||||
**Configuring the Web Server**
|
||||
#### Apache Configuration <a id="authentication-configuration-external-authentication-example-apache"></a>
|
||||
|
||||
Add the following configuration to the **<Directory> Directive** in the **icingaweb.conf** web server
|
||||
Add the following configuration to the `<Directory>` directive in the `icingaweb2.conf` web server
|
||||
configuration file.
|
||||
|
||||
```
|
||||
|
|
@ -60,25 +71,34 @@ Require valid-user
|
|||
|
||||
Restart your web server to apply the changes.
|
||||
|
||||
Example on CentOS 7:
|
||||
|
||||
```
|
||||
systemctl restart httpd
|
||||
```
|
||||
|
||||
## Active Directory or LDAP Authentication <a id="authentication-configuration-ad-or-ldap-authentication"></a>
|
||||
|
||||
If you want to authenticate against Active Directory or LDAP, you have to define a
|
||||
[LDAP resource](04-Resources.md#resources-configuration-ldap) which will be referenced as data source for the
|
||||
Active Directory or LDAP configuration method.
|
||||
If you want to authenticate against Active Directory or LDAP, you have to define an
|
||||
[LDAP resource](04-Resources.md#resources-configuration-ldap).
|
||||
This is referenced as data source for the Active Directory or LDAP configuration method.
|
||||
|
||||
### LDAP <a id="authentication-configuration-ldap-authentication"></a>
|
||||
|
||||
| Directive | Description |
|
||||
| ------------------------- | ----------- |
|
||||
| **backend** | `ldap` |
|
||||
| **resource** | The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources). |
|
||||
| **user_class** | LDAP user class. |
|
||||
| **user_name_attribute** | LDAP attribute which contains the username. |
|
||||
| **filter** | LDAP search filter. |
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Must be set to `ldap`.
|
||||
resource | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
|
||||
user\_class | **Optional.** LDAP user class. Defaults to `inetOrgPerson`.
|
||||
user\_name\_attribute | **Optional.** LDAP attribute which contains the username. Defaults to `uid`.
|
||||
filter | **Optional.** LDAP search filter. Requires `user_class` and `user_name_attribute`.
|
||||
|
||||
**Example:**
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/authentication.ini
|
||||
|
||||
[auth_ldap]
|
||||
backend = ldap
|
||||
resource = my_ldap
|
||||
|
|
@ -87,20 +107,25 @@ user_name_attribute = uid
|
|||
filter = "memberOf=cn=icinga_users,cn=groups,cn=accounts,dc=icinga,dc=org"
|
||||
```
|
||||
|
||||
Note that in case the set *user_name_attribute* holds multiple values it is required that all of its
|
||||
values are unique. Additionally, a user will be logged in using the exact user id used to authenticate
|
||||
with Icinga Web 2 (e.g. an alias) no matter what the primary user id might actually be.
|
||||
If `user_name_attribute` specifies multiple values all of them must be unique.
|
||||
Please keep in mind that a user will be logged in with the exact user id used to authenticate
|
||||
with Icinga Web 2 (e.g. an alias) ignoring the actual primary user id.
|
||||
|
||||
### Active Directory <a id="authentication-configuration-ad-authentication"></a>
|
||||
|
||||
| Directive | Description |
|
||||
| ------------- | ----------- |
|
||||
| **backend** | `msldap` |
|
||||
| **resource** | The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources). |
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Must be set to `msldap`.
|
||||
resource | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
|
||||
user\_class | **Optional.** LDAP user class. Defaults to `user`.
|
||||
user\_name\_attribute | **Optional.** LDAP attribute which contains the username. Defaults to `sAMAccountName`.
|
||||
filter | **Optional.** LDAP search filter. Requires `user_class` and `user_name_attribute`.
|
||||
|
||||
**Example:**
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/authentication.ini
|
||||
|
||||
[auth_ad]
|
||||
backend = msldap
|
||||
resource = my_ad
|
||||
|
|
@ -112,45 +137,89 @@ If you want to authenticate against a MySQL or a PostgreSQL database, you have t
|
|||
[database resource](04-Resources.md#resources-configuration-database) which will be referenced as data source for the database
|
||||
authentication method.
|
||||
|
||||
| Directive | Description |
|
||||
| ------------------------| ----------- |
|
||||
| **backend** | `db` |
|
||||
| **resource** | The name of the database resource defined in [resources.ini](04-Resources.md#resources). |
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Must be set to `db`.
|
||||
resource | **Required.** The name of the database resource defined in [resources.ini](04-Resources.md#resources). |
|
||||
|
||||
**Example:**
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/authentication.ini
|
||||
|
||||
[auth_db]
|
||||
backend = db
|
||||
resource = icingaweb-mysql
|
||||
```
|
||||
|
||||
### Database Setup <a id="authentication-configuration-db-setup"></a>
|
||||
Please read [this chapter](20-Advanced-Topics.md#advanced-topics-authentication-tips-manual-user-database-auth)
|
||||
in order to manually create users directly inside the database.
|
||||
|
||||
For authenticating against a database, you have to import one of the following database schemas:
|
||||
|
||||
* **etc/schema/preferences.mysql.sql** (for **MySQL** database)
|
||||
* **etc/schema/preferences.pgsql.sql** (for **PostgreSQL** databases)
|
||||
## Groups <a id="authentication-configuration-groups"></a>
|
||||
|
||||
After that you have to define the [database resource](04-Resources.md#resources-configuration-database).
|
||||
Navigate into **Configuration > Application > Authentication **.
|
||||
|
||||
**Manually Creating Users**
|
||||
Group configuration is stored in the `/etc/icingaweb2/groups.ini` file.
|
||||
|
||||
Icinga Web 2 uses the MD5 based BSD password algorithm. For generating a password hash, please use the following
|
||||
command:
|
||||
### LDAP Groups <a id="authentication-configuration-groups-ldap"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Can be set to `ldap`, `msldap`.
|
||||
resource | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
|
||||
user\_class | **Optional.** LDAP user class. Defaults to `user`.
|
||||
user\_name\_attribute | **Optional.** LDAP attribute which contains the username. Defaults to `sAMAccountName` with `msldap` and `uid` with `ldap`.
|
||||
group\_class | **Optional.** LDAP group class. Defaults to `group`.
|
||||
group\_name\_attribute | **Optional.** LDAP attribute which contains the groupname. Defaults to `sAMAccountName` with `msldap` and `gid` with `ldap`.
|
||||
group\_filter | **Optional.** LDAP group search filter. Requires `group_class` and `group_name_attribute`.
|
||||
nested\_group\_search | **Optional.** Enable nested group search in Active Directory based on the user. Defaults to `0`. Only available with `backend` type `msldap`.
|
||||
|
||||
Example for Active Directory groups:
|
||||
|
||||
```
|
||||
openssl passwd -1 password
|
||||
# vim /etc/icingaweb2/groups.ini
|
||||
|
||||
[active directory]
|
||||
backend = "msldap"
|
||||
resource = "auth_ad"
|
||||
group_class = "group"
|
||||
user_class = "user"
|
||||
user_name_attribute = "userPrincipalName"
|
||||
```
|
||||
|
||||
> Note: The switch to `openssl passwd` is the **number one** (`-1`) for using the MD5 based BSD password algorithm.
|
||||
|
||||
Insert the user into the database using the generated password hash:
|
||||
Example for Active Directory using the group backend resource `ad_company`.
|
||||
It also references the defined user backend resource `ad_users_company`.
|
||||
|
||||
```
|
||||
INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, 'hash from openssl');
|
||||
# vim /etc/icingaweb2/groups.ini
|
||||
|
||||
[ad_groups_company]
|
||||
backend = "msldap"
|
||||
resource = "ad_company"
|
||||
user_backend = "ad_users_company"
|
||||
nested_group_search = "1"
|
||||
base_dn = "ou=Icinga,ou=Groups,dc=company,dc=com"
|
||||
```
|
||||
|
||||
### Database Groups <a id="authentication-configuration-groups-database"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
backend | **Required.** Specifies the backend type. Must be set to `db`.
|
||||
resource | **Required.** The name of the database resource defined in [resources.ini](04-Resources.md#resources).
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/groups.ini
|
||||
|
||||
[icingaweb2]
|
||||
backend = "db"
|
||||
resource = "icingaweb_db"
|
||||
```
|
||||
|
||||
|
||||
## Domain-aware Authentication <a id="domain-aware-auth"></a>
|
||||
|
||||
If there are multiple LDAP/AD authentication backends with distinct domains, you should make Icinga Web 2 aware of the
|
||||
|
|
@ -161,6 +230,8 @@ configuration. (AD: NetBIOS name, other LDAP: domain in DNS-notation)
|
|||
**Example:**
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/authentication.ini
|
||||
|
||||
[auth_icinga]
|
||||
backend = ldap
|
||||
resource = icinga_ldap
|
||||
|
|
@ -179,10 +250,10 @@ If you configure the domains like above, the icinga.com user "jdoe" will have to
|
|||
EXAMPLE employee "rroe" will have to log in as "rroe@EXAMPLE". They could also log in as "EXAMPLE\\rroe", but this gets
|
||||
converted to "rroe@EXAMPLE" as soon as the user logs in.
|
||||
|
||||
**Caution!**
|
||||
|
||||
Enabling domain-awareness or changing domains in existing setups requires migration of the usernames in the Icinga Web 2
|
||||
configuration. Consult `icingacli --help migrate config users` for details.
|
||||
> **Caution!**
|
||||
>
|
||||
> Enabling domain-awareness or changing domains in existing setups requires migration of the usernames in the Icinga Web 2
|
||||
> configuration. Consult `icingacli --help migrate config users` for details.
|
||||
|
||||
### Default Domain <a id="default-auth-domain"></a>
|
||||
|
||||
|
|
@ -191,6 +262,8 @@ For the sake of simplicity a default domain can be configured (in `config.ini`).
|
|||
**Example:**
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/config.ini
|
||||
|
||||
[authentication]
|
||||
default_domain = "icinga.com"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ things to which access can be managed: actions and objects.
|
|||
### <a id="security-basics-actions"></a>Actions
|
||||
|
||||
Actions are all the things an Icinga Web 2 user can do, like changing a certain configuration,
|
||||
changing permissions or sending a command to the Icinga instance through the Icinga command pipe.
|
||||
changing permissions or sending a command to an Icinga 2 instance.
|
||||
All actions must be be **allowed explicitly** using permissions.
|
||||
|
||||
A permission is a simple list of identifiers of actions a user is
|
||||
|
|
@ -49,11 +49,11 @@ Icinga Web 2 users and groups are not configured by a configuration file, but pr
|
|||
an **authentication backend**. For extended information on setting up authentication backends and managing users, please read the chapter [Authentication](05-Authentication.md#authentication).
|
||||
|
||||
|
||||
<div class="info-box">
|
||||
Since Icinga Web 2, users in the Icinga configuration and the web authentication are separated, to allow
|
||||
use of external authentication providers. This means that users and groups defined in the Icinga configuration are not available to Icinga Web 2. Instead it uses its own authentication
|
||||
backend to fetch users and groups from, which must be configured separately.
|
||||
</div>
|
||||
> **Note**
|
||||
>
|
||||
> Since Icinga Web 2, users in the Icinga configuration and the web authentication are separated, to allow
|
||||
> use of external authentication providers. This means that users and groups defined in the Icinga configuration are not available to Icinga Web 2. Instead it uses its own authentication
|
||||
> backend to fetch users and groups from, which must be configured separately.
|
||||
|
||||
#### <a id="security-basics-users-managing"></a>Managing Users
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ Like users, groups are identified solely by their **name** that is provided by
|
|||
|
||||
When using a [Database as an authentication backend](05-Authentication.md#authentication-configuration-db-authentication),
|
||||
it is possible to manage groups and group memberships directly in the frontend. This configuration
|
||||
can be found at **Configuration > Authentication > Groups **.
|
||||
can be found at **Configuration > Authentication > User Groups **.
|
||||
|
||||
## <a id="security-roles"></a>Roles
|
||||
|
||||
|
|
@ -97,19 +97,21 @@ Roles can be changed either through the icingaweb2 interface, by navigation
|
|||
to the page **Configuration > Authentication > Roles**, or through editing the
|
||||
configuration file:
|
||||
|
||||
/etc/icingaweb2/roles.ini
|
||||
|
||||
```
|
||||
vim /etc/icingaweb2/roles.ini
|
||||
```
|
||||
|
||||
#### <a id="security-roles-configuration-example"></a>Introducing Example
|
||||
|
||||
To get you a quick start, here is an example of what a role definition could look like:
|
||||
|
||||
|
||||
[winadmin]
|
||||
users = "jdoe, janedoe"
|
||||
groups = "admin"
|
||||
permissions = "config/*, monitoring/commands/schedule-check"
|
||||
monitoring/filter/objects = "host_name=*win*"
|
||||
```
|
||||
[winadmin]
|
||||
users = "jdoe, janedoe"
|
||||
groups = "admin"
|
||||
permissions = "config/*, monitoring/commands/schedule-check"
|
||||
monitoring/filter/objects = "host_name=*win*"
|
||||
```
|
||||
|
||||
|
||||
This example creates a role called **winadmin**, that grants all permissions in `config/*` and `monitoring/commands/schedule-check` and additionally only
|
||||
|
|
@ -124,12 +126,12 @@ Each role is defined as a section, with the name of the role as section name. Th
|
|||
attributes can be defined for each role in a default Icinga Web 2 installation:
|
||||
|
||||
|
||||
| Directive | Description |
|
||||
| ----------------------------- | ----------- |
|
||||
| **users** | a comma-separated list of user **user names** that are affected by this role |
|
||||
| **groups** | a comma-separated list of **group names** that are affected by this role |
|
||||
| **permissions** | a comma-separated list of **permissions** granted by this role |
|
||||
| **monitoring/filter/objects** | a **filter expression** that restricts the access to services and hosts |
|
||||
Name | Description
|
||||
--------------------------|-----------------------------------------------
|
||||
users | Comma-separated list of user **user names** that are affected by this role.
|
||||
groups | Comma-separated list of **group names** that are affected by this role.
|
||||
permissions | Comma-separated list of **permissions** granted by this role.
|
||||
monitoring/filter/objects | **Filter expression** that restricts the access to services and hosts.
|
||||
|
||||
|
||||
|
||||
|
|
@ -155,12 +157,12 @@ through a group) all permissions are added together to get the users actual perm
|
|||
|
||||
### Global Permissions <a id="permissions-global"></a>
|
||||
|
||||
| Name | Permits |
|
||||
| ----------------------------- | ------------ |
|
||||
| **\*** | allow everything, including module-specific permissions |
|
||||
| **config/\*** | allow all configuration actions |
|
||||
| **config/modules** | allow enabling or disabling modules |
|
||||
| **module/<moduleName>** | allow access to module <moduleName> |
|
||||
Name | Permits
|
||||
--------------------------|-----------------------------------------------
|
||||
\* | allow everything, including module-specific permissions
|
||||
config/\* | allow all configuration actions
|
||||
config/modules | allow enabling or disabling modules
|
||||
module/<moduleName> | allow access to module <moduleName>
|
||||
|
||||
|
||||
### Monitoring Module Permissions <a id="permissions-module"></a>
|
||||
|
|
@ -236,15 +238,19 @@ the filter expressions. The following examples will show the usefulness of this
|
|||
|
||||
#### <a id="restrictions-filter-example1"></a>Example 1: Negation
|
||||
|
||||
[winadmin]
|
||||
groups = "windows-admins"
|
||||
monitoring/filter/objects = "host_name=*win*"
|
||||
```
|
||||
[winadmin]
|
||||
groups = "windows-admins"
|
||||
monitoring/filter/objects = "host_name=*win*"
|
||||
```
|
||||
|
||||
Will display only hosts and services whose host name contains **win**.
|
||||
|
||||
[webadmin]
|
||||
groups = "web-admins"
|
||||
monitoring/filter/objects = "host_name!=*win*"
|
||||
```
|
||||
[webadmin]
|
||||
groups = "web-admins"
|
||||
monitoring/filter/objects = "host_name!=*win*"
|
||||
```
|
||||
|
||||
Will only match hosts and services whose host name does **not** contain **win**
|
||||
|
||||
|
|
@ -252,9 +258,11 @@ Notice that because of the behavior of two stacking filters, a user that is memb
|
|||
|
||||
#### <a id="restrictions-filter-example2"></a>Example 2: Hostgroups
|
||||
|
||||
[unix-server]
|
||||
groups = "unix-admins"
|
||||
monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)"
|
||||
```
|
||||
[unix-server]
|
||||
groups = "unix-admins"
|
||||
monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)"
|
||||
```
|
||||
|
||||
This role allows all members of the group unix-admins to see hosts and services
|
||||
that are part of the host-group linux-servers or the host-group bsd-servers.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,18 @@
|
|||
# Preferences <a id="preferences"></a>
|
||||
|
||||
Preferences are settings a user can set for his account only, for example his language and time zone.
|
||||
|
||||
**Choosing Where to Store Preferences**
|
||||
Preferences are settings a user can set for their account only,
|
||||
for example the language and time zone.
|
||||
|
||||
Preferences can be stored either in INI files or in a MySQL or in a PostgreSQL database. By default, Icinga Web 2 stores
|
||||
preferences in INI files beneath Icinga Web 2's configuration directory.
|
||||
|
||||
```
|
||||
/etc/icingaweb2/<username>/config.ini
|
||||
```
|
||||
|
||||
## Configuration <a id="preferences-configuration"></a>
|
||||
|
||||
Where to store preferences is defined in the INI file **config/config.ini** in the *preferences* section.
|
||||
The preference configuration backend is defined in the global [config.ini](03-Configuration.md#configuration-general-global) file.
|
||||
|
||||
### Store Preferences in INI Files <a id="preferences-configuration-ini"></a>
|
||||
|
||||
|
|
@ -17,11 +20,12 @@ If preferences are stored in INI Files, Icinga Web 2 automatically creates one f
|
|||
file name for storing preferences. A INI file is created once a user saves changed preferences the first time.
|
||||
The files are located beneath the `preferences` directory beneath Icinga Web 2's configuration directory.
|
||||
|
||||
For storing preferences in INI files you have to add the following section to the INI file **config/config.ini**:
|
||||
You need to add the following section to the global [config.ini](03-Configuration.md#configuration-general-global) file
|
||||
in order to store preferences in a file.
|
||||
|
||||
```
|
||||
[preferences]
|
||||
type = ini
|
||||
[global]
|
||||
config_backend = "ini"
|
||||
```
|
||||
|
||||
### Store Preferences in a Database <a id="preferences-configuration-db"></a>
|
||||
|
|
@ -30,24 +34,11 @@ In order to be more flexible in distributed setups you can store preferences in
|
|||
For storing preferences in a database, you have to define a [database resource](04-Resources.md#resources-configuration-database)
|
||||
which will be referenced as resource for the preferences storage.
|
||||
|
||||
| Directive | Description |
|
||||
| ------------- | ----------- |
|
||||
| **type** | `db` |
|
||||
| **resource** | The name of the database resource defined in [resources.ini](04-Resources.md#resources). |
|
||||
|
||||
**Example:**
|
||||
You need to add the following section to the global [config.ini](03-Configuration.md#configuration-general-global) file
|
||||
in order to store preferences in a database.
|
||||
|
||||
```
|
||||
[preferences]
|
||||
type = db
|
||||
resource = icingaweb-mysql
|
||||
[global]
|
||||
config_backend = "db"
|
||||
config_resource = "icingaweb_db"
|
||||
```
|
||||
|
||||
#### Database Setup <a id="preferences-configuration-db-setup"></a>
|
||||
|
||||
For storing preferences in a database, you have to import one of the following database schemas:
|
||||
|
||||
* **etc/schema/preferences.mysql.sql** (for **MySQL** database)
|
||||
* **etc/schema/preferences.pgsql.sql** (for **PostgreSQL** databases)
|
||||
|
||||
After that you have to define the [database resource](04-Resources.md#resources-configuration-database).
|
||||
|
|
|
|||
|
|
@ -113,6 +113,25 @@ Reload Apache and open the FQDN in your web browser.
|
|||
systemctl reload httpd
|
||||
```
|
||||
|
||||
## Advanced Authentication Tips <a id="advanced-topics-authentication-tips"></a>
|
||||
|
||||
### Manual User Creation for Database Authentication Backend <a id="advanced-topics-authentication-tips-manual-user-database-auth"></a>
|
||||
|
||||
Icinga Web 2 uses the MD5 based BSD password algorithm. For generating a password hash, please use the following
|
||||
command:
|
||||
|
||||
```
|
||||
openssl passwd -1 password
|
||||
```
|
||||
|
||||
> Note: The switch to `openssl passwd` is the **number one** (`-1`) for using the MD5 based BSD password algorithm.
|
||||
|
||||
Insert the user into the database using the generated password hash:
|
||||
|
||||
```
|
||||
INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, 'hash from openssl');
|
||||
```
|
||||
|
||||
|
||||
## Installing Icinga Web 2 from Source <a id="installing-from-source"></a>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,21 +1,23 @@
|
|||
# Vagrant <a id="vagrant"></a>
|
||||
|
||||
This chapter shows how to set up and use our [Icinga Vagrant
|
||||
boxes](https://github.com/icinga/icinga-vagrant) that we've created for
|
||||
development, tests and demo cases.
|
||||
This chapter explains how to setup the development environment
|
||||
for Icinga Web 2 inside a Vagrant VM.
|
||||
|
||||
If you are looking for a demo setup, please use the official
|
||||
[Icinga Vagrant boxes](https://github.com/icinga/icinga-vagrant)
|
||||
instead.
|
||||
|
||||
## <a id="vagrant-requirements"></a>Requirements
|
||||
|
||||
* Vagrant >= version 1.5
|
||||
* VirtualBox or Parallels Desktop
|
||||
|
||||
> **Note:** The deployment of the virtual machine is tested against Vagrant starting with version 1.5.
|
||||
> Unfortunately older versions will not work.
|
||||
|
||||
Parallels requires the additional provider plugin
|
||||
[vagrant-paralells](http://parallels.github.io/vagrant-parallels/docs/) to be installed:
|
||||
|
||||
$ vagrant plugin install vagrant-parallels
|
||||
```
|
||||
$ vagrant plugin install vagrant-parallels
|
||||
```
|
||||
|
||||
## <a id="vagrant-general"></a>General
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
# About the Doc Module <a id="doc-module-about"></a>
|
||||
|
||||
Please read the following chapters for more insights on this module:
|
||||
|
||||
* [Installation](02-Installation.md#doc-module-installation)
|
||||
* [Module Documentation](03-Module-Documentation.md#module-documentation)
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# Doc Module Installation <a id="doc-module-installation"></a>
|
||||
|
||||
This module is provided with the Icinga Web 2 package and does
|
||||
not need any extra installation step.
|
||||
|
||||
## Enable the Module <a id="monitoring-module-enable"></a>
|
||||
|
||||
Navigate to `Configuration` -> `Modules` -> `doc` and enable
|
||||
the module.
|
||||
|
||||
You can also enable the module during the setup wizard, or on the CLI:
|
||||
|
||||
```
|
||||
icingacli module enable doc
|
||||
```
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# <a id="module-documentation"></a> Writing Module Documentation
|
||||
# Writing Module Documentation <a id="module-documentation"></a>
|
||||
|
||||
|
||||
|
||||
|
|
@ -6,14 +6,16 @@ Icinga Web 2 is capable of viewing your module's documentation, if the documenta
|
|||
[Markdown](http://en.wikipedia.org/wiki/Markdown). Please refer to
|
||||
[Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) for Markdown's formatting syntax.
|
||||
|
||||
## <a id="location"></a> Where to Put Module Documentation?
|
||||
## Where to Put Module Documentation? <a id="module-documentation-location"></a>
|
||||
|
||||
By default, your module's Markdown documentation files must be placed in the `doc` directory beneath your module's root
|
||||
directory, e.g.:
|
||||
|
||||
example-module/doc
|
||||
```
|
||||
example-module/doc
|
||||
```
|
||||
|
||||
## <a id="chapters"></a> Chapters
|
||||
## Chapters <a id="module-documentation-chapters"></a>
|
||||
|
||||
Each Markdown documentation file represents a chapter of your module's documentation. The first found heading inside
|
||||
each file is the chapter's title. The order of chapters is based on the case insensitive "Natural Order" of your files'
|
||||
|
|
@ -21,49 +23,65 @@ names. <dfn>Natural Order</dfn> means that the file names are ordered in the way
|
|||
It is best practice to prefix Markdown documentation file names with numbers to ensure that they appear in the correct
|
||||
order, e.g.:
|
||||
|
||||
1-about.md
|
||||
2-installation.md
|
||||
3-configuration.md
|
||||
```
|
||||
01-About.md
|
||||
02-Installation.md
|
||||
03-Configuration.md
|
||||
```
|
||||
|
||||
## <a id="toc"></a> Table Of Contents
|
||||
## Table Of Contents <a id="module-documentation-toc"></a>
|
||||
|
||||
The table of contents for your module's documentation is auto-generated based on all found headings inside each
|
||||
Markdown documentation file.
|
||||
|
||||
## <a id="linking"></a> Linking Between Headings
|
||||
## Linking Between Headings <a id="module-documentation-linking"></a>
|
||||
|
||||
For linking between headings, place an anchor where you want to link to, e.g.:
|
||||
For linking between headings, place an anchor **after the text** where you want to link to, e.g.:
|
||||
|
||||
# <a id="heading"></a> Heading
|
||||
```
|
||||
# Heading <a id="heading"></a> Heading
|
||||
```
|
||||
|
||||
Please note that anchors have to be unique across all your Markdown documentation files.
|
||||
|
||||
Now you can reference the anchor either in the same or **in another** Markdown documentation file, e.g.:
|
||||
|
||||
This is a link to [Heading](#heading).
|
||||
```
|
||||
This is a link to [Heading](#heading).
|
||||
```
|
||||
|
||||
Other tools support linking between headings by giving the filename plus the anchor to link to, e.g.:
|
||||
|
||||
This is a link to [About/Heading](1-about.md#heading.md)
|
||||
```
|
||||
This is a link to [About/Heading](01-About.md#heading)
|
||||
```
|
||||
|
||||
This syntax is also supported in Icinga Web 2.
|
||||
|
||||
## <a id="images"></a> Including Images
|
||||
## Including Images <a id="module-documentation-images"></a>
|
||||
|
||||
Images must placed in the `doc` directory beneath your module's root directory, e.g.:
|
||||
|
||||
/path/to/icingaweb2/modules/example-module/doc/img/example.png
|
||||
```
|
||||
/path/to/icingaweb2/modules/example-module/doc/img/example.png
|
||||
```
|
||||
|
||||
Note that the `img` sub directory is not mandatory but good for organizing your directory structure.
|
||||
|
||||
Module images can be accessed using the following URL:
|
||||
|
||||
{baseURL}/doc/module/{moduleName}/image/{image} e.g. icingaweb2/doc/module/example-module/image/img/example.png
|
||||
```
|
||||
{baseURL}/doc/module/{moduleName}/image/{image} e.g. icingaweb2/doc/module/example-module/image/img/example.png
|
||||
```
|
||||
|
||||
Markdown's image syntax is very similar to Markdown's link syntax, but prefixed with an exclamation mark, e.g.:
|
||||
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
URLs to images inside your Markdown documentation files must be specified without the base URL, e.g.:
|
||||
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# About the Monitoring Module <a id="monitoring-module-about"></a>
|
||||
|
||||
Please read the following chapters for more insights on this module:
|
||||
|
||||
* [Installation](02-Installation.md#monitoring-module-installation)
|
||||
* [Configuration](03-Configuration.md#monitoring-module-configuration)
|
||||
* [Security](06-Security.md#monitoring-module-security)
|
||||
* [Restrict Custom Variables](10-Restrict-Custom-Variables.md#monitoring-module-restrict-access-custom-variables)
|
||||
* [Hooks](20-Hooks.md#monitoring-module-hooks)
|
||||
* [Add Columns to List Views](11-Add-Columns-List-Views.md#monitoring-module-add-columns-list-views)
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# Monitoring Module Installation <a id="monitoring-module-installation"></a>
|
||||
|
||||
This module is provided with the Icinga Web 2 package and does
|
||||
not need any extra installation step.
|
||||
|
||||
## Enable the Module <a id="monitoring-module-enable"></a>
|
||||
|
||||
Navigate to `Configuration` -> `Modules` -> `monitoring` and enable
|
||||
the module.
|
||||
|
||||
You can also enable the module during the setup wizard, or on the CLI:
|
||||
|
||||
```
|
||||
icingacli module enable monitoring
|
||||
```
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# Monitoring Module Configuration <a id="monitoring-module-configuration"></a>
|
||||
|
||||
## Overview <a id="monitoring-module-configuration-overview"></a>
|
||||
|
||||
The module specific configuration is stored in `/etc/icingaweb2/modules/monitoring`.
|
||||
|
||||
File/Directory | Description
|
||||
----------------------------------------------------------------------|---------------------------------
|
||||
[config.ini](01-Configuration.md#monitoring-module-configuration-general) | Security settings (e.g. protected custom vars) for the `monitoring` module |
|
||||
[backends.ini](02-Backends.md#monitoring-module-backends) | Data backend (e.g. the IDO database [resource](../../../doc/04-Resources.md#resources-configuration-database) name).
|
||||
[commandtransports.ini](03-Command-Transports.md#commandtransports) | Command transports for specific Icinga instances
|
||||
|
||||
|
||||
## General Configuration <a id="monitoring-module-configuration-general"></a>
|
||||
|
||||
Navigate into `Configuration` -> `Modules` -> `Monitoring`. This allows
|
||||
you to see the provided [permissions and restrictions](06-Security.md#monitoring-security)
|
||||
by this module.
|
||||
|
||||
### Security Configuration <a id="monitoring-module-configuration-security"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
protected\_customvars | **Optional.** Comma separated list of string patterns for custom variables which should be excluded from user's view.
|
||||
|
||||
|
||||
Example for custom variable names which match `*pw*` or `*pass*` or `community`.
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/modules/monitoring/config.ini
|
||||
|
||||
[security]
|
||||
protected_customvars = "*pw*,*pass*,community"
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
# Backends <a id="monitoring-module-backends"></a>
|
||||
|
||||
The configuration file `backends.ini` contains information about data sources which are
|
||||
used to fetch monitoring objects presented to the user.
|
||||
|
||||
The required [resources](../../../doc/04-Resources.md#resources-configuration-database) must be globally defined beforehand.
|
||||
|
||||
## Configuration <a id="monitoring-module-backends-configuration"></a>
|
||||
|
||||
Navigate into `Configuration` -> `Modules` -> `Monitoring` -> `Backends`.
|
||||
You can select a specified global resource here, and also update its details.
|
||||
|
||||
Each section in `backends.ini` references a resource. By default you should only have one backend enabled.
|
||||
|
||||
### IDO Backend <a id="monitoring-module-backends-ido"></a>
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
type | **Required.** Specify the backend type. Must be set to `ido`.
|
||||
resource | **Required.** Specify a defined [resource](../../../doc/04-Resources.md#resources-configuration-database) name which provides details about the IDO database resource.
|
||||
|
||||
|
||||
Example for using the database resource `icinga2_ido_mysql`:
|
||||
|
||||
```
|
||||
[icinga2_ido_mysql]
|
||||
type = "ido"
|
||||
resource = "icinga2_ido_mysql"
|
||||
```
|
||||
|
||||
|
|
@ -0,0 +1,185 @@
|
|||
# External Command Transport Configuration <a id="monitoring-module-commandtransports"></a>
|
||||
|
||||
## Configuration <a id="monitoring-module-commandtransports-configuration"></a>
|
||||
|
||||
Navigate into `Configuration` -> `Modules` -> `Monitoring` -> `Backends`.
|
||||
You can create/edit command transports here.
|
||||
|
||||
The `commandtransports.ini` configuration file defines how Icinga Web 2
|
||||
transports commands to your Icinga instance in order to submit
|
||||
external commands. By default, this file is located at `/etc/icingaweb2/modules/monitoring/commandtransports.ini`.
|
||||
|
||||
You can define multiple command transports in the `commandtransports.ini` file. Every transport starts with a section header
|
||||
containing its name, followed by the config directives for this transport in the standard INI-format.
|
||||
|
||||
Icinga Web 2 will try one transport after another to send a command until the command is successfully sent.
|
||||
If [configured](02-Command-Transports.md#commandtransports-multiple-instances), Icinga Web 2 will take different instances into account.
|
||||
The order in which Icinga Web 2 processes the configured transports is defined by the order of sections in
|
||||
`commandtransports.ini`.
|
||||
|
||||
## Use the Icinga 2 API <a id="commandtransports-icinga2-api"></a>
|
||||
|
||||
If you're running Icinga 2 it's best to use the [Icinga 2 API](https://www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/)
|
||||
for transmitting external commands.
|
||||
|
||||
### Icinga 2 Preparations <a id="commandtransports-icinga2-api-preparations"></a>
|
||||
|
||||
You have to run the `api` setup on the Icinga 2 host where you want to send the commands to:
|
||||
|
||||
```
|
||||
icinga2 api setup
|
||||
```
|
||||
|
||||
Next, you have to create an ApiUser object for authenticating against the Icinga 2 API. This configuration also applies
|
||||
to the host where you want to send the commands to. We recommend to create/edit the file
|
||||
`/etc/icinga2/conf.d/api-users.conf`:
|
||||
|
||||
```
|
||||
object ApiUser "icingaweb2" {
|
||||
password = "bea11beb7b810ea9ce6ea" // Change this!
|
||||
permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
|
||||
}
|
||||
```
|
||||
|
||||
The permissions are mandatory in order to submit all external commands from within Icinga Web 2.
|
||||
|
||||
**Restart Icinga 2** for the changes to take effect.
|
||||
|
||||
```
|
||||
systemctl restart icinga2
|
||||
```
|
||||
|
||||
### Configuration in Icinga Web 2 <a id="commandtransports-icinga2-api-configuration"></a>
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Please make sure that your server running Icinga Web 2 has the `PHP cURL` extension installed and enabled.
|
||||
|
||||
The Icinga 2 API requires the following settings:
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
transport | **Required.** The transport type. Must be set to `api`.
|
||||
host | **Required.** The host address where the Icinga 2 API is listening on.
|
||||
port | **Required.** The port where the Icinga 2 API is listening on. Defaults to `5665`.
|
||||
username | **Required.** Basic auth username.
|
||||
password | **Required.** Basic auth password.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
|
||||
|
||||
[icinga2]
|
||||
transport = "api"
|
||||
host = "127.0.0.1" // Icinga 2 host
|
||||
port = "5665"
|
||||
username = "icingaweb2"
|
||||
password = "bea11beb7b810ea9ce6ea" // Change that!
|
||||
```
|
||||
|
||||
## Use a Local Command Pipe <a id="commandtransports-local-command-pipe"></a>
|
||||
|
||||
A local Icinga instance requires the following settings:
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
transport | **Required.** The transport type. Must be set to `local`.
|
||||
path | **Required.** The absolute path to the local command pipe.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
|
||||
|
||||
[icinga2]
|
||||
transport = local
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
```
|
||||
|
||||
When commands are being sent to the Icinga instance, Icinga Web 2 opens the file found
|
||||
on the local filesystem underneath `path` and writes the external command to it.
|
||||
|
||||
Please note that errors are not returned using this method. The Icinga 2 API sends
|
||||
error feedback.
|
||||
|
||||
## Use SSH For a Remote Command Pipe <a id="commandtransports-ssh-remote-command-pipe"></a>
|
||||
|
||||
A command pipe on a remote host's filesystem can be accessed by configuring a
|
||||
SSH based command transport and requires the following settings:
|
||||
|
||||
Option | Description
|
||||
-------------------------|-----------------------------------------------
|
||||
transport | **Required.** The transport type. Must be set to `remote`.
|
||||
path | **Required.** The path on the remote server to its local command pipe.
|
||||
host | **Required.** The SSH host.
|
||||
port | **Optional.** The SSH port. Defaults to `22`.
|
||||
user | **Required.** The SSH auth user.
|
||||
resource | **Optional.** The SSH [resource](../../../doc/04-Resources.md#resources-configuration-ssh)
|
||||
instance | **Optional.** The Icinga instance name. Only required for multiple instances.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
|
||||
|
||||
[icinga2]
|
||||
transport = remote
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
host = example.tld
|
||||
user = icinga
|
||||
;port = 22 ; Optional. The default is 22
|
||||
```
|
||||
|
||||
To make this example work, you'll need to permit your web-server's user
|
||||
public-key based access to the defined remote host so that Icinga Web 2 can
|
||||
connect to it and login as the defined user.
|
||||
|
||||
You can also make use of a dedicated SSH resource to permit access for a
|
||||
different user than the web-server's one. This way, you can provide a private
|
||||
key file on the local filesystem that is used to access the remote host.
|
||||
|
||||
To accomplish this, a new resource is required that is defined in your
|
||||
transport's configuration instead of a user:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini
|
||||
|
||||
[icinga2]
|
||||
transport = remote
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
host = example.tld
|
||||
resource = example.tld-icinga2
|
||||
;port = 22 ; Optional. The default is 22
|
||||
```
|
||||
|
||||
The resource's configuration needs to be put into the resources.ini file:
|
||||
|
||||
```
|
||||
# vim /etc/icingaweb2/resources.ini
|
||||
|
||||
[example.tld-icinga2]
|
||||
type = ssh
|
||||
user = icinga
|
||||
private_key = /etc/icingaweb2/ssh/icinga
|
||||
```
|
||||
|
||||
## Configure Transports for Different Icinga Instances <a id="commandtransports-multiple-instances"></a>
|
||||
|
||||
If there are multiple but different Icinga instances writing to your IDO database,
|
||||
you can define which transport belongs to which Icinga instance by providing the
|
||||
`instance` setting. This setting must specify the name of the Icinga
|
||||
instance you want to assign to the transport:
|
||||
|
||||
```
|
||||
[icinga1]
|
||||
...
|
||||
instance = icinga1
|
||||
|
||||
[icinga2]
|
||||
...
|
||||
instance = icinga2
|
||||
```
|
||||
|
||||
Associating a transport to a specific Icinga instance causes this transport to be used to send commands to the linked
|
||||
instance only. Transports without a linked Icinga instance are used to send commands to all instances.
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
# Security <a id="monitoring-module-security"></a>
|
||||
|
||||
The monitoring module provides an additional set of restrictions and permissions
|
||||
that can be used for access control. The following sections will list those
|
||||
restrictions and permissions in detail:
|
||||
|
||||
|
||||
## Permissions <a id="monitoring-module-security-permissions"></a>
|
||||
|
||||
The monitoring module allows to send commands to an Icinga 2 instance.
|
||||
A user needs specific permissions to be able to send those commands
|
||||
when using the monitoring module.
|
||||
|
||||
|
||||
Name | Permits
|
||||
--------------------------------------------|-----------------------------------------------
|
||||
monitoring/command/\* | Allow all commands.
|
||||
monitoring/command/schedule-check | Allow scheduling host and service checks.
|
||||
monitoring/command/acknowledge-problem | Allow acknowledging host and service problems.
|
||||
monitoring/command/remove-acknowledgement | Allow removing problem acknowledgements.
|
||||
monitoring/command/comment/\* | Allow adding and deleting host and service comments.
|
||||
monitoring/command/comment/add | Allow commenting on hosts and services.
|
||||
monitoring/command/downtime/delete | Allow deleting host and service downtimes.
|
||||
monitoring/command/process-check-result | Allow processing host and service check results.
|
||||
monitoring/command/feature/instance | Allow processing commands for toggling features on an instance-wide basis.
|
||||
monitoring/command/feature/object | Allow processing commands for toggling features on host and service objects.
|
||||
monitoring/command/send-custom-notification | Allow sending custom notifications for hosts and services.
|
||||
|
||||
|
||||
## Restrictions <a id="monitoring-module-security-restrictions"></a>
|
||||
|
||||
The monitoring module allows filtering objects:
|
||||
|
||||
|
||||
Keys | Restricts
|
||||
--------------------------------------------|-----------------------------------------------
|
||||
monitoring/filter/objects | Applies a filter to all hosts and services.
|
||||
|
||||
|
||||
This filter will affect all hosts and services. Furthermore, it will also
|
||||
affect all related objects, like notifications, downtimes and events. If a
|
||||
service is hidden, all notifications, downtimes on that service will be hidden too.
|
||||
|
||||
|
||||
### Filter Column Names <a id="monitoring-module-security-restrictions-filter-column-names"></a>
|
||||
|
||||
The following filter column names are available in filter expressions:
|
||||
|
||||
|
||||
Column | Description
|
||||
-----------------------------------------------------------|-----------------------------------------------
|
||||
instance\_name | Filter on an Icinga 2 instance.
|
||||
host\_name | Filter on host object names.
|
||||
hostgroup\_name | Filter on hostgroup object names.
|
||||
service\_description | Filter on service object names.
|
||||
servicegroup\_name | Filter on servicegroup object names.
|
||||
all custom variables prefixed with `_host_` or `_service_` | Filter on specified custom variables.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Restrict Access to Custom Variables (WIP)
|
||||
# Restrict Access to Custom Variables <a id="monitoring-module-restrict-access-custom-variables"></a>
|
||||
|
||||
* Restriction name: monitoring/blacklist/properties
|
||||
* Restriction value: Comma separated list of GLOB like filters
|
||||
* Restriction value: Comma separated list of GLOB like filters
|
||||
|
||||
Imagine the following host custom variable structure.
|
||||
|
||||
|
|
@ -27,7 +27,7 @@ host.vars.
|
|||
|
||||
`host.vars.cmdb_name`
|
||||
|
||||
Blacklists cmdb_name in the first level of the custom variable structure only.
|
||||
Blacklists `cmdb_name` in the first level of the custom variable structure only.
|
||||
`host.vars.legacy.cmdb_name` is not blacklisted.
|
||||
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ the following restriction.
|
|||
|
||||
`host.vars.**.*password,service.vars.**.*password`
|
||||
|
||||
## Escape Meta Characters
|
||||
## Escape Meta Characters <a id="restrict-access-custom-variables-escape-meta-chars"></a>
|
||||
|
||||
Use backslash to escape the meta characters
|
||||
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
# Add Columns to List Views <a id="monitoring-module-add-columns-list-views"></a>
|
||||
|
||||
The monitoring module provides list views for hosts and services.
|
||||
These lists only provide the most common columns to reduce the backend
|
||||
query load.
|
||||
|
||||
If you want to add more columns to the list view e.g. in order to use the URL in
|
||||
your dashboards or as external iframe integration, you need the `addColumns` URL
|
||||
parameter.
|
||||
|
||||
|
||||
|
||||
Example for adding the host `address` attribute in a host list:
|
||||
|
||||
```
|
||||
http://localhost/icingaweb2/monitoring/list/hosts?addColumns=host_address
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Example for multiple columns as comma separated parameter string. This
|
||||
includes a reference to the Icinga 2 host object custom attribute `os` using
|
||||
`_host_` as custom variable identifier.
|
||||
|
||||
```
|
||||
http://localhost/icingaweb2/monitoring/list/services?addColumns=host_address,_host_os
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -1,20 +1,20 @@
|
|||
# <a id="detailviewextension"></a> Detail View Extension Hook
|
||||
# Monitoring Module Hooks <a id="monitoring-module-hooks"></a>
|
||||
|
||||
## About
|
||||
## Detail View Extension Hook <a id="monitoring-module-hooks-detailviewextension"></a>
|
||||
|
||||
This hook can be used to easily extend the detail view of monitored objects (hosts and services).
|
||||
|
||||
## How it works
|
||||
### How it works <a id="monitoring-module-hooks-detailviewextension-how-it-works"></a>
|
||||
|
||||
### Directory structure
|
||||
#### Directory structure <a id="monitoring-module-hooks-detailviewextension-directory-structure"></a>
|
||||
|
||||
* `icingaweb2/modules/example`
|
||||
* `library/Example/ProvidedHook/Monitoring/DetailviewExtension/Simple.php`
|
||||
* `run.php`
|
||||
|
||||
### Files
|
||||
#### Files <a id="monitoring-module-hooks-detailviewextension-files"></a>
|
||||
|
||||
#### run.php
|
||||
##### run.php <a id="monitoring-module-hooks-detailviewextension-files-run-php"></a>
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
|
@ -26,7 +26,7 @@ $this->provideHook(
|
|||
);
|
||||
```
|
||||
|
||||
#### Simple.php
|
||||
##### Simple.php <a id="monitoring-module-hooks-detailviewextension-files-simple-php"></a>
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
|
@ -71,6 +71,6 @@ class Simple extends DetailviewExtensionHook
|
|||
}
|
||||
```
|
||||
|
||||
## How it looks like
|
||||
### How it looks <a id="monitoring-module-hooks-detailviewextension-how-it-looks"></a>
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,127 +0,0 @@
|
|||
# <a id="commandtransports"></a> External Command Transport Configuration
|
||||
|
||||
## Introduction
|
||||
|
||||
The `commandtransports.ini` defines how Icinga Web 2 transports commands to your Icinga instance in order to submit
|
||||
external commands. By default, this file is located at `/etc/icingaweb2/modules/monitoring/commandtransports.ini`.
|
||||
|
||||
You can define multiple command transports in the `commandtransports.ini`. Every transport starts with a section header
|
||||
containing its name, followed by the config directives for this transport in the standard INI-format.
|
||||
|
||||
Icinga Web 2 will try one transport after another to send a command until the command is successfully sent.
|
||||
If [configured](#commandtransports-multiple-instances), Icinga Web 2 will take different instances into account.
|
||||
The order in which Icinga Web 2 processes the configured transports is defined by the order of sections in
|
||||
`commandtransports.ini`.
|
||||
|
||||
## Use the Icinga 2 API
|
||||
|
||||
If you're running Icinga 2 it's best to use the Icinga 2 API for transmitting external commands.
|
||||
|
||||
First, please make sure that your server running Icinga Web 2 has the `PHP cURL` extension installed and enabled.
|
||||
|
||||
Second, you have to enable the `api` feature on the Icinga 2 host where you want to send the commands to:
|
||||
|
||||
```
|
||||
icinga2 feature enable api
|
||||
```
|
||||
|
||||
Next, you have to create an ApiUser object for authenticating against the Icinga 2 API. This configuration also applies
|
||||
to the host where you want to send the commands to. We recommend to create/edit the file
|
||||
`/etc/icinga2/conf.d/api-users.conf`:
|
||||
|
||||
```
|
||||
object ApiUser "web2" {
|
||||
password = "bea11beb7b810ea9ce6ea" // Change this!
|
||||
permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
|
||||
}
|
||||
```
|
||||
|
||||
The permissions are mandatory in order to submit all external commands from within Icinga Web 2.
|
||||
|
||||
**Restart Icinga 2** for the changes to take effect.
|
||||
|
||||
After that, you have to set up Icinga Web 2's `commandtransport.ini` to use the Icinga 2 API:
|
||||
|
||||
```
|
||||
[icinga2]
|
||||
transport = "api"
|
||||
host = "127.0.0.1" // Icinga 2 host
|
||||
port = "5665"
|
||||
username = "web2"
|
||||
password = "bea11beb7b810ea9ce6ea" // Change that!
|
||||
```
|
||||
|
||||
## Use a Local Command Pipe
|
||||
|
||||
A local Icinga instance requires the following directives:
|
||||
|
||||
```
|
||||
[icinga2]
|
||||
transport = local
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
```
|
||||
|
||||
When sending commands to the Icinga instance, Icinga Web 2 opens the file found
|
||||
on the local filesystem underneath 'path' and writes the external command to it.
|
||||
|
||||
## Use SSH For a Remote Command Pipe
|
||||
|
||||
A command pipe on a remote host's filesystem can be accessed by configuring a
|
||||
SSH based command transport and requires the following directives:
|
||||
|
||||
```
|
||||
[icinga2]
|
||||
transport = remote
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
host = example.tld
|
||||
user = icinga
|
||||
;port = 22 ; Optional. The default is 22
|
||||
```
|
||||
|
||||
To make this example work, you'll need to permit your web-server's user
|
||||
public-key based access to the defined remote host so that Icinga Web 2 can
|
||||
connect to it and login as the defined user.
|
||||
|
||||
You can also make use of a dedicated SSH resource to permit access for a
|
||||
different user than the web-server's one. This way, you can provide a private
|
||||
key file on the local filesystem that is used to access the remote host.
|
||||
|
||||
To accomplish this, a new resource is required that is defined in your
|
||||
transport's configuration instead of a user:
|
||||
|
||||
```
|
||||
[icinga2]
|
||||
transport = remote
|
||||
path = /var/run/icinga2/cmd/icinga2.cmd
|
||||
host = example.tld
|
||||
resource = example.tld-icinga2
|
||||
;port = 22 ; Optional. The default is 22
|
||||
```
|
||||
|
||||
The resource's configuration needs to be put into the resources.ini file:
|
||||
|
||||
```
|
||||
[example.tld-icinga2]
|
||||
type = ssh
|
||||
user = icinga
|
||||
private_key = /etc/icingaweb2/ssh/icinga
|
||||
```
|
||||
|
||||
## <a id="commandtransports-multiple-instances"></a> Configure Transports for Different Icinga Instances
|
||||
|
||||
If there are multiple but different Icinga instances writing to your IDO, you can define which transport belongs to
|
||||
which Icinga instance by providing the directive `instance`. This directive should contain the name of the Icinga
|
||||
instance you want to assign to the transport:
|
||||
|
||||
```
|
||||
[icinga1]
|
||||
...
|
||||
instance = icinga1
|
||||
|
||||
[icinga2]
|
||||
...
|
||||
instance = icinga2
|
||||
```
|
||||
|
||||
Associating a transport to a specific Icinga instance causes this transport to be used to send commands to the linked
|
||||
instance only. Transports without a linked Icinga instance are used to send commands to all instances.
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
# <a id="monitoring-configuration"></a> Monitoring Module Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Apart from its web configuration capabilities, the local configuration is
|
||||
stored in `/etc/icingaweb2` by default (depending on your config setup).
|
||||
|
||||
| Location | File | Description |
|
||||
| --------------------- | ----------------------------------------------------------------- | ----------- |
|
||||
| modules/monitoring | Directory | `monitoring` module specific configuration |
|
||||
| modules/monitoring | config.ini | Security settings (e.g. protected custom vars) for the `monitoring` module |
|
||||
| modules/monitoring | backends.ini | Backend type and resources (e.g. Icinga IDO DB) |
|
||||
| modules/monitoring | [commandtransports.ini](commandtransports.md#commandtransports) | Command transports for specific Icinga instances |
|
||||
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 184 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 205 KiB |
|
|
@ -1,57 +0,0 @@
|
|||
# <a id="monitoring-security"></a> Security
|
||||
|
||||
The monitoring module provides an additional set of restrictions and permissions
|
||||
that can be used for access control. The following sections will list those
|
||||
restrictions and permissions in detail:
|
||||
|
||||
|
||||
## Permissions
|
||||
|
||||
The Icinga Web 2 monitoring module can send commands to the current Icinga2 instance
|
||||
through the command pipe. A user needs specific permissions to be able to send those
|
||||
commands when using the monitoring module.
|
||||
|
||||
|
||||
| Name | Permits |
|
||||
| ------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| monitoring/command/* | Allow all commands |
|
||||
| monitoring/command/schedule-check | Allow scheduling host and service checks' |
|
||||
| monitoring/command/acknowledge-problem | Allow acknowledging host and service problems |
|
||||
| monitoring/command/remove-acknowledgement | Allow removing problem acknowledgements |
|
||||
| monitoring/command/comment/* | Allow adding and deleting host and service comments |
|
||||
| monitoring/command/comment/add | Allow commenting on hosts and services |
|
||||
| monitoring/command/downtime/delete | Allow deleting host and service downtimes' |
|
||||
| monitoring/command/process-check-result | Allow processing host and service check results |
|
||||
| monitoring/command/feature/instance | Allow processing commands for toggling features on an instance-wide basis |
|
||||
| monitoring/command/feature/object | Allow processing commands for toggling features on host and service objects |
|
||||
| monitoring/command/send-custom-notification | Allow sending custom notifications for hosts and services |
|
||||
|
||||
|
||||
## <a id="monitoring-security-restrictions"></a> Restrictions
|
||||
|
||||
The monitoring module allows filtering objects:
|
||||
|
||||
|
||||
| Keys | Restricts |
|
||||
| ---------------------------|---------------------------------------------- |
|
||||
| monitoring/filter/objects | Applies a filter to all hosts and services |
|
||||
|
||||
|
||||
This filter will affect all hosts and services. Furthermore, it will also
|
||||
affect all related objects, like notifications, downtimes and events. If a
|
||||
service is hidden, all notifications, downtimes on that service will be hidden too.
|
||||
|
||||
|
||||
### Filter Column Names
|
||||
|
||||
The following filter column names are available in filter expressions:
|
||||
|
||||
|
||||
| Column |
|
||||
| ------------------------------------------------------------ |
|
||||
| instance_name |
|
||||
| host_name |
|
||||
| hostgroup_name |
|
||||
| service_description |
|
||||
| servicegroup_name |
|
||||
| + all custom variables prefixed with `_host_` or `_service_` |
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
# About the Translation Module <a id="translation-module-about"></a>
|
||||
|
||||
Please read the following chapters for more insights on this module:
|
||||
|
||||
* [Installation](02-Installation.md#translation-module-installation)
|
||||
* [Translations](03-Translation.md#module-translation-introduction)
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# Translation Module Installation <a id="translation-module-installation"></a>
|
||||
|
||||
This module is provided with the Icinga Web 2 package and does
|
||||
not need any extra installation step.
|
||||
|
||||
## Enable the Module <a id="translation-module-enable"></a>
|
||||
|
||||
Navigate to `Configuration` -> `Modules` -> `translation` and enable
|
||||
the module.
|
||||
|
||||
You can also enable the module during the setup wizard, or on the CLI:
|
||||
|
||||
```
|
||||
icingacli module enable translation
|
||||
```
|
||||
|
|
@ -1,14 +1,15 @@
|
|||
# Introduction
|
||||
# Introduction <a id="module-translation-introduction"></a>
|
||||
|
||||
Icinga Web 2 provides localization out of the box - for the core application and the modules, that means
|
||||
that you can with a lightness use existent localizations, update or even create you own localizations.
|
||||
|
||||
The chapters [Translation for Developers](Translation for Developers),
|
||||
[Translation for Translators](Translation for Translators) and [Testing Translations](Testing Translations) will
|
||||
introduce and explain you, how to take part on localizing Icinga Web 2 for different languages and how to use the
|
||||
The chapters [Translation for Developers](03-Translations.md#module-translation-developers),
|
||||
[Translation for Translators](03-Translations.md#module-translation-translators) and
|
||||
[Testing Translations](03-Translations.md#module-translation-tests) will introduce and explain you, how to take
|
||||
part on localizing Icinga Web 2 for different languages and how to use the
|
||||
`translation module` to make your life much easier.
|
||||
|
||||
# Translation for Developers
|
||||
## Translation for Developers <a id="module-translation-developers"></a>
|
||||
|
||||
To make use of the built-in translations in your applications code or views, you should use the method
|
||||
`$this->translate('String to be translated')`, let's have a look at an example:
|
||||
|
|
@ -26,7 +27,7 @@ class ExampleController extends Controller
|
|||
```
|
||||
|
||||
So if there a translation available for the `Hello World` string you will get an translated output, depends on the
|
||||
language which is setted in your configuration as the default language, if it is `de_DE` the output would be
|
||||
language which is set in your configuration as the default language, if it is `de_DE` the output would be
|
||||
`Hallo Welt`.
|
||||
|
||||
The same works also for views:
|
||||
|
|
@ -42,7 +43,7 @@ The same works also for views:
|
|||
If you need to provide placeholders in your messages, you should wrap the `$this->translate()` with `sprintf()` for e.g.
|
||||
sprintf($this->translate('Hello User: (%s)'), $user->getName())
|
||||
|
||||
## Translating plural forms
|
||||
### Translating plural forms <a id="module-translation-plural-forms"></a>
|
||||
|
||||
To provide a plural translation, just use the `translatePlural()` function.
|
||||
|
||||
|
|
@ -58,7 +59,7 @@ class ExampleController extends Controller
|
|||
}
|
||||
```
|
||||
|
||||
## Context based translation
|
||||
### Context based translation <a id="module-translation-context-based"></a>
|
||||
|
||||
If you want to provide context based translations, you can easily do it with an extra parameter in both methods
|
||||
`translate()` and `translatePlural()`.
|
||||
|
|
@ -76,7 +77,7 @@ class ExampleController extends Controller
|
|||
}
|
||||
```
|
||||
|
||||
# Translation for Translators
|
||||
## Translation for Translators <a id="module-translation-translators"></a>
|
||||
|
||||
Icinga Web 2 internally uses the UNIX standard gettext tool to perform internationalization, this means translation
|
||||
files in the .po file format are supplied for text strings used in the code.
|
||||
|
|
@ -84,33 +85,33 @@ files in the .po file format are supplied for text strings used in the code.
|
|||
There are a lot of tools and techniques to work with .po localization files, you can choose what ever you prefer. We
|
||||
won't let you alone on your first steps and therefore we'll introduce you a nice tool, called Poedit.
|
||||
|
||||
### Poedit
|
||||
### Poedit <a id="module-translation-translators-poedit"></a>
|
||||
|
||||
First of all, you have to download and install Poedit from http://poedit.net, when you are done, you have to do some
|
||||
configuration under the Preferences.
|
||||
First of all, you have to download and install [Poedit](http://poedit.net).
|
||||
When you are done, you have to configure Poedit.
|
||||
|
||||
#### Configuration
|
||||
#### Configuration <a id="module-translation-translators-poedit-configuration"></a>
|
||||
|
||||
__Personalize__: Please provide your Name and E-Mail under Identity.
|
||||
`Personalize`: Please provide your Name and E-Mail under Identity.
|
||||
|
||||
|
||||
|
||||
__Editor__: Under the Behavior the Automatically compile .mo files on save, should be disabled.
|
||||
`Editor`: Under the `Behavior` the Automatically compile .mo files on save, should be disabled.
|
||||
|
||||
|
||||
|
||||
__Translations Memory__: Under the Database please add your languages, for which are you writing translations.
|
||||
`Translations Memory`: Under the `Database` please add your languages, for which are you writing translations.
|
||||
|
||||
|
||||
|
||||
When you are done, just save your new settings.
|
||||
|
||||
#### Editing .po files
|
||||
#### Editing .po files <a id="module-translation-translators-poedit-edit-po-files"></a>
|
||||
|
||||
To work with Icinga Web 2 .po files, you can open for e.g. the german icinga.po file which is located under
|
||||
To work with Icinga Web 2 .po files, you can open for e.g. the German icinga.po file which is located under
|
||||
`application/locale/de_DE/LC_MESSAGES/icinga.po`, as shown below, you will get then a full list of all available
|
||||
translation strings for the core application. Each module names its translation files `%module_name%.po`. For a
|
||||
module called __yourmodule__ the .po translation file will be named `yourmodule.po`.
|
||||
module called `yourmodule` the .po translation file will be named `yourmodule.po`.
|
||||
|
||||
|
||||
|
||||
|
|
@ -123,77 +124,94 @@ below.
|
|||
And when you want to test your changes, please read more about under the chapter
|
||||
[Testing Translations](Testing Translations).
|
||||
|
||||
# Testing Translations
|
||||
## Testing Translations <a id="module-translation-tests"></a>
|
||||
|
||||
If you want to try out your translation changes in Icinga Web 2, you can make use of the the CLI translations commands.
|
||||
|
||||
** NOTE: Please make sure that the gettext package is installed **
|
||||
> **Note**:
|
||||
>
|
||||
> Please make sure that the gettext package is installed
|
||||
|
||||
To get an easier development with translations, you can activate the `translation module` which provides CLI commands,
|
||||
after that you would be able to refresh and compile your .po files.
|
||||
|
||||
|
||||
** NOTE: the ll_CC stands for ll=language and CC=country code for e.g de_DE, fr_FR, ru_RU, it_IT etc. **
|
||||
> **Note**
|
||||
>
|
||||
> The ll_CC stands for ll=language and CC=country code for e.g `de_DE`, `fr_FR`, `ru_RU`, `it_IT` etc.
|
||||
|
||||
## Application
|
||||
### Application <a id="module-translation-tests-application"></a>
|
||||
|
||||
To refresh the __icinga.po__:
|
||||
To refresh the `icinga.po` file:
|
||||
|
||||
icingacli translation refresh icinga ll_CC
|
||||
```
|
||||
icingacli translation refresh icinga ll_CC
|
||||
```
|
||||
|
||||
And to compile it:
|
||||
|
||||
icingacli translation compile icinga ll_CC
|
||||
```
|
||||
icingacli translation compile icinga ll_CC
|
||||
```
|
||||
|
||||
** NOTE: After a compile you need to restart the web server to get new translations available in your application. **
|
||||
> **Note**
|
||||
>
|
||||
> After a compile you need to restart the web server to get new translations available in your application.
|
||||
|
||||
## Modules
|
||||
### Modules <a id="module-translation-tests-modules"></a>
|
||||
|
||||
Let's assume, we want to provide german translations for our just new created module __yourmodule__.
|
||||
Let's assume, we want to provide German translations for our just new created module `yourmodule`.
|
||||
|
||||
If we haven't yet any translations strings in our .po file or even the .po file, we can use the CLI command, to do the
|
||||
job for us:
|
||||
|
||||
icingacli translation refresh module development ll_CC
|
||||
```
|
||||
icingacli translation refresh module development ll_CC
|
||||
```
|
||||
|
||||
This will go through all .php and .phtml files inside the module and a look after `$this->translate()` if there is
|
||||
something to translate - if there is something and is not available in the __yourmodule.po__ it will updates this file
|
||||
for us with new
|
||||
strings.
|
||||
something to translate - if there is something and is not available in the `yourmodule.po` it will update this file
|
||||
for us with new strings.
|
||||
|
||||
Now you can open the __yourmodule.po__ and you will see something similar:
|
||||
Now you can open the `yourmodule.po` and you will see something similar:
|
||||
|
||||
# Icinga Web 2 - Head for multiple monitoring backends.
|
||||
# Copyright (C) 2014 Icinga Development Team
|
||||
# This file is distributed under the same license as Development Module.
|
||||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: Development Module (0.0.1)\n"
|
||||
"Report-Msgid-Bugs-To: dev@icinga.com\n"
|
||||
"POT-Creation-Date: 2014-09-09 10:12+0200\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||||
"Language: ll_CC\n"
|
||||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=UTF-8\n"
|
||||
"Content-Transfer-Encoding: 8bit\n"
|
||||
```
|
||||
# Icinga Web 2 - Head for multiple monitoring backends.
|
||||
# Copyright (C) 2014 Icinga Development Team
|
||||
# This file is distributed under the same license as Development Module.
|
||||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: Development Module (0.0.1)\n"
|
||||
"Report-Msgid-Bugs-To: dev@icinga.com\n"
|
||||
"POT-Creation-Date: 2014-09-09 10:12+0200\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||||
"Language: ll_CC\n"
|
||||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=UTF-8\n"
|
||||
"Content-Transfer-Encoding: 8bit\n"
|
||||
|
||||
#: /modules/yourmodule/configuration.php:6
|
||||
msgid "yourmodule"
|
||||
msgstr ""
|
||||
#: /modules/yourmodule/configuration.php:6
|
||||
msgid "yourmodule"
|
||||
msgstr ""
|
||||
```
|
||||
|
||||
Great, now you can adjust the file and provide the german `msgstr` for `yourmodule`.
|
||||
Great, now you can adjust the file and provide the German `msgstr` for `yourmodule`.
|
||||
|
||||
#: /modules/yourmodule/configuration.php:6
|
||||
msgid "Dummy"
|
||||
msgstr "Attrappe"
|
||||
```
|
||||
#: /modules/yourmodule/configuration.php:6
|
||||
msgid "Dummy"
|
||||
msgstr "Attrappe"
|
||||
```
|
||||
|
||||
The last step is to compile the __yourmodule.po__ to the __yourmodule.mo__:
|
||||
The last step is to compile the `yourmodule.po` to the `yourmodule.mo`:
|
||||
|
||||
icingacli translation compile module development ll_CC
|
||||
```
|
||||
icingacli translation compile module development ll_CC
|
||||
```
|
||||
|
||||
At this moment, everywhere in the module where the `Dummy` should be translated, it would returns the translated
|
||||
string `Attrappe`.
|
||||
Loading…
Reference in New Issue