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 include 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]
information/icinga-app: Icinga application loader (version: 0.0.1, git branch master, commit 0fcbfdb2) [2013/04/23 13:36:20 +0200]
information/base: Adding library search dir: /usr/lib/icinga2 [2013/04/23 13:36:20 +0200]
information/base: Loading library 'libicinga.la' [2013/04/23 13:36:20 +0200]
information/config: Adding include search dir: /usr/share/icinga2 [2013/04/23 13:36:20 +0200]
information/config: Compiling config file: /etc/icinga2/icinga2.conf [2013/04/23 13:36:20 +0200]
information/config: Linking config items... [2013/04/23 13:36:20 +0200]
information/config: Validating config items... [2013/04/23 13:36:20 +0200]
information/config: Activating config items in compilation unit 'b2d21c28-a2e8-4fcb-ba00-45646bc1afb9' [2013/04/23 13:36:20 +0200]
information/base: Restoring program state from file '/var/lib/icinga2/icinga2.state' [2013/04/23 13:36:20 +0200]
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] information/base: Shutting down Icinga... [2013/04/23 13:39:39 +0200] information/base: Dumping program state to file '/var/lib/icinga2/icinga2.state' [2013/04/23 13:39:39 +0200]
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 > **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 " 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 < **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 > **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 /\* 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 " \\" \ \\t \ \\r \ \\n \ \\b \ \\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 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 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: \*/