DirX Directory Nagios Plugins Reference Descriptions

[perl] check_dirx_backup_status.pl -w warning_value -c critical_value [-L] [-h] [-v] [-x]

Evaluates the status of the last dirxbackup save or delta save operation.

-w warning_value
The number of seconds since the last dirxbackup save operation that defines the WARNING threshold for the time period between DirX Directory database backups. For example, 3600.

-c critical_value
The number of seconds since the last dirxbackup save operation that defines the CRITICAL threshold for the time period between DirX Directory database backups. For example, 86400.

See the section Common Plugin Syntax for a description of the options used in this plugin.

The check_dirx_backup_status plugin evaluates the time of the most recent dirxbackup operation and returns a status not equal to OK if either the warning threshold or the critical threshold is reached or an error occurs while the plugin is processing.

Use this DirX Directory Nagios plugin to monitor the frequency of DirX Directory database backup operations.

When called by Nagios (or from a shell), the check_dirx_backup_status plugin operates on output returned by a call to the dsa_backup_status extended operation. This operation returns the time, duration and completion status of the last dirxbackup save operation and the last delta save operation, if it is available. See Example for an example of the output.

The plugin calculates the difference between the current time and the timestamp of the most recent dirxbackup save operation returned in the output and then compares it to the warning and critical thresholds for backup frequency specified in the -w and -c arguments. It also checks the completion status returned in the output.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the date/time, duration and size of the most recent backup.

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command:

The plugin calls the dsa_backup_status extended operation. Suppose the operation returns the following data to the plugin:

Given this output, the plugin determines that the delta backup operation is the most recent backup. It evaluates the status of this operation and the time at which it occurred. In this example, the plugin determines that the delta backup operation completed successfully, but the difference between the current time and the time at which the backup operation occurred is more than the 3600 second limit specified in the -w argument. The plugin returns the following message:

DIRX-BACKUP-STATUS WARNING - Last delta backup at Mo 16 Dez 2013 14:10:35 W. Europe Standard Time, duration 11 sec, size 36334 kb

Note that the timestamp format shown in the output varies according to the operating system in use and other time-related local settings.

dirxbackup, dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_ctx.pl -w warning_value -c critical_value -T DSA | LDAP [-L] [-h] [-v] [-x]

Checks the CTX memory consumption of a DSA or an LDAP server.

-w warning_value
The percentage of the maximum CTX size that defines the WARNING threshold for CTX memory consumption. For example, a value of 50 indicates that when 50% of CTX memory is in use, a WARNING result should be returned.

-c critical_value
The percentage of the maximum CTX size that defines the CRITICAL threshold for CTX memory consumption. For example, a value of 90 indicates that when 90% of CTX memory is in use, a CRITICAL result should be returned.

-T DSA | LDAP
The target server to monitor. Specify DSA to monitor a DirX Directory DSA. Specify LDAP to monitor an LDAP server.

See the section Common Plugin Syntax for a description of the -L, -h, -v and -x options. These options are common to all DirX Directory Nagios plugins.

The check_dirx_ctx plugin evaluates the amount of CTX memory in use by a DSA or an LDAP server and returns a status not equal to OK if either the warning threshold or the critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to check the consumption of CTX memory by DSA and LDAP server processes in a DirX Directory service installation against the maximum available amount (in MB) defined in the DIRX_CTX_LIMIT environment variable.

When called by Nagios (or from the shell), the check_dirx_ctx plugin operates on data returned from a call to the dsa_ctxinfo extended operation (for -T DSA) or the ldap_ctxinfo extended operation (for -T LDAP). See Example for an example of the output.

The plugin extracts the following values from the returned data:

Next, the plugin evaluates the percentage of memory consumption using the following calculation:

Consumption in percent = 100 * CurrTotal-CTX-Size / EntireCTXLimitHard

The plugin then checks whether the current consumption is above the percentages given in the -w and -c arguments. As long as the current consumption is below the percentage given in warning_value, the status is OK.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current values of CTX and HWM.

The plugin also returns the following performance data for CTX and HWM:

Note that because this plugin monitors percentage values, administrators can increase or decrease the maximum available CTX memory allocation without affecting the plugin’s configuration.

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command:

The plugin calls the ldap_ctxinfo extended operation to evaluate the current CTX memory consumption of the LDAP server. Suppose that ldap_ctxinfo returns the following data to the plugin:

The plugin calculates the current memory consumption based on this data (100 * 110 / 1600 = 6,875) and compares it to the 50% and 90% values specified in the -w and -c arguments, respectively. Since current consumption (6.875 %) is below the 50% warning value, the plugin returns an exit code of 0 and the following message to Nagios:

DIRX-LDAP-CTX OK - Current CTX-size = 110 MB (HWM:120)

