mirror of https://github.com/Icinga/icinga2.git
Update tutorial.
This commit is contained in:
Gunnar Beutner
parent
49c717c65e
commit
5a6876f81e
|
|
@ -7,21 +7,21 @@ Icinga 2 Configuration
|
|||
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:
|
||||
|
||||
|
|
@ -30,7 +30,7 @@ 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.
|
||||
|
|
@ -53,19 +53,20 @@ local object IcingaApplication "my-icinga" {
|
|||
}
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -86,7 +87,7 @@ $ /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf
|
|||
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
|
||||
|
|
@ -98,8 +99,8 @@ $
|
|||
|
||||
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" {
|
||||
|
|
@ -130,8 +131,9 @@ object Host "localhost" {
|
|||
|
||||
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.
|
||||
|
|
@ -148,11 +150,11 @@ By convention the following macros are usually used:
|
|||
|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
|
||||
|
|
@ -171,7 +173,7 @@ We're also setting the check_interval for all services belonging to this host to
|
|||
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.
|
||||
|
||||
|
|
@ -181,7 +183,7 @@ 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 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:
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
|
@ -208,8 +210,8 @@ Verify that your Icinga 1.x CGIs work by browsing to your CGI's installation URL
|
|||
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" {
|
||||
|
|
@ -231,10 +233,14 @@ 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:
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
|
@ -260,7 +266,7 @@ We have replaced our hard-coded timeout values with macros and we're providing d
|
|||
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" {
|
||||
|
|
@ -285,12 +291,64 @@ 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.
|
||||
|
||||
ITL
|
||||
---
|
||||
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.
|
||||
|
||||
TODO
|
||||
|
||||
|
|
@ -304,7 +362,12 @@ Time Periods
|
|||
|
||||
TODO
|
||||
|
||||
Host/Service Groups
|
||||
-------------------
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
TODO
|
||||
|
||||
Performance Data
|
||||
----------------
|
||||
|
||||
TODO
|
||||
|
|
|
|||
Loading…
Reference in New Issue