# <a id="configuring-icinga2"></a> Configuring Icinga 2
-## <a id="global-constants"></a> Global Constants
-
-Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
-
-Variable |Description
---------------------|-------------------
-PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
-SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
-ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to SysconfDir + "/zones.d".
-LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
-RunDir |**Read-only.** Contains the path of the run directory. Defaults to LocalStateDir + "/run".
-PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
-StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
-ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to LocalStateDir + "/cache/icinga2/icinga2.debug".
-PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to RunDir + "/icinga2/icinga2.pid".
-Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
-NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
-ApplicationType |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
-EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
-EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
-EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
-EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
-EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
-EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
-UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
-RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Used in [init.conf](#init-conf).
-RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Used in [init.conf](#init-conf).
-
-## <a id="reserved-keywords"></a> Reserved Keywords
-
-These keywords are reserved by the configuration parser and must not be
-used as constants or custom attributes.
-
- object
- template
- include
- include_recursive
- library
- null
- true
- false
- const
- var
- this
- use
- apply
- to
- where
- import
- assign
- ignore
- function
- return
- for
- if
- else
- in
-
-You can escape reserved keywords using the `@` character. The following example
-will try to set `vars.include` which references a reserved keyword and generates
-the following error:
-
-
- [2014-09-15 17:24:00 +0200] critical/config: Location:
- /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
- /etc/icinga2/conf.d/hosts/localhost.conf(14):
- /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
- ^^^^^^^
- /etc/icinga2/conf.d/hosts/localhost.conf(16): }
- /etc/icinga2/conf.d/hosts/localhost.conf(17):
-
- Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
- [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
-
-You can escape the `include` key with an additional `@` character becoming `vars.@include`:
-
- object Host "localhost" {
- import "generic-host"
-
- address = "127.0.0.1"
- address6 = "::1"
-
- vars.os = "Linux"
- vars.sla = "24x7"
-
- vars.@include = "some cmdb export field"
- }
-
-
## <a id="configuration-syntax"></a> Configuration Syntax
### <a id="object-definition"></a> Object Definition
### Expressions
-The following expressions can be used on the right-hand side of dictionary
-values.
+The following expressions can be used on the right-hand side of assignments.
#### <a id="numeric-literals"></a> Numeric Literals
#### <a id="boolean-literals"></a> Boolean Literals
-The keywords `true` and `false` are equivalent to 1 and 0 respectively.
+The keywords `true` and `false` are used to denote truth values.
#### <a id="null-value"></a> Null Value
#### <a id="dictionary"></a> Dictionary
An unordered list of key-value pairs. Keys must be unique and are
-compared in a case-insensitive manner.
+compared in a case-sensitive manner.
Individual key-value pairs must either be comma-separated or on separate lines.
The comma after the last key-value pair is optional.
- | 3 - 1 (2) | Subtracts two numbers
* | 5m * 10 (3000) | Multiplies two numbers
/ | 5m / 5 (60) | Divides two numbers
+% | 17 % 12 (5) | Remainder after division
+^ | 17 ^ 12 (29) | Bitwise XOR
& | 7 & 3 (3) | Binary AND
| | 2 | 3 (3) | Binary OR
&& | true && false (false) | Logical AND
assign where match("192.168.*", host.address)
+A list of available functions is available in the [Built-in functions and methods](#builtin-functions) chapter.
-Function | Description
---------------------------------|-----------------------
-regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
-match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
-len(value) | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
-union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
-intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
-keys(dict) | Returns an array containing the dictionary's keys.
-string(value) | Converts the value to a string.
-number(value) | Converts the value to a number.
-bool(value) | Converts the value to a bool.
-random() | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
-log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
-log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
-exit(integer) | Terminates the application.
-
-### <a id="dictionary-operators"></a> Dictionary Operators
+### <a id="dictionary-operators"></a> Assignments
In addition to the `=` operator shown above a number of other operators
-to manipulate dictionary elements are supported. Here's a list of all
+to manipulate attributes are supported. Here's a list of all
available operators:
#### <a id="operator-assignment"></a> Operator =
-Sets a dictionary element to the specified value.
+Sets an attribute to the specified value.
Example:
}
}
+If the `hello` attribute does not already have a value it is automatically initialized to an empty dictionary.
+
### <a id="template-imports"></a> Template Imports
Objects can import attributes from other objects.
Once defined a constant can be accessed from any file. Constants cannot be changed
once they are set.
-There is a defined set of [global constants](#global-constants) which allow
-you to specify application settings.
+Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
+
+Variable |Description
+--------------------|-------------------
+PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
+SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
+ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to SysconfDir + "/zones.d".
+LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
+RunDir |**Read-only.** Contains the path of the run directory. Defaults to LocalStateDir + "/run".
+PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
+StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
+ObjectsPath |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to LocalStateDir + "/cache/icinga2/icinga2.debug".
+PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to RunDir + "/icinga2/icinga2.pid".
+Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
+NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
+ApplicationType |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
+EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
+EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
+EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
+EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
+EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
+EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
+UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
+RunAsUser |**Read-write.** Defines the user the Icinga 2 daemon is running as. Used in [init.conf](#init-conf).
+RunAsGroup |**Read-write.** Defines the group the Icinga 2 daemon is running as. Used in [init.conf](#init-conf).
### <a id="apply"></a> Apply
Note the use of angle brackets instead of double quotes. This causes the
config compiler to search the include search paths for the specified
-file. By default $PREFIX/share/icinga2 is included in the list of search
+file. By default $PREFIX/share/icinga2/include is included in the list of search
paths. Additional include search paths can be added using
[command-line options](#cmdline).
library "snmphelper"
+### <a id="functions"></a> Functions
+
+Functions can be defined using the `function` keyword.
+
+Example:
+
+ function multiply(a, b) {
+ return a * b
+ }
+
+When encountering the `return` keyword further execution of the function is terminated and
+the specified value is supplied to the caller of the function:
+
+ log(multiply(3, 5))
+
+In this example the `add` function we declared earlier is invoked with two arguments (3 and 5).
+The function computes the product of those arguments and makes the result available to the
+function's caller.
+
+When no value is supplied for the `return` statement the function returns `null`.
+
+Functions which do not have a `return` statement have their return value set to the value of the
+last expression which was performed by the function. For example, we could have also written our
+`multiply` function like this:
+
+ function multiply(a, b) {
+ a * b
+ }
+
+### <a id="lambdas"></a> Lambda Expressions
+
+Functions can also be declared using the alternative lambda syntax.
+
+Example:
+
+ f = (x) => x * x
+
+Multiple statements can be used by putting the function body into braces:
+
+ f = (x) => {
+ log("Lambda called")
+ x * x
+ }
+
+Just like with ordinary functions the return value is the value of the last statement.
+
+For lambdas which take exactly one argument the braces around the arguments can be omitted:
+
+ f = x => x * x
+
+### <a id="variable-scopes"></a> Variable Scopes
+
+When setting a variable Icinga checks the following scopes in this order whether the variable
+already exists there:
+
+* Local Scope
+* `this` Scope
+* Global Scope
+
+The local scope contains variables which only exist during the invocation of the current function,
+object or apply statement. Local variables can be declared using the `var` keyword:
+
+ function multiple(a, b) {
+ var temp = a * b
+ return temp
+ }
+
+Each time the `multiply` function is invoked a new `temp` variable is used which is in no way
+related to previous invocations of the function.
+
+When setting a variable which has not previously been declared as local using the `var` keyword
+the `this` scope is used.
+
+The `this` scope refers to the current object which the function or object/apply statement
+operates on.
+
+ object Host "localhost" {
+ check_interval = 5m
+ }
+
+In this example the `this` scope refers to the "localhost" object. The `check_interval` attribute
+is set for this particular host.
+
+You can explicitly access the `this` scope using the `this` keyword:
+
+ object Host "localhost" {
+ var check_interval = 5m
+
+ /* This explicitly specifies that the attribute should be set
+ * for the host, if we had omitted `this.` the (poorly named)
+ * local variable `check_interval` would have been modified instead.
+ */
+ this.check_interval = 1m
+ }
+
+Similarly the keywords `locals` and `globals` are available to access the local and global scope.
+
+Functions also have a `this` scope. However unlike for object/apply statements the `this` scope for
+a function is set to whichever object was used to invoke the function. Here's an example:
+
+ hm = {
+ h_word = null
+
+ function init(word) {
+ h_word = word
+ }
+ }
+
+ /* Let's invoke the init() function */
+ hm.init("hello")
+
+We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
+scope for this function call.
+
+### <a id="conditional-statements"></a> Conditional Statements
+
+Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
+construct can be used to accomplish this.
+
+Example:
+
+ a = 3
+
+ if (a < 5) {
+ a *= 7
+ } else {
+ a *= 2
+ }
+
+An if/else construct can also be used in place of any other value. The value of an if/else statement
+is the value of the last statement which was evaluated for the branch which was taken:
+
+ a = if (true) {
+ log("Taking the 'true' branch")
+ 7 * 3
+ } else {
+ log("Taking the 'false' branch")
+ 9
+ }
+
+This example prints the log message "Taking the 'true' branch" and the `a` variable is set to 21 (7 * 3).
+
+The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
+
+## <a id="for-loops"></a> For Loops
+
+The `for` statement can be used to iterate over arrays and dictionaries.
+
+Example:
+
+ var list = [ "a", "b", "c" ]
+
+ for (item in list) {
+ log("Item: " + item)
+ }
+
+The loop body is evaluated once for each item in the array. The variable `item` is declared as a local
+variable just as if the `var` keyword had been used.
+
+Iterating over dictionaries can be accomplished in a similar manner:
+
+ var dict = { a = 3, b = 7 }
+
+ for (key => value in dict) {
+ log("Key: " + key + ", Value: " + value)
+ }
+
+## <a id="types"></a> Types
+
+All values have a static type. The `typeof` function can be used to determine the type of a value:
+
+ typeof(3) /* Returns an object which represents the type for numbers */
+
+The following built-in types are available:
+
+Type | Examples | Description
+-----------|-------------------|------------------------
+Number | 3.7 | A numerical value.
+Boolean | true, false | A boolean value.
+String | "hello" | A string.
+Array | [ "a", "b" ] | An array.
+Dictionary | { a = 3 } | A dictionary.
+
+Depending on which other libraries are loaded other types may become available. The `icinga`
+library implements a whole bunch of other types, e.g. Host, Service, CheckCommand, etc.
+
+Each type has an associated type object which describes the type's semantics. These
+type objects are made available using global variables which match the type's name:
+
+ /* This logs 'true' */
+ log(typeof(3) == Number)
+
+The type object's `prototype` property can be used to find out which methods a certain type
+supports:
+
+ /* This returns: ["find","len","lower","replace","split","substr","to_string","upper"] */
+ keys(String.prototype)
+
+## <a id="reserved-keywords"></a> Reserved Keywords
+
+These keywords are reserved and must not be used as constants or custom attributes.
+
+ object
+ template
+ include
+ include_recursive
+ library
+ null
+ true
+ false
+ const
+ var
+ this
+ use
+ apply
+ to
+ where
+ import
+ assign
+ ignore
+ function
+ return
+ for
+ if
+ else
+ in
+
+You can escape reserved keywords using the `@` character. The following example
+tries to set `vars.include` which references a reserved keyword and generates
+an error:
+
+ [2014-09-15 17:24:00 +0200] critical/config: Location:
+ /etc/icinga2/conf.d/hosts/localhost.conf(13): vars.sla = "24x7"
+ /etc/icinga2/conf.d/hosts/localhost.conf(14):
+ /etc/icinga2/conf.d/hosts/localhost.conf(15): vars.include = "some cmdb export field"
+ ^^^^^^^
+ /etc/icinga2/conf.d/hosts/localhost.conf(16): }
+ /etc/icinga2/conf.d/hosts/localhost.conf(17):
+
+ Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
+ [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
+
+You can escape the `include` keyword by prefixing it with an additional `@` character:
+
+ object Host "localhost" {
+ import "generic-host"
+
+ address = "127.0.0.1"
+ address6 = "::1"
+
+ vars.os = "Linux"
+ vars.sla = "24x7"
+
+ vars.@include = "some cmdb export field"
+ }
+
+## <a id="builtin-functions"></a> Built-in functions and methods
+
+### <a id="global-functions"></a> Global functions
+
+Function | Description
+--------------------------------|-----------------------
+regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
+match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
+len(value) | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
+union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
+intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
+keys(dict) | Returns an array containing the dictionary's keys.
+string(value) | Converts the value to a string.
+number(value) | Converts the value to a number.
+bool(value) | Converts the value to a bool.
+random() | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
+log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
+log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
+exit(integer) | Terminates the application.
+
+### <a id="number-type"></a> Number type
+
+#### <a id="number-to_string"></a> Number#to_string
+
+Signature:
+
+ function to_string();
+
+The `to_string` method returns a string representation of the number.
+
+Example:
+
+ var example = 7
+ example.to_string() /* Returns "7" */
+
+### <a id="boolean-type"></a> Boolean type
+
+#### <a id="boolean-to_string"></a> Boolean#to_string
+
+Signature:
+
+ function to_string();
+
+The `to_string` method returns a string representation of the boolean value.
+
+Example:
+
+ var example = true
+ example.to_string() /* Returns "true" */
+
+### <a id="string-type"></a> String type
+
+#### <a id="string-find"></a> String#find
+
+Signature:
+
+ function find(str, start);
+
+Returns the zero-based index at which the string `str` was found in the string. If the string
+was not found -1 is returned. `start` specifies the zero-based index at which `find` should
+start looking for the string (defaults to 0 when not specified).
+
+Example:
+
+ "Hello World".find("World") /* Returns 6 */
+
+#### <a id="string-len"></a> String#len
+
+Signature
+
+ function len();
+
+Returns the length of the string in bytes. Note that depending on the encoding type of the string
+this is not necessarily the number of characters.
+
+Example:
+
+ "Hello World".len() /* Returns 11 */
+
+#### <a id="string-lower"></a> String#lower
+
+Signature:
+
+ function lower();
+
+Returns a copy of the string with all of its characters converted to lower-case.
+
+Example:
+
+ "Hello World".lower() /* Returns "hello world" */
+
+#### <a id="string-upper"></a> String#upper
+
+Signature:
+
+ function upper();
+
+Returns a copy of the string with all of its characters converted to upper-case.
+
+Example:
+
+ "Hello World".upper() /* Returns "HELLO WORLD" */
+
+#### <a id="string-replace"></a> String#replace
+
+Signature:
+
+ function replace(search, replacement);
+
+Returns a copy of the string with all occurences of the string specified in `search` replaced
+with the string specified in `replacement`.
+
+#### <a id="string-split"></a> String#split
+
+Signature:
+
+ function split(delimiters);
+
+Splits a string into individual parts and returns them as an array. The `delimiters` argument
+specifies the characters which should be used as delimiters between parts.
+
+Example:
+
+ "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
+
+#### <a id="string-substr"></a> String#substr
+
+Signature:
+
+ function substr(start, len);
+
+Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
+The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
+
+Example:
+
+ "Hello World".substr(6) /* Returns "World" */
+
+#### <a id="string-to_string"></a> String#to_string
+
+Signature:
+
+ function to_string();
+
+Returns a copy of the string.
+
+### <a id="scriptfunction-type"> ScriptFunction type
+
+#### <a id="scriptfunction-call"> ScriptFunction#call
+
+Signature:
+
+ function call(thisArg, ...);
+
+Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
+scope for the function. All other arguments are passed directly to the function.
+
+Example:
+
+ function set_x(val) {
+ this.x = val
+ }
+
+ dict = {}
+
+ set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
+
+#### <a id="scriptfunction-callv"> ScriptFunction#callv
+
+Signature:
+
+ function call(thisArg, args);
+
+Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
+scope for the function. The items in the `args` array are passed to the function as individual arguments.
+
+Example:
+ function set_x(val) {
+ this.x = val
+ }
+
+ var dict = {}
+
+ var args = [ 7 ]
+
+ set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
## <a id="object-types"></a> Object Types
Metric prefix names can be modified using [runtime macros](#runtime-macros).
-Example with your custom [global constant](#global-constants) `GraphiteEnv`:
+Example with your custom [global constant](#constants) `GraphiteEnv`:
const GraphiteEnv = "icinga.env1"
projects / icinga2 / commitdiff