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