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

## <a id="setting-up-icinga2"></a> 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/
  Ubuntu                  |http://packages.icinga.org/ubuntu/
  RHEL/CentOS 5           |http://packages.icinga.org/epel/5/release/
  RHEL/CentOS 6           |http://packages.icinga.org/epel/6/release/
  OpenSUSE 12.3           |http://packages.icinga.org/openSUSE/12.3/release/
  SLES 11 SP3             |http://packages.icinga.org/SUSE/sles11-sp3/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 favourite distribution.

> **Note**
>
> RHEL/CentOS 5 packages require the [EPEL repository](http://fedoraproject.org/wiki/EPEL)
> enabled (which provides the `boost141` package). SLES 11 SP3 and older versions
> require the `boost_1_54_0` package (available on http://packages.icinga.org).

You can install Icinga 2 by using your distribution's package manager
to install the `icinga2` package.

> **Note**
>
> On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2
start`.

Some parts of Icinga 2's functionality are available as separate packages:

  Name                    | Description
  ------------------------|--------------------------------
  icinga2-ido-mysql       | IDO provider module for MySQL

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](https://www.icinga.org/). The
release tarballs contain an `INSTALL` file with further instructions.

### <a id="installation-paths"></a> 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/bin/icinga2-*                  | Migration and certificate build scripts.
  /usr/sbin/icinga2*                  | The Icinga 2 binary and feature enable/disable scripts.
  /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/spool/icinga2                  | Used for performance data spool files.
  /var/lib/icinga2                    | Icinga 2 state file, cluster feature replay log and configuration files.
  /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.

### <a id="icinga2-conf"></a> icinga2.conf

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

Here's a brief description of the example configuration:

    /**
     * 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](#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
     * icinga2-enable-feature / icinga2-disable-feature 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 `icinga2-enable-feature`. See
[Enabling/Disabling Features](#features) for more details.

    /**
     * Although in theory you could define all your objects in this file
     * the preferred way is to create separate directories and files in the conf.d
     * directory.
     */
    include_recursive "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.

### <a id="macros-conf"></a> 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.

### <a id="localhost-conf"></a> 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"] = {
        templates = [ "generic-service" ],

        check_command = "ping4"
      },

      services["ping6"] = {
        templates = [ "generic-service" ],

        check_command = "ping6"
      },

      services["http"] = {
        templates = [ "generic-service" ],

        check_command = "http_ip"
      },

      services["ssh"] = {
        templates = [ "generic-service" ],

        check_command = "ssh"
      },

      services["load"] = {
        templates = [ "generic-service" ],

        check_command = "load"
      },

      services["processes"] = {
        templates = [ "generic-service" ],

        check_command = "processes"
      },

      services["users"] = {
        templates = [ "generic-service" ],

        check_command = "users"
      },

      services["disk"] = {
        templates = [ "generic-service" ],

        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.