It also returns the following performance data string to Nagios for CTX and HWM:

LDAP-Ctx=110MB;800;1440;0;1600 LDAP-Ctx-HWM=120MB;800;1440;0;1600

where:

dirxextop, Environment Variables in the DirX Directory Administration Reference.

[perl] check_dirx_dbam_preload_status.pl [-L] [-h] [-v] [-x]

Checks the status of the DBAM buffer cache preloader.

See the section Common Plugin Syntax for a description of the -L, -h, -v and -x options. These options are common to all DirX Directory Nagios plugins.

The check_dirx_dbam_preload_status plugin evaluates the status of the preloader for the DBAM buffer cache and returns a status not equal to OK if the function is still running or disabled, or if an error occurs while the plugin is processing.

Use this DirX Directory Nagios plugin to monitor whether the DBAM buffer cache has been filled correctly. Performance issues can occur if the DBAM cache is not used as expected. If the status is CRITICAL, the plugin returns a message that explains why the preload function is disabled.

When called by Nagios (or from a shell), the check_dirx_dbam_preload_status plugin operates on output returned by a call to the dsa_dbam_preload_status extended operation. This operation returns status information about the DBAM buffer cache preload status. The plugin evaluates the status and returns an exit code and a message about the result in the format described in the section Common Return Code Format.

The following table shows the result values returned by the plugin and their meanings.

In this example, the plugin runs in a shell and returns successful status about the preloader to standard output:

The output is as follows:

Environment Variables in the DirX Directory Administration Reference.

[perl] check_dirx_dbam_usage.pl -w warning_value -c critical_value [-L] [-h] [-v] [-x]

Checks the percentage of reserved space in use on DBAM devices in a DirX Directory service installation to monitor their capacity.

-w warning_value
The percentage of reserved space in use that defines the WARNING threshold for problems with DBAM device capacity. For example, a value of 50 indicates that a warning should be returned if one of the DBAM devices has reached 50% of its maximum.

-c critical_value
The percentage of reserved space in use that defines the CRITICAL threshold for problems with DBAM device capacity. For example, a value of 90 indicates that a critical message should be returned if one of the DBAM devices has reached 90% of its maximum.

See the section Common Plugin Syntax for a description of the -L, -h, -v and -x options. These options are common to all DirX Directory Nagios plugins.

The check_dirx_dbam_usage plugin evaluates the current reserved space in use on all of the logical DBAM devices configured in a DirX Directory service installation and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor the capacity of the DBAM devices in a DirX Directory service installation and take steps to extend the DBAM database if warning or critical thresholds are reported. (See Extending the Directory Database in the Disc Dimensioning Guide for details.)

When called by Nagios (or from a shell), the plugin operates on output returned from a call to the dsa_dbam_devinfo extended operation. This output consists of the current percentage of reserved space (usage and fragmentation) in use on each logical device and each attribute index-specific device and the current percentage of reserved index entries and index clusters in use. It is identical to the output returned by the dbamdevinfo command. See Example for an example of the output (see also the dbamdevinfo command in the DirX Directory Administration Reference).

The plugin compares the percentages given for each logical device and for the index entries and index clusters to the values specified in the -w and -c arguments. The warning threshold or the critical threshold is reached if one of these percentages exceeds one of these values.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current usage percentages for the evaluated logical devices, index entries and index clusters.

The plugin also returns the following performance data:

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command:

The plugin calls the dsa_dbam_info extended operation. Suppose it returns the following output to the plugin:

Because the command specifies a warning value of 50%, the plugin will return a warning status on the following percentages if at least one of the following conditions is met:

In this example, the output returned to the plugin indicates that all of the percentages are below the 50% warning value, so the plugin returns the following result description:

It also returns the following performance data:

where:

dbamdevinfo, dirxextop in the DirX Directory Administration Reference, DirX Directory Disc Dimensoning Guide.

[perl] check_dirx_dsa_get_opmode.pl [-L] [-h] [-v] [-x]

Determines the current operating mode of a DirX Directory DSA.

See the section Common Plugin Syntax for a description of the -L, -h, -v and -x options. These options are common to all DirX Directory Nagios plugins.

The check_dirx_dsa_get_opmode plugin determines operating mode of a DirX DSA and returns a status not equal to OK if the DSA is not operating in READWRITE mode or an error occurs while the plugin is processing.

Use this DirX Directory Nagios plugin to monitor the operation mode of the DSA. (For details about the operation mode of the DSA, see the dirxadm sys opmode command in the DirX Directory Administration Reference.) If the operating mode is not READWRITE, the DSA rejects update operations. This situation prevents workflows from performing successfully.

