9.6 KiB
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
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 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 to 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
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.
Indexer
The indexer syntax provides a convenient way to set dictionary elements.
Example:
{
hello["key"] = "world"
}
This is equivalent to writing:
{
hello += {
key = "world"
}
}
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 3 macros and the macro
color
has the value"blue"
.
Parent objects are resolved in the order they're specified using the
inherits
keyword.
Variables
Global variables can be set using the set
keyword:
set VarName = "some value"
The value can be a string, number, array or a dictionary.
Constant Expressions
Simple calculations can be performed using the constant expression syntax:
{
check_interval = (15 * 60)
}
Valid operators include +, -, * and /. The default precedence rules can be overridden by grouping expressions using parentheses:
{
check_interval ((15 * 60) / 2)
}
Global variables may be used in constant expressions.
set MyCheckInterval = 10m
...
{
check_interval = (MyCheckInterval / 2.5)
}
Note
Constant expressions are evaluated as soon as they're encountered in the configuration file.
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.