Documentation: Emphasize on runtime vs configuration macros.

Fixes #5457
Fixes #5458

doc/3.03-macros.md

@@ -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
+> **Best Practice**
-which have an IPv6 address should also have an `address6` macro.
+>
+> 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).

doc/4-configuring-icinga.md

@@ -1 +1 @@
-# Configuring Icinga
+# <a id="configuring-icinga2"></a> Configuring Icinga 2

doc/4.1-configuration-syntax.md

@@ -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