icinga2/docs/icinga2-tutorial.adoc

Icinga 2 Configuration
======================

:keywords:	Icinga, documentation, installation, configuration, tutorial
:description:	Quick introduction to monitoring network services with Icinga 2

Preface
-------

This tutorial is a step-by-step introduction to installing Icinga 2 and setting
up your first couple of service checks. It assumes some familiarity with Icinga 1.x.

Installation
------------

In order to get started with Icinga 2 we will have to install it. The preferred way
of doing this is to use the official Debian or RPM packages depending on which Linux
distribution you are running.

|===
|Distribution          | Package URL
|Debian                | http://icingabuild.dus.dg-i.net:8080/job/icinga2/
|RHEL                  | TBD
|===

In case you're running a distribution for which Icinga 2 packages are not yet available
you will have to check out the Icinga 2 Git repository from git://git.icinga.org/icinga2
and read the 'INSTALL' file.

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

Our First Service Check
-----------------------

The Icinga 2 package comes with a number of example configuration files. However, in order
to explain some of the basics we're going write our own configuration file from scratch.

Start by creating the file /etc/icinga2/icinga2.conf with the following content:

----
include <itl/itl.conf>
include <itl/standalone.conf>

local object IcingaApplication "my-icinga" {
	macros["plugindir"] = "/usr/lib/nagios/plugins"
}
----

The configuration snippet includes the 'itl/itl.conf' and 'itl/standalone.conf' files
which are distributed as part of Icinga 2. We will discuss the Icinga Template Library (ITL)
in more detail later on.

The 'itl/standalone.conf' configuration file takes care of configuring Icinga 2 for
single-instance (i.e. non-clustered) mode.

Our configuration file also creates an object of type 'IcingaApplication' with the
name 'my-icinga'. The 'IcingaApplication' type can be used to define global macros and some
other global settings.

For now we're only defining the global macro 'plugindir' which we're going to use later on
when referring to the path which contains our check plugins. Depending on where you've installed
your check plugins you may need to update this path in your configuration file.

You can verify that your configuration file works by starting Icinga 2:

