diff options
Diffstat (limited to 'doc/02-Installation.md')
| -rw-r--r-- | doc/02-Installation.md | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 0000000..b4f50c5 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,319 @@ +<!-- {% if index %} --> +# Installing Icinga DB + +The recommended way to install Icinga DB is to use prebuilt packages for +all supported platforms from our official release repository. +Please follow the steps listed for your target operating system, +which guide you through setting up the repository and installing Icinga DB. + +To upgrade an existing Icinga DB installation to a newer version, +see the [Upgrading](04-Upgrading.md) documentation for the necessary steps. + + + +Before installing Icinga DB, make sure you have installed [Icinga 2](https://icinga.com/docs/icinga-2), +set up a Redis server, and enabled the `icingadb` feature. +The Icinga 2 installation documentation covers all the necessary steps. +Additionally, Icinga offers the `icingadb-redis` package for all supported operating systems, +which ships an up-to-date Redis server version and is pre-configured for the Icinga DB components. + +!!! tip + + Although Icinga DB can run anywhere in an Icinga environment, + we recommend to install it where the corresponding Icinga 2 node and Redis server is running to + keep latency between the components low. + +<!-- {% else %} --> +## Adding Icinga Package Repository + +The recommended way to install Icinga DB is to use prebuilt packages from our official release repository. + +!!! tip + + If you install Icinga DB on a node that has Icinga 2 or Icinga Web installed via packages, + proceed to [installing the Icinga DB package](#installing-icinga-db-web-package) as + the repository is already configured. + +Here's how to add the official release repository: + +<!-- {% if amazon_linux %} --> +<!-- {% if not icingaDocs %} --> +### Amazon Linux 2 Repository +<!-- {% endif %} --> +!!! info + + A paid repository subscription is required for Amazon Linux 2 repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription). + + Don't forget to fill in the username and password section with appropriate 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 +``` +<!-- {% endif %} --> + +<!-- {% if centos %} --> +<!-- {% if not icingaDocs %} --> +### CentOS Repository +<!-- {% endif %} --> +```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 +``` +<!-- {% endif %} --> + +<!-- {% if debian %} --> +<!-- {% if not icingaDocs %} --> +### Debian Repository +<!-- {% endif %} --> + +```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 rhel %} --> +<!-- {% if not icingaDocs %} --> +### RHEL Repository +<!-- {% endif %} --> +!!! 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 appropriate 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 +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +<!-- {% if not icingaDocs %} --> +### SLES Repository +<!-- {% endif %} --> +!!! info + + A paid repository subscription is required for SLES repositories. Get more information on + [icinga.com/subscription](https://icinga.com/subscription). + + Don't forget to fill in the username and password section with appropriate 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 +``` +<!-- {% endif %} --> + +<!-- {% if ubuntu %} --> +<!-- {% if not icingaDocs %} --> +### Ubuntu Repository +<!-- {% endif %} --> + +```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 %} --> + +## Installing Icinga DB Package + +Use your distribution's package manager to install the `icingadb` package as follows: + +<!-- {% if amazon_linux %} --> +<!-- {% if not icingaDocs %} --> +#### Amazon Linux 2 +<!-- {% endif %} --> +```bash +yum install icingadb +``` +<!-- {% endif %} --> + +<!-- {% if centos %} --> +<!-- {% if not icingaDocs %} --> +#### CentOS +<!-- {% endif %} --> +!!! info + + Note that installing Icinga DB is only supported on CentOS 7 as CentOS 8 is EOL. + +```bash +yum install icingadb +``` +<!-- {% endif %} --> + +<!-- {% if debian or ubuntu %} --> +<!-- {% if not icingaDocs %} --> +#### Debian / Ubuntu +<!-- {% endif %} --> +```bash +apt-get install icingadb +``` +<!-- {% endif %} --> + +<!-- {% if rhel %} --> +#### RHEL 8 or Later + +```bash +dnf install icingadb +``` + +#### RHEL 7 + +```bash +yum install icingadb +``` +<!-- {% endif %} --> + +<!-- {% if sles %} --> +<!-- {% if not icingaDocs %} --> +#### SLES +<!-- {% endif %} --> +```bash +zypper install icingadb +``` +<!-- {% endif %} --> + +## Setting up the Database + +A MySQL (≥5.5), MariaDB (≥10.1), or PostgreSQL (≥9.6) database is required to run Icinga DB. +Please follow the steps listed for your target database, +which guide you through setting up the database and user and importing the schema. + + + +!!! info + + In high availability setups, all Icinga DB instances must write to the same database. + +### Setting up a MySQL or MariaDB Database + +If you use a version of MySQL < 5.7 or MariaDB < 10.2, the following server options must be set: + +``` +innodb_file_format=barracuda +innodb_file_per_table=1 +innodb_large_prefix=1 +``` + +Set up a MySQL database for Icinga DB: + +``` +# mysql -u root -p + +CREATE DATABASE icingadb; +CREATE USER 'icingadb'@'localhost' IDENTIFIED BY 'CHANGEME'; +GRANT ALL ON icingadb.* TO 'icingadb'@'localhost'; +``` + +After creating the database, import the Icinga DB schema using the following command: + +``` +mysql -u root -p icingadb </usr/share/icingadb/schema/mysql/schema.sql +``` + +### Setting up a PostgreSQL Database + +Set up a PostgreSQL database for Icinga DB: + +``` +# su -l postgres + +createuser -P icingadb +createdb -E UTF8 --locale en_US.UTF-8 -T template0 -O icingadb icingadb +psql icingadb <<<'CREATE EXTENSION IF NOT EXISTS citext;' +``` + +The `CREATE EXTENSION` command requires the `postgresql-contrib` package. + +Edit `pg_hba.conf`, insert the following before everything else: + +``` +local all icingadb md5 +host all icingadb 0.0.0.0/0 md5 +host all icingadb ::/0 md5 +``` + +To apply these changes, run `systemctl reload postgresql`. + +After creating the database, import the Icinga DB schema using the following command: + +``` +psql -U icingadb icingadb < /usr/share/icingadb/schema/pgsql/schema.sql +``` + +## Configuring Icinga DB + +Icinga DB installs its configuration file to `/etc/icingadb/config.yml`, +pre-populating most of the settings for a local setup. Before running Icinga DB, +adjust the Redis and database credentials and, if necessary, the connection configuration. +The configuration file explains general settings. +All available settings can be found under [Configuration](03-Configuration.md). + +## Running Icinga DB + +The `icingadb` package automatically installs the necessary systemd unit files to run Icinga DB. +Please run the following command to enable and start its service: + +```bash +systemctl enable --now icingadb +``` + +## Installing Icinga DB Web + +With Icinga 2, Redis, Icinga DB and the database fully set up, it is now time to install Icinga DB Web, +which connects to both Redis and the database to display and work with the monitoring data. + + + +The Icinga DB Web package is also included in the Icinga repository, and since it is already set up, +you have completed the instructions here and can proceed to +<!-- {% if amazon_linux %} --> +[installing Icinga DB Web on Amazon Linux](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/01-Amazon-Linux/#installing-icinga-db-web-package), +<!-- {% endif %} --> +<!-- {% if centos %} --> +[installing Icinga DB Web on CentOS](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/02-CentOS/#installing-icinga-db-web-package), +<!-- {% endif %} --> +<!-- {% if debian %} --> +[installing Icinga DB Web on Debian](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/03-Debian/#installing-icinga-db-web-package), +<!-- {% endif %} --> +<!-- {% if rhel %} --> +[installing Icinga DB Web on RHEL](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/04-RHEL/#installing-icinga-db-web-package), +<!-- {% endif %} --> +<!-- {% if sles %} --> +[installing Icinga DB Web on SLES](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/05-SLES/#installing-icinga-db-web-package), +<!-- {% endif %} --> +<!-- {% if ubuntu %} --> +[installing Icinga DB Web on Ubuntu](https://icinga.com/docs/icinga-db-web/latest/doc/02-Installation/06-Ubuntu/#installing-icinga-db-web-package), +<!-- {% endif %} --> +which will also guide you through the setup of the Icinga Web PHP framework, +which is required to run the Icinga DB web module. +Below is a preview of how the interface visualizes monitoring data and also supports dark and light mode: + + +<!-- {% endif %} --><!-- {# end else if index #} --> |