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