From 52d51f0ee532c33f2a1ab3136d5cfd5fd20d5f4c Mon Sep 17 00:00:00 2001 From: Blerim Sheqa Date: Wed, 16 Feb 2022 09:10:54 +0100 Subject: [PATCH] Update installation instructions for easier navigation on icinga.com --- doc/02-Installation.md | 654 +++++++++++--------- doc/02-Installation.md.d/01-Debian.md | 3 + doc/02-Installation.md.d/02-Ubuntu.md | 3 + doc/02-Installation.md.d/03-CentOS.md | 3 + doc/02-Installation.md.d/04-RHEL.md | 3 + doc/02-Installation.md.d/05-SLES.md | 3 + doc/02-Installation.md.d/06-Amazon-Linux.md | 3 + doc/02-Installation.md.d/07-From-Source.md | 3 + doc/20-Advanced-Topics.md | 179 +----- 9 files changed, 395 insertions(+), 459 deletions(-) create mode 100644 doc/02-Installation.md.d/01-Debian.md create mode 100644 doc/02-Installation.md.d/02-Ubuntu.md create mode 100644 doc/02-Installation.md.d/03-CentOS.md create mode 100644 doc/02-Installation.md.d/04-RHEL.md create mode 100644 doc/02-Installation.md.d/05-SLES.md create mode 100644 doc/02-Installation.md.d/06-Amazon-Linux.md create mode 100644 doc/02-Installation.md.d/07-From-Source.md diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 2882dc9cc..d24de9c90 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -1,29 +1,14 @@ + # 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. -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. +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. -Source and automated setups are described inside the [advanced topics](20-Advanced-Topics.md#advanced-topics) -chapter. - -## Installing Requirements - -* [Icinga 2](https://icinga.com/products/icinga-2/) with the IDO database backend (MySQL or PostgreSQL) -* A web server, e.g. Apache or Nginx -* PHP version >= 7.3 - * Older versions (5.6+) are only supported up until version 2.11 -* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.6) -* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10) -* The following PHP modules must be installed: cURL, json, gettext, fileinfo, intl, dom, OpenSSL and xml -* For exports to PDF also the following PHP modules are required: mbstring, GD, Imagick -* LDAP PHP library when using Active Directory or LDAP for authentication -* MySQL or PostgreSQL PHP libraries - -### Browser Support +## 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. @@ -38,43 +23,37 @@ or sub-category here: 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. -> **Note for Internet Explorer users** -> -> Support for Internet Explorer will be completely dropped with version 2.11 +!!! note -## Installing Icinga Web 2 from Package + Support for Internet Explorer will be completely dropped with version 2.11 -Official repositories ([support matrix](https://icinga.com/subscription/support-details/)): +## Upgrade -| Distribution | Repository | -| ------------- | ---------- | -| Debian | [Icinga Repository](https://packages.icinga.com/debian/) | -| Ubuntu | [Icinga Repository](https://packages.icinga.com/ubuntu/) | -| RHEL/CentOS | [Icinga Repository](https://packages.icinga.com/epel/) | -| openSUSE | [Icinga Repository](https://packages.icinga.com/openSUSE/) | -| SLES | [Icinga Repository](https://packages.icinga.com/SUSE/) | +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. + +## Installation Requirements -Community repositories: +* [Icinga 2](https://icinga.com/products/icinga-2/) with the IDO database backend (MySQL or PostgreSQL) +* A web server, e.g. Apache or Nginx +* PHP version >= 7.3 + * Older versions (5.6+) are only supported up until Icinga Web v2.11 -| Distribution | Repository | -| ------------- | ---------- | -| Gentoo | [Upstream](https://packages.gentoo.org/packages/www-apps/icingaweb2) | -| FreeBSD | [Upstream](http://portsmon.freebsd.org/portoverview.py?category=net-mgmt&portname=icingaweb2) | -| ArchLinux | [Upstream](https://aur.archlinux.org/packages/icingaweb2) | -| Alpine Linux | [Upstream](https://git.alpinelinux.org/cgit/aports/tree/community/icingaweb2/APKBUILD) | +### Optional Requirements +* For exports to PDF also the following PHP modules are required: mbstring, GD, Imagick +* LDAP PHP library when using Active Directory or LDAP for authentication -Packages for distributions other than the ones listed above may also be available. -Please contact your distribution packagers. - -### Setting up Package Repositories +## Add Icinga Package Repository 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. -**Debian**: + +### Debian Repository -``` +```bash apt-get update apt-get -y install apt-transport-https wget gnupg @@ -88,10 +67,12 @@ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ apt-get update ``` + -**Ubuntu**: + +### Ubuntu Repository -``` +```bash apt-get update apt-get -y install apt-transport-https wget gnupg @@ -105,76 +86,55 @@ wget -O - https://packages.icinga.com/icinga.key | apt-key add - apt-get update ``` + -**RHEL and CentOS 8**: -``` -dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm + +### CentOS Repository + +```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 ``` -**RHEL and CentOS 7**: -``` -yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm -``` - -**Fedora 31**: -``` -dnf install https://packages.icinga.com/fedora/icinga-rpm-release-31-latest.noarch.rpm -``` - -**SLES 15/12**: -``` -zypper ar http://packages.icinga.com/SUSE/ICINGA-release.repo -zypper ref -``` - -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`. - -**openSUSE**: -``` -zypper ar http://packages.icinga.com/openSUSE/ICINGA-release.repo -zypper ref -``` - -**Alpine Linux**: -``` -echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repos -apk update -``` -> INFO -> -> 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 +The packages for CentOS depend on other packages which are distributed as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). -CentOS 8 additionally needs the PowerTools repository for EPEL: -*Be aware that the name of the `powertools` repo [changed to lowercase](https://wiki.centos.org/Manuals/ReleaseNotes/CentOS8.2011#Yum_repo_file_and_repoid_changes) with CentOS 8.3.2011 and newer.* -*If you are using CentOS 8.2.2044 or earlier please change the name to `PowerTools` in the following command.* -``` -dnf install 'dnf-command(config-manager)' -dnf config-manager --set-enabled powertools - -dnf install epel-release -``` - 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 +``` + + + +### RHEL Repository + +!!! 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: +#### RHEL 8 -``` +```bash ARCH=$( /bin/arch ) subscription-manager repos --enable rhel-8-server-optional-rpms @@ -183,188 +143,175 @@ 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: - -``` -subscription-manager repos --enable rhel-7-server-optional-rpms -yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm -``` - -##### RHEL/CentOS 7 PHP SCL - -Since version 2.5.0 we also require a **newer PHP version** than what is available +#### 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. -CentOS: -``` -yum install centos-release-scl -``` - -RedHat: -``` +```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 +``` + + + +### SLES Repository + +!!! 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 ``` -Make sure to also read the chapter on [Setting up FPM](02-Installation.md#setting-up-fpm). +You need to additionally enable a couple of SLES repositories to fulfill dependencies: -#### Alpine Linux Notes +```bash +source /etc/os-release -The example provided suppose that you are running Alpine edge, which is the -dev branch and is a rolling release. -If you are using a stable version, in order to use the latest Icinga Web 2 version you should "pin" the edge repository. -In order to correctly manage your repository, please follow -[these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management). +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 +``` + -### Installing Icinga Web 2 + +### Amazon Linux 2 Repository + +!!! 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 +``` + + +## Install Icinga Web 2 You can install Icinga Web 2 by using your distribution's package manager to install the `icingaweb2` package. -Below is a list with examples for various distributions. The additional package `icingacli` is necessary to follow further steps in this guide. -The additional package `libapache2-mod-php` is necessary on Ubuntu to make -Icinga Web 2 working out-of-the-box if you aren't sure or don't care about [PHP -FPM](02-Installation.md#setting-up-fpm). +The additional package `icingacli` is necessary to follow further steps in this guide. -**Debian**: -``` + + +#### Debian + +```bash apt-get install icingaweb2 icingacli ``` + -**Ubuntu**: -``` + + +#### Ubuntu + +```bash apt-get install icingaweb2 libapache2-mod-php icingacli ``` -**RHEL/CentOS 8 and Fedora**: +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. + + + +!!! tip + + If you have [SELinux](90-SELinux.md) enabled, the package `icingaweb2-selinux` is also required. + + + + +#### CentOS + ``` dnf install icingaweb2 icingacli ``` + -**RHEL/CentOS 7** + + +#### RHEL + +#### RHEL 8 +```bash +dnf install icingaweb2 icingacli ``` + +#### RHEL 7 +```bash yum install icingaweb2 icingacli ``` + -If you have [SELinux](90-SELinux.md) enabled, the package `icingaweb2-selinux` is also required. -For RHEL/CentOS please read the [package repositories notes](02-Installation.md#package-repositories-rhel-notes). - -**SLES and openSUSE**: -``` + + +#### SLES + +```bash zypper install icingaweb2 icingacli ``` + -**Alpine Linux**: + + +#### Amazon Linux 2 + +```bash +yum install icingaweb2 icingacli ``` -apk add icingaweb2 -``` -For Alpine Linux please read the [package repositories notes](02-Installation.md#package-repositories-alpine-notes). + -## Installing the web server +## Install the Web Server -Depending on your OS you might have to install, and or configure the web server. -We usually only require PHP as hard dependency. +Make sure you have a web server with PHP up and running before moving on. +Please refer to the [installation requirements](#installation-requirements) for details about supported versions. +Depending on your OS you might have to install, and configure the web server separately. -We usually build on Apache httpd as the default web server, but you also can use nginx. - -**RedHat / CentOS / Fedora** - -Make sure to install httpd, start and enable it on boot. -``` -yum install httpd - -systemctl start httpd.service -systemctl enable httpd.service -``` - -Note for **EPEL 7 and 8**: Check the [Setting up FPM](02-Installation.md#setting-up-fpm) chapter. - -**SUSE SLE / openSUSE** - -Make sure that web server is installed, and the required modules are loaded. -``` -zypper install apache2 - -a2enmod rewrite -a2enmod php7 - -systemctl start apache2.service -systemctl enable apache2.service -``` - -**Debian / Ubuntu** - -Your web server should be up and running after the installation of Icinga Web 2. - -### Setting up FPM - -If you are on CentOS / RedHat, or just want to run Icinga Web 2 with PHP-FPM instead -of the Apache module. - -| Operating System | FPM configuration path | -|---------------------|-----------------------------------| -| RedHat 8 | `/etc/php-fpm.d/` | -| RedHat 7 (with SCL) | `/etc/opt/rh/rh-php71/php-fpm.d/` | -| Fedora | `/etc/php-fpm.d/` | -| Debian/Ubuntu | `/etc/php*/*/fpm/pool.d/` | - -The default pool `www` should be sufficient for Icinga Web 2. - -On RedHat you need to start and enable the FPM service. - -RedHat / CentOS 8 and Fedora: - -``` -systemctl start php-fpm.service -systemctl enable php-fpm.service -``` - -RedHat / CentOS 7 (SCL package): -``` -systemctl start rh-php71-php-fpm.service -systemctl enable rh-php71-php-fpm.service -``` - -All module packages for PHP have this SCL prefix, so you can install a -database module like this: -``` -yum install rh-php71-php-mysqlnd -# or -yum install rh-php71-php-pgsql -``` - -Depending on your web server installation, we might have installed or -updated the config file for icingaweb2 with defaults for FPM. - -Check `/etc/httpd/conf.d/icingaweb2.conf` or `/etc/apache2/conf.d/icingaweb2.conf`. -And `*.rpm*` `*.dpkg*` files there with updates. - -Make sure that the `FilesMatch` part is included for Apache >= 2.4. For Apache < 2.4 you have to include the -`LocationMatch` block. - -Also see the example from icingacli: -``` -icingacli setup config webserver apache -``` - -### Preparing Web Setup +## Prepare Web 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. 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 ``` -#### Preparing Web Setup on Debian/Ubuntu - -On Debian and derivates, you need to manually create a database and a database user prior to starting the web wizard. + +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'; @@ -372,84 +319,213 @@ MariaDB [mysql]> GRANT ALL ON icingaweb2.* TO icingaweb2@localhost IDENTIFIED BY 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. +!!! note -### Starting Web Setup + This is only required if you are using a local database as authentication type. + + +### Start Web Setup Finally visit Icinga Web 2 in your browser to access the setup wizard and complete the installation: `/icingaweb2/setup`. -> **Note for Debian/Ubuntu** -> -> Use the same database, user and password details created above when asked. + +!!! hint + + Use the same database, user and password details created above when asked. + The setup wizard automatically detects the required packages. In case one of them is missing, e.g. a PHP module, please install the package, restart your webserver and reload the setup page. -If you have SELinux enabled, please ensure to either have the selinux package for Icinga Web 2 -installed, or disable it. + +!!! 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`. + -### Upgrading to FPM + +!!! note -Valid for: + If you have SELinux enabled, please ensure to either have the selinux package for Icinga Web 2 installed, or disable it. + -* RedHat / CentOS 7 + + +## Installing Icinga Web 2 from Source + -Other distributions are also possible if preferred, but not included here. +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. -Some upgrading work needs to be done manually, while we install PHP FPM -as dependency, you need to start the service, and configure some things. +### Getting the Source -Please read [Setting up FPM](02-Installation.md#setting-up-fpm) first. +First of all, you need to download the sources. -**php.ini settings** you have tuned in the past needs to be migrated to a SCL installation -of PHP. +Git clone: -Check these directories: - -* `/etc/php.ini` -* `/etc/php.d/*.ini` - -PHP settings should be stored to: - -* RedHat / CentOS 7: `/etc/opt/rh/rh-php71/php.d/` - -Make sure to **install the required database modules** - -RedHat / CentOS 7: -``` -yum install rh-php71-php-mysqlnd -# or -yum install rh-php71-php-pgsql +```bash +cd /usr/share/ +git clone https://github.com/Icinga/icingaweb2.git icingaweb2 ``` -After any PHP related change you now need to **restart FPM**: +Tarball download (latest [release](https://github.com/Icinga/icingaweb2/releases/latest)): -RedHat / CentOS 7: -``` -systemctl restart rh-php71-php-fpm.service +```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 ``` -If you don't need mod_php for other apps on the server, you should disable it in Apache. +### Installing Requirements from Source -Disable PHP in Apache httpd: -``` -cd /etc/httpd -cp conf.d/php.conf{,.bak} -: >conf.d/php.conf +You will need to install certain dependencies depending on your setup: -# ONLY on el7! -cp conf.modules.d/10-php.conf{,.bak} -: >conf.modules.d/10-php.conf +* [Icinga 2](https://icinga.com/products/icinga-2/) with the IDO database backend (MySQL or PostgreSQL) +* A web server, e.g. Apache or Nginx +* PHP version >= 7.3 + * Older versions (5.6+) are only supported up until version 2.11 +* [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.6) +* [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10) +* The following PHP modules must be installed: cURL, json, gettext, fileinfo, intl, dom, OpenSSL and xml +* For exports to PDF also the following PHP modules are required: mbstring, GD, Imagick +* LDAP PHP library when using Active Directory or LDAP for authentication +* MySQL or PostgreSQL PHP libraries -systemctl restart httpd.service +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 ``` -You can also uninstall the mod_php package, or all non-SCL PHP related packages. -``` -yum remove php -# or -yum remove php-common +The setup wizard will check the pre-requisites later on. + + +### Installing Icinga Web 2 + +Choose a target directory and move Icinga Web 2 there. + +```bash +mv icingaweb2 /usr/share/icingaweb2 ``` +### Configuring the Web Server + +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 + +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 + +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) + 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 000000000..9ff5665ab --- /dev/null +++ b/doc/02-Installation.md.d/01-Debian.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Debian + + 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 000000000..74b7075dd --- /dev/null +++ b/doc/02-Installation.md.d/02-Ubuntu.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Ubuntu + + 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 000000000..0be7b1c73 --- /dev/null +++ b/doc/02-Installation.md.d/03-CentOS.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on CentOS + + 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 000000000..cab51946e --- /dev/null +++ b/doc/02-Installation.md.d/04-RHEL.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on RHEL + + 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 000000000..f17ab344f --- /dev/null +++ b/doc/02-Installation.md.d/05-SLES.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on SLES + + 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 000000000..d9cb7f282 --- /dev/null +++ b/doc/02-Installation.md.d/06-Amazon-Linux.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 on Amazon Linux + + 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 000000000..540335fb8 --- /dev/null +++ b/doc/02-Installation.md.d/07-From-Source.md @@ -0,0 +1,3 @@ +# Install Icinga Web 2 from Source + + diff --git a/doc/20-Advanced-Topics.md b/doc/20-Advanced-Topics.md index 150811c61..2329a623c 100644 --- a/doc/20-Advanced-Topics.md +++ b/doc/20-Advanced-Topics.md @@ -151,168 +151,7 @@ Example from [puppet-icingaweb2](https://github.com/Icinga/puppet-icingaweb2): ``` - - -## 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 +## Icinga Web 2 Manual Setup If you have chosen not to run the setup wizard, you will need further knowledge about @@ -329,10 +168,11 @@ Puppet, Ansible, Chef, etc. > 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. +> 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 +### Icinga Web 2 Manual Database Setup Create the database and add a new user as shown below for MySQL/MariaDB: @@ -357,7 +197,7 @@ INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', quit ``` -#### Icinga Web 2 Manual Configuration +### Icinga Web 2 Manual Configuration [resources.ini](04-Resources.md#resources) providing the details for the Icinga Web 2 and @@ -423,7 +263,7 @@ users = "icingaadmin" permissions = "*" ``` -#### Icinga Web 2 Manual Configuration Monitoring Module +### Icinga Web 2 Manual Configuration Monitoring Module **config.ini** defining additional security settings. @@ -458,11 +298,10 @@ username = "api" password = "api" ``` -#### Icinga Web 2 Manual Setup Login +### 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 Prior to creating your own script, please look into the official resources @@ -483,7 +322,7 @@ by Icinga Web 2. 4. Insert administrator user in the `icingaweb2` database: `INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('admin', 1, '')`, where `` 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 +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,