----
$ /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf
[2013/04/23 13:36:20 +0200] <Main Thread> information/icinga-app: Icinga application loader (version: 0.0.1, git branch master, commit 0fcbfdb2)
[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Adding library search dir: /usr/lib/icinga2
[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Loading library 'libicinga.la'
[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Adding include search dir: /usr/share/icinga2
[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Compiling config file: /etc/icinga2/icinga2.conf
[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Linking config items...
[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Validating config items...
[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Activating config items in compilation unit 'b2d21c28-a2e8-4fcb-ba00-45646bc1afb9'
[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Restoring program state from file '/var/lib/icinga2/icinga2.state'
[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Restored 0 objects
----

In case there are any configuration errors Icinga 2 should print error messages
containing details about what went wrong.

You can stop Icinga 2 with Control-C:

----
^C
[2013/04/23 13:39:39 +0200] <TP 0x7f2e9070f500 Worker #0> information/base: Shutting down Icinga...
[2013/04/23 13:39:39 +0200] <TP 0x7f2e9070f500 Worker #0> information/base: Dumping program state to file '/var/lib/icinga2/icinga2.state'
[2013/04/23 13:39:39 +0200] <Main Thread> information/icinga: Icinga has shut down.
$
----

Icinga 2 automatically saves its current state every couple of minutes and when it's being shut down.

So far our Icinga 2 setup doesn't do much. Lets change that by setting up a service
check for localhost. Modify your 'icinga2.conf' configuration file by adding the following lines:

----
template Service "my-ping" inherits "plugin-service" {
	check_command = [
		"$plugindir$/check_ping",
		"-H", "$address$",
		"-w", "10,5%",
		"-c", "25,10%"
	]
}

object Host "localhost" {
	display_name = "Home, sweet home!",

	services["ping"] = {
		templates = [ "my-ping" ]
	},

	macros = {
		address = "127.0.0.1"
	},

	check_interval = 10s,

	hostcheck = "ping"
}
----

We're defining a service template called "my-ping" which inherits from the
'plugin-service' template. The 'plugin-service' template is provided as part of
the Icinga Template Library and describes how services are checked.
In the case of plugin-based services this means that the command specified by
the 'check_command' property is executed.

The 'check_command' property is an array or command-line arguments for the check
plugin. Alternatively you can specify the check command as a string.

The check command can make use of macros. Unlike in Icinga 1.x we have free-form
macros which means that users can choose arbitrary names for their macros.

By convention the following macros are usually used:

|===
|Macro       |Description
|plugindir   |The path of your check plugins.
|address     |The IPv4 address of the host.
|address6    |The IPv6 address of the host.
|===

Note that the 'my-ping' template does not define a value for the 'address' macro. This
is perfectly fine as long as that macro is defined somewhere else (e.g. in the host).

Next we're defining a 'Host' object called 'localhost'. We're setting an optional
display_name which is used by the CGIs when showing that host in the host overview.

The services dictionary defines which services belong to a host. Using the [] indexing
operator we can manipulate individual items in this dictionary. In this case we're creating
a new service called 'ping'.

The templates array inside the service definition lists all the templates we want to use
for this particular service. For now we're just listing our 'my-ping' template.

Remember how we used the 'address' macro in the 'check_command' setting earlier? Now we're
defining a value for this macro which is used for all services which belong to the 'localhost'
Host object.

We're also setting the check_interval for all services belonging to this host to
10 seconds.

NOTE: When you don't specify an explicit time unit Icinga 2 automatically assumes that
you meant seconds.

And finally we're specifying which of the services we've created before is used to define
the host's state. Note that unlike in Icinga 1.x this just "clones" the service's state
and does not cause any additional checks to be performed.

Setting up the Icinga 1.x CGIs
------------------------------

Icinga 2 can write status.dat and objects.cache files in the format that is supported
by the Icinga 1.x CGIs.

In order to enable this feature you will need to load the library 'compat' by adding the following lines
to your configuration file:

----
library "compat"

local object CompatComponent "compat" { }
----

After restarting Icinga 2 you should be able to find the status.dat and objects.cache files in
/var/cache/icinga2.

You can create symlinks in your Icinga 1.x installation directory to make the CGIs use
Icinga 2's status files and its command pipe:

----
cd /usr/local/icinga # Change this to your Icinga 1.x installation directory
ln -sf /var/cache/icinga2/status.dat var/status.dat
ln -sf /var/cache/icinga2/objects.cache var/objects.cache
ln -sf /var/run/icinga2/icinga2.cmd var/rw/icinga.cmd
----

Verify that your Icinga 1.x CGIs work by browsing to your CGI's installation URL.

Some More Templates
-------------------

Now that we've got our basic monitoring setup as well as the Icinga 1.x CGIs to work
we can define a second host. Add the following lines to your configuration file:

----
object Host "icinga.org" {
	display_name = "Icinga Website",

	services["ping"] = {
		templates = [ "my-ping" ]
	},

	macros = {
		address = "www.icinga.org"
	},

	check_interval = 10s,

	hostcheck = "ping"
}
----

Restart your Icinga 2 instance and check the CGIs for your new service's state. Unless
you have a low-latency network connection you will note that the service's state is 'CRITICAL'.
This is because in the 'my-ping' template we have hard-coded the timeout as 25 milliseconds.

Ideally we'd be able to specify different timeouts for our new service. Using macros we
can easily do this.

NOTE: If you've used Icinga 1.x before you're probably familiar with doing this by passing
ARGx macros to your check commands.

Start by replacing your 'my-ping' service template with this:

----
template Service "my-ping" inherits "plugin-service" {
	check_command = [
		"$plugindir$/check_ping",
		"-H", "$address$",
		"-w", "$wrta$,$wpl$%",
		"-c", "$crta$,$cpl$%"
	],

	macros = {
		wrta = 10,
		wpl = 5,

		crta = 25,
		cpl = 10
	}
}
----

We have replaced our hard-coded timeout values with macros and we're providing default
values for these same macros right in the template definition.

In order to oderride some of these macros for a specific host we need to update our
'icinga.org' host definition like this:

----
object Host "icinga.org" {
	display_name = "Icinga Website",

	services["ping"] = {
		templates = [ "my-ping" ],

		macros += {
			wrta = 100,
			crta = 250
		}
	},

	macros = {
		address = "www.icinga.org"
	},

	check_interval = 10s,

	hostcheck = "ping"
}
----

The '+=' operator allows us to selectively add new key-value pairs to an existing
dictionary. If we were to use the '=' operator instead we would have to provide
values for all the macros that are used in the 'my-ping' template.

Icinga Template Library
-----------------------

The Icinga Template Library is a collection of configuration templates for commonly
used services. By default it is installed in '/usr/share/icinga2/itl' and you can include
it in your configuration files using the include directive:

----
include <itl/itl.conf>
----

NOTE: Ordinarily you'd use double-quotes for the include path. This way only paths
relative to the current configuration file are considered. The angle brackets tell
Icinga 2 to search its list of global include directories.

One of the templates in the ITL is the 'ping4' template which is quite similar
to our own 'my-ping' template:

----
template Service "ping4" inherits "plugin-service" {
	check_command = [
		"$plugindir$/check_ping",
		"-4",
		"-H", "$address$",
		"-w", "$wrta$,$wpl$%",
		"-c", "$crta$,$cpl$%",
		"-p", "$packets$",
		"-t", "$timeout$"
	],

	macros = {
		wrta = 100,
		wpl = 5,

		crta = 200,
		cpl = 15,

		packets = 5,
		timeout = 0
	}
}
----

Lets simplify our configuration file by removing our custom 'my-ping' template and
updating our service definitions to use the 'ping4' template instead.

Include Files
-------------

So far we've been using just one configuration file. However, once you've created a
few more host objects and service templates this can get rather confusing.

Icinga 2 lets you include other files from your configuration file. We can use this
feature to make our configuration a bit more modular and easier to understand.

Lets start by moving our two 'Host' objects to a separate configuration file: hosts.conf

We will also need to tell Icinga 2 that it should include our newly created configuration
file when parsing the main configuration file. This can be done by adding the include
directive to our 'icinga2.conf' file:

----
include "hosts.conf"
----

Depending on the number of hosts you have it might be useful to split your configuration
files based on other criteria (e.g. device type, location, etc.).

You can use wildcards in the include path in order to refer to multiple files. Assuming
you're keeping your host configuration files in a directory called 'hosts' you could include
them like this:

----
include "hosts/*.conf"
----

Notifications
-------------

Icinga 2 can send you notifications when your services change state. In order to do this
we're going to write a shell script in '/etc/icinga2/mail-notification.sh' that sends
e-mail based notifications:

----
#!/bin/sh

if [ -z "$1" ]; then
	echo "Syntax: $0 <e-mail>"
	echo
	echo "Sends a mail notification to the specified e-mail address."
	exit 1
fi

mail -s "** $NOTIFICATIONTYPE Service Alert: $HOSTALIAS/$SERVICEDESC is $SERVICESTATE **" $1 <<TEXT
***** Icinga *****

Notification Type: $NOTIFICATIONTYPE

Service: $SERVICEDESC
Host: $HOSTALIAS
Address: $address
State: $SERVICESTATE

Date/Time: $LONGDATETIME

Additional Info:

$SERVICEOUTPUT
TEXT

exit 0
----

Our shell script uses a couple of pre-defined macros (e.g. SERVICEDESC, HOSTALIAS, etc.)
that are always available.

Next we're going to create a 'Notification' template which tells Icinga how to invoke
the shell script:

----
template Notification "mail-notification" inherits "plugin-notification" {
	notification_command = [
		"/etc/icinga2/mail-notification.sh",
		"$email$"
	],

	export_macros = [
		"NOTIFICATIONTYPE",
		"HOSTALIAS",
		"SERVICEDESC",
		"SERVICESTATE",
		"SERVICEDESC",
		"address",
		"LONGDATETIME",
		"SERVICEOUTPUT"
	]
}
----

NOTE: Rather than adding these templates to your main configuration file you might want
to create a separate file, e.g. 'notifications.conf' and include it in 'icinga2.conf'.

The 'export_macros' property tells Icinga which macros to export into the
environment for the notification script.

We also need to create a 'User' object which Icinga can use to send notifications
to specific people:

----
object User "tutorial-user" {
	display_name = "Some User",

	macros = {
		email = "tutorial@example.org"
	}
}
----

Each time a notification is sent for a service the user's macros are used when
resolving the macros we used in the 'Notification' template.

In the next step we're going to create a 'Service' template which specifies
who notifications should be sent to:

----
template Service "mail-notification-service" {
	notifications["mail"] = {
		templates = [ "mail-notification" ],

		users = [ "tutorial-user" ]
	},

	notification_interval = 1m
}
----

And finally we can assign this new service template to our services:

----
	...
	services["ping"] = {
		templates = [ "ping4", "mail-notification-service" ]
	},
	...
----

In addition to defining notifications for individual services it is also possible
to assign notification templates to all services of a host. You can find more
information about how to do that in the documentation.

Time Periods
------------

Time periods allow you to specify when certain services should be checked and when notifications
should be sent.

Here is an example time period definition:

----
object TimePeriod "work-hours" inherits "legacy-timeperiod" {
	ranges = {
		monday = "9:00-17:00",
		tuesday = "9:00-17:00",
		wednesday = "9:00-17:00",
		thursday = "9:00-17:00",
		friday = "9:00-17:00",
	}
}
----

The 'legacy-timeperiod' template is defined in the Icinga Template Library and supports Icinga 1.x
time periods. A complete definition of the time Icinga 1.x time period syntax can be found at
http://docs.icinga.org/latest/en/objectdefinitions.html#timeperiod.

Using the 'check_period' attribute you can define when services should be checked:

----
	...
	services["ping"] = {
		templates = [ "ping4", "mail-notification-service" ],
		check_period = "work-hours"
	},
	...
----

Also, using the 'notification_period' attribute you can define when notifications should be sent:

----
template Service "mail-notification-service" {
	notifications["mail"] = {
		templates = [ "mail-notification" ],

		users = [ "tutorial-user" ]
	},

	notification_interval = 1m,
	notification_period = "work-hours"
}
----

The 'notification_period' attribute is also valid in 'User' and 'Notification' objects.

Dependencies
------------

TODO

Performance Data
----------------

TODO

Compat Log Files
----------------

TODO