icinga2/doc/2.1-setting-up-icinga-2.md

Setting up Icinga 2

First of all you will have to install Icinga 2. The preferred way of doing this is to use the official Debian or RPM package repositories depending on which operating system and distribution you are running.

Distribution	Repository URL
Debian	http://packages.icinga.org/debian/
RHEL/CentOS 5	http://packages.icinga.org/epel/5/release/
RHEL/CentOS 6	http://packages.icinga.org/epel/6/release/

Packages for distributions other than the ones listed above may also be available. Please check http://packages.icinga.org/ to see if packages are available for your favorite distribution.

Icinga 2 is split up into several packages:

You can install Icinga 2 by using your distribution's package manager to install the icinga2 package. Some parts of Icinga 2's functionality are available as separate packages:

Name	Description
icinga2-ido-mysql	IDO provider module for MySQL
icinga2-python	Python scripting support for Icinga 2

In case you're running a distribution for which Icinga 2 packages are not yet available you will have to use the release tarball which you can download from the Icinga website. The release tarballs contain an INSTALL file with further instructions.

Installation Paths

By default Icinga 2 uses the following files and directories:

Path	Description
/etc/icinga2	Contains Icinga 2 configuration files.
/etc/init.d/icinga2	The Icinga 2 init script.
/usr/share/doc/icinga2	Documentation files that come with Icinga 2.
/usr/share/icinga2/itl	The Icinga Template Library.
/var/run/icinga2	PID file.
/var/run/icinga2/cmd	Command pipe and livestatus socket.
/var/cache/icinga2	Performance data files and status.dat/objects.cache.
/var/lib/icinga2	The Icinga 2 state file.

icinga2.conf

An example configuration file is installed for you in /etc/icinga2/icinga2.conf.

Here's a brief description of the example config:

/**
 * Icinga 2 configuration file
 * - this is where you define settings for the Icinga application including
 * which hosts/services to check.
 *
 * For an overview of all available configuration options please refer
 * to the documentation that is distributed as part of Icinga 2.
 */

Icinga 2 supports C/C++-style comments.

include <itl/itl.conf>

The include directive can be used to include other files. The itl/itl.conf file is distributed as part of Icinga 2 and provides a number of useful templates and constants you can use to configure your services.

/**
 * The features-available directory contains a number of configuration
 * files for features which can be enabled and disabled using the
 * i2enfeature / i2disfeature tools. These two tools work by creating
 * and removing symbolic links in the features-enabled directory.
 */
include "features-enabled/*.conf"

This include directive takes care of including the configuration files for all the features which have been enabled with i2enfeature. See Enabling/Disabling Features for more details.

/**
 * Although in theory you could define all your objects in this file
 * the preferred way is to create separate files in the conf.d
 * directory.
 */
include "conf.d/*.conf"

You can put your own configuration files in the conf.d directory. This directive makes sure that all of your own configuration files are included.

macros.conf

The conf.d/macros.conf file can be used to define global macros:

/**
 * Global macros
 */
set IcingaMacros = {
  plugindir = "/usr/local/icinga/libexec"
}

Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used to define global macros which are available in all command definitions.

localhost.conf

The conf.d/localhost.conf file contains our first host definition:

/**
 * A host definition. You can create your own configuration files
 * in the conf.d directory (e.g. one per host). By default all *.conf
 * files in this directory are included.
 */
object Host "localhost" {
  services["ping4"] = {
    check_command = "ping4"
  },

  services["ping6"] = {
    check_command = "ping6"
  },

  services["http"] = {
    check_command = "http_ip"
  },

  services["ssh"] = {
    check_command = "ssh"
  },

  services["load"] = {
    check_command = "load"
  },

  services["processes"] = {
    check_command = "processes"
  },

  services["users"] = {
    check_command = "users"
  },

  services["disk"] = {
    check_command = "disk"
  },

  macros = {
    address = "127.0.0.1",
    address6 = "::1",
  },

  check = "ping4",
}

This defines a host named "localhost" which has a couple of services. Services may inherit from one or more service templates.

The command objects ping4, ping6, http_ip, ssh, load, processes, users and disk are all provided by the Icinga Template Library (short ITL) which we enabled earlier by including the itl/itl.conf configuration file.

The macros attribute can be used to define macros that are available for all services which belong to this host. Most of the templates in the Icinga Template Library require an address macro.