granicus.if.org Git - icinga2/blob - doc/02-getting-started.md

   1 # Getting Started <a id="getting-started"></a>
   2
   3 This tutorial is a step-by-step introduction to installing [Icinga 2](02-getting-started.md#setting-up-icinga2)
   4 and [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2).
   5 It assumes that you are familiar with the operating system you're using to install Icinga 2.
   6
   7 ## Setting up Icinga 2 <a id="setting-up-icinga2"></a>
   8
   9 First off you have to install Icinga 2. The preferred way of doing this
  10 is to use the official package repositories depending on which operating system
  11 and distribution you are running.
  12
  13   Distribution            | Repository
  14   ------------------------|---------------------------
  15   Debian                  | [Icinga Repository](https://packages.icinga.com/debian/)
  16   Ubuntu                  | [Icinga Repository](https://packages.icinga.com/ubuntu/)
  17   RHEL/CentOS             | [Icinga Repository](https://packages.icinga.com/epel/)
  18   openSUSE                | [Icinga Repository](https://packages.icinga.com/openSUSE/)
  19   SLES                    | [Icinga Repository](https://packages.icinga.com/SUSE/)
  20   Gentoo                  | [Upstream](https://packages.gentoo.org/package/net-analyzer/icinga2)
  21   FreeBSD                 | [Upstream](https://www.freshports.org/net-mgmt/icinga2)
  22   OpenBSD                 | [Upstream](http://ports.su/net/icinga/core2,-main)
  23   ArchLinux               | [Upstream](https://aur.archlinux.org/packages/icinga2)
  24   Alpine Linux            | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2)
  25
  26 Packages for distributions other than the ones listed above may also be
  27 available. Please contact your distribution packagers.
  28
  29 ### Package Repositories <a id="package-repositories"></a>
  30
  31 You need to add the Icinga repository to your package management configuration.
  32 Below is a list with examples for the various distributions.
  33
  34 Debian:
  35
  36     # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
  37     # echo 'deb https://packages.icinga.com/debian icinga-stretch main' >/etc/apt/sources.list.d/icinga.list
  38     # apt-get update
  39
  40 Ubuntu:
  41
  42     # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
  43     # echo 'deb https://packages.icinga.com/ubuntu icinga-xenial main' >/etc/apt/sources.list.d/icinga.list
  44     # apt-get update
  45
  46 RHEL/CentOS 7:
  47
  48     yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
  49
  50 RHEL/CentOS 6:
  51
  52     yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
  53
  54 Fedora 26:
  55
  56     dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm
  57
  58 Fedora 25:
  59
  60     dnf install https://packages.icinga.com/fedora/icinga-rpm-release-25-latest.noarch.rpm
  61
  62 SLES 11:
  63
  64     # zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo
  65     # zypper ref
  66
  67 SLES 12:
  68
  69     # zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
  70     # zypper ref
  71
  72 openSUSE:
  73
  74     # zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
  75     # zypper ref
  76
  77
  78 Alpine Linux:
  79
  80     # echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
  81     # apk update
  82
  83 #### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
  84
  85 The packages for RHEL/CentOS depend on other packages which are distributed
  86 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
  87
  88 CentOS 7/6:
  89
  90     yum install epel-release
  91
  92 If you are using RHEL you need enable the `optional` repository and then install
  93 the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
  94
  95 #### SLES Security Repository <a id="package-repositories-sles-security"></a>
  96
  97 The packages for SLES 11 depend on the `openssl1` package which is distributed
  98 as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
  99
 100 #### SLES 12 SDK <a id="package-sles-sdk"></a>
 101
 102 Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
 103 Linux documentation for further information.
 104
 105 #### Alpine Linux Notes  <a id="package-repositories-alpine-notes"></a>
 106
 107 The example provided suppose that you are running Alpine edge, which is the -dev branch and is a rolling release.
 108 If you are using a stable version please "pin" the edge repository on the latest Icinga 2 package version.
 109 In order to correctly manage your repository, please follow
 110 [these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management)
 111
 112 ### Installing Icinga 2 <a id="installing-icinga2"></a>
 113
 114 You can install Icinga 2 by using your distribution's package manager
 115 to install the `icinga2` package.
 116
 117 Debian/Ubuntu:
 118
 119     # apt-get install icinga2
 120
 121 RHEL/CentOS 6:
 122
 123     # yum install icinga2
 124     # chkconfig icinga2 on
 125     # service icinga2 start
 126
 127 RHEL/CentOS 7 and Fedora:
 128
 129     # yum install icinga2
 130     # systemctl enable icinga2
 131     # systemctl start icinga2
 132
 133 SLES/openSUSE:
 134
 135     # zypper install icinga2
 136
 137 FreeBSD:
 138
 139     # pkg install icinga2
 140
 141
 142 Alpine Linux:
 143
 144     # apk add icinga2
 145
 146 ### Enabled Features during Installation <a id="installation-enabled-features"></a>
 147
 148 The default installation will enable three features required for a basic
 149 Icinga 2 installation:
 150
 151 * `checker` for executing checks
 152 * `notification` for sending notifications
 153 * `mainlog` for writing the `icinga2.log` file
 154
 155 You can verify that by calling `icinga2 feature list`
 156 [CLI command](11-cli-commands.md#cli-command-feature) to see which features are
 157 enabled and disabled.
 158
 159     # icinga2 feature list
 160     Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
 161     Enabled features: checker mainlog notification
 162
 163
 164 ### Installation Paths <a id="installation-paths"></a>
 165
 166 By default Icinga 2 uses the following files and directories:
 167
 168   Path                                          | Description
 169   ----------------------------------------------|------------------------------------
 170   /etc/icinga2                                  | Contains Icinga 2 configuration files.
 171   /usr/lib/systemd/system/icinga2.service       | The Icinga 2 Systemd service file on systems using Systemd.
 172   /etc/init.d/icinga2                           | The Icinga 2 init script on systems using SysVinit or OpenRC
 173   /usr/sbin/icinga2                             | Shell wrapper for the Icinga 2 binary.
 174   /usr/lib\*/icinga2                            | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
 175   /usr/share/doc/icinga2                        | Documentation files that come with Icinga 2.
 176   /usr/share/icinga2/include                    | The Icinga Template Library and plugin command configuration.
 177   /var/run/icinga2                              | PID file.
 178   /var/run/icinga2/cmd                          | Command pipe and Livestatus socket.
 179   /var/cache/icinga2                            | status.dat/objects.cache, icinga2.debug files
 180   /var/spool/icinga2                            | Used for performance data spool files.
 181   /var/lib/icinga2                              | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
 182   /var/log/icinga2                              | Log file location and compat/ directory for the CompatLogger feature.
 183
 184 FreeBSD uses slightly different paths:
 185
 186 By default Icinga 2 uses the following files and directories:
 187
 188   Path                                | Description
 189   ------------------------------------|------------------------------------
 190   /usr/local/etc/icinga2              | Contains Icinga 2 configuration files.
 191   /usr/local/etc/rc.d/icinga2         | The Icinga 2 init script.
 192   /usr/local/sbin/icinga2             | Shell wrapper for the Icinga 2 binary.
 193   /usr/local/lib/icinga2              | Libraries and the Icinga 2 binary.
 194   /usr/local/share/doc/icinga2        | Documentation files that come with Icinga 2.
 195   /usr/local/share/icinga2/include    | The Icinga Template Library and plugin command configuration.
 196   /var/run/icinga2                    | PID file.
 197   /var/run/icinga2/cmd                | Command pipe and Livestatus socket.
 198   /var/cache/icinga2                  | status.dat/objects.cache, icinga2.debug files
 199   /var/spool/icinga2                  | Used for performance data spool files.
 200   /var/lib/icinga2                    | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
 201   /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.
 202
 203 ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
 204
 205 Without plugins Icinga 2 does not know how to check external services. The
 206 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
 207 an extensive set of plugins which can be used with Icinga 2 to check whether
 208 services are working properly.
 209
 210 These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
 211 work out-of-the-box.
 212
 213 For your convenience here is a list of package names for some of the more
 214 popular operating systems/distributions:
 215
 216 OS/Distribution        | Package Name       | Repository                | Installation Path
 217 -----------------------|--------------------|---------------------------|----------------------------
 218 RHEL/CentOS            | nagios-plugins-all | [EPEL](https://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
 219 SLES/OpenSUSE          | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
 220 Debian/Ubuntu          | monitoring-plugins | -                         | /usr/lib/nagios/plugins
 221 FreeBSD                | monitoring-plugins | -                         | /usr/local/libexec/nagios
 222 Alpine Linux           | monitoring-plugins | -                         | /usr/lib/monitoring-plugins
 223 OS X                   | nagios-plugins     | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
 224
 225 The recommended way of installing these standard plugins is to use your
 226 distribution's package manager.
 227
 228 Debian/Ubuntu:
 229
 230     # apt-get install monitoring-plugins
 231
 232 RHEL/CentOS:
 233
 234     # yum install nagios-plugins-all
 235
 236 The packages for RHEL/CentOS depend on other packages which are distributed
 237 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please
 238 make sure to enable this repository by following
 239 [these instructions](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
 240
 241 Fedora:
 242
 243     # dnf install nagios-plugins-all
 244
 245 SLES/openSUSE:
 246
 247     # zypper install monitoring-plugins
 248
 249 The packages for SLES/OpenSUSE depend on other packages which are distributed
 250 as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
 251 Please make sure to enable this repository beforehand.
 252
 253 FreeBSD:
 254
 255     # pkg install monitoring-plugins
 256
 257 Alpine Linux:
 258
 259     # apk add monitoring-plugins
 260
 261 Note: For Alpine you don't need to explicitly add the `monitoring-plugins` package since it is a dependency of
 262 `icinga2` and is pulled automatically.
 263
 264 Depending on which directory your plugins are installed into you may need to
 265 update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
 266 This constant is used by the check command definitions contained in the Icinga Template Library
 267 to determine where to find the plugin binaries.
 268
 269 > **Note**
 270 >
 271 > Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
 272 > additional check plugins into your Icinga 2 setup.
 273
 274 ## Running Icinga 2 <a id="running-icinga2"></a>
 275
 276 ### Init Script <a id="init-script"></a>
 277
 278 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
 279
 280     # /etc/init.d/icinga2
 281     Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
 282
 283 The init script supports the following actions:
 284
 285   Command             | Description
 286   --------------------|------------------------
 287   start               | The `start` action starts the Icinga 2 daemon.
 288   stop                | The `stop` action stops the Icinga 2 daemon.
 289   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
 290   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.
 291   checkconfig         | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
 292   status              | The `status` action checks if Icinga 2 is running.
 293
 294 By default the Icinga 2 daemon is running as `icinga` user and group
 295 using the init script. Using Debian packages the user and group are set to
 296 `nagios` for historical reasons.
 297
 298 ### systemd Service <a id="systemd-service"></a>
 299
 300 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
 301 Icinga 2 packages automatically install the necessary systemd unit files.
 302
 303 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
 304 queried for its current status.
 305
 306     # systemctl status icinga2
 307     icinga2.service - Icinga host/service/network monitoring system
 308        Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
 309        Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
 310       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)
 311       Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
 312      Main PID: 21727 (icinga2)
 313        CGroup: /system.slice/icinga2.service
 314                21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
 315
 316     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
 317     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
 318     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
 319     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
 320     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
 321     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
 322     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
 323     Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
 324
 325 The `systemctl` command supports the following actions:
 326
 327   Command             | Description
 328   --------------------|------------------------
 329   start               | The `start` action starts the Icinga 2 daemon.
 330   stop                | The `stop` action stops the Icinga 2 daemon.
 331   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
 332   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.
 333   status              | The `status` action checks if Icinga 2 is running.
 334   enable              | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
 335
 336 Examples:
 337
 338     # systemctl enable icinga2
 339
 340     # systemctl restart icinga2
 341     Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
 342
 343 If you're stuck with configuration errors, you can manually invoke the
 344 [configuration validation](11-cli-commands.md#config-validation).
 345
 346 ### FreeBSD
 347
 348 On FreeBSD you need to enable icinga2 in your rc.conf
 349
 350     # sysrc icinga2_enable=yes
 351
 352     # service icinga2 restart
 353
 354 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
 355
 356 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
 357 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
 358 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
 359 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
 360 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
 361
 362 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
 363
 364 Install the package `vim-icinga2` with your distribution's package manager.
 365
 366 Debian/Ubuntu:
 367
 368     # apt-get install vim-icinga2 vim-addon-manager
 369     # vim-addon-manager -w install icinga2
 370     Info: installing removed addon 'icinga2' to /var/lib/vim/addons
 371
 372 RHEL/CentOS/Fedora:
 373
 374     # yum install vim-icinga2
 375
 376 SLES/openSUSE:
 377
 378     # zypper install vim-icinga2
 379
 380 Alpine Linux:
 381
 382    # apk add icinga2-vim
 383
 384 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
 385 configuration file:
 386
 387     # vim ~/.vimrc
 388     syntax on
 389
 390 Test it:
 391
 392     # vim /etc/icinga2/conf.d/templates.conf
 393
 394 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
 395
 396
 397 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
 398
 399 Install the package `nano-icinga2` with your distribution's package manager.
 400
 401 Debian/Ubuntu:
 402
 403 **Note:** The syntax files are installed with the `icinga2-common` package already.
 404
 405 RHEL/CentOS/Fedora:
 406
 407     # yum install nano-icinga2
 408
 409 SLES/openSUSE:
 410
 411     # zypper install nano-icinga2
 412
 413 Copy the `/etc/nanorc` sample file to your home directory.
 414
 415     $ cp /etc/nanorc ~/.nanorc
 416
 417 Include the `icinga2.nanorc` file.
 418
 419     $ vim ~/.nanorc
 420
 421     ## Icinga 2
 422     include "/usr/share/nano/icinga2.nanorc"
 423
 424 Test it:
 425
 426     $ nano /etc/icinga2/conf.d/templates.conf
 427
 428 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
 429
 430 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
 431
 432 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
 433 This chapter explains how to set up Icinga Web 2.
 434
 435 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
 436 exporting all configuration and status information into a database. The IDO
 437 database is used by a number of projects including
 438 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
 439 or Icinga Web 1.x.
 440
 441 There is a separate module for each database backend. At present support for
 442 both MySQL and PostgreSQL is implemented.
 443
 444 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
 445 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
 446
 447 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
 448
 449 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
 450
 451 Debian/Ubuntu:
 452
 453     # apt-get install mysql-server mysql-client
 454     # mysql_secure_installation
 455
 456 RHEL/CentOS 6:
 457
 458     # yum install mysql-server mysql
 459     # chkconfig mysqld on
 460     # service mysqld start
 461     # mysql_secure_installation
 462
 463 RHEL/CentOS 7 and Fedora:
 464
 465     # yum install mariadb-server mariadb
 466     # systemctl enable mariadb
 467     # systemctl start mariadb
 468     # mysql_secure_installation
 469
 470 SUSE:
 471
 472     # zypper install mysql mysql-client
 473     # chkconfig mysqld on
 474     # service mysqld start
 475
 476 FreeBSD:
 477
 478     # pkg install mysql56-server
 479     # sysrc mysql_enable=yes
 480     # service mysql-server restart
 481     # mysql_secure_installation
 482
 483 Alpine Linux:
 484
 485     # apk add mariadb
 486     # rc-service mariadb setup
 487     # rc-update add mariadb default
 488     # rc-service mariadb start
 489
 490 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
 491
 492 The next step is to install the `icinga2-ido-mysql` package using your
 493 distribution's package manager.
 494
 495 Debian/Ubuntu:
 496
 497     # apt-get install icinga2-ido-mysql
 498
 499 RHEL/CentOS:
 500
 501     # yum install icinga2-ido-mysql
 502
 503 SUSE:
 504
 505     # zypper install icinga2-ido-mysql
 506
 507 FreeBSD:
 508
 509 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
 510 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
 511
 512 Alpine Linux:
 513
 514 On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package
 515 and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql
 516
 517 > **Note**
 518 >
 519 > The Debian/Ubuntu packages provide a database configuration wizard by
 520 > default. You can skip the automated setup and install/upgrade the
 521 > database manually if you prefer that.
 522
 523 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
 524
 525 Set up a MySQL database for Icinga 2:
 526
 527     # mysql -u root -p
 528
 529     mysql>  CREATE DATABASE icinga;
 530     mysql>  GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
 531     mysql> quit
 532
 533 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
 534
 535 After creating the database you can import the Icinga 2 IDO schema using the
 536 following command:
 537
 538     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
 539
 540
 541 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
 542
 543 The package provides a new configuration file that is installed in
 544 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
 545 update the database credentials in this file.
 546
 547 All available attributes are explained in the
 548 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
 549 chapter.
 550
 551 You can enable the `ido-mysql` feature configuration file using
 552 `icinga2 feature enable`:
 553
 554     # icinga2 feature enable ido-mysql
 555     Module 'ido-mysql' was enabled.
 556     Make sure to restart Icinga 2 for these changes to take effect.
 557
 558 After enabling the ido-mysql feature you have to restart Icinga 2:
 559
 560 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 561
 562     # systemctl restart icinga2
 563
 564 Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
 565
 566     # service icinga2 restart
 567
 568 FreeBSD:
 569
 570     # service icinga2 restart
 571
 572 Alpine Linux:
 573
 574    # rc-service icinga2 restart
 575
 576 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
 577
 578 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
 579
 580 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
 581
 582 Debian/Ubuntu:
 583
 584     # apt-get install postgresql
 585
 586 RHEL/CentOS 6:
 587
 588     # yum install postgresql-server postgresql
 589     # chkconfig postgresql on
 590     # service postgresql start
 591
 592 RHEL/CentOS 7:
 593
 594     # yum install postgresql-server postgresql
 595     # postgresql-setup initdb
 596     # systemctl enable postgresql
 597     # systemctl start postgresql
 598
 599 SUSE:
 600
 601     # zypper install postgresql postgresql-server
 602     # chkconfig postgresql on
 603     # service postgresql start
 604
 605 FreeBSD:
 606
 607     # pkg install postgresql93-server
 608     # sysrc postgresql_enable=yes
 609     # service postgresql start
 610
 611 Alpine Linux:
 612
 613    # apk add postgresql
 614    # rc-update add postgresql default
 615    # rc-service postgresql setup
 616    # rc-service postgresql start
 617
 618 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
 619
 620 The next step is to install the `icinga2-ido-pgsql` package using your
 621 distribution's package manager.
 622
 623 Debian/Ubuntu:
 624
 625     # apt-get install icinga2-ido-pgsql
 626
 627 RHEL/CentOS:
 628
 629     # yum install icinga2-ido-pgsql
 630
 631 SUSE:
 632
 633     # zypper install icinga2-ido-pgsql
 634
 635 FreeBSD:
 636
 637 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
 638 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
 639
 640 Alpine Linux:
 641
 642 On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package
 643 and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 644
 645 > **Note**
 646 >
 647 > Upstream Debian packages provide a database configuration wizard by default.
 648 > You can skip the automated setup and install/upgrade the database manually
 649 > if you prefer that.
 650
 651 #### Setting up the PostgreSQL database
 652
 653 Set up a PostgreSQL database for Icinga 2:
 654
 655     # cd /tmp
 656     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
 657     # sudo -u postgres createdb -O icinga -E UTF8 icinga
 658     # sudo -u postgres createlang plpgsql icinga
 659
 660 > **Note**
 661 >
 662 > When using PostgreSQL 9.x you can omit the `createlang` command.
 663 > Also it is assumed here that your locale is set to utf-8, you may run into
 664 > problems otherwise.
 665
 666 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
 667 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
 668 authentication method and restart the postgresql server.
 669
 670     # icinga
 671     local   icinga      icinga                            md5
 672     host    icinga      icinga      127.0.0.1/32          md5
 673     host    icinga      icinga      ::1/128               md5
 674
 675     # "local" is for Unix domain socket connections only
 676     local   all         all                               ident
 677     # IPv4 local connections:
 678     host    all         all         127.0.0.1/32          ident
 679     # IPv6 local connections:
 680     host    all         all         ::1/128               ident
 681
 682     # service postgresql restart
 683
 684
 685 After creating the database and permissions you can import the Icinga 2 IDO
 686 schema using the following command:
 687
 688     # export PGPASSWORD=icinga
 689     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 690
 691 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
 692
 693
 694 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
 695
 696 The package provides a new configuration file that is installed in
 697 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
 698 the database credentials in this file.
 699
 700 All available attributes are explained in the
 701 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
 702 chapter.
 703
 704 You can enable the `ido-pgsql` feature configuration file using
 705 `icinga2 feature enable`:
 706
 707     # icinga2 feature enable ido-pgsql
 708     Module 'ido-pgsql' was enabled.
 709     Make sure to restart Icinga 2 for these changes to take effect.
 710
 711 After enabling the ido-pgsql feature you have to restart Icinga 2:
 712
 713 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 714
 715     # systemctl restart icinga2
 716
 717 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
 718
 719     # service icinga2 restart
 720
 721 FreeBSD:
 722
 723     # service icinga2 restart
 724
 725 Alpine Linux:
 726
 727     # rc-service icinga2 restart
 728
 729 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
 730
 731 ### Webserver <a id="icinga2-user-interface-webserver"></a>
 732
 733 Debian/Ubuntu:
 734
 735     # apt-get install apache2
 736
 737 RHEL/CentOS 6:
 738
 739     # yum install httpd
 740     # chkconfig httpd on
 741     # service httpd start
 742
 743 RHEL/CentOS 7, Fedora:
 744
 745     # yum install httpd
 746     # systemctl enable httpd
 747     # systemctl start httpd
 748
 749 SUSE:
 750
 751     # zypper install apache2
 752     # chkconfig on
 753     # service apache2 start
 754
 755 FreeBSD (nginx, but you could also use the apache24 package):
 756
 757     # pkg 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
 758     # sysrc php_fpm_enable=yes
 759     # sysrc nginx_enable=yes
 760     # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
 761     # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
 762     # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
 763     # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
 764     # service php-fpm start
 765     # service nginx start
 766
 767 Alpine Linux:
 768
 769     # apk add apache2 php7-apache2
 770     # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
 771     # rc-update add apache2 default
 772     # rc-service apache2 start
 773
 774 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
 775
 776 Example:
 777
 778     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
 779     # service iptables save
 780
 781 RHEL/CentOS 7 specific:
 782
 783     # firewall-cmd --add-service=http
 784     # firewall-cmd --permanent --add-service=http
 785
 786 FreeBSD:
 787 Please 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.
 788
 789
 790 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
 791
 792 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
 793 to send actions (reschedule check, etc.) and query object details.
 794
 795 You can run the CLI command `icinga2 api setup` to enable the
 796 `api` [feature](11-cli-commands.md#enable-features) and set up
 797 certificates as well as a new API user `root` with an auto-generated password in the
 798 `/etc/icinga2/conf.d/api-users.conf` configuration file:
 799
 800     # icinga2 api setup
 801
 802 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
 803 attribute with minimal permissions required by Icinga Web 2.
 804
 805     # vim /etc/icinga2/conf.d/api-users.conf
 806
 807     object ApiUser "icingaweb2" {
 808       password = "Wijsn8Z9eRs5E25d"
 809       permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
 810     }
 811
 812 Make sure to restart Icinga 2 to activate the configuration.
 813
 814 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 815
 816     # systemctl restart icinga2
 817
 818 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 819
 820     # service icinga2 restart
 821
 822 FreeBSD:
 823
 824     # service icinga2 restart
 825
 826 Alpine Linux:
 827
 828     # rc-service icinga2 restart
 829
 830 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
 831
 832 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
 833 for further instructions on how to install Icinga Web 2.
 834
 835 The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
 836 in Icinga Web 2 >= 2.4.
 837
 838 ## Addons <a id="install-addons"></a>
 839
 840 A number of additional features are available in the form of addons. A list of
 841 popular addons is available in the
 842 [Addons and Plugins](13-addons.md#addons) chapter.
 843
 844 ## Backup <a id="install-backup"></a>
 845
 846 Ensure to include the following in your backups:
 847
 848 * Configuration files in `/etc/icinga2`
 849 * Runtime files in `/var/lib/icinga2` (the master's CA is stored here as well)
 850 * Optional: IDO database backup