mirror of https://github.com/Icinga/icinga2.git
2866 lines
82 KiB
Markdown
2866 lines
82 KiB
Markdown
Icinga 2 Main
|
||
=============
|
||
|
||
Introduction
|
||
------------
|
||
|
||
A detailed introduction can be found in the chapter
|
||
[Introduction](icinga2-intro.html). /\* 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](icinga2-tutorial.html). /\* 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](http://webchat.freenode.net/?channels=icinga) on the
|
||
Freenode IRC Network
|
||
|
||
- [Mailinglists](https://lists.sourceforge.net/lists/listinfo/icinga-users)
|
||
|
||
- [Monitoring Portal](http://www.monitoring-portal.org)
|
||
|
||
More details at
|
||
[http://www.icinga.org/support/](http://www.icinga.org/support/)
|
||
|
||
Support
|
||
-------
|
||
|
||
For more information on the support options refer to
|
||
[https://www.icinga.org/support](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](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](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](icinga2-compat.html).
|
||
|
||
Changes
|
||
-------
|
||
|
||
For details check the chapter [Changes](icinga2-compat.html).
|
||
|
||
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](:icinga2-config.html)
|
||
|
||
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](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](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](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](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](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](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):
|
||
|
||
1. Properties specified in the dictionary of the inline service
|
||
definition
|
||
|
||
2. Host properties
|
||
|
||
3. 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: \*/
|