Preface
-------
-This tutorial is a step-by-step introduction to setting up Icinga 2 in order to
-monitor network services. It assumes some familiarity with Icinga 1.x.
+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 Debian or RPM packages depending on which Linux distribution
-you are running.
+of doing this is to use the official Debian or RPM packages depending on which Linux
+distribution you are running.
<INSERT LIST OF PACKAGES HERE>
-In case you're running a distribution for which Icinga 2 packages are not available
-you will have to check out the Icinga 2 git repository from git://git.icinga.org/icinga2
-and run the "autogen.sh" script and follow its instructions to get Icinga 2 installed.
+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:
|/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 (a collection of configuration fragments).
+|/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.
}
-------------------------------------------------------------------------------
-The configuration snippet includes the "itl/itl.conf" and "itl/standalone.conf" files
-which are distributed as part of Icinga 2. The Icinga Template Library (ITL) is a
-collection of templates for commonly used templates.
+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
+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 setting one global macro named 'plugindir' which you may need to update
-with your plugin directory's path.
+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:
In case there are any configuration errors Icinga 2 should print error messages
containing details about what went wrong.
-You can stop Icinga 2 by hitting Control-C:
+You can stop Icinga 2 with Control-C:
-------------------------------------------------------------------------------
^C
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. Edit your
-'icinga2.conf' configuration file by adding the following lines:
+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" {
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 ITL 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 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.
|address6 |The IPv6 address of the host.
|===
-Note how the 'my-ping' template does not define a value for the 'address' macro. This
+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 with name 'localhost'. We're setting an optional
-display_name which is used by the CGIs when showing that host in the host list.
+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
NOTE: When you don't specify an explicit time unit Icinga 2 automatically assumes that
you meant seconds.
-And finally we're defining which of the services we've defined before is used to define
+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.
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 do this you will need to load the library 'compat' by adding the following lines
+In order to enable this feature you will need to load the library 'compat' by adding the following lines
to your configuration file:
-------------------------------------------------------------------------------
Some More Templates
-------------------
-Now that we've got a work basic monitoring setup as well as the CGIs we can define
-a second host. Add the following lines to your configuration file:
+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" {
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:
-------------------------------------------------------------------------------
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
-host 'icinga.org' like this:
+'icinga.org' host definition like this:
-------------------------------------------------------------------------------
object Host "icinga.org" {
}
-------------------------------------------------------------------------------
-The '+=' operator allows us to selectively modify an existing dictionary. If we were
-to use the '=' operator instead we would have to provide values for all the macros from
-the 'my-ping' template.
+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.
-ITL
----
+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.
TODO
TODO
-Host/Service Groups
--------------------
+Dependencies
+------------
+
+TODO
+
+Performance Data
+----------------
TODO
projects / icinga2 / commitdiff