Update documentation.

Refs #5877

doc/2.1-setting-up-icinga-2.md

@@ -114,19 +114,17 @@ the features which have been enabled with `icinga2-enable-feature`. See
 You can put your own configuration files in the `conf.d` directory. This
 directive makes sure that all of your own configuration files are included.
 
-### <a id="macros-conf"></a> macros.conf
+### <a id="constants-conf"></a> constants.conf
 
-The `conf.d/macros.conf` file can be used to define global macros:
+The `constants.conf` constants file can be used to define global constants:
 
     /**
-     * Global macros
+     * This file defines global constants which can be used in
+     * the other configuration files. At a minimum the
+     * PluginDir constant should be defined.
      */
-    const IcingaMacros = {
-      plugindir = "/usr/local/icinga/libexec"
-    }
 
-Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used
+    const PluginDir = "/usr/lib/nagios/plugins"
-to define global macros which are available in all command definitions.
 
 ### <a id="localhost-conf"></a> localhost.conf
 

doc/2.2-setting-up-check-plugins.md

@@ -25,7 +25,7 @@ FreeBSD                | nagios-plugins     | /usr/local/libexec/nagios
 OS X (MacPorts)        | nagios-plugins     | /opt/local/libexec
 
 Depending on which directory your plugins are installed into you may need to
-update the `plugindir` macro in your Icinga 2 configuration. This macro is used
+update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
 by the service templates contained in the Icinga Template Library to determine
 where to find the plugin binaries.
 
