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

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