icinga2/doc/4.1-configuration-syntax.md

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",

  macros = {
    address = "192.168.0.1"
  }
}

Note

The Icinga 2 configuration format is agnostic to white space characters and new-lines.

Note

Exclamation marks (!) 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:

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).

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.}}}

Note

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
}

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 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 ]

Note

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
!, ~	~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

== | "hello" == "hello" (true), 3 == 5 (false) | Equal to != | "hello" != "world" (true), 3 != 3 (false) | Not equal to in | "foo" in [ "foo", "bar" ] (true) | Element contained in array !in | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array () | (3 + 3) * 5 | Groups sub-expressions

Constants may be used in constant 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(string)	Writes a message to the log.

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 +=

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.

Indexer

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

Example:

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

This is equivalent to writing:

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

Object Inheritance

Objects can inherit attributes from other objects.

Example:

template Host "default-host" {
  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",
  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.

Note

The final macros dictionary contains all three macros and the macro color has the value "blue".

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

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

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.

Constants cannot be changed once they are set.

Note

The set and var keywords are an alias for const and are available in order to provide compatibility with older versions. Their use is deprecated.

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 two object types.

template Service "ping-service" {
  short_name = "ping",
  check_command = "ping4"
}

apply template Service "ping-service" to Host where host == "localhost"

In this example the where condition is a constant expression which is evaluated for all objects of type Host and a new service is created for each matching host.

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

Comments

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

Example:

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

Includes

Other configuration files can be included using the include directive. Paths must be relative to the configuration file that contains the include directive.

Example:

include "some/other/file.conf"
include "conf.d/*.conf"

Note

Wildcard includes are not recursive.

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

include <itl/itl.conf>

Note the use of angle brackets instead of double quotes. This causes the config compiler to search the include search paths for the specified file. By default $PREFIX/icinga2 is included in the list of search paths. 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 methods.

Example:

library "snmphelper"

Note

The icinga library is automatically loaded at startup. You don't need to load it manually.