mirror of
https://github.com/Icinga/icinga2.git
synced 2025-07-25 22:54:57 +02:00
Update config syntax documentation. Add install/config tutorial.
This commit is contained in:
Gunnar Beutner
parent
a8e3d794ac
commit
49c717c65e
@ -1,8 +1,10 @@
|
|||||||
.PHONY: clean
|
.PHONY: clean
|
||||||
|
|
||||||
EXTRA_DIST = \
|
EXTRA_DIST = \
|
||||||
icinga2-config.txt \
|
icinga2-config-syntax.txt \
|
||||||
|
icinga2-config-types.txt \
|
||||||
icinga2-intro.txt \
|
icinga2-intro.txt \
|
||||||
|
icinga2-tutorial.txt \
|
||||||
icinga2.8
|
icinga2.8
|
||||||
|
|
||||||
icinga2docdir = ${docdir}
|
icinga2docdir = ${docdir}
|
||||||
@ -15,8 +17,10 @@ man8_MANS = \
|
|||||||
|
|
||||||
if AD_COND_doc
|
if AD_COND_doc
|
||||||
icinga2doc_DATA += \
|
icinga2doc_DATA += \
|
||||||
icinga2-config.html \
|
icinga2-config-syntax.html \
|
||||||
icinga2-intro.html
|
icinga2-config-types.html \
|
||||||
|
icinga2-intro.html \
|
||||||
|
icinga2-tutorial.html
|
||||||
|
|
||||||
.txt.html:
|
.txt.html:
|
||||||
$(AD_ENV) $(AD_ASCIIDOC) -a toc -a numbered -o $@ $<
|
$(AD_ENV) $(AD_ASCIIDOC) -a toc -a numbered -o $@ $<
|
||||||
|
|||||||
449
docs/icinga2-config-syntax.txt
Normal file
449
docs/icinga2-config-syntax.txt
Normal file
@ -0,0 +1,449 @@
|
|||||||
|
Icinga 2 Configuration
|
||||||
|
======================
|
||||||
|
|
||||||
|
:keywords: Icinga, documentation, configuration
|
||||||
|
:description: Description of the Icinga 2 config
|
||||||
|
|
||||||
|
Configuration Syntax
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Object Definition
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Icinga 2 features an object-based configuration format. In order to define
|
||||||
|
objects the 'object' keyword is used:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
object Host "host1.example.org" {
|
||||||
|
display_name = "host1",
|
||||||
|
|
||||||
|
check_interval = 30,
|
||||||
|
retry_interval = 15,
|
||||||
|
|
||||||
|
macros = {
|
||||||
|
address = "192.168.0.1"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: The Icinga 2 configuration format is agnostic to whitespaces and
|
||||||
|
new-lines.
|
||||||
|
|
||||||
|
Each object is uniquely identified by its type ('Host') and name
|
||||||
|
('host1.example.org'). Objects can contain a comma-separated list of property
|
||||||
|
declarations. The following data types are available for property values:
|
||||||
|
|
||||||
|
Numeric Literals
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
A floating-point number.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
-27.3
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Duration Literal
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Similar to floating-point numbers except for that fact that they support
|
||||||
|
suffixes to help with specifying time durations.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
2.5m
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Supported suffixes include ms (milliseconds), s (seconds), m (minutes) and h (hours).
|
||||||
|
|
||||||
|
String Literals
|
||||||
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
A string.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
"Hello World!"
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Certain characters need to be escaped. The following escape sequences are supported:
|
||||||
|
|
||||||
|
|===================================
|
||||||
|
|Character |Escape sequence
|
||||||
|
|" |\"
|
||||||
|
|<TAB> |\t
|
||||||
|
|<CARRIAGE-RETURN> |\r
|
||||||
|
|<LINE-FEED> |\n
|
||||||
|
|<BEL> |\b
|
||||||
|
|<FORM-FEED> |\f
|
||||||
|
|===================================
|
||||||
|
|
||||||
|
In addition to these pre-defined escape sequences you can specify arbitrary ASCII
|
||||||
|
characters using the backslash character (\) followed by an ASCII character in
|
||||||
|
octal encoding.
|
||||||
|
|
||||||
|
Multiline String Literals
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Strings spanning multiple lines can be specified by enclosing them in {{{ and }}}.
|
||||||
|
|
||||||
|
Example.
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{{{This
|
||||||
|
is
|
||||||
|
a multi-line
|
||||||
|
string.}}}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Boolean Literals
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The keywords 'true' and 'false' are equivalent to 1 and 0 respectively.
|
||||||
|
|
||||||
|
Null Value
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
The 'null' keyword can be used to specify an empty value.
|
||||||
|
|
||||||
|
Dictionary
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
An unordered list of key-value pairs. Keys must be unique and are compared in
|
||||||
|
a case-insensitive manner.
|
||||||
|
|
||||||
|
Individual key-value pairs must be separated from each other with a comma. The
|
||||||
|
comma after the last key-value pair is optional.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
address = "192.168.0.1",
|
||||||
|
port = 443
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: Identifiers may not contain certain characters (e.g. space) or start with
|
||||||
|
certain characters (e.g. digits). If you want to use a dictionary key that is
|
||||||
|
not a valid identifier you can put the key in double quotes.
|
||||||
|
|
||||||
|
NOTE: Setting a dictionary key to null causes the key to be removed from the
|
||||||
|
dictionary.
|
||||||
|
|
||||||
|
Array
|
||||||
|
^^^^^
|
||||||
|
|
||||||
|
An ordered list of values.
|
||||||
|
|
||||||
|
Individual array elements must be separated from each other with a comma. The
|
||||||
|
comma after the last element is optional.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
[
|
||||||
|
"hello",
|
||||||
|
"world",
|
||||||
|
42,
|
||||||
|
[ "a", "nested", "array" ]
|
||||||
|
]
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: An array may simultaneously contain values of different types, e.g.
|
||||||
|
strings and numbers.
|
||||||
|
|
||||||
|
Operators
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
In addition to the '=' operator shown above a number of other operators to
|
||||||
|
manipulate configuration objects are supported. Here's a list of all available
|
||||||
|
operators:
|
||||||
|
|
||||||
|
Operator '='
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Sets a dictionary element to the specified value.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
a = 5,
|
||||||
|
a = 7
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
In this example a has the value 7 after both instructions are executed.
|
||||||
|
|
||||||
|
Operator '+='
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Modifies a dictionary or array by adding new elements to it.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
a = [ "hello" ],
|
||||||
|
a += [ "world" ]
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
In this example a contains both '"hello"' and '"world"'. This currently only works
|
||||||
|
for dictionaries and arrays. Support for numbers might be added later on.
|
||||||
|
|
||||||
|
Operator '-='
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Removes elements from a dictionary.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
a = { "hello", "world" },
|
||||||
|
a -= { "world" }
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
In this example a contains '"hello"'. Trying to remove an item that does not
|
||||||
|
exist is not an error. Not implemented yet.
|
||||||
|
|
||||||
|
Operator '*='
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Multiplies an existing dictionary element with the specified number. If the
|
||||||
|
dictionary element does not already exist 0 is used as its value.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
a = 60,
|
||||||
|
a *= 5
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
In this example a is 300. This only works for numbers. Not implemented yet.
|
||||||
|
|
||||||
|
Operator '/='
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Divides an existing dictionary element by the specified number. If the
|
||||||
|
dictionary element does not already exist 0 is used as its value.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
a = 300,
|
||||||
|
a /= 5
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
In this example a is 60. This only works for numbers. Not implemented yet.
|
||||||
|
|
||||||
|
Attribute Shortcuts
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Indexer Shortcut
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
hello["key"] = "world"
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
This is equivalent to writing:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
{
|
||||||
|
hello += {
|
||||||
|
key = "world"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Specifiers
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
Objects can have specifiers that have special meaning. The following specifiers
|
||||||
|
can be used (prefacing the 'object' keyword):
|
||||||
|
|
||||||
|
Specifier 'abstract'
|
||||||
|
^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This specifier identifies the object as a template which can be used by other
|
||||||
|
object definitions. The object will not be instantiated on its own.
|
||||||
|
|
||||||
|
Instead of using the 'abstract' specifier you can use the 'template' keyword
|
||||||
|
which is a shorthand for writing 'abstract object':
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
template Service "http" {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Specifier 'local'
|
||||||
|
^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This specifier disables replication for this object. The object will not be
|
||||||
|
sent to remote Icinga instances.
|
||||||
|
|
||||||
|
Inheritance
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
Objects can inherit attributes from one or more other objects.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
template Host "default-host" {
|
||||||
|
check_interval = 30,
|
||||||
|
|
||||||
|
macros = {
|
||||||
|
color = "red"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
template Host "test-host" inherits "default-host" {
|
||||||
|
macros += {
|
||||||
|
color = "blue"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
object Host "localhost" inherits "test-host" {
|
||||||
|
macros += {
|
||||||
|
address = "127.0.0.1",
|
||||||
|
address6 = "::1"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: The '"default-host"' and '"test-host"' objects are marked as templates using
|
||||||
|
the 'abstract' keyword. Parent objects do not necessarily have to be 'abstract'
|
||||||
|
though in general they are.
|
||||||
|
|
||||||
|
NOTE: The += operator is used to insert additional properties into the macros
|
||||||
|
dictionary. The final dictionary contains all 3 macros and the property 'color'
|
||||||
|
has the value '"blue"'.
|
||||||
|
|
||||||
|
Parent objects are resolved in the order they're specified using the 'inherits'
|
||||||
|
keyword.
|
||||||
|
|
||||||
|
Comments
|
||||||
|
~~~~~~~~
|
||||||
|
|
||||||
|
The Icinga 2 configuration format supports C/C++-style comments.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
/*
|
||||||
|
This is a comment.
|
||||||
|
*/
|
||||||
|
object Host "localhost" {
|
||||||
|
check_interval = 30, // this is also a comment.
|
||||||
|
retry_interval = 15
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Includes
|
||||||
|
~~~~~~~~
|
||||||
|
|
||||||
|
Other configuration files can be included using the 'include' directive. Paths
|
||||||
|
must be relative to the configuration file that contains the 'include'
|
||||||
|
directive.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
include "some/other/file.conf"
|
||||||
|
include "conf.d/*.conf"
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: Wildcard includes are not recursive.
|
||||||
|
|
||||||
|
Icinga also supports include search paths similar to how they work in a
|
||||||
|
C/C++ compiler:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
include <itl/itl.conf>
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Note the use of angle brackets instead of double quotes. This causes the
|
||||||
|
config compiler to search the include search paths for the specified file.
|
||||||
|
By default $PREFIX/icinga2 is included in the list of search paths.
|
||||||
|
|
||||||
|
Wildcards are not permitted when using angle brackets.
|
||||||
|
|
||||||
|
Library directive
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The 'library' directive can be used to manually load additional libraries.
|
||||||
|
Upon loading these libraries may provide additional types or methods.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
library "snmphelper"
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
NOTE: The 'icinga' library is automatically loaded at startup.
|
||||||
|
|
||||||
|
Type Definition
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
By default Icinga has no way of semantically verifying its configuration
|
||||||
|
objects. This is where type definitions come in. Using type definitions you
|
||||||
|
can specify which attributes are allowed in an object definition.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
type Pizza {
|
||||||
|
%require "radius",
|
||||||
|
%attribute number "radius",
|
||||||
|
|
||||||
|
%attribute dictionary "ingredients" {
|
||||||
|
%validator "ValidateIngredients",
|
||||||
|
|
||||||
|
%attribute string "*",
|
||||||
|
|
||||||
|
%attribute dictionary "*" {
|
||||||
|
%attribute number "quantity",
|
||||||
|
%attribute string "name"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
|
||||||
|
%attribute any "custom::*"
|
||||||
|
}
|
||||||
|
-------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
The Pizza definition provides the following validation rules:
|
||||||
|
|
||||||
|
* Pizza objects must contain an attribute 'radius' which has to be a number.
|
||||||
|
* Pizza objects may contain an attribute 'ingredients' which has to be a
|
||||||
|
dictionary.
|
||||||
|
* Elements in the ingredients dictionary can be either a string or a dictionary.
|
||||||
|
* If they're a dictionary they may contain attributes 'quantity' (of type
|
||||||
|
number) and 'name' (of type string).
|
||||||
|
* The script function 'ValidateIngredients' is run to perform further
|
||||||
|
validation of the ingredients dictionary.
|
||||||
|
* Pizza objects may contain attribute matching the pattern 'custom::*' of any
|
||||||
|
type.
|
||||||
|
|
||||||
|
Valid types for type rules include:
|
||||||
|
* any
|
||||||
|
* number
|
||||||
|
* string
|
||||||
|
* scalar (an alias for string)
|
||||||
|
* dictionary
|
||||||
310
docs/icinga2-tutorial.txt
Normal file
310
docs/icinga2-tutorial.txt
Normal file
@ -0,0 +1,310 @@
|
|||||||
|
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 setting up Icinga 2 in order to
|
||||||
|
monitor network services. 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.
|
||||||
|
|
||||||
|
<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.
|
||||||
|
|
||||||
|
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 (a collection of configuration fragments).
|
||||||
|
|/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. The Icinga Template Library (ITL) is a
|
||||||
|
collection of templates for commonly used templates.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 by hitting 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. Edit 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 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 '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 how 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.
|
||||||
|
|
||||||
|
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 defining which of the services we've defined 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 do this 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 a work basic monitoring setup as well as the CGIs 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'.
|
||||||
|
|
||||||
|
Ideally we'd be able to specify different timeouts for our new service. Using macros we
|
||||||
|
can easily do this.
|
||||||
|
|
||||||
|
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
|
||||||
|
host 'icinga.org' 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 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.
|
||||||
|
|
||||||
|
ITL
|
||||||
|
---
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
Notifications
|
||||||
|
-------------
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
Time Periods
|
||||||
|
------------
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
Host/Service Groups
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
TODO
|
||||||
Loading…
x
Reference in New Issue
Block a user