1 # <a id="language-reference"></a> Language Reference
3 ## <a id="object-definition"></a> Object Definition
5 Icinga 2 features an object-based configuration format. You can define new
6 objects using the `object` keyword:
8 object Host "host1.example.org" {
11 address = "192.168.0.1"
15 In general you need to write each statement on a new line. Expressions started
16 with `{`, `(` and `[` extend until the matching closing character and can be broken
17 up into multiple lines.
19 Alternatively you can write multiple statements on a single line by separating
20 them with a semicolon:
22 object Host "host1.example.org" {
23 display_name = "host1"
25 address = "192.168.0.1"; address6 = "::1"
28 Each object is uniquely identified by its type (`Host`) and name
29 (`host1.example.org`). Some types have composite names, e.g. the
30 `Service` type which uses the `host_name` attribute and the name
31 you specified to generate its object name.
33 Exclamation marks (!) are not permitted in object names.
35 Objects can contain a comma-separated list of property
36 declarations. Instead of commas semicolons may also be used.
37 The following data types are available for property values:
39 All objects have at least the following attributes:
41 Attribute | Description
42 ---------------------|-----------------------------
43 name | The name of the object. This attribute can be modified in the object definition to override the name specified with the `object` directive.
44 type | The type of the object.
48 The following expressions can be used on the right-hand side of assignments.
50 ### <a id="numeric-literals"></a> Numeric Literals
52 A floating-point number.
58 ### <a id="duration-literals"></a> Duration Literals
60 Similar to floating-point numbers except for the fact that they support
61 suffixes to help with specifying time durations.
67 Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
68 h (hours) and d (days).
70 Duration literals are converted to seconds by the config parser and
71 are treated like numeric literals.
73 ### <a id="string-literals"></a> String Literals
81 Certain characters need to be escaped. The following escape sequences
84 Character | Escape sequence
85 --------------------------|------------------------------------
90 <CARRIAGE-RETURN> | \\r
91 <LINE-FEED> | \\n
93 <FORM-FEED> | \\f
95 In addition to these pre-defined escape sequences you can specify
96 arbitrary ASCII characters using the backslash character (\\) followed
97 by an ASCII character in octal encoding.
99 ### <a id="multiline-string-literals"></a> Multi-line String Literals
101 Strings spanning multiple lines can be specified by enclosing them in
111 Unlike in ordinary strings special characters do not have to be escaped
112 in multi-line string literals.
114 ### <a id="boolean-literals"></a> Boolean Literals
116 The keywords `true` and `false` are used to denote truth values.
118 ### <a id="null-value"></a> Null Value
120 The `null` keyword can be used to specify an empty value.
122 ### <a id="dictionary"></a> Dictionary
124 An unordered list of key-value pairs. Keys must be unique and are
125 compared in a case-sensitive manner.
127 Individual key-value pairs must either be comma-separated or on separate lines.
128 The comma after the last key-value pair is optional.
133 address = "192.168.0.1"
137 Identifiers may not contain certain characters (e.g. space) or start
138 with certain characters (e.g. digits). If you want to use a dictionary
139 key that is not a valid identifier you can enclose the key in double
142 ### <a id="array"></a> Array
144 An ordered list of values.
146 Individual array elements must be comma-separated.
147 The comma after the last element is optional.
153 An array may simultaneously contain values of different types, such as
156 ### <a id="expression-operators"></a> Operators
158 The following operators are supported in expressions. The operators are by descending precedence.
160 Operator | Precedence | Examples (Result) | Description
161 ---------|------------|-----------------------------------------------|--------------------------------
162 () | 1 | (3 + 3) * 5 | Groups sub-expressions
163 () | 1 | Math.random() | Calls a function
164 [] | 1 | a[3] | Array subscript
165 . | 1 | a.b | Element access
166 ! | 2 | !"Hello" (false), !false (true) | Logical negation of the operand
167 ~ | 2 | ~true (false) | Bitwise negation of the operand
168 + | 2 | +3 | Unary plus
169 - | 2 | -3 | Unary minus
170 * | 3 | 5m * 10 (3000) | Multiplies two numbers
171 / | 3 | 5m / 5 (60) | Divides two numbers
172 % | 3 | 17 % 12 (5) | Remainder after division
173 + | 4 | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
174 - | 4 | 3 - 1 (2) | Subtracts two numbers
175 << | 5 | 4 << 8 (1024) | Left shift
176 >> | 5 | 1024 >> 4 (64) | Right shift
177 < | 6 | 3 < 5 (true) | Less than
178 > | 6 | 3 > 5 (false) | Greater than
179 <= | 6 | 3 <= 3 (true) | Less than or equal
180 >= | 6 | 3 >= 3 (true) | Greater than or equal
181 in | 7 | "foo" in [ "foo", "bar" ] (true) | Element contained in array
182 !in | 7 | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
183 == | 8 | "hello" == "hello" (true), 3 == 5 (false) | Equal to
184 != | 8 | "hello" != "world" (true), 3 != 3 (false) | Not equal to
185 & | 9 | 7 & 3 (3) | Binary AND
186 ^ | 10 | 17 ^ 12 (29) | Bitwise XOR
187 | | 11 | 2 | 3 (3) | Binary OR
188 && | 13 | true && false (false), 3 && 7 (7), 0 && 7 (0) | Logical AND
189 || | 14 | true || false (true), 0 || 7 (7)| Logical OR
190 = | 12 | a = 3 | Assignment
191 => | 15 | x => x * x (function with arg x) | Lambda, for loop
193 ### <a id="function-calls"></a> Function Calls
195 Functions can be called using the `()` operator:
197 const MyGroups = [ "test1", "test" ]
200 check_interval = len(MyGroups) * 1m
203 A list of available functions is available in the [Library Reference](20-library-reference.md#library-reference) chapter.
205 ## <a id="dictionary-operators"></a> Assignments
207 In addition to the `=` operator shown above a number of other operators
208 to manipulate attributes are supported. Here's a list of all
211 ### <a id="operator-assignment"></a> Operator =
213 Sets an attribute to the specified value.
222 In this example `a` has the value `7` after both instructions are executed.
224 ### <a id="operator-additive-assignment"></a> Operator +=
226 The += operator is a shortcut. The following expression:
240 ### <a id="operator-substractive-assignment"></a> Operator -=
242 The -= operator is a shortcut. The following expression:
256 ### <a id="operator-multiply-assignment"></a> Operator \*=
258 The *= operator is a shortcut. The following expression:
272 ### <a id="operator-dividing-assignment"></a> Operator /=
274 The /= operator is a shortcut. The following expression:
288 ## <a id="indexer"></a> Indexer
290 The indexer syntax provides a convenient way to set dictionary elements.
298 Example (alternative syntax):
301 hello["key"] = "world"
304 This is equivalent to writing:
312 If the `hello` attribute does not already have a value it is automatically initialized to an empty dictionary.
314 ## <a id="template-imports"></a> Template Imports
316 Objects can import attributes from other objects.
320 template Host "default-host" {
324 template Host "test-host" {
325 import "default-host"
330 object Host "localhost" {
333 address = "127.0.0.1"
337 The `default-host` and `test-host` objects are marked as templates
338 using the `template` keyword. Unlike ordinary objects templates are not
339 instantiated at run-time. Parent objects do not necessarily have to be
340 templates, however in general they are.
342 The `vars` dictionary for the `localhost` object contains all three
343 custom attributes and the custom attribute `colour` has the value `"blue"`.
345 Parent objects are resolved in the order they're specified using the
348 ## <a id="constants"></a> Constants
350 Global constants can be set using the `const` keyword:
352 const VarName = "some value"
354 Once defined a constant can be accessed from any file. Constants cannot be changed
357 Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
359 Variable |Description
360 --------------------|-------------------
361 PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
362 SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
363 ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to SysconfDir + "/zones.d".
364 LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
365 RunDir |**Read-only.** Contains the path of the run directory. Defaults to LocalStateDir + "/run".
366 PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
367 StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
368 ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to LocalStateDir + "/cache/icinga2/icinga2.debug".
369 PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to RunDir + "/icinga2/icinga2.pid".
370 Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
371 NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
372 EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
373 EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
374 EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
375 EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
376 EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
377 EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
378 UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
379 RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Used in the `init.conf` configuration file.
380 RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Used in the `init.conf` configuration file.
382 ## <a id="apply"></a> Apply
384 The `apply` keyword can be used to create new objects which are associated with
385 another group of objects.
387 apply Service "ping" to Host {
388 import "generic-service"
390 check_command = "ping4"
392 assign where host.name == "localhost"
395 In this example the `assign where` condition is a boolean expression which is
396 evaluated for all objects of type `Host` and a new service with name "ping"
397 is created for each matching host. [Expression operators](19-language-reference.md#expression-operators)
398 may be used in `assign where` conditions.
400 The `to` keyword and the target type may be omitted if there is only one target
401 type, e.g. for the `Service` type.
403 Depending on the object type used in the `apply` expression additional local
404 variables may be available for use in the `where` condition:
406 Source Type | Target Type | Variables
407 ------------------|-------------|--------------
408 Service | Host | host
409 Dependency | Host | host
410 Dependency | Service | host, service
411 Notification | Host | host
412 Notification | Service | host, service
413 ScheduledDowntime | Host | host
414 ScheduledDowntime | Service | host, service
416 Any valid config attribute can be accessed using the `host` and `service`
417 variables. For example, `host.address` would return the value of the host's
418 "address" attribute - or null if that attribute isn't set.
420 ## <a id="group-assign"></a> Group Assign
422 Group objects can be assigned to specific member objects using the `assign where`
423 and `ignore where` conditions.
425 object HostGroup "linux-servers" {
426 display_name = "Linux Servers"
428 assign where host.vars.os == "Linux"
431 In this example the `assign where` condition is a boolean expression which is evaluated
432 for all objects of the type `Host`. Each matching host is added as member to the host group
433 with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
434 condition. [Expression operators](19-language-reference.md#expression-operators) may be used in `assign where` and
435 `ignore where` conditions.
437 Source Type | Variables
438 ------------------|--------------
440 ServiceGroup | host, service
444 ## <a id="boolean-values"></a> Boolean Values
446 The `assign where`, `ignore where`, `if` and `while` statements, the `!` operator as
447 well as the `bool()` function convert their arguments to a boolean value based on the
450 Description | Example Value | Boolean Value
451 ---------------------|-------------------|--------------
452 Empty value | null | false
454 Non-zero integer | -23945 | true
455 Empty string | "" | false
456 Non-empty string | "Hello" | true
457 Empty array | [] | false
458 Non-empty array | [ "Hello" ] | true
459 Empty dictionary | {} | false
460 Non-empty dictionary | { key = "value" } | true
462 For a list of supported expression operators for `assign where` and `ignore where`
463 statements, see [expression operators](19-language-reference.md#expression-operators).
465 ## <a id="comments"></a> Comments
467 The Icinga 2 configuration format supports C/C++-style and shell-style comments.
474 object Host "localhost" {
475 check_interval = 30 // this is also a comment.
476 retry_interval = 15 # yet another comment
479 ## <a id="includes"></a> Includes
481 Other configuration files can be included using the `include` directive.
482 Paths must be relative to the configuration file that contains the
487 include "some/other/file.conf"
488 include "conf.d/*.conf"
490 Wildcard includes are not recursive.
492 Icinga also supports include search paths similar to how they work in a
497 Note the use of angle brackets instead of double quotes. This causes the
498 config compiler to search the include search paths for the specified
499 file. By default $PREFIX/share/icinga2/include is included in the list of search
500 paths. Additional include search paths can be added using
501 [command-line options](8-cli-commands.md#config-include-path).
503 Wildcards are not permitted when using angle brackets.
505 ## <a id="recursive-includes"></a> Recursive Includes
507 The `include_recursive` directive can be used to recursively include all
508 files in a directory which match a certain pattern.
512 include_recursive "conf.d", "*.conf"
513 include_recursive "templates"
515 The first parameter specifies the directory from which files should be
516 recursively included.
518 The file names need to match the pattern given in the second parameter.
519 When no pattern is specified the default pattern "*.conf" is used.
521 ## <a id="library"></a> Library directive
523 The `library` directive can be used to manually load additional
524 libraries. Libraries can be used to provide additional object types and
531 ## <a id="functions"></a> Functions
533 Functions can be defined using the `function` keyword.
537 function multiply(a, b) {
541 When encountering the `return` keyword further execution of the function is terminated and
542 the specified value is supplied to the caller of the function:
546 In this example the `multiply` function we declared earlier is invoked with two arguments (3 and 5).
547 The function computes the product of those arguments and makes the result available to the
550 When no value is supplied for the `return` statement the function returns `null`.
552 Functions which do not have a `return` statement have their return value set to the value of the
553 last expression which was performed by the function. For example, we could have also written our
554 `multiply` function like this:
556 function multiply(a, b) {
560 Anonymous functions can be created by omitting the name in the function definition. The
561 resulting function object can be used like any other value:
563 var fn = function() { 3 }
567 ## <a id="lambdas"></a> Lambda Expressions
569 Functions can also be declared using the alternative lambda syntax.
575 Multiple statements can be used by putting the function body into braces:
582 Just like with ordinary functions the return value is the value of the last statement.
584 For lambdas which take exactly one argument the braces around the arguments can be omitted:
588 ## <a id="nullary-lambdas"></a> Abbreviated Lambda Syntax
590 Lambdas which take no arguments can also be written using the abbreviated lambda syntax.
596 This creates a new function which returns the value 3.
598 ## <a id="variable-scopes"></a> Variable Scopes
600 When setting a variable Icinga checks the following scopes in this order whether the variable
601 already exists there:
607 The local scope contains variables which only exist during the invocation of the current function,
608 object or apply statement. Local variables can be declared using the `var` keyword:
610 function multiply(a, b) {
615 Each time the `multiply` function is invoked a new `temp` variable is used which is in no way
616 related to previous invocations of the function.
618 When setting a variable which has not previously been declared as local using the `var` keyword
619 the `this` scope is used.
621 The `this` scope refers to the current object which the function or object/apply statement
624 object Host "localhost" {
628 In this example the `this` scope refers to the "localhost" object. The `check_interval` attribute
629 is set for this particular host.
631 You can explicitly access the `this` scope using the `this` keyword:
633 object Host "localhost" {
634 var check_interval = 5m
636 /* This explicitly specifies that the attribute should be set
637 * for the host, if we had omitted `this.` the (poorly named)
638 * local variable `check_interval` would have been modified instead.
640 this.check_interval = 1m
643 Similarly the keywords `locals` and `globals` are available to access the local and global scope.
645 Functions also have a `this` scope. However unlike for object/apply statements the `this` scope for
646 a function is set to whichever object was used to invoke the function. Here's an example:
651 function init(word) {
656 /* Let's invoke the init() function */
659 We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
660 scope for this function call.
662 ## <a id="closures"></a> Closures
664 By default `function`s, `object`s and `apply` rules do not have access to variables declared
665 outside of their scope (except for global variables).
667 In order to access variables which are defined in the outer scope the `use` keyword can be used:
669 function MakeHelloFunction(name) {
670 return function() use(name) {
671 log("Hello, " + name)
675 In this case a new variable `name` is created inside the inner function's scope which has the
676 value of the `name` function argument.
678 Alternatively a different value for the inner variable can be specified:
680 function MakeHelloFunction(name) {
681 return function() use (greeting = "Hello, " + name) {
686 ## <a id="conditional-statements"></a> Conditional Statements
688 Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
689 construct can be used to accomplish this.
703 An if/else construct can also be used in place of any other value. The value of an if/else statement
704 is the value of the last statement which was evaluated for the branch which was taken:
707 log("Taking the 'true' branch")
710 log("Taking the 'false' branch")
714 This example prints the log message "Taking the 'true' branch" and the `a` variable is set to 21 (7 * 3).
716 The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
718 ## <a id="while-loops"></a> While Loops
720 The `while` statement checks a condition and executes the loop body when the condition evaluates to `true`.
721 This is repeated until the condition is no longer true.
732 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
733 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
734 breaks out of the loop.
736 ## <a id="for-loops"></a> For Loops
738 The `for` statement can be used to iterate over arrays and dictionaries.
742 var list = [ "a", "b", "c" ]
748 The loop body is evaluated once for each item in the array. The variable `item` is declared as a local
749 variable just as if the `var` keyword had been used.
751 Iterating over dictionaries can be accomplished in a similar manner:
753 var dict = { a = 3, b = 7 }
755 for (key => value in dict) {
756 log("Key: " + key + ", Value: " + value)
759 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
760 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
761 breaks out of the loop.
763 ## <a id="types"></a> Types
765 All values have a static type. The `typeof` function can be used to determine the type of a value:
767 typeof(3) /* Returns an object which represents the type for numbers */
769 The following built-in types are available:
771 Type | Examples | Description
772 -----------|-------------------|------------------------
773 Number | 3.7 | A numerical value.
774 Boolean | true, false | A boolean value.
775 String | "hello" | A string.
776 Array | [ "a", "b" ] | An array.
777 Dictionary | { a = 3 } | A dictionary.
779 Depending on which libraries are loaded additional types may become available. The `icinga`
780 library implements a whole bunch of other types, e.g. Host, Service, CheckCommand, etc.
782 Each type has an associated type object which describes the type's semantics. These
783 type objects are made available using global variables which match the type's name:
785 /* This logs 'true' */
786 log(typeof(3) == Number)
788 The type object's `prototype` property can be used to find out which methods a certain type
791 /* This returns: ["find","len","lower","replace","split","substr","to_string","upper"] */
792 keys(String.prototype)
794 ## <a id="reserved-keywords"></a> Reserved Keywords
796 These keywords are reserved and must not be used as constants or custom attributes.
823 You can escape reserved keywords using the `@` character. The following example
824 tries to set `vars.include` which references a reserved keyword and generates
827 [2014-09-15 17:24:00 +0200] critical/config: Location:
828 /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
829 /etc/icinga2/conf.d/hosts/localhost.conf(14):
830 /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
832 /etc/icinga2/conf.d/hosts/localhost.conf(16): }
833 /etc/icinga2/conf.d/hosts/localhost.conf(17):
835 Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
836 [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
838 You can escape the `include` keyword by prefixing it with an additional `@` character:
840 object Host "localhost" {
841 import "generic-host"
843 address = "127.0.0.1"
849 vars.@include = "some cmdb export field"