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 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
9 First of all you will have to install Icinga 2. The preferred way of doing this
10 is to use the official Debian or RPM package repositories depending on which
11 operating system and distribution you are running.
13 Distribution | Repository URL
14 ------------------------|---------------------------
15 Debian | http://packages.icinga.org/debian/
16 Ubuntu | http://packages.icinga.org/ubuntu/
17 RHEL/CentOS | http://packages.icinga.org/epel/
18 OpenSUSE | http://packages.icinga.org/openSUSE/
19 SLES | http://packages.icinga.org/SUSE/
21 Packages for distributions other than the ones listed above may also be
22 available. Please check http://packages.icinga.org/ to see if packages
23 are available for your favourite distribution.
25 The packages for RHEL/CentOS 5 depend on other packages which are distributed
26 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
27 make sure to enable this repository.
29 You can install Icinga 2 by using your distribution's package manager
30 to install the `icinga2` package.
32 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
33 `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
35 Some parts of Icinga 2's functionality are available as separate packages:
38 ------------------------|--------------------------------
39 icinga2-ido-mysql | IDO provider module for MySQL
40 icinga2-ido-pgsql | IDO provider module for PostgreSQL
42 In case you're running a distribution for which Icinga 2 packages are
43 not yet available you will have to use the release tarball which you
44 can download from the [Icinga website](https://www.icinga.org/). The
45 release tarballs contain an `INSTALL` file with further instructions.
48 ### <a id="installation-paths"></a> Installation Paths
50 By default Icinga 2 uses the following files and directories:
53 ------------------------------------|------------------------------------
54 /etc/icinga2 | Contains Icinga 2 configuration files.
55 /etc/init.d/icinga2 | The Icinga 2 init script.
56 /usr/bin/icinga2-* | Migration and certificate build scripts.
57 /usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts.
58 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
59 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
60 /var/run/icinga2 | PID file.
61 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
62 /var/cache/icinga2 | status.dat/objects.cache.
63 /var/spool/icinga2 | Used for performance data spool files.
64 /var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
65 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
67 ### <a id="icinga2-conf"></a> icinga2.conf
69 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
71 Here's a brief description of the example configuration:
74 * Icinga 2 configuration file
75 * - this is where you define settings for the Icinga application including
76 * which hosts/services to check.
78 * For an overview of all available configuration options please refer
79 * to the documentation that is distributed as part of Icinga 2.
82 Icinga 2 supports [C/C++-style comments](#comments).
85 * The constants.conf defines global constants.
87 include "constants.conf"
89 The `include` directive can be used to include other files.
92 * The zones.conf defines zones for a cluster setup.
93 * Not required for single instance setups.
98 * The Icinga Template Library (ITL) provides a number of useful templates
99 * and command definitions.
100 * Common monitoring plugin command definitions are included separately.
106 * The features-available directory contains a number of configuration
107 * files for features which can be enabled and disabled using the
108 * icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
109 * and removing symbolic links in the features-enabled directory.
111 include "features-enabled/*.conf"
113 This `include` directive takes care of including the configuration files for all
114 the features which have been enabled with `icinga2-enable-feature`. See
115 [Enabling/Disabling Features](#features) for more details.
118 * Although in theory you could define all your objects in this file
119 * the preferred way is to create separate directories and files in the conf.d
120 * directory. Each of these files must have the file extension ".conf".
122 include_recursive "conf.d"
124 You can put your own configuration files in the `conf.d` directory. This
125 directive makes sure that all of your own configuration files are included.
127 ### <a id="constants-conf"></a> constants.conf
129 The `constants.conf` configuration file can be used to define global constants:
132 * This file defines global constants which can be used in
133 * the other configuration files.
136 /* The directory which contains the plugins from the Monitoring Plugins project. */
137 const PluginDir = "/usr/lib/nagios/plugins"
139 /* Our local instance name. This should be the common name from the API certificate */
140 const NodeName = "localhost"
142 /* Our local zone name. */
143 const ZoneName = NodeName
145 ### <a id="zones-conf"></a> zones.conf
147 The `zones.conf` configuration file can be used to configure `Endpoint` and `Zone` objects
148 required for a [distributed zone setup](#distributed-monitoring-high-availability). By default
149 a local dummy zone is defined based on the `NodeName` constant defined in
150 [constants.conf](#constants-conf).
154 > Not required for single instance installations.
157 ### <a id="localhost-conf"></a> localhost.conf
159 The `conf.d/localhost.conf` file contains our first host definition:
162 * A host definition. You can create your own configuration files
163 * in the conf.d directory (e.g. one per host). By default all *.conf
164 * files in this directory are included.
167 object Host "localhost" {
168 import "generic-host"
170 address = "127.0.0.1"
177 This defines the host `localhost`. The `import` keyword is used to import
178 the `linux-server` template which takes care of setting up the host check
181 The `vars` attribute can be used to define custom attributes which are available
182 for check and notification commands. Most of the templates in the Icinga
183 Template Library require an `address` attribute.
185 The custom attribute `os` is evaluated by the `linux-servers` group in
186 `groups.conf `making the host `localhost` a member.
188 object HostGroup "linux-servers" {
189 display_name = "Linux Servers"
191 assign where host.vars.os == "Linux"
194 A host notification apply rule in `notifications.conf` checks for the custom
195 attribute `sla` being set to `24x7` automatically applying a host notification.
198 * The example notification apply rules.
200 * Only applied if host/service objects have
201 * the custom attribute `sla` set to `24x7`.
204 apply Notification "mail-icingaadmin" to Host {
205 import "mail-host-notification"
207 user_groups = [ "icingaadmins" ]
209 assign where host.vars.sla == "24x7"
212 Now it's time to define services for the host object. Because these checks
213 are only available for the `localhost` host, they are organized below
218 > The directory tree and file organisation is just an example. You are
219 > free to define your own strategy. Just keep in mind to include the
220 > main directories in the [icinga2.conf](#icinga2-conf) file.
222 object Service "disk" {
223 import "generic-service"
225 host_name = "localhost"
226 check_command = "disk"
230 object Service "http" {
231 import "generic-service"
233 host_name = "localhost"
234 check_command = "http"
238 object Service "load" {
239 import "generic-service"
241 host_name = "localhost"
242 check_command = "load"
246 object Service "procs" {
247 import "generic-service"
249 host_name = "localhost"
250 check_command = "procs"
254 object Service "ssh" {
255 import "generic-service"
257 host_name = "localhost"
258 check_command = "ssh"
262 object Service "swap" {
263 import "generic-service"
265 host_name = "localhost"
266 check_command = "swap"
270 object Service "users" {
271 import "generic-service"
273 host_name = "localhost"
274 check_command = "users"
278 object Service "icinga" {
279 import "generic-service"
281 host_name = "localhost"
282 check_command = "icinga"
286 The command object `icinga` for the embedded health check is provided by the
287 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
288 `users` and `disk` are all provided by the plugin check commands which we enabled
289 earlier by including the `itl` and `plugins` configuration file.
291 The Debian packages also ship an additional `apt` service check.
295 > Instead of defining each service object and assigning it to a host object
296 > using the `host_name` attribute rather use the [apply rules](#apply)
297 > simplifying your configuration.
299 There are two generic services applied to all hosts in the host group `linux-servers`
300 and `windows-servers` by default: `ping4` and `ping6`. Host objects without
301 a valid `address` resp. `address6` attribute will be excluded.
303 apply Service "ping4" {
304 import "generic-service"
306 check_command = "ping4"
309 assign where "linux-server" in host.groups
310 assign where "windows-server" in host.groups
311 ignore where host.address == ""
314 apply Service "ping6" {
315 import "generic-service"
317 check_command = "ping6"
320 assign where "linux-server" in host.groups
321 assign where "windows-server" in host.groups
322 ignore where host.address6 == ""
325 Each of these services has the custom attribute `sla` set to `24x7`. The
326 notification apply rule in `notifications.conf` will automatically apply
327 a service notification matchting this attribute pattern.
329 apply Notification "mail-icingaadmin" to Service {
330 import "mail-service-notification"
332 user_groups = [ "icingaadmins" ]
334 assign where service.vars.sla == "24x7"
337 Don't forget to install the [check plugins](#setting-up-check-plugins) required by the services and
338 their check commands.
340 Further details on the monitoring configuration can be found in the
341 [monitoring basics](#monitoring-basics) chapter.
343 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
345 On its own Icinga 2 does not know how to check external services. The
346 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
347 an extensive set of plugins which can be used with Icinga 2 to check whether
348 services are working properly.
350 The recommended way of installing these standard plugins is to use your
351 distribution's package manager.
355 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
356 > in January 2014. At the time of this writing the packages are still
357 > using the old name.
359 For your convenience here is a list of package names for some of the more
360 popular operating systems/distributions:
362 OS/Distribution | Package Name | Installation Path
363 -----------------------|--------------------|---------------------------
364 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
365 Debian | nagios-plugins | /usr/lib/nagios/plugins
366 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
367 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
369 Depending on which directory your plugins are installed into you may need to
370 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
371 by the service templates contained in the Icinga Template Library to determine
372 where to find the plugin binaries.
374 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
376 For some services you may need additional check plugins which are not provided
377 by the official Monitoring Plugins project.
379 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
380 list of popular community sites which host check plugins:
382 * [MonitoringExchange](https://www.monitoringexchange.org)
383 * [Icinga Wiki](https://wiki.icinga.org)
385 The recommended way of setting up these plugins is to copy them to a common directory
386 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
389 # cp check_snmp_int.pl /opt/plugins
390 # chmod +x /opt/plugins/check_snmp_int.pl
392 # cat /etc/icinga2/constants.conf
394 * This file defines global constants which can be used in
395 * the other configuration files. At a minimum the
396 * PluginDir constant should be defined.
399 const PluginDir = "/usr/lib/nagios/plugins"
400 const CustomPluginDir = "/opt/monitoring"
402 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
403 by trying to run it on the console using whichever user Icinga 2 is running as:
405 # su - icinga -s /bin/bash
406 $ /opt/plugins/check_snmp_int.pl --help
408 Additional libraries may be required for some plugins. Please consult the plugin
409 documentation and/or README for installation instructions.
411 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
412 configuration which can be used in the [Service](#objecttype-service) or
413 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
414 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
416 For further information on your monitoring configuration read the
417 [monitoring basics](#monitoring-basics).
420 ## <a id="configuring-ido"></a> Configuring IDO
422 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
423 configuration and status information into a database. The IDO database is used
424 by a number of projects including Icinga Web.
426 There is a separate module for each database back-end. At present support for
427 both MySQL and PostgreSQL is implemented.
429 Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
430 `1.11.0`. Icinga 2 may require additional features not yet released with
431 Icinga 1.x and therefore require manual upgrade steps during pre-final
436 > Only install the IDO feature if your web interface or reporting tool requires
437 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
438 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
440 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
442 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
444 First of all you have to install the `icinga2-ido-mysql` package using your
445 distribution's package manager. Once you have done that you can proceed with
446 setting up a MySQL database for Icinga 2:
450 > The Debian packages can optionally create and maintain the database for you
451 > using Debian's `dbconfig` framework. This is the recommended way of setting up
456 mysql> CREATE DATABASE icinga;
458 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
463 After creating the database you can import the Icinga 2 IDO schema using the
466 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
468 The Icinga 2 RPM packages install the schema files into
469 `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
471 On SuSE-based distributions the schema files are installed in
472 `/usr/share/doc/packages/icinga2-ido-mysql/schema`.
474 The Debian/Ubuntu packages put the schema files into
475 `/usr/share/icinga2-ido-mysql/schema`.
477 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
479 Check the `schema/upgrade` directory for an incremental schema upgrade file.
480 If there isn't an upgrade file available there's nothing to do.
484 > During pre release status (0.x.y releases) small snippets called for example
485 > `0.0.10.sql` will ship the required schema updates.
487 Apply all database schema upgrade files incrementially.
489 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
491 The Icinga 2 IDO module will check for the required database schema version on startup
492 and generate an error message if not satisfied.
494 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
496 The package provides a new configuration file that is installed in
497 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
498 database credentials in this file.
500 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
502 # icinga2-enable-feature ido-mysql
503 Module 'ido-mysql' was enabled.
504 Make sure to restart Icinga 2 for these changes to take effect.
506 After enabling the ido-mysql feature you have to restart Icinga 2:
508 # /etc/init.d/icinga2 restart
511 ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
513 #### Setting up the PostgreSQL database
515 First of all you have to install the `icinga2-ido-pgsql` package using your
516 distribution's package manager. Once you have done that you can proceed with
517 setting up a PostgreSQL database for Icinga 2:
521 > The Debian packages can optionally create and maintain the database for you
522 > using Debian's `dbconfig` framework. This is the recommended way of setting up
526 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
527 # sudo -u postgres createdb -O icinga -E UTF8 icinga
528 # sudo -u postgres createlang plpgsql icinga
530 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
531 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
532 authentication method and restart the postgresql server.
534 # vim /var/lib/pgsql/data/pg_hba.conf
537 local icinga icinga md5
538 host icinga icinga 127.0.0.1/32 md5
539 host icinga icinga ::1/128 md5
541 # "local" is for Unix domain socket connections only
543 # IPv4 local connections:
544 host all all 127.0.0.1/32 ident
545 # IPv6 local connections:
546 host all all ::1/128 ident
548 # /etc/init.d/postgresql restart
551 After creating the database and permissions you can import the Icinga 2 IDO schema
552 using the following command:
554 # export PGPASSWORD=icinga
555 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
557 The Icinga 2 RPM packages install the schema files into
558 `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
560 On SuSE-based distributions the schema files are installed in
561 `/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
563 The Debian/Ubuntu packages put the schema files into
564 `/usr/share/icinga2-ido-pgsql/schema`.
566 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
568 Check the `schema/upgrade` directory for an incremental schema upgrade file.
569 If there isn't an upgrade file available there's nothing to do.
573 > During pre release status (0.x.y releases) small snippets called for example
574 > `0.0.10.sql` will ship the required schema updates.
576 Apply all database schema upgrade files incrementially.
578 # export PGPASSWORD=icinga
579 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
581 The Icinga 2 IDO module will check for the required database schema version on startup
582 and generate an error message if not satisfied.
584 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
586 The package provides a new configuration file that is installed in
587 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
588 database credentials in this file.
590 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
592 # icinga2-enable-feature ido-pgsql
593 Module 'ido-pgsql' was enabled.
594 Make sure to restart Icinga 2 for these changes to take effect.
596 After enabling the ido-pgsql feature you have to restart Icinga 2:
598 # /etc/init.d/icinga2 restart
601 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
603 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
604 implements a query protocol that lets users query their Icinga instance for
605 status information. It can also be used to send commands.
609 > Only install the Livestatus feature if your web interface or addon requires
610 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
611 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
612 > do not use Livestatus as backend.
614 The Livestatus component that is distributed as part of Icinga 2 is a
615 re-implementation of the Livestatus protocol which is compatible with MK
618 Details on the available tables and attributes with Icinga 2 can be found
619 in the [Livestatus Schema](#schema-livestatus) section.
621 You can enable Livestatus using icinga2-enable-feature:
623 # icinga2-enable-feature livestatus
625 After that you will have to restart Icinga 2:
627 # /etc/init.d/icinga2 restart
629 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
631 In order for queries and commands to work you will need to add your query user
632 (e.g. your web server) to the `icingacmd` group:
634 # usermod -a -G icingacmd www-data
636 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
637 `nagios` if you're using Debian.
639 Change "www-data" to the user you're using to run queries.
641 In order to use the historical tables provided by the livestatus feature (for example, the
642 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
643 are expected in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path`
644 configuration attribute.
646 # icinga2-enable-feature compatlog
649 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
651 Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
652 features required as backends.
654 Furthermore these interfaces (and somewhere in the future an Icinga 2
655 exclusive interface) can be used for the newly created `Icinga Web 2`
658 Some interface features will only work in a limited manner due to
659 [compatibility reasons](#differences-1x-2), other features like the
660 statusmap parents are available dumping the host dependencies as parents.
661 Special restrictions are noted specifically in the sections below.
665 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
666 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
668 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
670 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
671 is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
672 "command pipe") are also supported. It also supports writing Icinga 1.x
673 log files which are required for the reporting functionality in the Classic UI.
675 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
677 The Icinga package repository has both Debian and RPM packages. You can install
678 the Classic UI using the following packages:
680 Distribution | Packages
681 --------------|---------------------
682 Debian | icinga2-classicui
683 all others | icinga2-classicui-config icinga-gui
685 The Debian packages require additional packages which are provided by the
686 [Debian Monitoring Project](http://www.debmon.org) repository.
688 On all distributions other than Debian you may have to restart both your web
689 server as well as Icinga 2 after installing the Classic UI package.
691 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
694 Distribution | URL | Default Login
695 --------------|--------------------------------------------------------------------------|--------------------------
696 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
697 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
699 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
701 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
702 is an explicit requirement to run `Icinga Web` next to the external command pipe.
703 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
705 #### <a id="installing-icinga-web"></a> Installing Icinga Web
707 The Icinga package repository has both Debian and RPM packages. You can install
708 the Classic UI using the following packages:
710 Distribution | Packages
711 --------------|-------------------------------------
712 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
715 Additionally you need to setup the `icinga_web` database.
717 The Icinga Web RPM packages install the schema files into
718 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
719 The Icinga Web dist tarball ships the schema files in `etc/schema`.
721 On SuSE-based distributions the schema files are installed in
722 `/usr/share/doc/packages/icinga-web/schema`.
724 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
725 Enable that feature, e.g. for MySQL.
727 # icinga2-enable-feature ido-mysql
729 If you've changed your default credentials you may either create a read-only user
730 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
731 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
732 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
734 # vim /etc/icinga-web/conf.d/databases.xml
736 # icinga-web-clearcache
738 Additionally you need to enable the `command` feature:
740 # icinga2-enable-feature command
742 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
743 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
744 to the default used in Icinga 2. Make sure to clear the cache afterwards.
746 # vim /etc/icinga-web/conf.d/access.xml
750 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
754 # icinga-web-clearcache
756 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
758 Distribution | URL | Default Login
759 --------------|-------------------------------------------------------------|--------------------------
760 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
761 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
764 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
766 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
767 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
768 further instructions.
770 Icinga Web 2 is still under development. Rather than installing it
771 yourself you should consider testing it using the available Vagrant
775 ### <a id="additional-visualization"></a> Additional visualization
777 There are many visualization addons which can be used with Icinga 2.
779 Some of the more popular ones are PNP, inGraph (graphing performance data),
780 Graphite, and NagVis (network maps).
783 ## <a id="configuration-tools"></a> Configuration Tools
785 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
786 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
787 store their configuration in a custom format in their backends (LDAP or RDBMS).
788 Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
789 your favourite configuration tool to export Icinga 2 configuration, please get in
790 touch with their developers.
792 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
793 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
796 ## <a id="running-icinga2"></a> Running Icinga 2
798 ### <a id="init-script"></a> Init Script
800 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
802 # /etc/init.d/icinga2
803 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
805 Command | Description
806 --------------------|------------------------
807 start | The `start` action starts the Icinga 2 daemon.
808 stop | The `stop` action stops the Icinga 2 daemon.
809 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
810 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.
811 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
812 status | The `status` action checks if Icinga 2 is running.
814 By default the Icinga 2 daemon is running as `icinga` user and group
815 using the init script. Using Debian packages the user and group are set to `nagios`
816 for historical reasons.
818 ### <a id="cmdline"></a> Command-line Options
821 icinga2 - The Icinga 2 network monitoring daemon.
824 --help show this help message
825 -V [ --version ] show version information
826 -l [ --library ] arg load a library
827 -I [ --include ] arg add include search directory
828 -D [ --define] args define a constant
829 -c [ --config ] arg parse a configuration file
830 -C [ --validate ] exit after validating the configuration
831 -x [ --debug ] enable debugging
832 -d [ --daemonize ] detach from the controlling terminal
833 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
834 in combination with --daemonize)
835 -u [ --user ] arg user to run Icinga as
836 -g [ --group ] arg group to run Icinga as
838 Report bugs at <https://dev.icinga.org/>
839 Icinga home page: <http://www.icinga.org/>
843 Instead of loading libraries using the [`library` config directive](#library)
844 you can also use the `--library` command-line option.
848 [Global constants](#global-constants) can be set using the `--define` command-line option.
850 #### Config Include Path
852 When including files you can specify that the include search path should be
853 checked. You can do this by putting your configuration file name in angle
858 This would cause Icinga 2 to search its include path for the configuration file
859 `test.conf`. By default the installation path for the Icinga Template Library
860 is the only search directory.
862 Using the `--include` command-line option additional search directories can be
867 Using the `--config` option you can specify one or more configuration files.
868 Config files are processed in the order they're specified on the command-line.
870 #### Config Validation
872 The `--validate` option can be used to check if your configuration files
873 contain errors. If any errors are found the exit status is 1, otherwise 0
876 ### <a id="features"></a> Enabling/Disabling Features
878 Icinga 2 provides configuration files for some commonly used features. These
879 are installed in the `/etc/icinga2/features-available` directory and can be
880 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
883 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
884 directory which is included by default in the example configuration file.
886 You can view a list of available feature configuration files:
888 # icinga2-enable-feature
889 Syntax: icinga2-enable-feature <feature>
890 Enables the specified feature.
892 Available features: statusdata
894 Using the `icinga2-enable-feature` command you can enable features:
896 # icinga2-enable-feature statusdata
897 Module 'statusdata' was enabled.
898 Make sure to restart Icinga 2 for these changes to take effect.
900 You can disable features using the `icinga2-disable-feature` command:
902 # icinga2-disable-feature statusdata
903 Module 'statusdata' was disabled.
904 Make sure to restart Icinga 2 for these changes to take effect.
906 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
907 restart Icinga 2. You will need to restart Icinga 2 using the init script
908 after enabling or disabling features.
910 ### <a id="config-validation"></a> Configuration Validation
912 Once you've edited the configuration files make sure to tell Icinga 2 to validate
913 the configuration changes. Icinga 2 will log any configuration error including
914 a hint on the file, the line number and the affected configuration line itself.
916 The following example creates an apply rule without any `assign` condition.
918 apply Service "5872-ping4" {
919 import "test-generic-service"
920 check_command = "ping4"
921 //assign where match("5872-*", host.name)
924 Validate the configuration with the init script option `checkconfig`
926 # /etc/init.d/icinga2 checkconfig
928 or manually passing the `-C` argument:
930 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
932 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: Location:
933 /etc/icinga2/conf.d/tests/5872.conf(5): }
934 /etc/icinga2/conf.d/tests/5872.conf(6):
935 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
937 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
938 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
940 Config error: 'apply' is missing 'assign'
941 [2014-05-22 17:07:25 +0200] <Main Thread> critical/config: 1 errors, 0 warnings.
942 Icinga 2 detected configuration errors.
945 ### <a id="config-change-reload"></a> Reload on Configuration Changes
947 Everytime you have changed your configuration you should first tell Icinga 2
948 to [validate](#config-validation). If there are no validation errors you can
949 safely reload the Icinga 2 daemon.
951 # /etc/init.d/icinga2 reload
955 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
956 > which will validate the configuration in a seperate process and not stop
957 > the other events like check execution, notifications, etc.
960 ## <a id="vagrant"></a> Vagrant Demo VM
962 The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
963 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
964 version `1.2.x` is required.
966 In order to build the Vagrant VM first you will have to check out
969 $ git clone git://git.icinga.org/icinga2.git
971 Once you have checked out the Git repository you can build the VM using the
976 The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
977 packages from `packages.icinga.org`. The check plugins are installed from
978 EPEL providing RPMs with sources from the Monitoring Plugins project.
980 ### <a id="vagrant-demo-guis"></a> Demo GUIs
982 In addition to installing Icinga 2 the Vagrant puppet modules also install the
983 Icinga 1.x Classic UI and Icinga Web.
985 GUI | Url | Credentials
986 ----------------|----------------------------------------------------------------------|------------------------
987 Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
988 Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
991 ### <a id="vagrant-ssh"></a> SSH Access
993 You can access the Vagrant VM using SSH:
997 Alternatively you can use your favorite SSH client:
1000 ----------------|----------------