diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 14bbeca61..561e48295 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,12 +1,15 @@ # Installation The preferred way of installing Icinga Web 2 is to use the official package repositories depending on which operating -system and distribution you are running. But it is also possible to install Icinga Web 2 directly from source. +system and distribution you are running. In case you are upgrading from an older version of Icinga Web 2 -please make sure to read the [upgrading](02-Installation.md#upgrading) section +please make sure to read the [upgrading](80-Upgrading.md#upgrading) section thoroughly. +Source and automated setups are described inside the [advanced topics](20-Advanced-Topics.md#advanced-topics) +chapter. + ## Installing Requirements * A web server, e.g. Apache or nginx @@ -14,12 +17,11 @@ thoroughly. * Default time zone configured for PHP in the php.ini file * LDAP PHP library when using Active Directory or LDAP for authentication * Icinga 2.x w/ IDO feature enabled or Icinga 1.x w/ IDO -* The IDO table prefix must be icinga_ which is the default +* The IDO table prefix must be `icinga_` which is the default * MySQL or PostgreSQL PHP libraries * cURL PHP library when using the Icinga 2 API for transmitting external commands - ## Installing Icinga Web 2 from Package Below is a list of official package repositories for installing Icinga Web 2 for various operating systems. @@ -103,6 +105,7 @@ apk update > Latest version of Icinga Web 2 is in the edge repository, which is the -dev branch. #### RHEL/CentOS Notes + The packages for RHEL/CentOS depend on other packages which are distributed as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). @@ -114,8 +117,6 @@ yum install epel-release If you are using RHEL you need enable the `optional` repository and then install the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). -> Please note that installing Icinga Web 2 on **RHEL/CentOS 5** is not supported due to EOL versions of PHP and PostgreSQL. - #### Alpine Linux Notes @@ -138,7 +139,7 @@ apt-get install icingaweb2 ``` yum install icingaweb2 icingacli ``` -For RHEL/CentOS please read the [package repositories notes](#package-repositories-rhel-notes). +For RHEL/CentOS please read the [package repositories notes](02-Installation.md#package-repositories-rhel-notes). **SLES and openSUSE**: ``` @@ -149,7 +150,7 @@ zypper install icingaweb2 icingacli ``` apk add icingaweb2 ``` -For Alpine Linux please read the [package repositories notes](#package-repositories-alpine-notes). +For Alpine Linux please read the [package repositories notes](02-Installation.md#package-repositories-alpine-notes). ### Preparing Web Setup @@ -165,459 +166,27 @@ In case you do not remember the token you can show it using the `icingacli`: icingacli setup token show ``` -Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: -`/icingaweb2/setup`. +#### Preparing Web Setup on Debian -## Installing Icinga Web 2 from Source - -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 - -First of all, you need to download the sources. Icinga Web 2 is available through a Git repository. You can clone this -repository either via git or http protocol using the following URLs: - - * git://git.icinga.com/icingaweb2.git - * http://git.icinga.com/icingaweb2.git - -There is also a browsable version available at -[git.icinga.com](https://git.icinga.com/?p=icingaweb2.git;a=summary "Icinga Web 2 Git Repository"). -This version also offers snapshots for easy download which you can use if you do not have git present on your system. +On Debian, 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. ``` -git clone git://git.icinga.com/icingaweb2.git +MariaDB [mysql]> CREATE DATABASE icingaweb2; + +MariaDB [mysql]> GRANT ALL ON icingaweb2.* TO icingaweb2@localhost IDENTIFIED BY 'CHANGEME'; ``` -### Installing Requirements from Source +You may also create a separate administrative account with all privileges instead. -You will need to install certain dependencies depending on your setup listed [here](02-Installation.md#installing-requirements). +> Note: This is only required if you are using a local database as authentication type. -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: - -``` -yum install httpd mysql-server -yum install php php-gd php-intl php-ZendFramework php-ZendFramework-Db-Adapter-Pdo-Mysql -``` - -The setup wizard will check the pre-requisites later on. - - -### Installing Icinga Web 2 - -Choose a target directory and move Icinga Web 2 there. - -``` -mv icingaweb2 /usr/share/icingaweb2 -``` - -### Configuring the Web Server - -Use `icingacli` to generate web server configuration for either Apache or nginx. - -**Apache**: -``` -./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public -``` - -**nginx**: -``` -./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: -``` -./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/httpd/conf.d/icingaweb2.conf -``` - -Example for Apache on SUSE: -``` -./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf -``` - -Example for Apache on Debian Jessie: -``` -./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: -``` -icingacli setup config webserver apache --document-root /usr/share/webapps/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf -``` -### Preparing Icinga Web 2 Setup - -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**: -``` -groupadd -r icingaweb2 -``` - -**Debian and Ubuntu**: -``` -addgroup --system icingaweb2 -``` - -Add your web server's user to the system group `icingaweb2` -and restart the web server: - -**Fedora, RHEL and CentOS**: -``` -usermod -a -G icingaweb2 apache -service httpd restart -``` - -**SLES and OpenSUSE**: -``` -usermod -A icingaweb2 wwwrun -service apache2 restart -``` - -**Debian and Ubuntu**: -``` -usermod -a -G icingaweb2 www-data -service apache2 restart -``` - -**Alpine Linux**: -``` -gpasswd -a apache icingaweb2 -rc-service apache2 restart -``` - - -Use `icingacli` to create the configuration directory which defaults to **/etc/icingaweb2**: -``` -./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`: -``` -./bin/icingacli setup token create -``` - -In case you do not remember the token you can show it using the `icingacli`: -``` -./bin/icingacli setup token show -``` - -### Icinga Web 2 Setup Wizard +### Starting Web Setup 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. +Note for Debian: Use the same database, user and password details created above when asked. -### Icinga Web 2 Manual Setup - -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](02-Installation.md#web-setup-wizard-from-source) once -> and then collect the generated configuration as well as sql dumps. - -#### Icinga Web 2 Manual Database Setup - -Create the database and add a new user as shown below for MySQL/MariaDB: - -``` -sudo mysql -p - -CREATE DATABASE icingaweb2; -GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icingaweb2.* TO 'icingaweb2'@'localhost' IDENTIFIED BY 'icingaweb2'; -quit - -mysql -p icingaweb2 < /usr/share/doc/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 - - -[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 - - -**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 - -Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`. - -## Troubleshooting - -### PageSpeed Module Incompatibility - -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/*"; -``` - - -## Automating the Installation of Icinga Web 2 - -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. Set a timezone in `php.ini` configuration file. -3. Create a database for Icinga Web 2, i.e. `icingaweb2`. -4. Import the database schema: `mysql -D icingaweb2 < /usr/share/icingaweb2/etc/schema/mysql.schema.sql`. -5. Insert administrator user in the `icingaweb2` database: -`INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('admin', 1, '')`, where `` is the output -of `openssl passwd -1 `. -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 apacahe 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 webserver`. 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](#web-setup-manual-from-source-config) for the contents of the files. - -## Upgrading Icinga Web 2 - -### Upgrading to Icinga Web 2 2.4.x - -* Icinga Web 2 version 2.4.x does not introduce any backward incompatible change. - -### Upgrading to Icinga Web 2 2.3.x - -* Icinga Web 2 version 2.3.x does not introduce any backward incompatible change. - -### Upgrading to Icinga Web 2 2.2.0 - -* 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 - -* 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 - -* Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through - the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library - 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/`. 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 - -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 - -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 - -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`. diff --git a/doc/06-Security.md b/doc/06-Security.md index 56b2c3914..726a45735 100644 --- a/doc/06-Security.md +++ b/doc/06-Security.md @@ -26,7 +26,7 @@ All actions must be be **allowed explicitly** using permissions. A permission is a simple list of identifiers of actions a user is allowed to do. Permissions are described in greater detail in the -section [Permissions](#permissions). +section [Permissions](06-Security.md#permissions). ### Objects @@ -35,7 +35,7 @@ There are all kinds of different objects in Icinga Web 2: Hosts, Services, Notif By default, a user can **see everything**, but it is possible to **explicitly restrict** what each user can see using restrictions. Restrictions are complex filter queries that describe what objects should be displayed to a user. Restrictions are described -in greater detail in the section [Restrictions](#restrictions). +in greater detail in the section [Restrictions](06-Security.md#restrictions). ### Users @@ -89,7 +89,7 @@ that match a specific query. The actual permission of a certain user will be determined by merging the permissions and restrictions of the user itself and all the groups the user is member of. Permissions can be simply added up, while restrictions follow a slighty more complex pattern, that is described -in the section [Stacking Filters](#stacking-filters). +in the section [Stacking Filters](06-Security.md#stacking-filters). ### Configuration @@ -180,7 +180,7 @@ data the filter is applied to. The **filter directive** is a simple identifier, defined in an Icinga Web 2 module. The only filter directive that is available in a default installation, is the `monitoring/filter/objects` directive, defined by the monitoring module, that can be used to apply filter to hosts and services. This directive was previously -mentioned in the section [Syntax](#syntax). +mentioned in the section [Syntax](06-Security.md#syntax). ### Filter Expressions diff --git a/doc/20-Advanced-Topics.md b/doc/20-Advanced-Topics.md new file mode 100644 index 000000000..08e8fe452 --- /dev/null +++ b/doc/20-Advanced-Topics.md @@ -0,0 +1,360 @@ +# Advanced Topics + +This chapter contains advanced Icinga Web 2 topics such as source installation +or automation hints. + +## Installing Icinga Web 2 from Source + +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 + +First of all, you need to download the sources. + +Git clone: + +``` +cd /usr/share/ +git clone https://github.com/Icinga/icingaweb2.git icingaweb2 +``` + +Tarball download (latest [release](https://github.com/Icinga/icingaweb2/releases/latest)): + +``` +cd /usr/share +wget https://github.com/Icinga/icingaweb2/archive/v2.4.1.zip +unzip v2.4.1.zip +mv icingaweb2-2.4.1 icingaweb2 +``` + +### Installing Requirements from Source + +You will need to install certain dependencies depending on your setup listed [here](02-Installation.md#installing-requirements). + +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: + +``` +yum install httpd mysql-server +yum install php php-gd php-intl php-ZendFramework php-ZendFramework-Db-Adapter-Pdo-Mysql +``` + +The setup wizard will check the pre-requisites later on. + + +### Installing Icinga Web 2 + +Choose a target directory and move Icinga Web 2 there. + +``` +mv icingaweb2 /usr/share/icingaweb2 +``` + +### Configuring the Web Server + +Use `icingacli` to generate web server configuration for either Apache or nginx. + +**Apache**: +``` +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public +``` + +**nginx**: +``` +./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: +``` +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/httpd/conf.d/icingaweb2.conf +``` + +Example for Apache on SUSE: +``` +./bin/icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf +``` + +Example for Apache on Debian Jessie: +``` +./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: +``` +icingacli setup config webserver apache --document-root /usr/share/webapps/icingaweb2/public > /etc/apache2/conf.d/icingaweb2.conf +``` +### Preparing Icinga Web 2 Setup + +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**: +``` +groupadd -r icingaweb2 +``` + +**Debian and Ubuntu**: +``` +addgroup --system icingaweb2 +``` + +Add your web server's user to the system group `icingaweb2` +and restart the web server: + +**Fedora, RHEL and CentOS**: +``` +usermod -a -G icingaweb2 apache +service httpd restart +``` + +**SLES and OpenSUSE**: +``` +usermod -A icingaweb2 wwwrun +service apache2 restart +``` + +**Debian and Ubuntu**: +``` +usermod -a -G icingaweb2 www-data +service apache2 restart +``` + +**Alpine Linux**: +``` +gpasswd -a apache icingaweb2 +rc-service apache2 restart +``` + + +Use `icingacli` to create the configuration directory which defaults to **/etc/icingaweb2**: +``` +./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`: +``` +./bin/icingacli setup token create +``` + +In case you do not remember the token you can show it using the `icingacli`: +``` +./bin/icingacli setup token show +``` + +### Icinga Web 2 Setup Wizard + +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. + + +### Icinga Web 2 Manual Setup + +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](02-Installation.md#web-setup-wizard-from-source) once +> and then collect the generated configuration as well as sql dumps. + +#### Icinga Web 2 Manual Database Setup + +Create the database and add a new user as shown below for MySQL/MariaDB: + +``` +sudo mysql -p + +CREATE DATABASE icingaweb2; +GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icingaweb2.* TO 'icingaweb2'@'localhost' IDENTIFIED BY 'icingaweb2'; +quit + +mysql -p icingaweb2 < /usr/share/doc/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 + + +[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 + + +**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 + +Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`. + +## Automating the Installation of Icinga Web 2 + +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. Set a timezone in `php.ini` configuration file. +3. Create a database for Icinga Web 2, i.e. `icingaweb2`. +4. Import the database schema: `mysql -D icingaweb2 < /usr/share/icingaweb2/etc/schema/mysql.schema.sql`. +5. Insert administrator user in the `icingaweb2` database: +`INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('admin', 1, '')`, where `` is the output +of `openssl passwd -1 `. +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 apacahe 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 webserver`. 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. + diff --git a/doc/70-Troubleshooting.md b/doc/70-Troubleshooting.md new file mode 100644 index 000000000..d71e08a71 --- /dev/null +++ b/doc/70-Troubleshooting.md @@ -0,0 +1,17 @@ +# Troubleshooting + +## PageSpeed Module Incompatibility + +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 000000000..4838f6743 --- /dev/null +++ b/doc/80-Upgrading.md @@ -0,0 +1,84 @@ +# Upgrading Icinga Web 2 + +## Upgrading to Icinga Web 2 2.4.x + +* Icinga Web 2 version 2.4.x does not introduce any backward incompatible change. + +## Upgrading to Icinga Web 2 2.3.x + +* Icinga Web 2 version 2.3.x does not introduce any backward incompatible change. + +## Upgrading to Icinga Web 2 2.2.0 + +* 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 + +* 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 + +* Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through + the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library + 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/`. 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 + +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 + +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 + +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`. diff --git a/modules/setup/library/Setup/Utils/DbTool.php b/modules/setup/library/Setup/Utils/DbTool.php index e89033a0b..a50d3aa79 100644 --- a/modules/setup/library/Setup/Utils/DbTool.php +++ b/modules/setup/library/Setup/Utils/DbTool.php @@ -378,7 +378,12 @@ class DbTool } catch (PDOException $e) { if ($this->config['db'] === 'mysql') { $code = $e->getCode(); - if ($code !== 1040 && $code !== 1045) { + /* + * 1040 .. Too many connections + * 1045 .. Access denied for user '%s'@'%s' (using password: %s) + * 1698 .. Access denied for user '%s'@'%s' + */ + if ($code !== 1040 && $code !== 1045 && $code !== 1698) { throw $e; } } elseif ($this->config['db'] === 'pgsql') {