diff options
Diffstat (limited to '')
42 files changed, 2864 insertions, 0 deletions
diff --git a/doc/01-About.md b/doc/01-About.md new file mode 100644 index 0000000..7df51d1 --- /dev/null +++ b/doc/01-About.md @@ -0,0 +1,93 @@ +# 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. +It's fast, responsive, accessible and easily extensible with modules. + +## Installation <a id="about-installation"></a> + +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. + +See [here](02-Installation.md#installation) for more information about the installation. + +## Configuration <a id="about-configuration"></a> + +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. + +## Authentication <a id="about-authentication"></a> + +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). + +See [here](05-Authentication.md#authentication) for more information about +the different authentication methods available and how to configure them. + +## Authorization <a id="about-authorization"></a> + +In Icinga Web 2 there are permissions and restrictions to allow and deny (respectively) +roles to view or to do certain things. +These roles can be assigned to users and groups. + +See [here](06-Security.md#security) for more information about authorization +and how to configure roles. + +## User preferences <a id="about-preferences"></a> + +Besides the global configuration each user has individual configuration options +like the interface's language or the current timezone. +They can be stored either in a database or in .ini files. + +See [here](07-Preferences.md#preferences) for more information about a user's preferences +and how to configure their storage type. + +## Modules + +Modules extend Icinga Web 2 with additional functionality. They allow the integration of +capabilities into existing views and even other modules. Be it a graph provider such as +[Graphite](https://github.com/Icinga/icingaweb2-module-graphite) or a UI for the Icinga 2 +configuration like the [Director](https://github.com/Icinga/icingaweb2-module-director). + +See [here](08-Modules.md#modules) for information on how to install and configure modules. + +### The monitoring module <a id="about-monitoring"></a> + +> **Note for Icinga DB Users** +> +> This module is only for the IDO backend. Use [Icinga DB Web](https://github.com/Icinga/icingadb-web) instead. + +This is the core module for most Icinga Web 2 users. + +It provides an intuitive user interface for monitoring with Icinga 2. +There are lots of list and detail views (e.g. for hosts and services) +you can sort and filter depending on what you want to see. + +You can also control the monitoring process itself by sending external commands to Icinga. +Most such actions (like rescheduling a check) can be done with just a single click in the UI. + +More details about this module can be found in [this chapter](../modules/monitoring/doc/01-About.md#monitoring-module-about). + +### Documentation <a id="about-documentation"></a> + +With the documentation module you can read the documentation of the framework (and any module) directly in the user interface. + +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> + +Icinga Web 2 and all modules by Icinga utilize gettext to provide translations into other languages from the default +English (en_US). However, the actual language specific files (locales) are not separately included in every project. + +Icinga uses a central repository to manage locales: https://github.com/Icinga/L10n + +If you want to provide or update a translation for your own language, please head over there where you will find +[instructions](https://github.com/Icinga/L10n/blob/main/CONTRIBUTING.md) on how to contribute. + +## Accessibility <a id="about-accessibility"></a> + +In the Icinga Web 2 interface even the blind can see - +easy navigation with a screen reader and specific themes for different kinds of vision deficiencies +make it possible for everyone to monitor their systems without impairments. diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..6bf9ee0 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,537 @@ +<!-- {% if index %} --> +# Installation <a id="installation"></a> + +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. + +Please follow the steps listed for your operating system. Packages for distributions other than the ones +listed here may also be available. Please refer to [icinga.com/get-started/download](https://icinga.com/get-started/download/#community) +for a full list of available community repositories. + +## Browser Support + +Icinga Web 2 and modules made by Icinga don't require a particular browser or set of browsers. The +vendor of the browser in question doesn't matter much. However, the features a browser supports do. + +This generally applies to CSS and Javascript features. Since there a plethora of features in each +category which Icinga Web 2 and modules may require, we will only mention the most prominent feature +or sub-category here: + +* For CSS this is [the flexible box layout module](https://caniuse.com/flexbox) +* For Javascript it is [the ECMAScript 2015 specification](https://caniuse.com/es6) + +If your desired browser and its version is showing up in green when visiting the respective link, +it's probably okay to use it for Icinga Web 2. + +## Upgrade <a id="upgrade"></a> + +In case you are upgrading from an older version of Icinga Web 2 +please make sure to read the [upgrading](80-Upgrading.md#upgrading) section +thoroughly. +<!-- {% elif not from_source %} --> + +## Installation Requirements <a id="installation-requirements"></a> + +* [Icinga 2](https://icinga.com/docs/icinga-2) and [Icinga DB](https://icinga.com/docs/icinga-db) to + monitor your infrastructure +* A web server, e.g. Apache or Nginx +* PHP version ≥ 7.2 + +### Optional Requirements + +* The [pdfexport](https://github.com/Icinga/icingaweb2-module-pdfexport) module (≥0.10) is required for the + export to PDF +* LDAP PHP library when using Active Directory or LDAP for authentication + +## Add Icinga Package Repository <a id="add-icinga-package-repository"></a> + +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 debian %} --> +### Debian Repository <a id="ubuntu-repository"></a> + +```bash +apt-get update +apt-get -y install apt-transport-https wget gnupg + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - + +DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ + echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \ + /etc/apt/sources.list.d/${DIST}-icinga.list + echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \ + /etc/apt/sources.list.d/${DIST}-icinga.list + +apt-get update +``` +<!-- {% endif %} --> + +<!-- {% if ubuntu %} --> +### Ubuntu Repository <a id="ubuntu-repository"></a> + +```bash +apt-get update +apt-get -y install apt-transport-https wget gnupg + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - + +. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \ + echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \ + /etc/apt/sources.list.d/${DIST}-icinga.list + echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \ + /etc/apt/sources.list.d/${DIST}-icinga.list + +apt-get update +``` +<!-- {% endif %} --> + +<!-- {% if centos %} --> +### CentOS Repository <a id="centos-repository"></a> + +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` + +The packages for CentOS depend on other packages which are distributed +as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). + +CentOS 7: + +```bash +yum install epel-release +``` + +Since Icinga Web v2.5 we also require a **newer PHP version** than what is available +in RedHat itself. You need to enable the SCL repository, so that the dependencies +can pull in the newer PHP. + +```bash +yum install centos-release-scl +``` +<!-- {% endif %} --> + +<!-- {% if rhel %} --> +### RHEL Repository <a id="rhel-repository"></a> + +!!! info + + A paid repository subscription is required for RHEL repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription) + + Don't forget to fill in the username and password section with your credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/subscription/rhel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` + +If you are using RHEL you need to additionally enable the `optional` and `codeready-builder` +repository before installing the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). + +#### RHEL 8 + +```bash +ARCH=$( /bin/arch ) + +subscription-manager repos --enable rhel-8-server-optional-rpms +subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms" + +dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm +``` + +#### RHEL 7 +Since Icinga Web v2.5 we also require a **newer PHP version** than what is available +in RedHat itself. You need to enable the SCL repository, so that the dependencies +can pull in the newer PHP. + +```bash +subscription-manager repos --enable rhel-7-server-optional-rpms +subscription-manager repos --enable rhel-server-rhscl-7-rpms + +yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +### SLES Repository <a id="rhel-repository"></a> + +!!! info + + A paid repository subscription is required for RHEL repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription) + + Don't forget to fill in the username and password section with your credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key + +zypper ar https://packages.icinga.com/subscription/sles/ICINGA-release.repo +zypper ref +``` + +You need to additionally enable a couple of SLES repositories to fulfill dependencies: + +```bash +source /etc/os-release + +SUSEConnect -p sle-module-desktop-applications/$VERSION_ID/x86_64 +SUSEConnect -p sle-module-development-tools/$VERSION_ID/x86_64 +SUSEConnect -p sle-module-web-scripting/$VERSION_ID/x86_64 +SUSEConnect -p PackageHub/$VERSION_ID/x86_64 +``` +<!-- {% endif %} --> + +<!-- {% if amazon_linux %} --> +### Amazon Linux 2 Repository <a id="amazon-linux-2-repository"></a> + +!!! info + + A paid repository subscription is required for Amazon Linux repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription) + + Don't forget to fill in the username and password section with your credentials in the local .repo file. + +```bash +rpm --import https://packages.icinga.com/icinga.key +wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo +``` + +You need to install and enable the `amazon-linux-extras` repository to meet the requirements of +Icinga Web 2 on Amazon Linux 2: + +```bash +yum install -y amazon-linux-extras + +amazon-linux-extras enable php8.0 +``` +<!-- {% endif %} --> + +## Install Icinga Web 2 <a id="install-icingaweb2"></a> + +You can install Icinga Web 2 by using your distribution's package manager to install the `icingaweb2` package. +The additional package `icingacli` is necessary to follow further steps in this guide. + +<!-- {% if debian %} --> +<!-- {% if not icingaDocs %} --> +#### Debian +<!-- {% endif %} --> +```bash +apt-get install icingaweb2 icingacli +``` +<!-- {% endif %} --> + +<!-- {% if ubuntu %} --> +<!-- {% if not icingaDocs %} --> +#### Ubuntu +<!-- {% endif %} --> +```bash +apt-get install icingaweb2 libapache2-mod-php icingacli +``` + +The additional package `libapache2-mod-php` is necessary on Ubuntu to automatically +install a web server and PHP and make Icinga Web 2 work out-of-the-box. +<!-- {% endif %} --> + +<!-- {% if centos or rhel or amazon_linux %} --> +!!! tip + + If you have [SELinux](90-SELinux.md) enabled, the package `icingaweb2-selinux` is also required. +<!-- {% endif %} --> + +<!-- {% if centos %} --> +<!-- {% if not icingaDocs %} --> +#### CentOS +<!-- {% endif %} --> +``` +yum install icingaweb2 icingacli +``` +<!-- {% endif %} --> + +<!-- {% if rhel %} --> +<!-- {% if not icingaDocs %} --> +#### RHEL +<!-- {% endif %} --> +#### RHEL 8 +```bash +dnf install icingaweb2 icingacli +``` + +#### RHEL 7 +```bash +yum install icingaweb2 icingacli +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +<!-- {% if not icingaDocs %} --> +#### SLES +<!-- {% endif %} --> +```bash +zypper install icingaweb2 icingacli +``` +<!-- {% endif %} --> + +<!-- {% if amazon_linux %} --> +<!-- {% if not icingaDocs %} --> +#### Amazon Linux 2 +<!-- {% endif %} --> +```bash +yum install icingaweb2 icingacli +``` +<!-- {% endif %} --> + +## Install the Web Server <a id="install-the-web-server"></a> + +Ensure that you have a web server with PHP installed before proceeding, +such as Apache or Nginx with PHP version ≥ 7.2. Depending on your operating system, +you may need to install and configure the web server separately. +An Apache configuration file to serve Icinga Web is already installed. +If you want to use Nginx, you must manually create a configuration file using the following command. +Save the output as a new file in the web server configuration directory: + +```bash +icingacli setup config webserver nginx --document-root /usr/share/icingaweb2/public +``` + +## Prepare Web Setup <a id="prepare-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 visit Icinga Web 2 in your browser. When using the web setup you are required to authenticate using a token. +In order to generate a token use the `icingacli`: + +```bash +icingacli setup token create +``` + +In case you do not remember the token you can show it using the `icingacli`: + +```bash +icingacli setup token show +``` + +<!-- {% if debian or ubuntu %} --> +You need to manually create a database and a database user prior to starting the web wizard. +This is due to local security restrictions whereas the web wizard cannot create a database/user through +a local unix domain socket. + +```bash +MariaDB [mysql]> CREATE DATABASE icingaweb2; + +MariaDB [mysql]> GRANT ALL ON icingaweb2.* TO icingaweb2@localhost IDENTIFIED BY 'CHANGEME'; +``` + +You may also create a separate administrative account with all privileges instead. + +!!! note + + This is only required if you are using a local database as authentication type. +<!-- {% endif %} --> + +### Start Web Setup <a id="start-web-setup-from-package"></a> + +Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: +`/icingaweb2/setup`. + +<!-- {% if debian or ubuntu %} --> +!!! hint + + Use the same database, user and password details created above when asked. +<!-- {% endif %} --> + +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 sles %} --> +!!! note + + If you're using php-fpm on SLES 15 SP2 onwards, `/etc/icingaweb2` may not be writable. + That's because the default systemd unit file for php-fpm has `ProtectSystem=full` + enabled. You want to lookup/add the systemd setting `ReadWritePaths=` in this case and + add `/etc/icingaweb2` to it. Alternatively you can also define a different configuration + directory using the environment variable `ICINGAWEB_CONFIGDIR`. +<!-- {% endif %} --> + +<!-- {% if centos or rhel or amazon_linux %} --> +!!! note + + If you have SELinux enabled, please ensure to either have the selinux package for Icinga Web 2 installed, or disable it. +<!-- {% endif %} --> + +<!-- {% else %} --><!-- {# end from_source elif #} --> +<!-- {% if not icingaDocs %} --> +## Installing Icinga Web 2 from Source <a id="installing-from-source"></a> +<!-- {% endif %} --> + +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. + +### Getting the Source <a id="getting-the-source"></a> + +First of all, you need to download the sources. + +Git clone: + +```bash +cd /usr/share/ +git clone https://github.com/Icinga/icingaweb2.git icingaweb2 +``` + +Tarball download (latest [release](https://github.com/Icinga/icingaweb2/releases/latest)): + +```bash +cd /usr/share +wget https://github.com/Icinga/icingaweb2/archive/v2.9.5.zip +unzip v2.9.5.zip +mv icingaweb2-2.9.5 icingaweb2 +``` + +### Installing Requirements from Source <a id="installing-from-source-requirements"></a> + +You will need to install certain dependencies depending on your setup: + +* [Icinga 2](https://github.com/Icinga/icinga2) and [Icinga DB](https://github.com/Icinga/icingadb) to + monitor your infrastructure +* A web server, e.g. Apache or Nginx +* PHP version ≥ 7.2 +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (≥ 0.13) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (≥ 0.12) +* The following PHP modules must be installed: cURL, json, gettext, fileinfo, intl, dom, OpenSSL and xml +* The [pdfexport](https://github.com/Icinga/icingaweb2-module-pdfexport) module (≥0.10) is required for the + export to PDF +* LDAP PHP library when using Active Directory or LDAP for authentication +* MySQL or PostgreSQL PHP libraries + +The following example installs Apache2 as web server, MySQL as RDBMS and uses the PHP adapter for MySQL. +Adopt the package requirements to your needs (e.g. adding ldap for authentication) and distribution. + +Example for RHEL/CentOS/Fedora: + +```bash +yum install httpd mysql-server +yum install php php-gd php-intl +``` + +The setup wizard will check the pre-requisites later on. + + +### Installing Icinga Web 2 <a id="installing-from-source-example"></a> + +Choose a target directory and move Icinga Web 2 there. + +```bash +mv icingaweb2 /usr/share/icingaweb2 +``` + +### Configuring the Web Server <a id="configuring-web-server"></a> + +Use `icingacli` to generate web server configuration for either Apache or nginx. + +**Apache**: +```bash +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public +``` + +**nginx**: +```bash +./bin/icingacli setup config webserver nginx --document-root /usr/share/icingaweb2/public +``` + +Save the output as new file in your webserver's configuration directory. + +Example for Apache on RHEL or CentOS: +```bash +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/httpd/conf.d/icingaweb2.conf +``` + +Example for Apache on SUSE: +```bash +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf +``` + +Example for Apache on Debian Jessie: +```bash +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/apache2/conf-available/icingaweb2.conf +a2enconf icingaweb2 +``` + +Example for Apache on Alpine Linux: +```bash +icingacli setup config webserver apache --document-root /usr/share/webapps/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf +``` +### 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 visit Icinga Web 2 in your browser. Please follow the steps listed below for preparing the web setup. + +Because both web and CLI must have access to configuration and logs, permissions will be managed using a special +system group. The web server user and CLI user have to be added to this system group. + +Add the system group `icingaweb2` in the first place. + +**Fedora, RHEL, CentOS, SLES and OpenSUSE**: +```bash +groupadd -r icingaweb2 +``` + +**Debian and Ubuntu**: +```bash +addgroup --system icingaweb2 +``` + +Add your web server's user to the system group `icingaweb2` +and restart the web server: + +**Fedora, RHEL and CentOS**: +```bash +usermod -a -G icingaweb2 apache +service httpd restart +``` + +**SLES and OpenSUSE**: +```bash +usermod -A icingaweb2 wwwrun +service apache2 restart +``` + +**Debian and Ubuntu**: +```bash +usermod -a -G icingaweb2 www-data +service apache2 restart +``` + +**Alpine Linux**: +```bash +gpasswd -a apache icingaweb2 +rc-service apache2 restart +``` + + +Use `icingacli` to create the configuration directory which defaults to **/etc/icingaweb2**: +```bash +./bin/icingacli setup config directory +``` + + +When using the web setup you are required to authenticate using a token. In order to generate a token use the +`icingacli`: +```bash +./bin/icingacli setup token create +``` + +In case you do not remember the token you can show it using the `icingacli`: +```bash +./bin/icingacli setup token show +``` + +### 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: +`/icingaweb2/setup`. + +Paste the previously generated token and follow the steps on-screen. Then you are done here. + +If you prefer to set up the configuration manually, follow the +[Icinga Web 2 Manual Configuration instructions](20-Advanced-Topics.md#web-setup-manual-from-source-config) +<!-- {% endif %} --><!-- {# end index if #} --> diff --git a/doc/02-Installation.md.d/01-Debian.md b/doc/02-Installation.md.d/01-Debian.md new file mode 100644 index 0000000..9ff5665 --- /dev/null +++ b/doc/02-Installation.md.d/01-Debian.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Debian +<!-- {% set debian = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/02-Ubuntu.md b/doc/02-Installation.md.d/02-Ubuntu.md new file mode 100644 index 0000000..74b7075 --- /dev/null +++ b/doc/02-Installation.md.d/02-Ubuntu.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Ubuntu +<!-- {% set ubuntu = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/03-CentOS.md b/doc/02-Installation.md.d/03-CentOS.md new file mode 100644 index 0000000..0be7b1c --- /dev/null +++ b/doc/02-Installation.md.d/03-CentOS.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on CentOS +<!-- {% set centos = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/04-RHEL.md b/doc/02-Installation.md.d/04-RHEL.md new file mode 100644 index 0000000..cab5194 --- /dev/null +++ b/doc/02-Installation.md.d/04-RHEL.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on RHEL +<!-- {% set rhel = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/05-SLES.md b/doc/02-Installation.md.d/05-SLES.md new file mode 100644 index 0000000..f17ab34 --- /dev/null +++ b/doc/02-Installation.md.d/05-SLES.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on SLES +<!-- {% set sles = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/06-Amazon-Linux.md b/doc/02-Installation.md.d/06-Amazon-Linux.md new file mode 100644 index 0000000..d9cb7f2 --- /dev/null +++ b/doc/02-Installation.md.d/06-Amazon-Linux.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Amazon Linux +<!-- {% set amazon_linux = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/02-Installation.md.d/07-From-Source.md b/doc/02-Installation.md.d/07-From-Source.md new file mode 100644 index 0000000..540335f --- /dev/null +++ b/doc/02-Installation.md.d/07-From-Source.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 from Source +<!-- {% set from_source = True %} --> +<!-- {% include "02-Installation.md" %} --> diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md new file mode 100644 index 0000000..0918aac --- /dev/null +++ b/doc/03-Configuration.md @@ -0,0 +1,88 @@ +# Configuration <a id="configuration"></a> + +## 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 configuration setup). + +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\_resource | **Required.** Specify a defined [resource](04-Resources.md#resources-configuration-database) name. + + +Example for storing the user preferences in the database resource `icingaweb_db`: + +``` +[global] +show_stacktraces = "0" +config_resource = "icingaweb_db" +module_path = "/usr/share/icingaweb2/modules" +``` + +### Security Configuration <a id="configuration-general-security"></a> + +| Option | Description | +|------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| use\_strict\_csp | **Optional.** Set this to `1` to enable strict [Content Security Policy](20-Advanced-Topics.md#advanced-topics-csp). Defaults to `0`. | + +Example: + +``` +[security] +use_strict_csp = "1" +``` + +### Logging Configuration <a id="configuration-general-logging"></a> + +Option | Description +-------------------------|----------------------------------------------- +log | **Optional.** Specifies the logging type. Can be set to `syslog`, `file`, `php` (web server's error log) 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 +-------------------------|----------------------------------------------- +default | **Optional.** Choose the default theme. Can be set to `Icinga`, `high-contrast`, `Winter`, 'colorblind' 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" +default = "high-contrast" +``` diff --git a/doc/04-Resources.md b/doc/04-Resources.md new file mode 100644 index 0000000..ca362fa --- /dev/null +++ b/doc/04-Resources.md @@ -0,0 +1,136 @@ +# Resources <a id="resources"></a> + +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. + +## Configuration <a id="resources-configuration"></a> + +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` 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 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. +use\_ssl | **Optional.** Use SSL. Enables the following SSL options. +ssl\_do\_not\_verify\_server\_cert | **Optional.** Disable validation of the server certificate. Only available for the `mysql` database and on PHP versions > 5.6. +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. + + +#### Example <a id="resources-configuration-database-example"></a> + +The name in brackets defines the resource name. + +``` +[icingaweb-mysql-tcp] +type = db +db = mysql +host = 127.0.0.1 +port = 3306 +username = icingaweb +password = icingaweb +dbname = icingaweb + +[icingaweb-mysql-socket] +type = db +db = mysql +host = localhost +username = icingaweb +password = icingaweb +dbname = icingaweb + +[icingaweb-pgsql-socket] +type = db +db = pgsql +host = /var/run/postgresql +port = 5432 +username = icingaweb +password = icingaweb +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. + +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`. +timeout | **Optional.** Connection timeout for every LDAP connection. Defaults to `5`. +disable_server_side_sort | **Optional.** Disable server side sorting. Defaults to automatic detection whether the server supports this. + +#### Server Side Sorting <a id="ldap-server-side-sort"></a> + +Icinga Web automatically detects whether the LDAP server supports server side sorting. +If that is not the case, results get sorted on the client side. +There are LDAP servers though which report that they support this feature in general but have it disabled for certain +fields. This may lead to failures. With `disable_server_side_sort` it is possible to disable server side sorting and it +has precedence over the automatic detection. + +#### Example <a id="resources-configuration-ldap-example"></a> + +The name in brackets defines the resource name. + +``` +[ad] +type = ldap +hostname = localhost +port = 389 +root_dn = "ou=people,dc=icinga,dc=org" +bind_dn = "cn=admin,ou=people,dc=icinga,dc=org" +bind_pw = admin +``` + +### 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 +ssh authentication. + +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" +private_key = "/etc/icingaweb2/ssh/ssh-user" +``` diff --git a/doc/05-Authentication.md b/doc/05-Authentication.md new file mode 100644 index 0000000..5923a8c --- /dev/null +++ b/doc/05-Authentication.md @@ -0,0 +1,293 @@ +# Authentication <a id="authentication"></a> + +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 +or if users are spread over multiple places. + +## Configuration <a id="authentication-configuration"></a> + +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. + +The order of entries in the authentication configuration determines the order of the authentication methods. +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. + +## External Authentication <a id="authentication-configuration-external-authentication"></a> + +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 +``` + +If your web server is not configured for authentication though, the `autologin` section has no effect. + +### 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 authentication. + +#### Create Basic Auth User <a id="authentication-configuration-external-authentication-example-user"></a> + +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 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 +``` + +#### Apache Configuration <a id="authentication-configuration-external-authentication-example-apache"></a> + +Add the following configuration to the `<Directory>` directive in the `icingaweb2.conf` web server +configuration file. + +``` +AuthType Basic +AuthName "Icinga Web 2" +AuthUserFile /etc/icingaweb2/.http-users +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 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> + +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`. + +> **Note for SELinux** +> +> If you run into problems connecting with LDAP and have SELinux enabled, take a look [here](90-SELinux.md#selinux-optional-booleans). + +Example: + +``` +# vim /etc/icingaweb2/authentication.ini + +[auth_ldap] +backend = ldap +resource = my_ldap +user_class = inetOrgPerson +user_name_attribute = uid +filter = "memberOf=cn=icinga_users,cn=groups,cn=accounts,dc=icinga,dc=org" +``` + +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> + +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: + +``` +# vim /etc/icingaweb2/authentication.ini + +[auth_ad] +backend = msldap +resource = my_ad +``` + +## 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 +[database resource](04-Resources.md#resources-configuration-database) which will be referenced as data source for the database +authentication method. + +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/authentication.ini + +[auth_db] +backend = db +resource = icingaweb-mysql +``` + +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. + + +## Groups <a id="authentication-configuration-groups"></a> + +Navigate into **Configuration > Application > Authentication **. + +Group configuration is stored in the `/etc/icingaweb2/groups.ini` file. + +### 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). +domain | **Optional.** The domain the LDAP server is responsible for. See [Domain-aware Authentication](05-Authentication.md#domain-aware-auth). +user\_class | **Optional.** LDAP user class. Defaults to `inetOrgPerson` with `msldap` and `user` with `ldap`. +user\_name\_attribute | **Optional.** LDAP attribute which contains the username. Defaults to `sAMAccountName` with `msldap` and `uid` with `ldap`. +user\_base\_dn | **Optional.** The path where users can be found on the LDAP server. +base_dn | **Optional.** LDAP base dn for groups. Leave empty to select all groups available using the specified resource. +group\_class | **Optional.** LDAP group class. Defaults to `group`. +group\_member\_attribute | **Optional.** LDAP attribute where a group's members are stored. Defaults to `member`. +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: + +``` +# vim /etc/icingaweb2/groups.ini + +[active directory] +backend = "msldap" +resource = "auth_ad" +group_class = "group" +user_class = "user" +user_name_attribute = "userPrincipalName" +``` + +Example for Active Directory using the group backend resource `ad_company`. +It also references the defined user backend resource `ad_users_company`. + +``` +# 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 +domains. This is possible since version 2.5 and can be done by configuring each LDAP/AD backend's domain. You can also +use the GUI for this purpose. This enables you to automatically discover a suitable value based on your LDAP server's +configuration. (AD: NetBIOS name, other LDAP: domain in DNS-notation) + +**Example:** + +``` +# vim /etc/icingaweb2/authentication.ini + +[auth_icinga] +backend = ldap +resource = icinga_ldap +user_class = inetOrgPerson +user_name_attribute = uid +filter = "memberOf=cn=icinga_users,cn=groups,cn=accounts,dc=icinga,dc=com" +domain = "icinga.com" + +[auth_example] +backend = msldap +resource = example_ad +domain = EXAMPLE +``` + +If you configure the domains like above, the icinga.com user "jdoe" will have to log in as "jdoe@icinga.com" and the +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. + +### Default Domain <a id="default-auth-domain"></a> + +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" +``` + +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. + +### How it works <a id="domain-aware-auth-process"></a> + +### 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 +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". + +### 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 +finds one which is responsible for that user -- e.g. a MySQL backend (SQL database backends aren't domain-aware). Then +Icinga Web 2 asks that backend to authenticate the user with the username "jdoe@icinga.com". diff --git a/doc/06-Security.md b/doc/06-Security.md new file mode 100644 index 0000000..b8d7cf2 --- /dev/null +++ b/doc/06-Security.md @@ -0,0 +1,242 @@ +# Security + +Access control is a vital part of configuring Icinga Web 2 securely. It is important that not every user that has +access to Icinga Web 2 can perform any action or see any host and service. Allow only a small group of administrators +to change the Icinga Web 2 configuration to prevent mis-configuration and security breaches. Define different rules +to users and groups of users which should only see a part of the monitoring environment they're in charge of. + +This chapter will describe how to configure such rules in Icinga Web 2 and how permissions, refusals, restrictions +and role inheritance work. + +## Basics + +Icinga Web 2 access control is done by defining **roles** that associate privileges with **users** and **groups**. +Privileges of a role consist of **permissions**, **refusals** and **restrictions**. A role can **inherit** privileges +from another role. + +### Role Memberships + +A role is tied to users or groups of users. Upon login, a user's roles are identified by the username or names of +groups the user is a member of. + +> **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. It uses its own authentication backend to fetch users and groups from, +> [which must be configured separately](05-Authentication.md#authentication). + +### Privileges + +Permissions are used to grant access. Whether this means that a user can see a certain area or perform a distinct +action is fully up to the permission in question. Without granting a permission, the user will lack access and won't +see the area or perform the action. + +Refusals are used to deny access. So they're the exact opposite of permissions. Most permissions can be refused. +Refusing a permission will block the user's access no matter if another role grants the permission. Refusals +override permissions. + +Restrictions are expressions that limit access. What this exactly means is up to how the restriction is being utilized. +Without any restriction, a user is supposed to see *everything*. A user that occupies multiple roles, which all define +a restriction of the same type, will see *more*. + +## Roles + +A user can occupy multiple roles. Permissions and restrictions stack up in this case, thus will grant *more* access. +Refusals still override permissions however. A refusal of one role negates the granted permission of any other role. + +### Configuration + +Roles can be changed either through the UI, by navigating to the page **Configuration > Authentication > Roles**, +or by editing the configuration file `/etc/icingaweb2/roles.ini`. + +#### Example + +The following shows a role definition from the configuration file mentioned above: + +``` +[winadmin] +users = "jdoe, janedoe" +groups = "admin" +permissions = "config/*, module/monitoring, monitoring/commands/schedule-check" +refusals = "config/authentication" +monitoring/filter/objects = "host_name=*win*" +``` + +This describes a role with the name `winadmin`. The users `jdoe` and `janedoe` are members of it. Just like the +members of group `admin` are. Full configuration access is granted, except of the authentication configuration, +which is forbidden. It also grants access to the *monitoring* module which includes the ability to re-schedule +checks, but only on objects related to hosts whose name contain `win`. + +#### Syntax + +Each role is defined as a section, with the name of the role as section name. The following +options can be defined for each role in a default Icinga Web 2 installation: + +Name | Description +--------------------------|----------------------------------------------- +parent | The name of the role from which to inherit privileges. +users | Comma-separated list of **usernames** that should occupy this role. +groups | Comma-separated list of **group names** whose users should occupy this role. +permissions | Comma-separated list of **permissions** granted by this role. +refusals | Comma-separated list of **permissions** refused by this role. +unrestricted | If set to `1`, owners of this role are not restricted in any way (Default: `0`) +monitoring/filter/objects | **Filter expression** that restricts the access to monitoring objects. + +### Administrative Roles + +Roles that have the wildcard `*` as permission, have full access and don't need any further permissions. However, +they are still affected by refusals. + +Unrestricted roles are supposed to allow users to access data without being limited to a subset of it. Once a user +occupies an unrestricted role, restrictions of the same and any other role are ignored. + +### Inheritance + +A role can inherit privileges from another role. Privileges are then combined the same way as if a user occupies +all roles in the inheritance path. Or to rephrase that, each role shares its members with all of its parents. + +## Permissions + +Each permission in Icinga Web 2 is denoted by a **namespaced key**, which is used to group permissions. All permissions +that affect the configuration of Icinga Web 2, are in a namespace called **config**, while all configuration options +that affect modules are covered by the permission `config/modules`. + +**Wildcards** can be used to grant all permissions in a certain namespace. The permission `config/*` grants access to +all configuration options. Just specifying a wildcard `*` will grant all permissions. + +Access to modules is restricted to users who have the related module permission granted. Icinga Web 2 provides +a module permission in the format `module/<moduleName>` for each installed module. + +### General Permissions + +Name | Permits +-----------------------------|----------------------------------------------- +\* | allow everything, including module-specific permissions +application/announcements | allow to manage announcements +application/log | allow to view the application log +config/\* | allow full config access +config/access-control/\* | allow to fully manage access control +config/access-control/groups | allow to manage groups +config/access-control/roles | allow to manage roles +config/access-control/users | allow to manage user accounts +config/general | allow to adjust the general configuration +config/modules | allow to enable/disable and configure modules +config/navigation | allow to view and adjust shared navigation items +config/resources | allow to manage resources +user/\* | allow all account related functionalities +user/application/stacktraces | allow to adjust in the preferences whether to show stacktraces +user/password-change | allow password changes in the account preferences +user/share/navigation | allow to share navigation items +module/`<moduleName>` | allow access to module `<moduleName>` (e.g. `module/monitoring`) + +### Monitoring Module Permissions + +The built-in monitoring module defines an additional set of permissions, that +is described in detail in the monitoring module documentation. + +## Restrictions + +Restrictions can be used to define what a user can see by specifying an expression that applies to a defined set of +data. By default, when no restrictions are defined, a user will be able to see the entire data that is available. + +The syntax of the expression used to define a particular restriction varies. This can be a comma-separated list of +terms, or [a full-blown filter](06-Security.md#filter-expressions). For more details on particular restrictions, +check the table below or the module's documentation providing the restriction. + +### General Restrictions + +Name | Applies to +--------------------------|------------------------------------------------------------------------------------------ +application/share/users | which users a user can share navigation items with (comma-separated list of usernames) +application/share/groups | which groups a user can share navigation items with (comma-separated list of group names) + +### Username placeholder + +It is possible to reference the local username (without the domain part) of the user in restrictions. To accomplish +this, put the macro `$user.local_name$` in the restriction where you want it to appear. + +This can come in handy if you have e.g. an attribute on hosts or services defining which user is responsible for it: +`_host_deputy=$user.local_name$|_service_deputy=$user.local_name$` + +### Filter Expressions + +Filters operate on columns. A complete list of all available filter columns on hosts and services can be found in +the monitoring module documentation. + +Any filter expression that is allowed in the filtered view, is also an allowed filter expression. +This means, that it is possible to define negations, wildcards, and even nested +filter expressions containing AND and OR-Clauses. + +The filter expression will be **implicitly** added as an **AND-Clause** to each query on +the filtered data. The following shows the filter expression `host_name=*win*` being applied on `monitoring/filter/objects`. + + +Regular filter query: + + AND-- service_problem = 1 + | + +--- service_handled = 0 + + +With our restriction applied, any user affected by this restrictions will see the +results of this query instead: + + + AND-- host_name = *win* + | + +--AND-- service_problem = 1 + | + +--- service_handled = 0 + +#### Stacking Filters + +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 +expression: + + + AND-- OR-- $FILTER1 + | | + | +-- $FILTER2 + | | + | +-- $FILTER3 + | + +--AND-- service_problem = 1 + | + +--- service_handled = 0 + + +As a result, a user is be able to see hosts that are matched by **ANY** of +the filter expressions. The following examples will show the usefulness of this behavior: + +#### Example 1: Negation + +``` +[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*" +``` + +Will only match hosts and services whose host name does **not** contain **win** + +Notice that because of the behavior of two stacking filters, a user that is member of **windows-admins** and **web-admins**, will now be able to see both, Windows and non-Windows hosts and services. + +#### Example 2: Hostgroups + +``` +[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. diff --git a/doc/07-Preferences.md b/doc/07-Preferences.md new file mode 100644 index 0000000..73abead --- /dev/null +++ b/doc/07-Preferences.md @@ -0,0 +1,21 @@ +# Preferences <a id="preferences"></a> + +Preferences are settings a user can set for their account only, +for example the language and time zone. + +Preferences can be stored either in a MySQL or in a PostgreSQL database. The database must be configured. + +## Configuration <a id="preferences-configuration"></a> + +The preference configuration backend is defined in the global [config.ini](03-Configuration.md#configuration-general-global) file. + +You have to define a [database resource](04-Resources.md#resources-configuration-database) +which will be referenced as resource for the preferences storage. + +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. + +``` +[global] +config_resource = "icingaweb_db" +``` diff --git a/doc/08-Modules.md b/doc/08-Modules.md new file mode 100644 index 0000000..6c81c5b --- /dev/null +++ b/doc/08-Modules.md @@ -0,0 +1,69 @@ +# Modules + +## Installation + +A module should be installed in one of the [configured module paths](03-Configuration.md#general-configuration). +The default path in most installations is `/usr/share/icingaweb2/modules`. + +Each directory in there contains the files for a particular module. The directory's name has to be the one +that is provided by the module's documentation. If there is none provided, it is usually the name of the +module in all lowercase. Some modules may use a name prefixed with `icingaweb2-module-`. If this is the case, +the directory's name should be that, but without the prefix. +(e.g. `icingaweb2-module-map` turns into `/usr/share/icingaweb2/modules/map`) + +> **Note:** +> +> Remember to ensure that your web-server can access those files. Though, read permission only. + +Once a module's files are in place, it needs to be enabled first before it can be used. This can either be done in +the UI at `Configuration -> Modules` or by using the icingacli: `icingacli module enable map` + +In order for other non-admin users to access the module's functionality, it is required to permit access first. +This is done by granting the permission `module/<module-name>`. (e.g. `module/map`) + +### Module Specific Instructions + +A module may require further installation steps. Whether these need to be performed before enabling the module, +should be provided by the module's documentation. In any case, don't forget to apply these as well, otherwise +the module will most likely not function correctly. + +### Examples + +There are sample installation instructions provided for your convenience: + +**Sample Tarball installation** + +```sh +MODULE_NAME="map" +MODULE_VERSION="v1.1.0" +MODULE_AUTHOR="nbuchwitz" +MODULES_PATH="/usr/share/icingaweb2/modules" +MODULE_PATH="${MODULES_PATH}/${MODULE_NAME}" +RELEASES="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}/archive" +mkdir "$MODULE_PATH" \ +&& wget -q $RELEASES/${MODULE_VERSION}.tar.gz -O - \ + | tar xfz - -C "$MODULE_PATH" --strip-components 1 +icingacli module enable "${MODULE_NAME}" +``` + +**Sample GIT installation** + +```sh +MODULE_NAME="map" +MODULE_VERSION="v1.1.0" +MODULE_AUTHOR="nbuchwitz" +REPO="https://github.com/${MODULE_AUTHOR}/icingaweb2-module-${MODULE_NAME}" +MODULES_PATH="/usr/share/icingaweb2/modules" +git clone ${REPO} "${MODULES_PATH}/${MODULE_NAME}" --branch "${MODULE_VERSION}" +icingacli module enable "${MODULE_NAME}" +``` + +## Configuration + +A module may also require configuration. Most modules provide additional tabs at their configuration page. +This is accessible in the UI at `Configuration -> Modules`. If not, and something isn't working, check the +module's documentation again for hints. + +If you need access to a module's configuration files directly, they should be in a subdirectory `modules` +of Icinga Web 2's configuration directory. That is usually `/etc/icingaweb2/modules`. Each directory in +there should be named the same as its installation path. (e.g. `/etc/icingaweb2/modules/map`) diff --git a/doc/15-Auditing.md b/doc/15-Auditing.md new file mode 100644 index 0000000..c44cbfe --- /dev/null +++ b/doc/15-Auditing.md @@ -0,0 +1,14 @@ +# Auditing <a id="auditing"></a> + +Auditing in Icinga Web 2 is possible with a separate [module](https://github.com/Icinga/icingaweb2-module-audit). + +This module provides different logging facilities to store/record activities by Icinga Web 2 users. + +Icinga Web 2 currently emits the following activities: + +## Authentication + +Activity | Additional Data +---------|---------------- +login | username +logout | username diff --git a/doc/20-Advanced-Topics.md b/doc/20-Advanced-Topics.md new file mode 100644 index 0000000..ade5aff --- /dev/null +++ b/doc/20-Advanced-Topics.md @@ -0,0 +1,440 @@ +# Advanced Topics <a id="advanced-topics"></a> + +This chapter provides details for advanced Icinga Web 2 topics. + +* [Global URL parameters](20-Advanced-Topics.md#global-url-parameters) +* [VirtualHost configuration](20-Advanced-Topics.md#virtualhost-configuration) +* [Content Security Policy (CSP)](20-Advanced-Topics.md#advanced-topics-csp) +* [Advanced Authentication Tips](20-Advanced-Topics.md#advanced-topics-authentication-tips) +* [Source installation](20-Advanced-Topics.md#installing-from-source) +* [Automated setup](20-Advanced-Topics.md#web-setup-automation) +* [Kiosk Mode Configuration](20-Advanced-Topics.md#kiosk-mode) +* [Customizing the Landing Page](20-Advanced-Topics.md#landing-page) + +## Global URL Parameters <a id="global-url-parameters"></a> + +Parameters starting with `_` are for development purposes only. + +Parameter | Value | Description +------------------|---------------|-------------------------------- +showFullscreen | - | Hides the left menu and optimizes the layout for full screen resolution. +showCompact | - | Provides a compact view. Hides the title and upper menu. This is helpful to embed a dashboard item into an external iframe. +format | json/csv/sql | Selected views can be exported as JSON or CSV. This also is available in the upper menu. You can also export the SQL queries for manual analysis. +\_dev | 0/1 | Whether the server should return compressed or full JS/CSS files. This helps debugging browser console errors. + + + +Examples for `showFullscreen`: + +http://localhost/icingaweb2/dashboard?showFullscreen +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&showFullscreen + +Examples for `showCompact`: + +http://localhost/icingaweb2/dashboard?showCompact&showFullscreen +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&showCompact + +Examples for `format`: + +http://localhost/icingaweb2/monitoring/list/services?format=json +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&dir=desc&format=csv + + +## VirtualHost Configuration <a id="virtualhost-configuration"></a> + +This describes how to run Icinga Web 2 on your FQDN's `/` entry point without +any redirect to `/icingaweb2`. + +### VirtualHost Configuration for Apache <a id="virtualhost-configuration-apache"></a> + +Use the setup CLI commands to generate the default Apache configuration which serves +Icinga Web 2 underneath `/icingaweb2`. + +The next steps are to create the VirtualHost configuration: + +* Copy the `<Directory "/usr/share/icingaweb2/public">` into the main VHost configuration. Don't forget to correct the indent. +* Set the `DocumentRoot` variable to look into `/usr/share/icingaweb2/public` +* Modify the `RewriteBase` variable to use `/` instead of `/icingaweb2` + +Example on RHEL/CentOS: + +``` +vim /etc/httpd/conf.d/web.icinga.com.conf + +<VirtualHost *:80> + ServerName web.icinga.com + + ## Vhost docroot + # modified for Icinga Web 2 + DocumentRoot "/usr/share/icingaweb2/public" + + ## Rewrite rules + RewriteEngine On + + <Directory "/usr/share/icingaweb2/public"> + Options SymLinksIfOwnerMatch + AllowOverride None + + <IfModule mod_authz_core.c> + # Apache 2.4 + <RequireAll> + Require all granted + </RequireAll> + </IfModule> + + <IfModule !mod_authz_core.c> + # Apache 2.2 + Order allow,deny + Allow from all + </IfModule> + + SetEnv ICINGAWEB_CONFIGDIR "/etc/icingaweb2" + + EnableSendfile Off + + <IfModule mod_rewrite.c> + RewriteEngine on + # modified base + RewriteBase / + RewriteCond %{REQUEST_FILENAME} -s [OR] + RewriteCond %{REQUEST_FILENAME} -l [OR] + RewriteCond %{REQUEST_FILENAME} -d + RewriteRule ^.*$ - [NC,L] + RewriteRule ^.*$ index.php [NC,L] + </IfModule> + + <IfModule !mod_rewrite.c> + DirectoryIndex error_norewrite.html + ErrorDocument 404 /error_norewrite.html + </IfModule> + </Directory> +</VirtualHost> +``` + +Reload Apache and open the FQDN in your web browser. + +``` +systemctl reload httpd +``` + +### Content Security Policy (CSP) <a id="advanced-topics-csp"></a> + +Elevate your security standards to an even higher level by enabling the [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) for Icinga Web. +Enabling strict CSP can prevent your Icinga Web environment from becoming a potential target of [Cross-Site Scripting (XSS)](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting) +and data injection attacks. After enabling this feature Icinga Web defines all the required CSP headers. Subsequently, +only content coming from Icinga Web's own origin is accepted, inline JS is prohibited, and inline CSS is accepted only +if it contains the nonce set in the response header. + +We decided against enabling this by default as we cannot guarantee that all the modules out there will function correctly. +Therefore, you have to manually enable this policy explicitly and accept the risks that this might break some of +the Icinga Web modules. Icinga Web and all it's components listed below, on the other hand, fully support strict CSP. If +that's not the case, please submit an issue on GitHub in the respective repositories. + +Here is a list of all Icinga Web components that are capable of strict CSP. + +| Name | CSP supported since | +|-----------------------------------|-------------------------------------------------------------------------------------------| +| Icinga DB Web | [v1.1.0](https://github.com/Icinga/icingadb-web/releases/tag/v1.1.0) | +| Icinga Reporting | [v1.0.0](https://github.com/Icinga/icingaweb2-module-reporting/releases/tag/v1.0.0) | +| Icinga IDO Reports | [v0.10.1](https://github.com/Icinga/icingaweb2-module-idoreports/releases/tag/v0.10.1) | +| Icinga Cube | [v1.3.2](https://github.com/Icinga/icingaweb2-module-cube/releases/tag/v1.3.2) | +| Icinga Business Process Modeling | [v2.5.0](https://github.com/Icinga/icingaweb2-module-businessprocess/releases/tag/v2.5.0) | +| Icinga Certificate Monitoring | [v1.3.0](https://github.com/Icinga/icingaweb2-module-x509/releases/tag/v1.3.0) | +| Icinga PDF Export | [v0.10.2](https://github.com/Icinga/icingaweb2-module-pdfexport/releases/tag/v0.10.2) | +| Icinga Web Jira Integration | [v1.3.2](https://github.com/Icinga/icingaweb2-module-jira/releases/tag/v1.3.2) | +| Icinga Web Graphite Integration | [v1.3.0](https://github.com/Icinga/icingaweb2-module-graphite/releases/tag/v1.2.4) | +| Icinga Web GenericTTS Integration | [v2.1.0](https://github.com/Icinga/icingaweb2-module-generictts/releases/tag/v2.1.0) | +| Icinga Web Nagvis Integration | [v1.2.0](https://github.com/Icinga/icingaweb2-module-nagvis/releases/tag/v1.2.0) | +| Icinga Web AWS Integration | [v1.1.0](https://github.com/Icinga/icingaweb2-module-aws/releases/tag/v1.1.0) | + + +## 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 v2.5+ uses the [native password hash algorithm](https://php.net/manual/en/faq.passwords.php) +provided by PHP 5.6+. + +In order to generate a password, run the following command with the PHP CLI >= 5.6: + +``` +php -r 'echo password_hash("yourtopsecretpassword", PASSWORD_DEFAULT);' +``` + +Please note that the hashed output changes each time. This is expected. + +Insert the user into the database using the generated password hash. + +``` +INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$2y$10$bEKU6.1bRYjE7wxktqfeO.IGV9pYAkDBeXEbjMFSNs26lKTI0JQ1q'); +``` + +#### Puppet <a id="advanced-topics-authentication-tips-manual-user-database-auth-puppet"></a> + +Please do note that the `$` character needs to be escaped with a leading backslash in your +Puppet manifests. + +Example from [puppet-icingaweb2](https://github.com/Icinga/puppet-icingaweb2): + +``` + exec { 'create default user': + command => "mysql -h '${db_host}' -P '${db_port}' -u '${db_username}' -p'${db_password}' '${db_name}' -Ns -e 'INSERT INTO icingaweb_user (name, active, password_hash) VALUES (\"icingaadmin\", 1, \"\$2y\$10\$QnXfBjl1RE6TqJcY85ZKJuP9AvAV3ont9QihMTFQ/D/vHmAWaz.lG\")'", + refreshonly => true, + } +``` + + +## 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 +about + +* manual creation of the Icinga Web 2 database `icingaweb2` including a default user (optional as authentication and session backend) +* additional configuration for the application +* additional configuration for the monitoring module (e.g. the IDO database and external command pipe from Icinga 2) + +This comes in handy if you are planning to deploy Icinga Web 2 automatically using +Puppet, Ansible, Chef, etc. + +> **Warning** +> +> Read the documentation on the respective linked configuration sections before +> deploying the configuration manually. +> +> If you are unsure about certain settings, use the setup wizard as described in the +> [installation instructions](02-Installation.md) once and then collect the generated +> configuration as well as sql dumps. + +### 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/MariaDB: + +``` +sudo mysql -p + +CREATE DATABASE icingaweb2; +GRANT CREATE, SELECT, INSERT, UPDATE, DELETE, DROP, ALTER, CREATE VIEW, INDEX, EXECUTE ON icingaweb2.* TO 'icingaweb2'@'localhost' IDENTIFIED BY 'icingaweb2'; +quit + +mysql -p icingaweb2 < /usr/share/icingaweb2/schema/mysql.schema.sql +``` + + +Then generate a new password hash as described in the [authentication docs](05-Authentication.md#authentication-configuration-db-setup) +and use it to insert a new user called `icingaadmin` into the database. + +``` +mysql -p icingaweb2 + +INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$1$EzxLOFDr$giVx3bGhVm4lDUAw6srGX1'); +quit +``` + +### 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 +Icinga 2 IDO database configuration. Example for MySQL: + +``` +vim /etc/icingaweb2/resources.ini + +[icingaweb2] +type = "db" +db = "mysql" +host = "localhost" +port = "3306" +dbname = "icingaweb2" +username = "icingaweb2" +password = "icingaweb2" + + +[icinga2] +type = "db" +db = "mysql" +host = "localhost" +port = "3306" +dbname = "icinga" +username = "icinga" +password = "icinga" +``` + +[config.ini](03-Configuration.md#configuration) defining general application settings. + +``` +vim /etc/icingaweb2/config.ini + +[logging] +log = "syslog" +level = "ERROR" +application = "icingaweb2" + + +[preferences] +type = "db" +resource = "icingaweb2" +``` + +[authentication.ini](05-Authentication.md#authentication) for e.g. using the previously created database. + +``` +vim /etc/icingaweb2/authentication.ini + +[icingaweb2] +backend = "db" +resource = "icingaweb2" +``` + + +[roles.ini](06-Security.md#security) granting the previously added `icingaadmin` user all permissions. + +``` +vim /etc/icingaweb2/roles.ini + +[admins] +users = "icingaadmin" +permissions = "*" +``` + +### Icinga Web 2 Manual Configuration Monitoring Module <a id="web-setup-manual-from-source-config-monitoring-module"></a> + + +**config.ini** defining additional security settings. + +``` +vim /etc/icingaweb2/modules/monitoring/config.ini + +[security] +protected_customvars = "*pw*,*pass*,community" +``` + +**backends.ini** referencing the Icinga 2 DB IDO resource. + +``` +vim /etc/icingaweb2/modules/monitoring/backends.ini + +[icinga2] +type = "ido" +resource = "icinga2" +``` + +**commandtransports.ini** defining the Icinga 2 API command transport. + +``` +vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = "api" +host = "localhost" +port = "5665" +username = "api" +password = "api" +``` + +### 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`. + +## Automating the Installation of Icinga Web 2 <a id="web-setup-automation"></a> + +Prior to creating your own script, please look into the official resources +which may help you already: + +* [Puppet module](https://icinga.com/products/integrations/puppet/) +* [Chef cookbook](https://icinga.com/products/integrations/chef/) + +If you are automating the installation of Icinga Web 2, you may want to skip the wizard and do things yourself. +These are the steps you'd need to take assuming you are using MySQL/MariaDB. If you are using PostgreSQL please adapt +accordingly. Note you need to have successfully completed the Icinga 2 installation, installed the Icinga Web 2 packages +and all the other steps described above first. + +1. Install PHP dependencies: `php`, `php-intl`, `php-imagick`, `php-gd`, `php-mysql`, `php-curl`, `php-mbstring` used +by Icinga Web 2. +2. Create a database for Icinga Web 2, i.e. `icingaweb2`. +3. Import the database schema: `mysql -D icingaweb2 < /usr/share/icingaweb2/schema/mysql.schema.sql`. +4. Insert administrator user in the `icingaweb2` database: +`INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('admin', 1, '<hash>')`, where `<hash>` is the output +of `php -r 'echo password_hash("yourtopsecretpassword", PASSWORD_DEFAULT);'`. +5. Make sure the `ido-mysql` and `api` features are enabled in Icinga 2: `icinga2 feature enable ido-mysql` and +`icinga2 feature enable api`. +6. Generate Apache/nginx config. This command will print an apache config for you on stdout: +`icingacli setup config webserver apache`. Similarly for nginx. You need to place that configuration in the right place, +for example `/etc/apache2/sites-enabled/icingaweb2.conf`. +7. Add `www-data` user to `icingaweb2` group if not done already (`usermod -a -G icingaweb2 www-data`). +8. Create the Icinga Web 2 configuration in `/etc/icingaweb2`. The directory can be easily created with: +`icingacli setup config directory`. This command ensures that the directory has the appropriate ownership and +permissions. If you want to create the directory manually, make sure to chown the group to `icingaweb2` and set the +access mode to `2770`. + +The structure of the configurations looks like the following: + +``` +/etc/icingaweb2/ +/etc/icingaweb2/authentication.ini +/etc/icingaweb2/modules +/etc/icingaweb2/modules/monitoring +/etc/icingaweb2/modules/monitoring/config.ini +/etc/icingaweb2/modules/monitoring/instances.ini +/etc/icingaweb2/modules/monitoring/backends.ini +/etc/icingaweb2/roles.ini +/etc/icingaweb2/config.ini +/etc/icingaweb2/enabledModules +/etc/icingaweb2/enabledModules/monitoring +/etc/icingaweb2/enabledModules/doc +/etc/icingaweb2/resources.ini +``` + +Have a look [here](20-Advanced-Topics.md#web-setup-manual-from-source-config) for the contents of the files. + +## Kiosk Mode Configuration <a id="kiosk-mode"></a> + +Be aware that when you create a kiosk user every person who has access to the kiosk is able to perform tasks on it. +Therefore you would need to create a user in the `roles.ini` in `/etc/icingaweb2/roles.ini`. + +``` +[kioskusers] +users = "kiosk" +``` + +If you need special permissions you should add those permissions to the user via the admin account in icingaweb2 to the role of the kiosk user. + +For the Dashboard system where you want to display the kiosk you can add also the following part into the `icingaweb2.conf`. +So it starts directly into the kiosk mode. +If you want to show a specific Dashboard you can enforce this onto the kiosk user via the [enforceddashboard](https://github.com/Thomas-Gelf/icingaweb2-module-enforceddashboard) module. + +``` +<ifmodule mod_authz_core.c> + # Apache 2.4 + SetEnvIf Remote_Addr "X.X.X.X" REMOTE_USER=kiosk + <requireall> + Require all granted + </requireall> +</ifmodule> +``` + +Replace Remote_Addr with the IP where the kiosk user is accessing the Web to restrict further usage from other IPs. + +## Customizing the Landing Page <a id="landing-page"></a> + +The default landing page of `dashboard` can be customized using the environment variable `ICINGAWEB_LANDING_PAGE`. + +Example on RHEL/CentOS: + +``` +vim /etc/httpd/conf.d/web.icinga.com.conf + +<VirtualHost *:80> + + ... + + <Directory "/usr/share/icingaweb2/public"> + + ... + + SetEnv ICINGAWEB_LANDING_PAGE "icingadb/services/grid?problems" + + ... + + </Directory> +</VirtualHost> +``` diff --git a/doc/60-Hooks.md b/doc/60-Hooks.md new file mode 100644 index 0000000..2dc645d --- /dev/null +++ b/doc/60-Hooks.md @@ -0,0 +1,49 @@ +# Hooks + +## ConfigFormEventsHook + +The `ConfigFormEventsHook` allows developers to hook into the handling of configuration forms. It provides three methods: + +* `appliesTo()` +* `isValid()` +* `onSuccess()` + +`appliesTo()` determines whether the hook should run for a given configuration form. +Developers should use `instanceof` checks in order to decide whether the hook should run or not. +If `appliesTo()` returns `false`, `isValid()` and `onSuccess()` won't get called for this hook. + +`isValid()` is called after the configuration form has been validated successfully. +An exception thrown here indicates form errors and prevents the config from being stored. +The exception's error message is shown in the frontend automatically. +If there are multiple hooks indicating errors, every error will be displayed. + +`onSuccess()` is called after the configuration has been stored successfully. +Form handling can't be interrupted here. Any exception will be caught, logged and notified. + +Hook example: + +```php +namespace Icinga\Module\Acme\ProvidedHook; + +use Icinga\Application\Hook\ConfigFormEventsHook; +use Icinga\Forms\ConfigForm; +use Icinga\Forms\Security\RoleForm; + +class ConfigFormEvents extends ConfigFormEventsHook +{ + public function appliesTo(ConfigForm $form) + { + return $form instanceof RoleForm; + } + + public function onSuccess(ConfigForm $form) + { + $this->updateMyModuleConfig(); + } + + protected function updateMyModuleConfig() + { + // ... + } +} +``` diff --git a/doc/70-Troubleshooting.md b/doc/70-Troubleshooting.md new file mode 100644 index 0000000..d71e08a --- /dev/null +++ b/doc/70-Troubleshooting.md @@ -0,0 +1,17 @@ +# Troubleshooting <a id="troubleshooting"></a> + +## 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 +following methods. + +**Apache**: +``` +ModPagespeedDisallow "*/icingaweb2/*" +``` + +**Nginx**: +``` +pagespeed Disallow "*/icingaweb2/*"; +``` + diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md new file mode 100644 index 0000000..c6f4b7b --- /dev/null +++ b/doc/80-Upgrading.md @@ -0,0 +1,435 @@ +# Upgrading Icinga Web 2 <a id="upgrading"></a> + +Specific version upgrades are described below. Please note that upgrades are incremental. An upgrade from +v2.6 to v2.8 requires to follow the instructions for v2.7 too. + +## Upgrading to Icinga Web 2.12.0 + +**Database Schema** + +With the latest Icinga Web versions, you no longer need to manually import sql upgrade scripts. Icinga Web `>= 2.12` +offers you the possibility to perform such migrations in an easy way. You can find and apply all pending migrations +of your Icinga Web environment in the menu at `System -> Migrations`. + +You can still apply the `2.12.0.sql` upgrade script manually, depending on your database vendor. +For package installations you can find this file in `/usr/share/icingaweb2/schema/*-upgrades/`. + +## Upgrading to Icinga Web 2.11.x + +**General** + +* Support for Internet Explorer 11 has been removed. +* The Vagrant file and all its assets have been removed. + +**Database Schema** + +* Please apply the `v2.11.0.sql` upgrade script depending on your database vendor. + As of version `2.11.4`, upgrade scripts can be found at `/usr/share/icingaweb2/schema/*-upgrades/`. + Older versions install these files to `/usr/share/doc/icingaweb2/schema/*-upgrades/` for RPM-based systems + and `/usr/share/icingaweb2/etc/schema/*-upgrades/` for Debian or Ubuntu. + +**Breaking changes** + +* The `user:local_name` macro in restrictions has been removed. Use `user.local_name` now. +* User preferences stored in INI files are not loaded anymore. Migrate yours with + `icingacli migrate preferences` before the upgrade, if you haven't already. + +**Framework changes affecting third-party code** + +* When loading library CSS assets, CSS files and LESS files are handled differently now. Only the latter + is parsed as LESS. +* jQuery is not bundled anymore as it's now part of the library icinga-php-thirdparty v0.11.0. It's shipped there + in version 3.6.0. (Previously bundled was jQuery 3.4.1) +* All the following classes have been removed: + * `Icinga\User\Preferences\Store\IniStore`: Preferences in INI files are not supported anymore. + * `Icinga\User\Preferences\Store\DbStore`: Its methods have been added to the `PreferencesStore` class. + * `Icinga\Util\String`: Use `Icinga\Util\StringHelper` instead. + * `Icinga\Util\Translator`: Use `\ipl\I18n\StaticTranslator::$instance` or `\ipl\I18n\Translation` instead. + * `Icinga\Module\Migrate\Clicommands\DashboardCommand`: Deleted without substitution. + * `Icinga\Web\Hook\TicketHook`: Use `Icinga\Application\Hook\TicketHook` instead. + * `Icinga\Web\Hook\GrapherHook`: Use `Icinga\Application\Hook\GrapherHook` instead. + * `Icinga\Module\Monitoring\Environment`: Not in use. + * `Icinga\Module\Monitoring\Backend`: Use `Icinga\Module\Monitoring\Backend\MonitoringBackend` instead. +* All the following methods have been removed: + * `loader.js.addUrlFlag()`: Use `Icinga.Utils.addUrlFlag()` instead. + * `Url::setBaseUrl()`: Please create a new url from scratch instead. + * `Url::getBaseUrl()`: Use either `Url::getBasePath()` or `Url::getAbsoluteUrl()` now. + * `ApplicationBootstrap::setupZendAutoloader()`: Since it does nothing, all usages removed. + * `ApplicationBootstrap::listLocales()`: Use `\ipl\I18n\GettextTranslator::listLocales()` instead. + * `Module::registerHook()`: Use `provideHook()` instead. + * `Web::getMenu()`: Instantiate the menu class `new Menu()` directly instead. + * `AesCrypt::encryptToBase64()`: Use `AesCrypt::encrypt()` instead as it also returns a base64 encoded string. + * `AesCrypt::decryptFromBase64()`: Use `AesCrypt::decrypt()` instead as it also returns a base64 decoded string. + * `InlinePie::disableNoScript()`: Empty method. + * `SimpleQuery::paginate()`: Use `Icinga\Web\Controller::setupPaginationControl()` and/or `Icinga\Web\Widget\Paginator` instead. + * `LdapConnection::connect()`: The connection is established lazily since .. a long time. + * `MonitoredObject::matches()`: Use `$filter->matches($object)` instead. + * `MonitoredObject::fromParams()`: Deleted without substitution. + * `DataView::fromRequest()`: Use `$backend->select()->from($viewName)` instead. + * `DataView::sort()`: Use `DataView::order()` instead. + * `MonitoringBackend::createBackend()`: Use `MonitoringBackend::instance()` instead. + * `DbConnection::getConnection()`: Use `Connection::getDbAdapter()` instead. + * `DbQuery::renderFilter()`: Use `DbConnection::renderFilter()` instead. + * `DbQuery::whereToSql()`: Use `DbConnection::renderFilter()` instead. + +## Upgrading to Icinga Web 2 2.10.x + +**General** + +* The theme "solarized-dark" has been removed due to the introduction of the new default dark mode. + +**Deprecations** + +* Builtin support for PDF exports using the `dompdf` library will be dropped with version 2.12. + It is highly recommended to use [Icinga PDF Export](https://github.com/Icinga/icingaweb2-module-pdfexport) + instead. + +**Discontinued package updates** + +* We will stop offering major updates for Debian 9 (Stretch) starting with version 2.11. + However, versions 2.9 and 2.10 will continue to receive minor updates on this platform. + +[icinga.com](https://icinga.com/subscription/support-details/) provides an overview about +currently supported distributions. + +**Framework changes affecting third-party code** + +* Asset support for modules (#3961) introduced with v2.8 has now been removed. +* `expandable-toggle`-support has been removed. Use `class="collapsible" data-visible-height=0` + to achieve the same effect. (Available since v2.7.0) +* The `.var()` LESS mixin and the LESS function `extract-variable-default` have been removed (introduced with v2.9) + +## Upgrading to Icinga Web 2 2.9.1 + +**Database Schema** + +* Please apply the `v2.9.1.sql` upgrade script depending on your database vendor. + In package installations this file can be found in `/usr/share/doc/icingaweb2/schema/*-upgrades/` + (Debian/Ubuntu: `/usr/share/icingaweb2/etc/schema/*-upgrades/`). + +## Upgrading to Icinga Web 2 2.9.x + +**Installation** + +* Icinga Web 2 now requires the [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.6) + and [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10). Please make sure to + install both when upgrading. We provide packages for them and if you've installed Icinga Web 2 already by + package they should be installed automatically during the upgrade. +* [Icinga Business Process Modelling](https://github.com/Icinga/icingaweb2-module-businessprocess/releases/tag/v2.3.1) + has been updated to v2.3.1. If you're using this module, this version is required when upgrading. + +**General** + +* For database connections to the IDO running on MySQL, a default charset (`latin1`) is now applied. + If you had previously problems with special characters and umlauts and you've set this charset + already manually, no change is required. However, if your IDO resource configuration has another + charset configured than this, it is highly recommended to clear this setting. Otherwise the default + won't apply and characters may still be shown incorrectly in the UI. + +**Database Schema** + +* Icinga Web 2 now permits its users to stay logged in. This requires a new database table. + * Please apply the `v2.9.0.sql` upgrade script depending on your database vendor. + In package installations this file can be found in `/usr/share/doc/icingaweb2/schema/*-upgrades/` + (Debian/Ubuntu: `/usr/share/icingaweb2/etc/schema/*-upgrades/`). + +**Breaking changes** + +* Password changes are not allowed by default anymore + * The fake refusal `no-user/password-change` has now been changed to a grant `user/password-change`. + Any user that had `no-user/password-change` previously still cannot change passwords. Though any + user that didn't have this *permission*, needs to be granted `user/password-change` now in order + to change passwords. + +**Deprecations** + +* Support for EOL PHP versions (5.6, 7.0, 7.1 and 7.2) will be removed with version 2.11 +* Support for Internet Explorer will be completely removed with version 2.11 + * New features after v2.9 will already not (necessarily) be available in Internet Explorer +* `user.local_name` replaces the `user:local_name` macro in restrictions, and the latter will be removed with + version 2.11 +* The configuration backend type `INI` is not configurable anymore. **A database is now mandatory.** + * Existing configurations using this configuration backend type will stop working with the + release of v2.11. + * To migrate your local user preferences to database, enable the `migrate` module and use the command + `icingacli migrate preferences`. If you already setup the configuration database, it will work right + away. If not, pass it the resource you'd like to use as configuration database with `--resource=`. + * Note that this only applies to user preferences. Other configurations are still stored + in `.ini` files. (#3770) +* The Vagrant file and all its assets will be removed with version 2.11 + +**Framework changes affecting third-party code** + +* The `jquery-migrate` compatibility layer for Javascript code working with jQuery 2.x has been removed. + It has been introduced with v2.7 when we upgraded jQuery to v3.4.1 in order to allow module developers + a seamless upgrade chance. If a module still has UI glitches after an upgrade to v2.9, please contact + the module developer. +* The method `getHtmlForEvent` of the `EventDetailsExtensionHook` previously received the host or service + object of an event. Now the actual event object is passed to it instead. +* Asset support for modules (#3961) introduced with v2.8 has now been deprecated in favor of library + support (#4272) and will be removed with v2.10. We don't expect broad usage of this feature since + it's been introduced with the latest major version, so it's already being removed with the next one. + +## Upgrading to Icinga Web 2 2.8.x + +**Changes in packaging and dependencies** + +Valid for distributions: + +* RHEL / CentOS 7 + * Upgrade to PHP 7.3 via RedHat SCL + +After upgrading to version 2.8.0 you'll get the new `rh-php73` dependency installed. This is a drop-in replacement +for the previous `rh-php71` dependency and only requires the setup of a new fpm service and possibly some copying +of customized configurations. + +**php.ini or php-fpm settings** you have tuned in the past need to be copied over to the new path: + +From `/etc/opt/rh/rh-php71/` to `/etc/opt/rh/rh-php73/`. + +Don't forget to also install any additional **php-modules** for PHP 7.3 you've had previously installed +for e.g. Icinga Web 2 modules. + +There's also a new **service** included which replaces the previous one for php-fpm: + +Stop the old service: `systemctl stop rh-php71-php-fpm.service` +Start the new service: `systemctl start rh-php73-php-fpm.service` + +You can now safely remove the previous dependency if you like: + +`yum remove rh-php71*` + +**Discontinued package updates** + +Icinga Web 2 v2.8+ is not supported on these platforms: + +* RHEL / CentOS 6 +* Debian 8 Jessie +* Ubuntu 16.04 LTS (Xenial Xerus) + +Please consider an upgrade of your central Icinga system to a newer distribution release. + +[icinga.com](https://icinga.com/subscription/support-details/) provides an overview about +currently supported distributions. + +**Framework changes affecting third-party code** + +* Url parameter `view=compact` is now deprecated. `showCompact` should be used instead. + Details are in pull request [#4164](https://github.com/Icinga/icingaweb2/pull/4164). +* Form elements of type checkbox now need to be checked prior submission if they're + required. Previously setting `required => true` didn't cause the browser to complain + if such a checkbox wasn't checked. Browsers now do complain if so. +* The general layout now uses flexbox instead of fixed positioning. This applies to the + `#header`, `#sidebar`, `#main`, `#footer`, `#col1`, `#col2` and a column's controls. + `#sidebar` and `#main` are now additionally wrapped in a new container `#content-wrapper`. + +## Upgrading to Icinga Web 2 2.7.x <a id="upgrading-to-2.7.x"></a> + +**Breaking changes** + +* We've upgraded jQuery to version 3.4.1. If you're a module developer, please add `?_dev` to your address bar to check + for log messages emitted by jquery-migrate. (https://github.com/jquery/jquery-migrate) Your javascript code will still + work, though jquery-migrate will notify you if you're utilizing deprecated/removed functions. jquery-migrate will be + removed with Icinga Web v2.8 and code not adjusted accordingly will stop working. +* If you're using a language other than english and you've adjusted or disabled module dashboards, you'll need to + update all of your `dashboard.ini` files. A CLI command exists to assist you with this task. Enable the `migrate` + module and run the following on the host where these files exist: `icingacli migrate dashboard sections --verbose` + +## Upgrading to Icinga Web 2 2.6.x <a id="upgrading-to-2.6.x"></a> + +* Icinga Web 2 version 2.6.x does not introduce any backward incompatible change. + +## Upgrading to Icinga Web 2 2.5.x <a id="upgrading-to-2.5.x"></a> + +> **Attention** +> +> Icinga Web 2 v2.5 requires **at least PHP 5.6**. + +**Breaking changes** + +* Hash marks (`#`) in INI files are no longer recognized as comments by + [parse_ini_file](https://secure.php.net/manual/en/function.parse-ini-file.php) since PHP 7.0. +* Existing sessions of logged-in users do no longer work as expected due to a change in the `User` data structure. + Everyone who was logged in before the upgrade has to log out once. + +**Changes in packaging and dependencies** + +Valid for distributions: + +* RHEL / CentOS 6 + 7 + * Upgrading to PHP 7.0 / 7.1 via RedHat SCL (new dependency) + * See [Upgrading to FPM](02-Installation.md#upgrading-to-fpm) for manual steps that + are required +* SUSE SLE 12 + * Upgrading PHP to >= 5.6.0 via the alternative packages. + You might have to confirm the replacement of PHP < 5.6 - but that + should work with any other PHP app as well. + * Make sure to enable the new Apache module `a2enmod php7` and restart `apache2` + +**Discontinued package updates** + +Icinga Web 2 v2.5+ is not supported on these platforms: + +* Debian 7 wheezy +* Ubuntu 14.04 LTS (trusty) +* SUSE SLE 11 (all service packs) + +Please consider an upgrade of your central Icinga system to a newer distribution release. + +[packages.icinga.com](https://packages.icinga.com) provides an overview about currently supported distributions. + +**Database schema** + +Icinga Web 2 v2.5.0 requires a schema update for the database. The database schema has been adjusted to support +usernames up to 254 characters. This is necessary to support the new domain-aware authentication feature. + +Continue here for [MySQL](80-Upgrading.md#upgrading-mysql-db) and [PostgreSQL](80-Upgrading.md#upgrading-pgsql-db). + +## 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. + +## 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. + +## 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 + group backend configuration which was previously found beneath `Authentication` has been moved to `Application`. + +## 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`. + Users who changed the configuration manually and used the option `filter` instead + have to change it back to `group_filter`. + +## 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 + the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library + through the package `icingaweb2-vendor-zend`. After upgrading, please make sure to remove the package + `icingaweb2-vendor-zend`. + +* Icinga Web 2 version 2.0.0 requires permissions for accessing modules. Those permissions are automatically generated + for each installed module in the format `module/<moduleName>`. Administrators have to grant the module permissions to + users and/or user groups in the roles configuration for permitting access to specific modules. + In addition, restrictions provided by modules are now configurable for each installed module too. Before, + a module had to be enabled before having the possibility to configure restrictions. + +* The **instances.ini** configuration file provided by the monitoring module + has been renamed to **commandtransports.ini**. The content and location of + the file remains unchanged. + +* The location of a user's preferences has been changed from + **<config-dir>/preferences/<username>.ini** to + **<config-dir>/preferences/<username>/config.ini**. + The content of the file remains unchanged. + +## 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 database schema has been adjusted and the tables `icingaweb_group` and + `icingaweb_group_membership` were altered to ensure referential integrity. + Please use the upgrade script located in **etc/schema/** to update your + database schema + +* Users who are using PostgreSQL < v9.1 are required to upgrade their + environment to v9.1+ as this is the new minimum required version + for utilizing PostgreSQL as database backend + +* The restrictions `monitoring/hosts/filter` and `monitoring/services/filter` + provided by the monitoring module were merged together. The new + restriction is called `monitoring/filter/objects` and supports only a + predefined subset of filter columns. Please see the module's security + related documentation for more details. + +## 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 +configuration files after upgrading to Icinga Web 2 Beta 3. + +## 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, +you are required to create the file **roles.ini** beneath Icinga Web 2's configuration directory with the following +content: +``` +[administrators] +users = "your_user_name, another_user_name" +permissions = "*" +``` + +After please log out from Icinga Web 2 and log in again for having all permissions granted. + +If you delegated authentication to your web server using the `autologin` backend, you have to switch to the `external` +authentication backend to be able to log in again. The new name better reflects +what's going on. A similar change +affects environments that opted for not storing preferences, your new backend is `none`. + +## Upgrading the MySQL Database <a id="upgrading-mysql-db"></a> + +If you installed Icinga Web 2 from package, please check the upgrade scripts located in +**/usr/share/doc/icingaweb2/schema/mysql-upgrades** (Debian/Ubuntu: **/usr/share/icingaweb2/etc/schema/mysql-upgrades**) +to update your database schema. +In case you installed Icinga Web 2 from source, please find the upgrade scripts in **etc/schema/mysql-upgrades**. + +> **Note** +> +> If there isn't an upgrade file for your current version available, there's nothing to do. + +Apply all database schema upgrade files incrementally. + +``` +# mysql -u root -p icingaweb2 < /usr/share/doc/icingaweb2/schema/mysql-upgrades/<version>.sql +``` + +**Example:** You are upgrading Icinga Web 2 from version `2.4.0` to `2.5.0`. Look into +the `upgrade` directory: + +``` +$ ls /usr/share/doc/icingaweb2/schema/mysql-upgrades/ +2.0.0beta3-2.0.0rc1.sql 2.5.0.sql +``` + +The upgrade file `2.5.0.sql` must be applied for the v2.5.0 release. If there are multiple +upgrade files involved, apply them incrementally. + +``` +# mysql -u root -p icinga < /usr/share/doc/icingaweb2/schema/mysql-upgrades/2.5.0.sql +``` + +## Upgrading the PostgreSQL Database <a id="upgrading-pgsql-db"></a> + +If you installed Icinga Web 2 from package, please check the upgrade scripts located in +**/usr/share/doc/icingaweb2/schema/pgsql-upgrades** (Debian/Ubuntu: **/usr/share/icingaweb2/etc/schema/pgsql-upgrades**) +to update your database schema. +In case you installed Icinga Web 2 from source, please find the upgrade scripts in **etc/schema/pgsql-upgrades**. + +> **Note** +> +> If there isn't an upgrade file for your current version available, there's nothing to do. + +Apply all database schema upgrade files incrementally. + +``` +# export PGPASSWORD=icingaweb2 +# psql -U icingaweb2 -d icingaweb2 < /usr/share/doc/icingaweb2/schema/pgsql-upgrades/<version>.sql +``` + +**Example:** You are upgrading Icinga Web 2 from version `2.4.0` to `2.5.0`. Look into +the `upgrade` directory: + +``` +$ ls /usr/share/doc/icingaweb2/schema/pgsql-upgrades/ +2.0.0beta3-2.0.0rc1.sql 2.5.0.sql +``` + +The upgrade file `2.5.0.sql` must be applied for the v2.5.0 release. If there are multiple +upgrade files involved, apply them incrementally. + +``` +# export PGPASSWORD=icingaweb2 +# psql -U icingaweb2 -d icingaweb2 < /usr/share/doc/icingaweb2/schema/pgsql-upgrades/2.5.0.sql +``` diff --git a/doc/90-SELinux.md b/doc/90-SELinux.md new file mode 100644 index 0000000..d19ca82 --- /dev/null +++ b/doc/90-SELinux.md @@ -0,0 +1,76 @@ +# SELinux <a id="selinux"></a> + +## 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 +to all resources on the system such as files, devices, networks and inter-process communication. + +The most important questions are answered briefly in the [FAQ of the SELinux Project](https://selinuxproject.org/page/FAQ). +For more details on SELinux and how to actually use and administrate it on your systems have a look at +[Red Hat Enterprise Linux 7 - SELinux User's and Administrator's Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/index.html). +For a simplified (and funny) introduction download the [SELinux Coloring Book](https://github.com/mairin/selinux-coloring-book). + + +## Policy <a id="selinux-policy"></a> + +Icinga Web 2 is providing its own SELinux policy for RPM-based systems running the targeted policy +which confines Icinga Web 2 with support for all its modules. + +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. + +Use your distribution's package manager to install the `icingaweb2-selinux` package. + +## 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 +configuration `icingaweb2_config_t` to allow confining access to it. + +## 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 +`icingaweb2_read_config` and `icingaweb2_manage_config`. +Files requiring read access are labeled `icingaweb2_content_t`. Files requiring write access are labeled +`icingaweb2_rw_content_t`. + +## 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 +a defined way. The Icinga Web 2 policy package provides the following booleans. + +**httpd_can_manage_icingaweb2_config** + +Having this boolean enabled allows httpd to write to the configuration labeled `icingaweb2_config_t`. This is enabled by +default. If not needed, you can disable it for more security. But this will disable all web based configuration of +Icinga Web 2. + +### Optional Booleans <a id="selinux-optional-booleans"></a> + +The Icinga Web 2 policy package does not enable booleans not required by default. In order to allow these things, +you'll need to enable them manually. (i.e. with the tool `setsebool`) + +**Ldap** +If you want to allow httpd to connect to the ldap port, you must turn on the `httpd_can_connect_ldap` boolean. +Disabled by default. + +## 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 +problem persists, it is not related to SELinux because in permissive mode SELinux will not deny anything. + +When filing a bug report please add the following information additionally to the +[common ones](https://icinga.com/icinga/faq/): +* Output of `semodule -l | grep -e icinga2 -e icingaweb2 -e nagios -e apache` +* Output of `semanage boolean -l | grep icinga` +* Output of `ps -eZ | grep httpd` +* Output of `audit2allow -li /var/log/audit/audit.log` + +If access to a file is blocked and you can tell which one, please provided the output of `ls -lZ /path/to/file` and the +directory above. + +If asked for full audit.log, add `-w /etc/shadow -p w` to `/etc/audit/rules.d/audit.rules` and restart the audit daemon. +Reproduce the problem and add `/var/log/audit/audit.log` to the bug report. The added audit rule includes +the path of files where access was denied. + +If asked to provide full audit log with dontaudit rules disabled, execute `semodule -DB` before reproducing the problem. +After that enable the rules again to prevent auditd spamming your logfile by executing `semodule -B`. diff --git a/doc/accessibility/ifont-mute.html b/doc/accessibility/ifont-mute.html new file mode 100644 index 0000000..f8252e3 --- /dev/null +++ b/doc/accessibility/ifont-mute.html @@ -0,0 +1,21 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Muted Icon Fonts</title> + <meta name="description" content="Accessible icon fonts"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <style type="text/css"> + .icon-star:before { + content: "★"; + } + </style> +</head> +<body> +<a href="#"> + <i aria-hidden="true" class="icon-star"></i> + Visit top rated article +</a> +</body> +</html> diff --git a/doc/accessibility/ifont.html b/doc/accessibility/ifont.html new file mode 100644 index 0000000..32f1221 --- /dev/null +++ b/doc/accessibility/ifont.html @@ -0,0 +1,18 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Icon Fonts</title> + <meta name="description" content="Accessible icon fonts"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <style type="text/css"> + .icon-star:before { + content: "★"; + } + </style> +</head> +<body> + <i role="img" class="icon-star" aria-label="Top rated article" title="Top rated article"></i> +</body> +</html>
\ No newline at end of file diff --git a/doc/accessibility/link-labels.html b/doc/accessibility/link-labels.html new file mode 100644 index 0000000..439adb8 --- /dev/null +++ b/doc/accessibility/link-labels.html @@ -0,0 +1,15 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Link Labels</title> + <meta name="description" content="Accessible links"> + <meta name="viewport" content="width=device-width, initial-scale=1"> +</head> +<body> + <a href="/monitoring/host/show?host=localhost" + title="Show detailed information about the host localhost" + aria-label="Show detailed information about the host localhost">localhost</a> +</body> +</html>
\ No newline at end of file diff --git a/doc/accessibility/required-form-elements.html b/doc/accessibility/required-form-elements.html new file mode 100644 index 0000000..86fc937 --- /dev/null +++ b/doc/accessibility/required-form-elements.html @@ -0,0 +1,19 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Required form elements</title> + <meta name="description" content="Required form elements"> + <meta name="viewport" content="width=device-width, initial-scale=1"> +</head> +<body> + <form> + <label> + Enter some text: + <input type="text" name="some_text" value="" aria-required="true" required> + </label> + <input type="submit" name="btn_submit" value="Submit"> + </form> +</body> +</html>
\ No newline at end of file diff --git a/doc/accessibility/skip-content.html b/doc/accessibility/skip-content.html new file mode 100644 index 0000000..3c1b2b4 --- /dev/null +++ b/doc/accessibility/skip-content.html @@ -0,0 +1,179 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Skip Links</title> + <meta name="description" content="Accessible skip links"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <style type="text/css"> + .sr-only { + border: 0; + clip: rect(0 0 0 0); + height: 1px; + margin: -1px; + overflow: hidden; + padding: 0; + position: absolute; + width: 1px; + } + .clearfix { + *zoom: 1; + } + .clearfix:before, + .clearfix:after { + display: table; + content: ""; + line-height: 0; + } + .clearfix:after { + clear: both; + } + body { + margin: 0; + padding: 0; + } + .head { + background-color: #049baf; + padding: 5px; + } + .nav { + width: 200px; + float: left; + margin: 0 20px 20px 0; + padding: 0 20px 20px 0; + } + .container { + margin: 10px 0 0 0; + } + .content { + overflow: auto; + } + .skip-links { + position: absolute; + opacity: 1; + } + .skip-links-inline { + margin-top: -3.5em; + } + .skip-links ul { + list-style-type: none; + margin: 0; + padding: 0; + } + .skip-links ul li { + display: inline; + margin: 0; + padding: 0; + } + .skip-links ul li a { + position: absolute; + display: block; + left: -999em; + width: 200px; + padding: 0.6em; + background-color: white; + } + .skip-links ul li a:focus { + left: 0; + } + </style> +</head> +<body> + <div class="head"> + <div class="skip-links"> + <nav> + <h1 class="sr-only">Skip Links</h1> + <ul> + <li><a tabindex="0" href="#content">Skip to Content</a></li> + <li><a tabindex="0" href="#searchField">Skip to Search</a></li> + <li><a tabindex="0" href="#navigation">Skip to Navigation</a></li> + </ul> + </nav> + </div> + <div id="logo"> + <a href="skip-content.html"> + <img width="92" height="32" title="" alt="" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFwAAAAgCAYAAACfDx/iAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAABcSAAAXEgFnn9JSAAAAB3RJTUUH3gkEDx0B5aU5bgAACCxJREFUaN7tmn2slmUdx7+/5+UcPFhAeQR0SSnOEodFWSPZdGxGZsWhiZFZq+myl5WZDWchIW4VODa3cDPNNWfFS9aquWmWyaJss1qDcE1txstKFPCEHA7ynPM8n/7gdx1/XN73cx7o0B9xru3e/dzX+/W9vtfv7Xqk40zAdOAhYAjYClzk+RpPY5iAKlAHnuS1ado4Qu1T5TjaVCVNlnRRyGv5e+E4pGMPOJKGJA1k35L0z3FIx16kmL9XZOJk07gMHz0l8GRmEVSZ2WvyA6BmZgD3SPqXpG1m9iBQM7PhcVjbM1aAAV3AJ4CzIpPbtFsInBO+a+MMHz3VnK4AWyW9RVIX0COpATRz5rvcr0s6VdJOoCqpaWbDRSclKFrzehSdnJNGabromCjpXElNz59tZs2c6WYmM2tJ6pU0aGZDZjayKUUget40STNi3kl7EtLCgZuBg8A6YFkmJq4A7gDuAj4GLE2b4SKpnXL9NHAAeAW4H6j5qRiX5cGx6QZuB3qBfwRLpAU0gQawIGunCD7Q5e9mZs3Mcn1x0gNdcSAqDtwZDlDD3feWP8P+BniXb1AVqGT9ngXM9XrD/gDMcU/15FSaQf62gIabfAI+GxSrZZ5mSg+bWW8A+UJJl3udbZK2SLpJ0hqv8pjnlZqhUcb/PypWK2B8zS2RJyS9s03bpgN7naTTJPVIetzMNsW4i5k1gV5Jp5nZ33IbHzAzo+z0FWyERUsnbky7TYonqmSzO5rHaP3HuRQZErWSTahJOrPjXTNbFQaueB+tZOlI2ivpYKrOkdXFDXmzpI9IOsdDBX+X9EMz2wPUzWwokcHNz14vGwE/OWNer0/SeyRNkPSSpMfM7Amg4ic53/Q0jzdKWixpppNuu6SNZrYb6DKzRhvQU9+zzWxrJyQYYbgrzb/SPg0lOZ4rzUwvzAB2ugV0ZWS/v1cFnZCn5cEaSlbPg172k9iP/54FPO96J6YG8Dvg1NBPJIiALwY9k6fVYT2lJyeEq3/teqo6qq4KE1rbAeDDcdIFHmwFWBwsnPXZItd72aGC/g/6+zuhz4luXvYnWgMTfJw5AdzhAsABdjjo1YwYa9rMY9DfG9t54MBs4OXQx9udvB1bL2c4SIcKGJjY/cGySQTAPxra/SiUf8HzXvH3duAmYGkwRdO4lzjLJzkAgwHwHn8PBIsI4F7gBuBh/z7s780Zsfqy8n3A14FbgGc9L5m2i3xNloVFzM3omJ7MT2C72Er6fX4Ju5vA16Lz0wbwqyLgnt8D/CnkbwziLLH/8VD+K8+b4gQYAdzzbwygtYDzMlCvCeVN4OIw3qNhnN8WzOOhUP7nPG7kprS5c5efqJmFsZQCVzxNdrukr7rCmyepW9IOSY9IqqcFHaMZV5V0uqRZ/r1f0uecqYdCvas9EilJT4fYe1FaIqkhqUvSMjN7GqhLGgZOMbMfAEskXeH1F0j6vaRJrlzlMf1rgQmSDgf5fI2kfa5En8nmYa5IP+mxpWS5Vf33bZI+fpTFknmKlchYYE2bk3C9K9daEcvbMLwKvDWyJsjh/ISdCVwavNbXlzB8R5CdF2R9pfDDl8OY93q7qeHEPucnyArmMR14v5/MWJ5OUH8QSRtCn7t9DSP4VHJmm1ky2T4l6VtAdxAdUUv/TNI6SVeV2a8dplZijAfHYtkeSZsljRZjj+MfTv6F92XpPYo53PJnZB4Bk+fN7BEzG5REKAdY5CfFwsnc5thOlTTfyww44mkC50taJmk6sE/SfZIOmdnetJsOaiTWfEmLJH3IZdszbY58budbG8CiudXwumMRB+i4j2Cvf1fSG7xtXdIvzexul+84Jtf5HOuSVrk9v0HSBd7dCjN7INnxNVcwT2Ue5EJJHygKpQYG/kLSXyQ95TJz7Nzfo1nOiQK2zfgt4FZJn3HWVxyXPuDHkvolVYEZki4LOuAe34y7JN3i7c4G5prZHwDVJK0tUGqStNLvKaPHGNk3aGZzkrg5BrHCaCGG4AFW0mL/S7F1POnZ5EFmc5wkqd893qud2UkkbfL1NdzASBu11sMkVpN0acmA57rmHQgXEzGmQbBSjuUWxzpheHK39epfMP6XEVQzs/XADpf3v3E9MiEwviVpZSBQTdKbMkmB13sHcKGZbalIeqFk3AEfhDJQXMFSdtvThuFRCU52Nli24Cbwc9/Yy04Utg6MObl69OoFuST90cw2B+AkqeHs/lJ2YodcYadn2NvUvf/r03FZHRo0kw0q6admdiBn9xgt8t+Sdvr3TEkLHOBuVy74rdKHvf7qgtDwWKRBFx3mFkWfy+9uSV0O7LUOWpcTK/kGSx2riqRvSrrYpcUl/sxPIHu6EpiS7MnvZZ7khrG42Ciyw0P5feFSIwGcypZn87nZ8yeV2OHbgx0+MwaNgscY7fDvh7ars7FWhrY3ZDdWd4ZwQCuUWZEL717o1lBvcZzQNOB9wOn+Xc+jYccJeIylrA/lU4C9WRyjKOC0E3id95UAH8gA3xWCXeeVAP6V0Pf9WUBsVwfz2OOOUhV4IJTf4XOrlIQ4bg2k2pLszYqZ7TazR83sRf8eOkbZXJZeDL/3BhndL+ndOvL3uC4/ns0g1uru+MwzswNm1jKz/V4+MRtjl8tfuU6qHr1mqsEtl6TngjV0UNJcLy+bxz5J7zWzF1yR10Nf69ySa+UXG97/7UE/nXJC70oDy/qAG0vuUc1ZsD+ImJeBFQWBIgGTgW8DZ2dx8m8A8/KAWjaPJcDnC/IrIQj2kouApgekbovzCKJtOXB5UVy8YJ1vA+4Epv4HBqUeGKwVd68AAAAASUVORK5CYII=" /> + </a> + </div> + </div> + <div class="container clearfix"> + <div class="nav"> + <h1 class="sr-only">Navigation</h1> + + <div id="search"> + <h2 class="sr-only">Search</h2> + <form> + <fieldset> + <label for="searchField">Search</label> + <input type="text" name="searchField" id="searchField" /> + </fieldset> + </form> + </div> + <nav> + <h2 id="navigation" tabindex="0" class="sr-only">Site Links</h2> + <ul> + <li><a href="#">Link1</a></li> + <li><a href="#">Link2</a></li> + <li><a href="#">Link3</a></li> + </ul> + </nav> + </div> + <div class="content"> + <h1 tabindex="0" id="content">Content</h1> + <div class="skip-links skip-links-inline"> + <nav> + <ul> + <li><a tabindex="0" href="#content2">Skip content</a></li> + </ul> + </nav> + </div> + <p> + Organised prehistoric cultures began developing on Bulgarian lands + during the Neolithic period. Its ancient history saw the presence + of the Thracians and later the Greeks and Romans. The emergence of + a unified Bulgarian state dates back to the establishment of the + <a href="#">First Bulgarian Empire</a> + in 681 CE, which dominated most of the + Balkans and functioned as a cultural hub for Slavs during the + Middle Ages. + </p> + <p> + With the downfall of the Second Bulgarian Empire in 1396, its + <a href="#">territories came under Ottoman</a> + rule for nearly five centuries. + The Russo-Turkish War (1877–78) led to the formation of the Third + Bulgarian State. The following years saw several conflicts with its + neighbours, which prompted Bulgaria to align with Germany in both + world wars. + </p> + <p> + In 1946 it became a single-party socialist state as part of the + Soviet-led Eastern Bloc. In December 1989 the ruling Communist + Party allowed multi-party elections, which subsequently led to + Bulgaria's transition into a democracy and a market-based economy. + </p> + + <h1 tabindex="0" id="content2">Content2</h1> + <p> + The development of Final Fantasy VIII began in 1997, during the + English localization process of Final Fantasy VII. It was produced + <a href="#">by Shinji Hashimoto</a>, + and directed by Yoshinori Kitase. The music + was scored by regular series composer Nobuo Uematsu, and in a + series first a vocal piece was written as the game's theme, "Eyes + on Me", performed by Faye Wong. + </p> + <p> + The game was positively received by + critics, + <a href="#">who praised the originality </a> + and scope of the game. It was + voted the 22nd-best game of all time in 2006 by readers of the + Japanese magazine Famitsu. The game was a commercial success; + thirteen weeks after its release, + </p> + </div> + </div> +</body> +</html>
\ No newline at end of file diff --git a/doc/accessibility/svg.html b/doc/accessibility/svg.html new file mode 100644 index 0000000..8ee548f --- /dev/null +++ b/doc/accessibility/svg.html @@ -0,0 +1,19 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: SVGs</title> + <meta name="description" content="Accessible icon fonts"> + <meta name="viewport" content="width=device-width, initial-scale=1"> +</head> +<body> +<svg version="1.2" role="img" aria-labelledby="title desc" tabindex="0"> + <title id="title">A Circle</title> + <desc id="desc">A red circle with a black border.</desc> + <circle cy="50" cx="50" r="50" stroke="black" stroke-width="1" fill="red" /> +</svg> +</body> +</html> + + diff --git a/doc/accessibility/text-cue-for-required-form-control-labels.html b/doc/accessibility/text-cue-for-required-form-control-labels.html new file mode 100644 index 0000000..1dd38eb --- /dev/null +++ b/doc/accessibility/text-cue-for-required-form-control-labels.html @@ -0,0 +1,36 @@ +<!doctype html> +<html class="no-js" lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Accessibility: Text cue for required form control labels</title> + <meta name="description" content="Text cue for required form control labels"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <style type="text/css"> + label.required span.required-indicator:after { + content: " *"; + } + .sr-only { + border: 0; + clip: rect(0 0 0 0); + height: 1px; + margin: -1px; + overflow: hidden; + padding: 0; + position: absolute; + width: 1px; + } + </style> +</head> +<body> + <form> + <label class="required"> + Enter some text + <span class="required-indicator" aria-hidden="true"></span> + <span class="sr-only"> (required)</span> + <input type="text" name="some_text" value="" aria-required="true" required> + </label> + <input type="submit" name="btn_submit" value="Submit"> + </form> +</body> +</html>
\ No newline at end of file diff --git a/doc/phpdoc.xml b/doc/phpdoc.xml new file mode 100644 index 0000000..0d9b207 --- /dev/null +++ b/doc/phpdoc.xml @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<phpdoc> + <title>Icinga Web 2</title> + <parser> + <target>./api</target> + <extensions> + <extension>php</extension> + </extensions> + </parser> + <visibility>public,private,protected</visibility> + <transformer> + <target>./api</target> + </transformer> + <logging> + <level>quiet</level> + </logging> + <transformations> + <template name="responsive" /> + </transformations> + <files> + <directory>../library/Icinga</directory> + <directory>../library/application</directory> + <directory>../modules/*/library</directory> + <directory>../modules/*/application</directory> + </files> +</phpdoc> diff --git a/doc/res/GraphExample#1.png b/doc/res/GraphExample#1.png Binary files differnew file mode 100644 index 0000000..fc3fe57 --- /dev/null +++ b/doc/res/GraphExample#1.png diff --git a/doc/res/GraphExample#2.png b/doc/res/GraphExample#2.png Binary files differnew file mode 100644 index 0000000..f81c4fb --- /dev/null +++ b/doc/res/GraphExample#2.png diff --git a/doc/res/GraphExample#3.png b/doc/res/GraphExample#3.png Binary files differnew file mode 100644 index 0000000..0aed97f --- /dev/null +++ b/doc/res/GraphExample#3.png diff --git a/doc/res/GraphExample#4.png b/doc/res/GraphExample#4.png Binary files differnew file mode 100644 index 0000000..1555ae3 --- /dev/null +++ b/doc/res/GraphExample#4.png diff --git a/doc/res/GraphExample#5.png b/doc/res/GraphExample#5.png Binary files differnew file mode 100644 index 0000000..ec659ae --- /dev/null +++ b/doc/res/GraphExample#5.png diff --git a/doc/res/GraphExample#6.png b/doc/res/GraphExample#6.png Binary files differnew file mode 100644 index 0000000..1bd44f6 --- /dev/null +++ b/doc/res/GraphExample#6.png diff --git a/doc/res/GraphExample#7.1.png b/doc/res/GraphExample#7.1.png Binary files differnew file mode 100644 index 0000000..8f67832 --- /dev/null +++ b/doc/res/GraphExample#7.1.png diff --git a/doc/res/GraphExample#7.png b/doc/res/GraphExample#7.png Binary files differnew file mode 100644 index 0000000..41b762e --- /dev/null +++ b/doc/res/GraphExample#7.png diff --git a/doc/res/GraphExample#8.png b/doc/res/GraphExample#8.png Binary files differnew file mode 100644 index 0000000..4c2928e --- /dev/null +++ b/doc/res/GraphExample#8.png diff --git a/doc/res/GraphExample#9.png b/doc/res/GraphExample#9.png Binary files differnew file mode 100644 index 0000000..18b1898 --- /dev/null +++ b/doc/res/GraphExample#9.png diff --git a/doc/res/gitlab-job-artifacts.png b/doc/res/gitlab-job-artifacts.png Binary files differnew file mode 100644 index 0000000..ba7af9a --- /dev/null +++ b/doc/res/gitlab-job-artifacts.png diff --git a/doc/res/gitlab-rpm-package-pipeline-jobs.png b/doc/res/gitlab-rpm-package-pipeline-jobs.png Binary files differnew file mode 100644 index 0000000..ed8d50a --- /dev/null +++ b/doc/res/gitlab-rpm-package-pipeline-jobs.png diff --git a/doc/res/monitoring-module-preview.png b/doc/res/monitoring-module-preview.png Binary files differnew file mode 100644 index 0000000..d07596b --- /dev/null +++ b/doc/res/monitoring-module-preview.png |
