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 plugin provided 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/icinga2-ido-mysql/schema/mysql.sql
489 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
491 Check the `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an
492 incremental schema upgrade file. If there isn't an upgrade file available
493 there's nothing to do.
495 Apply all database schema upgrade files incrementially.
497 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/<version>.sql
499 The Icinga 2 DB IDO module will check for the required database schema version on startup
500 and generate an error message if not satisfied.
502 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
504 The package provides a new configuration file that is installed in
505 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
506 database credentials in this file.
508 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
510 # icinga2-enable-feature ido-mysql
511 Module 'ido-mysql' was enabled.
512 Make sure to restart Icinga 2 for these changes to take effect.
514 After enabling the ido-mysql feature you have to restart Icinga 2:
516 # /etc/init.d/icinga2 restart
519 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
521 #### Setting up the PostgreSQL database
523 First of all you have to install the `icinga2-ido-pgsql` package using your
524 distribution's package manager. Once you have done that you can proceed with
525 setting up a PostgreSQL database for Icinga 2:
528 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
529 # sudo -u postgres createdb -O icinga -E UTF8 icinga
530 # sudo -u postgres createlang plpgsql icinga
534 > Using PostgreSQL 9.x you can omit the `createlang` command.
536 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
537 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
538 authentication method and restart the postgresql server.
540 # vim /var/lib/pgsql/data/pg_hba.conf
543 local icinga icinga md5
544 host icinga icinga 127.0.0.1/32 md5
545 host icinga icinga ::1/128 md5
547 # "local" is for Unix domain socket connections only
549 # IPv4 local connections:
550 host all all 127.0.0.1/32 ident
551 # IPv6 local connections:
552 host all all ::1/128 ident
554 # /etc/init.d/postgresql restart
557 After creating the database and permissions you can import the Icinga 2 IDO schema
558 using the following command:
560 # export PGPASSWORD=icinga
561 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
563 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
565 Check the `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for an
566 incremental schema upgrade file. If there isn't an upgrade file available
567 there's nothing to do.
569 Apply all database schema upgrade files incrementially.
571 # export PGPASSWORD=icinga
572 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/<version>.sql
574 The Icinga 2 DB IDO module will check for the required database schema version on startup
575 and generate an error message if not satisfied.
577 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
579 The package provides a new configuration file that is installed in
580 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
581 database credentials in this file.
583 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
585 # icinga2-enable-feature ido-pgsql
586 Module 'ido-pgsql' was enabled.
587 Make sure to restart Icinga 2 for these changes to take effect.
589 After enabling the ido-pgsql feature you have to restart Icinga 2:
591 # /etc/init.d/icinga2 restart
594 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
596 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
597 implements a query protocol that lets users query their Icinga instance for
598 status information. It can also be used to send commands.
602 > Only install the Livestatus feature if your web interface or addon requires
603 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
604 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
605 > do not use Livestatus as backend.
607 The Livestatus component that is distributed as part of Icinga 2 is a
608 re-implementation of the Livestatus protocol which is compatible with MK
611 Details on the available tables and attributes with Icinga 2 can be found
612 in the [Livestatus Schema](#schema-livestatus) section.
614 You can enable Livestatus using icinga2-enable-feature:
616 # icinga2-enable-feature livestatus
618 After that you will have to restart Icinga 2:
620 # /etc/init.d/icinga2 restart
622 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
624 In order for queries and commands to work you will need to add your query user
625 (e.g. your web server) to the `icingacmd` group:
627 # usermod -a -G icingacmd www-data
629 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
630 `nagios` if you're using Debian.
632 Change "www-data" to the user you're using to run queries.
634 In order to use the historical tables provided by the livestatus feature (for example, the
635 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
636 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
637 `compat_log_path` configuration attribute.
639 # icinga2-enable-feature compatlog
642 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
644 Icinga 2 is compatible with Icinga 1.x user interfaces by providing additional
645 features required as backends.
647 Furthermore these interfaces can be used for the newly created `Icinga Web 2`
650 Some interface features will only work in a limited manner due to
651 [compatibility reasons](#differences-1x-2), other features like the
652 statusmap parents are available by dumping the host dependencies as parents.
653 Special restrictions are noted specifically in the sections below.
657 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
658 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
660 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
662 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
663 is supported by the Icinga 1.x Classic UI. [External commands](#external-commands)
664 (a.k.a. the "command pipe") are also supported. It also supports writing Icinga 1.x
665 log files which are required for the reporting functionality in the Classic UI.
667 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
669 The Icinga package repository has both Debian and RPM packages. You can install
670 the Classic UI using the following packages:
672 Distribution | Packages
673 --------------|---------------------
674 Debian | icinga2-classicui
675 all others | icinga2-classicui-config icinga-gui
677 The Debian packages require additional packages which are provided by the
678 [Debian Monitoring Project](http://www.debmon.org) (`DebMon`) repository.
680 `libjs-jquery-ui` requires at least version `1.10.*` which is not available
681 in Debian Wheezy and Ubuntu 12.04 LTS (Precise). Add the following repositories
682 to satisfy this dependency:
684 Distribution | Package Repositories
685 ------------------------------|------------------------------
686 Debian Wheezy | [wheezy-backports](http://backports.debian.org/Instructions/) or [DebMon](http://www.debmon.org)
687 Ubuntu 12.04 LTS (Precise) | [Icinga PPA](https://launchpad.net/~formorer/+archive/icinga)
689 On all distributions other than Debian you may have to restart both your web
690 server as well as Icinga 2 after installing the Classic UI package.
692 Icinga Classic UI requires the [StatusDataWriter](#status-data), [CompatLogger](#compat-logging)
693 and [ExternalCommandListener](#external-commands) features.
694 Enable these features and restart Icinga 2.
696 # icinga2-enable-feature statusdata compatlog command
698 In order for commands to work you will need to add your webserver's user to the `icingacmd` group.
702 > Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
705 # usermod -a -G icingacmd www-data
707 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
708 `nagios` if you're using Debian.
710 Change "www-data" to the user your webserver is running as.
712 #### <a id="setting-up-icinga-classic-ui-summary"></a> Setting Up Icinga Classic UI Summary
714 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
717 Distribution | URL | Default Login
718 --------------|--------------------------------------------------------------------------|--------------------------
719 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
720 all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
722 For further information on configuration, troubleshooting and interface documentation
723 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
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 Icinga Web using the following packages (RPMs ship an additional configuration package):
736 Distribution | Packages
737 --------------|-------------------------------------
738 RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
741 Additionally you need to setup the `icinga_web` database and import the database schema.
742 Details can be found in the package `README` files, for example [README.RHEL](https://github.com/Icinga/icinga-web/blob/master/doc/README.RHEL)
744 The Icinga Web RPM packages install the schema files into
745 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
746 The Icinga Web dist tarball ships the schema files in `etc/schema`.
748 On SuSE-based distributions the schema files are installed in
749 `/usr/share/doc/packages/icinga-web/schema`.
751 Example for RHEL and MySQL:
755 mysql> CREATE DATABASE icinga_web;
756 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga_web.* TO 'icinga_web'@'localhost' IDENTIFIED BY 'icinga_web';
759 # mysql -u root -p icinga_web < /usr/share/doc/icinga-web-<version>/schema/mysql.sql
761 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
762 Enable that feature, e.g. for MySQL.
764 # icinga2-enable-feature ido-mysql
766 If you've changed your default credentials you may either create a read-only user
767 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
768 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
769 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
771 # vim /etc/icinga-web/conf.d/databases.xml
773 # icinga-web-clearcache
775 Additionally you need to enable the `command` feature for sending [external commands](#external-commands):
777 # icinga2-enable-feature command
779 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
780 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
781 to the default used in Icinga 2. Make sure to clear the cache afterwards.
783 # vim /etc/icinga-web/conf.d/access.xml
787 <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga2.cmd</resource>
791 # icinga-web-clearcache
795 > The path to the Icinga Web `clearcache` script may differ. Please check the
796 > [Icinga Web documentation](https://docs.icinga.org) for details.
798 #### <a id="setting-up-icinga-web-summary"></a> Setting Up Icinga Web Summary
800 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
802 Distribution | URL | Default Login
803 --------------|-------------------------------------------------------------|--------------------------
804 Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
805 all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
807 For further information on configuration, troubleshooting and interface documentation
808 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
811 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
813 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
815 Using DB IDO as backend, you need to install and configure the [DB IDO backend](#configuring-db-ido).
816 Once finished, you can enable the feature for DB IDO MySQL:
818 # icinga2-enable-feature ido-mysql
820 furthermore [external commands](#external-commands) are supported through the external
823 # icinga2-enable-feature command
825 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
826 further instructions on how to install Icinga Web 2 and to configure
827 backends, resources and instances.
831 > Icinga Web 2 is still under heavy development. Rather than installing it
832 > yourself you should consider testing it using the available Vagrant
833 > demo VM in the [git repository](https://github.com/icinga/icingaweb2).
835 Check the [Icinga website](https://www.icinga.org) for release schedules,
836 blog updates and more.
839 ### <a id="additional-visualization"></a> Additional visualization
841 There are many visualization addons which can be used with Icinga 2.
843 Some of the more popular ones are [PNP](#addons-graphing-pnp), [inGraph](#addons-graphing-pnp)
844 graphing performance data), [Graphite](#addons-graphing-pnp), and
845 [NagVis](#addons-visualization-nagvis) (network maps).
848 ## <a id="configuration-tools"></a> Configuration Tools
850 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
851 touch with their developers. The Icinga project does not provide a configuration web interface
856 > Get to know the new configuration format and the advanced [apply](#using-apply) rules and
857 > use [syntax highlighting](#configuration-syntax-highlighting) in vim/nano.
859 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
860 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
862 These tools are in development and require feedback and tests:
864 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
865 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
867 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
869 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano`editors.
870 The RHEL, SUSE and Debian package `icinga2-common` install these files into
871 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
873 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
875 Create a new local vim configuration storage, if not already existing.
876 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
880 $ mkdir -p $PREFIX/{syntax,ftdetect}
881 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
882 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
886 $ vim /etc/icinga2/conf.d/templates.conf
888 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
890 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
891 and copy the provided `icinga2.nanorc` into it.
893 $ cp /etc/nanorc ~/.nanorc
896 # cp icinga2.nanorc /etc/nano/
898 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
903 include "/etc/nano/icinga2.nanorc"
907 $ nano /etc/icinga2/conf.d/templates.conf
910 ## <a id="running-icinga2"></a> Running Icinga 2
912 ### <a id="init-script"></a> Init Script
914 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
916 # /etc/init.d/icinga2
917 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
919 Command | Description
920 --------------------|------------------------
921 start | The `start` action starts the Icinga 2 daemon.
922 stop | The `stop` action stops the Icinga 2 daemon.
923 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
924 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.
925 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
926 status | The `status` action checks if Icinga 2 is running.
928 By default the Icinga 2 daemon is running as `icinga` user and group
929 using the init script. Using Debian packages the user and group are set to `nagios`
930 for historical reasons.
932 ### <a id="systemd-service"></a> Systemd Service
934 Modern distributions (Fedora, OpenSUSE, etc.) already use `Systemd` natively. Enterprise-grade
935 distributions such as RHEL7 changed to `Systemd` recently. Icinga 2 Packages will install the
936 service automatically.
938 The Icinga 2 `Systemd` service can be (re)started, reloaded, stopped and also queried for its current status.
940 # systemctl status icinga2
941 icinga2.service - Icinga host/service/network monitoring system
942 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
943 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
944 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)
945 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
946 Main PID: 21727 (icinga2)
947 CGroup: /system.slice/icinga2.service
948 └─21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
950 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
951 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
952 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
953 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
954 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
955 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
956 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
957 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
959 `Systemd` supports the following command actions:
961 Command | Description
962 --------------------|------------------------
963 start | The `start` action starts the Icinga 2 daemon.
964 stop | The `stop` action stops the Icinga 2 daemon.
965 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
966 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.
967 status | The `status` action checks if Icinga 2 is running.
969 If you're stuck with configuration errors, you can manually invoke the [configuration validation](#config-validation).
973 ### <a id="cmdline"></a> Command-line Options
976 icinga2 - The Icinga 2 network monitoring daemon.
979 --help show this help message
980 -V [ --version ] show version information
981 -l [ --library ] arg load a library
982 -I [ --include ] arg add include search directory
983 -D [ --define] args define a constant
984 -c [ --config ] arg parse a configuration file
985 -C [ --validate ] exit after validating the configuration
986 -x [ --debug ] arg enable debugging with severity level specified
987 -d [ --daemonize ] detach from the controlling terminal
988 -e [ --errorlog ] arg log fatal errors to the specified log file (only works
989 in combination with --daemonize)
990 -u [ --user ] arg user to run Icinga as
991 -g [ --group ] arg group to run Icinga as
993 Report bugs at <https://dev.icinga.org/>
994 Icinga home page: <http://www.icinga.org/>
998 Instead of loading libraries using the [`library` config directive](#library)
999 you can also use the `--library` command-line option.
1003 [Global constants](#global-constants) can be set using the `--define` command-line option.
1005 #### Config Include Path
1007 When including files you can specify that the include search path should be
1008 checked. You can do this by putting your configuration file name in angle
1013 This would cause Icinga 2 to search its include path for the configuration file
1014 `test.conf`. By default the installation path for the Icinga Template Library
1015 is the only search directory.
1017 Using the `--include` command-line option additional search directories can be
1022 Using the `--config` option you can specify one or more configuration files.
1023 Config files are processed in the order they're specified on the command-line.
1025 #### Config Validation
1027 The `--validate` option can be used to check if your configuration files
1028 contain errors. If any errors are found the exit status is 1, otherwise 0
1031 ### <a id="features"></a> Enabling/Disabling Features
1033 Icinga 2 provides configuration files for some commonly used features. These
1034 are installed in the `/etc/icinga2/features-available` directory and can be
1035 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
1038 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
1039 directory which is included by default in the example configuration file.
1041 You can view a list of available feature configuration files:
1043 # icinga2-enable-feature
1044 Syntax: icinga2-enable-feature <feature>
1045 Enables the specified feature.
1047 Available features: statusdata
1049 Using the `icinga2-enable-feature` command you can enable features:
1051 # icinga2-enable-feature statusdata
1052 Module 'statusdata' was enabled.
1053 Make sure to restart Icinga 2 for these changes to take effect.
1055 You can disable features using the `icinga2-disable-feature` command:
1057 # icinga2-disable-feature statusdata
1058 Module 'statusdata' was disabled.
1059 Make sure to restart Icinga 2 for these changes to take effect.
1061 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
1062 restart Icinga 2. You will need to restart Icinga 2 using the init script
1063 after enabling or disabling features.
1065 ### <a id="config-validation"></a> Configuration Validation
1067 Once you've edited the configuration files make sure to tell Icinga 2 to validate
1068 the configuration changes. Icinga 2 will log any configuration error including
1069 a hint on the file, the line number and the affected configuration line itself.
1071 The following example creates an apply rule without any `assign` condition.
1073 apply Service "5872-ping4" {
1074 import "test-generic-service"
1075 check_command = "ping4"
1076 //assign where match("5872-*", host.name)
1079 Validate the configuration with the init script option `checkconfig`
1081 # /etc/init.d/icinga2 checkconfig
1083 or manually passing the `-C` argument:
1085 # /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -C
1087 [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
1088 /etc/icinga2/conf.d/tests/5872.conf(5): }
1089 /etc/icinga2/conf.d/tests/5872.conf(6):
1090 /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
1092 /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service"
1093 /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4"
1095 Config error: 'apply' is missing 'assign'
1096 [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
1097 Icinga 2 detected configuration errors.
1100 ### <a id="config-change-reload"></a> Reload on Configuration Changes
1102 Everytime you have changed your configuration you should first tell Icinga 2
1103 to [validate](#config-validation). If there are no validation errors you can
1104 safely reload the Icinga 2 daemon.
1106 # /etc/init.d/icinga2 reload
1110 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
1111 > which will validate the configuration in a separate process and not stop
1112 > the other events like check execution, notifications, etc.
1114 > Details can be found [here](#differences-1x-2-real-reload).
1117 ## <a id="vagrant"></a> Vagrant Demo VM
1119 The Icinga Vagrant Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
1120 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
1121 version `1.2.x` is required.
1123 In order to build the Vagrant VM first you will have to check out
1126 $ git clone git://git.icinga.org/icinga-vagrant.git
1128 For Icinga 2 there are currently two scenarios available:
1130 * `icinga2x` bringing up a standalone box with Icinga 2
1131 * `icinga2x-cluster` setting up two virtual machines in a master/slave cluster
1135 > Please consult the `README.md` file for each project for further installation
1136 > details at [https://github.com/Icinga/icinga-vagrant]
1138 Once you have checked out the Git repository navigate to your required
1139 vagrant box and build the VM using the following command:
1143 The Vagrant VMs are based on CentOS 6.x and are using the official
1144 Icinga 2 RPM snapshot packages from `packages.icinga.org`. The check
1145 plugins are installed from EPEL providing RPMs with sources from the
1146 Monitoring Plugins project.