Documentation: Revamp migration/object accessors, fix several items

fixes #8764
fixes #8771
fixes #8765
fixes #8686
fixes #8740

doc/12-distributed-monitoring-ha.md

@@ -3,7 +3,7 @@
 Building distributed environments with high availability included is fairly easy with Icinga 2.
 The cluster feature is built-in and allows you to build many scenarios based on your requirements:
 
-* [High Availability](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability). All instances in the `Zone` elect one active master and run as Active/Active cluster.
+* [High Availability](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability). All instances in the `Zone` run as Active/Active cluster.
 * [Distributed Zones](12-distributed-monitoring-ha.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones.
 * [Load Distribution](12-distributed-monitoring-ha.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites.
 
@@ -232,7 +232,7 @@ are located. The `check-satellite` zone consists of `icinga2c` only, but more no
 be added.
 
 The `config-ha-master` zone acts as High-Availability setup - the Icinga 2 instances elect
-one active master where all features are running on (for example `icinga2a`). In case of
+one instance running a check, notification or feature (DB IDO), for example `icinga2a`. In case of
 failure of the `icinga2a` instance, `icinga2b` will take over automatically.
 
     object Zone "config-ha-master" {

doc/18-migrating-from-icinga-1x.md

@@ -3,8 +3,8 @@
 ## <a id="configuration-migration"></a> Configuration Migration
 
 The Icinga 2 configuration format introduces plenty of behavioural changes. In
-order to ease migration from Icinga 1.x, Icinga 2 ships its own config migration
+order to ease migration from Icinga 1.x, this section provides hints and tips
-script.
+on your migration requirements.
 
 ### <a id="configuration-migration-script"></a> Configuration Migration Script
 
@@ -12,15 +12,18 @@ A standalone configuration migration script is available at
 https://github.com/Icinga/icinga2-migration. All further
 details on the command line parameters are documented there too.
 
-This script will be merged back upstream into the Icinga Web 2 CLI once there
+Please note that not each configuration detail, trick or attribute does work.
-is a final stable release.
-
-Please note that not each configuration detail, trick or attribute will work.
 Some specific migration steps will be still required to be done manually,
 especially if you want to preserve your existing file layout, or any other
 object specific policies.
 
-If you encounter a bug, please open an issue at https://dev.icinga.org.
+> **Note**
+>
+> It is highly recommended to review your existing installation, do an inventory
+> of checked objects, thresholds and then pland and design your new configuration
+> layout.
+> Keep in mind that the more dynamic approach using the [apply rules](3-monitoring-basics.md#using-apply)
+> allows you to start over in many scenarios.
 
 ### <a id="manual-config-migration"></a> Manual Config Migration
 
@@ -37,7 +40,8 @@ or to adapt your configuration export tool to dump Icinga 2 configuration instea
 Icinga 1.x configuration.
 
 The examples are taken from Icinga 1.x test and production environments and converted
-straight into a possible Icinga 2 format. If you found a different strategy, send a patch!
+straight into a possible Icinga 2 format. If you found a different strategy, please
+let us know!
 
 If you require in-depth explanations, please check the [next chapter](18-migrating-from-icinga-1x.md#differences-1x-2).
 
@@ -110,7 +114,6 @@ Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md#
       assign where "hostgroup3" in host.groups
     }
 
-
 #### <a id="manual-config-migration-hints-group-members"></a> Manual Config Migration Hints for Group Members
 
 The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as
@@ -201,60 +204,6 @@ While you could manually migrate this like (please note the new generic command
       vars.ping_cpl = 60
     }
 
-There also is a quick programmatical workaround for this (example exported from LConf). Define a generic
-check command importing the basic template, and also setting the `$USER1$` macro. Assign it to the global
-`PluginDir` constant.
-
-    template CheckCommand "generic-check-command" {
-      import "plugin-check-command"
-
-      vars.USER1 = PluginDir
-    }
-
-Every check command importing the `generic-check-command` template will now automatically set the new plugin
-directory - one major problem solved.
-
-For the check command it is required to
-
-* Escape all double quotes with an additional `\`.
-* Replace all [runtime macros](18-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`.
-* Replace [custom variable macros](18-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any.
-* Keep `$ARGn$` macros.
-
-The final check command looks like this in Icinga2:
-
-    object CheckCommand "ping4" {
-      import "generic-check-command"
-
-      command = "$USER1$/check_ping -H $address$ -w $ARG1$ -c $ARG2$ -p 5"
-    }
-
-The service object will now set the command arguments as `ARGn` custom attributes.
-
-    check_command                     ping4!100.0,20%!500.0,60%
-
-This command line can be split by the `!` separator into
-
-* `ping4` (command name, keep it for Icinga 2)
-* `100.0,20%` as `vars.ARG1`
-* `500.0,60%` as `vars.ARG2`
-
-The final service could look like:
-
-    apply Service "ping4" {
-      import "generic-service"
-
-      check_command = "ping4"
-
-      vars.ARG1 = "100.0,20%"
-      vars.ARG2 = "500.0,60%"
-
-      assign where host.name == "my-server"
-    }
-
-That way the old command arguments fashion can be applied for Icinga 2, although it's not recommended.
-
-
 #### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
 
 Runtime macros have been renamed. A detailed comparison table can be found [here](18-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
@@ -267,6 +216,14 @@ In Icinga 2 you will need to write:
 
     $service.output$
 
+Another example referencing the host's address attribute in Icinga 1.x:
+
+    $HOSTADDRESS$
+
+In Icinga 2 you'd just use the following macro to access all `address` attributes (even overridden from the service objects):
+
+    $address$
+
 
 #### <a id="manual-config-migration-hints-runtime-custom-attributes"></a> Manual Config Migration Hints for Runtime Custom Attributes
 
@@ -315,6 +272,10 @@ If you are just defining `$CVTEST$` in your command definition its value depends
 execution scope - the host check command will fetch the host attribute value of `vars.CVTEST`
 while the service check command resolves its value to the service attribute attribute `vars.CVTEST`.
 
+> **Note**
+>
+> Custom attributes in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`.
+
 #### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users)
 
 Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
@@ -738,8 +699,12 @@ Icinga 1.x supports two configuration formats: key-value-based settings in the
 `cfg_file`). The path to the `icinga.cfg` configuration file must be passed to
 the Icinga daemon at startup.
 
+icinga.cfg:
+
     enable_notifications=1
 
+objects.cfg:
+
     define service {
        notifications_enabled    0
     }
@@ -747,10 +712,12 @@ the Icinga daemon at startup.
 Icinga 2 supports objects and (global) variables, but does not make a difference
 if it's the main configuration file, or any included file.
 
+icinga2.conf:
+
     const EnableNotifications = true
 
     object Service "test" {
-        enable_notifications = 0
+        enable_notifications = false
     }
 
 #### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
@@ -761,7 +728,7 @@ and includes them in the sample configuration.
 
 Additional plugin check commands are shipped with Icinga 2 as well.
 
-The ITL will be updated on every release and should not be edited by the user.
+The ITL will be updated on every release and must not be edited by the user.
 
 There are still generic templates available for your convenience which may or may
 not be re-used in your configuration. For instance, `generic-service` includes
@@ -770,6 +737,11 @@ all required attributes except `check_command` for a service.
 Sample configuration files are located in the `conf.d/` directory which is
 included in `icinga2.conf` by default.
 
+> **Note**
+>
+> Add your own custom templates in the `conf.d`directory as well, e.g. inside
+> the [templates.conf](5-configuring-icinga-2.md#templates-conf) file.
+
 ### <a id="differences-1x-2-main-config"></a> Main Config File
 
 In Icinga 1.x there are many global configuration settings available in `icinga.cfg`.
@@ -838,11 +810,11 @@ In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
 multi-line comments) or starting with two slashes (`//`). A leading hash (`#`)
 could also be used.
 
-### <a id="differences-1x-2-object-names"></a> Object names
+### <a id="differences-1x-2-object-names"></a> Object Names
 
 Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute
 to specify user-friendly names which should be shown in UIs (supported by
-Icinga 1.x Classic UI and Web).
+Icinga Web 2 for example).
 
 Object names are not specified using attributes (e.g. `service_description` for
 services) like in Icinga 1.x but directly after their type definition.
@@ -926,6 +898,10 @@ In Icinga 2 these attributes must be added to the `vars` dictionary as custom at
 
 These custom attributes are also used as [command parameters](3-monitoring-basics.md#command-passing-parameters).
 
+While Icinga 1.x only supports numbers and strings as custom attribute values,
+Icinga 2 extends that to arrays and (nested) dictionaries. For more details
+look [here](3-monitoring-basics.md#custom-attributes).
+
 ### <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
 
 In Icinga 1.x a service object is associated with a host by defining the
@@ -935,14 +911,22 @@ to `hostgroup_name` or behaviour changing regular expression.
 The preferred way of associating hosts with services in Icinga 2 is by
 using the [apply](3-monitoring-basics.md#using-apply) keyword.
 
+Direct object relations between a service and a host still allow you to use
+the `host_name` [Service](6-object-types.md#objecttype-service) object attribute.
+
 ### <a id="differences-1x-2-users"></a> Users
 
-Contacts have been renamed to users (same for groups). A user does not
+Contacts have been renamed to users (same for groups). A contact does not
-only provide attributes and custom attributes used for notifications, but is also
+only provide (custom) attributes and notification commands used for notifications,
-used for authorization checks.
+but is also used for authorization checks in Icinga 1.x.
+
+Icinga 2 changes that behavior and makes the user an attribute provider only.
+These attributes can be accessed using [runtime macros](3-monitoring-basics.md#runtime-macros)
+inside notification command definitions.
 
 In Icinga 2 notification commands are not directly associated with users.
-Instead the notification command is specified using `Notification` objects.
+Instead the notification command is specified inside `Notification` objects next to
+user and user group relations.
 
 The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
 provide the contact and contactgroups attributes for services for compatibility
@@ -964,36 +948,8 @@ longer specified in the `check_command` setting.
 In Icinga 1.x arguments are specified in the `check_command` attribute and
 are separated from the command name using an exclamation mark (`!`).
 
-    define command {
+Please check the migration hints for a detailed
-        command_name  ping4
+[migration example](18-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
-        command_line  $USER1$/check_ping -H $address$ -w $ARG1$ -c $ARG2$ -p 5
-    }
-
-    define service {
-        use                     local-service
-        host_name               localhost
-        service_description     PING
-        check_command           ping4!100.0,20%!500.0,60%
-    }
-
-With the freely definable custom attributes in Icinga 2 it looks like this:
-
-    object CheckCommand "ping4" {
-        command = PluginDir + "/check_ping -H $address$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$"
-    }
-
-    object Service "PING" {
-        check_command = "ping4"
-        vars.wrta = 100
-        vars.wpl = 20
-        vars.crta = 500
-        vars.cpl = 60
-    }
-
-> **Note**
->
-> For better maintainability you should consider using [command arguments](3-monitoring-basics.md#command-arguments)
-> for your check commands.
 
 > **Note**
 >
@@ -1004,14 +960,17 @@ With the freely definable custom attributes in Icinga 2 it looks like this:
 The global configuration setting `enable_environment_macros` does not exist in
 Icinga 2.
 
-Macros exported into the [environment](#runtime-custom-attribute-env-vars)
+Macros exported into the [environment](3-monitoring-basics.md#command-environment-variables)
-must be set using the `env` attribute in command objects.
+can be set using the `env` attribute in command objects.
 
 #### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
 
 Icinga 2 requires an object specific namespace when accessing configuration
 and stateful runtime macros. Custom attributes can be accessed directly.
 
+If a runtime macro from Icinga 1.x is not listed here, it is not supported
+by Icinga 2.
+
 Changes to user (contact) runtime macros
 
   Icinga 1.x             | Icinga 2
@@ -1191,13 +1150,9 @@ The following external commands are not supported:
 
 ### <a id="differences-1x-2-async-event-execution"></a> Asynchronous Event Execution
 
-Unlike Icinga 1.x, Icinga 2 does not block when it waits for a check command
+Unlike Icinga 1.x, Icinga 2 does not block when it waits for a command
-being executed. Similar when a notification or event handler is triggered - they
+being executed - be it a check, notification, event handler, performance data writing update, etc.
-run asynchronously in their own thread.
+That way you'll recognize low to zero (check) latencies with Icinga 2.
-
-Writing performance data files or status data and log files doesn't block either.
-Last but not least the external command pipe runs asynchronously and accepts
-multiple connections at once.
 
 ### <a id="differences-1x-2-checks"></a> Checks
 
@@ -1238,11 +1193,11 @@ In Icinga 2 these command types are separated and will generate an error on
 configuration validation if used in the wrong context.
 
 While Icinga 2 still supports the complete command line in command objects, it's
-also possible to encapsulate all arguments into double quotes and passing them
+recommended to use [command arguments](3-monitoring-basics.md#command-arguments)
-as array to the `command_line` attribute i.e. for better readability.
+with optional and conditional command line parameters instead.
 
-It's also possible to define default custom attributes for the command itself which can be
+It's also possible to define default argument values for the command itself
-overridden by a service macro.
+which can be overridden by the host or service then.
 
 #### <a id="differences-1x-2-commands-timeouts"></a> Command Timeouts
 
@@ -1260,7 +1215,7 @@ accordingly.
 In Icinga 2 hosts, services, and users are added to groups using the `groups`
 attribute in the object. The old way of listing all group members in the group's
 `members` attribute is available through `assign where` and `ignore where`
-conditions.
+expressions by using [group assign](3-monitoring-basics.md#group-assign-intro).
 
     object Host "web-dev" {
       import "generic-host"
@@ -1273,7 +1228,7 @@ conditions.
 
 #### <a id="differences-1x-2-service-hostgroup-host"></a> Add Service to Hostgroup where Host is Member
 
-In order to associate a service with all hosts in a host group the `apply`
+In order to associate a service with all hosts in a host group the [apply](3-monitoring-basics.md#using-apply)
 keyword can be used:
 
     apply Service "ping4" {
@@ -1421,7 +1376,7 @@ service check is forced.
 
 ### <a id="differences-1x-2-real-reload"></a> Real Reload
 
-In Nagios / Icinga 1.x a daemon reload happens like this
+In Nagios / Icinga 1.x a daemon reload does the following:
 
 * receive reload signal SIGHUP
 * stop all events (checks, notifications, etc)
@@ -1429,24 +1384,26 @@ In Nagios / Icinga 1.x a daemon reload happens like this
 * validation NOT ok: stop the daemon (cannot restore old config state)
 * validation ok: start with new objects, dump status.dat / ido
 
-Unlike Icinga 1.x the Icinga 2 daemon reload happens asynchronously.
+Unlike Icinga 1.x the Icinga 2 daemon reload does not block any event
+execution during config validation:
 
 * receive reload signal SIGHUP
 * fork a child process, start configuration validation in parallel work queues
 * parent process continues with old configuration objects and the event scheduling
 (doing checks, replicating cluster events, triggering alert notifications, etc.)
 * validation NOT ok: child process terminates, parent process continues with old configuration state
-(this is ESSENTIAL for the [cluster config synchronisation](12-distributed-monitoring-ha.md#cluster-zone-config-sync))
+(this is **essential** for the [cluster config synchronisation](12-distributed-monitoring-ha.md#cluster-zone-config-sync))
 * validation ok: child process signals parent process to terminate and save its current state
 (all events until now) into the icinga2 state file
 * parent process shuts down writing icinga2.state file
 * child process waits for parent process gone, reads the icinga2 state file and synchronizes all historical and status data
 * child becomes the new session leader
 
-The DB IDO configuration dump and status/historical event updates also runs asynchronously in a queue not blocking the core anymore. Same goes for any other enabled feature running in its own thread.
+The DB IDO configuration dump and status/historical event updates use a queue
+not blocking event execution. Same goes for any other enabled feature.
 The configuration validation itself runs in parallel allowing fast verification checks.
 
-That way you are not blind (anymore) during a configuration reload and benefit from a real scalable architecture.
+That way your monitoring does not stop during a configuration reload.
 
 
 ### <a id="differences-1x-2-state-retention"></a> State Retention
@@ -1454,7 +1411,7 @@ That way you are not blind (anymore) during a configuration reload and benefit f
 Icinga 1.x uses the `retention.dat` file to save its state in order to be able
 to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
 
-The format objects are stored in is not compatible with Icinga 1.x.
+The format is **not** compatible with Icinga 1.x.
 
 ### <a id="differences-1x-2-logging"></a> Logging
 
@@ -1491,6 +1448,8 @@ distribution out-of-the-box. Furthermore comments, downtimes, and other stateful
 not synced between the master and slave nodes. There are addons available solving the check
 and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
 
-Icinga 2 implements a new built-in [distributed monitoring architecture](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
+Icinga 2 implements a new built-in
+[distributed monitoring architecture](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
 including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ.
-High Availability and load balancing are also part of the Icinga 2 Cluster setup.
+High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay
+logs on connection loss ensuring that the event history is kept in sync.

doc/3-monitoring-basics.md

@@ -155,8 +155,8 @@ Valid values for custom attributes include:
 
 ### <a id="custom-attributes-functions"></a> Functions as Custom Attributes
 
-Icinga lets you specify functions for custom attributes. The special case here
+Icinga 2 lets you specify functions for custom attributes. The special case here
-is that whenever Icinga needs the value for such a custom attribute it runs
+is that whenever Icinga 2 needs the value for such a custom attribute it runs
 the function and uses whatever value the function returns:
 
     object CheckCommand "random-value" {
@@ -193,8 +193,8 @@ value of arbitrary macro expressions:
       return "Some text"
     }}
 
-The [Object Accessor Functions](20-library-reference.md#object-accessor-functions) can be used to retrieve references
+Acessing object attributes at runtime inside these functions is described in the
-to other objects by name.
+[advanced topics](4-advanced-topics.md#access-object-attributes-at-runtime) chapter.
 
 ## <a id="runtime-macros"></a> Runtime Macros
 
@@ -394,8 +394,6 @@ The following macros provide global statistics:
   icinga.num_hosts_acknowledged     | Current number of acknowledged host problems.
 
 
-
-
 ## <a id="using-apply"></a> Apply Rules
 
 Instead of assigning each object ([Service](6-object-types.md#objecttype-service),
@@ -542,15 +540,59 @@ Detailed examples can be found in the [recurring downtimes](4-advanced-topics.md
 
 ### <a id="using-apply-for"></a> Using Apply For Rules
 
-Next to the standard way of using apply rules there is the requirement of generating
+Next to the standard way of using [apply rules](3-monitoring-basics.md#using-apply)
-apply rules objects based on set (array or dictionary). That way you'll save quite
+there is the requirement of generating apply rules objects based on set (array or
-of a lot of duplicated apply rules by combining them into one generic generating
+dictionary).
-the object name with or without a prefix.
 
 The sample configuration already includes a detailed example in [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
 and [services.conf](5-configuring-icinga-2.md#services-conf) for this use case.
 
-Imagine a different example: You are monitoring your switch (hosts) with many
+Take the following example: A host provides the snmp oids for different service check
+types. This could look like the following example:
+
+    object Host "router-v6" {
+      check_command = "hostalive"
+      address6 = "::1"
+
+      vars.oids["if01"] = "1.1.1.1.1"
+      vars.oids["temp"] = "1.1.1.1.2"
+      vars.oids["bgp"] = "1.1.1.1.5"
+    }
+
+Now we want to create service checks for `if01` and `temp` but not `bgp`.
+Furthermore we want to pass the snmp oid stored as dictionary value to the
+custom attribute called `vars.snmp_oid` - this is the command argument required
+by the [snmp]() check command.
+The service's `display_name` should be set to the identifier inside the dictionary.
+
+    apply Service for (identifier => oid in host.vars.oids) {
+      check_command = "snmp"
+      display_name = identifier
+      vars.snmp_oid = oid
+
+      ignore where identifier == "bgp" //don't generate service for bgp checks
+    }
+
+Icinga 2 evalatues the `apply for` rule for all objects with the custom attribute
+`oids` set. It then iterates over all list items inside the `for` loop and evaluates the
+`assign/ignore where` expressions. You can access the loop variable
+in these expressions, e.g. for ignoring certain values.
+In this example we'd ignore the `bgp` identifier and avoid generating an unwanted service.
+We could extend the configuration by also matching the `oid` value on certain regex/wildcard
+patterns for example.
+
+> **Note**
+>
+> You don't need an `assign where` expression only checking for existance
+> of the custom attribute.
+
+That way you'll save duplicated apply rules by combining them into one
+generic `apply for` rule generating the object name with or without a prefix.
+
+
+#### <a id="using-apply-for-custom-attribute-override"></a> Apply For and Custom Attribute Override
+
+Imagine a different more advanced example: You are monitoring your switch (hosts) with many
 interfaces (services). The following requirements/problems apply:
 
 * Each interface service check should be named with a prefix and a running number
@@ -563,7 +605,6 @@ By defining the `interfaces` dictionary with three example interfaces on the `co
 host object, you'll make sure to pass the storage required by the for loop in the service apply
 rule.
 
-
     object Host "core-switch" {
       import "generic-host"
       address = "127.0.0.1"
@@ -593,7 +634,7 @@ The config dictionary contains all key-value pairs for the specific interface in
 loop cycle, like `port`, `vlan`, `address` and `qos` for the `0` interface.
 
 By defining a default value for the custom attribute `qos` in the `vars` dictionary
-before adding the `config` dictionary we''ll ensure that this attribute is always defined.
+before adding the `config` dictionary we'll ensure that this attribute is always defined.
 
 After `vars` is fully populated, all object attributes can be set. For strings, you can use
 string concatention with the `+` operator.
@@ -624,7 +665,7 @@ This can be achieved by wrapping them into the [string()](19-language-reference.
 > after successful [configuration validation](8-cli-commands.md#config-validation).
 
 
-### <a id="using-apply-object attributes"></a> Use Object Attributes in Apply Rules
+### <a id="using-apply-object-attributes"></a> Use Object Attributes in Apply Rules
 
 Since apply rules are evaluated after the generic objects, you
 can reference existing host and/or service object attributes as
@@ -1194,6 +1235,38 @@ Details on all available options can be found in the
 [CheckCommand object definition](6-object-types.md#objecttype-checkcommand).
 
 
+#### <a id="command-environment-variables"></a> Environment Variables
+
+The `env` command object attribute specifies a list of environment variables with values calculated
+from either runtime macros or custom attributes 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" {
+      import "plugin-check-command"
+
+      command = [
+        PluginDir + "/check_mysql"
+      ]
+
+      arguments = {
+        "-H" = "$mysql_address$"
+        "-d" = "$mysql_database$"
+      }
+
+      vars.mysql_address = "$address$"
+      vars.mysql_database = "icinga"
+      vars.mysql_user = "icinga_check"
+      vars.mysql_pass = "password"
+
+      env.MYSQLUSER = "$mysql_user$"
+      env.MYSQLPASS = "$mysql_pass$"
+    }
+
+
+
 ### <a id="notification-commands"></a> Notification Commands
 
 [NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external
@@ -1640,6 +1713,3 @@ and `nrpe-disk` applied to the `nrpe-server`. The health check is defined as
 The `disable-nrpe-checks` dependency is applied to all services
 on the `nrpe-service` host using the `nrpe` check_command attribute
 but not the `nrpe-health` service itself.
-
-
-

doc/4-advanced-topics.md

@@ -208,6 +208,108 @@ Use the `period` attribute to assign time periods to
       period = "workhours"
     }
 
+## <a id="access-object-attributes-at-runtime"></a> Access Object Attributes at Runtime
+
+The [Object Accessor Functions](20-library-reference.md#object-accessor-functions)
+can be used to retrieve references to other objects by name.
+
+This allows you to access configuration and runtime object attributes. A detailed
+list can be found [here](6-object-types.md#object-types).
+
+Simple cluster example for accessing two host object states and calculating a virtual
+cluster state and output:
+
+    object Host "cluster-host-01" {
+      check_command = "dummy"
+      vars.dummy_state = 2
+      vars.dummy_text = "This host is down."
+    }
+
+    object Host "cluster-host-02" {
+      check_command = "dummy"
+      vars.dummy_state = 0
+      vars.dummy_text = "This host is up."
+    }
+
+    object Host "cluster" {
+      check_command = "dummy"
+      vars.cluster_nodes = [ "cluster-host-01", "cluster-host-02" ]
+
+      vars.dummy_state = {{
+        var up_count = 0
+        var down_count = 0
+        var cluster_nodes = macro("$cluster_nodes$")
+
+        for (node in cluster_nodes) {
+          if (get_host(node).state > 0) {
+            down_count += 1
+          } else {
+            up_count += 1
+          }
+        }
+
+        if (up_count >= down_count) {
+          return 0 //same up as down -> UP
+        } else {
+          return 1 //something is broken
+        }
+      }}
+
+      vars.dummy_text = {{
+        var output = "Cluster hosts:\n"
+        var cluster_nodes = macro("$cluster_nodes$")
+
+        for (node in cluster_nodes) {
+          output += node + ": " + get_host(node).last_check_result.output + "\n"
+        }
+
+        return output
+      }}
+    }
+
+
+The following example sets time dependent thresholds for the load check based on the current
+time of the day compared to the defined time period.
+
+    object TimePeriod "backup" {
+      import "legacy-timeperiod"
+
+      ranges = {
+        monday = "02:00-03:00"
+        tuesday = "02:00-03:00"
+        wednesday = "02:00-03:00"
+        thursday = "02:00-03:00"
+        friday = "02:00-03:00"
+        saturday = "02:00-03:00"
+        sunday = "02:00-03:00"
+      }
+    }
+
+    object Host "webserver-with-backup" {
+      check_command = "hostalive"
+      address = "127.0.0.1"
+    }
+
+    object Service "webserver-backup-load" {
+      check_command = "load"
+      host_name = "webserver-with-backup"
+
+      vars.load_wload1 = {{
+        if (get_time_period("backup").is_inside) {
+          return 20
+        } else {
+          return 5
+        }
+      }}
+      vars.load_cload1 = {{
+        if (get_time_period("backup").is_inside) {
+          return 40
+        } else {
+          return 10
+        }
+      }}
+    }
+
 
 ## <a id="check-result-freshness"></a> Check Result Freshness