1 # <a id="getting-started"></a> Getting Started
3 This tutorial is a step-by-step introduction to installing Icinga 2 and
4 available Icinga web interfaces. It assumes that you are familiar with
5 the system you're installing Icinga 2 on.
7 Details on troubleshooting problems can be found [here](#troubleshooting).
9 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
11 First off you will have to install Icinga 2. The preferred way of doing this
12 is to use the official Debian or RPM package repositories depending on which
13 operating system and distribution you are running.
15 Distribution | Repository URL
16 ------------------------|---------------------------
17 Debian | http://packages.icinga.org/debian/
18 Ubuntu | http://packages.icinga.org/ubuntu/
19 RHEL/CentOS | http://packages.icinga.org/epel/
20 OpenSUSE | http://packages.icinga.org/openSUSE/
21 SLES | http://packages.icinga.org/SUSE/
23 Packages for distributions other than the ones listed above may also be
24 available. Please check http://packages.icinga.org/ to see if packages
25 are available for your favourite distribution.
27 The packages for RHEL/CentOS 5 depend on other packages which are distributed
28 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
29 make sure to enable this repository.
31 You can install Icinga 2 by using your distribution's package manager
32 to install the `icinga2` package.
34 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
35 `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
37 Some parts of Icinga 2's functionality are available as separate packages:
40 ------------------------|--------------------------------
41 icinga2-ido-mysql | IDO provider module for MySQL
42 icinga2-ido-pgsql | IDO provider module for PostgreSQL
44 If you're running a distribution for which Icinga 2 packages are
45 not yet available you will need to use the release tarball which you
46 can download from the [Icinga website](https://www.icinga.org/). The
47 release tarballs contain an `INSTALL` file with further instructions.
49 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
51 The default installation will enable three features required for a basic
52 Icinga 2 installation:
54 * `checker` for executing checks
55 * `notification` for sending notifications
56 * `mainlog` for writing the `icinga2.log ` file
58 Verify that by calling `icinga2-enable-feature` without any additional parameters
59 and enable the missing features, if any.
61 # icinga2-enable-feature
62 Syntax: icinga2-enable-feature <features separated with whitespaces>
63 Example: icinga2-enable-feature checker notification mainlog
64 Enables the specified feature(s).
66 Available features: api checker command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus mainlog notification perfdata statusdata syslog
67 Enabled features: checker mainlog notification
69 ### <a id="installation-paths"></a> Installation Paths
71 By default Icinga 2 uses the following files and directories:
74 ------------------------------------|------------------------------------
75 /etc/icinga2 | Contains Icinga 2 configuration files.
76 /etc/init.d/icinga2 | The Icinga 2 init script.
77 /usr/bin/icinga2-* | Migration and certificate build scripts.
78 /usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts.
79 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
80 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
81 /var/run/icinga2 | PID file.
82 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
83 /var/cache/icinga2 | status.dat/objects.cache.
84 /var/spool/icinga2 | Used for performance data spool files.
85 /var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
86 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
88 ### <a id="icinga2-conf"></a> icinga2.conf
90 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
92 Here's a brief description of the example configuration:
95 * Icinga 2 configuration file
96 * - this is where you define settings for the Icinga application including
97 * which hosts/services to check.
99 * For an overview of all available configuration options please refer
100 * to the documentation that is distributed as part of Icinga 2.
103 Icinga 2 supports [C/C++-style comments](#comments).
106 * The constants.conf defines global constants.
108 include "constants.conf"
110 The `include` directive can be used to include other files.
113 * The zones.conf defines zones for a cluster setup.
114 * Not required for single instance setups.
119 * The Icinga Template Library (ITL) provides a number of useful templates
120 * and command definitions.
121 * Common monitoring plugin command definitions are included separately.
127 * The features-available directory contains a number of configuration
128 * files for features which can be enabled and disabled using the
129 * icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
130 * and removing symbolic links in the features-enabled directory.
132 include "features-enabled/*.conf"
134 This `include` directive takes care of including the configuration files for all
135 the features which have been enabled with `icinga2-enable-feature`. See
136 [Enabling/Disabling Features](#features) for more details.
139 * Although in theory you could define all your objects in this file
140 * the preferred way is to create separate directories and files in the conf.d
141 * directory. Each of these files must have the file extension ".conf".
143 include_recursive "conf.d"
145 You can put your own configuration files in the `conf.d` directory. This
146 directive makes sure that all of your own configuration files are included.
148 ### <a id="constants-conf"></a> constants.conf
150 The `constants.conf` configuration file can be used to define global constants:
153 * This file defines global constants which can be used in
154 * the other configuration files.
157 /* The directory which contains the plugins from the Monitoring Plugins project. */
158 const PluginDir = "/usr/lib/nagios/plugins"
160 /* Our local instance name. This should be the common name from the API certificate */
161 const NodeName = "localhost"
163 /* Our local zone name. */
164 const ZoneName = NodeName
166 ### <a id="zones-conf"></a> zones.conf
168 The `zones.conf` configuration file can be used to configure `Endpoint` and `Zone` objects
169 required for a [distributed zone setup](#distributed-monitoring-high-availability). By default
170 a local dummy zone is defined based on the `NodeName` constant defined in
171 [constants.conf](#constants-conf).
175 > Not required for single instance installations.
178 ### <a id="localhost-conf"></a> localhost.conf
180 The `conf.d/localhost.conf` file contains our first host definition:
183 * A host definition. You can create your own configuration files
184 * in the conf.d directory (e.g. one per host). By default all *.conf
185 * files in this directory are included.
188 object Host "localhost" {
189 import "generic-host"
191 address = "127.0.0.1"
198 This defines the host `localhost`. The `import` keyword is used to import
199 the `generic-host` template which takes care of setting up the host check
202 The `vars` attribute can be used to define custom attributes which are available
203 for check and notification commands. Most of the templates in the Icinga
204 Template Library require an `address` attribute.
206 The custom attribute `os` is evaluated by the `linux-servers` group in
207 `groups.conf `making the host `localhost` a member.
209 object HostGroup "linux-servers" {
210 display_name = "Linux Servers"
212 assign where host.vars.os == "Linux"
215 A host notification apply rule in `notifications.conf` checks for the custom
216 attribute `sla` being set to `24x7` automatically applying a host notification.
219 * The example notification apply rules.
221 * Only applied if host/service objects have
222 * the custom attribute `sla` set to `24x7`.
225 apply Notification "mail-icingaadmin" to Host {
226 import "mail-host-notification"
228 user_groups = [ "icingaadmins" ]
230 assign where host.vars.sla == "24x7"
233 Now it's time to define services for the host object. Because these checks
234 are only available for the `localhost` host, they are organized below
239 > The directory tree and file organisation is just an example. You are
240 > free to define your own strategy. Just keep in mind to include the
241 > main directories in the [icinga2.conf](#icinga2-conf) file.
243 object Service "disk" {
244 import "generic-service"
246 host_name = "localhost"
247 check_command = "disk"
251 object Service "http" {
252 import "generic-service"
254 host_name = "localhost"
255 check_command = "http"
259 object Service "load" {
260 import "generic-service"
262 host_name = "localhost"
263 check_command = "load"
267 object Service "procs" {
268 import "generic-service"
270 host_name = "localhost"
271 check_command = "procs"
275 object Service "ssh" {
276 import "generic-service"
278 host_name = "localhost"
279 check_command = "ssh"
283 object Service "swap" {
284 import "generic-service"
286 host_name = "localhost"
287 check_command = "swap"
291 object Service "users" {
292 import "generic-service"
294 host_name = "localhost"
295 check_command = "users"
299 object Service "icinga" {
300 import "generic-service"
302 host_name = "localhost"
303 check_command = "icinga"
307 The command object `icinga` for the embedded health check is provided by the
308 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
309 `users` and `disk` are all provided by the plugin check commands which we enabled
310 earlier by including the `itl` and `plugins` configuration file.
312 The Debian packages also ship an additional `apt` service check.
316 > Instead of defining each service object and assigning it to a host object
317 > using the `host_name` attribute rather use the [apply rules](#apply)
318 > simplifying your configuration.
320 There are two generic services applied to all hosts in the host group `linux-servers`
321 and `windows-servers` by default: `ping4` and `ping6`. Host objects without
322 a valid `address` resp. `address6` attribute will be excluded.
324 apply Service "ping4" {
325 import "generic-service"
327 check_command = "ping4"
330 assign where "linux-servers" in host.groups
331 assign where "windows-servers" in host.groups
332 ignore where host.address == ""
335 apply Service "ping6" {
336 import "generic-service"
338 check_command = "ping6"
341 assign where "linux-servers" in host.groups
342 assign where "windows-servers" in host.groups
343 ignore where host.address6 == ""
346 Each of these services has the custom attribute `sla` set to `24x7`. The
347 notification apply rule in `notifications.conf` will automatically apply
348 a service notification matchting this attribute pattern.
350 apply Notification "mail-icingaadmin" to Service {
351 import "mail-service-notification"
353 user_groups = [ "icingaadmins" ]
355 assign where service.vars.sla == "24x7"
358 Don't forget to install the [check plugins](#setting-up-check-plugins) required by the services and
359 their check commands.
361 Further details on the monitoring configuration can be found in the
362 [monitoring basics](#monitoring-basics) chapter.
364 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
367 Icinga 2 does not know how to check external services. The
368 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
369 an extensive set of plugins which can be used with Icinga 2 to check whether
370 services are working properly.
372 The recommended way of installing these standard plugins is to use your
373 distribution's package manager.
377 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
378 > in January 2014. At the time of this writing the packages are still
379 > using the old name.
381 For your convenience here is a list of package names for some of the more
382 popular operating systems/distributions:
384 OS/Distribution | Package Name | Installation Path
385 -----------------------|--------------------|---------------------------
386 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
387 Debian | nagios-plugins | /usr/lib/nagios/plugins
388 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
389 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
391 Depending on which directory your plugins are installed into you may need to
392 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
393 by the service templates contained in the Icinga Template Library to determine
394 where to find the plugin binaries.
396 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
398 For some services you may need additional 'check plugins' which are not provided
399 by the official Monitoring Plugins project.
401 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
402 list of popular community sites which host check plugins:
404 * [MonitoringExchange](https://www.monitoringexchange.org)
405 * [Icinga Wiki](https://wiki.icinga.org)
407 The recommended way of setting up these plugins is to copy them to a common directory
408 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
411 # cp check_snmp_int.pl /opt/plugins
412 # chmod +x /opt/plugins/check_snmp_int.pl
414 # cat /etc/icinga2/constants.conf
416 * This file defines global constants which can be used in
417 * the other configuration files. At a minimum the
418 * PluginDir constant should be defined.
421 const PluginDir = "/usr/lib/nagios/plugins"
422 const CustomPluginDir = "/opt/monitoring"
424 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
425 by trying to run it on the console using whichever user Icinga 2 is running as:
427 # su - icinga -s /bin/bash
428 $ /opt/plugins/check_snmp_int.pl --help
430 Additional libraries may be required for some plugins. Please consult the plugin
431 documentation and/or README for installation instructions.
433 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
434 configuration which can be used in the [Service](#objecttype-service) or
435 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
436 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
438 For further information on your monitoring configuration read the
439 [monitoring basics](#monitoring-basics).
442 ## <a id="configuring-ido"></a> Configuring IDO
444 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
445 configuration and status information into a database. The IDO database is used
446 by a number of projects including Icinga Web.
448 There is a separate module for each database back-end. At present support for
449 both MySQL and PostgreSQL is implemented.
451 Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
452 `1.11.0`. Icinga 2 may require additional features not yet released with
453 Icinga 1.x and therefore require manual upgrade steps during pre-final
458 > Only install the IDO feature if your web interface or reporting tool requires
459 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
460 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
462 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
464 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
466 First of all you have to install the `icinga2-ido-mysql` package using your
467 distribution's package manager. Once you have done that you can proceed with
468 setting up a MySQL database for Icinga 2:
472 > The Debian packages can optionally create and maintain the database for you
473 > using Debian's `dbconfig` framework. This is the recommended way of setting up
478 mysql> CREATE DATABASE icinga;
480 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
485 After creating the database you can import the Icinga 2 IDO schema using the
488 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
490 The schema file location differs by the distribution used:
492 Distribution | Schema Files
493 --------------|---------------------
494 RHEL | `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
495 SUSE | `/usr/share/doc/packages/icinga2-ido-mysql/schema`
496 Debian/Ubuntu | `/usr/share/icinga2-ido-mysql/schema`
498 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
500 Check the `schema/upgrade` directory for an incremental schema upgrade file.
501 If there isn't an upgrade file available there's nothing to do.
505 > During pre release status (0.x.y releases) small snippets called for example
506 > `0.0.10.sql` will ship the required schema updates.
508 Apply all database schema upgrade files incrementially.
510 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
512 The Icinga 2 IDO module will check for the required database schema version on startup
513 and generate an error message if not satisfied.
515 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
517 The package provides a new configuration file that is installed in
518 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
519 database credentials in this file.
521 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
523 # icinga2-enable-feature ido-mysql
524 Module 'ido-mysql' was enabled.
525 Make sure to restart Icinga 2 for these changes to take effect.
527 After enabling the ido-mysql feature you have to restart Icinga 2:
529 # /etc/init.d/icinga2 restart
532 ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
534 #### Setting up the PostgreSQL database
536 First of all you have to install the `icinga2-ido-pgsql` package using your
537 distribution's package manager. Once you have done that you can proceed with
538 setting up a PostgreSQL database for Icinga 2:
542 > The Debian packages can optionally create and maintain the database for you
543 > using Debian's `dbconfig` framework. This is the recommended way of setting up
547 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
548 # sudo -u postgres createdb -O icinga -E UTF8 icinga
549 # sudo -u postgres createlang plpgsql icinga
553 > Using PostgreSQL 9.x you can omit the `createlang` command.
555 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
556 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
557 authentication method and restart the postgresql server.
559 # vim /var/lib/pgsql/data/pg_hba.conf
562 local icinga icinga md5
563 host icinga icinga 127.0.0.1/32 md5
564 host icinga icinga ::1/128 md5
566 # "local" is for Unix domain socket connections only
568 # IPv4 local connections:
569 host all all 127.0.0.1/32 ident
570 # IPv6 local connections:
571 host all all ::1/128 ident
573 # /etc/init.d/postgresql restart
576 After creating the database and permissions you can import the Icinga 2 IDO schema
577 using the following command:
579 # export PGPASSWORD=icinga
580 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
582 The schema file location differs by the distribution used:
584 Distribution | Schema Files
585 --------------|---------------------
586 RHEL | `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
587 SUSE | `/usr/share/doc/packages/icinga2-ido-pgsql/schema`
588 Debian/Ubuntu | `/usr/share/icinga2-ido-pgsql/schema`
591 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
593 Check the `schema/upgrade` directory for an incremental schema upgrade file.
594 If there isn't an upgrade file available there's nothing to do.
598 > During pre release status (0.x.y releases) small snippets called for example
599 > `0.0.10.sql` will ship the required schema updates.
601 Apply all database schema upgrade files incrementially.
603 # export PGPASSWORD=icinga
604 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
606 The Icinga 2 IDO module will check for the required database schema version on startup
607 and generate an error message if not satisfied.
609 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
611 The package provides a new configuration file that is installed in
612 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
613 database credentials in this file.
615 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
617 # icinga2-enable-feature ido-pgsql
618 Module 'ido-pgsql' was enabled.
619 Make sure to restart Icinga 2 for these changes to take effect.
621 After enabling the ido-pgsql feature you have to restart Icinga 2:
623 # /etc/init.d/icinga2 restart
626 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
628 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
629 implements a query protocol that lets users query their Icinga instance for
630 status information. It can also be used to send commands.
634 > Only install the Livestatus feature if your web interface or addon requires
635 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
636 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
637 > do not use Livestatus as backend.
639 The Livestatus component that is distributed as part of Icinga 2 is a
640 re-implementation of the Livestatus protocol which is compatible with MK
643 Details on the available tables and attributes with Icinga 2 can be found
644 in the [Livestatus Schema](#schema-livestatus) section.
646 You can enable Livestatus using icinga2-enable-feature:
648 # icinga2-enable-feature livestatus
650 After that you will have to restart Icinga 2:
652 # /etc/init.d/icinga2 restart
654 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
656 In order for queries and commands to work you will need to add your query user
657 (e.g. your web server) to the `icingacmd` group:
659 # usermod -a -G icingacmd www-data
661 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
662 `nagios` if you're using Debian.
664 Change "www-data" to the user you're using to run queries.
666 In order to use the historical tables provided by the livestatus feature (for example, the
667 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
668 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
669 `compat_log_path` configuration attribute.
671 # icinga2-enable-feature compatlog
674 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
676 Icinga 2 is compatible with Icinga 1.x user interfaces by providing additional
677 features required as backends.
679 Furthermore these interfaces (and somewhere in the future an Icinga 2
680 exclusive interface) can be used for the newly created `Icinga Web 2`
683 Some interface features will only work in a limited manner due to
684 [compatibility reasons](#differences-1x-2), other features like the
685 statusmap parents are available by dumping the host dependencies as parents.
686 Special restrictions are noted specifically in the sections below.
690 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
691 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
693 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
695 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
696 is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
697 "command pipe") are also supported. It also supports writing Icinga 1.x
698 log files which are required for the reporting functionality in the Classic UI.
700 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
702 The Icinga package repository has both Debian and RPM packages. You can install
703 the Classic UI using the following packages:
705 Distribution | Packages
706 --------------|---------------------
707 Debian | icinga2-classicui
708 all others | icinga2-classicui-config icinga-gui
710 The Debian packages require additional packages which are provided by the
711 [Debian Monitoring Project](http://www.debmon.org) repository.
713 On all distributions other than Debian you may have to restart both your web
714 server as well as Icinga 2 after installing the Classic UI package.
716 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
719 Distribution | URL | Default Login
720 --------------|--------------------------------------------------------------------------|--------------------------
721 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
722 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
724 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
726 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
727 is an explicit requirement to run `Icinga Web` next to the external command pipe.
728 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
730 #### <a id="installing-icinga-web"></a> Installing Icinga Web
732 The Icinga package repository has both Debian and RPM packages. You can install
733 the Classic UI using the following packages:
735 Distribution | Packages
736 --------------|-------------------------------------
737 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
740 Additionally you need to setup the `icinga_web` database.
742 The Icinga Web RPM packages install the schema files into
743 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
744 The Icinga Web dist tarball ships the schema files in `etc/schema`.
746 On SuSE-based distributions the schema files are installed in
747 `/usr/share/doc/packages/icinga-web/schema`.
749 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
750 Enable that feature, e.g. for MySQL.
752 # icinga2-enable-feature ido-mysql
754 If you've changed your default credentials you may either create a read-only user
755 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
756 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
757 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
759 # vim /etc/icinga-web/conf.d/databases.xml
761 # icinga-web-clearcache
763 Additionally you need to enable the `command` feature:
765 # icinga2-enable-feature command
767 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
768 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
769 to the default used in Icinga 2. Make sure to clear the cache afterwards.
771 # vim /etc/icinga-web/conf.d/access.xml
775 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
779 # icinga-web-clearcache
783 > The path to the Icinga Web `clearcache` script may differ. Please check the
784 > [Icinga Web documentation](https://docs.icinga.org) for details.
786 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
788 Distribution | URL | Default Login
789 --------------|-------------------------------------------------------------|--------------------------
790 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
791 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
794 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
796 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
797 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
798 further instructions.
800 Icinga Web 2 is still under development. Rather than installing it
801 yourself you should consider testing it using the available Vagrant
805 ### <a id="additional-visualization"></a> Additional visualization
807 There are many visualization addons which can be used with Icinga 2.
809 Some of the more popular ones are PNP, inGraph (graphing performance data),
810 Graphite, and NagVis (network maps).
813 ## <a id="configuration-tools"></a> Configuration Tools
815 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
816 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
817 store their configuration in a custom format in their backends (LDAP or RDBMS).
818 Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
819 your favourite configuration tool to export Icinga 2 configuration, please get in
820 touch with their developers.
822 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
823 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
826 ## <a id="running-icinga2"></a> Running Icinga 2
828 ### <a id="init-script"></a> Init Script
830 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
832 # /etc/init.d/icinga2
833 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
835 Command | Description
836 --------------------|------------------------
837 start | The `start` action starts the Icinga 2 daemon.
838 stop | The `stop` action stops the Icinga 2 daemon.
839 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
840 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.
841 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
842 status | The `status` action checks if Icinga 2 is running.
844 By default the Icinga 2 daemon is running as `icinga` user and group
845 using the init script. Using Debian packages the user and group are set to `nagios`
846 for historical reasons.
848 ### <a id="cmdline"></a> Command-line Options
851 icinga2 - The Icinga 2 network monitoring daemon.
854 --help show this help message
855 -V [ --version ] show version information
856 -l [ --library ] arg load a library
857 -I [ --include ] arg add include search directory
858 -D [ --define] args define a constant
859 -c [ --config ] arg parse a configuration file
860 -C [ --validate ] exit after validating the configuration
861 -x [ --debug ] arg enable debugging with severity level specified
862 -d [ --daemonize ] detach from the controlling terminal
863 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
864 in combination with --daemonize)
865 -u [ --user ] arg user to run Icinga as
866 -g [ --group ] arg group to run Icinga as
868 Report bugs at <https://dev.icinga.org/>
869 Icinga home page: <http://www.icinga.org/>
873 Instead of loading libraries using the [`library` config directive](#library)
874 you can also use the `--library` command-line option.
878 [Global constants](#global-constants) can be set using the `--define` command-line option.
880 #### Config Include Path
882 When including files you can specify that the include search path should be
883 checked. You can do this by putting your configuration file name in angle
888 This would cause Icinga 2 to search its include path for the configuration file
889 `test.conf`. By default the installation path for the Icinga Template Library
890 is the only search directory.
892 Using the `--include` command-line option additional search directories can be
897 Using the `--config` option you can specify one or more configuration files.
898 Config files are processed in the order they're specified on the command-line.
900 #### Config Validation
902 The `--validate` option can be used to check if your configuration files
903 contain errors. If any errors are found the exit status is 1, otherwise 0
906 ### <a id="features"></a> Enabling/Disabling Features
908 Icinga 2 provides configuration files for some commonly used features. These
909 are installed in the `/etc/icinga2/features-available` directory and can be
910 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
913 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
914 directory which is included by default in the example configuration file.
916 You can view a list of available feature configuration files:
918 # icinga2-enable-feature
919 Syntax: icinga2-enable-feature <feature>
920 Enables the specified feature.
922 Available features: statusdata
924 Using the `icinga2-enable-feature` command you can enable features:
926 # icinga2-enable-feature statusdata
927 Module 'statusdata' was enabled.
928 Make sure to restart Icinga 2 for these changes to take effect.
930 You can disable features using the `icinga2-disable-feature` command:
932 # icinga2-disable-feature statusdata
933 Module 'statusdata' was disabled.
934 Make sure to restart Icinga 2 for these changes to take effect.
936 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
937 restart Icinga 2. You will need to restart Icinga 2 using the init script
938 after enabling or disabling features.
940 ### <a id="config-validation"></a> Configuration Validation
942 Once you've edited the configuration files make sure to tell Icinga 2 to validate
943 the configuration changes. Icinga 2 will log any configuration error including
944 a hint on the file, the line number and the affected configuration line itself.
946 The following example creates an apply rule without any `assign` condition.
948 apply Service "5872-ping4" {
949 import "test-generic-service"
950 check_command = "ping4"
951 //assign where match("5872-*", host.name)
954 Validate the configuration with the init script option `checkconfig`
956 # /etc/init.d/icinga2 checkconfig
958 or manually passing the `-C` argument:
960 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
962 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: Location:
963 /etc/icinga2/conf.d/tests/5872.conf(5): }
964 /etc/icinga2/conf.d/tests/5872.conf(6):
965 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
967 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
968 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
970 Config error: 'apply' is missing 'assign'
971 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: 1 errors, 0 warnings.
972 Icinga 2 detected configuration errors.
975 ### <a id="config-change-reload"></a> Reload on Configuration Changes
977 Everytime you have changed your configuration you should first tell Icinga 2
978 to [validate](#config-validation). If there are no validation errors you can
979 safely reload the Icinga 2 daemon.
981 # /etc/init.d/icinga2 reload
985 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
986 > which will validate the configuration in a separate process and not stop
987 > the other events like check execution, notifications, etc.
990 ## <a id="vagrant"></a> Vagrant Demo VM
992 The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
993 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
994 version `1.2.x` is required.
996 In order to build the Vagrant VM first you will have to check out
999 $ git clone git://git.icinga.org/icinga2.git
1001 Once you have checked out the Git repository you can build the VM using the
1006 The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
1007 packages from `packages.icinga.org`. The check plugins are installed from
1008 EPEL providing RPMs with sources from the Monitoring Plugins project.
1010 ### <a id="vagrant-demo-guis"></a> Demo GUIs
1012 In addition to installing Icinga 2 the Vagrant puppet modules also install the
1013 Icinga 1.x Classic UI and Icinga Web.
1015 GUI | Url | Credentials
1016 ----------------|----------------------------------------------------------------------|------------------------
1017 Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
1018 Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
1021 ### <a id="vagrant-ssh"></a> SSH Access
1023 You can access the Vagrant VM using SSH:
1027 Alternatively you can use your favorite SSH client:
1030 ----------------|----------------