From 255490ede21f0cc6da4d745c6afc274a515be4a9 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Mon, 19 Jan 2015 15:02:47 +0100 Subject: [PATCH] Update documentation refs #8096 --- doc/2-getting-started.md | 4 +- doc/4-monitoring-basics.md | 2 +- doc/5-monitoring-remote-systems.md | 4 +- doc/7-configuring-icinga-2.md | 596 +++++++++++++++++++++++------ doc/8-migration.md | 4 +- 5 files changed, 487 insertions(+), 123 deletions(-) diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index 45f3a3296..b09e79b7c 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -356,7 +356,7 @@ directive makes sure that all of your own configuration files are included. ### init.conf This initialization configuration file is automatically included by Icinga 2. It -defines the daemon user and group [constants](#global-constants) `RunAsUser` and +defines the daemon user and group [constants](#constants) `RunAsUser` and `RunAsGroup`. @@ -1799,7 +1799,7 @@ you can also use the `--library` command-line option. ##### Constants -[Global constants](#global-constants) can be set using the `--define` command-line option. +[Global constants](#constants) can be set using the `--define` command-line option. ##### Config Include Path diff --git a/doc/4-monitoring-basics.md b/doc/4-monitoring-basics.md index 09472d589..caf21b146 100644 --- a/doc/4-monitoring-basics.md +++ b/doc/4-monitoring-basics.md @@ -2297,7 +2297,7 @@ You can customize the metric prefix name by using the `host_name_template` and `service_name_template` configuration attributes. The example below uses [runtime macros](#runtime-macros) and a -[global constant](#global-constants) named `GraphiteEnv`. The constant name +[global constant](#constants) named `GraphiteEnv`. The constant name is freely definable and should be put in the [constants.conf](#constants-conf) file. const GraphiteEnv = "icinga.env1" diff --git a/doc/5-monitoring-remote-systems.md b/doc/5-monitoring-remote-systems.md index 82c254945..d17411c9f 100644 --- a/doc/5-monitoring-remote-systems.md +++ b/doc/5-monitoring-remote-systems.md @@ -1103,7 +1103,7 @@ and configure [cluster scenarios](#cluster-scenarios). #### Configure the Icinga Node Name Instead of using the default FQDN as node name you can optionally set -that value using the [NodeName](#global-constants) constant. +that value using the [NodeName](#constants) constant. > ** Note ** > @@ -1279,7 +1279,7 @@ process. > > `zones.d` must not be included in [icinga2.conf](#icinga2-conf). Icinga 2 automatically > determines the required include directory. This can be overridden using the -> [global constant](#global-constants) `ZonesDir`. +> [global constant](#constants) `ZonesDir`. #### Global Configuration Zone for Templates diff --git a/doc/7-configuring-icinga-2.md b/doc/7-configuring-icinga-2.md index caca3d46d..8b27a718f 100644 --- a/doc/7-configuring-icinga-2.md +++ b/doc/7-configuring-icinga-2.md @@ -1,94 +1,5 @@ # Configuring Icinga 2 -## 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). - -## 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" - } - - ## Configuration Syntax ### Object Definition @@ -129,8 +40,7 @@ The following data types are available for property values: ### 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. #### Numeric Literals @@ -197,7 +107,7 @@ in multi-line string literals. #### 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. #### Null Value @@ -206,7 +116,7 @@ The `null` keyword can be used to specify an empty value. #### 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. @@ -249,6 +159,8 @@ Operator | Examples (Result) | Description - | 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 @@ -291,32 +203,17 @@ Functions can be called using the `()` operator: 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. - -### Dictionary Operators +### 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: #### Operator = -Sets a dictionary element to the specified value. +Sets an attribute to the specified value. Example: @@ -415,6 +312,8 @@ This is equivalent to writing: } } +If the `hello` attribute does not already have a value it is automatically initialized to an empty dictionary. + ### Template Imports Objects can import attributes from other objects. @@ -458,8 +357,31 @@ Global constants can be set using the `const` keyword: 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). ### Apply @@ -578,7 +500,7 @@ C/C++ compiler: 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). @@ -610,7 +532,449 @@ Example: library "snmphelper" +### 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 + } + +### 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 + +### 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. + +### 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. + +## 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) + } + +## 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) + +## 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" + } + +## Built-in functions and methods + +### 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. + +### Number type + +#### 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" */ + +### Boolean type + +#### 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" */ + +### String type + +#### 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 */ + +#### 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 */ + +#### 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" */ + +#### 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" */ + +#### 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`. + +#### 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" ] */ + +#### 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" */ + +#### String#to_string + +Signature: + + function to_string(); + +Returns a copy of the string. + +### ScriptFunction type + +#### 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` */ + +#### 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` */ ## Object Types @@ -1351,7 +1715,7 @@ Attributes: 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" diff --git a/doc/8-migration.md b/doc/8-migration.md index 99032d1b4..168073c4f 100644 --- a/doc/8-migration.md +++ b/doc/8-migration.md @@ -773,7 +773,7 @@ included in `icinga2.conf` by default. ### Main Config File In Icinga 1.x there are many global configuration settings available in `icinga.cfg`. -Icinga 2 only uses a small set of [global constants](#global-constants) allowing +Icinga 2 only uses a small set of [global constants](#constants) allowing you to specify certain different setting such as the `NodeName` in a cluster scenario. Aside from that, the [icinga2.conf](#icinga2-conf) should take care of including @@ -826,7 +826,7 @@ set in the `constants.conf` configuration file: const PluginDir = "/usr/lib/nagios/plugins" -[Global macros](#global-constants) can only be defined once. Trying to modify a +[Global macros](#constants) can only be defined once. Trying to modify a global constant will result in an error. ### Configuration Comments