When called by Nagios (or from a shell), the check_dirx_dsa_get_opmode plugin operates on output returned by a call to the dsa_get_opmode extended operation. This operation returns the current operating mode of the DSA.

The plugin evaluates the output and returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current operating status of the DSA.

The following table shows the result values returned by the plugin and their meanings.

In this example, the plugin runs in a shell and returns successful status about the DSA operating mode to standard output:

The output is as follows:

dirxadm, dirxextop, Environment Variables in the DirX Directory Administration Reference.

[perl] check_dirx_heartbeat.pl -w warning_value -c critical_value [-s host] [-p port][ -D dn]
-W pwd [-S host] [-P port] [-h] [-v] [-x]

Verifies the responsiveness of the DirX Directory processes running in standalone and supplier (master) / consumer (shadow) DirX Directory service configurations.

-w warning_value
The number of seconds that defines the WARNING threshold for the heartbeat operation’s running time. For example, a value of 2 indicates that a WARNING result should be returned when the operation’s execution time meets or exceeds 2 seconds without completion but is still under the critical_value timeframe.

-c critical_value
The number of seconds that defines the CRITICAL threshold for the heartbeat operation’s running time. For example, a value of 4 indicates that a CRITICAL result should be returned when the operation’s execution time meets or exceeds 4 seconds without completion.

-s
The host name or IP address of the local DirX Directory service to be validated. If this option is not specified, the plugin uses the value specified in the plugin configuration file check_dirx_config.pm*. The default is *localhost.

-p port
The port on which the local LDAP server listens for incoming requests. If this option is not specified, the plugin uses the value specified in the plugin configuration file check_dirx_config.pm*. The default is *389.

-D dn
The distinguished name of the user that performs LDAP heartbeat checking operations on the plugin’s behalf and that is also the target of these operations. If this option is not specified, the plugin uses the value specified in the plugin configuration file check_dirx_config.pm*. The default is *cn=admin,o=my-company.

-W pwd
The password for the user account specified in the –D argument. If this option is not specified, the plugin uses the value specified in the plugin configuration file check_dirx_config.pm*. The default is *dirx.

-S host
The host name or IP address of the remote DirX Directory service to be validated.

-P port
The port on which the remote LDAP server listens for incoming requests. The default is 389.

See the section Common Plugin Syntax for a description of the -L, -h, -v and -x options. These options are common to all DirX Directory Nagios plugins.

The check_dirx_heartbeat plugin determines the responsiveness of a local standalone or supplier DirX Directory service instance (DSA and LDAP server) and optionally of a remote consumer instance and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing.

Use this DirX Directory Nagios plugin to monitor the responsiveness of local update operations and also of data replication in supplier/consumer configurations.

When called by Nagios (or from a shell), the plugin performs an LDAP bind to the DirX Directory service specified in the -s option (or in the configuration file, if -s is not specified) as the user specified in the -D option (or in the configuration file, if this option is not used) and then writes a timestamp to this entry’s description attribute. If the -S and -P options for a remote DirX Directory service instance are specified, the plugin subsequently performs an LDAP bind to the remote instance and then compares the timestamp of the (replicated) user entry’s description attribute with the value on the master to verify that replication has occurred.

The plugin compares the elapsed time of the bind and update operation against the number of seconds specified as warning and critical values. The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format.

The specified user entry must have a description attribute. By means of the access control the user must have privileges for updating and reading its own description attribute. f replication is also to be checked, the specified user entry must reside in the replicated area on the supplier instance.

Specifying values for -D, -W and -p on the plugin command line overrides any values for these items specified in the configuration file check_dirx_config.pm.

Note that the check_dirx_heartbeat plugin requires the perl-ldap distribution to be installed on each DirX Directory service to be monitored. See the ReadMe.txt file in the 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.

The following table shows the result values returned by the plugin and their meanings.

The output is as follows:

The output is as follows:

dirxadm in the DirX Directory Administration Reference

[perl] check_dirx_ldap_current.pl -w warning_value -c critical_value -k key_name [-d] [-L] [-h] [-v] [-x]

Monitors the value of a selected absolute counter or delta counter in the LDAP MIB current table.

-w warning_value
The value to be used as a warning threshold for determining the status of the monitored counter. A counter 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 as a relative percentage value, depending on the counter specified in the -k argument.

-c critical_value
The value to be used as a critical threshold for determining the status of the monitored counter. A counter 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 relative percentage value, depending on the counter specified in the -k argument.

-k key_name
The absolute or delta counter to be monitored, where key_name is one of the counters or delta counters selected from the following table:

Note that key_name is case sensitive.

Note: It is not recommended to monitor the delta counters without a deeper understanding as they would show the changes of changes.

