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](https://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 - https://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 Install the package `vim-icinga2` with your distribution's package manager.
 329
 330 Debian/Ubuntu:
 331
 332     $ apt-get install vim-icinga2 vim-addon-manager
 333     $ vim-addon-manager -w install icinga2
 334     Info: installing removed addon 'icinga2' to /var/lib/vim/addons
 335
 336 RHEL/CentOS/Fedora:
 337
 338     $ yum install vim-icinga2
 339
 340 SLES/openSUSE:
 341
 342     $ zypper install vim-icinga2
 343
 344 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
 345 configuration file:
 346
 347     $ vim ~/.vimrc
 348     syntax on
 349
 350 Test it:
 351
 352     $ vim /etc/icinga2/conf.d/templates.conf
 353
 354 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
 355
 356
 357 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
 358
 359 Install the package `nano-icinga2` with your distribution's package manager.
 360
 361 Debian/Ubuntu:
 362
 363 **Note:** The syntax files are installed with the `icinga2-common` package already.
 364
 365 RHEL/CentOS/Fedora:
 366
 367     $ yum install nano-icinga2
 368
 369 SLES/openSUSE:
 370
 371     $ zypper install nano-icinga2
 372
 373 Copy the `/etc/nanorc` sample file to your home directory.
 374
 375     $ cp /etc/nanorc ~/.nanorc
 376
 377 Include the `icinga2.nanorc` file.
 378
 379     $ vim ~/.nanorc
 380
 381     ## Icinga 2
 382     include "/usr/share/nano/icinga2.nanorc"
 383
 384 Test it:
 385
 386     $ nano /etc/icinga2/conf.d/templates.conf
 387
 388 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
 389
 390 ## <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
 391
 392 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
 393 This chapter explains how to set up Icinga Web 2.
 394
 395 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
 396 exporting all configuration and status information into a database. The IDO
 397 database is used by a number of projects including
 398 [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting
 399 or Icinga Web 1.x.
 400
 401 There is a separate module for each database backend. At present support for
 402 both MySQL and PostgreSQL is implemented.
 403
 404 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
 405
 406 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
 407
 408 Debian/Ubuntu:
 409
 410     # apt-get install mysql-server mysql-client
 411
 412 RHEL/CentOS 5/6:
 413
 414     # yum install mysql-server mysql
 415     # chkconfig mysqld on
 416     # service mysqld start
 417     # mysql_secure_installation
 418
 419 RHEL/CentOS 7 and Fedora:
 420
 421     # yum install mariadb-server mariadb
 422     # systemctl enable mariadb
 423     # systemctl start mariadb
 424     # mysql_secure_installation
 425
 426 SUSE:
 427
 428     # zypper install mysql mysql-client
 429     # chkconfig mysqld on
 430     # service mysqld start
 431
 432 FreeBSD:
 433
 434     # pkg install mysql56-server
 435     # sysrc mysql_enable=yes
 436     # service mysql-server restart
 437     # mysql_secure_installation
 438
 439 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
 440
 441 The next step is to install the `icinga2-ido-mysql` package using your
 442 distribution's package manager.
 443
 444 Debian/Ubuntu:
 445
 446     # apt-get install icinga2-ido-mysql
 447
 448 RHEL/CentOS:
 449
 450     # yum install icinga2-ido-mysql
 451
 452 SUSE:
 453
 454     # zypper install icinga2-ido-mysql
 455
 456 FreeBSD:
 457
 458 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
 459 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
 460
 461 > **Note**
 462 >
 463 > The Debian/Ubuntu packages provide a database configuration wizard by
 464 > default. You can skip the automated setup and install/upgrade the
 465 > database manually if you prefer that.
 466
 467 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
 468
 469 Set up a MySQL database for Icinga 2:
 470
 471     # mysql -u root -p
 472
 473     mysql>  CREATE DATABASE icinga;
 474     mysql>  GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
 475     mysql> quit
 476
 477 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
 478
 479 After creating the database you can import the Icinga 2 IDO schema using the
 480 following command:
 481
 482     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
 483
 484
 485 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
 486
 487 The package provides a new configuration file that is installed in
 488 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
 489 update the database credentials in this file.
 490
 491 All available attributes are explained in the
 492 [IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
 493 chapter.
 494
 495 You can enable the `ido-mysql` feature configuration file using
 496 `icinga2 feature enable`:
 497
 498     # icinga2 feature enable ido-mysql
 499     Module 'ido-mysql' was enabled.
 500     Make sure to restart Icinga 2 for these changes to take effect.
 501
 502 After enabling the ido-mysql feature you have to restart Icinga 2:
 503
 504 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 505
 506     # service icinga2 restart
 507
 508 RHEL/CentOS 7 and Fedora:
 509
 510     # systemctl restart icinga2
 511
 512 FreeBSD:
 513
 514     # service icinga2 restart
 515
 516 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
 517
 518 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
 519
 520 Debian/Ubuntu:
 521
 522     # apt-get install postgresql
 523
 524 RHEL/CentOS 5/6:
 525
 526     # yum install postgresql-server postgresql
 527     # chkconfig postgresql on
 528     # service postgresql start
 529
 530 RHEL/CentOS 7:
 531
 532     # yum install postgresql-server postgresql
 533     # postgresql-setup initdb
 534     # systemctl enable postgresql
 535     # systemctl start postgresql
 536
 537 SUSE:
 538
 539     # zypper install postgresql postgresql-server
 540     # chkconfig postgresql on
 541     # service postgresql start
 542
 543 FreeBSD:
 544
 545     # pkg install postgresql93-server
 546     # sysrc postgresql_enable=yes
 547     # service postgresql start
 548
 549 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
 550
 551 The next step is to install the `icinga2-ido-pgsql` package using your
 552 distribution's package manager.
 553
 554 Debian/Ubuntu:
 555
 556     # apt-get install icinga2-ido-pgsql
 557
 558 RHEL/CentOS:
 559
 560     # yum install icinga2-ido-pgsql
 561
 562 SUSE:
 563
 564     # zypper install icinga2-ido-pgsql
 565
 566 FreeBSD:
 567
 568 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
 569 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
 570
 571 > **Note**
 572 >
 573 > Upstream Debian packages provide a database configuration wizard by default.
 574 > You can skip the automated setup and install/upgrade the database manually
 575 > if you prefer that.
 576
 577 #### Setting up the PostgreSQL database
 578
 579 Set up a PostgreSQL database for Icinga 2:
 580
 581     # cd /tmp
 582     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
 583     # sudo -u postgres createdb -O icinga -E UTF8 icinga
 584     # sudo -u postgres createlang plpgsql icinga
 585
 586 > **Note**
 587 >
 588 > When using PostgreSQL 9.x you can omit the `createlang` command.
 589 > Also it is assumed here that your locale is set to utf-8, you may run into
 590 > problems otherwise.
 591
 592 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
 593 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
 594 authentication method and restart the postgresql server.
 595
 596     # icinga
 597     local   icinga      icinga                            md5
 598     host    icinga      icinga      127.0.0.1/32          md5
 599     host    icinga      icinga      ::1/128               md5
 600
 601     # "local" is for Unix domain socket connections only
 602     local   all         all                               ident
 603     # IPv4 local connections:
 604     host    all         all         127.0.0.1/32          ident
 605     # IPv6 local connections:
 606     host    all         all         ::1/128               ident
 607
 608     # service postgresql restart
 609
 610
 611 After creating the database and permissions you can import the Icinga 2 IDO
 612 schema using the following command:
 613
 614     # export PGPASSWORD=icinga
 615     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 616
 617 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
 618
 619
 620 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
 621
 622 The package provides a new configuration file that is installed in
 623 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
 624 the database credentials in this file.
 625
 626 All available attributes are explained in the
 627 [IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
 628 chapter.
 629
 630 You can enable the `ido-pgsql` feature configuration file using
 631 `icinga2 feature enable`:
 632
 633     # icinga2 feature enable ido-pgsql
 634     Module 'ido-pgsql' was enabled.
 635     Make sure to restart Icinga 2 for these changes to take effect.
 636
 637 After enabling the ido-pgsql feature you have to restart Icinga 2:
 638
 639 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
 640
 641     # service icinga2 restart
 642
 643 RHEL/CentOS 7 and Fedora:
 644
 645     # systemctl restart icinga2
 646
 647
 648 ### <a id="icinga2-user-interface-webserver"></a> Webserver
 649
 650 Debian/Ubuntu:
 651
 652     # apt-get install apache2
 653
 654 RHEL/CentOS 6:
 655
 656     # yum install httpd
 657     # chkconfig httpd on
 658     # service httpd start
 659
 660 RHEL/CentOS 7/Fedora:
 661
 662     # yum install httpd
 663     # systemctl enable httpd
 664     # systemctl start httpd
 665
 666 SUSE:
 667
 668     # zypper install apache2
 669     # chkconfig on
 670     # service apache2 start
 671
 672 FreeBSD (nginx, but you could also use the apache24 package):
 673
 674     # 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
 675     # sysrc php_fpm_enable=yes
 676     # sysrc nginx_enable=yes
 677     # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
 678     # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
 679     # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
 680     # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
 681     # service php-fpm start
 682     # service nginx start
 683
 684 ### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
 685
 686 Example:
 687
 688     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
 689     # service iptables save
 690
 691 RHEL/CentOS 7 specific:
 692
 693     # firewall-cmd --add-service=http
 694     # firewall-cmd --permanent --add-service=http
 695
 696 FreeBSD:
 697 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.
 698
 699
 700 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
 701
 702 Web interfaces and other Icinga addons are able to send commands to
 703 Icinga 2 through the external command pipe.
 704
 705 You can enable the External Command Pipe using the CLI:
 706
 707     # icinga2 feature enable command
 708
 709 After that you will have to restart Icinga 2:
 710
 711 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 712
 713     # service icinga2 restart
 714
 715 RHEL/CentOS 7 and Fedora:
 716
 717     # systemctl restart icinga2
 718
 719 FreeBSD:
 720
 721     # service icinga2 restart
 722
 723 By default the command pipe file is owned by the group `icingacmd` with
 724 read/write permissions. Add your webserver's user to the group `icingacmd` to
 725 enable sending commands to Icinga 2 through your web interface:
 726
 727     # usermod -a -G icingacmd www-data
 728
 729 FreeBSD:
 730 On FreeBSD the rw directory is owned by the group `www`. You do not need to add the
 731 user `icinga` to the group `www`.
 732
 733 Debian packages use `nagios` as the default user and group name. Therefore
 734 change `icingacmd` to `nagios`.
 735
 736 The webserver's user is different between distributions so you might have to
 737 change `www-data` to `wwwrun`, `www`, or `apache`.
 738
 739 Change `www-data` to the user you're using to run queries.
 740
 741 You can verify that the user has been successfully added to the `icingacmd`
 742 group using the `id` command:
 743
 744     $ id <your-webserver-user>
 745
 746 ![id command on CentOS 7](images/getting-started/id-apache-centos7.png "Confirm that the webserver's user
 747 (here: `apache` on a CentOS 7 system) is a member of the group `icingacmd`.")
 748
 749 ### <a id="installing-icingaweb2"></a> Installing Icinga Web 2
 750
 751 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
 752 for further instructions on how to install Icinga Web 2.
 753
 754
 755 ## <a id="install-addons"></a> Addons
 756
 757 A number of additional features are available in the form of addons. A list of
 758 popular addons is available in the
 759 [Addons and Plugins](14-addons-plugins.md#addons-plugins) chapter.