@@ -41,20 +41,21 @@ list of popular community sites which host check plugins:
 * [Icinga Wiki](https://wiki.icinga.org)
 
 The recommended way of setting up these plugins is to copy them to a common directory
-and creating an extra global macro, e.g. `customplugindir` in your `macros.conf`
+and creating an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
 configuration file:
 
     # cp check_snmp_int.pl /opt/plugins
     # chmod +x /opt/plugins/check_snmp_int.pl
 
-    # cat /etc/icinga2/conf/macros.conf
+    # cat /etc/icinga2/constants.conf
     /**
-     * Global macros
+     * This file defines global constants which can be used in
+     * the other configuration files. At a minimum the
+     * PluginDir constant should be defined.
      */
-    const IcingaMacros = {
+
-      plugindir = "/usr/lib/nagios/plugins",
+    const PluginDir = "/usr/lib/nagios/plugins"
-      customplugindir = "/opt/monitoring"
+    const CustomPluginDir = "/opt/monitoring"
-    }
 
 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 by trying to run it on the console using whichever user Icinga 2 is running as:

doc/3.02-commands.md

@@ -6,10 +6,10 @@ events should be handled.
 
 > **Note**
 >
-> Define the `$plugindir$` macro in your global `IcingaMacros` variable
+> Define the global `PluginDir` constant (located in
-> (located in `/etc/icinga2/conf.d/macros.conf` by default) and use
+> `/etc/icinga2/conf.d/macros.conf` by default) and use
 > it in all your command object definitions.
-> Put your plugins and scripts into the directory defined by the `$plugindir$` macro
+> Put your plugins and scripts into the directory defined by the `PluginDir` constant
 > and make sure they are executable by the Icinga 2 user.
 
 ### <a id="environment-macros"></a> Environment Macros
@@ -38,7 +38,7 @@ to define all macros in the `export_macros` attribute as list.
 > to support native plugin based check methods.
 
 Unless you have done so already, download your check plugin and put it
-into the `$plugindir$` directory. The following example uses the
+into the `PluginDir` directory. The following example uses the
 `check_disk` plugin shipped with the Nagios Plugins package.
 
 The plugin path and all command arguments are made a list of
@@ -63,7 +63,7 @@ then use these macros on the command line.
       import "plugin-check-command",
 
       command = [
-        "$plugindir$/check_disk",
+        PluginDir + "/check_disk",
         "-w", "$wfree$%",
         "-c", "$cfree$%"
       ],
@@ -191,7 +191,7 @@ information in the check output (`-o`).
       import "plugin-event-command",
 
       command = [ 
-        "$plugindir$/process_check_result",
+        PluginDir + "/process_check_result",
         "-H",
         "$HOSTNAME$",
         "-S",

doc/3.03-macros.md

@@ -25,7 +25,7 @@ Here is an example of a command definition which uses user-defined macros:
       import "plugin-check-command",
 
       command = [
-        "$plugindir$/check_ping",
+        PluginDir + "/check_ping",
         "-4",
         "-H", "$address$",
         "-w", "$wrta$,$wpl$%",
@@ -53,7 +53,7 @@ Here is an example of a command definition which uses user-defined macros:
 > may have arbitrary names and arguments are no longer specified in the
 > `check_command` setting.
 
-Macro names must be enclosed in two `$` signs, e.g. `$plugindir$`. When using
+Macro names must be enclosed in two `$` signs, e.g. `$address$`. When using
 the `$` sign as single character, you need to escape it with an additional dollar
 sign (`$$`).
 
@@ -96,46 +96,12 @@ emitted to the Icinga 2 log.
 > 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.
-
 #### 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" {
-      import "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
@@ -251,7 +217,7 @@ when passing credentials to database checks:
     object CheckCommand "mysql-health" {
       import "plugin-check-command",
 
-      command = "$plugindir$/check_mysql -H $address$ -d $db$",
+      command = PluginDir + "/check_mysql -H $address$ -d $db$",
       /* default macro values */
       macros = {
         "MYSQLUSER" = "icinga_check",

doc/3.04-notifications.md

@@ -176,7 +176,7 @@ Define an additional `NotificationCommand` for sms notifications.
 > or local hardware with a sim card active.
 
     object NotificationCommand "sms-notification" {
-       command = "$plugindir$/send_sms_notification $mobile$ ..."
+       command = PluginDir + "/send_sms_notification $mobile$ ..."
     }
     
 The two new notification escalations are added onto the host `localhost`

doc/3.15-monitoring-remote-clients.md

@@ -43,7 +43,7 @@ its return code and output. `check_by_ssh` is available in the [Monitoring Plugi
     object CheckCommand "check_by_ssh_swap" {
       import "plugin-check-command",
 
-      command = [ "$plugindir$/check_by_ssh",
+      command = [ PluginDir + "/check_by_ssh",
                   "-l", "remoteuser",
                   "-H", "$address$",
                   "-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\""
@@ -78,7 +78,7 @@ Example:
     object CheckCommand "check_nrpe" {
       import "plugin-check-command",
 
-      command = [ "$plugindir$/check_nrpe",
+      command = [ PluginDir + "/check_nrpe",
                   "-H", "$address$",
                   "-c", "$remote_nrpe_command$",
                 ],
@@ -114,7 +114,7 @@ Example:
     object CheckCommand "check_nscp" {
       import "plugin-check-command",
 
-      command = [ "$plugindir$/check_nt",
+      command = [ PluginDir + "/check_nt",
                   "-H", "$address$",
                   "-p", "$port$",
                   "-v", "$remote_nscp_command$",

doc/4.3-object-types.md

@@ -419,7 +419,12 @@ Example:
     object CheckCommand "check_snmp" {
       import "plugin-check-command",
 
-      command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
+      command = [
+        PluginDir + "/check_snmp",
+	"-H", "$address$",
+	"-C", "$community$",
+	"-o", "$oid$"
+      ],
 
       macros = {
         address = "127.0.0.1",
@@ -447,7 +452,9 @@ Example:
     object NotificationCommand "mail-service-notification" {
       import "plugin-notification-command",
 
-      command = [ IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh" ],
+      command = [
+        IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh"
+      ],
 
       export_macros = [
         "NOTIFICATIONTYPE",

doc/5-icinga-template-library.md

@@ -10,6 +10,9 @@ file:
 
     include <itl/itl.conf>
 
+The ITL assumes that there's a global constant named `PluginDir` which contains
+the path of the plugins from the Monitoring Plugins project.
+
 ## <a id="itl-check-commands"></a> Check Commands
 
 ### <a id="itl-ping4"></a> ping4
@@ -20,7 +23,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 wrta            | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
 wpl             | **Optional.** The packet loss warning threshold in %. Defaults to 5.
@@ -37,7 +39,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address6        | **Required.** The host's IPv6 address.
 wrta            | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
 wpl             | **Optional.** The packet loss warning threshold in %. Defaults to 5.
@@ -54,7 +55,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 state           | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
 text            | **Optional.** Plugin output. Defaults to "Check was successful.".
 
@@ -66,7 +66,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 state           | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3.
 text            | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
 
@@ -78,7 +77,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 port            | **Required.** The port that should be checked.
 
@@ -90,7 +88,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 port            | **Required.** The port that should be checked.
 
@@ -102,7 +99,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 vhost           | **Required.** The name of the virtual host that should be checked.
 
 ### <a id="itl-http-ip"></a> http_ip
@@ -113,7 +109,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 
 ### <a id="itl-https-vhost"></a> https_vhost
@@ -124,7 +119,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 vhost           | **Required.** The name of the virtual host that should be checked.
 
 ### <a id="itl-https-ip"></a> https_ip
@@ -135,7 +129,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 
 ### <a id="itl-smtp"></a> smtp
@@ -146,7 +139,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 
 ### <a id="itl-ssmtp"></a> ssmtp
@@ -157,7 +149,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 port            | **Optional.** The port that should be checked. Defaults to 465.
 
@@ -169,7 +160,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 
 ### <a id="itl-ssh"></a> ssh
@@ -180,7 +170,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 
 ### <a id="itl-disk"></a> disk
@@ -191,7 +180,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 wfree           | **Optional.** The free space warning threshold in %. Defaults to 20.
 cfree           | **Optional.** The free space critical threshold in %. Defaults to 10.
 
@@ -203,7 +191,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 wgreater        | **Optional.** The user count warning threshold. Defaults to 20.
 cgreater        | **Optional.** The user count critical threshold. Defaults to 50.
 
@@ -215,7 +202,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 wgreater        | **Optional.** The process count warning threshold. Defaults to 250.
 cgreater        | **Optional.** The process count critical threshold. Defaults to 400.
 
@@ -227,7 +213,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 wload1          | **Optional.** The 1-minute warning threshold. Defaults to 5.
 wload5          | **Optional.** The 5-minute warning threshold. Defaults to 4.
 wload15         | **Optional.** The 15-minute warning threshold. Defaults to 3.
@@ -243,7 +228,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 oid             | **Required.** The SNMP OID.
 community       | **Optional.** The SNMP community. Defaults to "public".
@@ -256,7 +240,6 @@ Macros:
 
 Name            | Description
 ----------------|--------------
-plugindir       | **Required.** The directory containing this plugin.
 address         | **Required.** The host's address.
 oid             | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0".
 community       | **Optional.** The SNMP community. Defaults to "public".

doc/8-differences-between-icinga-1x-and-2.md

@@ -76,15 +76,16 @@ Global macros such as for the plugin directory, usernames and passwords can be
 set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
 `USER1` macro is used to define the directory for the plugins.
 
-Icinga 2 uses a global `IcingaMacros` constant variable which is set in the
+Icinga 2 uses global constants instead. In the default config these are
-`conf.d/macros.conf` file:
+set in the `constants.conf` configuration file:
 
     /**
-     * Global macros
+     * This file defines global constants which can be used in
-    */
+     * the other configuration files. At a minimum the
-    set IcingaMacros = {
+     * PluginDir constant should be defined.
-      plugindir = "/usr/lib/nagios/plugins"
+     */
-    }
+
+    const PluginDir = "/usr/lib/nagios/plugins"
 
 > **Note**
 >
@@ -280,7 +281,7 @@ are separated from the command name using an exclamation mark (`!`).
 With the freely definable macros in Icinga 2 it looks like this:
 
     object CheckCommand "ping4" {
-        command = "$plugindir$/check_ping -H $HOSTADDRESS$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$",
+        command = PluginDir + "/check_ping -H $HOSTADDRESS$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$",
     }
 
     object Service "PING" {
@@ -295,7 +296,7 @@ With the freely definable macros in Icinga 2 it looks like this:
 
 > **Note**
 >
-> Tip: The above example uses the global $plugindir$ macro instead of the Icinga 1.x
+> Tip: The above example uses the global `PluginDir` constant instead of the Icinga 1.x
 > $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely
 > definable macros.
 

icinga2.spec

@@ -265,7 +265,7 @@ install -D -m 0644 etc/icinga/icinga-classic-apache.conf %{buildroot}%{apachecon
 
 # fix plugin path on x64
 %if "%{_vendor}" != "suse"
-sed -i 's@plugindir = .*@plugindir = "%{_libdir}/nagios/plugins"@' %{buildroot}/%{_sysconfdir}/%{name}/conf.d/macros.conf
+sed -i 's@PluginDir = .*@PluginDir = "%{_libdir}/nagios/plugins"@' %{buildroot}/%{_sysconfdir}/%{name}/constants.conf
 %endif
 
 # remove features-enabled symlinks