-d
The key_name specified in the -k argument is to be evaluated as a delta counter. When this option is not specified, the plugin evaluates key_name as an absolute counter. As the non-delta counters from this “current” table are floating counters (and not incrementing counters like in the “total” table) it is recommended to use -d for the non-delta counters (for example, OpStackSize or PoolThreadsRunning),

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_ldap_current plugin evaluates the value of a selected absolute or delta counter in the LDAP MIB current table and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor one or more counters in the LDAP server’s MIB current table. You can only specify one counter on the plugin command line (with the -k argument). To monitor multiple LDAP server counters, set up separate invocations of the plugin for each counter to be monitored, and then specify each command line as a separate service to Nagios. See the Nagios documentation for details.

Use the -k key_name argument to select a counter. Select an absolute counter (see the Counter Key Name column in the table above for a list) to evaluate the absolute number of occurrences at the time of the call; for example, specify LdapConnections in key_name to evaluate the current number of open LDAP connections.

Select a delta counter (see the Delta Counter Key Name column in the table above for a list) to evaluate the difference in the number of occurrences since the last call to the plugin with the same key_name value; for example, specify LdapConnectionsDelta in key_name to evaluate the change of the number of open LDAP connections established since the last call to the plugin with LdapConnectionsDelta key_name. Note that many of the delta counters increment and decrement over time; as a result, it is possible that a delta counter can have a negative value.

For the LDAP MIB current table, absolute counters are usually more interesting to monitor than delta counters, because they can provide an indication of current server load; for example, the current number of LDAP binds or the current number of idle pool threads.

Use -d to both, for the non-delta as well as for the delta counters. This is necessary as even the non-deltas are non-linear-incrementing counters (their value can decrease or get negative). By supplying -d this counter-property is indicated for the Nagios database to be handled differently than continuous incrementing counters.

Use the -w and -c arguments to specify warning and critical thresholds. For most counters, criticality increases with increasing counter values; LdapConnections is an example. For these counters, call the plugin with a -w threshold that is less than the –c threshold. For some counters, criticality increases with decreasing counter values; PoolThreadsIdle is an example. For these counters, call the plugin with a -w threshold that is greater than the -c threshold.

Note that the plugin does not check whether the ranges specified in the -w and -c arguments make sense for the selected counter; that is, whether the values indicate absolute values or percentages. As a result, make sure you supply meaningful data to these arguments when building your plugin services.

When called by Nagios (or from a shell), the check_dirx_ldap_current plugin operates on output returned from a call to the ldap_mib_current_tevd extended operation. This operation returns all counters from the LDAP current MIB table, and the plugin evaluates the value of the specified key (-k argument). The plugin evaluates whether this value exceeds the warning or critical values specified in the -w and -c arguments and returns an exit code and a message about the result in the format described in the section Common Return Code Format. The message includes the current value of the selected counter.

The plugin also returns the following performance data to Nagios for storage:

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command to evaluate the current number of open LDAP connections:

If there are currently 120 open LDAP connections, the plugin returns the exit code 1 for WARNING and the following string containing a readable message followed by the performance data:

In this example, the performance data consists of the string:

LDAP-LdapConnections=120;100;200;0;0

Where the substrings have the following meanings:

check_dirx_ldap_total in DirX Directory LDAP Extended Operations, dirxcp, dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_ldap_duration.pl -w warning_value -c critical_value -C range -T op_group _
_[-L] [-h] [-v] [-x]

Monitors the duration of LDAP client calls.

-w warning_value
The percentage that defines the WARNING threshold for the number of long-duration operations. For example, a value of 5 indicates that if 5% the LDAP operations selected in the -T option run longer than the duration range selected in the -C option, a WARNING result should be returned.

-c critical_value
The percentage that defines the CRITICAL threshold for the number of long-duration operations. For example, a value of 10 indicates that if 10% of the LDAP operations selected in the -T option run longer than the duration range selected in the -C option, a CRITICAL result should be returned.

-C range
The duration range to be monitored. Supply one of the following values:

-T op_group
The group of operations to be checked for duration. Supply one of the following keywords:

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_ldap_duration plugin evaluates the percentage of the selected LDAP operation group whose runtime falls into a selected timeframe and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing. The plugin also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor the frequency of long-duration LDAP operations for three groups of operations: bind and unbind operations, retrieval operations and update operations. In a well-configured and dimensioned DirX Directory service environment, these operations typically complete in a few milliseconds. However, it’s also easy to initiate operations that can run for some time; for example, when initiating a search with a filter (objectclass=) and all attributes requested. As long as long-duration operations occur infrequently and for well-known reasons (for example, during workflow scenarios), their occurrence is not a problem. However, if they occur more frequently, it can indicate that something is wrong or misconfigured; for example, that indexes are missing or the hardware is overloaded. The *check_dirx_ldap_duration plugin allows you to use Nagios to monitor whether more long-duration operations occur than expected.

