From fdd5fbc2176d3436a1f00c18db24aff3a9c947f8 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Mon, 31 Mar 2014 13:27:39 +0200 Subject: [PATCH] Update documentation. Refs #5877 --- doc/2.1-setting-up-icinga-2.md | 14 +++---- doc/2.2-setting-up-check-plugins.md | 17 +++++---- doc/3.02-commands.md | 12 +++--- doc/3.03-macros.md | 40 ++------------------ doc/3.04-notifications.md | 2 +- doc/3.15-monitoring-remote-clients.md | 6 +-- doc/4.3-object-types.md | 11 +++++- doc/5-icinga-template-library.md | 23 ++--------- doc/8-differences-between-icinga-1x-and-2.md | 19 +++++----- icinga2.spec | 2 +- 10 files changed, 51 insertions(+), 95 deletions(-) diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index ab2c60d44..1742bc234 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/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. -### macros.conf +### 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 -to define global macros which are available in all command definitions. + const PluginDir = "/usr/lib/nagios/plugins" ### localhost.conf diff --git a/doc/2.2-setting-up-check-plugins.md b/doc/2.2-setting-up-check-plugins.md index 6f81b9fa3..145d869d5 100644 --- a/doc/2.2-setting-up-check-plugins.md +++ b/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", - customplugindir = "/opt/monitoring" - } + + const PluginDir = "/usr/lib/nagios/plugins" + 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: diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md index 9eb8ee02e..35ca0583f 100644 --- a/doc/3.02-commands.md +++ b/doc/3.02-commands.md @@ -6,10 +6,10 @@ events should be handled. > **Note** > -> Define the `$plugindir$` macro in your global `IcingaMacros` variable -> (located in `/etc/icinga2/conf.d/macros.conf` by default) and use +> Define the global `PluginDir` constant (located in +> `/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. ### 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", diff --git a/doc/3.03-macros.md b/doc/3.03-macros.md index 5cb76565a..c2b81fb9d 100644 --- a/doc/3.03-macros.md +++ b/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" where 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. - ### 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", diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index edcb164ac..f70e6c96f 100644 --- a/doc/3.04-notifications.md +++ b/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` diff --git a/doc/3.15-monitoring-remote-clients.md b/doc/3.15-monitoring-remote-clients.md index 401b225fb..bb15d1252 100644 --- a/doc/3.15-monitoring-remote-clients.md +++ b/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$", diff --git a/doc/4.3-object-types.md b/doc/4.3-object-types.md index 3a60a7ba2..a2e6c4504 100644 --- a/doc/4.3-object-types.md +++ b/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", diff --git a/doc/5-icinga-template-library.md b/doc/5-icinga-template-library.md index d2e914f86..d7c4b2c6e 100644 --- a/doc/5-icinga-template-library.md +++ b/doc/5-icinga-template-library.md @@ -10,6 +10,9 @@ file: include +The ITL assumes that there's a global constant named `PluginDir` which contains +the path of the plugins from the Monitoring Plugins project. + ## Check Commands ### 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. ### http_ip @@ -113,7 +109,6 @@ Macros: Name | Description ----------------|-------------- -plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. ### 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. ### https_ip @@ -135,7 +129,6 @@ Macros: Name | Description ----------------|-------------- -plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. ### smtp @@ -146,7 +139,6 @@ Macros: Name | Description ----------------|-------------- -plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. ### 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. ### ssh @@ -180,7 +170,6 @@ Macros: Name | Description ----------------|-------------- -plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. ### 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". diff --git a/doc/8-differences-between-icinga-1x-and-2.md b/doc/8-differences-between-icinga-1x-and-2.md index 33f2acc1e..3761e0ea6 100644 --- a/doc/8-differences-between-icinga-1x-and-2.md +++ b/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 -`conf.d/macros.conf` file: +Icinga 2 uses global constants instead. In the default config these are +set in the `constants.conf` configuration file: /** - * Global macros - */ - set IcingaMacros = { - plugindir = "/usr/lib/nagios/plugins" - } + * This file defines global constants which can be used in + * the other configuration files. At a minimum the + * PluginDir constant should be defined. + */ + + 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. diff --git a/icinga2.spec b/icinga2.spec index 293066b7e..2d494142e 100644 --- a/icinga2.spec +++ b/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 -- 2.40.0