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
200 command to `hostalive`. If you require a different check command, you can
201 override it in the object definition.
203 The `vars` attribute can be used to define custom attributes which are available
204 for check and notification commands. Most of the templates in the Icinga
205 Template Library require an `address` attribute.
207 The custom attribute `os` is evaluated by the `linux-servers` group in
208 `groups.conf `making the host `localhost` a member.
210 object HostGroup "linux-servers" {
211 display_name = "Linux Servers"
213 assign where host.vars.os == "Linux"
216 A host notification apply rule in `notifications.conf` checks for the custom
217 attribute `sla` being set to `24x7` automatically applying a host notification.
220 * The example notification apply rules.
222 * Only applied if host/service objects have
223 * the custom attribute `sla` set to `24x7`.
226 apply Notification "mail-icingaadmin" to Host {
227 import "mail-host-notification"
229 user_groups = [ "icingaadmins" ]
231 assign where host.vars.sla == "24x7"
234 Now it's time to define services for the host object. Because these checks
235 are only available for the `localhost` host, they are organized below
240 > The directory tree and file organisation is just an example. You are
241 > free to define your own strategy. Just keep in mind to include the
242 > main directories in the [icinga2.conf](#icinga2-conf) file.
244 object Service "disk" {
245 import "generic-service"
247 host_name = "localhost"
248 check_command = "disk"
252 object Service "http" {
253 import "generic-service"
255 host_name = "localhost"
256 check_command = "http"
260 object Service "load" {
261 import "generic-service"
263 host_name = "localhost"
264 check_command = "load"
268 object Service "procs" {
269 import "generic-service"
271 host_name = "localhost"
272 check_command = "procs"
276 object Service "ssh" {
277 import "generic-service"
279 host_name = "localhost"
280 check_command = "ssh"
284 object Service "swap" {
285 import "generic-service"
287 host_name = "localhost"
288 check_command = "swap"
292 object Service "users" {
293 import "generic-service"
295 host_name = "localhost"
296 check_command = "users"
300 object Service "icinga" {
301 import "generic-service"
303 host_name = "localhost"
304 check_command = "icinga"
308 The command object `icinga` for the embedded health check is provided by the
309 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
310 `users` and `disk` are all provided by the plugin check commands which we enabled
311 earlier by including the `itl` and `plugins` configuration file.
313 The Debian packages also ship an additional `apt` service check.
317 > Instead of defining each service object and assigning it to a host object
318 > using the `host_name` attribute rather use the [apply rules](#apply)
319 > simplifying your configuration.
321 There are two generic services applied to all hosts in the host group `linux-servers`
322 and `windows-servers` by default: `ping4` and `ping6`. Host objects without
323 a valid `address` resp. `address6` attribute will be excluded.
325 apply Service "ping4" {
326 import "generic-service"
328 check_command = "ping4"
331 assign where "linux-servers" in host.groups
332 assign where "windows-servers" in host.groups
333 ignore where host.address == ""
336 apply Service "ping6" {
337 import "generic-service"
339 check_command = "ping6"
342 assign where "linux-servers" in host.groups
343 assign where "windows-servers" in host.groups
344 ignore where host.address6 == ""
347 Each of these services has the custom attribute `sla` set to `24x7`. The
348 notification apply rule in `notifications.conf` will automatically apply
349 a service notification matchting this attribute pattern.
351 apply Notification "mail-icingaadmin" to Service {
352 import "mail-service-notification"
354 user_groups = [ "icingaadmins" ]
356 assign where service.vars.sla == "24x7"
359 Don't forget to install the [check plugins](#setting-up-check-plugins) required by the services and
360 their check commands.
362 Further details on the monitoring configuration can be found in the
363 [monitoring basics](#monitoring-basics) chapter.
365 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
368 Icinga 2 does not know how to check external services. The
369 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
370 an extensive set of plugins which can be used with Icinga 2 to check whether
371 services are working properly.
373 The recommended way of installing these standard plugins is to use your
374 distribution's package manager.
378 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
379 > in January 2014. At the time of this writing the packages are still
380 > using the old name.
382 For your convenience here is a list of package names for some of the more
383 popular operating systems/distributions:
385 OS/Distribution | Package Name | Installation Path
386 -----------------------|--------------------|---------------------------
387 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
388 Debian | nagios-plugins | /usr/lib/nagios/plugins
389 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
390 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
392 Depending on which directory your plugins are installed into you may need to
393 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
394 by the service templates contained in the Icinga Template Library to determine
395 where to find the plugin binaries.
397 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
399 For some services you may need additional 'check plugins' which are not provided
400 by the official Monitoring Plugins project.
402 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
403 list of popular community sites which host check plugins:
405 * [MonitoringExchange](https://www.monitoringexchange.org)
406 * [Icinga Wiki](https://wiki.icinga.org)
408 The recommended way of setting up these plugins is to copy them to a common directory
409 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
412 # cp check_snmp_int.pl /opt/plugins
413 # chmod +x /opt/plugins/check_snmp_int.pl
415 # cat /etc/icinga2/constants.conf
417 * This file defines global constants which can be used in
418 * the other configuration files. At a minimum the
419 * PluginDir constant should be defined.
422 const PluginDir = "/usr/lib/nagios/plugins"
423 const CustomPluginDir = "/opt/monitoring"
425 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
426 by trying to run it on the console using whichever user Icinga 2 is running as:
428 # su - icinga -s /bin/bash
429 $ /opt/plugins/check_snmp_int.pl --help
431 Additional libraries may be required for some plugins. Please consult the plugin
432 documentation and/or README for installation instructions.
434 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
435 configuration which can be used in the [Service](#objecttype-service) or
436 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
437 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
439 For further information on your monitoring configuration read the
440 [monitoring basics](#monitoring-basics).
443 ## <a id="configuring-ido"></a> Configuring IDO
445 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
446 configuration and status information into a database. The IDO database is used
447 by a number of projects including Icinga Web.
449 There is a separate module for each database back-end. At present support for
450 both MySQL and PostgreSQL is implemented.
452 Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
453 `1.11.0`. Icinga 2 may require additional features not yet released with
454 Icinga 1.x and therefore require manual upgrade steps during pre-final
459 > Only install the IDO feature if your web interface or reporting tool requires
460 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
461 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
463 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
465 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
467 First of all you have to install the `icinga2-ido-mysql` package using your
468 distribution's package manager. Once you have done that you can proceed with
469 setting up a MySQL database for Icinga 2:
473 > The Debian packages can optionally create and maintain the database for you
474 > using Debian's `dbconfig` framework. This is the recommended way of setting up
479 mysql> CREATE DATABASE icinga;
481 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
486 After creating the database you can import the Icinga 2 IDO schema using the
489 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
491 The schema file location differs by the distribution used:
493 Distribution | Schema Files
494 --------------|---------------------
495 RHEL | `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
496 SUSE | `/usr/share/doc/packages/icinga2-ido-mysql/schema`
497 Debian/Ubuntu | `/usr/share/icinga2-ido-mysql/schema`
499 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
501 Check the `schema/upgrade` directory for an incremental schema upgrade file.
502 If there isn't an upgrade file available there's nothing to do.
506 > During pre release status (0.x.y releases) small snippets called for example
507 > `0.0.10.sql` will ship the required schema updates.
509 Apply all database schema upgrade files incrementially.
511 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
513 The Icinga 2 IDO module will check for the required database schema version on startup
514 and generate an error message if not satisfied.
516 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
518 The package provides a new configuration file that is installed in
519 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
520 database credentials in this file.
522 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
524 # icinga2-enable-feature ido-mysql
525 Module 'ido-mysql' was enabled.
526 Make sure to restart Icinga 2 for these changes to take effect.
528 After enabling the ido-mysql feature you have to restart Icinga 2:
530 # /etc/init.d/icinga2 restart
533 ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
535 #### Setting up the PostgreSQL database
537 First of all you have to install the `icinga2-ido-pgsql` package using your
538 distribution's package manager. Once you have done that you can proceed with
539 setting up a PostgreSQL database for Icinga 2:
543 > The Debian packages can optionally create and maintain the database for you
544 > using Debian's `dbconfig` framework. This is the recommended way of setting up
548 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
549 # sudo -u postgres createdb -O icinga -E UTF8 icinga
550 # sudo -u postgres createlang plpgsql icinga
554 > Using PostgreSQL 9.x you can omit the `createlang` command.
556 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
557 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
558 authentication method and restart the postgresql server.
560 # vim /var/lib/pgsql/data/pg_hba.conf
563 local icinga icinga md5
564 host icinga icinga 127.0.0.1/32 md5
565 host icinga icinga ::1/128 md5
567 # "local" is for Unix domain socket connections only
569 # IPv4 local connections:
570 host all all 127.0.0.1/32 ident
571 # IPv6 local connections:
572 host all all ::1/128 ident
574 # /etc/init.d/postgresql restart
577 After creating the database and permissions you can import the Icinga 2 IDO schema
578 using the following command:
580 # export PGPASSWORD=icinga
581 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
583 The schema file location differs by the distribution used:
585 Distribution | Schema Files
586 --------------|---------------------
587 RHEL | `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
588 SUSE | `/usr/share/doc/packages/icinga2-ido-pgsql/schema`
589 Debian/Ubuntu | `/usr/share/icinga2-ido-pgsql/schema`
592 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
594 Check the `schema/upgrade` directory for an incremental schema upgrade file.
595 If there isn't an upgrade file available there's nothing to do.
599 > During pre release status (0.x.y releases) small snippets called for example
600 > `0.0.10.sql` will ship the required schema updates.
602 Apply all database schema upgrade files incrementially.
604 # export PGPASSWORD=icinga
605 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
607 The Icinga 2 IDO module will check for the required database schema version on startup
608 and generate an error message if not satisfied.
610 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
612 The package provides a new configuration file that is installed in
613 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
614 database credentials in this file.
616 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
618 # icinga2-enable-feature ido-pgsql
619 Module 'ido-pgsql' was enabled.
620 Make sure to restart Icinga 2 for these changes to take effect.
622 After enabling the ido-pgsql feature you have to restart Icinga 2:
624 # /etc/init.d/icinga2 restart
627 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
629 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
630 implements a query protocol that lets users query their Icinga instance for
631 status information. It can also be used to send commands.
635 > Only install the Livestatus feature if your web interface or addon requires
636 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
637 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
638 > do not use Livestatus as backend.
640 The Livestatus component that is distributed as part of Icinga 2 is a
641 re-implementation of the Livestatus protocol which is compatible with MK
644 Details on the available tables and attributes with Icinga 2 can be found
645 in the [Livestatus Schema](#schema-livestatus) section.
647 You can enable Livestatus using icinga2-enable-feature:
649 # icinga2-enable-feature livestatus
651 After that you will have to restart Icinga 2:
653 # /etc/init.d/icinga2 restart
655 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
657 In order for queries and commands to work you will need to add your query user
658 (e.g. your web server) to the `icingacmd` group:
660 # usermod -a -G icingacmd www-data
662 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
663 `nagios` if you're using Debian.
665 Change "www-data" to the user you're using to run queries.
667 In order to use the historical tables provided by the livestatus feature (for example, the
668 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
669 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
670 `compat_log_path` configuration attribute.
672 # icinga2-enable-feature compatlog
675 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
677 Icinga 2 is compatible with Icinga 1.x user interfaces by providing additional
678 features required as backends.
680 Furthermore these interfaces (and somewhere in the future an Icinga 2
681 exclusive interface) can be used for the newly created `Icinga Web 2`
684 Some interface features will only work in a limited manner due to
685 [compatibility reasons](#differences-1x-2), other features like the
686 statusmap parents are available by dumping the host dependencies as parents.
687 Special restrictions are noted specifically in the sections below.
691 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
692 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
694 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
696 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
697 is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
698 "command pipe") are also supported. It also supports writing Icinga 1.x
699 log files which are required for the reporting functionality in the Classic UI.
701 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
703 The Icinga package repository has both Debian and RPM packages. You can install
704 the Classic UI using the following packages:
706 Distribution | Packages
707 --------------|---------------------
708 Debian | icinga2-classicui
709 all others | icinga2-classicui-config icinga-gui
711 The Debian packages require additional packages which are provided by the
712 [Debian Monitoring Project](http://www.debmon.org) repository.
714 On all distributions other than Debian you may have to restart both your web
715 server as well as Icinga 2 after installing the Classic UI package.
717 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
720 Distribution | URL | Default Login
721 --------------|--------------------------------------------------------------------------|--------------------------
722 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
723 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
725 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
727 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
728 is an explicit requirement to run `Icinga Web` next to the external command pipe.
729 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
731 #### <a id="installing-icinga-web"></a> Installing Icinga Web
733 The Icinga package repository has both Debian and RPM packages. You can install
734 the Classic UI using the following packages:
736 Distribution | Packages
737 --------------|-------------------------------------
738 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
741 Additionally you need to setup the `icinga_web` database.
743 The Icinga Web RPM packages install the schema files into
744 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
745 The Icinga Web dist tarball ships the schema files in `etc/schema`.
747 On SuSE-based distributions the schema files are installed in
748 `/usr/share/doc/packages/icinga-web/schema`.
750 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
751 Enable that feature, e.g. for MySQL.
753 # icinga2-enable-feature ido-mysql
755 If you've changed your default credentials you may either create a read-only user
756 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
757 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
758 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
760 # vim /etc/icinga-web/conf.d/databases.xml
762 # icinga-web-clearcache
764 Additionally you need to enable the `command` feature:
766 # icinga2-enable-feature command
768 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
769 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
770 to the default used in Icinga 2. Make sure to clear the cache afterwards.
772 # vim /etc/icinga-web/conf.d/access.xml
776 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
780 # icinga-web-clearcache
784 > The path to the Icinga Web `clearcache` script may differ. Please check the
785 > [Icinga Web documentation](https://docs.icinga.org) for details.
787 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
789 Distribution | URL | Default Login
790 --------------|-------------------------------------------------------------|--------------------------
791 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
792 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
795 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
797 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
798 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
799 further instructions.
801 Icinga Web 2 is still under development. Rather than installing it
802 yourself you should consider testing it using the available Vagrant
806 ### <a id="additional-visualization"></a> Additional visualization
808 There are many visualization addons which can be used with Icinga 2.
810 Some of the more popular ones are PNP, inGraph (graphing performance data),
811 Graphite, and NagVis (network maps).
814 ## <a id="configuration-tools"></a> Configuration Tools
816 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
817 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
818 store their configuration in a custom format in their backends (LDAP or RDBMS).
819 Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
820 your favourite configuration tool to export Icinga 2 configuration, please get in
821 touch with their developers.
823 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
824 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
826 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
828 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano`editors.
829 The RHEL, SUSE and Debian package `icinga2-common` install these files into
830 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
832 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
834 Create a new local vim configuration storage, if not already existing.
835 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
839 $ mkdir -p $PREFIX/{syntax,ftdetect}
840 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
841 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
845 $ vim /etc/icinga2/conf.d/templates.conf
847 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
849 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
850 and copy the provided `icinga2.nanorc` into it.
852 $ cp /etc/nanorc ~/.nanorc
855 # cp icinga2.nanorc /etc/nano/
857 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
862 include "/etc/nano/icinga2.nanorc"
866 $ nano /etc/icinga2/conf.d/templates.conf
869 ## <a id="running-icinga2"></a> Running Icinga 2
871 ### <a id="init-script"></a> Init Script
873 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
875 # /etc/init.d/icinga2
876 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
878 Command | Description
879 --------------------|------------------------
880 start | The `start` action starts the Icinga 2 daemon.
881 stop | The `stop` action stops the Icinga 2 daemon.
882 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
883 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.
884 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
885 status | The `status` action checks if Icinga 2 is running.
887 By default the Icinga 2 daemon is running as `icinga` user and group
888 using the init script. Using Debian packages the user and group are set to `nagios`
889 for historical reasons.
891 ### <a id="cmdline"></a> Command-line Options
894 icinga2 - The Icinga 2 network monitoring daemon.
897 --help show this help message
898 -V [ --version ] show version information
899 -l [ --library ] arg load a library
900 -I [ --include ] arg add include search directory
901 -D [ --define] args define a constant
902 -c [ --config ] arg parse a configuration file
903 -C [ --validate ] exit after validating the configuration
904 -x [ --debug ] arg enable debugging with severity level specified
905 -d [ --daemonize ] detach from the controlling terminal
906 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
907 in combination with --daemonize)
908 -u [ --user ] arg user to run Icinga as
909 -g [ --group ] arg group to run Icinga as
911 Report bugs at <https://dev.icinga.org/>
912 Icinga home page: <http://www.icinga.org/>
916 Instead of loading libraries using the [`library` config directive](#library)
917 you can also use the `--library` command-line option.
921 [Global constants](#global-constants) can be set using the `--define` command-line option.
923 #### Config Include Path
925 When including files you can specify that the include search path should be
926 checked. You can do this by putting your configuration file name in angle
931 This would cause Icinga 2 to search its include path for the configuration file
932 `test.conf`. By default the installation path for the Icinga Template Library
933 is the only search directory.
935 Using the `--include` command-line option additional search directories can be
940 Using the `--config` option you can specify one or more configuration files.
941 Config files are processed in the order they're specified on the command-line.
943 #### Config Validation
945 The `--validate` option can be used to check if your configuration files
946 contain errors. If any errors are found the exit status is 1, otherwise 0
949 ### <a id="features"></a> Enabling/Disabling Features
951 Icinga 2 provides configuration files for some commonly used features. These
952 are installed in the `/etc/icinga2/features-available` directory and can be
953 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
956 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
957 directory which is included by default in the example configuration file.
959 You can view a list of available feature configuration files:
961 # icinga2-enable-feature
962 Syntax: icinga2-enable-feature <feature>
963 Enables the specified feature.
965 Available features: statusdata
967 Using the `icinga2-enable-feature` command you can enable features:
969 # icinga2-enable-feature statusdata
970 Module 'statusdata' was enabled.
971 Make sure to restart Icinga 2 for these changes to take effect.
973 You can disable features using the `icinga2-disable-feature` command:
975 # icinga2-disable-feature statusdata
976 Module 'statusdata' was disabled.
977 Make sure to restart Icinga 2 for these changes to take effect.
979 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
980 restart Icinga 2. You will need to restart Icinga 2 using the init script
981 after enabling or disabling features.
983 ### <a id="config-validation"></a> Configuration Validation
985 Once you've edited the configuration files make sure to tell Icinga 2 to validate
986 the configuration changes. Icinga 2 will log any configuration error including
987 a hint on the file, the line number and the affected configuration line itself.
989 The following example creates an apply rule without any `assign` condition.
991 apply Service "5872-ping4" {
992 import "test-generic-service"
993 check_command = "ping4"
994 //assign where match("5872-*", host.name)
997 Validate the configuration with the init script option `checkconfig`
999 # /etc/init.d/icinga2 checkconfig
1001 or manually passing the `-C` argument:
1003 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
1005 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: Location:
1006 /etc/icinga2/conf.d/tests/5872.conf(5): }
1007 /etc/icinga2/conf.d/tests/5872.conf(6):
1008 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
1010 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
1011 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
1013 Config error: 'apply' is missing 'assign'
1014 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: 1 errors, 0 warnings.
1015 Icinga 2 detected configuration errors.
1018 ### <a id="config-change-reload"></a> Reload on Configuration Changes
1020 Everytime you have changed your configuration you should first tell Icinga 2
1021 to [validate](#config-validation). If there are no validation errors you can
1022 safely reload the Icinga 2 daemon.
1024 # /etc/init.d/icinga2 reload
1028 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
1029 > which will validate the configuration in a separate process and not stop
1030 > the other events like check execution, notifications, etc.
1033 ## <a id="vagrant"></a> Vagrant Demo VM
1035 The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
1036 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
1037 version `1.2.x` is required.
1039 In order to build the Vagrant VM first you will have to check out
1042 $ git clone git://git.icinga.org/icinga2.git
1044 Once you have checked out the Git repository you can build the VM using the
1049 The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
1050 packages from `packages.icinga.org`. The check plugins are installed from
1051 EPEL providing RPMs with sources from the Monitoring Plugins project.
1053 ### <a id="vagrant-demo-guis"></a> Demo GUIs
1055 In addition to installing Icinga 2 the Vagrant puppet modules also install the
1056 Icinga 1.x Classic UI and Icinga Web.
1058 GUI | Url | Credentials
1059 ----------------|----------------------------------------------------------------------|------------------------
1060 Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
1061 Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
1064 ### <a id="vagrant-ssh"></a> SSH Access
1066 You can access the Vagrant VM using SSH:
1070 Alternatively you can use your favorite SSH client:
1073 ----------------|----------------