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

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