## <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:
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:
> 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:
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:
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:
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
-----------------------|--------------
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).
\ No newline at end of file
-## 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:
property declarations. The following data types are available for
property values:
-#### Numeric Literals
+#### <a id="numeric-literals"></a> Numeric Literals
A floating-point number.
-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.
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.
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 }}}.
> 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.
> 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.
> 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.
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.
<!--
-#### Operator -=
+#### <a id="operator-substractive-assignment"></a> Operator -=
Removes elements from a dictionary.
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.
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.
-->
-### Indexer
+### <a id="indexer"></a> Indexer
The indexer syntax provides a convenient way to set dictionary elements.
}
}
-### Inheritance
+### <a id="object-inheritance"></a> Object Inheritance
Objects can inherit attributes from other objects.
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.
services["ping6"] = null
-### Variables
+### <a id="variables"></a> Variables
Global variables can be set using the `var` and `const` keywords:
> 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:
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
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.
<!--
-### 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
projects / icinga2 / commitdiff