Use the -T argument to specify the group of operations to be monitored for duration: bind and unbind operations, search and compare operations, or add, update and delete operations. Note that you can only specify one group on the plugin command line per call. To monitor multiple LDAP operation groups, set up separate invocations of the plugin for each group to be monitored, and then specify each command line as a separate service to Nagios. See the Nagios documentation for details. Note that you cannot monitor the duration of a single LDAP operation with this plugin, only the specified groups of operations.

Use the -C argument to specify the duration range to be monitored for the operation group selected with the -T argument. To facilitate tracking and identification of long-duration operations, the LDAP server separates operation duration into 6 incremental ranges (or "classes") in milliseconds, from shortest runtime (0 to 10 milliseconds) to longest runtime (greater than 100 seconds). Each range increases the runtime interval by a factor of 10. The ranges are pre-defined and currently cannot be changed. The LDAP server maintains a counter for each range and increments the counter for the range that corresponds to the duration runtime of each LDAP operation. This data is kept in the LDAP server’s LDAP MIB total table.

When called by Nagios (or from a shell), the plugin operates on the duration data retrieved from the LDAP MIB total table by a call to the ldap_mib_total_tevd extended operation. This operation returns the duration data for all operation groups and all ranges. The plugin reads the current "accumulated duration percentage" returned in the output for the group of LDAP operations selected with the -T option and for the duration range selected with the -C option. The accumulated percentage duration is the percentage of LDAP operations whose duration fell into this range or one of the ranges above it; that is it is the percentage of operations with a duration of at least the lower boundary of the range specified by –C option. The plugin checks whether the percentage returned in the output is at or above the percentages given in the -w and -c arguments.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current value of the accumulated duration percentage.

It also returns the accumulated duration percentage as performance data to Nagios.

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command:

check_dirx_ldap_duration.pl -w 5 -c 10 –T Dur_Retr –C 4

This command instructs the plugin to monitor retrieval operations whether they exceed the duration range of 1 to 10 seconds and evaluates how many operations run longer than 1 second. The plugin calls the ldap_mib_total_tevd extended operation. Suppose the operation returns an accumulated duration percentage of 1% for range 4. This value indicates that 1% of the LDAP retrieval operations ran longer than 1 second. Since this runtime percentage is below the 5% warning value (less than 5% of retrieval operations ran longer than 1 second), the plugin returns an exit code of 0 for OK and the following string containing a readable message followed by the performance data:

DIRX-LDAP-Dur_Retr OK - Currently 1% of operations >1sec |Dur_Retr_Class4=1

check_dirx_ldap_resultsize in DirX Directory LDAP Extended Operations, dirxcp, dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_ldap_resultsize.pl -w warning_value -c critical_value -C range -T data_type _
_[-L] [-h] [-v] [-x]

Monitors the size of search results returned by LDAP searches.

-w warning_value
The accumulated percentage value that defines the WARNING threshold for the frequency of large search results for a given range.

-c critical_value
The accumulated percentage value that defines the CRITICAL threshold for the frequency of large search results.

-C range
The search size range to be monitored. Supply one of the following values:

-T data_type
The type of data to be monitored for size. Supply the keyword:

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_ldap_resultsize plugin evaluates the percentage of LDAP search operations whose result sizes fall into a selected range and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing. The plugin also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor the frequency of large LDAP search results. Search result sizes that grow larger and larger over time can have implications for efficient DirX Directory service operation: large search results require a lot of memory, use CPU resources, produce a high level of disk and network I/O operations and occupy worker threads for long periods of time. Symptoms of these problems begin with reduced service responsiveness and end with service crashes when resources are exhausted. The check_dirx_ldap_resultsize plugin allows you to use Nagios to detect and respond to unexpected huge data transfers.

Use the -T argument to specify the type of data to be monitored for size. Note that the size of LDAP search results is currently the only type of data the plugin can monitor.

Use the -C argument to specify the size range to be monitored for the data type selected with the -T argument (currently LDAP search results). To facilitate tracking and identification of very large search results, the DirX Directory LDAP server separates the possible search sizes that can be returned by LDAP operations into six incremental ranges in bytes, from smallest (0 to 10 kilobytes) to largest (greater than 10 megabytes). Each range increases the size interval by a factor of 10. The ranges are pre-defined and currently cannot be changed. The LDAP server maintains a counter for each range and increments the counter for the range that corresponds to the size of the results returned by each LDAP operation. The search size data is kept in the LDAP server’s LDAP MIB total table.

