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