## <a id="what-is-icinga2"></a> What is Icinga 2?
-Icinga 2 is an open source monitoring system which keeps watch over network resources,
-notifies users of outages and recoveries and generates performance data for reporting.
+Icinga 2 is an open source monitoring system which checks the availability of your
+network resources, notifies users of outages and generates performance data for reporting.
+
Scalable and extensible, Icinga 2 can monitor complex, large environments across
multiple locations.
is to use the official Debian or RPM package repositories depending on which
operating system and distribution you are running.
- Distribution |Repository URL
+ Distribution | Repository URL
------------------------|---------------------------
- Debian |http://packages.icinga.org/debian/
- Ubuntu |http://packages.icinga.org/ubuntu/
- RHEL/CentOS 5 |http://packages.icinga.org/epel/5/release/
- RHEL/CentOS 6 |http://packages.icinga.org/epel/6/release/
- OpenSUSE 12.3 |http://packages.icinga.org/openSUSE/12.3/release/
- SLES 11 SP3 |http://packages.icinga.org/SUSE/sles11-sp3/release/
+ Debian | http://packages.icinga.org/debian/
+ Ubuntu | http://packages.icinga.org/ubuntu/
+ RHEL/CentOS 5 | http://packages.icinga.org/epel/5/release/
+ RHEL/CentOS 6 | http://packages.icinga.org/epel/6/release/
+ OpenSUSE 12.3 | http://packages.icinga.org/openSUSE/12.3/release/
+ SLES 11 SP3 | http://packages.icinga.org/SUSE/sles11-sp3/release/
Packages for distributions other than the ones listed above may also be
available. Please check http://packages.icinga.org/ to see if packages
> **Note**
>
> On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
-`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2
-start`.
+> `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
Some parts of Icinga 2's functionality are available as separate packages:
/**
* Global macros
*/
- set IcingaMacros = {
+ const IcingaMacros = {
plugindir = "/usr/local/icinga/libexec"
}
macros.address6 = "::1"
}
+This defines the host `localhost`. The `import` keyword is used to import
+the `linux-server` template which takes care of setting up the `ping4` and
+`ping6` services for the host as well as adding the host to the `linux-servers`
+host group.
+
+The `macros` attribute can be used to define macros that are available for all
+services which belong to this host. Most of the templates in the Icinga Template
+Library require an `address` macro.
+
apply Service "icinga" {
import "generic-service",
assign where host.name == "localhost"
}
-This defines a host named "localhost" which has a couple of services. Services
-may import one or more service templates.
+The `apply` keyword can be used to dynamically create services for all hosts based
+on rules.
-The command objects `ping4`, `ping6`, `http_ip`, `ssh`, `load`, `processes`, `users`
+The command objects `http_ip`, `ssh`, `load`, `processes`, `users`
and `disk` are all provided by the Icinga Template Library (short ITL) which
we enabled earlier by including the `itl/itl.conf` configuration file.
-
-The `macros` attribute can be used to define macros that are available for all
-services which belong to this host. Most of the templates in the Icinga Template
-Library require an `address` macro.
## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
On its own Icinga 2 does not know how to check external services. The
-[Monitoring Plugins Project](https://www.monitoring-plugins.org/) (former
-Nagios Plugins) provides an extensive set of plugins which can be used by
-Icinga 2 to check whether services are working properly.
+[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
+an extensive set of plugins which can be used with Icinga 2 to check whether
+services are working properly.
The recommended way of installing these standard plugins is to use your
distribution's package manager.
> **Note**
>
-> The `Nagios Plugins` project was renamed to `Monitoring Plugins` project
-> in Jan 2014. Therefore package names may still reflect the old name.
+> The `Nagios Plugins` project was renamed to `Monitoring Plugins`
+> in January 2014. At the time of this writing the packages are still
+> using the old name.
For your convenience here is a list of package names for some of the more
popular operating systems/distributions:
update the `plugindir` macro in your Icinga 2 configuration. This macro is used
by the service templates contained in the Icinga Template Library to determine
where to find the plugin binaries.
-Alternatively you can create a symbolic link pointing to the installation path
-of the plugins.
### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
-You may require a custom check plugin not provided by the official Nagios plugins.
-All existing Nagios or Icinga 1.x plugins found on public community websites
-will work with Icinga 2 as well.
+For some services you may need additional check plugins which are not provided
+by the official Monitoring Plugins project.
+
+All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
+list of popular community sites which host check plugins:
* [MonitoringExchange](https://www.monitoringexchange.org)
* [Icinga Wiki](https://wiki.icinga.org)
-Once you have downloaded the plugin copy it into the directory defined by the global
-`IcingaMacro` `$plugindir$` and make sure that the user the Icinga daemon is running as
-can execute the the plugin binary. Plugins should support the `--help` parameter
-providing details how they have to be called in your command definition later on.
+The recommended way of setting up these plugins is to copy them to a common directory
+and creating an extra global macro, e.g. `customplugindir` in your `macros.conf`
+configuration file:
- # cp check_snmp_int.pl /usr/local/icinga/libexec/
- # chmod +x /usr/local/icinga/libexec/check_snmp_int.pl
-
- # /usr/local/icinga/libexec/check_snmp_int.pl --help
+ # cp check_snmp_int.pl /opt/plugins
+ # chmod +x /opt/plugins/check_snmp_int.pl
+
+ # cat /etc/icinga2/conf/macros.conf
+ /**
+ * Global macros
+ */
+ const IcingaMacros = {
+ plugindir = "/usr/lib/nagios/plugins",
+ customplugindir = "/opt/monitoring"
+ }
+
+Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
+by trying to run it on the console using whichever user Icinga 2 is running as:
+
+ # su - icinga -s /bin/bash
+ $ /opt/plugins/check_snmp_int.pl --help
> **Note**
>
-> You may require additional libraries for scripts. Please consult the installation
+> You may require additional libraries for some plugins. Please consult the installation
> documentation and/or README for their installation requirements.
Icinga 2 supports three different types of logging:
-* File logging (local Icinga 2 log file)
-* Syslog facility logging (system's syslog application)
+* File logging
+* Syslog (on *NIX-based operating systems)
* Console logging (`STDOUT` on tty)
-> **Note**
->
-> You can define multiple logging objects at once.
+You can enable additional loggers using the `icinga2-enable-feature`
+and `icinga2-disable-feature` commands to configure loggers:
-The most common scenario will be logging Icinga 2's output to
-syslog with severity `information`.
-
- object SyslogLogger "syslog" {
- severity = "information"
- }
-
-For debugging purposes you can install a `FileLogger` object
-and forward the `debug` severity into an Icinga 2 debug file.
-
- object FileLogger "debug-file" {
- severity = "debug",
- path = "/var/log/icinga2/debug.log"
- }
+Feature | Description
+---------|------------
+debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher)
+mainlog | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher)
+syslog | Syslog (severity: `warning` or higher)
+By default file the `mainlog` feature is enabled. When running Icinga 2
+on a terminal log messages with severity `information` or higher are
+written to the console.
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
+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
Operator | Examples (Result) | Description
---------|-----------------------------------------------|--------------------------------
-!, ~ | ~true (false) | Bitwise negation of the operand
+! | !"Hello" (false), !false (true) | Logical negation of the operand
+~ | ~true (false) | Bitwise negation of the operand
+ | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
- | 3 - 1 (2) | Subtracts two numbers
* | 5m * 10 (3000) | Multiplies two numbers
Example:
+ {
+ hello.key = "world"
+ }
+
+Example (alternative syntax):
+
{
hello["key"] = "world"
}
}
}
-### <a id="object-inheritance"></a> Object Inheritance
+### <a id="template-imports"></a> Template Imports
-Objects can inherit attributes from other objects.
+Objects can import attributes from other objects.
Example:
template Host "default-host" {
- macros["color"] = "red"
+ macros.color = "red"
}
template Host "test-host" {
import "default-host",
- macros["color"] = "blue"
+ macros.color = "blue"
}
object Host "localhost" {
import "test-host",
- macros["address"] = "127.0.0.1",
- macros["address6"] = "::1"
+ macros.address = "127.0.0.1",
+ macros.address6 = "::1"
}
The `default-host` and `test-host` objects are marked as templates
using the `template` keyword. Unlike ordinary objects templates are not
instantiated at run-time. Parent objects do not necessarily have to be
-templates though in general they are.
+templates, however in general they are.
> **Note**
>
-> The final macros dictionary contains all three macros and the macro
-> `color` has the value `"blue"`.
+> The macros dictionary for the `localhost` object contains all three
+> macros and the macro `color` has the value `"blue"`.
Parent objects are resolved in the order they're specified using the
`import` keyword.
-### <a id="disable-override-objects-attributes"></a> Disable/Override Objects and Attributes
-
-Object attributes can be overridden by defining the additional changed attribute
-directly on the object. Use the `+=` operator for the inline services dictionary.
-
- services["overridden-custom-attr"] += {
- custom = {
- notes = "disabled all custom attr"
- }
- }
-
-If you don't require an attribute inherited from templates, you can simply
-override its value by setting it explicitely to `null`.
-
- services["no-custom-attr"] += {
- custom = null
- }
-
-The same method applies for disabling services defined in the inline `services`
-dictionary by explicitly overriding their value with `null`.
-
- services["ping6"] = null
-
### <a id="constants"></a> Constants
Global constants can be set using the `const` keyword:
const VarName = "some value"
-The value can be a string, number, array, or a dictionary.
-
Once defined a constant can be access from any file. Constants cannot be changed
once they are set.
### <a id="apply"></a> Apply
-The `apply` keyword can be used to associate a template with another group of
-objects. The exact effect of this association depends on the object type.
+The `apply` keyword can be used to create new objects which are associated with
+another group of objects.
apply Service "ping" {
import "generic-service",
assign where host.name == "localhost"
}
-In this example the `assign where` condition is an expression which is
-evaluated for all objects of type Host and a new service with name "ping"
+In this example the `assign where` condition is a boolean expression which is
+evaluated for all objects of type `Host` and a new service with name "ping"
is created for each matching host.
Depending on the object type used in the `apply` expression additional local
variables may be available for use in the `where` condition:
- Type |Variables
- -----------------|----------------
- Dependency |host, service
- Notification |host, service
- Service |host
- ScheduledDowntime|host, service
+Source Type | Target Type | Variables
+-----------------|-------------|--------------
+Service | Host | host
+Dependency | Service | host, service
+Notification | Service | host, service
+ScheduledDowntime| Service | host, service
+
+> **Note**
+>
+> Any valid config attribute can be accessed using the `host` and `service`
+> variables. For example, `host.macros.address` would return the host's
+> "address" macro - or null if it doesn't have that macro.
+
+### <a id="boolean-values"></a> Boolean Values
+
+The `assign where` and `ignore where` statements, the unary `!`, `&&` and `||`
+operators as well as the `bool()` function convert their arguments to a
+boolean value based on the following rules:
+
+Description | Example Value | Boolean Value
+---------------------|-------------------|--------------
+Empty value | null | false
+Zero | 0 | false
+Non-zero integer | -23945 | true
+Empty string | "" | false
+Non-empty string | "Hello" | true
+Empty array | [] | false
+Non-empty array | [ "Hello" ] | true
+Empty dictionary | {} | false
+Non-empty dictionary | { key = "value" } | true
### <a id="comments"></a> Comments
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
+file. By default $PREFIX/share/icinga2 is included in the list of search
paths. Additional include search paths can be added using
[command-line options](#cmdline).
The `library` directive can be used to manually load additional
libraries. Libraries can be used to provide additional object types and
-methods.
+functions.
Example:
> **Note**
>
-> The `icinga` library is automatically loaded at startup. You don't need
-> to load it manually.
+> The `icinga` and `methods` libraries is automatically loaded at startup.
+> You don't need to load them manually.
<!--
- 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
+- The s
+- cript function `ValidateIngredients` is run to perform further
validation of the ingredients dictionary.
- Pizza objects may contain attribute matching the pattern
Variable |Description
--------------------------|-------------------
-IcingaPrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to /usr/local
+IcingaPrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
IcingaSysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to IcingaPrefixDir + "/etc".
IcingaLocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to IcingaPrefixDir + "/var".
IcingaPkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to IcingaPrefixDir + "/share/icinga2".
groups = [ "all-hosts" ],
- services["ping"] = {
- templates = [ "ping" ]
- },
-
check = "ping"
}
Name |Description
----------------|----------------
display_name |**Optional.** A short description of the time period.
- methods |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should just inherit from the "legacy-timeperiod" template to take care of this setting.
+ methods |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
Name |Description
----------------|----------------
- methods |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should just inherit from the "plugin-check-command" template to take care of this setting.
+ methods |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
Name |Description
----------------|----------------
- methods |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should just inherit from the "plugin-notification-command" template to take care of this setting.
+ methods |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
Name |Description
----------------|----------------
- methods |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should just inherit from the "plugin-event-command" template to take care of this setting.
+ methods |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
### <a id="best-practice-config-structure"></a> Configuration File and Directory Structure
Icinga 2 does not care how you name your files and/or directories as long as
-you'll include them accordingly in the [icinga2.conf](#icinga2-conf) file.
+you include them in the [icinga2.conf](#icinga2-conf) file.
+
+By default, the `conf.d` directory is included recursively looking for files
+which match the pattern `*.conf`.
-By default, `conf.d` is included recursively looking for `*.conf` file endings.
If you're putting/generating your configuration structure in there, you do not
need to touch the [icinga2.conf](#icinga2-conf) file. This becomes useful with
external addons not having write permissions to this file such as LConf.
projects / icinga2 / commitdiff