When called by Nagios (or from a shell), the check_dirx_ldap_resultsize plugin operates on LDAP server search size data returned from the LDAP MIB total table by a call to the ldap_mib_total_tevd extended operation. This operation returns the size data for all data types and all ranges. The plugin reads the current "accumulated search size percentage" returned in the output for the size range specified in the -C argument. The accumulated search size percentage is the sum of the percentages for this range and all of the ranges above it. It shows the percentage of search result sizes that fell into this range or higher. The plugin evaluates this value against the warning and critical percentages specified in the -w and -c arguments.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current accumulated search size percentage for the selected range.

The plugin also returns the current accumulated percentage for the selected range as performance data to Nagios.

The following table shows the result values returned by the plugin and their meanings.

Given the following command line:

The plugin calls the ldap_mib_total_tevd extended operation. Suppose the operation returns an accumulated search size percentage of 2%. This value indicates that 2% of the LDAP searches returned sizes larger than 1MB. Since this percentage is below the 5% warning value (less than 5% of LDAP searches returned sizes larger than 1MB), the plugin returns an exit code of 0 for OK and the following string containing a readable message followed by the performance data:

check_dirx_ldap_duration in DirX Directory LDAP Extended Operations, dirxcp, dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_ldap_totals.pl –w warning_value –c critical_value –k key_name [-d] [-L] [-h] [-v] [-x]

Monitors the value of a selected absolute counter or delta counter in the LDAP MIB total table.

-w warning_value
The value to be used as a warning threshold for determining the status of the monitored counter. A counter 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 counter specified in the –k argument.

-c critical_value
The value to be used as a critical threshold for determining the status of the monitored counter. A counter 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 relative percentage value, depending on the counter specified in the –k argument.

-k key_name
The absolute or delta counter to be monitored, where key_name is one of the counters or delta counter keys selected from the following table:

Note that key_name is case-sensitive.

-d
The key_name specified in the -k argument is to be evaluated as a delta counter. When this option is not specified, the plugin evaluates key_name as an absolute counter.

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_ldap_totals plugin evaluates the value of a selected absolute or delta counter in the LDAP MIB total table and returns a status not equal to OK if either the warning or critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor one or more counters in the LDAP server’s MIB total table. You can only specify one counter on the plugin command line (with the -k argument). To monitor multiple LDAP server counters, set up separate invocations of the plugin for each counter to be monitored, and then specify each command line as a separate service to Nagios. See the Nagios documentation for details.

Use the -k key_name argument to select a counter. Select an absolute counter (see the Counter Key Name column in the table above for a list) to evaluate the number of occurrences since LDAP server startup time; for example, specify BindErrors in key_name to evaluate the number of erroneous bind operations performed since LDAP server startup time.

Select a delta counter (see the Delta Counter Key Name column in the table above for a list) to evaluate the number of occurrences since the last call to the plugin with the same key_name value; for example, specify BindErrorsDelta in key_name to evaluate the number of erroneous bind operations performed since the last call to the plugin with BindErrorsDelta key_name.

For the LDAP MIB total table, delta counters are usually more interesting to monitor than absolute counters, because the absolute numbers for operations or errors always increase over an LDAP server process’s lifetime. However, absolute values can provide an indication of server load.

Note that the CacheHitRatio counter increments and decrements over time, as a result, it is possible that its delta counter can have a negative value.

Use the -d option to indicate to Nagios (in the returned performance data string) that the counter specified in the -k option is a delta counter whose value should be interpreted as an incremental counter; for example, SearchesDelta.

When the -d option is not specified, for example with the -k option set to Searches, Nagios interprets the counter value as absolute and automatically calculates the deltas between collected counter values in subsequent graphical displays.

Use the -w and -c arguments to specify warning and critical thresholds. For most counters, criticality increases with increasing counter values; BindErrors is an example. For these counters, call the plugin with a -w threshold that is less than the -c threshold. For some counters, criticality increases with decreasing counter values; CacheHitRatio is an example. For these counters, call the plugin with a -w threshold that is greater than the –c threshold.

Note that the time period between delta values (change in value since the last plugin query) is equal to the frequency of Nagios calls to the plugin. When monitoring a delta counter, you need to know what this frequency is in order to establish meaningful warning and critical values for the counter. For example, suppose you want Nagios to monitor the number of searches and notify the administrator if too many occur within a certain time period. If Nagios calls the plugin every minute, you can determine warning and critical levels for the number of searches that occur within a minute; for example, 500 searches every minute for warning, and 1,000 searches every minute for critical, with the delta counter SearchesDelta as the counter to be monitored every minute.

Note that the plugin does not check whether the ranges specified in the -w and -c arguments make sense for the selected counter; that is, whether the values indicate absolute values or percentages. As a result, make sure you supply meaningful data to these arguments when building your plugin services.

