General Information

This section provides information that applies to all of the DirX Directory Nagios plugins, followed by reference pages for each Nagios plugin and the plugin configuration file.

Prerequisites and Limitations

The DirX Directory Nagios plugins have the following pre-requisites and limitations:

  • The Perl language/interpreter must be installed on each plugin host.

  • On Windows, Perl distribution version 5.16.3 or newer.

  • On Linux, Perl distribution version 5.8 or newer.

  • The perl-ldap distribution must be installed on all plugin hosts that:

  • Allow the plugins to make direct LDAP extended operation calls. See the section Plugin Operation for details.

  • Run the check_dirx_heartbeat plugin.

    See the ReadMe.txt file in the DirX Directory Nagios plugin installation folder (install_path/monitoring/nagios) for instructions on how to set up Perl and perl-ldap on the supported DirX Directory platforms.

  • Because most of the plugins use new and specialized LDAP server extended operations available only in DirX Directory V8.3, they cannot be used with older DirX Directory versions.

Installation Location

DirX Directory provides the DirX Directory Nagios plugins in the location install_path*/monitoring/nagios*. This folder contains the following files:

  • The files that contain the plugin operation code (*.pl).

  • The support module check_dirx_common.pm, which contains common routines used by many of the plugin *.pl files.

  • The configuration module check_dirx_config.pm.sample, which contains local settings for plugin LDAP calls.

Plugin Operation

The DirX Directory Nagios plugins operate in a Nagios configuration as follows:

  • The Nagios monitoring host runs on a host (typically a Linux machine). It periodically polls the status of the DirX Directory service by invoking the DirX Directory Nagios plugins via the Nagios Remote Plugin Executor (NRPE) to gather the required monitoring data for the objects they monitor.

  • The DirX Directory Nagios plugins are installed on the remote monitored hosts, co-located with an NRPE daemon. Each DirX Directory Nagios plugin is tailored to the object it monitors. When called by the Nagios monitoring host, each plugin returns the following data to the Nagios monitoring host:

  • The object’s current status, for immediate display in the Nagios Web-based browser interface.

  • Performance data about the object, to be stored in the Nagios system for later correlation and display in graph format via Nagios add-ons like pnp4nagios.

  • The DirX Directory Nagios plugins interact with their monitored DirX Directory service objects via LDAP server extended operations. The plugins can be configured to use the DirX Directory command dirxextop to perform these operations or to use direct LDAP calls to the extended operations. See the sections Plugin Configuration and Common Plugin Syntax for details.

Plugin Configuration

To use the DirX Directory Nagios plugins in an existing Nagios configuration, both the Nagios monitoring host and the remote DirX Directory Nagios plugin hosts must be configured to use NRPE and the plugins must be defined as Nagios services on the monitoring host and as NRPE commands on the remote plugin hosts. See the Nagios documentation, in particular, the NRPE documentation, for instructions.

The plugins have the following additional configuration requirements:

  • Hosts that support the use of dirxextop for plugin LDAP extended operations must allow NRPE to execute this command. To enable dirxextop execution by NRPE:

  • Add the account name of the user who installed Nagios user to the same group as the account name of the user who installed DirX Directory.

  • Set an x-bit for dirxextop as necessary.

  • The perl-ldap distribution must be installed on all hosts that shall support the use of direct LDAP extended operation calls by the plugins, as described in the section Prerequisites and Limitations. The perl-ldap distribution is also needed if the heartbeat plugin shall be used. See the ReadMe.txt file in the DirX Directory Nagios plugin installation folder (install_path*/monitoring/nagios*) for instructions.

  • The DirX Directory Nagios plugins include the check_dirx_config.pm configuration file, which contains the local settings for making LDAP calls. A template configuration file is supplied in install_path*/monitoring/nagios/ check_dirx_config.pm.sample*. On each remote plugin host:

  • Copy this file and rename it to check_dirx_config.pm.

  • Edit the file with the local settings that apply. See the check_dirx_config.pm reference page for details.

  • The user(s) specified in the configuration file for performing dirxextop operations or direct LDAP calls on the plugins' behalf must be configured in the LDAP Extended Operations Admins (ldapExtOpAdmin) attribute or in the LDAP Extended Operations Monitoring Users (ldapExtOpMonitoringUsers) attribute in the LDAP server configuration subentry. See the subsection Attributes Controlling LDAP Extended Operations in the section Attributes for LDAP Server Configuration in DirX Directory Syntaxes and Attributes for details.

Common Plugin Syntax

All plugins use the following calling convention:

[perl] check_dirx*_object.pl* -w warning_value -c critical_value [common_options]

Where:

perl
Specifies the perl command. This parameter is only required when invoking a plugin from a shell.

check_dirx_object
Specifies the plugin’s executable name, starting with check_dirx_ and followed by a string that describes the object to be monitored; for example, backup_status, ctx, ldap_duration, and so on.

