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