58 KiB

Raw Blame History

Configuring Icinga 2

Configuration Syntax

Object Definition

Icinga 2 features an object-based configuration format. You can define new objects using the object keyword:

object Host "host1.example.org" {
  display_name = "host1"

  address = "192.168.0.1"
  address6 = "::1"
}

In general you need to write each statement on a new line. Expressions started with {, ( and [ extend until the matching closing character and can be broken up into multiple lines.

Alternatively you can write multiple statements in a single line by separating them with a semicolon:

object Host "host1.example.org" {
  display_name = "host1"

  address = "192.168.0.1"; address6 = "::1"
}

Each object is uniquely identified by its type (Host) and name (host1.example.org). Some types have composite names, e.g. the Service type which uses the host_name attribute and the name you specified to generate its object name.

Exclamation marks (!) are not permitted in object names.

Objects can contain a comma-separated list of property declarations. Instead of commas semicolons may also be used. The following data types are available for property values:

Expressions

The following expressions can be used in the right-hand side of dictionary values.

Numeric Literals

A floating-point number.

Example:

-27.3

Duration Literals

Similar to floating-point numbers except for the fact that they support suffixes to help with specifying time durations.

Example:

2.5m

Supported suffixes include ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days).

Duration literals are converted to seconds by the config parser and are treated like numeric literals.

String Literals

A string.

Example:

"Hello World!"

Certain characters need to be escaped. The following escape sequences are supported:

Character	Escape sequence
"	\"
\	\\
<TAB>	\t
<CARRIAGE-RETURN>	\r
<LINE-FEED>	\n
<BEL>	\b
<FORM-FEED>	\f

In addition to these pre-defined escape sequences you can specify arbitrary ASCII characters using the backslash character (\) followed by an ASCII character in octal encoding.

Multi-line String Literals

Strings spanning multiple lines can be specified by enclosing them in {{{ and }}}.

Example.

{{{This
is
a multi-line
string.}}}

Unlike in ordinary strings special characters do not have to be escaped in multi-line string literals.

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
}

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.

Setting a dictionary key to null causes the key and its value 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", 42 ]

An array may simultaneously contain values of different types, such as strings and numbers.

Operators

The following operators are supported in expressions:

Operator	Examples (Result)	Description
!	!"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

/ | 5m / 5 (60) | Divides two numbers & | 7 & 3 (3) | Binary AND | | 2 | 3 (3) | Binary OR < | 3 < 5 (true) | Less than

   | 3 > 5 (false)                                 | Greater than

<= | 3 <= 3 (true) | Less than or equal

= | 3 >= 3 (true) | Greater than or equal << | 4 << 8 (1024) | Left shift
  | 1024 >> 4 (64)                                | Right shift

Constants may be used in expressions:

const MyCheckInterval = 10m

...

{
  check_interval = MyCheckInterval / 2.5
}

Function Calls

Functions can be called using the () operator:

const MyGroups = [ "test1", "test" ]

{
  check_interval = len(MyGroups) * 1m
}

Function	Description
regex(pattern, text)	Returns true if the regex pattern matches the text, false otherwise.
match(pattern, text)	Returns true if the wildcard pattern matches the text, false otherwise.
len(value)	Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
union(array, array, ...)	Returns an array containing all unique elements from the specified arrays.
intersection(array, array, ...)	Returns an array containing all unique elements which are common to all specified arrays.
string(value)	Converts the value to a string.
number(value)	Converts the value to a number.
bool(value)	Converts to value to a bool.
log(value)	Writes a message to the log. Non-string values are converted to a JSON string.
log(severity, facility, value)	Writes a message to the log. `severity` can be one of `LogDebug`, `LogInformation`, `LogWarning` and `LogCritical`. Non-string values are converted to a JSON string.
exit(integer)	Terminates the application.

Dictionary Operators

In addition to the = operator shown above a number of other operators to manipulate dictionary elements 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 +=

The += operator is a shortcut. The following expression:

{
  a = [ "hello" ]
  a += [ "world" ]
}

is equivalent to:

{
  a = [ "hello" ]
  a = a + [ "world" ]
}

Operator -=

The -= operator is a shortcut. The following expression:

{
  a = 10
  a -= 5
}

is equivalent to:

{
  a = 10
  a = a - 5
}

Operator *=

The *= operator is a shortcut. The following expression:

{
  a = 60
  a *= 5
}

is equivalent to:

{
  a = 60
  a = a * 5
}

Operator /=

The /= operator is a shortcut. The following expression:

{
  a = 300
  a /= 5
}

is equivalent to:

{
  a = 300
  a = a / 5
}

Indexer

The indexer syntax provides a convenient way to set dictionary elements.

Example:

{
  hello.key = "world"
}

Example (alternative syntax):

{
  hello["key"] = "world"
}

This is equivalent to writing:

{
  hello += {
    key = "world"
  }
}

Template Imports

Objects can import attributes from other objects.

Example:

template Host "default-host" {
  vars.color = "red"
}

template Host "test-host" {
  import "default-host"

  vars.color = "blue"
}

object Host "localhost" {
  import "test-host"

  address = "127.0.0.1"
  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, however in general they are.

The vars dictionary for the localhost object contains all three custom attributes and the custom attribute color has the value "blue".

Parent objects are resolved in the order they're specified using the import keyword.

Constants

Global constants can be set using the const keyword:

const VarName = "some value"

Once defined a constant can be access from any file. Constants cannot be changed once they are set.

Apply

The apply keyword can be used to create new objects which are associated with another group of objects.

apply Service "ping" to Host {
  import "generic-service"

  check_command = "ping4"

  assign where host.name == "localhost"
}

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.

The to keyword and the target type may be omitted if there is only target type, e.g. for the Service type.

Depending on the object type used in the apply expression additional local variables may be available for use in the where condition:

Source Type	Target Type	Variables
Service	Host	host
Dependency	Host	host
Dependency	Service	host, service
Notification	Host	host
Notification	Service	host, service
ScheduledDowntime	Host	host
ScheduledDowntime	Service	host, service

Any valid config attribute can be accessed using the host and service variables. For example, host.address would return the value of the host's "address" attribute - or null if that attribute isn't set.

Group Assign

Group objects can be assigned to specific member objects using the assign where and ignore where conditions.

object HostGroup "linux-servers" {
  display_name = "Linux Servers"

  assign where host.vars.os == "Linux"
}

In this example the assign where condition is a boolean expression which is evaluated for all objects of the type Host. Each matching host is added as member to the host group with the name "linux-servers". Membership exclusion can be controlled using the ignore where condition.

Source Type	Variables
HostGroup	host
ServiceGroup	host, service
UserGroup	user

Boolean Values

The assign where and ignore where statements, the !, && 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

Comments

The Icinga 2 configuration format supports C/C++-style and shell-style comments.

Example:

/*
 This is a comment.
 */
object Host "localhost" {
  check_interval = 30 // this is also a comment.
  retry_interval = 15 # yet another comment
}

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"

Wildcard includes are not recursive.

Icinga also supports include search paths similar to how they work in a C/C++ compiler:

include <itl/itl.conf>

Note the use of angle brackets instead of double quotes. This causes the config compiler to search the include search paths for the specified file. By default $PREFIX/share/icinga2 is included in the list of search paths. Additional include search paths can be added using command-line options.

Wildcards are not permitted when using angle brackets.

Recursive Includes

The include_recursive directive can be used to recursively include all files in a directory which match a certain pattern.

Example:

include_recursive "conf.d", "*.conf"
include_recursive "templates"

The first parameter specifies the directory from which files should be recursively included.

The file names need to match the pattern given in the second parameter. When no pattern is specified the default pattern "*.conf" is used.

Library directive

The library directive can be used to manually load additional libraries. Libraries can be used to provide additional object types and functions.

Example:

library "snmphelper"

Global Constants

Icinga 2 provides a number of special global constants. Some of them can be overriden using the --define command line parameter:

Variable	Description
PrefixDir	Read-only. Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
SysconfDir	Read-only. Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
LocalStateDir	Read-only. Contains the path of the local state directory. Defaults to PrefixDir + "/var".
PkgDataDir	Read-only. Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
StatePath	Read-write. Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
PidPath	Read-write. Contains the path of the Icinga 2 PID file. Defaults to LocalStateDir + "/run/icinga2/icinga2.pid".
Vars	Read-write. Contains a dictionary with global custom attributes. Not set by default.
NodeName	Read-write. Contains the cluster node name. Set to the local hostname by default.
ApplicationType	Read-write. Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
EnableNotifications	Read-write. Whether notifications are globally enabled. Defaults to true.
EnableEventHandlers	Read-write. Whether event handlers are globally enabled. Defaults to true.
EnableFlapping	Read-write. Whether flap detection is globally enabled. Defaults to true.
EnableHostChecks	Read-write. Whether active host checks are globally enabled. Defaults to true.
EnableServiceChecks	Read-write. Whether active service checks are globally enabled. Defaults to true.
EnablePerfdata	Read-write. Whether performance data processing is globally enabled. Defaults to true.
UseVfork	Read-write. Whether to use vfork(). Only available on *NIX. Defaults to true.

Object Types

Host

A host.

Example:

object Host "localhost" {
  display_name = "The best host there is"
  address = "127.0.0.1"
  address6 = "::1"

  groups = [ "all-hosts" ]

  check_command = "hostalive"
}

Attributes:

Name	Description
display_name	Optional. A short description of the host.
address	Optional. The host's address. Available as command runtime macro $address$ if set.
address6	Optional. The host's address. Available as command runtime macro $address6$ if set.
groups	Optional. A list of host groups this host belongs to.
vars	Optional. A dictionary containing custom attributes that are specific to this host.
check_command	Required. The name of the check command.
max_check_attempts	Optional. The number of times a host is re-checked before changing into a hard state. Defaults to 3.
check_period	Optional. The name of a time period which determines when this host should be checked. Not set by default.
check_interval	Optional. The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to 5 minutes.
retry_interval	Optional. The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to 1 minute.
enable_notifications	Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks	Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks	Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler	Optional. Enables event handlers for this host. Defaults to true.
enable_flap_detection	Optional. Whether flap detection is enabled. Defaults to true.
enable_perfdata	Optional. Whether performance data processing is enabled. Defaults to true.
event_command	Optional. The name of an event command that should be executed every time the host's state changes.
flapping_threshold	Optional. The flapping threshold in percent when a host is considered to be flapping.
volatile	Optional. The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
authorities	Optional. A list of Endpoints on which this host check will be executed in a cluster scenario.
domains	Optional. A list of Domains for this host object in a cluster scenario.
notes	Optional. Notes for the host.
notes_url	Optional. Url for notes for the host (for example, in notification commands).
action_url	Optional. Url for actions for the host (for example, an external graphing tool).
icon_image	Optional. Icon image for the host. Required for external interfaces only.
icon_image_alt	Optional. Icon image description for the host. Required for external interface only.

Best Practice

The address and address6 attributes are required for running commands using the $address$ and $address6 runtime macros.

HostGroup

A group of hosts.

Example:

object HostGroup "my-hosts" {
  display_name = "My hosts"
}

Attributes:

Name	Description
display_name	Optional. A short description of the host group.
groups	Optional. An array of nested group names.

Service

Service objects describe network services and how they should be checked by Icinga 2.

Best Practice

Rather than creating a Service object for a specific host it is usually easier to just create a Service template and use the apply keyword to assign the service to a number of hosts.

Example:

object Service "uptime" {
  host_name = "localhost"

  display_name = "localhost Uptime"

  check_command = "check_snmp"

  vars.community = "public"
  vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"

  check_interval = 60s
  retry_interval = 15s

  groups = [ "all-services", "snmp" ]
}

Attributes:

Name	Description
host_name	Required. The host this service belongs to. There must be a `Host` object with that name.
name	Required. The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
groups	Optional. The service groups this service belongs to.
vars	Optional. A dictionary containing custom attributes that are specific to this service.
check_command	Required. The name of the check command.
max_check_attempts	Optional. The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check_period	Optional. The name of a time period which determines when this service should be checked. Not set by default.
check_interval	Optional. The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
retry_interval	Optional. The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1 minute.
enable_notifications	Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks	Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks	Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler	Optional. Enables event handlers for this host. Defaults to true.
enable_flap_detection	Optional. Whether flap detection is enabled. Defaults to true.
enable_perfdata	Optional. Whether performance data processing is enabled. Defaults to true.
event_command	Optional. The name of an event command that should be executed every time the service's state changes.
flapping_threshold	Optional. The flapping threshold in percent when a service is considered to be flapping.
volatile	Optional. The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
authorities	Optional. A list of Endpoints on which this service check will be executed in a cluster scenario.
domains	Optional. A list of Domains for this service object in a cluster scenario.
notes	Optional. Notes for the service.
notes_url	Optional. Url for notes for the service (for example, in notification commands).
action_url	Optional. Url for actions for the service (for example, an external graphing tool).
icon_image	Optional. Icon image for the service. Required for external interfaces only.
icon_image_alt	Optional. Icon image description for the service. Required for external interface only.

Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means you can define more than one object with the same (short) name as long as the host_name attribute has a different value.

ServiceGroup

A group of services.

Example:

object ServiceGroup "snmp" {
  display_name = "SNMP services"
}

Attributes:

Name	Description
display_name	Optional. A short description of the service group.
groups	Optional. An array of nested group names.

Notification

Notification objects are used to specify how users should be notified in case of host and service state changes and other events.

Best Practice

Rather than creating a Notification object for a specific host or service it is usually easier to just create a Notification template and use the apply keyword to assign the notification to a number of hosts or services. Use the to keyword to set the specific target type for Host or Service.

Example:

object Notification "localhost-ping-notification" {
  host_name = "localhost"
  service_name = "ping4"

  command = "mail-notification"

  users = [ "user1", "user2" ]

  types = [ Problem, Recovery ]
}

Attributes:

Name	Description
host_name	Required. The name of the host this notification belongs to.
service_name	Optional. The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
vars	Optional. A dictionary containing custom attributes that are specific to this notification object.
users	Optional. A list of user names who should be notified.
user_groups	Optional. A list of user group names who should be notified.
times	Optional. A dictionary containing `begin` and `end` attributes for the notification.
command	Required. The name of the notification command which should be executed when the notification is triggered.
interval	Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes.
period	Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
types	Optional. A list of type filters when this notification should be triggered. By default everything is matched.
states	Optional. A list of state filters when this notification should be triggered. By default everything is matched.

Available notification state filters:

OK
Warning
Critical
Unknown
Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

Dependency

Dependency objects are used to specify dependencies between hosts and services.

Best Practice

Rather than creating a Dependency object for a specific host or service it is usually easier to just create a Dependency template and use the apply keyword to assign the dependency to a number of hosts or services. Use the to keyword to set the specific target type for Host or Service.

Example:

object Dependency "webserver-internet" {
  child_host_name = "webserver"
  child_service_name = "ping4"

  parent_host_name = "internet"
  parent_service_name = "ping4"

  states = [ OK, Warning ]

  disable_checks = true
}

Attributes:

Name	Description
parent_host_name	Required. The parent host.
parent_service_name	Optional. The parent service. If omitted this dependency object is treated as host dependency.
child_host_name	Required. The child host.
child_service_name	Optional. The child service. If omitted this dependency object is treated as host dependency.
disable_checks	Optional. Whether to disable checks when this dependency fails. Defaults to false.
disable_notifications	Optional. Whether to disable notifications when this dependency fails. Defaults to true.
period	Optional. Time period during which this dependency is enabled.
states	Optional. A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.

Available state filters:

OK
Warning
Critical
Unknown
Up
Down

Dependency objects have composite names, i.e. their names are based on the child_host_name and child_service_name attributes and the name you specified. This means you can define more than one object with the same (short) name as long as one of the child_host_name and child_service_name attributes has a different value.

User

A user.

Example:

object User "icingaadmin" {
  display_name = "Icinga 2 Admin"
  groups = [ "icingaadmins" ]
  email = "icinga@localhost"
  pager = "icingaadmin@localhost.localdomain"

  period = "24x7"

  states = [ OK, Warning, Critical, Unknown ]
  types = [ Problem, Recovery ]

  vars.additional_notes = "This is the Icinga 2 Admin account."
}

Available notification state filters:

OK
Warning
Critical
Unknown
Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

Attributes:

Name	Description
display_name	Optional. A short description of the user.
email	Optional. An email string for this user. Useful for notification commands.
pager	Optional. A pager string for this user. Useful for notification commands.
vars	Optional. A dictionary containing custom attributes that are specific to this user.
groups	Optional. An array of group names.
enable_notifications	Optional. Whether notifications are enabled for this user.
period	Optional. The name of a time period which determines when a notification for this user should be triggered. Not set by default.
types	Optional. A set of type filters when this notification should be triggered. By default everything is matched.
states	Optional. A set of state filters when this notification should be triggered. By default everything is matched.

UserGroup

A user group.

Example:

object UserGroup "icingaadmins" {
    display_name = "Icinga 2 Admin Group"
}

Attributes:

Name	Description
display_name	Optional. A short description of the user group.
groups	Optional. An array of nested group names.

TimePeriod

Time periods can be used to specify when services should be checked or to limit when notifications should be sent out.

Example:

object TimePeriod "24x7" {
  import "legacy-timeperiod"

  display_name = "Icinga 2 24x7 TimePeriod"

  ranges = {
    monday = "00:00-24:00"
    tuesday = "00:00-24:00"
    wednesday = "00:00-24:00"
    thursday = "00:00-24:00"
    friday = "00:00-24:00"
    saturday = "00:00-24:00"
    sunday = "00:00-24:00"
  }
}

Attributes:

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 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 timeperiods including this one.

ScheduledDowntime

ScheduledDowntime objects can be used to set up recurring downtimes for services.

Best Practice

Rather than creating a ScheduledDowntime object for a specific host or service it is usually easier to just create a ScheduledDowntime template and use the apply keyword to assign the scheduled downtime to a number of hosts or services. Use the to keyword to set the specific target type for Host or Service.

Example:

object ScheduledDowntime "some-downtime" {
  host_name = "localhost"
  service_name = "ping4"

  author = "icingaadmin"
  comment = "Some comment"

  fixed = false
  duration = 30m

  ranges = {
    "sunday" = "02:00-03:00"
  }
}

Attributes:

Name	Description
host_name	Required. The name of the host this scheduled downtime belongs to.
service_name	Optional. The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
author	Required. The author of the downtime.
comment	Required. A comment for the downtime.
fixed	Optional. Whether this is a fixed downtime. Defaults to true.
duration	Optional. How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges	Required. A dictionary containing information which days and durations apply to this timeperiod.

ScheduledDowntime objects have composite names, i.e. their names are based on the host_name and service_name attributes and the name you specified. This means you can define more than one object with the same (short) name as long as one of the host_name and service_name attributes has a different value.

FileLogger

Specifies Icinga 2 logging to a file.

Example:

object FileLogger "debug-file" {
  severity = "debug"
  path = "/var/log/icinga2/debug.log"
}

Attributes:

Name	Description
path	Required. The log path.
severity	Optional. The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

SyslogLogger

Specifies Icinga 2 logging to syslog.

Example:

object SyslogLogger "crit-syslog" {
  severity = "critical"
}

Attributes:

Name	Description
severity	Optional. The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "warning".

CheckCommand

A check command definition. Additional default command custom attributes can be defined here.

Example:

object CheckCommand "check_snmp" {
  import "plugin-check-command"

  command = [
    PluginDir + "/check_snmp",
"-H", "$address$",
"-C", "$community$",
"-o", "$oid$"
  ]

  vars.address = "127.0.0.1"
  vars.community = "public"
}

Attributes:

Name	Description
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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes that are specific to this command.
timeout	Optional. The command timeout in seconds. Defaults to 5 minutes.

NotificationCommand

A notification command definition.

Example:

object NotificationCommand "mail-service-notification" {
  import "plugin-notification-command"

  command = [
    SysconfDir + "/icinga2/scripts/mail-notification.sh"
  ]

  env = {
    "NOTIFICATIONTYPE" = "$notification.type$"
    "SERVICEDESC" = "$service.name$"
    "HOSTALIAS" = "$host.display_name$",
    "HOSTADDRESS" = "$address$",
    "SERVICESTATE" = "$service.state$",
    "LONGDATETIME" = "$icinga.long_date_time$",
    "SERVICEOUTPUT" = "$service.output$",
    "NOTIFICATIONAUTHORNAME" = "$notification.author$",
    "NOTIFICATIONCOMMENT" = "$notification.comment$",
    "HOSTDISPLAYNAME" = "$host.display_name$",
    "SERVICEDISPLAYNAME" = "$service.display_name$",
    "USEREMAIL" = "$user.email$"
  }
}

Attributes:

Name	Description
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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes that are specific to this command.
timeout	Optional. The command timeout in seconds. Defaults to 5 minutes.

EventCommand

An event command definition.

Example:

object EventCommand "restart-httpd-event" {
  import "plugin-event-command"

  command = "/opt/bin/restart-httpd.sh"
}

Attributes:

Name	Description
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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes that are specific to this command.
timeout	Optional. The command timeout in seconds. Defaults to 5 minutes.

PerfdataWriter

Writes check result performance data to a defined path using macro pattern consisting of custom attributes and runtime macros.

Example:

library "perfdata"

object PerfdataWriter "pnp" {
  host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"

  service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"

  host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
  service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"

  rotation_interval = 15s
}

Attributes:

Name	Description
host_perfdata_path	Optional. Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
service_perfdata_path	Optional. Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
host_temp_path	Optional. Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
service_temp_path	Optional. Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
host_format_template	Optional. Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
service_format_template	Optional. Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
rotation_interval	Optional. Rotation interval for the files specified in `{host,service}\_perfdata\_path`. Defaults to 30 seconds.

When rotating the performance data file the current UNIX timestamp is appended to the path specified in host_perfdata\_path and service_perfdata\_path to generate a unique filename.

GraphiteWriter

Writes check result metrics and performance data to a defined Graphite Carbon host.

Example:

library "perfdata"

object GraphiteWriter "graphite" {
  host = "127.0.0.1"
  port = 2003
}

Attributes:

Name	Description
host	Optional. Graphite Carbon host address. Defaults to '127.0.0.1'.
port	Optional. Graphite Carbon port. Defaults to 2003.

IdoMySqlConnection

IDO database adapter for MySQL.

Example:

library "db_ido_mysql"

object IdoMysqlConnection "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"

  cleanup = {
    downtimehistory_age = 48h
    logentries_age = 31d
  }

  categories = DbCatConfig | DbCatState
}

Attributes:

Name	Description
host	Optional. MySQL database host address. Defaults to "localhost".
port	Optional. MySQL database port. Defaults to 3306.
user	Optional. MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
password	Optional. MySQL database user's password. Defaults to "icinga".
database	Optional. MySQL database name. Defaults to "icinga".
table_prefix	Optional. MySQL database table prefix. Defaults to "icinga_".
instance_name	Optional. Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance_description	Optional. Description for the Icinga 2 instance.
cleanup	Optional. Dictionary with items for historical table cleanup.
categories	Optional. The types of information that should be written to the database.

Cleanup Items:

Name	Description
acknowledgements_age	Optional. Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
commenthistory_age	Optional. Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
contactnotifications_age	Optional. Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
contactnotificationmethods_age	Optional. Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
downtimehistory_age	Optional. Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
eventhandlers_age	Optional. Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
externalcommands_age	Optional. Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
flappinghistory_age	Optional. Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
hostchecks_age	Optional. Max age for hostalives table rows (start_time). Defaults to 0 (never).
logentries_age	Optional. Max age for logentries table rows (logentry_time). Defaults to 0 (never).
notifications_age	Optional. Max age for notifications table rows (start_time). Defaults to 0 (never).
processevents_age	Optional. Max age for processevents table rows (event_time). Defaults to 0 (never).
statehistory_age	Optional. Max age for statehistory table rows (state_time). Defaults to 0 (never).
servicechecks_age	Optional. Max age for servicechecks table rows (start_time). Defaults to 0 (never).
systemcommands_age	Optional. Max age for systemcommands table rows (start_time). Defaults to 0 (never).

Data Categories:

Name	Description
DbCatConfig	Configuration data
DbCatState	Current state data
DbCatAcknowledgement	Acknowledgements
DbCatComment	Comments
DbCatDowntime	Downtimes
DbCatEventHandler	Event handler data
DbCatExternalCommand	External commands
DbCatFlapping	Flap detection data
DbCatCheck	Check results
DbCatLog	Log messages
DbCatNotification	Notifications
DbCatProgramStatus	Program status data
DbCatRetention	Retention data
DbCatStateHistory	Historical state data

Multiple categories can be combined using the | operator. In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

IdoPgSqlConnection

IDO database adapter for PostgreSQL.

Example:

library "db_ido_pgsql"

object IdoMysqlConnection "pgsql-ido" {
  host = "127.0.0.1"
  port = 5432
  user = "icinga"
  password = "icinga"
  database = "icinga"
  table_prefix = "icinga_"
  instance_name = "icinga2"
  instance_description = "icinga2 dev instance"

  cleanup = {
    downtimehistory_age = 48h
    logentries_age = 31d
  }

  categories = DbCatConfig | DbCatState
}

Attributes:

Name	Description
host	Optional. PostgreSQL database host address. Defaults to "localhost".
port	Optional. PostgreSQL database port. Defaults to "5432".
user	Optional. PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
password	Optional. PostgreSQL database user's password. Defaults to "icinga".
database	Optional. PostgreSQL database name. Defaults to "icinga".
table_prefix	Optional. PostgreSQL database table prefix. Defaults to "icinga_".
instance_name	Optional. Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance_description	Optional. Description for the Icinga 2 instance.
cleanup	Optional. Dictionary with items for historical table cleanup.
categories	Optional. The types of information that should be written to the database.

Cleanup Items:

Name	Description
acknowledgements_age	Optional. Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
commenthistory_age	Optional. Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
contactnotifications_age	Optional. Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
contactnotificationmethods_age	Optional. Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
downtimehistory_age	Optional. Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
eventhandlers_age	Optional. Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
externalcommands_age	Optional. Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
flappinghistory_age	Optional. Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
hostchecks_age	Optional. Max age for hostalives table rows (start_time). Defaults to 0 (never).
logentries_age	Optional. Max age for logentries table rows (logentry_time). Defaults to 0 (never).
notifications_age	Optional. Max age for notifications table rows (start_time). Defaults to 0 (never).
processevents_age	Optional. Max age for processevents table rows (event_time). Defaults to 0 (never).
statehistory_age	Optional. Max age for statehistory table rows (state_time). Defaults to 0 (never).
servicechecks_age	Optional. Max age for servicechecks table rows (start_time). Defaults to 0 (never).
systemcommands_age	Optional. Max age for systemcommands table rows (start_time). Defaults to 0 (never).

Data Categories:

Name	Description
DbCatConfig	Configuration data
DbCatState	Current state data
DbCatAcknowledgement	Acknowledgements
DbCatComment	Comments
DbCatDowntime	Downtimes
DbCatEventHandler	Event handler data
DbCatExternalCommand	External commands
DbCatFlapping	Flap detection data
DbCatCheck	Check results
DbCatLog	Log messages
DbCatNotification	Notifications
DbCatProgramStatus	Program status data
DbCatRetention	Retention data
DbCatStateHistory	Historical state data

Multiple categories can be combined using the | operator. In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

LiveStatusListener

Livestatus API interface available as TCP or UNIX socket. Historical table queries require the CompatLogger feature enabled pointing to the log files using the compat_log_path configuration attribute.

Example:

library "livestatus"

object LivestatusListener "livestatus-tcp" {
  socket_type = "tcp"
  bind_host = "127.0.0.1"
  bind_port = "6558"
}

object LivestatusListener "livestatus-unix" {
  socket_type = "unix"
  socket_path = "/var/run/icinga2/cmd/livestatus"
}

Attributes:

Name	Description
socket_type	Optional. Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
bind_host	Optional. Only valid when socket_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
bind_port	Optional. Only valid when `socket\_type` is "tcp". Port to listen on for connections. Defaults to 6558.
socket_path	Optional. Only valid when `socket\_type` is "unix". Specifies the path to the UNIX socket file. Defaults to LocalStateDir + "/run/icinga2/cmd/livestatus".
compat_log_path	Optional. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"

Note

UNIX sockets are not supported on Windows.

StatusDataWriter

Periodically writes status data files which are used by the Classic UI and other third-party tools.

Example:

library "compat"

object StatusDataWriter "status" {
    status\_path = "/var/cache/icinga2/status.dat"
    objects\_path = "/var/cache/icinga2/objects.path"
    update\_interval = 30s
}

Attributes:

Name	Description
status_path	Optional. Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
objects_path	Optional. Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
update_interval	Optional. The interval in which the status files are updated. Defaults to 15 seconds.

ExternalCommandListener

Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.

Example:

library "compat"

object ExternalCommandListener "external" {
    command\_path = "/var/run/icinga2/cmd/icinga2.cmd"
}

Attributes:

Name	Description
command_path	Optional. Path to the command pipe. Defaults to LocalStateDir + "/run/icinga2/cmd/icinga2.cmd".

CompatLogger

Writes log files in a format that's compatible with Icinga 1.x.

Example:

library "compat"

object CompatLogger "my-log" {
  log\_dir = "/var/log/icinga2/compat"
  rotation\_method = "HOURLY"
}

Attributes:

Name	Description
log_dir	Optional. Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
rotation_method	Optional. Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".

CheckResultReader

Reads Icinga 1.x check results from a directory. This functionality is provided to help existing Icinga 1.x users and might be useful for certain cluster scenarios.

Example:

library "compat"

object CheckResultReader "reader" {
  spool_dir = "/data/check-results"
}

Attributes:

Name	Description
spool_dir	Optional. The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".

CheckerComponent

The checker component is responsible for scheduling active checks. There are no configurable options.

Example:

library "checker"

object CheckerComponent "checker" { }

NotificationComponent

The notification component is responsible for sending notifications. There are no configurable options.

Example:

library "notification"

object NotificationComponent "notification" { }

IcingaStatusWriter

The IcingaStatusWriter feature periodically dumps the current status and performance data from Icinga 2 and all registered features into a defined JSON file.

Example:

object IcingaStatusWriter "status" {
  status_path = LocalStateDir + "/cache/icinga2/status.json"
  update_interval = 15s
}

Attributes:

Name	Description
status_path	Optional. Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
update_interval	Optional. The interval in which the status files are updated. Defaults to 15 seconds.

ClusterListener

ClusterListener objects are used to specify remote cluster node peers and the certificate files used for ssl authorization.

Example:

library "cluster"

object ClusterListener "cluster" {
  ca_path = "/etc/icinga2/ca/ca.crt"
  cert_path = "/etc/icinga2/ca/icinga2a.crt"
  key_path = "/etc/icinga2/ca/icinga2a.key"

  bind_port = 8888

  peers = [ "icinga2b" ]
}

Attributes:

Name	Description
cert_path	Required. Path to the public key.
key_path	Required. Path to the private key.
ca_path	Required. Path to the CA certificate file.
crl_path	Optional. Path to the CRL file.
bind_host	Optional. The IP address the cluster listener should be bound to.
bind_port	Optional. The port the cluster listener should be bound to.
peers	Optional. A list of

Endpoint

Endpoint objects are used to specify connection information for remote Icinga 2 instances.

Example:

library "cluster"

object Endpoint "icinga2b" {
  host = "192.168.5.46"
  port = 7777

  metric = 0

  config_files = [ "/etc/icinga2/cluster.d/*" ]

  config_files_recursive = [
    "/etc/icinga2/cluster2",
    { path = "/etc/icinga2/cluster3"; pattern = "*.myconf" }
  ]
}

Attributes:

Name	Description
host	Required. The hostname/IP address of the remote Icinga 2 instance.
port	Required. The service name/port of the remote Icinga 2 instance.
metric	Optional. The link metric for this endpoint. Defaults to 0.
config_files	Optional. A list of configuration files sent to remote peers (wildcards possible).
config_files_recursive	Optional. A list of configuration files sent to remote peers. Array elements can either be a string (in which case all files in that directory matching the pattern *.conf are included) or a dictionary with elements "path" and "pattern".
accept_config	Optional. A list of endpoint names from which this endpoint accepts configuration files.

Domain

A Service object can be restricted using the domains attribute array specifying endpoint privileges.

A Domain object specifices the ACLs applied for each Endpoint.

Example:

object Domain "dmz-1" {
  acl = {
    node1 = DomainPrivCheckResult
    node2 = DomainPrivReadWrite
  }
}

Attributes:

Name	Description
acl	Required. Dictionary with items for Domain ACLs.

Domain ACLs:

Name	Description
DomainPrivRead	Endpoint reads local messages and relays them to remote nodes.
DomainPrivCheckResult	Endpoint accepts check result messages from remote nodes.
DomainPrivCommand	Endpoint accepts command messages from remote nodes.
DomainPrevReadOnly	Equivalent to DomainPrivRead.
DomainPrivReadWrite	Equivalent to DomainPrivRead \| DomainPrivCheckResult \| DomainPrivCommand.

58 KiB Raw Blame History

Configuring Icinga 2

Configuration Syntax

Object Definition

Expressions

Numeric Literals

Duration Literals

String Literals

Multi-line String Literals

Boolean Literals

Null Value

Dictionary

Array

Operators

Function Calls

Dictionary Operators

Operator =

Operator +=

Operator -=

Operator *=

Operator /=

Indexer

Template Imports

Constants

Apply

Group Assign

Boolean Values

Comments

Includes

Recursive Includes

Library directive

Global Constants

Object Types

Host

HostGroup

Service

ServiceGroup

Notification

Dependency

User

UserGroup

TimePeriod

ScheduledDowntime

FileLogger

SyslogLogger

CheckCommand

NotificationCommand

EventCommand

PerfdataWriter

GraphiteWriter

IdoMySqlConnection

IdoPgSqlConnection

LiveStatusListener

StatusDataWriter

ExternalCommandListener

CompatLogger

CheckResultReader

CheckerComponent

NotificationComponent

IcingaStatusWriter

ClusterListener

Endpoint

Domain

58 KiB

Raw Blame History