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

### Setting up Icinga 2

In order to get started with Icinga 2 you will have to install it. The
preferred way of doing this is to use the official Debian or RPM
package repositories depending on which Linux 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.

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 information.

#### 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                    |Command pipe and PID file.
  /var/cache/icinga2                  |Performance data files and status.dat/objects.cache.
  /var/lib/icinga2                    |The Icinga 2 state file.

#### Configuration

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

Here's a brief description of the concepts the example configuration file
introduces:

    /**
     * Icinga 2 configuration file
     * - this is where you define settings for the Icinga application including
     * which hosts/services to check.
     *
     * The docs/icinga2-config.adoc file in the source tarball has a detailed
     * description of what configuration options are available.
     */

Icinga 2 supports [C/C++-style comments](#comments).

    include <itl/itl.conf>
    include <itl/standalone.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.

    /**
     * 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.

    /**
     * The compat library periodically updates the status.dat and objects.cache
     * files. These are used by the Icinga 1.x CGIs to display the state of
     * hosts and services. CompatLog writeis the Icinga 1.x icinga.log and archives.
     */
    library "compat"

Some of Icinga 2's functionality is available in separate libraries. These
libraries usually implement their own object types that can be used to configure
what you want the library to do.

    object StatusDataWriter "status" { }
    object ExternalCommandListener "command" { }
    object CompatLogger "compat-log" { }

Those three object types are provided by the *compat* library:

  Type                     | Description
  -------------------------|-------------------------
  StatusDataWriter         | Responsible for writing the status.dat and objects.cache files.
  ExternalCommandListener  | Implements the command pipe which is used by the CGIs to send commands to Icinga 2.
  CompatLogger             | Writes log files in a format that is compatible with Icinga 1.x.

    /**
     * And finally we define some host that should be checked.
     */
    object Host "localhost" {
      services["ping4"] = {
        templates = [ "ping4" ]
      },

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

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

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

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

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

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

      services["disk"] = {
        templates = [ "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 templates *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.