mirror of https://github.com/Icinga/icinga2.git
Documentation: Emphasize on runtime vs configuration macros.
Fixes #5457 Fixes #5458
This commit is contained in:
Michael Friedrich
parent
9116c58b24
commit
0e2e031c23
|
|
@ -1,8 +1,23 @@
|
|||
|
||||
## <a id="macros"></a> Macros
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> There is a limited set of special [global variables](#global-variables) which can be re-used and
|
||||
> also partly overridden such as `IcingaEnableChecks`.
|
||||
|
||||
### <a id="runtime-macros"></a> Runtime Macros
|
||||
|
||||
Macros may be used in command definitions to dynamically change how the command
|
||||
is executed.
|
||||
Additionally there are Icinga 2 features for example the `PerfDataWriter`
|
||||
using the available runtime macros for output formatting.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Macros are evaluated at runtime when executing a command. These macros cannot be
|
||||
> used inside the configuration objects to add references or similar unless
|
||||
> stated otherwise.
|
||||
|
||||
Here is an example of a command definition which uses user-defined macros:
|
||||
|
||||
|
|
@ -40,6 +55,8 @@ Macro names must be enclosed in two `$` signs, e.g. `$plugindir$`. When using
|
|||
the `$` sign as single character, you need to escape it with an additional dollar
|
||||
sign (`$$`).
|
||||
|
||||
### <a id="runtime-macro-evaluation-order"></a> Runtime Macro Evaluation Order
|
||||
|
||||
When executing commands Icinga 2 checks the following objects in this order to look
|
||||
up macros:
|
||||
|
||||
|
|
@ -74,14 +91,50 @@ emitted to the Icinga 2 log.
|
|||
> Macros in capital letters (e.g. `HOSTNAME`) are reserved for use by Icinga 2
|
||||
> and should not be overwritten by users.
|
||||
|
||||
By convention every host should have an `address` macro. Hosts
|
||||
which have an IPv6 address should also have an `address6` macro.
|
||||
> **Best Practice**
|
||||
>
|
||||
> By convention every host should have an `address` macro. Hosts
|
||||
> which have an IPv6 address should also have an `address6` macro.
|
||||
|
||||
The `plugindir` macro should be set to the path of your check plugins. The
|
||||
`/etc/icinga2/conf.d/macros.conf` file is usually used to define global macros
|
||||
including this one.
|
||||
|
||||
### Host Macros
|
||||
#### Custom Variables as Runtime Macros
|
||||
|
||||
Custom variables are made available as macros using an underscore and the object type
|
||||
in uppercase characters as additional prefix. For example `_HOST`name "_HOST<name>"
|
||||
where <name> is the name of the custom variable.
|
||||
|
||||
#### Runtime Macro Evaluation Order in Cluster Mode
|
||||
|
||||
These macros are evaluated and calculated upon command execution on each node. If a
|
||||
cluster node defines additional macros overriding the default tuples, the calculated
|
||||
macro values will be different and affect only the node executing the command.
|
||||
|
||||
Node 1:
|
||||
|
||||
const IcingaMacros = {
|
||||
plugindir = "/usr/lib/icinga/plugins"
|
||||
}
|
||||
|
||||
Node 2:
|
||||
|
||||
const IcingaMacros = {
|
||||
plugindir = "/usr/lib/monitoring/plugins"
|
||||
}
|
||||
|
||||
CheckCommand definition:
|
||||
|
||||
object CheckCommand "whatever" inherits "plugin-check-command" {
|
||||
command = "$plugindir$/check_whatever"
|
||||
}
|
||||
|
||||
On Node 1, this will be evaluated into `/usr/lib/icinga/plugins/check_whatever`.
|
||||
On Node 2, Icinga 2 will attempt to execute `/usr/lib/icinga/monitoring/check_whatever`
|
||||
instead.
|
||||
|
||||
### <a id="host-runtime-macros"></a> Host Runtime Macros
|
||||
|
||||
The following host macros are available in all commands that are executed for
|
||||
hosts or services:
|
||||
|
|
@ -109,10 +162,16 @@ hosts or services:
|
|||
HOSTADDRESS | This is an alias for the `address` macro. If the `address` macro is not defined the host object's name is used instead.
|
||||
HOSTADDRESS6 | This is an alias for the `address6` macro. If the `address` macro is not defined the host object's name is used instead.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> `HOSTADDRESS` and `HOSTADDRESS6` macros are available as legacy macros. The
|
||||
> Icinga 2 Template Library (`ITL`) examples use the `$address$` macro instead
|
||||
> requiring that macro key to be defined.
|
||||
|
||||
Custom variables are made available as macros with the name "_HOST<name>"
|
||||
where <name> is the name of the custom variable.
|
||||
|
||||
### Service Macros
|
||||
### <a id="service-runtime-macros"></a> Service Runtime Macros
|
||||
|
||||
The following service macros are available in all commands that are executed for
|
||||
services:
|
||||
|
|
@ -146,7 +205,7 @@ services:
|
|||
Custom variables are made available as macros with the name "_SERVICE<name>"
|
||||
where <name> is the name of the custom variable.
|
||||
|
||||
### User Macros
|
||||
### <a id="user-runtime-macros"></a> User Runtime Macros
|
||||
|
||||
The following service macros are available in all commands that are executed for
|
||||
users:
|
||||
|
|
@ -159,16 +218,17 @@ users:
|
|||
USERPAGER | This is an alias for the `pager` macro.
|
||||
|
||||
Custom variables are made available as macros with the name "_USER<name>" and
|
||||
"_CONTACT<name>" where <name> is the name of the custom variable.
|
||||
"_CONTACT<name>" where <name> is the name of the custom variable. "_CONTACT<name>"
|
||||
|
||||
### Notification Macros
|
||||
|
||||
### <a id="notification-runtime-macros"></a> Notification Runtime Macros
|
||||
|
||||
Custom variables are made available as macros with the name "_NOTIFICATION<name>"
|
||||
where <name> is the name of the custom variable.
|
||||
|
||||
### Global Macros
|
||||
### <a id="global-runtime-macros"></a> Global Runtime Macros
|
||||
|
||||
The following macros are available in all commands:
|
||||
The following macros are available in all executed commands:
|
||||
|
||||
Name | Description
|
||||
-----------------------|--------------
|
||||
|
|
@ -177,3 +237,43 @@ The following macros are available in all commands:
|
|||
SHORTDATETIME | Current date and time. Example: `2014-01-0311:23:08`
|
||||
DATE | Current date. Example: `2014-01-03`
|
||||
TIME | Current time including timezone information. Example: `11:23:08+0000`
|
||||
|
||||
### <a id="runtime-macros-env-vars"></a> Runtime Macros as Environment Variables
|
||||
|
||||
The `export_macros` command object attribute requires a list of macros which should
|
||||
be exported as environment variables prior to executing the command.
|
||||
|
||||
This is useful for example for hiding sensitive information on the command line output
|
||||
when passing credentials to database checks:
|
||||
|
||||
object CheckCommand "mysql-health" inherits "plugin-check-command" {
|
||||
command = "$plugindir$/check_mysql -H $address$ -d $db$",
|
||||
/* default macro values */
|
||||
macros = {
|
||||
"MYSQLUSER" = "icinga_check",
|
||||
"MYSQLPASS" = "1c1ng42r0xx"
|
||||
},
|
||||
|
||||
export_macros = [
|
||||
"MYSQLUSER",
|
||||
"MYSQLPASS"
|
||||
]
|
||||
}
|
||||
|
||||
### <a id="configuration-macros"></a> Configuration Macros
|
||||
|
||||
Icinga 2 allows you to define constant variables which can be used in a limited
|
||||
scope. For example, constant expressions can reference a pre-defined global constant
|
||||
variable and calculate a value for the service check interval.
|
||||
|
||||
Example:
|
||||
|
||||
const MyCheckInterval = 10m
|
||||
|
||||
...
|
||||
|
||||
{
|
||||
check_interval = (MyCheckInterval / 2.5)
|
||||
}
|
||||
|
||||
More details in the chapter [Constant Expressions](#constant-expressions).
|
||||
|
|
@ -1 +1 @@
|
|||
# Configuring Icinga
|
||||
# <a id="configuring-icinga2"></a> Configuring Icinga 2
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
## Configuration Syntax
|
||||
## <a id="configuration-syntax"></a> Configuration Syntax
|
||||
|
||||
### Object Definition
|
||||
### <a id="object-definition"></a> Object Definition
|
||||
|
||||
Icinga 2 features an object-based configuration format. In order to
|
||||
define objects the `object` keyword is used:
|
||||
|
|
@ -27,7 +27,7 @@ Each object is uniquely identified by its type (`Host`) and name
|
|||
property declarations. The following data types are available for
|
||||
property values:
|
||||
|
||||
#### Numeric Literals
|
||||
#### <a id="numeric-literals"></a> Numeric Literals
|
||||
|
||||
A floating-point number.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ Example:
|
|||
|
||||
-27.3
|
||||
|
||||
#### Duration Literals
|
||||
#### <a id="duration-literals"></a> Duration Literals
|
||||
|
||||
Similar to floating-point numbers except for the fact that they support
|
||||
suffixes to help with specifying time durations.
|
||||
|
|
@ -47,7 +47,7 @@ Example:
|
|||
Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
|
||||
h (hours) and d (days).
|
||||
|
||||
#### String Literals
|
||||
#### <a id="string-literals"></a> String Literals
|
||||
|
||||
A string.
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ In addition to these pre-defined escape sequences you can specify
|
|||
arbitrary ASCII characters using the backslash character (\\) followed
|
||||
by an ASCII character in octal encoding.
|
||||
|
||||
#### Multi-line String Literals
|
||||
#### <a id="multiline-string-literals"></a> Multi-line String Literals
|
||||
|
||||
Strings spanning multiple lines can be specified by enclosing them in
|
||||
{{{ and }}}.
|
||||
|
|
@ -89,15 +89,15 @@ Example.
|
|||
> Unlike in ordinary strings special characters to not have to be escaped
|
||||
> in multi-line string literals.
|
||||
|
||||
#### Boolean Literals
|
||||
#### <a id="boolean-literals"></a> Boolean Literals
|
||||
|
||||
The keywords `true` and `false` are equivalent to 1 and 0 respectively.
|
||||
|
||||
#### Null Value
|
||||
#### <a id="null-value"></a> Null Value
|
||||
|
||||
The `null` keyword can be used to specify an empty value.
|
||||
|
||||
#### Dictionary
|
||||
#### <a id="dictionary"></a> Dictionary
|
||||
|
||||
An unordered list of key-value pairs. Keys must be unique and are
|
||||
compared in a case-insensitive manner.
|
||||
|
|
@ -124,7 +124,7 @@ Example:
|
|||
> Setting a dictionary key to null causes the key and its value to be
|
||||
> removed from the dictionary.
|
||||
|
||||
#### Array
|
||||
#### <a id="array"></a> Array
|
||||
|
||||
An ordered list of values.
|
||||
|
||||
|
|
@ -140,13 +140,13 @@ Example:
|
|||
> An array may simultaneously contain values of different types, such as
|
||||
> strings and numbers.
|
||||
|
||||
### Operators
|
||||
### <a id="operators"></a> Operators
|
||||
|
||||
In addition to the `=` operator shown above a number of other operators
|
||||
to manipulate configuration objects are supported. Here's a list of all
|
||||
available operators:
|
||||
|
||||
#### Operator =
|
||||
#### <a id="operator-assignment"></a> Operator =
|
||||
|
||||
Sets a dictionary element to the specified value.
|
||||
|
||||
|
|
@ -159,7 +159,7 @@ Example:
|
|||
|
||||
In this example a has the value 7 after both instructions are executed.
|
||||
|
||||
#### Operator +=
|
||||
#### <a id="operator-additive-assignment"></a> Operator +=
|
||||
|
||||
Modifies a dictionary or array by adding new elements to it.
|
||||
|
||||
|
|
@ -175,7 +175,7 @@ only works for dictionaries and arrays.
|
|||
|
||||
<!--
|
||||
|
||||
#### Operator -=
|
||||
#### <a id="operator-substractive-assignment"></a> Operator -=
|
||||
|
||||
Removes elements from a dictionary.
|
||||
|
||||
|
|
@ -189,7 +189,7 @@ Example:
|
|||
In this example a contains `"hello"`. Trying to remove an item that does
|
||||
not exist is not an error. Not implemented yet.
|
||||
|
||||
#### Operator \*=
|
||||
#### <a id="operator-multiply-assignment"></a> Operator \*=
|
||||
|
||||
Multiplies an existing dictionary element with the specified number. If
|
||||
the dictionary element does not already exist 0 is used as its value.
|
||||
|
|
@ -204,7 +204,7 @@ Example:
|
|||
In this example a is 300. This only works for numbers. Not implemented
|
||||
yet.
|
||||
|
||||
#### Operator /=
|
||||
#### <a id="operator-dividing-assignment"></a> Operator /=
|
||||
|
||||
Divides an existing dictionary element by the specified number. If the
|
||||
dictionary element does not already exist 0 is used as its value.
|
||||
|
|
@ -221,7 +221,7 @@ yet.
|
|||
|
||||
-->
|
||||
|
||||
### Indexer
|
||||
### <a id="indexer"></a> Indexer
|
||||
|
||||
The indexer syntax provides a convenient way to set dictionary elements.
|
||||
|
||||
|
|
@ -239,7 +239,7 @@ This is equivalent to writing:
|
|||
}
|
||||
}
|
||||
|
||||
### Inheritance
|
||||
### <a id="object-inheritance"></a> Object Inheritance
|
||||
|
||||
Objects can inherit attributes from other objects.
|
||||
|
||||
|
|
@ -271,7 +271,7 @@ templates though in general they are.
|
|||
Parent objects are resolved in the order they're specified using the
|
||||
`inherits` keyword.
|
||||
|
||||
### Disable/Override Objects and Attributes
|
||||
### <a id="disable-override-objects-attributes"></a> Disable/Override Objects and Attributes
|
||||
|
||||
Object attributes can be overridden by defining the additional changed attribute
|
||||
directly on the object. Use the `+=` operator for the inline services dictionary.
|
||||
|
|
@ -296,7 +296,7 @@ dictionary by exiplicitely overriding their value with `null`.
|
|||
services["ping6"] = null
|
||||
|
||||
|
||||
### Variables
|
||||
### <a id="variables"></a> Variables
|
||||
|
||||
Global variables can be set using the `var` and `const` keywords:
|
||||
|
||||
|
|
@ -313,7 +313,7 @@ the `const` keyword.
|
|||
> in order to provide compatibility with older versions. Its use is
|
||||
> deprecated.
|
||||
|
||||
### Constant Expressions
|
||||
### <a id="constant-expressions"></a> Constant Expressions
|
||||
|
||||
Simple calculations can be performed using the constant expression syntax:
|
||||
|
||||
|
|
@ -357,7 +357,7 @@ Example:
|
|||
retry_interval = 15
|
||||
}
|
||||
|
||||
### Includes
|
||||
### <a id="includes"></a> Includes
|
||||
|
||||
Other configuration files can be included using the `include` directive.
|
||||
Paths must be relative to the configuration file that contains the
|
||||
|
|
@ -385,7 +385,7 @@ paths. Additional include search paths can be added using
|
|||
|
||||
Wildcards are not permitted when using angle brackets.
|
||||
|
||||
### Recursive Includes
|
||||
### <a id="recursive-includes"></a> Recursive Includes
|
||||
|
||||
The `include_recursive` directive can be used to recursively include all
|
||||
files in a directory which match a certain pattern.
|
||||
|
|
@ -418,7 +418,7 @@ Example:
|
|||
|
||||
<!--
|
||||
|
||||
### Type Definition
|
||||
### <a id="type-definition"></a> Type Definition
|
||||
|
||||
By default Icinga has no way of semantically verifying its configuration
|
||||
objects. This is where type definitions come in. Using type definitions
|
||||
|
|
|
|||
Loading…
Reference in New Issue