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 package repositories depending on which operating system
13 and distribution you are running.
15 Distribution | Repository
16 ------------------------|---------------------------
17 Debian | [Icinga Repository](http://packages.icinga.org/debian/), [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2)
18 Ubuntu | [Icinga Repository](http://packages.icinga.org/ubuntu/), [Upstream](https://launchpad.net/ubuntu/+source/icinga2)
19 RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
20 OpenSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2)
21 SLES | [Icinga Repository](http://packages.icinga.org/SUSE/)
22 Gentoo | [Upstream](http://packages.gentoo.org/package/net-analyzer/icinga2)
23 FreeBSD | [Upstream](http://www.freshports.org/net-mgmt/icinga2)
24 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
26 Packages for distributions other than the ones listed above may also be
27 available. Please contact your distribution packagers.
29 The packages for RHEL/CentOS 5 depend on other packages which are distributed
30 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
31 make sure to enable this repository.
33 You can install Icinga 2 by using your distribution's package manager
34 to install the `icinga2` package.
36 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
37 `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
38 RHEL/CentOS 7 use [Systemd](#systemd-service) with `systemctl {enable,start} icinga2`.
40 Some parts of Icinga 2's functionality are available as separate packages:
43 ------------------------|--------------------------------
44 icinga2-ido-mysql | DB IDO provider module for MySQL
45 icinga2-ido-pgsql | DB IDO provider module for PostgreSQL
47 If you're running a distribution for which Icinga 2 packages are
48 not yet available you will need to use the release tarball which you
49 can download from the [Icinga website](https://www.icinga.org/). The
50 release tarballs contain an `INSTALL` file with further instructions.
52 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
54 The default installation will enable three features required for a basic
55 Icinga 2 installation:
57 * `checker` for executing checks
58 * `notification` for sending notifications
59 * `mainlog` for writing the `icinga2.log ` file
61 Verify that by calling `icinga2-enable-feature` without any additional parameters
62 and enable the missing features, if any.
64 # icinga2-enable-feature
65 Syntax: icinga2-enable-feature <features separated with whitespaces>
66 Example: icinga2-enable-feature checker notification mainlog
67 Enables the specified feature(s).
69 Available features: api checker command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus mainlog notification perfdata statusdata syslog
70 Enabled features: checker mainlog notification
72 ### <a id="installation-paths"></a> Installation Paths
74 By default Icinga 2 uses the following files and directories:
77 ------------------------------------|------------------------------------
78 /etc/icinga2 | Contains Icinga 2 configuration files.
79 /etc/init.d/icinga2 | The Icinga 2 init script.
80 /usr/bin/icinga2-* | Migration and certificate build scripts.
81 /usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts.
82 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
83 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
84 /var/run/icinga2 | PID file.
85 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
86 /var/cache/icinga2 | status.dat/objects.cache.
87 /var/spool/icinga2 | Used for performance data spool files.
88 /var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
89 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
91 ### <a id="icinga2-conf"></a> icinga2.conf
93 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
95 Here's a brief description of the example configuration:
98 * Icinga 2 configuration file
99 * - this is where you define settings for the Icinga application including
100 * which hosts/services to check.
102 * For an overview of all available configuration options please refer
103 * to the documentation that is distributed as part of Icinga 2.
106 Icinga 2 supports [C/C++-style comments](#comments).
109 * The constants.conf defines global constants.
111 include "constants.conf"
113 The `include` directive can be used to include other files.
116 * The zones.conf defines zones for a cluster setup.
117 * Not required for single instance setups.
122 * The Icinga Template Library (ITL) provides a number of useful templates
123 * and command definitions.
124 * Common monitoring plugin command definitions are included separately.
130 * The features-available directory contains a number of configuration
131 * files for features which can be enabled and disabled using the
132 * icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
133 * and removing symbolic links in the features-enabled directory.
135 include "features-enabled/*.conf"
137 This `include` directive takes care of including the configuration files for all
138 the features which have been enabled with `icinga2-enable-feature`. See
139 [Enabling/Disabling Features](#features) for more details.
142 * Although in theory you could define all your objects in this file
143 * the preferred way is to create separate directories and files in the conf.d
144 * directory. Each of these files must have the file extension ".conf".
146 include_recursive "conf.d"
148 You can put your own configuration files in the `conf.d` directory. This
149 directive makes sure that all of your own configuration files are included.
151 ### <a id="constants-conf"></a> constants.conf
153 The `constants.conf` configuration file can be used to define global constants:
156 * This file defines global constants which can be used in
157 * the other configuration files.
160 /* The directory which contains the plugins from the Monitoring Plugins project. */
161 const PluginDir = "/usr/lib/nagios/plugins"
163 /* Our local instance name. This should be the common name from the API certificate */
164 const NodeName = "localhost"
166 /* Our local zone name. */
167 const ZoneName = NodeName
169 ### <a id="zones-conf"></a> zones.conf
171 The `zones.conf` configuration file can be used to configure `Endpoint` and `Zone` objects
172 required for a [distributed zone setup](#distributed-monitoring-high-availability). By default
173 a local dummy zone is defined based on the `NodeName` constant defined in
174 [constants.conf](#constants-conf).
178 > Not required for single instance installations.
181 ### <a id="localhost-conf"></a> localhost.conf
183 The `conf.d/hosts/localhost.conf` file contains our first host definition:
186 * A host definition. You can create your own configuration files
187 * in the conf.d directory (e.g. one per host). By default all *.conf
188 * files in this directory are included.
191 object Host "localhost" {
192 import "generic-host"
194 address = "127.0.0.1"
201 This defines the host `localhost`. The `import` keyword is used to import
202 the `generic-host` template which takes care of setting up the host check
203 command to `hostalive`. If you require a different check command, you can
204 override it in the object definition.
206 The `vars` attribute can be used to define custom attributes which are available
207 for check and notification commands. Most of the templates in the Icinga
208 Template Library require an `address` attribute.
210 The custom attribute `os` is evaluated by the `linux-servers` group in
211 `groups.conf `making the host `localhost` a member.
213 object HostGroup "linux-servers" {
214 display_name = "Linux Servers"
216 assign where host.vars.os == "Linux"
219 A host notification apply rule in `notifications.conf` checks for the custom
220 attribute `sla` being set to `24x7` automatically applying a host notification.
223 * The example notification apply rules.
225 * Only applied if host/service objects have
226 * the custom attribute `sla` set to `24x7`.
229 apply Notification "mail-icingaadmin" to Host {
230 import "mail-host-notification"
232 user_groups = [ "icingaadmins" ]
234 assign where host.vars.sla == "24x7"
237 Now it's time to define services for the host object. Because these checks
238 are only available for the `localhost` host, they are organized below
243 > The directory tree and file organisation is just an example. You are
244 > free to define your own strategy. Just keep in mind to include the
245 > main directories in the [icinga2.conf](#icinga2-conf) file.
247 object Service "disk" {
248 import "generic-service"
250 host_name = "localhost"
251 check_command = "disk"
255 object Service "http" {
256 import "generic-service"
258 host_name = "localhost"
259 check_command = "http"
263 object Service "load" {
264 import "generic-service"
266 host_name = "localhost"
267 check_command = "load"
271 object Service "procs" {
272 import "generic-service"
274 host_name = "localhost"
275 check_command = "procs"
279 object Service "ssh" {
280 import "generic-service"
282 host_name = "localhost"
283 check_command = "ssh"
287 object Service "swap" {
288 import "generic-service"
290 host_name = "localhost"
291 check_command = "swap"
295 object Service "users" {
296 import "generic-service"
298 host_name = "localhost"
299 check_command = "users"
303 object Service "icinga" {
304 import "generic-service"
306 host_name = "localhost"
307 check_command = "icinga"
311 The command object `icinga` for the embedded health check is provided by the
312 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
313 `users` and `disk` are all provided by the plugin check commands which we enabled
314 earlier by including the `itl` and `plugins` configuration file.
316 The Debian packages also ship an additional `apt` service check.
320 > Instead of defining each service object and assigning it to a host object
321 > using the `host_name` attribute rather use the [apply rules](#apply)
322 > simplifying your configuration.
324 There are two generic services applied to all hosts in the host group `linux-servers`
325 and `windows-servers` by default: `ping4` and `ping6`. Host objects without
326 a valid `address` resp. `address6` attribute will be excluded.
328 apply Service "ping4" {
329 import "generic-service"
331 check_command = "ping4"
334 assign where "linux-servers" in host.groups
335 assign where "windows-servers" in host.groups
336 ignore where host.address == ""
339 apply Service "ping6" {
340 import "generic-service"
342 check_command = "ping6"
345 assign where "linux-servers" in host.groups
346 assign where "windows-servers" in host.groups
347 ignore where host.address6 == ""
350 Each of these services has the custom attribute `sla` set to `24x7`. The
351 notification apply rule in `notifications.conf` will automatically apply
352 a service notification matchting this attribute pattern.
354 apply Notification "mail-icingaadmin" to Service {
355 import "mail-service-notification"
357 user_groups = [ "icingaadmins" ]
359 assign where service.vars.sla == "24x7"
362 Don't forget to install the [check plugins](#setting-up-check-plugins) required by the services and
363 their check commands.
365 Further details on the monitoring configuration can be found in the
366 [monitoring basics](#monitoring-basics) chapter.
368 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
371 Icinga 2 does not know how to check external services. The
372 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
373 an extensive set of plugins which can be used with Icinga 2 to check whether
374 services are working properly.
376 The recommended way of installing these standard plugins is to use your
377 distribution's package manager.
381 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
382 > in January 2014. At the time of this writing the packages are still
383 > using the old name.
385 For your convenience here is a list of package names for some of the more
386 popular operating systems/distributions:
388 OS/Distribution | Package Name | Installation Path
389 -----------------------|--------------------|---------------------------
390 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
391 Debian | nagios-plugins | /usr/lib/nagios/plugins
392 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
393 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
395 Depending on which directory your plugins are installed into you may need to
396 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
397 by the service templates contained in the Icinga Template Library to determine
398 where to find the plugin binaries.
400 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
402 For some services you may need additional 'check plugins' which are not provided
403 by the official Monitoring Plugins project.
405 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
406 list of popular community sites which host check plugins:
408 * [MonitoringExchange](https://www.monitoringexchange.org)
409 * [Icinga Wiki](https://wiki.icinga.org)
411 The recommended way of setting up these plugins is to copy them to a common directory
412 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
415 # cp check_snmp_int.pl /opt/plugins
416 # chmod +x /opt/plugins/check_snmp_int.pl
418 # cat /etc/icinga2/constants.conf
420 * This file defines global constants which can be used in
421 * the other configuration files. At a minimum the
422 * PluginDir constant should be defined.
425 const PluginDir = "/usr/lib/nagios/plugins"
426 const CustomPluginDir = "/opt/monitoring"
428 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
429 by trying to run it on the console using whichever user Icinga 2 is running as:
431 # su - icinga -s /bin/bash
432 $ /opt/plugins/check_snmp_int.pl --help
434 Additional libraries may be required for some plugins. Please consult the plugin
435 documentation and/or README for installation instructions.
437 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
438 configuration which can be used in the [Service](#objecttype-service) or
439 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
440 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
442 For further information on your monitoring configuration read the
443 [monitoring basics](#monitoring-basics).
446 ## <a id="configuring-db-ido"></a> Configuring DB IDO
448 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting
449 all configuration and status information into a database. The IDO database is used
450 by a number of projects including Icinga Web 1.x, Reporting or Icinga Web 2.
452 There is a separate module for each database back-end. At present support for
453 both MySQL and PostgreSQL is implemented.
455 Icinga 2 uses the Icinga 1.x IDOUtils database schema. Icinga 2 requires additional
456 features not yet released with older Icinga 1.x versions.
458 * Current required schema version: `1.11.6`.
463 > Only install the IDO feature if your web interface or reporting tool requires
464 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
465 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
467 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
469 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
471 First of all you have to install the `icinga2-ido-mysql` package using your
472 distribution's package manager. Once you have done that you can proceed with
473 setting up a MySQL database for Icinga 2:
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.
502 Apply all database schema upgrade files incrementially.
504 # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/<version>.sql
506 The Icinga 2 DB IDO module will check for the required database schema version on startup
507 and generate an error message if not satisfied.
509 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
511 The package provides a new configuration file that is installed in
512 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
513 database credentials in this file.
515 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
517 # icinga2-enable-feature ido-mysql
518 Module 'ido-mysql' was enabled.
519 Make sure to restart Icinga 2 for these changes to take effect.
521 After enabling the ido-mysql feature you have to restart Icinga 2:
523 # /etc/init.d/icinga2 restart
526 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
528 #### Setting up the PostgreSQL database
530 First of all you have to install the `icinga2-ido-pgsql` package using your
531 distribution's package manager. Once you have done that you can proceed with
532 setting up a PostgreSQL database for Icinga 2:
535 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
536 # sudo -u postgres createdb -O icinga -E UTF8 icinga
537 # sudo -u postgres createlang plpgsql icinga
541 > Using PostgreSQL 9.x you can omit the `createlang` command.
543 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
544 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
545 authentication method and restart the postgresql server.
547 # vim /var/lib/pgsql/data/pg_hba.conf
550 local icinga icinga md5
551 host icinga icinga 127.0.0.1/32 md5
552 host icinga icinga ::1/128 md5
554 # "local" is for Unix domain socket connections only
556 # IPv4 local connections:
557 host all all 127.0.0.1/32 ident
558 # IPv6 local connections:
559 host all all ::1/128 ident
561 # /etc/init.d/postgresql restart
564 After creating the database and permissions you can import the Icinga 2 IDO schema
565 using the following command:
567 # export PGPASSWORD=icinga
568 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
570 The schema file location differs by the distribution used:
572 Distribution | Schema Files
573 --------------|---------------------
574 RHEL | `/usr/share/doc/icinga2-ido-pgsql-*/schema` (* means package version).
575 SUSE | `/usr/share/doc/packages/icinga2-ido-pgsql/schema`
576 Debian/Ubuntu | `/usr/share/icinga2-ido-pgsql/schema`
579 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
581 Check the `schema/upgrade` directory for an incremental schema upgrade file.
582 If there isn't an upgrade file available there's nothing to do.
584 Apply all database schema upgrade files incrementially.
586 # export PGPASSWORD=icinga
587 # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/<version>.sql
589 The Icinga 2 DB IDO module will check for the required database schema version on startup
590 and generate an error message if not satisfied.
592 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
594 The package provides a new configuration file that is installed in
595 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
596 database credentials in this file.
598 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
600 # icinga2-enable-feature ido-pgsql
601 Module 'ido-pgsql' was enabled.
602 Make sure to restart Icinga 2 for these changes to take effect.
604 After enabling the ido-pgsql feature you have to restart Icinga 2:
606 # /etc/init.d/icinga2 restart
609 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
611 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
612 implements a query protocol that lets users query their Icinga instance for
613 status information. It can also be used to send commands.
617 > Only install the Livestatus feature if your web interface or addon requires
618 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
619 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
620 > do not use Livestatus as backend.
622 The Livestatus component that is distributed as part of Icinga 2 is a
623 re-implementation of the Livestatus protocol which is compatible with MK
626 Details on the available tables and attributes with Icinga 2 can be found
627 in the [Livestatus Schema](#schema-livestatus) section.
629 You can enable Livestatus using icinga2-enable-feature:
631 # icinga2-enable-feature livestatus
633 After that you will have to restart Icinga 2:
635 # /etc/init.d/icinga2 restart
637 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
639 In order for queries and commands to work you will need to add your query user
640 (e.g. your web server) to the `icingacmd` group:
642 # usermod -a -G icingacmd www-data
644 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
645 `nagios` if you're using Debian.
647 Change "www-data" to the user you're using to run queries.
649 In order to use the historical tables provided by the livestatus feature (for example, the
650 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
651 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
652 `compat_log_path` configuration attribute.
654 # icinga2-enable-feature compatlog
657 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
659 Icinga 2 is compatible with Icinga 1.x user interfaces by providing additional
660 features required as backends.
662 Furthermore these interfaces can be used for the newly created `Icinga Web 2`
665 Some interface features will only work in a limited manner due to
666 [compatibility reasons](#differences-1x-2), other features like the
667 statusmap parents are available by dumping the host dependencies as parents.
668 Special restrictions are noted specifically in the sections below.
672 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
673 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
675 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
677 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
678 is supported by the Icinga 1.x Classic UI. [External commands](#external-commands)
679 (a.k.a. the "command pipe") are also supported. It also supports writing Icinga 1.x
680 log files which are required for the reporting functionality in the Classic UI.
682 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
684 The Icinga package repository has both Debian and RPM packages. You can install
685 the Classic UI using the following packages:
687 Distribution | Packages
688 --------------|---------------------
689 Debian | icinga2-classicui
690 all others | icinga2-classicui-config icinga-gui
692 The Debian packages require additional packages which are provided by the
693 [Debian Monitoring Project](http://www.debmon.org) (`DebMon`) repository.
695 `libjs-jquery-ui` requires at least version `1.10.*` which is not available
696 in Debian Wheezy and Ubuntu 12.04 LTS (Precise). Add the following repositories
697 to satisfy this dependency:
699 Distribution | Package Repositories
700 ------------------------------|------------------------------
701 Debian Wheezy | [wheezy-backports](http://backports.debian.org/Instructions/) or [DebMon](http://www.debmon.org)
702 Ubuntu 12.04 LTS (Precise) | [Icinga PPA](https://launchpad.net/~formorer/+archive/icinga)
704 On all distributions other than Debian you may have to restart both your web
705 server as well as Icinga 2 after installing the Classic UI package.
707 Icinga Classic UI requires the [StatusDataWriter](#status-data), [CompatLogger](#compat-logging)
708 and [ExternalCommandListener](#external-commands) features.
709 Enable these features and restart Icinga 2.
711 # icinga2-enable-feature statusdata compatlog command
713 In order for commands to work you will need to add your webserver's user to the `icingacmd` group.
717 > Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
720 # usermod -a -G icingacmd www-data
722 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
723 `nagios` if you're using Debian.
725 Change "www-data" to the user your webserver is running as.
727 #### <a id="setting-up-icinga-classic-ui-summary"></a> Setting Up Icinga Classic UI Summary
729 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
732 Distribution | URL | Default Login
733 --------------|--------------------------------------------------------------------------|--------------------------
734 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
735 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
737 For further information on configuration, troubleshooting and interface documentation
738 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
740 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
742 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
743 is an explicit requirement to run `Icinga Web` next to the external command pipe.
744 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
746 #### <a id="installing-icinga-web"></a> Installing Icinga Web
748 The Icinga package repository has both Debian and RPM packages. You can install
749 Icinga Web using the following packages (RPMs ship an additional configuration package):
751 Distribution | Packages
752 --------------|-------------------------------------
753 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
756 Additionally you need to setup the `icinga_web` database and import the database schema.
757 Details can be found in the package `README` files, for example [README.RHEL](https://github.com/Icinga/icinga-web/blob/master/doc/README.RHEL)
759 The Icinga Web RPM packages install the schema files into
760 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
761 The Icinga Web dist tarball ships the schema files in `etc/schema`.
763 On SuSE-based distributions the schema files are installed in
764 `/usr/share/doc/packages/icinga-web/schema`.
766 Example for RHEL and MySQL:
770 mysql> CREATE DATABASE icinga_web;
771 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga_web.* TO 'icinga_web'@'localhost' IDENTIFIED BY 'icinga_web';
774 # mysql -u root -p icinga_web < /usr/share/doc/icinga-web-<version>/schema/mysql.sql
776 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
777 Enable that feature, e.g. for MySQL.
779 # icinga2-enable-feature ido-mysql
781 If you've changed your default credentials you may either create a read-only user
782 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
783 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
784 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
786 # vim /etc/icinga-web/conf.d/databases.xml
788 # icinga-web-clearcache
790 Additionally you need to enable the `command` feature for sending [external commands](#external-commands):
792 # icinga2-enable-feature command
794 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
795 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
796 to the default used in Icinga 2. Make sure to clear the cache afterwards.
798 # vim /etc/icinga-web/conf.d/access.xml
802 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga2.cmd</resource>
806 # icinga-web-clearcache
810 > The path to the Icinga Web `clearcache` script may differ. Please check the
811 > [Icinga Web documentation](https://docs.icinga.org) for details.
813 #### <a id="setting-up-icinga-web-summary"></a> Setting Up Icinga Web Summary
815 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
817 Distribution | URL | Default Login
818 --------------|-------------------------------------------------------------|--------------------------
819 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
820 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
822 For further information on configuration, troubleshooting and interface documentation
823 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
826 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
828 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
830 Using DB IDO as backend, you need to install and configure the [DB IDO backend](#configuring-db-ido).
831 Once finished, you can enable the feature for DB IDO MySQL:
833 # icinga2-enable-feature ido-mysql
835 furthermore [external commands](#external-commands) are supported through the external
838 # icinga2-enable-feature command
840 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
841 further instructions on how to install Icinga Web 2 and to configure
842 backends, resources and instances.
846 > Icinga Web 2 is still under heavy development. Rather than installing it
847 > yourself you should consider testing it using the available Vagrant
848 > demo VM in the [git repository](https://github.com/icinga/icingaweb2).
850 Check the [Icinga website](https://www.icinga.org) for release schedules,
851 blog updates and more.
854 ### <a id="additional-visualization"></a> Additional visualization
856 There are many visualization addons which can be used with Icinga 2.
858 Some of the more popular ones are [PNP](#addons-graphing-pnp), [inGraph](#addons-graphing-pnp)
859 graphing performance data), [Graphite](#addons-graphing-pnp), and
860 [NagVis](#addons-visualization-nagvis) (network maps).
863 ## <a id="configuration-tools"></a> Configuration Tools
865 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
866 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
867 store their configuration in a custom format in their backends (LDAP or RDBMS).
868 Currently only LConf 1.4.x supports Icinga 2 configuration export as compatibility extension.
869 It does not use advanced Icinga 2 features such as [apply](#using-apply) rules or
870 easy [notifications](#using-apply-notifications) and [dependencies](#using-apply-dependencies)
873 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
874 touch with their developers.
878 > Get to know the new configuration format and the advanced [apply](#using-apply) rules and
879 > use [syntax highlighting](#configuration-syntax-highlighting) in vim/nano.
881 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
882 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
884 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
886 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano`editors.
887 The RHEL, SUSE and Debian package `icinga2-common` install these files into
888 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
890 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
892 Create a new local vim configuration storage, if not already existing.
893 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
897 $ mkdir -p $PREFIX/{syntax,ftdetect}
898 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
899 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
903 $ vim /etc/icinga2/conf.d/templates.conf
905 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
907 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
908 and copy the provided `icinga2.nanorc` into it.
910 $ cp /etc/nanorc ~/.nanorc
913 # cp icinga2.nanorc /etc/nano/
915 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
920 include "/etc/nano/icinga2.nanorc"
924 $ nano /etc/icinga2/conf.d/templates.conf
927 ## <a id="running-icinga2"></a> Running Icinga 2
929 ### <a id="init-script"></a> Init Script
931 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
933 # /etc/init.d/icinga2
934 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
936 Command | Description
937 --------------------|------------------------
938 start | The `start` action starts the Icinga 2 daemon.
939 stop | The `stop` action stops the Icinga 2 daemon.
940 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
941 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.
942 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
943 status | The `status` action checks if Icinga 2 is running.
945 By default the Icinga 2 daemon is running as `icinga` user and group
946 using the init script. Using Debian packages the user and group are set to `nagios`
947 for historical reasons.
949 ### <a id="systemd-service"></a> Systemd Service
951 Modern distributions (Fedora, OpenSUSE, etc.) already use `Systemd` natively. Enterprise-grade
952 distributions such as RHEL7 changed to `Systemd` recently. Icinga 2 Packages will install the
953 service automatically.
955 The Icinga 2 `Systemd` service can be (re)started, reloaded, stopped and also queried for its current status.
957 # systemctl status icinga2
958 icinga2.service - Icinga host/service/network monitoring system
959 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
960 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
961 Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS)
962 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
963 Main PID: 21727 (icinga2)
964 CGroup: /system.slice/icinga2.service
965 └─21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
967 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
968 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
969 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
970 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
971 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
972 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
973 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
974 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
976 `Systemd` supports the following command actions:
978 Command | Description
979 --------------------|------------------------
980 start | The `start` action starts the Icinga 2 daemon.
981 stop | The `stop` action stops the Icinga 2 daemon.
982 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
983 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.
984 status | The `status` action checks if Icinga 2 is running.
986 If you're stuck with configuration errors, you can manually invoke the [configuration validation](#config-validation).
990 ### <a id="cmdline"></a> Command-line Options
993 icinga2 - The Icinga 2 network monitoring daemon.
996 --help show this help message
997 -V [ --version ] show version information
998 -l [ --library ] arg load a library
999 -I [ --include ] arg add include search directory
1000 -D [ --define] args define a constant
1001 -c [ --config ] arg parse a configuration file
1002 -C [ --validate ] exit after validating the configuration
1003 -x [ --debug ] arg enable debugging with severity level specified
1004 -d [ --daemonize ] detach from the controlling terminal
1005 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
1006 in combination with --daemonize)
1007 -u [ --user ] arg user to run Icinga as
1008 -g [ --group ] arg group to run Icinga as
1010 Report bugs at <https://dev.icinga.org/>
1011 Icinga home page: <http://www.icinga.org/>
1015 Instead of loading libraries using the [`library` config directive](#library)
1016 you can also use the `--library` command-line option.
1020 [Global constants](#global-constants) can be set using the `--define` command-line option.
1022 #### Config Include Path
1024 When including files you can specify that the include search path should be
1025 checked. You can do this by putting your configuration file name in angle
1030 This would cause Icinga 2 to search its include path for the configuration file
1031 `test.conf`. By default the installation path for the Icinga Template Library
1032 is the only search directory.
1034 Using the `--include` command-line option additional search directories can be
1039 Using the `--config` option you can specify one or more configuration files.
1040 Config files are processed in the order they're specified on the command-line.
1042 #### Config Validation
1044 The `--validate` option can be used to check if your configuration files
1045 contain errors. If any errors are found the exit status is 1, otherwise 0
1048 ### <a id="features"></a> Enabling/Disabling Features
1050 Icinga 2 provides configuration files for some commonly used features. These
1051 are installed in the `/etc/icinga2/features-available` directory and can be
1052 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
1055 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
1056 directory which is included by default in the example configuration file.
1058 You can view a list of available feature configuration files:
1060 # icinga2-enable-feature
1061 Syntax: icinga2-enable-feature <feature>
1062 Enables the specified feature.
1064 Available features: statusdata
1066 Using the `icinga2-enable-feature` command you can enable features:
1068 # icinga2-enable-feature statusdata
1069 Module 'statusdata' was enabled.
1070 Make sure to restart Icinga 2 for these changes to take effect.
1072 You can disable features using the `icinga2-disable-feature` command:
1074 # icinga2-disable-feature statusdata
1075 Module 'statusdata' was disabled.
1076 Make sure to restart Icinga 2 for these changes to take effect.
1078 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
1079 restart Icinga 2. You will need to restart Icinga 2 using the init script
1080 after enabling or disabling features.
1082 ### <a id="config-validation"></a> Configuration Validation
1084 Once you've edited the configuration files make sure to tell Icinga 2 to validate
1085 the configuration changes. Icinga 2 will log any configuration error including
1086 a hint on the file, the line number and the affected configuration line itself.
1088 The following example creates an apply rule without any `assign` condition.
1090 apply Service "5872-ping4" {
1091 import "test-generic-service"
1092 check_command = "ping4"
1093 //assign where match("5872-*", host.name)
1096 Validate the configuration with the init script option `checkconfig`
1098 # /etc/init.d/icinga2 checkconfig
1100 or manually passing the `-C` argument:
1102 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
1104 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
1105 /etc/icinga2/conf.d/tests/5872.conf(5): }
1106 /etc/icinga2/conf.d/tests/5872.conf(6):
1107 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
1109 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
1110 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
1112 Config error: 'apply' is missing 'assign'
1113 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
1114 Icinga 2 detected configuration errors.
1117 ### <a id="config-change-reload"></a> Reload on Configuration Changes
1119 Everytime you have changed your configuration you should first tell Icinga 2
1120 to [validate](#config-validation). If there are no validation errors you can
1121 safely reload the Icinga 2 daemon.
1123 # /etc/init.d/icinga2 reload
1127 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
1128 > which will validate the configuration in a separate process and not stop
1129 > the other events like check execution, notifications, etc.
1131 > Details can be found [here](#differences-1x-2-real-reload).
1134 ## <a id="vagrant"></a> Vagrant Demo VM
1136 The Icinga Vagrant Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
1137 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
1138 version `1.2.x` is required.
1140 In order to build the Vagrant VM first you will have to check out
1143 $ git clone git://git.icinga.org/icinga-vagrant.git
1145 For Icinga 2 there are currently two scenarios available:
1147 * `icinga2x` bringing up a standalone box with Icinga 2
1148 * `icinga2x-cluster` setting up two virtual machines in a master/slave cluster
1152 > Please consult the `README` file for each project for further installation
1153 > details at [https://github.com/Icinga/icinga-vagrant]
1155 Once you have checked out the Git repository navigate to your required
1156 vagrant box and build the VM using the following command:
1160 The Vagrant VMs are based on CentOS 6.x and are using the official
1161 Icinga 2 RPM snapshot packages from `packages.icinga.org`. The check
1162 plugins are installed from EPEL providing RPMs with sources from the
1163 Monitoring Plugins project.