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