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 Usually Icinga 2 is a mission critical part of infrastructure and should be
 351 online at all times. In case of a recoverable crash (e.g. OOM) you may want to
 352 restart Icinga 2 automatically. With Systemd it is as easy as overriding some
 353 settings of the Icinga 2 Systemd service by creating
 354 `/etc/systemd/system/icinga2.service.d/override.conf` with the following
 355 content:
 356
 357     [Service]
 358     Restart=always
 359     RestartSec=1
 360     StartLimitInterval=10
 361     StartLimitBurst=3
 362
 363 Run `systemctl daemon-reload && systemctl restart icinga2` to apply the changes.
 364 Now Systemd will always try to restart Icinga 2 (except if you run
 365 `systemctl stop icinga2`). After three failures in ten seconds it will stop
 366 trying because you probably have a problem that requires manual intervention.
 367
 368 > **Tip**
 369 >
 370 > If you are running into fork errors with Systemd enabled distributions,
 371 > please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors).
 372
 373 ### FreeBSD <a id="running-icinga2-freebsd"></a>
 374
 375 On FreeBSD you need to enable icinga2 in your rc.conf
 376
 377     # sysrc icinga2_enable=yes
 378
 379     # service icinga2 restart
 380
 381
 382 ### SELinux <a id="running-icinga2-selinux"></a>
 383
 384 SELinux is a mandatory access control (MAC) system on Linux which adds
 385 a fine-grained permission system for access to all system resources such
 386 as files, devices, networks and inter-process communication.
 387
 388 Icinga 2 provides its own SELinux policy. `icinga2-selinux` is a policy package
 389 for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy
 390 which confines Icinga 2 including enabled features and running commands.
 391
 392 RHEL/CentOS 7:
 393
 394 ```
 395 yum install icinga2-selinux
 396 ```
 397
 398 Fedora:
 399
 400 ```
 401 dnf install icinga2-selinux
 402 ```
 403
 404 Read more about SELinux in [this chapter](22-selinux.md#selinux).
 405
 406 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
 407
 408 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
 409 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
 410 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
 411 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
 412 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
 413
 414 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
 415
 416 Install the package `vim-icinga2` with your distribution's package manager.
 417
 418 Debian/Ubuntu:
 419
 420     # apt-get install vim-icinga2 vim-addon-manager
 421     # vim-addon-manager -w install icinga2
 422     Info: installing removed addon 'icinga2' to /var/lib/vim/addons
 423
 424 RHEL/CentOS/Fedora:
 425
 426     # yum install vim-icinga2
 427
 428 SLES/openSUSE:
 429
 430     # zypper install vim-icinga2
 431
 432 Alpine Linux:
 433
 434     # apk add icinga2-vim
 435
 436 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
 437 configuration file:
 438
 439     # vim ~/.vimrc
 440     syntax on
 441
 442 Test it:
 443
 444     # vim /etc/icinga2/conf.d/templates.conf
 445
 446 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
 447
 448
 449 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
 450
 451 Install the package `nano-icinga2` with your distribution's package manager.
 452
 453 Debian/Ubuntu:
 454
 455 **Note:** The syntax files are installed with the `icinga2-common` package already.
 456
 457 RHEL/CentOS/Fedora:
 458
 459     # yum install nano-icinga2
 460
 461 SLES/openSUSE:
 462
 463     # zypper install nano-icinga2
 464
 465 Copy the `/etc/nanorc` sample file to your home directory.
 466
 467     $ cp /etc/nanorc ~/.nanorc
 468
 469 Include the `icinga2.nanorc` file.
 470
 471     $ vim ~/.nanorc
 472
 473     ## Icinga 2
 474     include "/usr/share/nano/icinga2.nanorc"
 475
 476 Test it:
 477
 478     $ nano /etc/icinga2/conf.d/templates.conf
 479
 480 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
 481
 482 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
 483
 484 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
 485 This chapter explains how to set up Icinga Web 2.
 486
 487 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
 488 exporting all configuration and status information into a database. The IDO
 489 database is used by a number of projects including
 490 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
 491 or Icinga Web 1.x.
 492
 493 There is a separate module for each database backend. At present support for
 494 both MySQL and PostgreSQL has been implemented.
 495
 496 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
 497 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
 498
 499 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
 500
 501 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
 502
 503 Debian/Ubuntu:
 504
 505     # apt-get install mysql-server mysql-client
 506     # mysql_secure_installation
 507
 508 RHEL/CentOS 6:
 509
 510     # yum install mysql-server mysql
 511     # chkconfig mysqld on
 512     # service mysqld start
 513     # mysql_secure_installation
 514
 515 RHEL/CentOS 7 and Fedora:
 516
 517     # yum install mariadb-server mariadb
 518     # systemctl enable mariadb
 519     # systemctl start mariadb
 520     # mysql_secure_installation
 521
 522 SUSE:
 523
 524     # zypper install mysql mysql-client
 525     # chkconfig mysqld on
 526     # service mysqld start
 527
 528 FreeBSD:
 529
 530     # pkg install mysql56-server
 531     # sysrc mysql_enable=yes
 532     # service mysql-server restart
 533     # mysql_secure_installation
 534
 535 Alpine Linux:
 536
 537     # apk add mariadb
 538     # rc-service mariadb setup
 539     # rc-update add mariadb default
 540     # rc-service mariadb start
 541
 542 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
 543
 544 The next step is to install the `icinga2-ido-mysql` package using your
 545 distribution's package manager.
 546
 547 Debian/Ubuntu:
 548
 549     # apt-get install icinga2-ido-mysql
 550
 551 RHEL/CentOS:
 552
 553     # yum install icinga2-ido-mysql
 554
 555 SUSE:
 556
 557     # zypper install icinga2-ido-mysql
 558
 559 FreeBSD:
 560
 561 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
 562 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
 563
 564 Alpine Linux:
 565
 566 On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package
 567 and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql
 568
 569 > **Note**
 570 >
 571 > The Debian/Ubuntu packages provide a database configuration wizard by
 572 > default. You can skip the automated setup and install/upgrade the
 573 > database manually if you prefer that.
 574
 575 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
 576
 577 Set up a MySQL database for Icinga 2:
 578
 579     # mysql -u root -p
 580
 581     mysql>  CREATE DATABASE icinga;
 582     mysql>  GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
 583     mysql> quit
 584
 585 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
 586
 587 After creating the database you can import the Icinga 2 IDO schema using the
 588 following command:
 589
 590     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
 591
 592
 593 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
 594
 595 The package provides a new configuration file that is installed in
 596 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
 597 update the database credentials in this file.
 598
 599 All available attributes are explained in the
 600 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
 601 chapter.
 602
 603 You can enable the `ido-mysql` feature configuration file using
 604 `icinga2 feature enable`:
 605
 606     # icinga2 feature enable ido-mysql
 607     Module 'ido-mysql' was enabled.
 608     Make sure to restart Icinga 2 for these changes to take effect.
 609
 610 After enabling the ido-mysql feature you have to restart Icinga 2:
 611
 612 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 613
 614     # systemctl restart icinga2
 615
 616 Debian/Ubuntu, RHEL/CentOS 6, SUSE 11 and FreeBSD:
 617
 618     # service icinga2 restart
 619
 620 Alpine Linux:
 621
 622    # rc-service icinga2 restart
 623
 624 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
 625
 626 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
 627
 628 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
 629
 630 Debian/Ubuntu:
 631
 632     # apt-get install postgresql
 633
 634 RHEL/CentOS 6:
 635
 636     # yum install postgresql-server postgresql
 637     # chkconfig postgresql on
 638     # service postgresql start
 639
 640 RHEL/CentOS 7:
 641
 642     # yum install postgresql-server postgresql
 643     # postgresql-setup initdb
 644     # systemctl enable postgresql
 645     # systemctl start postgresql
 646
 647 SUSE:
 648
 649     # zypper install postgresql postgresql-server
 650     # chkconfig postgresql on
 651     # service postgresql start
 652
 653 FreeBSD:
 654
 655     # pkg install postgresql93-server
 656     # sysrc postgresql_enable=yes
 657     # service postgresql start
 658
 659 Alpine Linux:
 660
 661     # apk add postgresql
 662     # rc-update add postgresql default
 663     # rc-service postgresql setup
 664     # rc-service postgresql start
 665
 666 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
 667
 668 The next step is to install the `icinga2-ido-pgsql` package using your
 669 distribution's package manager.
 670
 671 Debian/Ubuntu:
 672
 673     # apt-get install icinga2-ido-pgsql
 674
 675 RHEL/CentOS:
 676
 677     # yum install icinga2-ido-pgsql
 678
 679 SUSE:
 680
 681     # zypper install icinga2-ido-pgsql
 682
 683 FreeBSD:
 684
 685 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
 686 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
 687
 688 Alpine Linux:
 689
 690 On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package
 691 and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 692
 693 > **Note**
 694 >
 695 > Upstream Debian packages provide a database configuration wizard by default.
 696 > You can skip the automated setup and install/upgrade the database manually
 697 > if you prefer that.
 698
 699 #### Setting up the PostgreSQL database
 700
 701 Set up a PostgreSQL database for Icinga 2:
 702
 703     # cd /tmp
 704     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
 705     # sudo -u postgres createdb -O icinga -E UTF8 icinga
 706     # sudo -u postgres createlang plpgsql icinga
 707
 708 > **Note**
 709 >
 710 > When using PostgreSQL 9.x you can omit the `createlang` command.
 711 > Also it is assumed here that your locale is set to utf-8, you may run into
 712 > problems otherwise.
 713
 714 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
 715 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
 716 authentication method and restart the postgresql server.
 717
 718     # icinga
 719     local   icinga      icinga                            md5
 720     host    icinga      icinga      127.0.0.1/32          md5
 721     host    icinga      icinga      ::1/128               md5
 722
 723     # "local" is for Unix domain socket connections only
 724     local   all         all                               ident
 725     # IPv4 local connections:
 726     host    all         all         127.0.0.1/32          ident
 727     # IPv6 local connections:
 728     host    all         all         ::1/128               ident
 729
 730     # service postgresql restart
 731
 732
 733 After creating the database and permissions you can import the Icinga 2 IDO
 734 schema using the following command:
 735
 736     # export PGPASSWORD=icinga
 737     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 738
 739 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
 740
 741
 742 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
 743
 744 The package provides a new configuration file that is installed in
 745 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
 746 the database credentials in this file.
 747
 748 All available attributes are explained in the
 749 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
 750 chapter.
 751
 752 You can enable the `ido-pgsql` feature configuration file using
 753 `icinga2 feature enable`:
 754
 755     # icinga2 feature enable ido-pgsql
 756     Module 'ido-pgsql' was enabled.
 757     Make sure to restart Icinga 2 for these changes to take effect.
 758
 759 After enabling the ido-pgsql feature you have to restart Icinga 2:
 760
 761 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 762
 763     # systemctl restart icinga2
 764
 765 Debian/Ubuntu, RHEL/CentOS 6, SUSE 11 and FreeBSD:
 766
 767     # service icinga2 restart
 768
 769 Alpine Linux:
 770
 771     # rc-service icinga2 restart
 772
 773 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
 774
 775 ### Webserver <a id="icinga2-user-interface-webserver"></a>
 776
 777 Debian/Ubuntu:
 778
 779     # apt-get install apache2
 780
 781 RHEL/CentOS 6:
 782
 783     # yum install httpd
 784     # chkconfig httpd on
 785     # service httpd start
 786
 787 RHEL/CentOS 7, Fedora:
 788
 789     # yum install httpd
 790     # systemctl enable httpd
 791     # systemctl start httpd
 792
 793 SUSE:
 794
 795     # zypper install apache2
 796     # chkconfig on
 797     # service apache2 start
 798
 799 FreeBSD (nginx, but you could also use the apache24 package):
 800
 801     # 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
 802     # sysrc php_fpm_enable=yes
 803     # sysrc nginx_enable=yes
 804     # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
 805     # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
 806     # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
 807     # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
 808     # service php-fpm start
 809     # service nginx start
 810
 811 Alpine Linux:
 812
 813     # apk add apache2 php7-apache2
 814     # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
 815     # rc-update add apache2 default
 816     # rc-service apache2 start
 817
 818 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
 819
 820 Example:
 821
 822     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
 823     # service iptables save
 824
 825 RHEL/CentOS 7 specific:
 826
 827     # firewall-cmd --add-service=http
 828     # firewall-cmd --permanent --add-service=http
 829
 830 FreeBSD:
 831 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.
 832
 833
 834 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
 835
 836 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
 837 to send actions (reschedule check, etc.) and query object details.
 838
 839 You can run the CLI command `icinga2 api setup` to enable the
 840 `api` [feature](11-cli-commands.md#enable-features) and set up
 841 certificates as well as a new API user `root` with an auto-generated password in the
 842 `/etc/icinga2/conf.d/api-users.conf` configuration file:
 843
 844     # icinga2 api setup
 845
 846 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
 847 attribute with minimal permissions required by Icinga Web 2.
 848
 849     # vim /etc/icinga2/conf.d/api-users.conf
 850
 851     object ApiUser "icingaweb2" {
 852       password = "Wijsn8Z9eRs5E25d"
 853       permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
 854     }
 855
 856 Make sure to restart Icinga 2 to activate the configuration.
 857
 858 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
 859
 860     # systemctl restart icinga2
 861
 862 Debian/Ubuntu, RHEL/CentOS 6, SUSE 11 and FreeBSD:
 863
 864     # service icinga2 restart
 865
 866 Alpine Linux:
 867
 868     # rc-service icinga2 restart
 869
 870 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
 871
 872 Please consult the [installation documentation](https://www.icinga.com/docs/icingaweb2/latest/doc/02-Installation/)
 873 for further instructions on how to install Icinga Web 2.
 874
 875 The Icinga 2 API can be defined as [command transport](https://www.icinga.com/docs/icingaweb2/latest/modules/monitoring/doc/05-Command-Transports/)
 876 in Icinga Web 2 >= 2.4.
 877
 878 ## Addons <a id="install-addons"></a>
 879
 880 A number of additional features are available in the form of addons. A list of
 881 popular addons is available in the
 882 [Addons and Plugins](13-addons.md#addons) chapter.
 883
 884 ## Backup <a id="install-backup"></a>
 885
 886 Ensure to include the following in your backups:
 887
 888 * Configuration files in `/etc/icinga2`
 889 * Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates)
 890 * Runtime files in `/var/lib/icinga2`
 891 * Optional: IDO database backup