1 # Language Reference <a id="language-reference"></a>
3 ## Object Definition <a id="object-definition"></a>
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"
12 address6 = "2001:db8:1234::42"
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 = "2001:db8:1234::42"
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.
46 ## Expressions <a id="expressions"></a>
48 The following expressions can be used on the right-hand side of assignments.
50 ### Numeric Literals <a id="numeric-literals"></a>
52 A floating-point number.
58 ### Duration Literals <a id="duration-literals"></a>
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 ### String Literals <a id="string-literals"></a>
81 #### String Literals Escape Sequences <a id="string-literals-escape-sequences"></a>
83 Certain characters need to be escaped. The following escape sequences
86 Character | Escape sequence
87 --------------------------|------------------------------------
91 <CARRIAGE-RETURN> | \\r
92 <LINE-FEED> | \\n
94 <FORM-FEED> | \\f
96 In addition to these pre-defined escape sequences you can specify
97 arbitrary ASCII characters using the backslash character (\\) followed
98 by an ASCII character in octal encoding.
100 ### Multi-line String Literals <a id="multiline-string-literals"></a>
102 Strings spanning multiple lines can be specified by enclosing them in
112 Unlike in ordinary strings special characters do not have to be escaped
113 in multi-line string literals.
115 ### Boolean Literals <a id="boolean-literals"></a>
117 The keywords `true` and `false` are used to denote truth values.
119 ### Null Value <a id="null-value"></a>
121 The `null` keyword can be used to specify an empty value.
123 ### Dictionary <a id="dictionary"></a>
125 An unordered list of key-value pairs. Keys must be unique and are
126 compared in a case-sensitive manner.
128 Individual key-value pairs must either be comma-separated or on separate lines.
129 The comma after the last key-value pair is optional.
134 address = "192.168.0.1"
138 Identifiers may not contain certain characters (e.g. space) or start
139 with certain characters (e.g. digits). If you want to use a dictionary
140 key that is not a valid identifier, you can enclose the key in double
143 ### Array <a id="array"></a>
145 An ordered list of values.
147 Individual array elements must be comma-separated.
148 The comma after the last element is optional.
154 An array may simultaneously contain values of different types, such as
157 ### Operators <a id="expression-operators"></a>
159 The following operators are supported in expressions. The operators are sorted by descending precedence.
161 Operator | Precedence | Examples (Result) | Description
162 ---------|------------|-----------------------------------------------|--------------------------------
163 `()` | 1 | (3 + 3) * 5 | Groups sub-expressions
164 `()` | 1 | Math.random() | Calls a function
165 `[]` | 1 | a[3] | Array subscript
166 `.` | 1 | a.b | Element access
167 `!` | 2 | !"Hello" (false), !false (true) | Logical negation of the operand
168 `~` | 2 | ~true (false) | Bitwise negation of the operand
169 `+` | 2 | +3 | Unary plus
170 `-` | 2 | -3 | Unary minus
171 `&` | 2 | &var (reference to 'var') | Reference operator
172 `*` | 2 | *var | Indirection operator
173 `*` | 3 | 5m * 10 (3000) | Multiplies two numbers
174 `/` | 3 | 5m / 5 (60) | Divides two numbers
175 `%` | 3 | 17 % 12 (5) | Remainder after division
176 `+` | 4 | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
177 `-` | 4 | 3 - 1 (2) | Subtracts two numbers
178 `<<` | 5 | 4 << 8 (1024) | Left shift
179 `>>` | 5 | 1024 >> 4 (64) | Right shift
180 `<` | 6 | 3 < 5 (true) | Less than
181 `>` | 6 | 3 > 5 (false) | Greater than
182 `<=` | 6 | 3 <= 3 (true) | Less than or equal
183 `>=` | 6 | 3 >= 3 (true) | Greater than or equal
184 `in` | 7 | "foo" in [ "foo", "bar" ] (true) | Element contained in array
185 `!in` | 7 | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
186 `==` | 8 | "hello" == "hello" (true), 3 == 5 (false) | Equal to
187 `!=` | 8 | "hello" != "world" (true), 3 != 3 (false) | Not equal to
188 `&` | 9 | 7 & 3 (3) | Binary AND
189 `^` | 10 | 17 ^ 12 (29) | Bitwise XOR
190 <code>|</code> | 11 | 2 | 3 (3) | Binary OR
191 <code>||</code> | 12 | true || false (true), 0 || 7 (7)| Logical OR
192 `&&` | 13 | true && false (false), 3 && 7 (7), 0 && 7 (0) | Logical AND
193 `=` | 14 | a = 3 | Assignment
194 `=>` | 15 | x => x * x (function with arg x) | Lambda, for loop
196 ### References <a id="references"></a>
198 A reference to a value can be obtained using the `&` operator. The `*` operator can be used
199 to dereference a reference:
202 var p = &value /* p refers to value */
204 log(value) // Prints "Hi!" because the variable was changed
206 ### Namespaces <a id="namespaces"></a>
208 Namespaces can be used to organize variables and functions. They are used to avoid name conflicts. The `namespace`
209 keyword is used to create a new namespace:
212 function calculate() {
217 The namespace is made available as a global variable which has the namespace's name (e.g. `Utils`):
221 The `using` keyword can be used to make all attributes in a namespace available to a script without having to
222 explicitly specify the namespace's name for each access:
227 The `using` keyword only has an effect for the current file and only for code that follows the keyword:
229 calculate() // This will not work.
232 The following namespaces are automatically imported as if by using the `using` keyword:
235 * System.Configuration
239 ### Function Calls <a id="function-calls"></a>
241 Functions can be called using the `()` operator:
243 const MyGroups = [ "test1", "test" ]
246 check_interval = len(MyGroups) * 1m
249 A list of available functions is available in the [Library Reference](18-library-reference.md#library-reference) chapter.
251 ## Assignments <a id="dictionary-operators"></a>
253 In addition to the `=` operator shown above a number of other operators
254 to manipulate attributes are supported. Here's a list of all
255 available operators (the outermost `{` `}` stand for a local variable scope):
257 ### Operator = <a id="operator-assignment"></a>
259 Sets an attribute to the specified value.
268 In this example `a` has the value `7` after both instructions are executed.
270 ### Operator += <a id="operator-additive-assignment"></a>
272 The += operator is a shortcut. The following expression:
286 ### Operator -= <a id="operator-substractive-assignment"></a>
288 The -= operator is a shortcut. The following expression:
302 ### Operator \*= <a id="operator-multiply-assignment"></a>
304 The *= operator is a shortcut. The following expression:
318 ### Operator /= <a id="operator-dividing-assignment"></a>
320 The /= operator is a shortcut. The following expression:
334 ## Indexer <a id="indexer"></a>
336 The indexer syntax provides a convenient way to set dictionary elements.
344 Example (alternative syntax):
347 hello["key"] = "world"
350 This is equivalent to writing:
358 If the `hello` attribute does not already have a value, it is automatically initialized to an empty dictionary.
360 ## Template Imports <a id="template-imports"></a>
362 Objects can import attributes from other objects.
366 template Host "default-host" {
370 template Host "test-host" {
371 import "default-host"
376 object Host "localhost" {
379 address = "127.0.0.1"
383 The `default-host` and `test-host` objects are marked as templates
384 using the `template` keyword. Unlike ordinary objects templates are not
385 instantiated at run-time. Parent objects do not necessarily have to be
386 templates, however in general they are.
388 The `vars` dictionary for the `localhost` object contains all three
389 custom attributes and the custom attribute `colour` has the value `"blue"`.
391 Parent objects are resolved in the order they're specified using the
394 Default templates which are automatically imported into all object definitions
395 can be specified using the `default` keyword:
397 template CheckCommand "plugin-check-command" default {
401 Default templates are imported before any other user-specified statement in an
402 object definition is evaluated.
404 If there are multiple default templates the order in which they are imported
407 ## Constants <a id="constants"></a>
409 Global constants can be set using the `const` keyword:
411 const VarName = "some value"
413 Once defined a constant can be accessed from any file. Constants cannot be changed
418 > Best practice is to manage constants in the [constants.conf](04-configuring-icinga-2.md#constants-conf) file.
420 ### Icinga 2 Specific Constants <a id="icinga-constants"></a>
422 Icinga 2 provides a number of special global constants. These include directory paths, global configuration
423 and runtime parameters for the application version and (build) platform.
427 Constant | Description
428 --------------------|-------------------
429 ConfigDir |**Read-only.** Main configuration directory. Usually set to `/etc/icinga2`.
430 DataDir |**Read-only.** Runtime data for the Icinga daemon. Usually set to `/var/lib/icinga2`.
431 LogDir |**Read-only.** Logfiles from the daemon. Usually set to `/var/log/icinga2`.
432 CacheDir |**Read-only.** Cached status information of the daemon. Usually set to `/var/cache/icinga2`.
433 SpoolDir |**Read-only.** Spool directory for certain data outputs. Usually set to `/var/spool/icinga2`.
434 InitRunDir |**Read-only.** Directory for PID files and sockets in daemon mode. Usually set to `/run/icinga2`.
435 ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to `ConfigDir + "/zones.d"`.
437 Global configuration:
439 Constant | Description
440 --------------------|-------------------
441 Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
442 NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
443 ReloadTimeout |**Read-write.** Defines the reload timeout for child processes. Defaults to `300s`.
444 Environment |**Read-write.** The name of the Icinga environment. Included in the SNI host name for outbound connections. Not set by default.
445 RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Set in the Icinga 2 sysconfig.
446 RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Set in the Icinga 2 sysconfig.
447 MaxConcurrentChecks |**Read-write.** The number of max checks run simultaneously. Defaults to `512`.
448 ApiBindHost |**Read-write.** Overrides the default value for the ApiListener `bind_host` attribute. Not set by default.
449 ApiBindPort |**Read-write.** Overrides the default value for the ApiListener `bind_port` attribute. Not set by default.
451 Application runtime details:
453 Constant | Description
454 --------------------|-------------------
455 PlatformName |**Read-only.** The name of the operating system, e.g. `Ubuntu`.
456 PlatformVersion |**Read-only.** The version of the operating system, e.g. `14.04.3 LTS`.
457 PlatformKernel |**Read-only.** The name of the operating system kernel, e.g. `Linux`.
458 PlatformKernelVersion|**Read-only.** The version of the operating system kernel, e.g. `3.13.0-63-generic`.
459 BuildCompilerName |**Read-only.** The name of the compiler Icinga was built with, e.g. `Clang`.
460 BuildCompilerVersion|**Read-only.** The version of the compiler Icinga was built with, e.g. `7.3.0.7030031`.
461 BuildHostName |**Read-only.** The name of the host Icinga was built on, e.g. `acheron`.
462 ApplicationVersion |**Read-only.** The application version, e.g. `2.9.0`.
464 Writable constants can be specified on the CLI using the `--define/-D` parameter.
466 > **Note for v2.10+**
468 > Default paths which include `/etc` and `/var` as base directory continue to work
469 > based on the `SysconfDir` and `LocalStateDir` constants respectively.
471 In addition to that, the constants below are used to define specific file paths. You should never need
472 to change them, as they are pre-compiled based on the constants above.
474 Variable |Description
475 --------------------|-------------------
476 StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to `DataDir + "/icinga2.state"`.
477 ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to `CacheDir + "/icinga2.debug"`.
478 PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to `InitRunDir + "/icinga2.pid"`.
479 PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to `PrefixDir + "/share/icinga2"`.
481 The constants below have been used until Icinga v2.10, and are still intact. You don't need them
482 for future builds and configuration based on the newly available constants above.
484 Variable |Description
485 --------------------|-------------------
486 PrefixDir |**Read-only.** Contains the installation prefix that was specified with `cmake -DCMAKE_INSTALL_PREFIX`. `Defaults to "/usr/local"`.
487 SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to `PrefixDir + "/etc"`.
488 LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to `PrefixDir + "/var"`.
489 RunDir |**Read-only.** Contains the path of the run directory. Defaults to `LocalStateDir + "/run"`.
491 Advanced runtime constants. Please only use them if advised by support or developers.
493 Variable | Description
494 ---------------------------|-------------------
495 EventEngine |**Read-write.** The name of the socket event engine, can be `poll` or `epoll`. The epoll interface is only supported on Linux.
496 AttachDebugger |**Read-write.** Whether to attach a debugger when Icinga 2 crashes. Defaults to `false`.
497 ICINGA2\_RLIMIT\_FILES |**Read-write.** Defines the resource limit for RLIMIT_NOFILE that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
498 ICINGA2\_RLIMIT\_PROCESSES |**Read-write.** Defines the resource limit for RLIMIT_NPROC that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
499 ICINGA2\_RLIMIT\_STACK |**Read-write.** Defines the resource limit for RLIMIT_STACK that should be set at start-up. Value cannot be set lower than the default `256 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
501 ## Apply <a id="apply"></a>
503 The `apply` keyword can be used to create new objects which are associated with
504 another group of objects.
506 apply Service "ping" to Host {
507 import "generic-service"
509 check_command = "ping4"
511 assign where host.name == "localhost"
514 In this example the `assign where` condition is a boolean expression which is
515 evaluated for all objects of type `Host` and a new service with name "ping"
516 is created for each matching host. [Expression operators](17-language-reference.md#expression-operators)
517 may be used in `assign where` conditions.
519 The `to` keyword and the target type may be omitted if there is only one target
520 type, e.g. for the `Service` type.
522 Depending on the object type used in the `apply` expression additional local
523 variables may be available for use in the `where` condition:
525 Source Type | Target Type | Variables
526 ------------------|-------------|--------------
527 Service | Host | host
528 Dependency | Host | host
529 Dependency | Service | host, service
530 Notification | Host | host
531 Notification | Service | host, service
532 ScheduledDowntime | Host | host
533 ScheduledDowntime | Service | host, service
535 Any valid config attribute can be accessed using the `host` and `service`
536 variables. For example, `host.address` would return the value of the host's
537 "address" attribute -- or null if that attribute isn't set.
539 More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-expressions)
542 ## Apply For <a id="apply-for"></a>
544 [Apply](17-language-reference.md#apply) rules can be extended with the
545 [for loop](17-language-reference.md#for-loops) keyword.
547 apply Service "prefix-" for (key => value in host.vars.dictionary) to Host {
548 import "generic-service"
550 check_command = "ping4"
551 vars.host_value = value
555 Any valid config attribute can be accessed using the `host` and `service`
556 variables. The attribute must be of the Array or Dictionary type. In this example
557 `host.vars.dictionary` is of the Dictionary type which needs a key-value-pair
560 In this example all generated service object names consist of `prefix-` and
561 the value of the `key` iterator. The prefix string can be omitted if not required.
563 The `key` and `value` variables can be used for object attribute assignment, e.g. for
564 setting the `check_command` attribute or custom attributes as command parameters.
566 `apply for` rules are first evaluated against all objects matching the `for loop` list
567 and afterwards the `assign where` and `ignore where` conditions are evaluated.
569 It is not necessary to check attributes referenced in the `for loop` expression
570 for their existance using an additional `assign where` condition.
572 More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-for)
575 ## Group Assign <a id="group-assign"></a>
577 Group objects can be assigned to specific member objects using the `assign where`
578 and `ignore where` conditions.
580 object HostGroup "linux-servers" {
581 display_name = "Linux Servers"
583 assign where host.vars.os == "Linux"
586 In this example the `assign where` condition is a boolean expression which is evaluated
587 for all objects of the type `Host`. Each matching host is added as member to the host group
588 with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
589 condition. [Expression operators](17-language-reference.md#expression-operators) may be used in `assign where` and
590 `ignore where` conditions.
592 Source Type | Variables
593 ------------------|--------------
595 ServiceGroup | host, service
599 ## Boolean Values <a id="boolean-values"></a>
601 The `assign where`, `ignore where`, `if` and `while` statements, the `!` operator as
602 well as the `bool()` function convert their arguments to a boolean value based on the
605 Description | Example Value | Boolean Value
606 ---------------------|-------------------|--------------
607 Empty value | null | false
609 Non-zero integer | -23945 | true
610 Empty string | "" | false
611 Non-empty string | "Hello" | true
612 Empty array | [] | false
613 Non-empty array | [ "Hello" ] | true
614 Empty dictionary | {} | false
615 Non-empty dictionary | { key = "value" } | true
617 For a list of supported expression operators for `assign where` and `ignore where`
618 statements, see [expression operators](17-language-reference.md#expression-operators).
620 ## Comments <a id="comments"></a>
622 The Icinga 2 configuration format supports C/C++-style and shell-style comments.
629 object Host "localhost" {
630 check_interval = 30 // this is also a comment.
631 retry_interval = 15 # yet another comment
634 ## Includes <a id="includes"></a>
636 Other configuration files can be included using the `include` directive.
637 Paths must be relative to the configuration file that contains the
642 include "some/other/file.conf"
643 include "conf.d/*.conf"
645 Wildcard includes are not recursive.
647 Icinga also supports include search paths similar to how they work in a
652 Note the use of angle brackets instead of double quotes. This causes the
653 config compiler to search the include search paths for the specified
654 file. By default $PREFIX/share/icinga2/include is included in the list of search
655 paths. Additional include search paths can be added using
656 [command-line options](11-cli-commands.md#config-include-path).
658 Wildcards are not permitted when using angle brackets.
660 ## Recursive Includes <a id="recursive-includes"></a>
662 The `include_recursive` directive can be used to recursively include all
663 files in a directory which match a certain pattern.
667 include_recursive "conf.d", "*.conf"
668 include_recursive "templates"
670 The first parameter specifies the directory from which files should be
671 recursively included.
673 The file names need to match the pattern given in the second parameter.
674 When no pattern is specified the default pattern "*.conf" is used.
676 ## Zone Includes <a id="zone-includes"></a>
678 The `include_zones` recursively includes all subdirectories for the
681 In addition to that it sets the `zone` attribute for all objects created
682 in these subdirectories to the name of the subdirectory.
686 include_zones "etc", "zones.d", "*.conf"
687 include_zones "puppet", "puppet-zones"
689 The first parameter specifies a tag name for this directive. Each `include_zones`
690 invocation should use a unique tag name. When copying the zones' configuration
691 files Icinga uses the tag name as the name for the destination directory in
692 `/var/lib/icinga2/api/config`.
694 The second parameter specifies the directory which contains the subdirectories.
696 The file names need to match the pattern given in the third parameter.
697 When no pattern is specified the default pattern "*.conf" is used.
699 ## Library directive <a id="library"></a>
701 The `library` directive was used to manually load additional
702 libraries. Starting with version 2.9 it is no longer necessary to explicitly load
703 libraries and this directive has no effect.
705 ## Functions <a id="functions"></a>
707 Functions can be defined using the `function` keyword.
711 function multiply(a, b) {
715 When encountering the `return` keyword further execution of the function is terminated and
716 the specified value is supplied to the caller of the function:
720 In this example the `multiply` function we declared earlier is invoked with two arguments (3 and 5).
721 The function computes the product of those arguments and makes the result available to the
724 When no value is supplied for the `return` statement the function returns `null`.
726 Functions which do not have a `return` statement have their return value set to the value of the
727 last expression which was performed by the function. For example, we could have also written our
728 `multiply` function like this:
730 function multiply(a, b) {
734 Anonymous functions can be created by omitting the name in the function definition. The
735 resulting function object can be used like any other value:
737 var fn = function() { 3 }
741 ## Lambda Expressions <a id="lambdas"></a>
743 Functions can also be declared using the alternative lambda syntax.
749 Multiple statements can be used by putting the function body into braces:
756 Just like with ordinary functions the return value is the value of the last statement.
758 For lambdas which take exactly one argument the braces around the arguments can be omitted:
762 ## Abbreviated Lambda Syntax <a id="nullary-lambdas"></a>
764 Lambdas which take no arguments can also be written using the abbreviated lambda syntax.
770 This creates a new function which returns the value 3.
772 ## Variable Scopes <a id="variable-scopes"></a>
774 When setting a variable Icinga checks the following scopes in this order whether the variable
775 already exists there:
781 The local scope contains variables which only exist during the invocation of the current function,
782 object or apply statement. Local variables can be declared using the `var` keyword:
784 function multiply(a, b) {
789 Each time the `multiply` function is invoked a new `temp` variable is used which is in no way
790 related to previous invocations of the function.
792 When setting a variable which has not previously been declared as local using the `var` keyword
793 the `this` scope is used.
795 The `this` scope refers to the current object which the function or object/apply statement
798 object Host "localhost" {
802 In this example the `this` scope refers to the "localhost" object. The `check_interval` attribute
803 is set for this particular host.
805 You can explicitly access the `this` scope using the `this` keyword:
807 object Host "localhost" {
808 var check_interval = 5m
810 /* This explicitly specifies that the attribute should be set
811 * for the host, if we had omitted `this.` the (poorly named)
812 * local variable `check_interval` would have been modified instead.
814 this.check_interval = 1m
817 Similarly the keywords `locals` and `globals` are available to access the local and global scope.
819 Functions also have a `this` scope. However unlike for object/apply statements the `this` scope for
820 a function is set to whichever object was used to invoke the function. Here's an example:
825 function init(word) {
830 /* Let's invoke the init() function */
833 We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
834 scope for this function call.
836 ## Closures <a id="closures"></a>
838 By default `function`s, `object`s and `apply` rules do not have access to variables declared
839 outside of their scope (except for global variables).
841 In order to access variables which are defined in the outer scope the `use` keyword can be used:
843 function MakeHelloFunction(name) {
844 return function() use(name) {
845 log("Hello, " + name)
849 In this case a new variable `name` is created inside the inner function's scope which has the
850 value of the `name` function argument.
852 Alternatively a different value for the inner variable can be specified:
854 function MakeHelloFunction(name) {
855 return function() use (greeting = "Hello, " + name) {
860 ## Conditional Statements <a id="conditional-statements"></a>
862 Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
863 construct can be used to accomplish this.
877 An if/else construct can also be used in place of any other value. The value of an if/else statement
878 is the value of the last statement which was evaluated for the branch which was taken:
881 log("Taking the 'true' branch")
884 log("Taking the 'false' branch")
888 This example prints the log message "Taking the 'true' branch" and the `a` variable is set to 21 (7 * 3).
890 The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
892 ## While Loops <a id="while-loops"></a>
894 The `while` statement checks a condition and executes the loop body when the condition evaluates to `true`.
895 This is repeated until the condition is no longer true.
906 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
907 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
908 breaks out of the loop.
910 ## For Loops <a id="for-loops"></a>
912 The `for` statement can be used to iterate over arrays and dictionaries.
916 var list = [ "a", "b", "c" ]
918 for (var item in list) {
922 The loop body is evaluated once for each item in the array. The variable `item` is declared as a local
923 variable just as if the `var` keyword had been used.
925 Iterating over dictionaries can be accomplished in a similar manner:
927 var dict = { a = 3, b = 7 }
929 for (var key => var value in dict) {
930 log("Key: " + key + ", Value: " + value)
933 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
934 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
935 breaks out of the loop.
937 The `var` keyword is optional when declaring variables in the loop's header. Variables declared without the `var`
938 keyword are nonetheless local to the function.
940 ## Constructors <a id="constructor"></a>
942 In order to create a new value of a specific type constructor calls may be used.
946 var pd = PerfdataValue()
950 You can also try to convert an existing value to another type by specifying it as an argument for the constructor call.
954 var s = String(3) /* Sets s to "3". */
956 ## Throwing Exceptions <a id="throw"></a>
958 Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions
959 using the `throw` keyword.
963 throw "An error occurred."
965 ## Handling Exceptions <a id="try-except"></a>
967 Exceptions can be handled using the `try` and `except` keywords. When an exception occurs while executing code in the
968 `try` clause no further statements in the `try` clause are evaluated and the `except` clause is executed instead.
975 log("This statement won't get executed.")
977 log("An error occurred in the try clause.")
980 ## Breakpoints <a id="breakpoints"></a>
982 The `debugger` keyword can be used to insert a breakpoint. It may be used at any place where an assignment would also be a valid expression.
984 By default breakpoints have no effect unless Icinga is started with the `--script-debugger` command-line option. When the script debugger is enabled Icinga stops execution of the script when it encounters a breakpoint and spawns a console which lets the user inspect the current state of the execution environment.
986 ## Types <a id="types"></a>
988 All values have a static type. The `typeof` function can be used to determine the type of a value:
990 typeof(3) /* Returns an object which represents the type for numbers */
992 The following built-in types are available:
994 Type | Examples | Description
995 -----------|-------------------|------------------------
996 Number | 3.7 | A numerical value.
997 Boolean | true, false | A boolean value.
998 String | "hello" | A string.
999 Array | [ "a", "b" ] | An array.
1000 Dictionary | { a = 3 } | A dictionary.
1002 Depending on which libraries are loaded additional types may become available. The `icinga`
1003 library implements a whole bunch of other [object types](09-object-types.md#object-types),
1004 e.g. Host, Service, CheckCommand, etc.
1006 Each type has an associated type object which describes the type's semantics. These
1007 type objects are made available using global variables which match the type's name:
1009 /* This logs 'true' */
1010 log(typeof(3) == Number)
1012 The type object's `prototype` property can be used to find out which methods a certain type
1015 /* This returns: ["contains","find","len","lower","replace","reverse","split","substr","to_string","trim","upper"] */
1016 keys(String.prototype)
1018 Additional documentation on type methods is available in the
1019 [library reference](18-library-reference.md#library-reference).
1021 ## Location Information <a id="location-information"></a>
1023 The location of the currently executing script can be obtained using the
1024 `current_filename` and `current_line` keywords.
1028 log("Hello from '" + current_filename + "' in line " + current_line)
1030 ## Reserved Keywords <a id="reserved-keywords"></a>
1032 These keywords are reserved and must not be used as constants or custom attributes.
1074 You can escape reserved keywords using the `@` character. The following example
1075 tries to set `vars.include` which references a reserved keyword and generates
1078 [2014-09-15 17:24:00 +0200] critical/config: Location:
1079 /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
1080 /etc/icinga2/conf.d/hosts/localhost.conf(14):
1081 /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
1083 /etc/icinga2/conf.d/hosts/localhost.conf(16): }
1084 /etc/icinga2/conf.d/hosts/localhost.conf(17):
1086 Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
1087 [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
1089 You can escape the `include` keyword by prefixing it with an additional `@` character:
1091 object Host "localhost" {
1092 import "generic-host"
1094 address = "127.0.0.1"
1100 vars.@include = "some cmdb export field"