-w warning_value
Specifies the value to be used as a warning threshold for determining the status of the monitored object. An object found to meet or exceed this threshold during a check operation is flagged with WARNING status (exit code 1). The warning_value is interpreted as an absolute value or a relative percentage value, depending on the plugin. See the plugin reference descriptions for details.

-c critical_value
Specifies the value to be used as a critical threshold for determining the status of the monitored object. An object found to meet or exceed this threshold during a check operation is flagged with CRITICAL status (exit code 2).The critical_value is interpreted as an absolute value or a percentage value, depending on the plugin. See the plugin reference descriptions for details.

common_options
Specifies one or more of the following options:

-h—Displays the usage description for the plugin.

-L—Executes direct LDAP calls for extended LDAP operation via perl (Net::LDAP). If this option is not specified, the dirxextop command is used. Using the -L option requires the perl-ldap distribution to be installed. Using dirxextop requires Nagios NRPE to be able to execute the command. See the section Plugin Configuration for details.

-v—Displays the DirX Directory Nagios plugin version, in the format:

plugin_name: plugin_version date

For example:

check_dirx_ctx.pl: V1.1 Build Feb-12, 2013

-x—Writes logging information to standard output. This option is for use in debug mode only for analyzing problems when running the plugin from a shell. Do not use this option when running the plugin from the Nagios monitoring host or the Nagios NRPE.

Most of the plugins require the -w and -c arguments and return an error if they are not specified.

Invoking a plugin without any arguments or options returns a usage description for the plugin.

Common Return Code Format

All DirX Directory Nagios plugins support the following return code format, as required by the Nagios product:

printable_string [ | performance_data]

where:

printable_string
Is a simple message that is printable via standard output. The Nagios monitoring host displays the printable string returned by the plugin in current status displays. The DirX Directory Nagios plugins return printable_string in the format:

plugin_name status – result_description

where:

plugin_name
Is the name of the DirX Directory Nagios plugin returning the message.

status
Is the status code returned by the plugin and is one of the following Nagios-defined values:

OK—The status of the monitored object is within the boundaries defined by the specified warning and critical values). This status corresponds to the Nagios-defined exit code 0 (which the plugin must return on exit) and is displayed in green in Nagios current status displays.

WARNING—The warning_value specified to the plugin was exceeded. This status corresponds to the Nagios-defined exit code 1 (which the plugin must return on exit) and is displayed in yellow in Nagios current status displays.

CRITICAL—The critical_value specified to the plugin was exceeded. This status corresponds to the Nagios-defined exit code 2 (which the plugin must return on exit) and is displayed in red in Nagios current status displays.

UNKNOWN—The plugin encountered an execution error. This status corresponds to the Nagios-defined exit code 3 (which the plugin must return on exit) and is displayed in orange in Nagios current status displays. When this status is returned, it is recommended to run the plugin from the shell and use the -x (debug) option as necessary to determine the cause of the problem.

result_description
Is a short description of the result.

performance_data
Is current data relevant to the performance of the monitored object that is intended to be collected over time and used for long-term trend analysis. The Nagios system saves the returned performance data in a database reserved to the monitored object that can be displayed graphical format later on.

Performance data consists of one or more label/value pairs separated by spaces. Each label/value pair has the Nagios-defined format:

label=value[UOM];[warn];[crit];[min];[max]

where:

  • label can contain any character. It must be enclosed in single quotes if it contains spaces, = or '. To specify a quotation character, use two single quotation marks (''). Label length is arbitrary, but ideally the first 19 characters are unique (due to a Nagios performance database limitation).

  • UOM is the unit of measurement and is one of the following values:

unspecified - indicates a number (int or float) of items (for example, users, processes, load averages)

s - seconds | us - microseconds | ms - milliseconds

% - percentage

B - bytes | KB - kilobytes | MB - megabytes | TB - terabytes | GB - gigabytes

c - indicates a continuous counter (an increment-only counter)

  • warn and crit are the current warning_value and critical_value respectively, are in the range format and must be the same unit of measurement.

  • value, min and max are in the class [-0-9.] and must all be the same unit of measurement. min and max represent the minimum and maximum displayable value. min and max are not required if UOM is %.

warn/crit and min/max are optional; for example, if the threshold is not defined or min and max do not apply. Trailing semicolons present when these values are not specified can be omitted.

For example, the following label/value pair:

NumProcesses=225;500;1000;0;100000

directs Nagios to maintain a database for an integer value called NumProcesses. The database stores the current value of 225 and identifies it with the current time.

When Nagios later displays a graph for the NumProcesses item, a yellow warning line is displayed at a value of 500 and a red line is displayed at a level of 1000 to indicate the warning and critical levels in the graphical output. The values 0 and 100000 are hints for the for the Nagios database software that indicate in which range of numbers the values will appear to better organize the database.

The next section DirX Directory Nagios Plugins Reference Descriptions provides details about each DirX Directory Nagios plugin’s calling syntax, operation and return codes. See the Nagios documentation for more information on required plugin exit/return code syntax.