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 of all 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 In case you're running a distribution for which Icinga 2 packages are
45 not yet available you will have 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 `linux-server` 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
366 On its own Icinga 2 does not know how to check external services. The
367 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
368 an extensive set of plugins which can be used with Icinga 2 to check whether
369 services are working properly.
371 The recommended way of installing these standard plugins is to use your
372 distribution's package manager.
376 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
377 > in January 2014. At the time of this writing the packages are still
378 > using the old name.
380 For your convenience here is a list of package names for some of the more
381 popular operating systems/distributions:
383 OS/Distribution | Package Name | Installation Path
384 -----------------------|--------------------|---------------------------
385 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
386 Debian | nagios-plugins | /usr/lib/nagios/plugins
387 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
388 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
390 Depending on which directory your plugins are installed into you may need to
391 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
392 by the service templates contained in the Icinga Template Library to determine
393 where to find the plugin binaries.
395 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
397 For some services you may need additional check plugins which are not provided
398 by the official Monitoring Plugins project.
400 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
401 list of popular community sites which host check plugins:
403 * [MonitoringExchange](https://www.monitoringexchange.org)
404 * [Icinga Wiki](https://wiki.icinga.org)
406 The recommended way of setting up these plugins is to copy them to a common directory
407 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
410 # cp check_snmp_int.pl /opt/plugins
411 # chmod +x /opt/plugins/check_snmp_int.pl
413 # cat /etc/icinga2/constants.conf
415 * This file defines global constants which can be used in
416 * the other configuration files. At a minimum the
417 * PluginDir constant should be defined.
420 const PluginDir = "/usr/lib/nagios/plugins"
421 const CustomPluginDir = "/opt/monitoring"
423 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
424 by trying to run it on the console using whichever user Icinga 2 is running as:
426 # su - icinga -s /bin/bash
427 $ /opt/plugins/check_snmp_int.pl --help
429 Additional libraries may be required for some plugins. Please consult the plugin
430 documentation and/or README for installation instructions.
432 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
433 configuration which can be used in the [Service](#objecttype-service) or
434 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
435 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
437 For further information on your monitoring configuration read the
438 [monitoring basics](#monitoring-basics).
441 ## <a id="configuring-ido"></a> Configuring IDO
443 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
444 configuration and status information into a database. The IDO database is used
445 by a number of projects including Icinga Web.
447 There is a separate module for each database back-end. At present support for
448 both MySQL and PostgreSQL is implemented.
450 Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
451 `1.11.0`. Icinga 2 may require additional features not yet released with
452 Icinga 1.x and therefore require manual upgrade steps during pre-final
457 > Only install the IDO feature if your web interface or reporting tool requires
458 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
459 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
461 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
463 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
465 First of all you have to install the `icinga2-ido-mysql` package using your
466 distribution's package manager. Once you have done that you can proceed with
467 setting up a MySQL database for Icinga 2:
471 > The Debian packages can optionally create and maintain the database for you
472 > using Debian's `dbconfig` framework. This is the recommended way of setting up
477 mysql> CREATE DATABASE icinga;
479 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
484 After creating the database you can import the Icinga 2 IDO schema using the
487 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
489 The schema file location differs by the distribution used:
491 Distribution | Schema Files
492 --------------|---------------------
493 RHEL | `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
494 SUSE | `/usr/share/doc/packages/icinga2-ido-mysql/schema`
495 Debian/Ubuntu | `/usr/share/icinga2-ido-mysql/schema`
497 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
499 Check the `schema/upgrade` directory for an incremental schema upgrade file.
500 If there isn't an upgrade file available there's nothing to do.
504 > During pre release status (0.x.y releases) small snippets called for example
505 > `0.0.10.sql` will ship the required schema updates.
507 Apply all database schema upgrade files incrementially.
509 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
511 The Icinga 2 IDO module will check for the required database schema version on startup
512 and generate an error message if not satisfied.
514 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
516 The package provides a new configuration file that is installed in
517 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
518 database credentials in this file.
520 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
522 # icinga2-enable-feature ido-mysql
523 Module 'ido-mysql' was enabled.
524 Make sure to restart Icinga 2 for these changes to take effect.
526 After enabling the ido-mysql feature you have to restart Icinga 2:
528 # /etc/init.d/icinga2 restart
531 ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
533 #### Setting up the PostgreSQL database
535 First of all you have to install the `icinga2-ido-pgsql` package using your
536 distribution's package manager. Once you have done that you can proceed with
537 setting up a PostgreSQL database for Icinga 2:
541 > The Debian packages can optionally create and maintain the database for you
542 > using Debian's `dbconfig` framework. This is the recommended way of setting up
546 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
547 # sudo -u postgres createdb -O icinga -E UTF8 icinga
548 # sudo -u postgres createlang plpgsql icinga
552 > Using PostgreSQL 9.x you can omit the `createlang` command.
554 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
555 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
556 authentication method and restart the postgresql server.
558 # vim /var/lib/pgsql/data/pg_hba.conf
561 local icinga icinga md5
562 host icinga icinga 127.0.0.1/32 md5
563 host icinga icinga ::1/128 md5
565 # "local" is for Unix domain socket connections only
567 # IPv4 local connections:
568 host all all 127.0.0.1/32 ident
569 # IPv6 local connections:
570 host all all ::1/128 ident
572 # /etc/init.d/postgresql restart
575 After creating the database and permissions you can import the Icinga 2 IDO schema
576 using the following command:
578 # export PGPASSWORD=icinga
579 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
581 The schema file location differs by the distribution used:
583 Distribution | Schema Files
584 --------------|---------------------
585 RHEL | `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
586 SUSE | `/usr/share/doc/packages/icinga2-ido-pgsql/schema`
587 Debian/Ubuntu | `/usr/share/icinga2-ido-pgsql/schema`
590 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
592 Check the `schema/upgrade` directory for an incremental schema upgrade file.
593 If there isn't an upgrade file available there's nothing to do.
597 > During pre release status (0.x.y releases) small snippets called for example
598 > `0.0.10.sql` will ship the required schema updates.
600 Apply all database schema upgrade files incrementially.
602 # export PGPASSWORD=icinga
603 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
605 The Icinga 2 IDO module will check for the required database schema version on startup
606 and generate an error message if not satisfied.
608 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
610 The package provides a new configuration file that is installed in
611 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
612 database credentials in this file.
614 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
616 # icinga2-enable-feature ido-pgsql
617 Module 'ido-pgsql' was enabled.
618 Make sure to restart Icinga 2 for these changes to take effect.
620 After enabling the ido-pgsql feature you have to restart Icinga 2:
622 # /etc/init.d/icinga2 restart
625 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
627 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
628 implements a query protocol that lets users query their Icinga instance for
629 status information. It can also be used to send commands.
633 > Only install the Livestatus feature if your web interface or addon requires
634 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
635 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
636 > do not use Livestatus as backend.
638 The Livestatus component that is distributed as part of Icinga 2 is a
639 re-implementation of the Livestatus protocol which is compatible with MK
642 Details on the available tables and attributes with Icinga 2 can be found
643 in the [Livestatus Schema](#schema-livestatus) section.
645 You can enable Livestatus using icinga2-enable-feature:
647 # icinga2-enable-feature livestatus
649 After that you will have to restart Icinga 2:
651 # /etc/init.d/icinga2 restart
653 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
655 In order for queries and commands to work you will need to add your query user
656 (e.g. your web server) to the `icingacmd` group:
658 # usermod -a -G icingacmd www-data
660 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
661 `nagios` if you're using Debian.
663 Change "www-data" to the user you're using to run queries.
665 In order to use the historical tables provided by the livestatus feature (for example, the
666 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
667 are expected in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path`
668 configuration attribute.
670 # icinga2-enable-feature compatlog
673 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
675 Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
676 features required as backends.
678 Furthermore these interfaces (and somewhere in the future an Icinga 2
679 exclusive interface) can be used for the newly created `Icinga Web 2`
682 Some interface features will only work in a limited manner due to
683 [compatibility reasons](#differences-1x-2), other features like the
684 statusmap parents are available dumping the host dependencies as parents.
685 Special restrictions are noted specifically in the sections below.
689 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
690 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
692 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
694 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
695 is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
696 "command pipe") are also supported. It also supports writing Icinga 1.x
697 log files which are required for the reporting functionality in the Classic UI.
699 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
701 The Icinga package repository has both Debian and RPM packages. You can install
702 the Classic UI using the following packages:
704 Distribution | Packages
705 --------------|---------------------
706 Debian | icinga2-classicui
707 all others | icinga2-classicui-config icinga-gui
709 The Debian packages require additional packages which are provided by the
710 [Debian Monitoring Project](http://www.debmon.org) repository.
712 On all distributions other than Debian you may have to restart both your web
713 server as well as Icinga 2 after installing the Classic UI package.
715 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
718 Distribution | URL | Default Login
719 --------------|--------------------------------------------------------------------------|--------------------------
720 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
721 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
723 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
725 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
726 is an explicit requirement to run `Icinga Web` next to the external command pipe.
727 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
729 #### <a id="installing-icinga-web"></a> Installing Icinga Web
731 The Icinga package repository has both Debian and RPM packages. You can install
732 the Classic UI using the following packages:
734 Distribution | Packages
735 --------------|-------------------------------------
736 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
739 Additionally you need to setup the `icinga_web` database.
741 The Icinga Web RPM packages install the schema files into
742 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
743 The Icinga Web dist tarball ships the schema files in `etc/schema`.
745 On SuSE-based distributions the schema files are installed in
746 `/usr/share/doc/packages/icinga-web/schema`.
748 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
749 Enable that feature, e.g. for MySQL.
751 # icinga2-enable-feature ido-mysql
753 If you've changed your default credentials you may either create a read-only user
754 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
755 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
756 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
758 # vim /etc/icinga-web/conf.d/databases.xml
760 # icinga-web-clearcache
762 Additionally you need to enable the `command` feature:
764 # icinga2-enable-feature command
766 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
767 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
768 to the default used in Icinga 2. Make sure to clear the cache afterwards.
770 # vim /etc/icinga-web/conf.d/access.xml
774 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
778 # icinga-web-clearcache
782 > The path to the Icinga Web `clearcache` script may differ. Please check the
783 > [Icinga Web documentation](https://docs.icinga.org) for details.
785 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
787 Distribution | URL | Default Login
788 --------------|-------------------------------------------------------------|--------------------------
789 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
790 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
793 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
795 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
796 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
797 further instructions.
799 Icinga Web 2 is still under development. Rather than installing it
800 yourself you should consider testing it using the available Vagrant
804 ### <a id="additional-visualization"></a> Additional visualization
806 There are many visualization addons which can be used with Icinga 2.
808 Some of the more popular ones are PNP, inGraph (graphing performance data),
809 Graphite, and NagVis (network maps).
812 ## <a id="configuration-tools"></a> Configuration Tools
814 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
815 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
816 store their configuration in a custom format in their backends (LDAP or RDBMS).
817 Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
818 your favourite configuration tool to export Icinga 2 configuration, please get in
819 touch with their developers.
821 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
822 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
825 ## <a id="running-icinga2"></a> Running Icinga 2
827 ### <a id="init-script"></a> Init Script
829 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
831 # /etc/init.d/icinga2
832 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
834 Command | Description
835 --------------------|------------------------
836 start | The `start` action starts the Icinga 2 daemon.
837 stop | The `stop` action stops the Icinga 2 daemon.
838 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
839 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.
840 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
841 status | The `status` action checks if Icinga 2 is running.
843 By default the Icinga 2 daemon is running as `icinga` user and group
844 using the init script. Using Debian packages the user and group are set to `nagios`
845 for historical reasons.
847 ### <a id="cmdline"></a> Command-line Options
850 icinga2 - The Icinga 2 network monitoring daemon.
853 --help show this help message
854 -V [ --version ] show version information
855 -l [ --library ] arg load a library
856 -I [ --include ] arg add include search directory
857 -D [ --define] args define a constant
858 -c [ --config ] arg parse a configuration file
859 -C [ --validate ] exit after validating the configuration
860 -x [ --debug ] arg enable debugging with severity level specified
861 -d [ --daemonize ] detach from the controlling terminal
862 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
863 in combination with --daemonize)
864 -u [ --user ] arg user to run Icinga as
865 -g [ --group ] arg group to run Icinga as
867 Report bugs at <https://dev.icinga.org/>
868 Icinga home page: <http://www.icinga.org/>
872 Instead of loading libraries using the [`library` config directive](#library)
873 you can also use the `--library` command-line option.
877 [Global constants](#global-constants) can be set using the `--define` command-line option.
879 #### Config Include Path
881 When including files you can specify that the include search path should be
882 checked. You can do this by putting your configuration file name in angle
887 This would cause Icinga 2 to search its include path for the configuration file
888 `test.conf`. By default the installation path for the Icinga Template Library
889 is the only search directory.
891 Using the `--include` command-line option additional search directories can be
896 Using the `--config` option you can specify one or more configuration files.
897 Config files are processed in the order they're specified on the command-line.
899 #### Config Validation
901 The `--validate` option can be used to check if your configuration files
902 contain errors. If any errors are found the exit status is 1, otherwise 0
905 ### <a id="features"></a> Enabling/Disabling Features
907 Icinga 2 provides configuration files for some commonly used features. These
908 are installed in the `/etc/icinga2/features-available` directory and can be
909 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
912 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
913 directory which is included by default in the example configuration file.
915 You can view a list of available feature configuration files:
917 # icinga2-enable-feature
918 Syntax: icinga2-enable-feature <feature>
919 Enables the specified feature.
921 Available features: statusdata
923 Using the `icinga2-enable-feature` command you can enable features:
925 # icinga2-enable-feature statusdata
926 Module 'statusdata' was enabled.
927 Make sure to restart Icinga 2 for these changes to take effect.
929 You can disable features using the `icinga2-disable-feature` command:
931 # icinga2-disable-feature statusdata
932 Module 'statusdata' was disabled.
933 Make sure to restart Icinga 2 for these changes to take effect.
935 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
936 restart Icinga 2. You will need to restart Icinga 2 using the init script
937 after enabling or disabling features.
939 ### <a id="config-validation"></a> Configuration Validation
941 Once you've edited the configuration files make sure to tell Icinga 2 to validate
942 the configuration changes. Icinga 2 will log any configuration error including
943 a hint on the file, the line number and the affected configuration line itself.
945 The following example creates an apply rule without any `assign` condition.
947 apply Service "5872-ping4" {
948 import "test-generic-service"
949 check_command = "ping4"
950 //assign where match("5872-*", host.name)
953 Validate the configuration with the init script option `checkconfig`
955 # /etc/init.d/icinga2 checkconfig
957 or manually passing the `-C` argument:
959 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
961 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: Location:
962 /etc/icinga2/conf.d/tests/5872.conf(5): }
963 /etc/icinga2/conf.d/tests/5872.conf(6):
964 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
966 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
967 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
969 Config error: 'apply' is missing 'assign'
970 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: 1 errors, 0 warnings.
971 Icinga 2 detected configuration errors.
974 ### <a id="config-change-reload"></a> Reload on Configuration Changes
976 Everytime you have changed your configuration you should first tell Icinga 2
977 to [validate](#config-validation). If there are no validation errors you can
978 safely reload the Icinga 2 daemon.
980 # /etc/init.d/icinga2 reload
984 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
985 > which will validate the configuration in a separate process and not stop
986 > the other events like check execution, notifications, etc.
989 ## <a id="vagrant"></a> Vagrant Demo VM
991 The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
992 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
993 version `1.2.x` is required.
995 In order to build the Vagrant VM first you will have to check out
998 $ git clone git://git.icinga.org/icinga2.git
1000 Once you have checked out the Git repository you can build the VM using the
1005 The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
1006 packages from `packages.icinga.org`. The check plugins are installed from
1007 EPEL providing RPMs with sources from the Monitoring Plugins project.
1009 ### <a id="vagrant-demo-guis"></a> Demo GUIs
1011 In addition to installing Icinga 2 the Vagrant puppet modules also install the
1012 Icinga 1.x Classic UI and Icinga Web.
1014 GUI | Url | Credentials
1015 ----------------|----------------------------------------------------------------------|------------------------
1016 Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
1017 Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
1020 ### <a id="vagrant-ssh"></a> SSH Access
1022 You can access the Vagrant VM using SSH:
1026 Alternatively you can use your favorite SSH client:
1029 ----------------|----------------