When called by Nagios (or from a shell), the check_dirx_ldap_totals plugin operates on output returned from a call to the ldap_mib_total_tevd extended operation. This operation returns the value of the counter specified in the -k argument. The plugin evaluates whether this value exceeds the warning or critical values specified in the -w and -c arguments and then returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current value of the selected counter.

The plugin also returns the following performance data to Nagios for storage:

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command to examine the SearchesDelta counter:

check_dirx_ldap_totals.pl –w 100 –c 200 –d –k SearchesDelta

If there were 23 LDAP search operations since the last call, the plugin returns the exit code 0 for OK and the following string containing a readable message followed by the performance data:

DIRX-LDAP-SearchesDelta OK – Current SearchesDelta=23|LDAP SearchesDelta=23;100;200;0;0

In this example, the returned performance data consists of the string:

LDAP SearchesDelta=23;100;200;0;0

The meaning of the substrings is as follows:

check_dirx_ldap_current in DirX Directory LDAP Extended Operations, dirxcp, dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_no_of_fds.pl -w warning_value -c critical_value -T DSA | LDAP [-L] [-h] [-v] [-x]

Checks the file descriptor or handle consumption of a DSA or an LDAP server.

-w warning_value
The number of file descriptors (Linux) or handles (Windows) in use that defines the WARNING threshold for file descriptor/handle consumption. For example, a value of 50 indicates that when 50 file descriptors/handles are in use, a WARNING result should be returned.

-c critical_value
The number of file descriptors (Linux) or handles (Windows) in use that defines the CRITICAL threshold for file descriptor/handle consumption. For example, a value of 90 indicates that when 90 file descriptors/handles are in use, a CRITICAL result should be returned.

-T DSA | LDAP
The target server to monitor. Specify DSA to monitor a DirX Directory DSA. Specify LDAP to monitor an LDAP server.

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_no_of_fds plugin determines the number of file descriptors ("handles" on Windows) in use by the LDAP server or the DSA in a DirX Directory service installation and returns a status not equal to OK if either the warning threshold or the critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor file descriptor usage on a DirX Directory service host. File descriptors represent a critical resource for DirX Directory service installations. Typically, there are limits on the number of descriptors that a single process can establish. While Windows does not describe an explicit limit for handles (the limit on Windows is a specific amount of memory that the system provides for allocating descriptors), Linux systems like Linux only provide a limited number, displayable via the ulimit -n command. For a normal DirX Directory installation on Linux, the limit is 1024.

Because sockets are descriptors, each LDAP connection can increase the number of file descriptors consumed by two in the LDAP server: one socket for the LDAP connection to the client and one more for the connection to the DSA. In the DSA, one request can also consume multiple sockets. Once the last descriptor is consumed, problems start to occur, from problems with external operations, such as LDAP clients no longer being able to connect to problems with internal operations, such as audit writing or shadowing journal writing. The check_dirx_no_of_fds plugin allows you to use Nagios to detect and respond to excessive file descriptor consumption before this resource is completely exhausted.

When called by Nagios (or from a shell), the check_dirx_no_of_fds plugin operates on output returned from a call to the extended operation ldap_no_of_fds (-T LDAP) or dsa_no_of_fds (-T DSA).

On Windows, the plugin calls the Windows API function GetProcessHandleCount() to evaluate handle consumption.

