1# Installation <a id="installation"></a> 2 3This tutorial is a step-by-step introduction to installing [Icinga 2](02-installation.md#setting-up-icinga2) 4and [Icinga Web 2](02-installation.md#setting-up-icingaweb2). 5It assumes that you are familiar with the operating system you're using to install Icinga 2. 6 7In case you are upgrading an existing setup, please ensure to 8follow the [upgrade documentation](16-upgrading-icinga-2.md#upgrading-icinga-2). 9 10## Setting up Icinga 2 <a id="setting-up-icinga2"></a> 11 12First off you have to install Icinga 2. The preferred way of doing this 13is to use the official package repositories depending on which operating system 14and distribution you are running. 15 16Official repositories ([support matrix](https://icinga.com/subscription/support-details/)): 17 18 Distribution | Repository 19 ------------------------|--------------------------- 20 Debian | [Icinga Repository](https://packages.icinga.com/debian/) 21 Ubuntu | [Icinga Repository](https://packages.icinga.com/ubuntu/) 22 Raspbian | [Icinga Repository](https://packages.icinga.com/raspbian/). Note that **Raspbian `icinga-buster` is required.** 23 RHEL/CentOS | [Icinga Repository](https://packages.icinga.com/epel/) 24 openSUSE | [Icinga Repository](https://packages.icinga.com/openSUSE/) 25 SLES | [Icinga Repository](https://packages.icinga.com/SUSE/) 26 27Community repositories: 28 29 Distribution | Repository 30 ------------------------|--------------------------- 31 Gentoo | [Upstream](https://packages.gentoo.org/package/net-analyzer/icinga2) 32 FreeBSD | [Upstream](https://www.freshports.org/net-mgmt/icinga2) 33 OpenBSD | [Upstream](http://ports.su/net/icinga/core2,-main) 34 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2) 35 Alpine Linux | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2) 36 37Packages for distributions other than the ones listed above may also be 38available. Please contact your distribution packagers. 39 40> **Note** 41> 42> Windows is only supported for agent installations. Please refer 43> to the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows). 44 45### Package Repositories <a id="package-repositories"></a> 46 47You need to add the Icinga repository to your package management configuration. 48The following commands must be executed with `root` permissions unless noted otherwise. 49 50#### Debian/Ubuntu/Raspbian Repositories <a id="package-repositories-debian-ubuntu-raspbian"></a> 51 52Debian: 53 54```bash 55apt-get update 56apt-get -y install apt-transport-https wget gnupg 57 58wget -O - https://packages.icinga.com/icinga.key | apt-key add - 59 60DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ 61 echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \ 62 /etc/apt/sources.list.d/${DIST}-icinga.list 63 echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \ 64 /etc/apt/sources.list.d/${DIST}-icinga.list 65 66apt-get update 67``` 68 69Ubuntu: 70 71```bash 72apt-get update 73apt-get -y install apt-transport-https wget gnupg 74 75wget -O - https://packages.icinga.com/icinga.key | apt-key add - 76 77. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \ 78 echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \ 79 /etc/apt/sources.list.d/${DIST}-icinga.list 80 echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \ 81 /etc/apt/sources.list.d/${DIST}-icinga.list 82 83apt-get update 84``` 85 86Raspbian Buster: 87 88```bash 89apt-get update 90apt-get -y install apt-transport-https wget gnupg 91 92wget -O - https://packages.icinga.com/icinga.key | apt-key add - 93 94DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ 95 echo "deb https://packages.icinga.com/raspbian icinga-${DIST} main" > \ 96 /etc/apt/sources.list.d/icinga.list 97 echo "deb-src https://packages.icinga.com/raspbian icinga-${DIST} main" >> \ 98 /etc/apt/sources.list.d/icinga.list 99 100apt-get update 101``` 102 103##### Debian Backports Repository <a id="package-repositories-debian-backports"></a> 104 105> **Note**: 106> 107> This repository is required for Debian Stretch since v2.11. 108 109Debian Stretch: 110 111```bash 112DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ 113 echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \ 114 /etc/apt/sources.list.d/${DIST}-backports.list 115 116apt-get update 117``` 118 119#### RHEL/CentOS/Fedora Repositories <a id="package-repositories-rhel-centos-fedora"></a> 120 121RHEL/CentOS 8: 122 123```bash 124dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm 125``` 126 127RHEL/CentOS 7: 128 129```bash 130yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm 131``` 132 133RHEL/CentOS 6 x64: 134 135```bash 136yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm 137``` 138 139Fedora 31: 140 141```bash 142dnf install https://packages.icinga.com/fedora/icinga-rpm-release-31-latest.noarch.rpm 143``` 144 145##### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a> 146 147The packages for RHEL/CentOS depend on other packages which are distributed 148as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). 149 150CentOS 8 additionally needs the PowerTools repository for EPEL: 151 152```bash 153dnf install 'dnf-command(config-manager)' 154dnf config-manager --set-enabled powertools 155 156dnf install epel-release 157``` 158 159CentOS 7/6: 160 161```bash 162yum install epel-release 163``` 164 165If you are using RHEL you need to additionally enable the `optional` and `codeready-builder` 166repository before installing the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). 167 168RHEL 8: 169 170```bash 171ARCH=$( /bin/arch ) 172 173subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms" 174 175dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm 176``` 177 178RHEL 7: 179 180```bash 181subscription-manager repos --enable rhel-7-server-optional-rpms 182yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm 183``` 184 185RHEL 6: 186 187```bash 188subscription-manager repos --enable rhel-6-server-optional-rpms 189yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm 190``` 191 192#### SLES/OpenSUSE Repositories <a id="package-repositories-sles-opensuse"></a> 193 194The release repository also provides the required Boost 1.66+ packages 195since v2.11. 196 197SLES 15/12: 198 199```bash 200rpm --import https://packages.icinga.com/icinga.key 201 202zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo 203zypper ref 204``` 205 206openSUSE: 207 208```bash 209rpm --import https://packages.icinga.com/icinga.key 210 211zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo 212zypper ref 213``` 214 215#### Alpine Linux Repositories <a id="package-repositories-alpine"></a> 216 217```bash 218echo "http://dl-cdn.alpinelinux.org/alpine/edge/main" >> /etc/apk/repositories 219echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories 220apk update 221``` 222 223The example provided assumes that you are running Alpine edge, which is the -dev branch and is a rolling release. 224If you are using a stable version please "pin" the edge repository on the latest Icinga 2 package version. 225In order to correctly manage your repository, please follow 226[these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) 227 228### Installing Icinga 2 <a id="installing-icinga2"></a> 229 230You can install Icinga 2 by using your distribution's package manager 231to install the `icinga2` package. The following commands must be executed 232with `root` permissions unless noted otherwise. 233 234Debian/Ubuntu: 235 236```bash 237apt-get install icinga2 238``` 239 240RHEL/CentOS 8 and Fedora: 241 242```bash 243dnf install icinga2 244systemctl enable icinga2 245systemctl start icinga2 246``` 247 248RHEL/CentOS 7: 249 250```bash 251yum install icinga2 252systemctl enable icinga2 253systemctl start icinga2 254``` 255 256RHEL/CentOS 6: 257 258```bash 259yum install icinga2 260chkconfig icinga2 on 261service icinga2 start 262``` 263 264SLES/openSUSE: 265 266```bash 267zypper install icinga2 268``` 269 270FreeBSD: 271 272```bash 273pkg install icinga2 274``` 275 276Alpine Linux: 277 278```bash 279apk add icinga2 280``` 281 282## Setting up Check Plugins <a id="setting-up-check-plugins"></a> 283 284Without plugins Icinga 2 does not know how to check external services. The 285[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides 286an extensive set of plugins which can be used with Icinga 2 to check whether 287services are working properly. 288 289These plugins are required to make the [example configuration](04-configuration.md#configuring-icinga2-overview) 290work out-of-the-box. 291 292For your convenience here is a list of package names for some of the more 293popular operating systems/distributions: 294 295OS/Distribution | Package Name | Repository | Installation Path 296-----------------------|--------------------|---------------------------|---------------------------- 297RHEL/CentOS | nagios-plugins-all | [EPEL](02-installation.md#package-repositories-rhel-epel) | /usr/lib64/nagios/plugins 298SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins 299Debian/Ubuntu | monitoring-plugins | - | /usr/lib/nagios/plugins 300FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios 301Alpine Linux | monitoring-plugins | - | /usr/lib/monitoring-plugins 302 303The recommended way of installing these standard plugins is to use your 304distribution's package manager. 305 306Depending on which directory your plugins are installed into you may need to 307update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuration.md#constants-conf). 308This constant is used by the check command definitions contained in the Icinga Template Library 309to determine where to find the plugin binaries. 310 311> **Note** 312> 313> Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate 314> additional check plugins into your Icinga 2 setup. 315 316### Debian/Ubuntu <a id="setting-up-check-plugins-debian-ubuntu"></a> 317 318```bash 319apt-get install monitoring-plugins 320``` 321 322### RHEL/CentOS/Fedora <a id="setting-up-check-plugins-rhel-centos-fedora"></a> 323 324The packages for RHEL/CentOS depend on other packages which are distributed 325as part of the [EPEL repository](02-installation.md#package-repositories-rhel-epel). 326 327RHEL/CentOS 8: 328 329```bash 330dnf install nagios-plugins-all 331``` 332 333RHEL/CentOS 7/6: 334 335```bash 336yum install nagios-plugins-all 337``` 338 339Fedora: 340 341```bash 342dnf install nagios-plugins-all 343``` 344 345### SLES/openSUSE <a id="setting-up-check-plugins-sles-opensuse"></a> 346 347The packages for SLES/OpenSUSE depend on other packages which are distributed 348as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring). 349Please make sure to enable this repository beforehand. 350 351```bash 352zypper install monitoring-plugins 353``` 354 355### FreeBSD <a id="setting-up-check-plugins-freebsd"></a> 356 357```bash 358pkg install monitoring-plugins 359``` 360 361### Alpine Linux <a id="setting-up-check-plugins-alpine"></a> 362 363```bash 364apk add monitoring-plugins 365``` 366 367Note: For Alpine you don't need to explicitly add the `monitoring-plugins` package since it is a dependency of 368`icinga2` and is pulled automatically. 369 370## Running Icinga 2 <a id="running-icinga2"></a> 371 372### Systemd Service <a id="systemd-service"></a> 373 374The majority of supported distributions use systemd. The 375Icinga 2 packages automatically install the necessary systemd unit files. 376 377The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also 378queried for its current status. 379 380``` 381systemctl status icinga2 382 383icinga2.service - Icinga host/service/network monitoring system 384 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled) 385 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago 386 Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS) 387 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS) 388 Main PID: 21727 (icinga2) 389 CGroup: /system.slice/icinga2.service 390 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit 391 392Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s). 393Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s). 394Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s). 395Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s). 396Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s). 397Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s). 398Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s). 399Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system. 400``` 401 402The `systemctl` command supports the following actions: 403 404 Command | Description 405 --------------------|------------------------ 406 start | The `start` action starts the Icinga 2 daemon. 407 stop | The `stop` action stops the Icinga 2 daemon. 408 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`. 409 reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted. 410 status | The `status` action checks if Icinga 2 is running. 411 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) 412 413Examples: 414 415``` 416systemctl enable icinga2 417 418systemctl restart icinga2 419Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. 420``` 421 422If you're stuck with configuration errors, you can manually invoke the 423[configuration validation](11-cli-commands.md#config-validation). 424 425```bash 426icinga2 daemon -C 427``` 428 429> **Tip** 430> 431> If you are running into fork errors with systemd enabled distributions, 432> please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors). 433 434### Init Script <a id="init-script"></a> 435 436Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default: 437 438``` 439/etc/init.d/icinga2 440 441Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status} 442``` 443 444The init script supports the following actions: 445 446 Command | Description 447 --------------------|------------------------ 448 start | The `start` action starts the Icinga 2 daemon. 449 stop | The `stop` action stops the Icinga 2 daemon. 450 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`. 451 reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted. 452 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors. 453 status | The `status` action checks if Icinga 2 is running. 454 455By default, the Icinga 2 daemon is running as `icinga` user and group 456using the init script. Using Debian packages the user and group are set to 457`nagios` for historical reasons. 458 459 460### FreeBSD <a id="running-icinga2-freebsd"></a> 461 462On FreeBSD you need to enable icinga2 in your rc.conf 463 464```bash 465sysrc icinga2_enable=yes 466 467service icinga2 restart 468``` 469 470### SELinux <a id="running-icinga2-selinux"></a> 471 472SELinux is a mandatory access control (MAC) system on Linux which adds 473a fine-grained permission system for access to all system resources such 474as files, devices, networks and inter-process communication. 475 476Icinga 2 provides its own SELinux policy. `icinga2-selinux` is a policy package 477for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy 478which confines Icinga 2 including enabled features and running commands. 479 480RHEL/CentOS 8 and Fedora: 481 482```bash 483dnf install icinga2-selinux 484``` 485 486RHEL/CentOS 7: 487 488```bash 489yum install icinga2-selinux 490``` 491 492Read more about SELinux in [this chapter](22-selinux.md#selinux). 493 494## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a> 495 496Icinga 2 provides configuration examples for syntax highlighting using the `vim` and `nano` editors. 497The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax` 498(where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`. 499On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`); 500to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`. 501 502### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a> 503 504Install the package `vim-icinga2` with your distribution's package manager. 505 506Debian/Ubuntu: 507 508``` 509apt-get install vim-icinga2 vim-addon-manager 510vim-addon-manager -w install icinga2 511Info: installing removed addon 'icinga2' to /var/lib/vim/addons 512``` 513 514RHEL/CentOS 8 and Fedora: 515 516```bash 517dnf install vim-icinga2 518``` 519 520RHEL/CentOS 7/6: 521 522```bash 523yum install vim-icinga2 524``` 525 526SLES/openSUSE: 527 528```bash 529zypper install vim-icinga2 530``` 531 532Alpine Linux: 533 534```bash 535apk add icinga2-vim 536``` 537 538Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc` 539configuration file: 540 541``` 542# vim ~/.vimrc 543syntax on 544``` 545 546Test it: 547 548```bash 549vim /etc/icinga2/conf.d/templates.conf 550``` 551 552![Vim with syntax highlighting](images/installation/vim-syntax.png "Vim with Icinga 2 syntax highlighting") 553 554 555### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a> 556 557Install the package `nano-icinga2` with your distribution's package manager. 558 559Debian/Ubuntu: 560 561**Note:** The syntax files are installed with the `icinga2-common` package already. 562 563RHEL/CentOS 8 and Fedora: 564 565```bash 566dnf install nano-icinga2 567``` 568 569RHEL/CentOS 7/6: 570 571```bash 572yum install nano-icinga2 573``` 574 575SLES/openSUSE: 576 577```bash 578zypper install nano-icinga2 579``` 580 581Copy the `/etc/nanorc` sample file to your home directory. 582 583```bash 584cp /etc/nanorc ~/.nanorc 585``` 586 587Include the `icinga2.nanorc` file. 588 589``` 590$ vim ~/.nanorc 591 592## Icinga 2 593include "/usr/share/nano/icinga2.nanorc" 594``` 595 596Test it: 597 598```bash 599nano /etc/icinga2/conf.d/templates.conf 600``` 601 602![Nano with syntax highlighting](images/installation/nano-syntax.png "Nano with Icinga 2 syntax highlighting") 603 604## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a> 605 606Icinga 2 can be used with Icinga Web 2 and a variety of modules. 607This chapter explains how to set up Icinga Web 2. 608 609The DB IDO (Database Icinga Data Output) feature for Icinga 2 takes care of 610exporting all configuration and status information into a database. 611 612> **Note** 613> 614> We're currently working on a new data backend called Icinga DB. 615> If you want to try the latest release candidate skip to 616> the [Icinga DB Chapter](02-installation.md#icingadb). 617> Please keep in mind, that this version is not ready for use in 618> production and currently only supports MySQL. 619 620### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a> 621 622#### Installing MySQL database server <a id="installing-database-mysql-server"></a> 623 624Debian/Ubuntu: 625 626```bash 627apt-get install mariadb-server mariadb-client 628 629mysql_secure_installation 630``` 631 632RHEL/CentOS and Fedora: 633 634```bash 635yum install mariadb-server mariadb 636systemctl enable mariadb 637systemctl start mariadb 638mysql_secure_installation 639``` 640 641SUSE: 642 643```bash 644zypper install mysql mysql-client 645chkconfig mysqld on 646service mysqld start 647``` 648 649FreeBSD: 650 651```bash 652pkg install mysql56-server 653sysrc mysql_enable=yes 654service mysql-server restart 655mysql_secure_installation 656``` 657 658Alpine Linux: 659 660```bash 661apk add mariadb 662rc-service mariadb setup 663rc-update add mariadb default 664rc-service mariadb start 665``` 666 667#### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a> 668 669The next step is to install the `icinga2-ido-mysql` package using your 670distribution's package manager. 671 672Debian/Ubuntu: 673 674```bash 675apt-get install icinga2-ido-mysql 676``` 677 678RHEL/CentOS: 679 680```bash 681yum install icinga2-ido-mysql 682``` 683 684SUSE: 685 686```bash 687zypper install icinga2-ido-mysql 688``` 689 690FreeBSD: 691 692On FreeBSD the IDO modules for MySQL are included with the icinga2 package 693and located at `/usr/local/share/icinga2-ido-mysql/schema/mysql.sql`. 694 695Alpine Linux: 696 697On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package 698and located at `/usr/share/icinga2-ido-mysql/schema/mysql.sql`. 699 700> **Note** 701> 702> The Debian/Ubuntu packages provide a database configuration wizard by 703> default. You can skip the automated setup and install/upgrade the 704> database manually if you prefer. 705 706#### Setting up the MySQL database <a id="setting-up-mysql-db"></a> 707 708Set up a MySQL database for Icinga 2: 709 710``` 711# mysql -u root -p 712 713CREATE DATABASE icinga; 714GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; 715quit 716``` 717 718![setting up the database on CentOS 7](images/installation/mariadb-centos7.png "Setting up the database on CentOS 7") 719 720After creating the database you can import the Icinga 2 IDO schema using the 721following command. Enter the root password into the prompt when asked. 722 723```bash 724mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql 725``` 726 727#### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a> 728 729The package provides a new configuration file that is installed in 730`/etc/icinga2/features-available/ido-mysql.conf`. You can update 731the database credentials in this file. 732 733All available attributes are explained in the 734[IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection) 735chapter. 736 737You can enable the `ido-mysql` feature configuration file using 738`icinga2 feature enable`: 739 740``` 741# icinga2 feature enable ido-mysql 742Module 'ido-mysql' was enabled. 743Make sure to restart Icinga 2 for these changes to take effect. 744``` 745 746Restart Icinga 2. 747 748```bash 749systemctl restart icinga2 750``` 751 752Alpine Linux: 753 754```bash 755rc-service icinga2 restart 756``` 757 758Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). 759 760### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a> 761 762#### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a> 763 764Debian/Ubuntu: 765 766```bash 767apt-get install postgresql 768``` 769 770RHEL/CentOS: 771 772```bash 773yum install postgresql-server postgresql 774postgresql-setup initdb 775systemctl enable postgresql 776systemctl start postgresql 777``` 778 779SUSE: 780 781```bash 782zypper install postgresql postgresql-server 783chkconfig postgresql on 784service postgresql initdb 785service postgresql start 786``` 787 788FreeBSD: 789 790```bash 791pkg install postgresql93-server 792sysrc postgresql_enable=yes 793service postgresql initdb 794service postgresql start 795``` 796 797Alpine Linux: 798 799```bash 800apk add postgresql 801rc-update add postgresql default 802rc-service postgresql setup 803rc-service postgresql start 804``` 805 806#### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a> 807 808The next step is to install the `icinga2-ido-pgsql` package using your 809distribution's package manager. 810 811Debian/Ubuntu: 812 813```bash 814apt-get install icinga2-ido-pgsql 815``` 816 817RHEL/CentOS: 818 819```bash 820yum install icinga2-ido-pgsql 821``` 822 823SUSE: 824 825```bash 826zypper install icinga2-ido-pgsql 827``` 828 829FreeBSD: 830 831On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package 832and located at `/usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql`. 833 834Alpine Linux: 835 836On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package 837and located at `/usr/share/icinga2-ido-pgsql/schema/pgsql.sql`. 838 839> **Note** 840> 841> Upstream Debian packages provide a database configuration wizard by default. 842> You can skip the automated setup and install/upgrade the database manually 843> if you prefer that. 844 845#### Setting up the PostgreSQL database 846 847Set up a PostgreSQL database for Icinga 2: 848 849```bash 850cd /tmp 851sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" 852sudo -u postgres createdb -O icinga -E UTF8 icinga 853``` 854 855> **Note** 856> 857> It is assumed here that your locale is set to utf-8, you may run into problems otherwise. 858 859Locate your `pg_hba.conf` configuration file (Debian: `/etc/postgresql/*/main/pg_hba.conf`, 860RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with `md5` 861as authentication method and restart the postgresql server. 862 863``` 864# icinga 865local icinga icinga md5 866host icinga icinga 127.0.0.1/32 md5 867host icinga icinga ::1/128 md5 868 869# "local" is for Unix domain socket connections only 870local all all ident 871# IPv4 local connections: 872host all all 127.0.0.1/32 ident 873# IPv6 local connections: 874host all all ::1/128 ident 875``` 876 877```bash 878systemctl restart postgresql 879``` 880 881 882After creating the database and permissions you need to import the IDO database 883schema using the following command: 884 885```bash 886export PGPASSWORD=icinga 887psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql 888``` 889 890![importing the Icinga 2 IDO schema](images/installation/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie") 891 892 893#### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a> 894 895The package provides a new configuration file that is installed in 896`/etc/icinga2/features-available/ido-pgsql.conf`. You can update 897the database credentials in this file. 898 899All available attributes are explained in the 900[IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection) 901chapter. 902 903You can enable the `ido-pgsql` feature configuration file using 904`icinga2 feature enable`: 905 906``` 907# icinga2 feature enable ido-pgsql 908Module 'ido-pgsql' was enabled. 909Make sure to restart Icinga 2 for these changes to take effect. 910``` 911 912Restart Icinga 2. 913 914```bash 915systemctl restart icinga2 916``` 917 918Alpine Linux: 919 920```bash 921rc-service icinga2 restart 922``` 923 924Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). 925 926### Webserver <a id="icinga2-user-interface-webserver"></a> 927 928The preferred way of installing Icinga Web 2 is to use Apache as webserver 929in combination with PHP-FPM. If you prefer Nginx, please refer to the Icinga Web 2 930documentation. 931 932> **Note** 933> 934> These instructions follow HTTP. In order to secure your webserver, please 935> use HTTPS and TLS certificates e.g. from [Let's Encrypt](https://letsencrypt.org/). 936 937Debian/Ubuntu: 938 939```bash 940apt-get install apache2 941``` 942 943RHEL/CentOS/Fedora: 944 945```bash 946yum install httpd 947systemctl enable httpd 948systemctl start httpd 949``` 950 951SUSE: 952 953```bash 954zypper install apache2 955chkconfig apache2 on 956service apache2 start 957``` 958 959FreeBSD (Nginx, but you could also use the `apache24` package): 960 961```bash 962pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl 963sysrc php_fpm_enable=yes 964sysrc nginx_enable=yes 965sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf 966sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf 967sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf 968sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf 969service php-fpm start 970service nginx start 971``` 972 973Alpine Linux: 974 975```bash 976apk add apache2 php7-apache2 977sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf 978rc-update add apache2 default 979rc-service apache2 start 980``` 981 982### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a> 983 984Enable port 80 (http). Best practice is to only enable port 443 (https) and use TLS certificates. 985 986firewall-cmd: 987 988```bash 989firewall-cmd --add-service=http 990firewall-cmd --permanent --add-service=http 991``` 992 993iptables: 994 995```bash 996iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT 997service iptables save 998``` 999 1000FreeBSD: 1001Please consult the [FreeBSD Handbook](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls.html) how to configure one of FreeBSD's firewalls. 1002 1003 1004### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a> 1005 1006Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup) 1007to send actions (reschedule check, etc.) and query object details. 1008 1009You can run the CLI command `icinga2 api setup` to enable the 1010`api` [feature](11-cli-commands.md#enable-features) and set up 1011certificates as well as a new API user `root` with an auto-generated password in the 1012`/etc/icinga2/conf.d/api-users.conf` configuration file: 1013 1014```bash 1015icinga2 api setup 1016``` 1017 1018Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions) 1019attribute with minimal permissions required by Icinga Web 2. 1020 1021``` 1022vim /etc/icinga2/conf.d/api-users.conf 1023 1024object ApiUser "icingaweb2" { 1025 password = "Wijsn8Z9eRs5E25d" 1026 permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] 1027} 1028``` 1029 1030Restart Icinga 2 to activate the configuration. 1031 1032```bash 1033systemctl restart icinga2 1034``` 1035 1036Alpine Linux: 1037 1038```bash 1039rc-service icinga2 restart 1040``` 1041 1042### Installing Icinga Web 2 <a id="installing-icingaweb2"></a> 1043 1044Please consult the [Icinga Web 2 documentation](https://icinga.com/docs/icingaweb2/latest/) 1045for further instructions on how to install Icinga Web 2. 1046 1047If you decided on using Icinga DB, consult the [Icinga DB Web documentation](https://icinga.com/docs/icingadb/latest/icingadb-web/doc/01-About/) on how to connect Icinga Web 2 with Icinga DB. 1048 1049## Addons <a id="install-addons"></a> 1050 1051A number of additional features are available in the form of addons. A list of 1052popular addons is available in the 1053[Addons and Plugins](13-addons.md#addons) chapter. 1054 1055## Installation Overview <a id="installation-overview"></a> 1056 1057### Enabled Features during Installation <a id="installation-overview-enabled-features"></a> 1058 1059The default installation will enable three features required for a basic 1060Icinga 2 installation: 1061 1062* `checker` for executing checks 1063* `notification` for sending notifications 1064* `mainlog` for writing the `icinga2.log` file 1065 1066You can verify that by calling `icinga2 feature list` 1067[CLI command](11-cli-commands.md#cli-command-feature) to see which features are 1068enabled and disabled. 1069 1070``` 1071# icinga2 feature list 1072Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog 1073Enabled features: checker mainlog notification 1074``` 1075 1076### Installation Paths <a id="installation-overview-paths"></a> 1077 1078By default Icinga 2 uses the following files and directories: 1079 1080 Path | Description 1081 ----------------------------------------------|------------------------------------ 1082 /etc/icinga2 | Contains Icinga 2 configuration files. 1083 /usr/lib/systemd/system/icinga2.service | The Icinga 2 systemd service file on systems using systemd. 1084 /etc/systemd/system/icinga2.service.d/limits.conf | On distributions with systemd >227, additional service limits are required. 1085 /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC. 1086 /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary. 1087 /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path). 1088 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2. 1089 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration. 1090 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api). 1091 /var/run/icinga2 | PID file. 1092 /var/run/icinga2/cmd | Command pipe and Livestatus socket. 1093 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files. 1094 /var/spool/icinga2 | Used for performance data spool files. 1095 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. 1096 1097FreeBSD uses slightly different paths: 1098 1099By default Icinga 2 uses the following files and directories: 1100 1101 Path | Description 1102 ------------------------------------|------------------------------------ 1103 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files. 1104 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script. 1105 /usr/local/sbin/icinga2 | Shell wrapper for the Icinga 2 binary. 1106 /usr/local/lib/icinga2 | Libraries and the Icinga 2 binary. 1107 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2. 1108 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration. 1109 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api). 1110 /var/run/icinga2 | PID file. 1111 /var/run/icinga2/cmd | Command pipe and Livestatus socket. 1112 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files. 1113 /var/spool/icinga2 | Used for performance data spool files. 1114 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. 1115 1116 1117## Backup <a id="install-backup"></a> 1118 1119Ensure to include the following in your backups: 1120 1121* Configuration files in `/etc/icinga2` 1122* Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates) 1123* Runtime files in `/var/lib/icinga2` 1124* Optional: IDO database backup 1125 1126## Backup: Database <a id="install-backup-database"></a> 1127 1128MySQL/MariaDB: 1129 1130* [Documentation](https://mariadb.com/kb/en/library/backup-and-restore-overview/) 1131 1132PostgreSQL: 1133 1134* [Documentation](https://www.postgresql.org/docs/9.3/static/backup.html) 1135 1136## Icinga DB <a id="icingadb"></a> 1137 1138Icinga DB is a new data backend currently in development. 1139It's purpose is to synchronise data between Icinga 2 (Redis) and Icinga Web 2 (MySQL), some day replacing the IDO. 1140Don't worry, we won't drop support on the IDO any time soon. 1141 1142> **Note** 1143> Icinga DB is not ready to be used in production 1144> and should only be used for testing purposes. 1145 1146### Configuring Icinga DB <a id="configuring-icinga-db"></a> 1147 1148First, make sure to setup Icinga DB itself and its database backends (Redis and MySQL) by following the [installation instructions](https://icinga.com/docs/icingadb/latest/doc/02-Installation/). 1149 1150#### Enabling the Icinga DB feature <a id="enabling-icinga-db"></a> 1151 1152Icinga 2 provides a configuration file that is installed in 1153`/etc/icinga2/features-available/icingadb.conf`. You can update 1154the Redis credentials in this file. 1155 1156All available attributes are explained in the 1157[IcingaDB object](09-object-types.md#objecttype-icingadb) 1158chapter. 1159 1160You can enable the `icingadb` feature configuration file using 1161`icinga2 feature enable`: 1162 1163``` 1164# icinga2 feature enable icingadb 1165Module 'icingadb' was enabled. 1166Make sure to restart Icinga 2 for these changes to take effect. 1167``` 1168 1169Restart Icinga 2. 1170 1171```bash 1172systemctl restart icinga2 1173``` 1174 1175Alpine Linux: 1176 1177```bash 1178rc-service icinga2 restart 1179``` 1180 1181Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). 1182