tyler.durden/icingaweb2
1
0
Fork 0
mirror of https://github.com/Icinga/icingaweb2.git synced 2025-07-24 22:34:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2890 from bobapple/fix/docs-header

Browse Source 
Update docs for better compatibility with mkdocs
This commit is contained in:
lippserd 2017-07-28 09:15:06 +02:00 committed by GitHub
commit 7f90ae4d89
9 changed files with 89 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/01-About.md
View File

@ -1,9 +1,9 @@
# <a id="about"></a> About Icinga Web 2 # About Icinga Web 2 <a id="about"></a>
Icinga Web 2 is a powerful PHP framework for web applications that comes in a clean and reduced design. 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. It's fast, responsive, accessible and easily extensible with modules.
## <a id="about-monitoring"></a> The monitoring module ## The monitoring module <a id="about-monitoring"></a>
This is the core module for most Icinga Web 2 users. This is the core module for most Icinga Web 2 users.
@ -14,20 +14,20 @@ 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. 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. Most such actions (like rescheduling a check) can be done with just a single click.
## <a id="about-installation"></a> Installation ## Installation <a id="about-installation"></a>
Icinga Web 2 can be installed easily from packages from the official package repositories. Icinga Web 2 can be installed easily from packages from the official package repositories.
Setting it up is also easy with the web based setup wizard. Setting it up is also easy with the web based setup wizard.
See [here](02-Installation.md#installation) for more information about the installation. See [here](02-Installation.md#installation) for more information about the installation.
## <a id="about-configuration"></a> Configuration ## Configuration <a id="about-configuration"></a>
Icinga Web 2 can be configured via the user interface and .ini files. Icinga Web 2 can be configured via the user interface and .ini files.
See [here](03-Configuration.md#configuration) for more information about the configuration. See [here](03-Configuration.md#configuration) for more information about the configuration.
## <a id="about-authentication"></a> Authentication ## Authentication <a id="about-authentication"></a>
With Icinga Web 2 you can authenticate against relational databases, LDAP and more. With Icinga Web 2 you can authenticate against relational databases, LDAP and more.
These authentication methods can be easily configured (via the corresponding .ini file). These authentication methods can be easily configured (via the corresponding .ini file).
@ -35,7 +35,7 @@ These authentication methods can be easily configured (via the corresponding .in
See [here](05-Authentication.md#authentication) for more information about See [here](05-Authentication.md#authentication) for more information about
the different authentication methods available and how to configure them. the different authentication methods available and how to configure them.
## <a id="about-authorization"></a> Authorization ## Authorization <a id="about-authorization"></a>
In Icinga Web 2 there are permissions and restrictions to allow and deny (respectively) In Icinga Web 2 there are permissions and restrictions to allow and deny (respectively)
roles to view or to do certain things. roles to view or to do certain things.
@ -44,7 +44,7 @@ These roles can be assigned to users and groups.
See [here](06-Security.md#security) for more information about authorization See [here](06-Security.md#security) for more information about authorization
and how to configure roles. and how to configure roles.
## <a id="about-preferences"></a> User preferences ## User preferences <a id="about-preferences"></a>
Besides the global configuration each user has individual configuration options Besides the global configuration each user has individual configuration options
like the interface's language or the current timezone. like the interface's language or the current timezone.
@ -53,13 +53,13 @@ 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 See [here](07-Preferences.md#preferences) for more information about a user's preferences
and how to configure their storage type. and how to configure their storage type.
## <a id="about-documentation"></a> Documentation ## 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. With the documentation module you can read the documentation of the framework (and any module) directly in the user interface.
The module can also export the documentation to PDF. The module can also export the documentation to PDF.
## <a id="about-translation"></a> Translation ## 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. 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.

60
doc/02-Installation.md
View File

@ -1,4 +1,4 @@
# <a id="installation"></a> Installation # Installation <a id="installation"></a>
The preferred way of installing Icinga Web 2 is to use the official package repositories depending on which operating The preferred way of installing Icinga Web 2 is to use the official package repositories depending on which operating
system and distribution you are running. But it is also possible to install Icinga Web 2 directly from source. system and distribution you are running. But it is also possible to install Icinga Web 2 directly from source.
@ -7,7 +7,7 @@ In case you are upgrading from an older version of Icinga Web 2
please make sure to read the [upgrading](02-Installation.md#upgrading) section please make sure to read the [upgrading](02-Installation.md#upgrading) section
thoroughly. thoroughly.
## <a id="installing-requirements"></a> Installing Requirements ## Installing Requirements <a id="installing-requirements"></a>
* A web server, e.g. Apache or nginx * A web server, e.g. Apache or nginx
* PHP >= 5.3.0 w/ gettext, intl, mbstring and OpenSSL support * PHP >= 5.3.0 w/ gettext, intl, mbstring and OpenSSL support
@ -18,7 +18,7 @@ thoroughly.
* MySQL or PostgreSQL PHP libraries * 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 for transmitting external commands
### <a id="pagespeed-incompatibility"></a> PageSpeed Module Incompatibility ### PageSpeed Module Incompatibility <a id="pagespeed-incompatibility"></a>
It seems that Web 2 is not compatible with the PageSpeed module. Please disable the PageSpeed module using one of the It seems that Web 2 is not compatible with the PageSpeed module. Please disable the PageSpeed module using one of the
following methods. following methods.
@ -33,7 +33,7 @@ ModPagespeedDisallow "*/icingaweb2/*"
pagespeed Disallow "*/icingaweb2/*"; pagespeed Disallow "*/icingaweb2/*";
``` ```
## <a id="installing-from-package"></a> Installing Icinga Web 2 from Package ## Installing Icinga Web 2 from Package <a id="installing-from-package"></a>
Below is a list of official package repositories for installing Icinga Web 2 for various operating systems. Below is a list of official package repositories for installing Icinga Web 2 for various operating systems.
@ -52,7 +52,7 @@ Below is a list of official package repositories for installing Icinga Web 2 for
Packages for distributions other than the ones listed above may also be available. Packages for distributions other than the ones listed above may also be available.
Please contact your distribution packagers. Please contact your distribution packagers.
### <a id="package-repositories"></a> Setting up Package Repositories ### Setting up Package Repositories <a id="package-repositories"></a>
You need to add the Icinga repository to your package management configuration for installing Icinga Web 2. You need to add the Icinga repository to your package management configuration for installing Icinga Web 2.
If you've already configured your OS to use the Icinga repository for installing Icinga 2, you may skip this step. If you've already configured your OS to use the Icinga repository for installing Icinga 2, you may skip this step.
@ -119,7 +119,7 @@ apk update
> >
> Latest version of Icinga Web 2 is in the edge repository, which is the -dev branch. > Latest version of Icinga Web 2 is in the edge repository, which is the -dev branch.
#### <a id="package-repositories-rhel-notes"></a> RHEL/CentOS Notes #### RHEL/CentOS Notes <a id="package-repositories-rhel-notes"></a>
The packages for RHEL/CentOS depend on other packages which are distributed as part of the The packages for RHEL/CentOS depend on other packages which are distributed as part of the
[EPEL repository](http://fedoraproject.org/wiki/EPEL). Please make sure to enable this repository by following [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please make sure to enable this repository by following
@ -128,14 +128,14 @@ The packages for RHEL/CentOS depend on other packages which are distributed as p
> Please note that installing Icinga Web 2 on **RHEL/CentOS 5** is not supported due to EOL versions of PHP and PostgreSQL. > Please note that installing Icinga Web 2 on **RHEL/CentOS 5** is not supported due to EOL versions of PHP and PostgreSQL.
#### <a id="package-repositories-alpine-notes"></a> Alpine Linux Notes #### Alpine Linux Notes <a id="package-repositories-alpine-notes"></a>
The example provided suppose that you are running Alpine edge, which is the -dev branch and is a rolling release. The example provided suppose that you are running Alpine edge, which is the -dev branch and is a rolling release.
If you are using a stable version, in order to use the latest Icinga Web 2 version you should "pin" the edge repository. If you are using a stable version, in order to use the latest Icinga Web 2 version you should "pin" the edge repository.
In order to correctly manage your repository, please follow In order to correctly manage your repository, please follow
[these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management). [these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management).
### <a id="installing-from-package-example"></a> Installing Icinga Web 2 ### Installing Icinga Web 2 <a id="installing-from-package-example"></a>
You can install Icinga Web 2 by using your distribution's package manager to install the `icingaweb2` package. You can install Icinga Web 2 by using your distribution's package manager to install the `icingaweb2` package.
Below is a list with examples for various distributions. The additional package `icingacli` is necessary on RPM based systems for being able to follow further steps in this guide. In DEB based systems, the icingacli binary is included in the icingaweb2 package. Below is a list with examples for various distributions. The additional package `icingacli` is necessary on RPM based systems for being able to follow further steps in this guide. In DEB based systems, the icingacli binary is included in the icingaweb2 package.
@ -162,7 +162,7 @@ apk add icingaweb2
``` ```
For Alpine Linux please read the [package repositories notes](#package-repositories-alpine-notes). For Alpine Linux please read the [package repositories notes](#package-repositories-alpine-notes).
### <a id="preparing-web-setup-from-package"></a> Preparing Web Setup ### Preparing Web Setup <a id="preparing-web-setup-from-package"></a>
You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time
you visit Icinga Web 2 in your browser. When using the web setup you are required to authenticate using a token. you visit Icinga Web 2 in your browser. When using the web setup you are required to authenticate using a token.
@ -179,12 +179,12 @@ icingacli setup token show
Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation:
`/icingaweb2/setup`. `/icingaweb2/setup`.
## <a id="installing-from-source"></a> Installing Icinga Web 2 from Source ## Installing Icinga Web 2 from Source <a id="installing-from-source"></a>
Although the preferred way of installing Icinga Web 2 is to use packages, it is also possible to install Icinga Web 2 Although the preferred way of installing Icinga Web 2 is to use packages, it is also possible to install Icinga Web 2
directly from source. directly from source.
### <a id="getting-the-source"></a> Getting the Source ### Getting the Source <a id="getting-the-source"></a>
First of all, you need to download the sources. Icinga Web 2 is available through a Git repository. You can clone this First of all, you need to download the sources. Icinga Web 2 is available through a Git repository. You can clone this
repository either via git or http protocol using the following URLs: repository either via git or http protocol using the following URLs:
@ -200,7 +200,7 @@ This version also offers snapshots for easy download which you can use if you do
git clone git://git.icinga.com/icingaweb2.git git clone git://git.icinga.com/icingaweb2.git
``` ```
### <a id="installing-from-source-requirements"></a> Installing Requirements from Source ### Installing Requirements from Source <a id="installing-from-source-requirements"></a>
You will need to install certain dependencies depending on your setup listed [here](02-Installation.md#installing-requirements). You will need to install certain dependencies depending on your setup listed [here](02-Installation.md#installing-requirements).
@ -217,7 +217,7 @@ yum install php php-gd php-intl php-ZendFramework php-ZendFramework-Db-Adapter-P
The setup wizard will check the pre-requisites later on. The setup wizard will check the pre-requisites later on.
### <a id="installing-from-source-example"></a> Installing Icinga Web 2 ### Installing Icinga Web 2 <a id="installing-from-source-example"></a>
Choose a target directory and move Icinga Web 2 there. Choose a target directory and move Icinga Web 2 there.
@ -225,7 +225,7 @@ Choose a target directory and move Icinga Web 2 there.
mv icingaweb2 /usr/share/icingaweb2 mv icingaweb2 /usr/share/icingaweb2
``` ```
### <a id="configuring-web-server"></a> Configuring the Web Server ### Configuring the Web Server <a id="configuring-web-server"></a>
Use `icingacli` to generate web server configuration for either Apache or nginx. Use `icingacli` to generate web server configuration for either Apache or nginx.
@ -261,7 +261,7 @@ Example for Apache on Alpine Linux:
``` ```
icingacli setup config webserver apache --document-root /usr/share/webapps/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf icingacli setup config webserver apache --document-root /usr/share/webapps/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf
``` ```
### <a id="preparing-web-setup-from-source"></a> Preparing Icinga Web 2 Setup ### Preparing Icinga Web 2 Setup <a id="preparing-web-setup-from-source"></a>
You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time You can set up Icinga Web 2 quickly and easily with the Icinga Web 2 setup wizard which is available the first time
you visit Icinga Web 2 in your browser. Please follow the steps listed below for preparing the web setup. you visit Icinga Web 2 in your browser. Please follow the steps listed below for preparing the web setup.
@ -326,7 +326,7 @@ In case you do not remember the token you can show it using the `icingacli`:
./bin/icingacli setup token show ./bin/icingacli setup token show
``` ```
### <a id="web-setup-from-source-wizard"></a> Icinga Web 2 Setup Wizard ### Icinga Web 2 Setup Wizard <a id="web-setup-from-source-wizard"></a>
Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation:
`/icingaweb2/setup`. `/icingaweb2/setup`.
@ -334,7 +334,7 @@ Finally visit Icinga Web 2 in your browser to access the setup wizard and comple
Paste the previously generated token and follow the steps on-screen. Then you are done here. Paste the previously generated token and follow the steps on-screen. Then you are done here.
### <a id="web-setup-manual-from-source"></a> Icinga Web 2 Manual Setup ### Icinga Web 2 Manual Setup <a id="web-setup-manual-from-source"></a>
If you have chosen not to run the setup wizard, you will need further knowledge If you have chosen not to run the setup wizard, you will need further knowledge
about about
@ -354,7 +354,7 @@ Puppet, Ansible, Chef, etc. modules.
> If you are unsure about certain settings, use the [setup wizard](02-Installation.md#web-setup-wizard-from-source) once > If you are unsure about certain settings, use the [setup wizard](02-Installation.md#web-setup-wizard-from-source) once
> and then collect the generated configuration as well as sql dumps. > and then collect the generated configuration as well as sql dumps.
#### <a id="web-setup-manual-from-source-database"></a> Icinga Web 2 Manual Database Setup #### Icinga Web 2 Manual Database Setup <a id="web-setup-manual-from-source-database"></a>
Create the database and add a new user as shown below for MySQL: Create the database and add a new user as shown below for MySQL:
@ -379,7 +379,7 @@ INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin',
quit quit
``` ```
#### <a id="web-setup-manual-from-source-config"></a> Icinga Web 2 Manual Configuration #### Icinga Web 2 Manual Configuration <a id="web-setup-manual-from-source-config"></a>
[resources.ini](04-Resources.md#resources) providing the details for the Icinga Web 2 and [resources.ini](04-Resources.md#resources) providing the details for the Icinga Web 2 and
@ -445,7 +445,7 @@ users = "icingaadmin"
permissions = "*" permissions = "*"
``` ```
#### <a id="web-setup-manual-from-source-config-monitoring-module"></a> Icinga Web 2 Manual Configuration Monitoring Module #### Icinga Web 2 Manual Configuration Monitoring Module <a id="web-setup-manual-from-source-config-monitoring-module"></a>
**config.ini** defining additional security settings. **config.ini** defining additional security settings.
@ -477,33 +477,33 @@ transport = "local"
path = "/var/run/icinga2/cmd/icinga2.cmd" path = "/var/run/icinga2/cmd/icinga2.cmd"
``` ```
#### <a id="web-setup-manual-from-source-login"></a> Icinga Web 2 Manual Setup Login #### Icinga Web 2 Manual Setup Login <a id="web-setup-manual-from-source-login"></a>
Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`. Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`.
## <a id="upgrading"></a> Upgrading Icinga Web 2 ## Upgrading Icinga Web 2 <a id="upgrading"></a>
### <a id="upgrading-to-2.4.x"></a> Upgrading to Icinga Web 2 2.4.x ### Upgrading to Icinga Web 2 2.4.x <a id="upgrading-to-2.4.x"></a>
* Icinga Web 2 version 2.4.x does not introduce any backward incompatible change. * Icinga Web 2 version 2.4.x does not introduce any backward incompatible change.
### <a id="upgrading-to-2.3.x"></a> Upgrading to Icinga Web 2 2.3.x ### Upgrading to Icinga Web 2 2.3.x <a id="upgrading-to-2.3.x"></a>
* Icinga Web 2 version 2.3.x does not introduce any backward incompatible change. * Icinga Web 2 version 2.3.x does not introduce any backward incompatible change.
### <a id="upgrading-to-2.2.0"></a> Upgrading to Icinga Web 2 2.2.0 ### Upgrading to Icinga Web 2 2.2.0 <a id="upgrading-to-2.2.0"></a>
* The menu entry `Authorization` beneath `Config` has been renamed to `Authentication`. The role, user backend and user * The menu entry `Authorization` beneath `Config` has been renamed to `Authentication`. The role, user backend and user
group backend configuration which was previously found beneath `Authentication` has been moved to `Application`. group backend configuration which was previously found beneath `Authentication` has been moved to `Application`.
### <a id="upgrading-to-2.1.x"></a> Upgrading to Icinga Web 2 2.1.x ### Upgrading to Icinga Web 2 2.1.x <a id="upgrading-to-2.1.x"></a>
* Since Icinga Web 2 version 2.1.3 LDAP user group backends respect the configuration option `group_filter`. * Since Icinga Web 2 version 2.1.3 LDAP user group backends respect the configuration option `group_filter`.
Users who changed the configuration manually and used the option `filter` instead Users who changed the configuration manually and used the option `filter` instead
have to change it back to `group_filter`. have to change it back to `group_filter`.
### <a id="upgrading-to-2.0.0"></a> Upgrading to Icinga Web 2 2.0.0 ### Upgrading to Icinga Web 2 2.0.0 <a id="upgrading-to-2.0.0"></a>
* Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through * Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through
the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library
@ -525,7 +525,7 @@ Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/ici
**&lt;config-dir&gt;/preferences/&lt;username&gt;/config.ini**. **&lt;config-dir&gt;/preferences/&lt;username&gt;/config.ini**.
The content of the file remains unchanged. The content of the file remains unchanged.
### <a id="upgrading-to-rc1"></a> Upgrading to Icinga Web 2 Release Candidate 1 ### Upgrading to Icinga Web 2 Release Candidate 1 <a id="upgrading-to-rc1"></a>
The first release candidate of Icinga Web 2 introduces the following non-backward compatible changes: The first release candidate of Icinga Web 2 introduces the following non-backward compatible changes:
@ -544,12 +544,12 @@ The first release candidate of Icinga Web 2 introduces the following non-backwar
predefined subset of filter columns. Please see the module's security predefined subset of filter columns. Please see the module's security
related documentation for more details. related documentation for more details.
### <a id="upgrading-to-beta3"></a> Upgrading to Icinga Web 2 Beta 3 ### Upgrading to Icinga Web 2 Beta 3 <a id="upgrading-to-beta3"></a>
Because Icinga Web 2 Beta 3 does not introduce any backward incompatible change you don't have to change your Because Icinga Web 2 Beta 3 does not introduce any backward incompatible change you don't have to change your
configuration files after upgrading to Icinga Web 2 Beta 3. configuration files after upgrading to Icinga Web 2 Beta 3.
### <a id="upgrading-to-beta2"></a> Upgrading to Icinga Web 2 Beta 2 ### Upgrading to Icinga Web 2 Beta 2 <a id="upgrading-to-beta2"></a>
Icinga Web 2 Beta 2 introduces access control based on roles for secured actions. If you've already set up Icinga Web 2, Icinga Web 2 Beta 2 introduces access control based on roles for secured actions. If you've already set up Icinga Web 2,
you are required to create the file **roles.ini** beneath Icinga Web 2's configuration directory with the following you are required to create the file **roles.ini** beneath Icinga Web 2's configuration directory with the following

6
doc/03-Configuration.md
View File

@ -1,6 +1,6 @@
# <a id="configuration"></a> Configuration # Configuration <a id="configuration"></a>
## <a id="configuration-overview"></a> Overview ## Overview <a id="configuration-overview"></a>
Apart from its web configuration capabilities, the local configuration is 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 config setup).
@ -8,7 +8,7 @@ stored in `/etc/icingaweb2` by default (depending on your config setup).
| File/Directory | Description/Purpose | | File/Directory | Description/Purpose |
| ------------------------------------------------- | ------------------- | | ------------------------------------------------- | ------------------- |
| **config.ini** | general configuration (logging, preferences, etc.) | | **config.ini** | general configuration (logging, preferences, etc.) |
| [**resources.ini**](04-Ressources.md) | global resources (Icinga Web 2 database for preferences and authentication, Icinga IDO database) | | [**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 | | **roles.ini** | user specific roles (e.g. `administrators`) and permissions |
| [**authentication.ini**](05-Authentication.md) | authentication backends (e.g. database) | | [**authentication.ini**](05-Authentication.md) | authentication backends (e.g. database) |
| **enabledModules** | contains symlinks to enabled modules | | **enabledModules** | contains symlinks to enabled modules |

16
doc/04-Resources.md
View File

@ -1,17 +1,17 @@
# <a id="resources"></a> Resources # 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 `config/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 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.
## <a id="resources-configuration"></a> Configuration ## 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 `config/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. 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*, *ssh* and *livestatus* which will described in detail in the following
paragraphs. paragraphs.
### <a id="resources-configuration-database"></a> Database ### Database <a id="resources-configuration-database"></a>
A Database resource defines a connection to a SQL databases which can contain users and groups 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. to handle authentication and authorization, monitoring data or user preferences.
@ -27,7 +27,7 @@ to handle authentication and authorization, monitoring data or user preferences.
| **dbname** | The database to use. | | **dbname** | The database to use. |
| **charset** | The character set to use for the database connection. | | **charset** | The character set to use for the database connection. |
#### <a id="resources-configuration-database-example"></a> Example #### Example <a id="resources-configuration-database-example"></a>
``` ```
[icingaweb-mysql-tcp] [icingaweb-mysql-tcp]
@ -57,7 +57,7 @@ password = icingaweb
dbname = icingaweb dbname = icingaweb
``` ```
### <a id="resources-configuration-ldap"></a> LDAP ### 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.
@ -71,7 +71,7 @@ A LDAP resource represents a tree in a LDAP directory. LDAP is usually used for
| **bind_pw** | The password 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`. | | **encryption** | Type of encryption to use: `none` (default), `starttls`, `ldaps`. |
#### <a id="resources-configuration-ldap-example"></a> Example #### Example <a id="resources-configuration-ldap-example"></a>
``` ```
[ad] [ad]
@ -83,7 +83,7 @@ bind_dn = "cn=admin,ou=people,dc=icinga,dc=org"
bind_pw = admin bind_pw = admin
``` ```
### <a id="resources-configuration-ssh"></a> SSH ### SSH <a id="resources-configuration-ssh"></a>
A SSH resource contains the information about the user and the private key location, which can be used for the key-based A SSH resource contains the information about the user and the private key location, which can be used for the key-based
ssh authentication. ssh authentication.
@ -94,7 +94,7 @@ ssh authentication.
| **user** | The username to use when connecting to the server. | | **user** | The username to use when connecting to the server. |
| **private_key** | The path to the private key of the user. | | **private_key** | The path to the private key of the user. |
#### <a id="resources-configuration-ssh-example"></a> Example #### Example <a id="resources-configuration-ssh-example"></a>
``` ```

28
doc/05-Authentication.md
View File

@ -1,4 +1,4 @@
# <a id="authentication"></a> Authentication # Authentication <a id="authentication"></a>
**Choosing the Authentication Method** **Choosing the Authentication Method**
@ -8,7 +8,7 @@ authentication to the web server.
Authentication methods can be chained to set up fallback authentication methods Authentication methods can be chained to set up fallback authentication methods
or if users are spread over multiple places. or if users are spread over multiple places.
## <a id="authentication-configuration"></a> Configuration ## Configuration <a id="authentication-configuration"></a>
Authentication methods are configured in the INI file **config/authentication.ini**. Authentication methods are configured in the INI file **config/authentication.ini**.
@ -18,7 +18,7 @@ The order of entries in the authentication configuration determines the order of
If the current authentication method errors or if the current authentication method does not know the account being If the current authentication method errors or if the current authentication method does not know the account being
authenticated, the next authentication method will be used. authenticated, the next authentication method will be used.
## <a id="authentication-configuration-external-authentication"></a> External Authentication ## External Authentication <a id="authentication-configuration-external-authentication"></a>
For delegating authentication to the web server simply add `autologin` to your authentication configuration: For delegating authentication to the web server simply add `autologin` to your authentication configuration:
@ -29,7 +29,7 @@ backend = external
If your web server is not configured for authentication though, the `autologin` section has no effect. If your web server is not configured for authentication though, the `autologin` section has no effect.
### <a id="authentication-configuration-external-authentication-example"></a> Example Configuration for Apache and Basic Authentication ### 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 The following example will show you how to enable external authentication in Apache
using **Basic access authentication**. using **Basic access authentication**.
@ -60,13 +60,13 @@ Require valid-user
Restart your web server to apply the changes. Restart your web server to apply the changes.
## <a id="authentication-configuration-ad-or-ldap-authentication"></a> Active Directory or LDAP Authentication ## 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 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 [LDAP resource](04-Resources.md#resources-configuration-ldap) which will be referenced as data source for the
Active Directory or LDAP configuration method. Active Directory or LDAP configuration method.
### <a id="authentication-configuration-ldap-authentication"></a> LDAP ### LDAP <a id="authentication-configuration-ldap-authentication"></a>
| Directive | Description | | Directive | Description |
| ------------------------- | ----------- | | ------------------------- | ----------- |
@ -91,7 +91,7 @@ Note that in case the set *user_name_attribute* holds multiple values it is requ
values are unique. Additionally, a user will be logged in using the exact user id used to authenticate 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. with Icinga Web 2 (e.g. an alias) no matter what the primary user id might actually be.
### <a id="authentication-configuration-ad-authentication"></a> Active Directory ### Active Directory <a id="authentication-configuration-ad-authentication"></a>
| Directive | Description | | Directive | Description |
| ------------- | ----------- | | ------------- | ----------- |
@ -106,7 +106,7 @@ backend = msldap
resource = my_ad resource = my_ad
``` ```
## <a id="authentication-configuration-db-authentication"></a> Database Authentication ## Database Authentication <a id="authentication-configuration-db-authentication"></a>
If you want to authenticate against a MySQL or a PostgreSQL database, you have to define a If you want to authenticate against a MySQL or a PostgreSQL database, you have to define a
[database resource](04-Resources.md#resources-configuration-database) which will be referenced as data source for the database [database resource](04-Resources.md#resources-configuration-database) which will be referenced as data source for the database
@ -125,7 +125,7 @@ backend = db
resource = icingaweb-mysql resource = icingaweb-mysql
``` ```
### <a id="authentication-configuration-db-setup"></a> Database Setup ### Database Setup <a id="authentication-configuration-db-setup"></a>
For authenticating against a database, you have to import one of the following database schemas: For authenticating against a database, you have to import one of the following database schemas:
@ -151,7 +151,7 @@ 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'); INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, 'hash from openssl');
``` ```
## <a id="domain-aware-auth"></a> Domain-aware Authentication ## 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 If there are multiple LDAP/AD authentication backends with distinct domains, you should make Icinga Web 2 aware of the
domains. This is possible since version 2.5 and can be done by configuring each LDAP/AD backend's domain. You can also domains. This is possible since version 2.5 and can be done by configuring each LDAP/AD backend's domain. You can also
@ -184,7 +184,7 @@ converted to "rroe@EXAMPLE" as soon as the user logs in.
Enabling domain-awareness or changing domains in existing setups requires migration of the usernames in the Icinga Web 2 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. configuration. Consult `icingacli --help migrate config users` for details.
### <a id="default-auth-domain"></a> Default Domain ### Default Domain <a id="default-auth-domain"></a>
For the sake of simplicity a default domain can be configured (in `config.ini`). For the sake of simplicity a default domain can be configured (in `config.ini`).
@ -198,15 +198,15 @@ default_domain = "icinga.com"
If you configure the default domain like above, the user "jdoe@icinga.com" will be able to just type "jdoe" as username If you configure the default domain like above, the user "jdoe@icinga.com" will be able to just type "jdoe" as username
while logging in. while logging in.
### <a id="domain-aware-auth-process"></a> How it works ### How it works <a id="domain-aware-auth-process"></a>
### <a id="domain-aware-auth-ad"></a> Active Directory ### Active Directory <a id="domain-aware-auth-ad"></a>
When the user "jdoe@ICINGA" logs in, Icinga Web 2 walks through all configured authentication backends until it finds When the user "jdoe@ICINGA" logs in, Icinga Web 2 walks through all configured authentication backends until it finds
one which is responsible for that user -- e.g. an Active Directory backend with the domain "ICINGA". Then Icinga Web 2 one which is responsible for that user -- e.g. an Active Directory backend with the domain "ICINGA". Then Icinga Web 2
asks that backend to authenticate the user with the sAMAccountName "jdoe". asks that backend to authenticate the user with the sAMAccountName "jdoe".
### <a id="domain-aware-auth-sqldb"></a> SQL Database ### SQL Database <a id="domain-aware-auth-sqldb"></a>
When the user "jdoe@icinga.com" logs in, Icinga Web 2 walks through all configured authentication backends until it When the user "jdoe@icinga.com" logs in, Icinga Web 2 walks through all configured authentication backends until it
finds one which is responsible for that user -- e.g. a MySQL backend (SQL database backends aren't domain-aware). Then finds one which is responsible for that user -- e.g. a MySQL backend (SQL database backends aren't domain-aware). Then

18
doc/06-Security.md
View File

@ -1,4 +1,4 @@
# <a id="security"></a> Security # Security <a id="security"></a>
Access control is a vital part of configuring Icinga Web 2 in a secure way. Access control is a vital part of configuring Icinga Web 2 in a secure way.
It is important that not every user that has access to Icinga Web 2 is able It is important that not every user that has access to Icinga Web 2 is able
@ -11,7 +11,7 @@ environment they are in charge of.
This chapter will describe how to do the security configuration of Icinga Web 2 This chapter will describe how to do the security configuration of Icinga Web 2
and how to apply permissions and restrictions to users or groups of users. and how to apply permissions and restrictions to users or groups of users.
## <a id="security-basics"></a> Basics ## Basics <a id="security-basics"></a>
Icinga Web 2 access control is done by defining **roles** that associate permissions Icinga Web 2 access control is done by defining **roles** that associate permissions
and restrictions with **users** and **groups**. There are two general kinds of and restrictions with **users** and **groups**. There are two general kinds of
@ -28,7 +28,7 @@ A permission is a simple list of identifiers of actions a user is
allowed to do. Permissions are described in greater detail in the allowed to do. Permissions are described in greater detail in the
section [Permissions](#permissions). section [Permissions](#permissions).
### <a id="security-basics-objects"></a> Objects ### Objects <a id="security-basics-objects"></a>
There are all kinds of different objects in Icinga Web 2: Hosts, Services, Notifications, Downtimes and Events. There are all kinds of different objects in Icinga Web 2: Hosts, Services, Notifications, Downtimes and Events.
@ -118,7 +118,7 @@ allows the hosts and services that match the filter `host_name=*win*` to be disp
by this role. by this role.
#### <a id="syntax"></a> Syntax #### Syntax <a id="syntax"></a>
Each role is defined as a section, with the name of the role as section name. The following Each role is defined as a section, with the name of the role as section name. The following
attributes can be defined for each role in a default Icinga Web 2 installation: attributes can be defined for each role in a default Icinga Web 2 installation:
@ -133,7 +133,7 @@ attributes can be defined for each role in a default Icinga Web 2 installation:
## <a id="permissions"></a> Permissions ## Permissions <a id="permissions"></a>
Permissions can be used to allow users or groups certain **actions**. By default, Permissions can be used to allow users or groups certain **actions**. By default,
all actions are **prohibited** and must be allowed explicitly by a role for any user. all actions are **prohibited** and must be allowed explicitly by a role for any user.
@ -153,7 +153,7 @@ a module permission in the format `module/<moduleName>` for each installed modul
When multiple roles assign permissions to the same user (either directly or indirectly When multiple roles assign permissions to the same user (either directly or indirectly
through a group) all permissions are added together to get the users actual permission set. through a group) all permissions are added together to get the users actual permission set.
### <a id="permissions-global"></a> Global Permissions ### Global Permissions <a id="permissions-global"></a>
| Name | Permits | | Name | Permits |
| ----------------------------- | ------------ | | ----------------------------- | ------------ |
@ -163,13 +163,13 @@ through a group) all permissions are added together to get the users actual perm
| **module/&lt;moduleName&gt;** | allow access to module &lt;moduleName&gt; | | **module/&lt;moduleName&gt;** | allow access to module &lt;moduleName&gt; |
### <a id="permissions-module"></a> Monitoring Module Permissions ### Monitoring Module Permissions <a id="permissions-module"></a>
The built-in monitoring module defines an additional set of permissions, that The built-in monitoring module defines an additional set of permissions, that
is described in detail in the monitoring module documentation. is described in detail in the monitoring module documentation.
## <a id="restrictions"></a> Restrictions ## Restrictions <a id="restrictions"></a>
Restrictions can be used to define what a user or group can see by specifying Restrictions can be used to define what a user or group can see by specifying
a filter expression that applies to a defined set of data. By default, when no a filter expression that applies to a defined set of data. By default, when no
@ -213,7 +213,7 @@ results of this query instead:
+--- service_handled = 0 +--- service_handled = 0
#### <a id="stacking-filters"></a> Stacking Filters #### Stacking Filters <a id="stacking-filters"></a>
When multiple roles assign restrictions to the same user, either directly or indirectly When multiple roles assign restrictions to the same user, either directly or indirectly
through a group, all filters will be combined using an **OR-Clause**, resulting in the final through a group, all filters will be combined using an **OR-Clause**, resulting in the final

10
doc/07-Preferences.md
View File

@ -1,4 +1,4 @@
# <a id="preferences"></a> Preferences # Preferences <a id="preferences"></a>
Preferences are settings a user can set for his account only, for example his language and time zone. Preferences are settings a user can set for his account only, for example his language and time zone.
@ -7,11 +7,11 @@ Preferences are settings a user can set for his account only, for example his la
Preferences can be stored either in INI files or in a MySQL or in a PostgreSQL database. By default, Icinga Web 2 stores 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. preferences in INI files beneath Icinga Web 2's configuration directory.
## <a id="preferences-configuration"></a> Configuration ## Configuration <a id="preferences-configuration"></a>
Where to store preferences is defined in the INI file **config/config.ini** in the *preferences* section. Where to store preferences is defined in the INI file **config/config.ini** in the *preferences* section.
### <a id="preferences-configuration-ini"></a> Store Preferences in INI Files ### Store Preferences in INI Files <a id="preferences-configuration-ini"></a>
If preferences are stored in INI Files, Icinga Web 2 automatically creates one file per user using the username as If preferences are stored in INI Files, Icinga Web 2 automatically creates one file per user using the username as
file name for storing preferences. A INI file is created once a user saves changed preferences the first time. file name for storing preferences. A INI file is created once a user saves changed preferences the first time.
@ -24,7 +24,7 @@ For storing preferences in INI files you have to add the following section to th
type = ini type = ini
``` ```
### <a id="preferences-configuration-db"></a> Store Preferences in a Database ### Store Preferences in a Database <a id="preferences-configuration-db"></a>
In order to be more flexible in distributed setups you can store preferences in a MySQL or in a PostgreSQL database. In order to be more flexible in distributed setups you can store preferences in a MySQL or in a PostgreSQL database.
For storing preferences in a database, you have to define a [database resource](04-Resources.md#resources-configuration-database) For storing preferences in a database, you have to define a [database resource](04-Resources.md#resources-configuration-database)
@ -43,7 +43,7 @@ type = db
resource = icingaweb-mysql resource = icingaweb-mysql
``` ```
#### <a id="preferences-configuration-db-setup"></a> Database Setup #### 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: For storing preferences in a database, you have to import one of the following database schemas:

20
doc/90-SELinux.md
View File

@ -1,6 +1,6 @@
# <a id="selinux"></a> SELinux # SELinux <a id="selinux"></a>
## <a id="selinux-introduction"></a> Introduction ## Introduction <a id="selinux-introduction"></a>
SELinux is a mandatory access control (MAC) system on Linux which adds a fine granular permission system for access SELinux is a mandatory access control (MAC) system on Linux which adds a fine granular permission system for access
to all resources on the system such as files, devices, networks and inter-process communication. to all resources on the system such as files, devices, networks and inter-process communication.
@ -11,7 +11,7 @@ For more details on SELinux and how to actually use and administrate it on your
For a simplified (and funny) introduction download the [SELinux Coloring Book](https://github.com/mairin/selinux-coloring-book). For a simplified (and funny) introduction download the [SELinux Coloring Book](https://github.com/mairin/selinux-coloring-book).
## <a id="selinux-policy"></a> Policy ## Policy <a id="selinux-policy"></a>
Icinga Web 2 is providing its own SELinux policy for Red Hat Enterprise Linux 7 and its derivates running the targeted Icinga Web 2 is providing its own SELinux policy for Red Hat Enterprise Linux 7 and its derivates running the targeted
policy which confines Icinga Web 2 with support for all its modules. All other distributions will require some tweaks. policy which confines Icinga Web 2 with support for all its modules. All other distributions will require some tweaks.
@ -20,7 +20,7 @@ It is not upstreamed to the reference policies yet.
The policy for Icinga Web 2 will also require the policy for Icinga 2 which provides access to its interfaces. The policy for Icinga Web 2 will also require the policy for Icinga 2 which provides access to its interfaces.
It covers only the scenario running Icinga Web 2 in Apache HTTP Server with mod_php. It covers only the scenario running Icinga Web 2 in Apache HTTP Server with mod_php.
## <a id="selinux-policy-installation"></a> Installation ## Installation <a id="selinux-policy-installation"></a>
There are two ways to install the SELinux Policy for Icinga Web 2 on Enterprise Linux 7. There are two ways to install the SELinux Policy for Icinga Web 2 on Enterprise Linux 7.
Either install it from the provided package which is the preferred option or intall the policy manually, if you need Either install it from the provided package which is the preferred option or intall the policy manually, if you need
@ -42,13 +42,13 @@ Verify that the system runs in enforcing mode.
If problems occur, you can set icinga2 or httpd to run to run its domain in permissive mode. If problems occur, you can set icinga2 or httpd to run to run its domain in permissive mode.
You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`. You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`.
### <a id="selinux-policy-installation-package"></a> Package installation ### Package installation <a id="selinux-policy-installation-package"></a>
Simply add the `selinux` subpackage to your installation. Simply add the `selinux` subpackage to your installation.
yum install icingaweb2-selinux yum install icingaweb2-selinux
### <a id="selinux-policy-installation-manual"></a> Manual installation ### Manual installation <a id="selinux-policy-installation-manual"></a>
This section describes the manual installation to support development and testing. This section describes the manual installation to support development and testing.
@ -73,19 +73,19 @@ Verify that Apache runs in its own domain `httpd_t` and the Icinga Web 2 configu
ls -ldZ /etc/icingaweb2/ ls -ldZ /etc/icingaweb2/
# drwxrws---. root icingaweb2 system_u:object_r:icingaweb2_config_t:s0 /etc/icingaweb2/ # drwxrws---. root icingaweb2 system_u:object_r:icingaweb2_config_t:s0 /etc/icingaweb2/
## <a id="selinux-policy-general"></a> General ## General <a id="selinux-policy-general"></a>
When the SELinux policy package for Icinga Web 2 is installed, it creates its own type of apache content and labels its When the SELinux policy package for Icinga Web 2 is installed, it creates its own type of apache content and labels its
configuration `icingaweb2_config_t` to allow confining access to it. configuration `icingaweb2_config_t` to allow confining access to it.
## <a id="selinux-policy-types"></a> Types ## Types <a id="selinux-policy-types"></a>
The configuration is labeled `icingaweb2_config_t` and other services can request access to it by using the interfaces The configuration is labeled `icingaweb2_config_t` and other services can request access to it by using the interfaces
`icingaweb2_read_config` and `icingaweb2_manage_config`. `icingaweb2_read_config` and `icingaweb2_manage_config`.
Files requiring read access are labeled `icingaweb2_content_t`. Files requiring write access are labeled Files requiring read access are labeled `icingaweb2_content_t`. Files requiring write access are labeled
`icingaweb2_rw_content_t`. `icingaweb2_rw_content_t`.
## <a id="selinux-policy-booleans"></a> Booleans ## Booleans <a id="selinux-policy-booleans"></a>
SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in
a defined way. The Icinga Web 2 policy package provides the following booleans. a defined way. The Icinga Web 2 policy package provides the following booleans.
@ -96,7 +96,7 @@ Having this boolean enabled allows httpd to write to the configuration labeled `
default. If not needed, you can disable it for more security. But this will disable all web based configuration of default. If not needed, you can disable it for more security. But this will disable all web based configuration of
Icinga Web 2. Icinga Web 2.
## <a id="selinux-bugreports"></a> Bugreports ## Bugreports <a id="selinux-bugreports"></a>
If you experience any problems while running SELinux in enforcing mode try to reproduce it in permissive mode. If the If you experience any problems while running SELinux in enforcing mode try to reproduce it in permissive mode. If the
problem persists, it is not related to SELinux because in permissive mode SELinux will not deny anything. problem persists, it is not related to SELinux because in permissive mode SELinux will not deny anything.

2
doc/99-Vagrant.md
View File

@ -1,4 +1,4 @@
# <a id="vagrant"></a> Vagrant # Vagrant <a id="vagrant"></a>
This chapter shows how to set up and use our [Icinga Vagrant This chapter shows how to set up and use our [Icinga Vagrant
boxes](https://github.com/icinga/icinga-vagrant) that we've created for boxes](https://github.com/icinga/icinga-vagrant) that we've created for