On Linux, the plugin executes the command /proc/*server_pid/fd*, where server_pid is the local DSA or LDAP server process identifier.

The plugin compares the current number of handles/file descriptors in use to the values specified in the -w and -c arguments.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format.

It also returns the current number of descriptors in use as performance data.

Note that the plugin will not be able to run on Linux if the LDAP server runs as a child of an s-Bit watchdog (dirxdsas). The reason for this limitation is that the information is retrieved from /proc/*pid/fd*, which only receives root-read permissions. When the LDAP server is started by the
s-Bit dirxdsas watchdog, the /proc/*pid is created under *root. However, after the LDAP server Directory binds to the 389/636 ports, it switches its effective user ID to the user ID of the account of the DirX Directory installation. This user is subsequently prohibited from reading the /proc information when the extended operation for the number of file descriptors is invoked later on by the Nagios plugin. The DSA does not have this problem because it is started as the user ID of the account of the DirX Directory installation and never changes its user ID.

The following table shows the result values returned by the plugin and their meanings.

In this example, given the plugin command-line:

check_dirx_no_of_fds –w 500 –c 2000 –T LDAP

The plugin returns the following return value string to Nagios:

DIRX-DSA-NO-FILE-DESCRIPTORS OK - 353 number of file descriptors in use

It returns the following performance data string to Nagios:

DIRX-DSA-NO-FILE-DESCRIPTORS=353;500;2000;0;10000

where:

dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_paging.pl -w warning_value -c critical_value [-p] [-L] [-h] [-v] [-x]

Checks the number of active paged search operations.

-w warning_value
The number of active paged search operations that define the WARNING threshold. For example, 40.

-c critical_value
The number of active search operations that defines the CRITICAL threshold. For example, 60.

-p
Directs the plugin to treat the values specified for -w and -c as percentage values rather than absolute values.

See the section Common Plugin Syntax for a description of the options used in this plugin.

The check_dirx_paging plugin determines the number of currently active paged search operations in the DSA. A paged search operation consumes resources until:

Releasing the resources that a paged search operation consumes also depends on the settings of the paging policy for maximum number of paged search operations, timeout and maximum amount of memory. (See Paging Policy in DirX Directory DSA Operational Attributes in the DirX Directory Administration Reference for details.)

This plugin counts the number of paged search operations at the time of the call and returns a status not equal to OK if either the warning threshold or the critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor the proper administration of the maximum number of paged search operations (component MAXNUM) of the paging policy.

When called by Nagios (or from a shell), the plugin operates on output returned from a call to the dsa_paging_info extended operation. This output returns information about paged search operations, especially the maximum number of paged search operations and the current number of paged search operations.

The plugin compares these values to the values specified in the -w and -c arguments. The warning threshold or the critical threshold is reached if the number of current search operations exceeds one of these values. If -p is specified, the plugin treats the thresholds as percentage values; for example, -w 5 reports a warning if more than 5 incomplete paged search operations are detected and -w 5 -p issues a warning if more than 5% of the maximum number of paged search operations are detected.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format.

The plugin also returns the following performance data to Nagios for storage:

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin command:

perl check_dirx_paging.pl -w 40 -c 60

The plugin calls the dsa_paging_info extended operation. From the output of this extended operation, the plugin determines that 62 paged search operations are active, which is more than the specified critical value of 60. It returns the exit code 2 for CRITICAL and the following message:

It returns the following performance data string to Nagios:

where:

dirxextop in the DirX Directory Administration Reference.

[perl] check_dirx_server_files.pl –w warning_value –c critical_value [-L] [-h] [-v] [-x]

Checks the number of files in the server/ldif and server/supdate subdirectories to monitor shadowing and LDIF agreement administration.

-w warning_value
The number of files present in each subdirectory that defines the WARNING threshold for problems with LDIF and shadowing agreement administration. For example, 10000.

-c critical_value
The number of files present in each subdirectory that defines the CRITICAL threshold for problems with LDIF and shadowing agreement administration. For example, 100000.

See the section Common Plugin Syntax for a description of the -L, -v, -h and -x options. These options are common to all Nagios plugins.

The check_dirx_server_files plugin determines the number of files below the server/ldif and server/supdate subdirectories in a DirX Directory service installation and returns a status not equal to OK if either the warning threshold or the critical threshold is reached or an error occurs while the plugin is processing. It also generates performance data in addition to its status message.

Use this DirX Directory Nagios plugin to monitor the proper administration of shadowing agreements and LDIF agreements. If these agreements have not been administered correctly, a huge number of files can accumulate below the server/ldif and server/supdate subdirectories. Using this plugin allows for timely identification of shadowing and LDIF administration problems so that administrative steps can be taken to correct them before the file system runs out of free space.

When called by Nagios (or from a shell), the plugin operates on output returned from a call to the dsa_server_files extended operation. This output consists of a set of counters whose values indicate the current number of files contained in specific subdirectories below the server subdirectory. For each subdirectory in the list, the output provides the number of immediate subordinate files and subdirectories. See Example for an example of the output.

The plugin only evaluates the current number of files in the server/ldif and server/supdate subdirectories. For the server/supdate subdirectory, it evaluates the number of files recursively; that is, it counts the number of files in all of the subdirectories below server/supdate.

The plugin compares these values to the values specified in the -w and -c arguments. The warning threshold or the critical threshold is reached if the number of files in either server/ldif or server/supdate exceeds one of these values.

The plugin returns an exit code and a message about the result in the format described in the section Common Return Code Format. The result description includes the current values of the counters for the two evaluated subdirectories.

The plugin also returns the following performance data to Nagios for storage:

The following table shows the result values returned by the plugin and their meanings.

Given the following plugin arguments:

check_dirx_server_files.pl –w 10000 –c 100000

The plugin calls the dsa_server_files extended operation. Suppose the dsa_server_files extended operation returns the following output to the plugin:

From this output, the plugin determines that the server/ldif directory contains 16,687 files, which is more than the specified warning value of 10,000. It returns the exit code 1 for WARNING and the following message:

It also returns the following performance data:

where:

dirxextop in the DirX Directory Administration Reference.