tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update tutorial.

This commit is contained in:
Gunnar Beutner 2013-04-24 09:35:58 +02:00
parent 49c717c65e
commit 5a6876f81e
1 changed files with 97 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
docs/icinga2-tutorial.txt
View File

@ -7,21 +7,21 @@ Icinga 2 Configuration
Preface Preface
------- -------
This tutorial is a step-by-step introduction to setting up Icinga 2 in order to This tutorial is a step-by-step introduction to installing Icinga 2 and setting
monitor network services. It assumes some familiarity with Icinga 1.x. up your first couple of service checks. It assumes some familiarity with Icinga 1.x.
Installation Installation
------------ ------------
In order to get started with Icinga 2 we will have to install it. The preferred way 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 of doing this is to use the official Debian or RPM packages depending on which Linux
you are running. distribution you are running.
<INSERT LIST OF PACKAGES HERE> <INSERT LIST OF PACKAGES HERE>
In case you're running a distribution for which Icinga 2 packages are not available 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 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. and read the 'INSTALL' file.
By default Icinga 2 uses the following files and directories: 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/icinga2 |Contains Icinga 2 configuration files.
|/etc/init.d/icinga2 |The Icinga 2 init script. |/etc/init.d/icinga2 |The Icinga 2 init script.
|/usr/share/doc/icinga2 |Documentation files that come with Icinga 2. |/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/run/icinga2 |Command pipe and PID file.
|/var/cache/icinga2 |Performance data files and status.dat/objects.cache. |/var/cache/icinga2 |Performance data files and status.dat/objects.cache.
|/var/lib/icinga2 |The Icinga 2 state file. |/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 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 which are distributed as part of Icinga 2. We will discuss the Icinga Template Library (ITL)
collection of templates for commonly used templates. 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. single-instance (i.e. non-clustered) mode.
Our configuration file also creates an object of type 'IcingaApplication' with the 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 name 'my-icinga'. The 'IcingaApplication' type can be used to define global macros and some
other global settings. other global settings.
For now we're only setting one global macro named 'plugindir' which you may need to update For now we're only defining the global macro 'plugindir' which we're going to use later on
with your plugin directory's path. 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: 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 In case there are any configuration errors Icinga 2 should print error messages
containing details about what went wrong. containing details about what went wrong.
You can stop Icinga 2 by hitting Control-C: You can stop Icinga 2 with Control-C:
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
^C ^C
@ -98,8 +99,8 @@ $
Icinga 2 automatically saves its current state every couple of minutes and when it's being 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. Edit your So far our Icinga 2 setup doesn't do much. Lets change that by setting up a service
'icinga2.conf' configuration file by adding the following lines: check for localhost. Modify your 'icinga2.conf' configuration file by adding the following lines:
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
template Service "my-ping" inherits "plugin-service" { 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 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 '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 the Icinga Template Library and describes how services are checked.
this means that the command specified by the 'check_command' property is executed. 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 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. 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. |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). 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 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 list. 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 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 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 NOTE: When you don't specify an explicit time unit Icinga 2 automatically assumes that
you meant seconds. 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 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. 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 Icinga 2 can write status.dat and objects.cache files in the format that is supported
by the Icinga 1.x CGIs. 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: 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 Some More Templates
------------------- -------------------
Now that we've got a work basic monitoring setup as well as the CGIs we can define Now that we've got our basic monitoring setup as well as the Icinga 1.x CGIs to work
a second host. Add the following lines to your configuration file: we can define a second host. Add the following lines to your configuration file:
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
object Host "icinga.org" { 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 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'. 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 Ideally we'd be able to specify different timeouts for our new service. Using macros we
can easily do this. 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: 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. 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 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" { 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 The '+=' operator allows us to selectively add new key-value pairs to an existing
to use the '=' operator instead we would have to provide values for all the macros from dictionary. If we were to use the '=' operator instead we would have to provide
the 'my-ping' template. 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 TODO
@ -304,7 +362,12 @@ Time Periods
TODO TODO
Host/Service Groups Dependencies
------------------- ------------
TODO
Performance Data
----------------
TODO TODO