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:
9 object Host "host1.example.org" {
10 display_name = "host1"
12 address = "192.168.0.1"
13 address6 = "2001:db8:1234::42"
17 In general you need to write each statement on a new line. Expressions started
18 with `{`, `(` and `[` extend until the matching closing character and can be broken
19 up into multiple lines.
21 Alternatively you can write multiple statements on a single line by separating
22 them with a semicolon:
25 object Host "host1.example.org" {
26 display_name = "host1"
28 address = "192.168.0.1"; address6 = "2001:db8:1234::42"
32 Each object is uniquely identified by its type (`Host`) and name
33 (`host1.example.org`). Some types have composite names, e.g. the
34 `Service` type which uses the `host_name` attribute and the name
35 you specified to generate its object name.
37 Exclamation marks (!) are not permitted in object names.
39 Objects can contain a comma-separated list of property
40 declarations. Instead of commas semicolons may also be used.
41 The following data types are available for property values:
43 All objects have at least the following attributes:
45 Attribute | Description
46 ---------------------|-----------------------------
47 name | The name of the object. This attribute can be modified in the object definition to override the name specified with the `object` directive.
48 type | The type of the object.
50 ## Expressions <a id="expressions"></a>
52 The following expressions can be used on the right-hand side of assignments.
54 ### Numeric Literals <a id="numeric-literals"></a>
56 A floating-point number.
64 ### Duration Literals <a id="duration-literals"></a>
66 Similar to floating-point numbers except for the fact that they support
67 suffixes to help with specifying time durations.
75 Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
76 h (hours) and d (days).
78 Duration literals are converted to seconds by the config parser and
79 are treated like numeric literals.
81 ### String Literals <a id="string-literals"></a>
91 #### String Literals Escape Sequences <a id="string-literals-escape-sequences"></a>
93 Certain characters need to be escaped. The following escape sequences
96 Character | Escape sequence
97 --------------------------|------------------------------------
101 <CARRIAGE-RETURN> | \\r
102 <LINE-FEED> | \\n
104 <FORM-FEED> | \\f
106 In addition to these pre-defined escape sequences you can specify
107 arbitrary ASCII characters using the backslash character (\\) followed
108 by an ASCII character in octal encoding.
110 ### Multi-line String Literals <a id="multiline-string-literals"></a>
112 Strings spanning multiple lines can be specified by enclosing them in
124 Unlike in ordinary strings special characters do not have to be escaped
125 in multi-line string literals.
127 ### Boolean Literals <a id="boolean-literals"></a>
129 The keywords `true` and `false` are used to denote truth values.
131 ### Null Value <a id="null-value"></a>
133 The `null` keyword can be used to specify an empty value.
135 ### Dictionary <a id="dictionary"></a>
137 An unordered list of key-value pairs. Keys must be unique and are
138 compared in a case-sensitive manner.
140 Individual key-value pairs must either be comma-separated or on separate lines.
141 The comma after the last key-value pair is optional.
147 address = "192.168.0.1"
152 Identifiers may not contain certain characters (e.g. space) or start
153 with certain characters (e.g. digits). If you want to use a dictionary
154 key that is not a valid identifier, you can enclose the key in double
157 ### Array <a id="array"></a>
159 An ordered list of values.
161 Individual array elements must be comma-separated.
162 The comma after the last element is optional.
170 An array may simultaneously contain values of different types, such as
173 ### Operators <a id="expression-operators"></a>
175 The following operators are supported in expressions. The operators are sorted by descending precedence.
177 Operator | Precedence | Examples (Result) | Description
178 ---------|------------|-----------------------------------------------|--------------------------------
179 `()` | 1 | (3 + 3) * 5 | Groups sub-expressions
180 `()` | 1 | Math.random() | Calls a function
181 `[]` | 1 | a[3] | Array subscript
182 `.` | 1 | a.b | Element access
183 `!` | 2 | !"Hello" (false), !false (true) | Logical negation of the operand
184 `~` | 2 | ~true (false) | Bitwise negation of the operand
185 `+` | 2 | +3 | Unary plus
186 `-` | 2 | -3 | Unary minus
187 `&` | 2 | &var (reference to 'var') | Reference operator
188 `*` | 2 | *var | Indirection operator
189 `*` | 3 | 5m * 10 (3000) | Multiplies two numbers
190 `/` | 3 | 5m / 5 (60) | Divides two numbers
191 `%` | 3 | 17 % 12 (5) | Remainder after division
192 `+` | 4 | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
193 `-` | 4 | 3 - 1 (2) | Subtracts two numbers
194 `<<` | 5 | 4 << 8 (1024) | Left shift
195 `>>` | 5 | 1024 >> 4 (64) | Right shift
196 `<` | 6 | 3 < 5 (true) | Less than
197 `>` | 6 | 3 > 5 (false) | Greater than
198 `<=` | 6 | 3 <= 3 (true) | Less than or equal
199 `>=` | 6 | 3 >= 3 (true) | Greater than or equal
200 `in` | 7 | "foo" in [ "foo", "bar" ] (true) | Element contained in array
201 `!in` | 7 | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
202 `==` | 8 | "hello" == "hello" (true), 3 == 5 (false) | Equal to
203 `!=` | 8 | "hello" != "world" (true), 3 != 3 (false) | Not equal to
204 `&` | 9 | 7 & 3 (3) | Binary AND
205 `^` | 10 | 17 ^ 12 (29) | Bitwise XOR
206 <code>|</code> | 11 | 2 | 3 (3) | Binary OR
207 <code>||</code> | 12 | true || false (true), 0 || 7 (7)| Logical OR
208 `&&` | 13 | true && false (false), 3 && 7 (7), 0 && 7 (0) | Logical AND
209 `=` | 14 | a = 3 | Assignment
210 `=>` | 15 | x => x * x (function with arg x) | Lambda, for loop
212 ### References <a id="references"></a>
214 A reference to a value can be obtained using the `&` operator. The `*` operator can be used
215 to dereference a reference:
219 var p = &value /* p refers to value */
221 log(value) // Prints "Hi!" because the variable was changed
224 ### Namespaces <a id="namespaces"></a>
226 Namespaces can be used to organize variables and functions. They are used to avoid name conflicts. The `namespace`
227 keyword is used to create a new namespace:
231 function calculate() {
237 The namespace is made available as a global variable which has the namespace's name (e.g. `Utils`):
243 The `using` keyword can be used to make all attributes in a namespace available to a script without having to
244 explicitly specify the namespace's name for each access:
251 The `using` keyword only has an effect for the current file and only for code that follows the keyword:
254 calculate() // This will not work.
258 The following namespaces are automatically imported as if by using the `using` keyword:
261 * System.Configuration
265 ### Function Calls <a id="function-calls"></a>
267 Functions can be called using the `()` operator:
270 const MyGroups = [ "test1", "test" ]
273 check_interval = len(MyGroups) * 1m
277 A list of available functions is available in the [Library Reference](18-library-reference.md#library-reference) chapter.
279 ## Assignments <a id="dictionary-operators"></a>
281 In addition to the `=` operator shown above a number of other operators
282 to manipulate attributes are supported. Here's a list of all
283 available operators (the outermost `{` `}` stand for a local variable scope):
285 ### Operator = <a id="operator-assignment"></a>
287 Sets an attribute to the specified value.
298 In this example `a` has the value `7` after both instructions are executed.
300 ### Operator += <a id="operator-additive-assignment"></a>
302 The += operator is a shortcut. The following expression:
320 ### Operator -= <a id="operator-substractive-assignment"></a>
322 The -= operator is a shortcut. The following expression:
340 ### Operator \*= <a id="operator-multiply-assignment"></a>
342 The *= operator is a shortcut. The following expression:
360 ### Operator /= <a id="operator-dividing-assignment"></a>
362 The /= operator is a shortcut. The following expression:
380 ## Indexer <a id="indexer"></a>
382 The indexer syntax provides a convenient way to set dictionary elements.
392 Example (alternative syntax):
396 hello["key"] = "world"
400 This is equivalent to writing:
410 If the `hello` attribute does not already have a value, it is automatically initialized to an empty dictionary.
412 ## Template Imports <a id="template-imports"></a>
414 Objects can import attributes from other objects.
419 template Host "default-host" {
423 template Host "test-host" {
424 import "default-host"
429 object Host "localhost" {
432 address = "127.0.0.1"
437 The `default-host` and `test-host` objects are marked as templates
438 using the `template` keyword. Unlike ordinary objects templates are not
439 instantiated at run-time. Parent objects do not necessarily have to be
440 templates, however in general they are.
442 The `vars` dictionary for the `localhost` object contains all three
443 custom variables and the custom variable `colour` has the value `"blue"`.
445 Parent objects are resolved in the order they're specified using the
448 Default templates which are automatically imported into all object definitions
449 can be specified using the `default` keyword:
452 template CheckCommand "plugin-check-command" default {
457 Default templates are imported before any other user-specified statement in an
458 object definition is evaluated.
460 If there are multiple default templates the order in which they are imported
463 ## Constants <a id="constants"></a>
465 Global constants can be set using the `const` keyword:
468 const VarName = "some value"
471 Once defined a constant can be accessed from any file. Constants cannot be changed
476 > Best practice is to manage constants in the [constants.conf](04-configuration.md#constants-conf) file.
478 ### Icinga 2 Specific Constants <a id="icinga-constants"></a>
480 Icinga 2 provides a number of special global constants. These include directory paths, global configuration
481 and runtime parameters for the application version and (build) platform.
483 #### Directory Path Constants <a id="icinga-constants-director-path"></a>
485 Constant | Description
486 --------------------|-------------------
487 ConfigDir |**Read-only.** Main configuration directory. Usually set to `/etc/icinga2`.
488 DataDir |**Read-only.** Runtime data for the Icinga daemon. Usually set to `/var/lib/icinga2`.
489 LogDir |**Read-only.** Logfiles from the daemon. Usually set to `/var/log/icinga2`.
490 CacheDir |**Read-only.** Cached status information of the daemon. Usually set to `/var/cache/icinga2`.
491 SpoolDir |**Read-only.** Spool directory for certain data outputs. Usually set to `/var/spool/icinga2`.
492 InitRunDir |**Read-only.** Directory for PID files and sockets in daemon mode. Usually set to `/run/icinga2`.
493 ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to `ConfigDir + "/zones.d"`.
495 #### Global Configuration Constants <a id="icinga-constants-global-config"></a>
497 Constant | Description
498 --------------------|-------------------
499 Vars |**Read-write.** Contains a dictionary with global custom variables. Not set by default.
500 NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
501 ReloadTimeout |**Read-write.** Defines the reload timeout for child processes. Defaults to `300s`.
502 Environment |**Read-write.** The name of the Icinga environment. Included in the SNI host name for outbound connections. Not set by default.
503 RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Set in the Icinga 2 sysconfig.
504 RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Set in the Icinga 2 sysconfig.
505 MaxConcurrentChecks |**Read-write.** The number of max checks run simultaneously. Defaults to `512`.
506 ApiBindHost |**Read-write.** Overrides the default value for the ApiListener `bind_host` attribute. Not set by default.
507 ApiBindPort |**Read-write.** Overrides the default value for the ApiListener `bind_port` attribute. Not set by default.
509 #### Application Runtime Constants <a id="icinga-constants-application-runtime"></a>
511 Constant | Description
512 --------------------|-------------------
513 PlatformName |**Read-only.** The name of the operating system, e.g. `Ubuntu`.
514 PlatformVersion |**Read-only.** The version of the operating system, e.g. `14.04.3 LTS`.
515 PlatformKernel |**Read-only.** The name of the operating system kernel, e.g. `Linux`.
516 PlatformKernelVersion|**Read-only.** The version of the operating system kernel, e.g. `3.13.0-63-generic`.
517 BuildCompilerName |**Read-only.** The name of the compiler Icinga was built with, e.g. `Clang`.
518 BuildCompilerVersion|**Read-only.** The version of the compiler Icinga was built with, e.g. `7.3.0.7030031`.
519 BuildHostName |**Read-only.** The name of the host Icinga was built on, e.g. `acheron`.
520 ApplicationVersion |**Read-only.** The application version, e.g. `2.9.0`.
522 #### Additional Constants <a id="icinga-constants-additional"></a>
524 Writable constants can be specified on the CLI using the `--define/-D` parameter.
526 > **Note for v2.10+**
528 > Default paths which include `/etc` and `/var` as base directory continue to work
529 > based on the `SysconfDir` and `LocalStateDir` constants respectively.
531 In addition to that, the constants below are used to define specific file paths. You should never need
532 to change them, as they are pre-compiled based on the constants above.
534 Variable |Description
535 --------------------|-------------------
536 StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to `DataDir + "/icinga2.state"`.
537 ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to `CacheDir + "/icinga2.debug"`.
538 PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to `InitRunDir + "/icinga2.pid"`.
539 PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to `PrefixDir + "/share/icinga2"`.
541 The constants below have been used until Icinga v2.10, and are still intact. You don't need them
542 for future builds and configuration based on the newly available constants above.
544 Variable |Description
545 --------------------|-------------------
546 PrefixDir |**Read-only.** Contains the installation prefix that was specified with `cmake -DCMAKE_INSTALL_PREFIX`. `Defaults to "/usr/local"`.
547 SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to `PrefixDir + "/etc"`.
548 LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to `PrefixDir + "/var"`.
549 RunDir |**Read-only.** Contains the path of the run directory. Defaults to `LocalStateDir + "/run"`.
551 #### Advanced Constants and Variables <a id="icinga-constants-advanced"></a>
553 Advanced runtime constants. Please only use them if advised by support or developers.
555 Variable | Description
556 ---------------------------|-------------------
557 EventEngine |**Read-write.** The name of the socket event engine, can be `poll` or `epoll`. The epoll interface is only supported on Linux.
558 AttachDebugger |**Read-write.** Whether to attach a debugger when Icinga 2 crashes. Defaults to `false`.
560 Advanced sysconfig environment variables, defined in `/etc/sysconfig/icinga2` (RHEL/SLES) or `/etc/default/icinga2` (Debian/Ubuntu).
562 Variable | Description
563 ---------------------------|-------------------
564 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.
565 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.
566 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.
569 ## Apply <a id="apply"></a>
571 The `apply` keyword can be used to create new objects which are associated with
572 another group of objects.
575 apply Service "ping" to Host {
576 import "generic-service"
578 check_command = "ping4"
580 assign where host.name == "localhost"
584 In this example the `assign where` condition is a boolean expression which is
585 evaluated for all objects of type `Host` and a new service with name "ping"
586 is created for each matching host. [Expression operators](17-language-reference.md#expression-operators)
587 may be used in `assign where` conditions.
589 The `to` keyword and the target type may be omitted if there is only one target
590 type, e.g. for the `Service` type.
592 Depending on the object type used in the `apply` expression additional local
593 variables may be available for use in the `where` condition:
595 Source Type | Target Type | Variables
596 ------------------|-------------|--------------
597 Service | Host | host
598 Dependency | Host | host
599 Dependency | Service | host, service
600 Notification | Host | host
601 Notification | Service | host, service
602 ScheduledDowntime | Host | host
603 ScheduledDowntime | Service | host, service
605 Any valid config attribute can be accessed using the `host` and `service`
606 variables. For example, `host.address` would return the value of the host's
607 "address" attribute -- or null if that attribute isn't set.
609 More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-expressions)
612 ## Apply For <a id="apply-for"></a>
614 [Apply](17-language-reference.md#apply) rules can be extended with the
615 [for loop](17-language-reference.md#for-loops) keyword.
618 apply Service "prefix-" for (key => value in host.vars.dictionary) to Host {
619 import "generic-service"
621 check_command = "ping4"
622 vars.host_value = value
626 Any valid config attribute can be accessed using the `host` and `service`
627 variables. The attribute must be of the Array or Dictionary type. In this example
628 `host.vars.dictionary` is of the Dictionary type which needs a key-value-pair
631 In this example all generated service object names consist of `prefix-` and
632 the value of the `key` iterator. The prefix string can be omitted if not required.
634 The `key` and `value` variables can be used for object attribute assignment, e.g. for
635 setting the `check_command` attribute or custom variables as command parameters.
637 `apply for` rules are first evaluated against all objects matching the `for loop` list
638 and afterwards the `assign where` and `ignore where` conditions are evaluated.
640 It is not necessary to check attributes referenced in the `for loop` expression
641 for their existance using an additional `assign where` condition.
643 More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-for)
646 ## Group Assign <a id="group-assign"></a>
648 Group objects can be assigned to specific member objects using the `assign where`
649 and `ignore where` conditions.
652 object HostGroup "linux-servers" {
653 display_name = "Linux Servers"
655 assign where host.vars.os == "Linux"
659 In this example the `assign where` condition is a boolean expression which is evaluated
660 for all objects of the type `Host`. Each matching host is added as member to the host group
661 with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
662 condition. [Expression operators](17-language-reference.md#expression-operators) may be used in `assign where` and
663 `ignore where` conditions.
665 Source Type | Variables
666 ------------------|--------------
668 ServiceGroup | host, service
672 ## Boolean Values <a id="boolean-values"></a>
674 The `assign where`, `ignore where`, `if` and `while` statements, the `!` operator as
675 well as the `bool()` function convert their arguments to a boolean value based on the
678 Description | Example Value | Boolean Value
679 ---------------------|-------------------|--------------
680 Empty value | null | false
682 Non-zero integer | -23945 | true
683 Empty string | "" | false
684 Non-empty string | "Hello" | true
685 Empty array | [] | false
686 Non-empty array | [ "Hello" ] | true
687 Empty dictionary | {} | false
688 Non-empty dictionary | { key = "value" } | true
690 For a list of supported expression operators for `assign where` and `ignore where`
691 statements, see [expression operators](17-language-reference.md#expression-operators).
693 ## Comments <a id="comments"></a>
695 The Icinga 2 configuration format supports C/C++-style and shell-style comments.
703 object Host "localhost" {
704 check_interval = 30 // this is also a comment.
705 retry_interval = 15 # yet another comment
709 ## Includes <a id="includes"></a>
711 Other configuration files can be included using the `include` directive.
712 Paths must be relative to the configuration file that contains the
718 include "some/other/file.conf"
719 include "conf.d/*.conf"
722 Wildcard includes are not recursive.
724 Icinga also supports include search paths similar to how they work in a
731 Note the use of angle brackets instead of double quotes. This causes the
732 config compiler to search the include search paths for the specified
733 file. By default $PREFIX/share/icinga2/include is included in the list of search
734 paths. Additional include search paths can be added using
735 [command-line options](11-cli-commands.md#config-include-path).
737 Wildcards are not permitted when using angle brackets.
739 ## Recursive Includes <a id="recursive-includes"></a>
741 The `include_recursive` directive can be used to recursively include all
742 files in a directory which match a certain pattern.
747 include_recursive "conf.d", "*.conf"
748 include_recursive "templates"
751 The first parameter specifies the directory from which files should be
752 recursively included.
754 The file names need to match the pattern given in the second parameter.
755 When no pattern is specified the default pattern "*.conf" is used.
757 ## Zone Includes <a id="zone-includes"></a>
761 > This is an internal functionality consumed by Icinga itself.
763 > The preferred way for users managing configuration files in
764 > zones is to use the [cluster config sync](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)
765 > or [REST API config packages](12-icinga2-api.md#icinga2-api-config-management).
767 The `include_zones` recursively includes all subdirectories for the
770 In addition to that it sets the `zone` attribute for all objects created
771 in these subdirectories to the name of the subdirectory.
776 include_zones "etc", "zones.d", "*.conf"
777 include_zones "puppet", "puppet-zones"
780 The first parameter specifies a tag name for this directive. Each `include_zones`
781 invocation should use a unique tag name. When copying the zones' configuration
782 files Icinga uses the tag name as the name for the destination directory in
783 `/var/lib/icinga2/api/config`.
785 The second parameter specifies the directory which contains the subdirectories.
787 The file names need to match the pattern given in the third parameter.
788 When no pattern is specified the default pattern "*.conf" is used.
790 ## Library directive <a id="library"></a>
792 The `library` directive was used to manually load additional
793 libraries. Starting with version 2.9 it is no longer necessary to explicitly load
794 libraries and this directive has no effect.
796 ## Functions <a id="functions"></a>
798 Functions can be defined using the `function` keyword.
803 function multiply(a, b) {
808 When encountering the `return` keyword further execution of the function is terminated and
809 the specified value is supplied to the caller of the function:
815 In this example the `multiply` function we declared earlier is invoked with two arguments (3 and 5).
816 The function computes the product of those arguments and makes the result available to the
819 When no value is supplied for the `return` statement the function returns `null`.
821 Functions which do not have a `return` statement have their return value set to the value of the
822 last expression which was performed by the function. For example, we could have also written our
823 `multiply` function like this:
826 function multiply(a, b) {
831 Anonymous functions can be created by omitting the name in the function definition. The
832 resulting function object can be used like any other value:
835 var fn = function() { 3 }
840 ## Lambda Expressions <a id="lambdas"></a>
842 Functions can also be declared using the alternative lambda syntax.
850 Multiple statements can be used by putting the function body into braces:
859 Just like with ordinary functions the return value is the value of the last statement.
861 For lambdas which take exactly one argument the braces around the arguments can be omitted:
867 ## Abbreviated Lambda Syntax <a id="nullary-lambdas"></a>
869 Lambdas which take no arguments can also be written using the abbreviated lambda syntax.
877 This creates a new function which returns the value 3.
879 ## Variable Scopes <a id="variable-scopes"></a>
881 When setting a variable Icinga checks the following scopes in this order whether the variable
882 already exists there:
888 The local scope contains variables which only exist during the invocation of the current function,
889 object or apply statement. Local variables can be declared using the `var` keyword:
892 function multiply(a, b) {
898 Each time the `multiply` function is invoked a new `temp` variable is used which is in no way
899 related to previous invocations of the function.
901 When setting a variable which has not previously been declared as local using the `var` keyword
902 the `this` scope is used.
904 The `this` scope refers to the current object which the function or object/apply statement
908 object Host "localhost" {
913 In this example the `this` scope refers to the "localhost" object. The `check_interval` attribute
914 is set for this particular host.
916 You can explicitly access the `this` scope using the `this` keyword:
919 object Host "localhost" {
920 var check_interval = 5m
922 /* This explicitly specifies that the attribute should be set
923 * for the host, if we had omitted `this.` the (poorly named)
924 * local variable `check_interval` would have been modified instead.
926 this.check_interval = 1m
929 Similarly the keywords `locals` and `globals` are available to access the local and global scope.
931 Functions also have a `this` scope. However unlike for object/apply statements the `this` scope for
932 a function is set to whichever object was used to invoke the function. Here's an example:
938 function init(word) {
943 /* Let's invoke the init() function */
947 We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
948 scope for this function call.
950 ## Closures <a id="closures"></a>
952 By default `function`s, `object`s and `apply` rules do not have access to variables declared
953 outside of their scope (except for global variables).
955 In order to access variables which are defined in the outer scope the `use` keyword can be used:
958 function MakeHelloFunction(name) {
959 return function() use(name) {
960 log("Hello, " + name)
965 In this case a new variable `name` is created inside the inner function's scope which has the
966 value of the `name` function argument.
968 Alternatively a different value for the inner variable can be specified:
971 function MakeHelloFunction(name) {
972 return function() use (greeting = "Hello, " + name) {
978 ## Conditional Statements <a id="conditional-statements"></a>
980 Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
981 construct can be used to accomplish this.
997 An if/else construct can also be used in place of any other value. The value of an if/else statement
998 is the value of the last statement which was evaluated for the branch which was taken:
1002 log("Taking the 'true' branch")
1005 log("Taking the 'false' branch")
1010 This example prints the log message "Taking the 'true' branch" and the `a` variable is set to 21 (7 * 3).
1012 The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
1014 ## While Loops <a id="while-loops"></a>
1016 The `while` statement checks a condition and executes the loop body when the condition evaluates to `true`.
1017 This is repeated until the condition is no longer true.
1030 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
1031 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
1032 breaks out of the loop.
1034 ## For Loops <a id="for-loops"></a>
1036 The `for` statement can be used to iterate over arrays and dictionaries.
1041 var list = [ "a", "b", "c" ]
1043 for (var item in list) {
1044 log("Item: " + item)
1048 The loop body is evaluated once for each item in the array. The variable `item` is declared as a local
1049 variable just as if the `var` keyword had been used.
1051 Iterating over dictionaries can be accomplished in a similar manner:
1054 var dict = { a = 3, b = 7 }
1056 for (var key => var value in dict) {
1057 log("Key: " + key + ", Value: " + value)
1061 The `continue` and `break` keywords can be used to control how the loop is executed: The `continue` keyword
1062 skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
1063 breaks out of the loop.
1065 The `var` keyword is optional when declaring variables in the loop's header. Variables declared without the `var`
1066 keyword are nonetheless local to the function.
1068 ## Constructors <a id="constructor"></a>
1070 In order to create a new value of a specific type constructor calls may be used.
1075 var pd = PerfdataValue()
1080 You can also try to convert an existing value to another type by specifying it as an argument for the constructor call.
1085 var s = String(3) /* Sets s to "3". */
1088 ## Throwing Exceptions <a id="throw"></a>
1090 Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions
1091 using the `throw` keyword.
1096 throw "An error occurred."
1099 ## Handling Exceptions <a id="try-except"></a>
1101 Exceptions can be handled using the `try` and `except` keywords. When an exception occurs while executing code in the
1102 `try` clause no further statements in the `try` clause are evaluated and the `except` clause is executed instead.
1110 log("This statement won't get executed.")
1112 log("An error occurred in the try clause.")
1116 ## Breakpoints <a id="breakpoints"></a>
1118 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.
1120 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.
1122 ## Types <a id="types"></a>
1124 All values have a static type. The `typeof` function can be used to determine the type of a value:
1127 typeof(3) /* Returns an object which represents the type for numbers */
1130 The following built-in types are available:
1132 Type | Examples | Description
1133 -----------|-------------------|------------------------
1134 Number | 3.7 | A numerical value.
1135 Boolean | true, false | A boolean value.
1136 String | "hello" | A string.
1137 Array | [ "a", "b" ] | An array.
1138 Dictionary | { a = 3 } | A dictionary.
1140 Depending on which libraries are loaded additional types may become available. The `icinga`
1141 library implements a whole bunch of other [object types](09-object-types.md#object-types),
1142 e.g. Host, Service, CheckCommand, etc.
1144 Each type has an associated type object which describes the type's semantics. These
1145 type objects are made available using global variables which match the type's name:
1148 /* This logs 'true' */
1149 log(typeof(3) == Number)
1152 The type object's `prototype` property can be used to find out which methods a certain type
1156 /* This returns: ["contains","find","len","lower","replace","reverse","split","substr","to_string","trim","upper"] */
1157 keys(String.prototype)
1160 Additional documentation on type methods is available in the
1161 [library reference](18-library-reference.md#library-reference).
1163 ## Location Information <a id="location-information"></a>
1165 The location of the currently executing script can be obtained using the
1166 `current_filename` and `current_line` keywords.
1171 log("Hello from '" + current_filename + "' in line " + current_line)
1174 ## Reserved Keywords <a id="reserved-keywords"></a>
1176 These keywords are reserved and must not be used as constants or custom variables.
1219 You can escape reserved keywords using the `@` character. The following example
1220 tries to set `vars.include` which references a reserved keyword and generates
1224 [2014-09-15 17:24:00 +0200] critical/config: Location:
1225 /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
1226 /etc/icinga2/conf.d/hosts/localhost.conf(14):
1227 /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
1229 /etc/icinga2/conf.d/hosts/localhost.conf(16): }
1230 /etc/icinga2/conf.d/hosts/localhost.conf(17):
1232 Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
1233 [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
1236 You can escape the `include` keyword by prefixing it with an additional `@` character:
1239 object Host "localhost" {
1240 import "generic-host"
1242 address = "127.0.0.1"
1248 vars.@include = "some cmdb export field"