82 KiB
Icinga 2 Main
Introduction
A detailed introduction can be found in the chapter Introduction. /* TODO insert url */
Installation
For more information see the chapter Installation. /* TODO insert url */
Quick Example
/* TODO */
For a general tutorial see the chapter Tutorial. /* TODO insert url */
Requirements
/* TODO */
License
Icinga 2 is licensed under the GPLv2 license, a copy of this license can be found in the LICENSE file on the main source tree.
Community
-
#icinga on the Freenode IRC Network
More details at http://www.icinga.org/support/
Support
For more information on the support options refer to https://www.icinga.org/support
Chapters
/* TODO */
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Introduction
Icinga 2 is a network monitoring application that tries to improve upon the success of Icinga 1.x while fixing some of its shortcomings. A few frequently encountered issues are:
-
Scalability problems in large monitoring setups
-
Difficult configuration with dozens of "magic" tweaks and several ways of defining services
-
Code quality and the resulting inability to implement changes without breaking add-ons
-
Limited access to the runtime state of Icinga (e.g. for querying a service’s state or for dynamically creating new services)
Fixing these issues would involve major breaking changes to the Icinga 1.x core and configuration syntax. Icinga users would likely experience plenty of problems with the Icinga versions introducing these changes. Many of these changes would likely break add-ons which rely on the NEB API and other core internals.
From a developer standpoint this may be justifiable in order to get to a better end-product. However, for (business) users spending time on getting familiar with these changes for each new version may become quite frustrating and may easily cause users to lose their confidence in Icinga.
Nagios™ 4 is currently following this approach and it remains to be seen how this fares with its users.
Instead the Icinga project will maintain two active development branches. There will be one branch for Icinga 1.x which focuses on improving the existing Icinga 1.x code base - just like it has been done so far.
Independently from Icinga 1.x development on Icinga 2 will happen in a separate branch and some of the long-term design goals will be outlined in this document. Status updates for Icinga 2 will be posted on the project website (www.icinga.org) as they become available.
Code Quality
Icinga 2 will not be using any code from the Icinga 1.x branch due to the rampant code quality issues with the existing code base. However, an important property of the Icinga development process has always been to rely on proven technologies and Icinga 2 will be no exception.
A lot of effort has gone into designing a maintainable architecture for Icinga 2 and making sure that algorithmic choices are in alignment with our scalability goals for Icinga 2.
There are plans to implement unit tests for most Icinga 2 features in order to make sure that changes to the code base do not break things that were known to work before.
Language Choice
Icinga 1.x is written in C and while in general C has quite a number of advantages (e.g. performance and relatively easy portability to other *NIX- based platforms) some of its disadvantages show in the context of a project that is as large as Icinga.
With a complex software project like Icinga an object-oriented design helps tremendously with keeping things modular and making changes to the existing code easier.
While it is true that you can write object-oriented software in C (the Linux kernel is one of the best examples of how to do that) a truly object-oriented language makes the programmers' life just a little bit easier.
For Icinga 2 we have chosen C++ as the main language. This decision was influenced by a number of criteria including performance, support on different platforms and general user acceptability.
In general there is nothing wrong with other languages like Java, C# or Python; however - even when ignoring technical problems for just a moment - in a community as conservative as the monitoring community these languages seem out of place.
Knowing that users will likely want to run Icinga 2 on older systems (which are still fully vendor-supported even for years to come) we will make every effort to ensure that Icinga 2 can be built and run on commonly used operating systems and refrain from using new and exotic features like C++11.
Unlike Icinga 1.x there will be Windows support for Icinga 2. Some of the compatibility features (e.g. the command pipe) which rely on *NIX features may not be supported on Windows but all new features will be designed in such a way as to support *NIX as well as Windows.
Configuration
Icinga 1.x has a configuration format that is fully backwards-compatible to the Nagios™ configuration format. This has the advantage of allowing users to easily upgrade their existing Nagios™ installations as well as downgrading if they choose to do so (even though this is generally not the case).
The Nagios™ configuration format has evolved organically over time and for the most part it does what it’s supposed to do. However this evolutionary process has brought with it a number of problems that make it difficult for new users to understand the full breadth of available options and ways of setting up their monitoring environment.
Experience with other configuration formats like the one used by Puppet has shown that it is often better to have a single "right" way of doing things rather than having multiple ways like Nagios™ does (e.g. defining host/service dependencies and parent/child relationships for hosts).
Icinga 2 tries to fix those issues by introducing a new object-based configuration format that is heavily based on templates and supports user-friendly features like freely definable macros.
External Interfaces
While Icinga 1.x has easily accessible interfaces to its internal state (e.g. status.dat, objects.cache and the command pipe) there is no standards-based way of getting that information.
For example, using Icinga’s status information in a custom script generally involves writing a parser for the status.dat format and there are literally dozens of Icinga-specific status.dat parsers out there.
While Icinga 2 will support these legacy interfaces in order to make migration easier and allowing users to use the existing CGIs and whatever other scripts they may have Icinga 2 will focus on providing a unified interface to Icinga’s state and providing similar functionality to that provided by the command pipe in Icinga 1.x. The exact details for such an interface are yet to be determined but this will likely be an RPC interface based on one of the commonly used web-based remoting technologies.
Icinga 1.x exports historical data using the IDO database interface (Icinga Data Output). Icinga 2 will support IDO in a backwards-compatible fashion in order to support icinga-web. Additionally there will be a newly-designed backend for historical data which can be queried using the built-in API when available. Effort will be put into making this new data source more efficient for use with SLA reporting.
Icinga 2 will also feature dynamic reconfiguration using the API which means users can create, delete and update any configuration object (e.g. hosts and services) on-the-fly. Based on the API there are plans to implement a command-line configuration tool similar to what Pacemaker has with "crm". Later on this API may also be used to implement auto-discovery for new services.
The RPC interface may also be used to receive events in real-time, e.g. when service checks are being executed or when a service’s state changes. Some possible uses of this interface would be to export performance data for services (RRD, graphite, etc.) or general log information (logstash, graylog2, etc.).
Checks
In Icinga 2 services are the only checkable objects. Hosts only have a calculated state and no check are ever run for them.
In order to maintain compatibility with the hundreds of existing check plugins for Icinga 1.x there will be support for Nagios™-style checks. The check interface however will be modular so that support for other kinds of checks can be implemented later on (e.g. built-in checks for commonly used services like PING, HTTP, etc. in order to avoid spawning a process for each check).
Based on the availability of remote Icinga 2 instances the core can delegate execution of service checks to them in order to support large-scale distributed setups with a minimal amount of maintenance. Services can be assigned to specific check instances using configuration settings.
Notifications
Event handlers and notifications will be supported similar to Icinga 1.x. Thanks to the dynamic configuration it is possible to easily adjust the notification settings at runtime (e.g. in order to implement on-call rotation).
Scalability
Icinga 1.x has some serious scalability issues which explains why there are several add-ons which try to improve the core’s check performance. One of these add-ons is mod_gearman which can be used to distribute checks to multiple workers running on remote systems.
A problem that remains is the performance of the core when processing check results. Scaling Icinga 1.x beyond 25.000 services proves to be a challenging problem and usually involves setting up a cascade of Icinga 1.x instances and dividing the service checks between those instances. This significantly increases the maintenance overhead when updating the configuration for such a setup.
Icinga 2 natively supports setting up multiple Icinga 2 instances in a cluster to distribute work between those instances. Independent tasks (e.g. performing service checks, sending notifications, updating the history database, etc.) are implemented as components which can be loaded for each instance. Configuration as well as program state is automatically replicated between instances.
In order to support using Icinga 2 in a partially trusted environment SSL is used for all network communication between individual instances. Objects (like hosts and services) can be grouped into security domains for which permissions can be specified on a per-instance basis (so e.g. you can have a separate API or checker instance for a specific domain).
Agent-based Checks
Traditionally most service checks have been performed actively, meaning that check plugins are executed on the same server that is also running Icinga. This works great for checking most network-based services, e.g. PING and HTTP. However, there are a number of services which cannot be checked remotely either because they are not network-based or because firewall settings or network policies ("no unencrypted traffic") disallow accessing these services from the network where Icinga is running.
To solve this problem two add-ons have emerged, namely NRPE and NSCA. NRPE can be thought of as a light-weight remote shell which allows the execution of a restricted set of commands while supporting some Nagios™-specific concepts like command timeouts. However unlike with the design of commonly used protocols like SSH security in NRPE is merely an afterthought.
In most monitoring setups all NRPE agents share the same secret key which is embedded into the NRPE binary at compile time. This means that users can extract this secret key from their NRPE agent binary and use it to query sensitive monitoring information from other systems running the same NRPE binary. NSCA has similar problems.
Based on Icinga 2’s code for check execution there will be an agent which can be used on *NIX as well as on Windows platforms. The agent will be using the same configuration format like Icinga 2 itself and will support SSL and IPv4/IPv6 to communicate with Icinga 2.
Business Processes
In most cases users don’t care about the availability of individual services but rather the aggregated state of multiple related services. For example one might have a database cluster that is used for a web shop. For an end-user the shop is available as long as at least one of the database servers is working.
Icinga 1.x does not have any support for business processes out of the box. There are several add-ons which implement business process support for Icinga, however none of those are well-integrated into Icinga.
Icinga 2 will have native support for business processes which are built right into the core and can be configured in a similar manner to Nagios™-style checks. Users can define their own services based on business rules which can be used as dependencies for other hosts or services.
Logging
Icinga 2 supports file-based logged as well as syslog (on *NIX) and event log (on Windows). Additionally Icinga 2 supports remote logging to a central Icinga 2 instance.
Icinga 2 Installation
Requirements
Packages
Note
Use packages whenever possible.
Distribution Package URL Debian TBD RHEL/CentOS TBD SLES TBD
In case you’re running a distribution for which Icinga 2 packages are not yet available download the source tarball and jump to Source Builds.
Windows Installer
TODO
Source Builds
Download the source tarball and read the INSTALL file for details and requirements.
Linux Builds
Building from source on specific linux distributions is described on the wiki: https://wiki.icinga.org/display/icinga2/Linux+Builds
Windows Builds
Icinga 2 ships a MS Visual Studio solution file. Requirements and compilation instructions can be found on the wiki: https://wiki.icinga.org/display/icinga2/Windows+Builds
Installation Locations
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.
/* TODO */
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Migration
Purpose
Documentation on the general migration from Icinga 1.x to Icinga 2.
Requirements
Multi-core cpu, ram, fast disks.
Installation
Icinga 1.x and Icinga 2 may run side by side, but it’s recommended to backup your existing 1.x installation before installing Icinga 2 on the same host.
Compatibility
Note
The configuration format changed from 1.x to 2.x. Don’t panic though. A conversion script is shipped in tools/configconvert - please check the README file.
For details check the chapter Compatibility.
Changes
For details check the chapter Changes.
TODO
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Compatibility
Purpose
Documentation on the compatibility and changes introduced with Icinga 2.
Introduction
Unlike Icinga 1.x, all used components (not only those for compatibility) run asynchronous and use queues, if required. That way Icinga 2 does not get blocked by any event, action or execution.
Configuration
Note
If you are upgrading from Icinga 1.x (or Nagios 3.x+) please note that Icinga 2 introduces a new configuration format.
Details on the configuration can be found in chapter Configuration
Icinga 2 ships a config conversion script which will help you migrating the existing configuration into the new format. Please look into the tools/configconvert directory and follow the README instructions.
Tip
If you kept planning to clean up your existing configuration, it may be a good shot to start fresh with a new configuration strategy based on the Icinga 2 configuration logic.
Check Plugins
All native check plugins can be used with Icinga 2. The configuration of check commands is changed due to the new configuration format.
Classic status and log files
Icinga 2 will write status.dat and objects.cache in a given interval like known from Icinga 1.x - including the logs and their archives in the old format and naming syntax. That way you can point any existing Classic UI installation to the new locations (or any other addon/plugin using them).
External Commands
Like known from Icinga 1.x, Icinga 2 also provides an external command pipe allowing your scripts and guis to send commands to the core triggering various actions.
Some commands are not supported though as their triggered functionality is not available in Icinga 2 anymore.
For a detailed list, please check: https://wiki.icinga.org/display/icinga2/External+Commands
Performance Data
The Icinga 1.x Plugin API defines the performance data format. Icinga 2 parses the check output accordingly and writes performance data files based on template macros. File rotation interval can be defined as well.
Unlike Icinga 1.x you can define multiple performance data writers for all your graphing addons such as PNP, inGraph or graphite.
IDO DB
Icinga 1.x uses an addon called IDOUtils to store core configuration, status and historical information in a database schema. Icinga Web and Reporting are using that database as their chosen backend.
Icinga 2 is compatible to the IDO db schema but the the underlaying design of inserting, updating and deleting data is different - asynchronous queueing, database transactions and optimized queries for performance.
Furthermore there is no seperated daemon to receive the data through a socket. Instead the IDO component queues the data and writes directly into the database using the native database driver library (e.g. libmysqlclient). Unlike Icinga 1.x libdbi as db abstraction layer is not used anymore.
Livestatus
Icinga 2 supports the livestatus api while using Icinga 1.x an addon named mk_livestatus was required.
Next to the GET functionality for retrieving configuration, status and historical data, Icinga 2 livestatus also supports the COMMANDS functionality.
Tip
Icinga 2 supports tcp sockets natively while the Icinga 1.x addon only provides unix socket support.
Checkresult Reaper
Unlike Icinga 1.x Icinga 2 is a multithreaded application and processes check results in memory. The old checkresult reaper reading files from disk again is obviously not required anymore for native checks.
Some popular addons have been injecting their checkresults into the Icinga 1.x checkresult spool directory bypassing the external command pipe and PROCESS_SERVICE_CHECK_RESULT mainly for performance reasons.
In order to support that functionality as well, Icinga 2 got its optional checkresult reaper.
Changes
This is a collection of known changes in behaviour, configuration and outputs.
Note
May be incomplete, and requires updates in the future.
TODO
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Tutorial
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:808 0/job/icinga2/](http://icingabuild.d us.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>
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/bin/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:
object CheckCommand "my-ping" inherits "plugin-check-command" {
command = [
"$plugindir$/check_ping",
"-H", "$address$",
"-w", "10,5%",
"-c", "25,10%"
]
}
template Service "my-ping" inherits "plugin-service" {
check_command = "my-ping"
}
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 command object called "my-ping" which inherits from the plugin-check-command template. The plugin-check-command template is provided as part of the Icinga Template Library and describes how checks are performed. In the case of plugin-based services this means that the command specified by the command property is executed.
The 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 command object 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).
We’re also defining a service template called my-ping which uses the command object we just created.
Next we’re defining a Host object called localhost. We’re setting an optional display_name which is used by the Icinga Classic UI 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 command setting earlier? Now we’re defining a value for this macro which is used for all services and their commands 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 Classic UI
Icinga 2 can write status.dat and objects.cache files in the format that is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the "command pipe") are also supported. If you require the icinga.log for history views and/or reporting in Classic UI, this can be added seperately to the CompatComponent object definition by adding a CompatLog object.
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"
object CompatComponent "compat" { }
object CompatLog "my-log" { }
After restarting Icinga 2 you should be able to find the status.dat and objects.cache files in /var/cache/icinga2. The log files can be found in /var/log/icinga2/compat. The command pipe can be found in /var/run/icinga2.
You can install the Icinga 1.x Classic UI in standalone mode using the following commands:
$ wget http://downloads.sourceforge.net/project/icinga/icinga/1.9.0/icinga-1.9.0.tar.gz
$ tar xzf icinga-1.9.0.tar.gz ; cd icinga-1.9.0
$ ./configure --enable-classicui-standalone --prefix=/usr/local/icinga2-classicui
$ make classicui-standalone
$ sudo make install classicui-standalone install-webconf-auth
$ sudo service apache2 restart
Note
A detailed guide on installing Icinga 1.x Classic UI Standalone can be found on the Icinga Wiki here: https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone
After installing the Classic UI you will need to update the following settings in your cgi.cfg configuration file at the bottom (section "STANDALONE (ICINGA 2) OPTIONS"):
Configuration Setting Value object_cache_file /var/cache/icinga2/objects.cache status_file /var/cache/icinga2/status.dat resource_file - command_file /var/run/icinga2/icinga2.cmd check_external_commands 1 interval_length 60 status_update_interval 10 log_file /var/log/icinga2/compat/icinga.log log_rotation_method h log_archive_path /var/log/icinga2/compat/archives date_format us
Depending on how you installed Icinga 2 some of those paths and options might be different.
Note
You need to grant permissions for the apache user manually after starting Icinga 2 for now.
# chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
Verify that your Icinga 1.x Classic UI works by browsing to your Classic UI installation URL e.g. http://localhost/icinga
Some More Templates
Now that we’ve got our basic monitoring setup as well as the Icinga 1.x Classic UI 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 Classic UI 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 command object 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 command object with this:
object CheckCommand "my-ping" inherits "plugin-check-command" {
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. The object inherits the basic check command attributes from the ITL provided template plugin-check-command.
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 overriding all values there.
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 service template which is quite similar to our example objects:
object CheckCommand "ping4" inherits "plugin-check-command" {
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
}
}
template Service "ping4" {
check_command = "ping4"
}
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:
object NotificationCommand "mail-notification" inherits "plugin-notification-command" {
command = [
"/etc/icinga2/mail-notification.sh",
"$email$"
],
export_macros = [
"NOTIFICATIONTYPE",
"HOSTALIAS",
"SERVICEDESC",
"SERVICESTATE",
"SERVICEDESC",
"address",
"LONGDATETIME",
"SERVICEOUTPUT"
]
}
template Notification "mail-notification" {
notification_command = "mail-notification"
}
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.
Note
Escalations in Icinga 2 are just a notification, only added a defined begin and end time. Check the documentation for details.
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
If you are familiar with Icinga 1.x host/service dependencies and parent/child relations on hosts, you might want to look at the conversion script in order to convert your existing configuration. There are no separate dependency objects anymore, and no separate parent attribute either.
Using Icinga 2, we can directly define a dependency in the current host or service object to any other host or service object. If we want other objects to inherit those dependency attributes, we can also define them in a template.
In the following example we’ve added a cluster host with the service ping which we are going to define a dependency for in another host.
template Service "my-cluster-ping" {
check_command = "my-ping",
}
object Host "my-cluster" {
...
services["ping"] = {
templates = [ "my-cluster-ping" ],
}
...
}
We can now define a service dependency as new service template (or directly on the service definition):
template Service "my-cluster-dependency" {
servicedependencies = [
{ host = "my-cluster", service = "ping" },
],
}
Now let’s use that template for the ping service we’ve defined previously and assign the servicedependencies to that service.
...
services["ping"] = {
templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ],
},
...
Performance Data
Because there are no host checks in Icinga 2, the PerfdataWriter object will only write service performance data files. Creating the object will allow you to set the perfdata_path, format_template and rotation_interval. The format template is similar to existing Icinga 1.x configuration for PNP or inGraph using macro formatted strings.
Details on the common Icinga 1.x macros can be found at http://docs.icinga.org/latest/en/macrolist.html
Note
You can define multiple PerfdataWriter objects with different configuration settings, i.e. one for PNP, one for inGraph or your preferred graphite collector.
Let’s create a new PNP PerfdataWriter object:
object PerfdataWriter "pnp" {
perfdata_path = "/var/lib/icinga2/service-perfdata",
format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
rotation_interval = 15s,
}
You may need to reconfigure your NPCD daemon with the correct path for your performance data files. This can be done in the PNP configuration file npcd.cfg:
perfdata_spool_dir = /var/lib/icinga2/
Livestatus Component
The Livestatus component will provide access to Icinga 2 using the livestatus api. In addition to the unix socket Icinga 2 also service livestatus directly via tcp socket.
Note
Only config and status tables are available at this time. History tables such as log, statehist will follow.
Once Icinga 2 is started, configure your gui (e.g. Thruk) using the livestatus backend.
TCP Socket
library "livestatus"
object LivestatusComponent "livestatus-tcp" {
socket_type = "tcp",
host = "10.0.10.18",
port = "6558"
}
Unix Socket
library "livestatus"
object LivestatusComponent "livestatus-unix" {
socket_type = "unix",
socket_path = "/var/run/icinga2/livestatus"
}
Note
You need to grant permissions for the apache user manually after starting Icinga 2 for now.
# chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
IDO Database Component
The IDO component will write to the same database backend as known from Icinga 1.x IDOUtils. Therefore you’ll need to have your database schema and users already installed, like described in http://docs.icinga.org/latest/en/quickstart-idoutils.html#createidoutilsdatabase
Note
Currently there’s only MySQL support in progress, Postgresql, Oracle tbd.
Configure the IDO MySQL component with the defined credentials and start Icinga 2.
Note
Make sure to define a unique instance_name. That way the Icinga 2 IDO component will not interfere with your Icinga 1.x setup, if existing.
library "ido_mysql"
object IdoMysqlDbConnection "my-ido-mysql" {
host = "127.0.0.1",
port = "3306",
user = "icinga",
password = "icinga",
database = "icinga",
table_prefix = "icinga_",
instance_name = "icinga2",
instance_description = "icinga2 instance"
}
Starting Icinga 2 in debug mode in foreground using -x will show all database queries.
Custom Attributes
In Icinga 1.x there were so-called "custom variables" available prefixed with an underscore, as well as plenty of other attributes such as action_url, notes_url, icon_image, etc. To overcome the limitations of hardcoded custom attributes, Icinga 2 ships with the custom attribute as dictionary.
For example, if you have PNP installed we could add a reference url to Icinga Classic UI by using the classic method of defining an action_url.
template Service "my-pnp-svc" {
custom = {
action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$",
}
}
And add that template again to our service definition:
...
services["ping"] = {
templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
},
...
While at it, our configuration tool will add its LDAP DN and a snmp community to the service too, using += for additive attributes:
...
services["ping"] = {
templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
custom += {
DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org",
SNMPCOMMUNITY = "public"
}
},
...
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Configuration
Configuration Introduction
In Icinga 2 configuration is based on objects. There’s no difference in defining global settings for the core application or for a specific runtime configuration object.
There are different types for the main application, its components and tools. The runtime configuration objects such as hosts, services, etc are defined using the same syntax.
Each configuration object must be unique by its name. Otherwise Icinga 2 will bail early on verifying the parsed configuration.
Main Configuration
Starting Icinga 2 requires the main configuration file called "icinga2.conf". That’s the location where everything is defined or included. Icinga 2 will only know the content of that file and included configuration file snippets.
# /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf
Note
You can use just the main configuration file and put everything in there. Though that is not advised because configuration may be expanded over time. Rather organize runtime configuration objects into their own files and/or directories and include that in the main configuration file.
Configuration Syntax
/* TODO */
Details on the syntax can be found in the chapter icinga2-config-syntax.html[Configuration Syntax]
Configuration Types
/* TODO */
Details on the available types can be found in the chapter icinga2-config-types.html[Configuration Types]
Configuration Templates
Icinga 2 ships with the Icinga Template Library (ITL). This is a set of predefined templates and definitions available in your actual configuration.
Note
Do not change the ITL’s files. They will be overridden on upgrade. Submit a patch upstream or include your very own configuration snippet.
Include the basic ITL set in your main configuration like
include <itl/itl.conf>
Note
Icinga 2 recognizes the ITL’s installation path and looks for that specific file then.
Having Icinga 2 installed in standalone mode make sure to include itl/standalone.conf as well (see sample configuration).
include <itl/standalone.conf>
/* vim: set syntax=asciidoc filetype=asciidoc: */
Icinga 2 Configuration Syntax
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.
Note
Colons (:) are not permitted in object names.
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
Icinga 2 Configuration Types
Configuration Format
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" {
alias = "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. No escape characters are supported at present though this will likely change.
Example:
"Hello World!"
Expression List
A list of expressions that when executed has a dictionary as a result.
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.
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 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 expression lists. 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
Value Shortcut
Example:
{
"hello", "world"
}
This is equivalent to writing:
{
_00000001 = "hello", _00000002 = "world"
}
The item’s keys are monotonically increasing and the config compiler takes care of ensuring that all keys are unique (even when adding items to an existing attribute using +=).
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 (before 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:
abstract object Host "default-host" {
check_interval = 30,
macros = {
color = "red"
}
}
abstract object 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. Parent objects must already be defined by the time they’re used in an object definition.
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" keyword:
Example:
#include "some/other/file.conf"
#include "conf.d/*.conf"
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 classes or methods.
Example:
#library "snmphelper"
Note
The "icinga" library is automatically loaded by Icinga.
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
Configuration Objects
Type: IcingaApplication
The "IcingaApplication" type is used to specify global configuration parameters for Icinga. There must be exactly one application object in each Icinga 2 configuration. The object must have the "local" specifier.
Example:
local object IcingaApplication "icinga" {
cert_path = "my-cert.pem",
ca_path = "ca.crt",
node = "192.168.0.1",
service = 7777,
pid_path = "/var/run/icinga2.pid",
state_path = "/var/lib/icinga2/icinga2.state",
macros = {
plugindir = "/usr/local/icinga/libexec"
}
}
Attribute: cert_path
This is used to specify the SSL client certificate Icinga 2 will use when connecting to other Icinga 2 instances. This property is optional when you’re setting up a non-networked Icinga 2 instance.
Attribute: ca_path
This is the public CA certificate that is used to verify connections from other Icinga 2 instances. This property is optional when you’re setting up a non-networked Icinga 2 instance.
Attribute: node
The externally visible IP address that is used by other Icinga 2 instances to connect to this instance. This property is optional when you’re setting up a non-networked Icinga 2 instance.
Note
Icinga does not bind to this IP address.
Attribute: service
The port this Icinga 2 instance should listen on. This property is optional when you’re setting up a non-networked Icinga 2 instance.
Attribute: pid_path
Optional. The path to the PID file. Defaults to "icinga.pid" in the current working directory.
Attribute: state_path
Optional. The path of the state file. This is the file Icinga 2 uses to persist objects between program runs. Defaults to "icinga2.state" in the current working directory.
Attribute: macros
Optional. Global macros that are used for service checks and notifications.
Type: Component
Icinga 2 uses a number of components to implement its feature-set. The "Component" configuration object is used to load these components and specify additional parameters for them. "Component" objects must have the "local" specifier. The typical components to be loaded in the default configuration would be "checker", "delegation" and more.
Example "compat":
local object Component "compat" {
status_path = "/var/cache/icinga2/status.dat",
objects_path = "/var/cache/icinga2/objects.cache",
}
Attribute: status_path
Specifies where Icinga 2 Compat component will put the status.dat file, which can be read by Icinga 1.x Classic UI and other addons. If not set, it defaults to the localstatedir location.
Attribute: objects_path
Specifies where Icinga 2 Compat component will put the objects.cache file, which can be read by Icinga 1.x Classic UI and other addons. If not set, it defaults to the localstatedir location.
Type: ConsoleLogger
Specifies Icinga 2 logging to the console. Objects of this type must have the "local" specifier.
Example:
local object ConsoleLogger "my-debug-console" {
severity = "debug"
}
Attribute: severity
The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
Type: FileLogger
Specifies Icinga 2 logging to a file. Objects of this type must have the "local" specifier.
Example:
local object FileLogger "my-debug-file" {
severity = "debug",
path = "/var/log/icinga2/icinga2-debug.log"
}
Attribute: path
The log path.
Attribute: severity
The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
Type: SyslogLogger
Specifies Icinga 2 logging to syslog. Objects of this type must have the "local" specifier.
Example:
local object SyslogLogger "my-crit-syslog" {
severity = "critical"
}
Attribute: severity
The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
Type: Endpoint
Endpoint objects are used to specify connection information for remote Icinga 2 instances. Objects of this type should not be local:
object Endpoint "icinga-c2" {
node = "192.168.5.46",
service = 7777,
}
Attribute: node
The hostname/IP address of the remote Icinga 2 instance.
Attribute: service
The service name/port of the remote Icinga 2 instance.
Type: CheckCommand
A check command definition. Additional default command macros can be defined here.
Example:
object CheckCommand "check_snmp" inherits "plugin-check-command" {
command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
macros = {2yy
plugindir = "/usr/lib/nagios/plugins",
address = "127.0.0.1",
community = "public",
}
}
Type: NotificationCommand
A notification command definition.
Example:
object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$",
}
Type: EventCommand
An event command definition.
NOTE: Similar to Icinga 1.x event handlers.
Example:
-------------------------------------------------------------------------------
object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
command = "/usr/local/icinga/libexec/restart-httpd.sh",
}
-------------------------------------------------------------------------------
Type: Service
Service objects describe network services and how they should be checked by Icinga 2.
Note
Better create a service template and use that reference on the host definition as shown below.
Example:
object Service "localhost-uptime" {
host_name = "localhost",
alias = "localhost Uptime",
methods = {
check = "PluginCheck"
},
check_command = "check_snmp",
macros = {
plugindir = "/usr/lib/nagios/plugins",
address = "127.0.0.1",
community = "public",
oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
}
check_interval = 60s,
retry_interval = 15s,
servicegroups = { "all-services", "snmp" },
checkers = { "*" },
}
Attribute: host_name
The host this service belongs to. There must be a "Host" object with that name.
Attribute: alias
Optional. A short description of the service.
Attribute: methods - check
The check type of the service. For now only external check plugins are supported ("PluginCheck").
Attribute: check_command
Optional when not using the "external plugin" check type. The check command. May contain macros.
Attribute: check_interval
Optional. The check interval (in seconds).
Attribute: retry_interval
Optional. The retry interval (in seconds). This is used when the service is in a soft state.
Attribute: servicegroups
Optional. The service groups this service belongs to.
Attribute: checkers
Optional. A list of remote endpoints that may check this service. Wildcards can be used here.
Type: ServiceGroup
A group of services.
Example:
object ServiceGroup "snmp" {
alias = "SNMP services",
custom = {
notes_url = "http://www.example.org/",
action_url = "http://www.example.org/",
}
}
Attribute: alias
Optional. A short description of the service group.
Attribute: notes_url
Optional. Notes URL. Used by the CGIs.
Attribute: action_url
Optional. Action URL. Used by the CGIs.
Type: Host
A host. Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2.
Example:
object Host "localhost" {
alias = "The best host there is",
hostgroups = [ "all-hosts" ],
hostcheck = "ping",
dependencies = [ "router-ping" ]
services["ping"] = { templates = "ping" }
services["http"] = {
templates = "my-http",
macros = {
vhost = "test1.example.org",
port = 81
}
}
check_interval = 60m,
retry_interval = 15m,
servicegroups = [ "all-services" ],
checkers = { "*" },
}
Attribute: alias
Optional. A short description of the host.
Attribute: hostgroups
Optional. A list of host groups this host belongs to.
Attribute: hostcheck
Optional. A service that is used to determine whether the host is up or down.
Attribute: hostdependencies
Optional. A list of hosts that are used to determine whether the host is unreachable.
Attribute: servicedependencies
Optional. A list of services that are used to determine whether the host is unreachable.
Attribute: services
Inline definition of services. Each service name is defined in square brackets and got its own dictionary with attribute properties, such as the template service being used. All other service-related properties are additively copied into the new service object.
The new service’s name is "hostname-service" - where "service" is the array key in the services array.
The priority for service properties is (from highest to lowest):
-
Properties specified in the dictionary of the inline service definition
-
Host properties
-
Properties inherited from the new service’s parent object
Attribute: check_interval
Optional. Copied into inline service definitions. The host itself does not have any checks.
Attribute: retry_interval
Optional. Copied into inline service definitions. The host itself does not have any checks.
Attribute: servicegroups
Optional. Copied into inline service definitions. The host itself does not have any checks.
Attribute: checkers
Optional. Copied into inline service definitions. The host itself does not have any checks.
Type: HostGroup
A group of hosts.
Example
object HostGroup "my-hosts" {
alias = "My hosts",
notes_url = "http://www.example.org/",
action_url = "http://www.example.org/",
}
Attribute: alias
Optional. A short description of the host group.
Attribute: notes_url
Optional. Notes URL. Used by the CGIs.
Attribute: action_url
Optional. Action URL. Used by the CGIs.
Type: PerfdataWriter
Write check result performance data to a defined path using macro pattern.
Example
local object PerfdataWriter "pnp" {
perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata",
format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
rotation_interval = 15s,
}
Attribute: perfdata_path
Path to the service perfdata file.
Note
Will be automatically rotated with timestamp suffix.
Attribute: format_template
Formatting of performance data output for graphing addons or other post processing.
Attribute: rotation_interval
Rotation interval for the file defined in perfdata_path.
Type: IdoMySqlConnection
IDO DB schema compatible output into mysql database.
Example
library "ido_mysql"
local object IdoMysqlDbConnection "mysql-ido" {
host = "127.0.0.1",
port = "3306",
user = "icinga",
password = "icinga",
database = "icinga",
table_prefix = "icinga_",
instance_name = "icinga2",
instance_description = "icinga2 dev instance"
}
Attribute: host
MySQL database host address. Default is localhost.
Attribute: port
MySQL database port. Default is 3306.
Attribute: user
MySQL database user with read/write permission to the icinga database. Default is icinga.
Attribute: password
MySQL database user’s password. Default is icinga.
Attribute: database
MySQL database name. Default is icinga.
Attribute: table_prefix
MySQL database table prefix. Default is icinga_.
Attribute: instance_name
Unique identifier for the local Icinga 2 instance.
Attribute: instance_description
Optional. Description for the Icinga 2 instance.
Type: LiveStatusComponent
Livestatus api interface available as tcp or unix socket.
Example
library "livestatus"
local object LivestatusComponent "livestatus-tcp" {
socket_type = "tcp",
host = "127.0.0.1",
port = "6558"
}
local object LivestatusComponent "livestatus-unix" {
socket_type = "unix",
socket_path = "/var/run/icinga2/livestatus"
}
Attribute: socket_type
tcp or unix socket. Default is unix.
Note
unix sockets are not supported on Windows.
Attribute: host
Only valid when socket_type="tcp". Host address to listen on for connections.
Attribute: port
Only valid when socket_type="tcp". Port to listen on for connections.
Attribute: socket_path
Only valid when socket_type="unix". Local unix socket file. Not supported on Windows.
Configuration Examples
Non-networked minimal example
Note
Icinga 2 ITL provides itl/standalone.conf which loads all required components, as well as itl/itl.conf includes many object templates already for an easy start with Icinga 2.
local object IcingaApplication "icinga" {
}
local object Component "checker" {
}
local object Component "delegation" {
}
object CheckCommand "ping" {
command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%",
}
template Service "icinga-service" {
methods = {
check = "PluginCheck"
},
macros = {
plugindir = "/usr/lib/nagios/plugins"
}
}
template Service "ping-tmpl" inherits "icinga-service" {
check_command = "ping",
macros += {
wrta = 50,
wpl = 5,
crta = 100,
cpl = 10
}
}
object Host "localhost" {
services["ping"] = { templates = "ping-tmpl" },
macros = {
address = "127.0.0.1"
},
check_interval = 10m
}
Note
You may also want to load the "compat" component if you want Icinga 2 to write status.dat and objects.cache files.
/* vim: set syntax=asciidoc filetype=asciidoc: */
/* vim: set syntax=asciidoc filetype=asciidoc: */