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:
41 The following expressions can be used on the right-hand side of assignments.
43 ### <a id="numeric-literals"></a> Numeric Literals
45 A floating-point number.
51 ### <a id="duration-literals"></a> Duration Literals
53 Similar to floating-point numbers except for the fact that they support
54 suffixes to help with specifying time durations.
60 Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
61 h (hours) and d (days).
63 Duration literals are converted to seconds by the config parser and
64 are treated like numeric literals.
66 ### <a id="string-literals"></a> String Literals
74 Certain characters need to be escaped. The following escape sequences
77 Character | Escape sequence
78 --------------------------|------------------------------------
82 <CARRIAGE-RETURN> | \\r
83 <LINE-FEED> | \\n
85 <FORM-FEED> | \\f
87 In addition to these pre-defined escape sequences you can specify
88 arbitrary ASCII characters using the backslash character (\\) followed
89 by an ASCII character in octal encoding.
91 ### <a id="multiline-string-literals"></a> Multi-line String Literals
93 Strings spanning multiple lines can be specified by enclosing them in
103 Unlike in ordinary strings special characters do not have to be escaped
104 in multi-line string literals.
106 ### <a id="boolean-literals"></a> Boolean Literals
108 The keywords `true` and `false` are used to denote truth values.
110 ### <a id="null-value"></a> Null Value
112 The `null` keyword can be used to specify an empty value.
114 ### <a id="dictionary"></a> Dictionary
116 An unordered list of key-value pairs. Keys must be unique and are
117 compared in a case-sensitive manner.
119 Individual key-value pairs must either be comma-separated or on separate lines.
120 The comma after the last key-value pair is optional.
125 address = "192.168.0.1"
129 Identifiers may not contain certain characters (e.g. space) or start
130 with certain characters (e.g. digits). If you want to use a dictionary
131 key that is not a valid identifier you can enclose the key in double
134 ### <a id="array"></a> Array
136 An ordered list of values.
138 Individual array elements must be comma-separated.
139 The comma after the last element is optional.
145 An array may simultaneously contain values of different types, such as
148 ### <a id="expression-operators"></a> Operators
150 The following operators are supported in expressions:
152 Operator | Examples (Result) | Description
153 ---------|-----------------------------------------------|--------------------------------
154 ! | !"Hello" (false), !false (true) | Logical negation of the operand
155 ~ | ~true (false) | Bitwise negation of the operand
156 + | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
158 - | 3 - 1 (2) | Subtracts two numbers
160 * | 5m * 10 (3000) | Multiplies two numbers
161 / | 5m / 5 (60) | Divides two numbers
162 % | 17 % 12 (5) | Remainder after division
163 ^ | 17 ^ 12 (29) | Bitwise XOR
164 & | 7 & 3 (3) | Binary AND
165 | | 2 | 3 (3) | Binary OR
166 && | true && false (false) | Logical AND
167 || | true || false (true) | Logical OR
168 < | 3 < 5 (true) | Less than
169 > | 3 > 5 (false) | Greater than
170 <= | 3 <= 3 (true) | Less than or equal
171 >= | 3 >= 3 (true) | Greater than or equal
172 << | 4 << 8 (1024) | Left shift
173 >> | 1024 >> 4 (64) | Right shift
174 == | "hello" == "hello" (true), 3 == 5 (false) | Equal to
175 != | "hello" != "world" (true), 3 != 3 (false) | Not equal to
176 in | "foo" in [ "foo", "bar" ] (true) | Element contained in array
177 !in | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
178 () | (3 + 3) * 5 | Groups sub-expressions
179 () | Math.random() | Calls a function
181 ### <a id="function-calls"></a> Function Calls
183 Functions can be called using the `()` operator:
185 const MyGroups = [ "test1", "test" ]
188 check_interval = len(MyGroups) * 1m
191 A list of available functions is available in the [Library Reference](11-library-reference.md#library-reference) chapter.
193 ## <a id="dictionary-operators"></a> Assignments
195 In addition to the `=` operator shown above a number of other operators
196 to manipulate attributes are supported. Here's a list of all
199 ### <a id="operator-assignment"></a> Operator =
201 Sets an attribute to the specified value.
210 In this example `a` has the value `7` after both instructions are executed.
212 ### <a id="operator-additive-assignment"></a> Operator +=
214 The += operator is a shortcut. The following expression:
228 ### <a id="operator-substractive-assignment"></a> Operator -=
230 The -= operator is a shortcut. The following expression:
244 ### <a id="operator-multiply-assignment"></a> Operator \*=
246 The *= operator is a shortcut. The following expression:
260 ### <a id="operator-dividing-assignment"></a> Operator /=
262 The /= operator is a shortcut. The following expression:
276 ## <a id="indexer"></a> Indexer
278 The indexer syntax provides a convenient way to set dictionary elements.
286 Example (alternative syntax):
289 hello["key"] = "world"
292 This is equivalent to writing:
300 If the `hello` attribute does not already have a value it is automatically initialized to an empty dictionary.
302 ## <a id="template-imports"></a> Template Imports
304 Objects can import attributes from other objects.
308 template Host "default-host" {
312 template Host "test-host" {
313 import "default-host"
318 object Host "localhost" {
321 address = "127.0.0.1"
325 The `default-host` and `test-host` objects are marked as templates
326 using the `template` keyword. Unlike ordinary objects templates are not
327 instantiated at run-time. Parent objects do not necessarily have to be
328 templates, however in general they are.
330 The `vars` dictionary for the `localhost` object contains all three
331 custom attributes and the custom attribute `colour` has the value `"blue"`.
333 Parent objects are resolved in the order they're specified using the
336 ## <a id="constants"></a> Constants
338 Global constants can be set using the `const` keyword:
340 const VarName = "some value"
342 Once defined a constant can be accessed from any file. Constants cannot be changed
345 Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
347 Variable |Description
348 --------------------|-------------------
349 PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
350 SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
351 ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to SysconfDir + "/zones.d".
352 LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
353 RunDir |**Read-only.** Contains the path of the run directory. Defaults to LocalStateDir + "/run".
354 PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
355 StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
356 ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to LocalStateDir + "/cache/icinga2/icinga2.debug".
357 PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to RunDir + "/icinga2/icinga2.pid".
358 Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
359 NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
360 ApplicationType |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
361 EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
362 EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
363 EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
364 EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
365 EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
366 EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
367 UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
368 RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Used in the `init.conf` configuration file.
369 RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Used in the `init.conf` configuration file.
371 ## <a id="apply"></a> Apply
373 The `apply` keyword can be used to create new objects which are associated with
374 another group of objects.
376 apply Service "ping" to Host {
377 import "generic-service"
379 check_command = "ping4"
381 assign where host.name == "localhost"
384 In this example the `assign where` condition is a boolean expression which is
385 evaluated for all objects of type `Host` and a new service with name "ping"
386 is created for each matching host. [Expression operators](10-language-reference.md#expression-operators)
387 may be used in `assign where` conditions.
389 The `to` keyword and the target type may be omitted if there is only one target
390 type, e.g. for the `Service` type.
392 Depending on the object type used in the `apply` expression additional local
393 variables may be available for use in the `where` condition:
395 Source Type | Target Type | Variables
396 ------------------|-------------|--------------
397 Service | Host | host
398 Dependency | Host | host
399 Dependency | Service | host, service
400 Notification | Host | host
401 Notification | Service | host, service
402 ScheduledDowntime | Host | host
403 ScheduledDowntime | Service | host, service
405 Any valid config attribute can be accessed using the `host` and `service`
406 variables. For example, `host.address` would return the value of the host's
407 "address" attribute - or null if that attribute isn't set.
409 ## <a id="group-assign"></a> Group Assign
411 Group objects can be assigned to specific member objects using the `assign where`
412 and `ignore where` conditions.
414 object HostGroup "linux-servers" {
415 display_name = "Linux Servers"
417 assign where host.vars.os == "Linux"
420 In this example the `assign where` condition is a boolean expression which is evaluated
421 for all objects of the type `Host`. Each matching host is added as member to the host group
422 with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
423 condition. [Expression operators](10-language-reference.md#expression-operators) may be used in `assign where` and
424 `ignore where` conditions.
426 Source Type | Variables
427 ------------------|--------------
429 ServiceGroup | host, service
433 ## <a id="boolean-values"></a> Boolean Values
435 The `assign where` and `ignore where` statements, the `!`, `&&` and `||`
436 operators as well as the `bool()` function convert their arguments to a
437 boolean value based on the following rules:
439 Description | Example Value | Boolean Value
440 ---------------------|-------------------|--------------
441 Empty value | null | false
443 Non-zero integer | -23945 | true
444 Empty string | "" | false
445 Non-empty string | "Hello" | true
446 Empty array | [] | false
447 Non-empty array | [ "Hello" ] | true
448 Empty dictionary | {} | false
449 Non-empty dictionary | { key = "value" } | true
451 For a list of supported expression operators for `assign where` and `ignore where`
452 statements, see [expression operators](10-language-reference.md#expression-operators).
454 ## <a id="comments"></a> Comments
456 The Icinga 2 configuration format supports C/C++-style and shell-style comments.
463 object Host "localhost" {
464 check_interval = 30 // this is also a comment.
465 retry_interval = 15 # yet another comment
468 ## <a id="includes"></a> Includes
470 Other configuration files can be included using the `include` directive.
471 Paths must be relative to the configuration file that contains the
476 include "some/other/file.conf"
477 include "conf.d/*.conf"
479 Wildcard includes are not recursive.
481 Icinga also supports include search paths similar to how they work in a
486 Note the use of angle brackets instead of double quotes. This causes the
487 config compiler to search the include search paths for the specified
488 file. By default $PREFIX/share/icinga2/include is included in the list of search
489 paths. Additional include search paths can be added using
490 [command-line options](5-cli-commands.md#config-include-path).
492 Wildcards are not permitted when using angle brackets.
494 ## <a id="recursive-includes"></a> Recursive Includes
496 The `include_recursive` directive can be used to recursively include all
497 files in a directory which match a certain pattern.
501 include_recursive "conf.d", "*.conf"
502 include_recursive "templates"
504 The first parameter specifies the directory from which files should be
505 recursively included.
507 The file names need to match the pattern given in the second parameter.
508 When no pattern is specified the default pattern "*.conf" is used.
510 ## <a id="library"></a> Library directive
512 The `library` directive can be used to manually load additional
513 libraries. Libraries can be used to provide additional object types and
520 ## <a id="functions"></a> Functions
522 Functions can be defined using the `function` keyword.
526 function multiply(a, b) {
530 When encountering the `return` keyword further execution of the function is terminated and
531 the specified value is supplied to the caller of the function:
535 In this example the `multiply` function we declared earlier is invoked with two arguments (3 and 5).
536 The function computes the product of those arguments and makes the result available to the
539 When no value is supplied for the `return` statement the function returns `null`.
541 Functions which do not have a `return` statement have their return value set to the value of the
542 last expression which was performed by the function. For example, we could have also written our
543 `multiply` function like this:
545 function multiply(a, b) {
549 Anonymous functions can be created by omitting the name in the function definition. The
550 resulting function object can be used like any other value:
552 var fn = function() { 3 }
556 ## <a id="lambdas"></a> Lambda Expressions
558 Functions can also be declared using the alternative lambda syntax.
564 Multiple statements can be used by putting the function body into braces:
571 Just like with ordinary functions the return value is the value of the last statement.
573 For lambdas which take exactly one argument the braces around the arguments can be omitted:
577 ## <a id="variable-scopes"></a> Variable Scopes
579 When setting a variable Icinga checks the following scopes in this order whether the variable
580 already exists there:
586 The local scope contains variables which only exist during the invocation of the current function,
587 object or apply statement. Local variables can be declared using the `var` keyword:
589 function multiply(a, b) {
594 Each time the `multiply` function is invoked a new `temp` variable is used which is in no way
595 related to previous invocations of the function.
597 When setting a variable which has not previously been declared as local using the `var` keyword
598 the `this` scope is used.
600 The `this` scope refers to the current object which the function or object/apply statement
603 object Host "localhost" {
607 In this example the `this` scope refers to the "localhost" object. The `check_interval` attribute
608 is set for this particular host.
610 You can explicitly access the `this` scope using the `this` keyword:
612 object Host "localhost" {
613 var check_interval = 5m
615 /* This explicitly specifies that the attribute should be set
616 * for the host, if we had omitted `this.` the (poorly named)
617 * local variable `check_interval` would have been modified instead.
619 this.check_interval = 1m
622 Similarly the keywords `locals` and `globals` are available to access the local and global scope.
624 Functions also have a `this` scope. However unlike for object/apply statements the `this` scope for
625 a function is set to whichever object was used to invoke the function. Here's an example:
630 function init(word) {
635 /* Let's invoke the init() function */
638 We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
639 scope for this function call.
641 ## <a id="conditional-statements"></a> Conditional Statements
643 Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
644 construct can be used to accomplish this.
656 An if/else construct can also be used in place of any other value. The value of an if/else statement
657 is the value of the last statement which was evaluated for the branch which was taken:
660 log("Taking the 'true' branch")
663 log("Taking the 'false' branch")
667 This example prints the log message "Taking the 'true' branch" and the `a` variable is set to 21 (7 * 3).
669 The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
671 ## <a id="for-loops"></a> For Loops
673 The `for` statement can be used to iterate over arrays and dictionaries.
677 var list = [ "a", "b", "c" ]
683 The loop body is evaluated once for each item in the array. The variable `item` is declared as a local
684 variable just as if the `var` keyword had been used.
686 Iterating over dictionaries can be accomplished in a similar manner:
688 var dict = { a = 3, b = 7 }
690 for (key => value in dict) {
691 log("Key: " + key + ", Value: " + value)
694 ## <a id="types"></a> Types
696 All values have a static type. The `typeof` function can be used to determine the type of a value:
698 typeof(3) /* Returns an object which represents the type for numbers */
700 The following built-in types are available:
702 Type | Examples | Description
703 -----------|-------------------|------------------------
704 Number | 3.7 | A numerical value.
705 Boolean | true, false | A boolean value.
706 String | "hello" | A string.
707 Array | [ "a", "b" ] | An array.
708 Dictionary | { a = 3 } | A dictionary.
710 Depending on which libraries are loaded additional types may become available. The `icinga`
711 library implements a whole bunch of other types, e.g. Host, Service, CheckCommand, etc.
713 Each type has an associated type object which describes the type's semantics. These
714 type objects are made available using global variables which match the type's name:
716 /* This logs 'true' */
717 log(typeof(3) == Number)
719 The type object's `prototype` property can be used to find out which methods a certain type
722 /* This returns: ["find","len","lower","replace","split","substr","to_string","upper"] */
723 keys(String.prototype)
725 ## <a id="reserved-keywords"></a> Reserved Keywords
727 These keywords are reserved and must not be used as constants or custom attributes.
754 You can escape reserved keywords using the `@` character. The following example
755 tries to set `vars.include` which references a reserved keyword and generates
758 [2014-09-15 17:24:00 +0200] critical/config: Location:
759 /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
760 /etc/icinga2/conf.d/hosts/localhost.conf(14):
761 /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
763 /etc/icinga2/conf.d/hosts/localhost.conf(16): }
764 /etc/icinga2/conf.d/hosts/localhost.conf(17):
766 Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
767 [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
769 You can escape the `include` keyword by prefixing it with an additional `@` character:
771 object Host "localhost" {
772 import "generic-host"
774 address = "127.0.0.1"
780 vars.@include = "some cmdb export field"