LDAP Monitor

The LDAP monitor tests the operation of Lightweight Directory Access Protocol (LDAP) servers.

The following table lists the LDAP monitor files.

Table 1. LDAP monitor files 
Monitor files Name or location
Monitor executable nco_m_ldap
Properties file $ISHOME/etc/props/ldap.props
Rules file $ISHOME/etc/rules/ldap.rules
Log file $ISHOME/log/ldap.log
Guidelines for configuring LDAP monitor

The LDAP monitor tests LDAP services by connecting to an LDAP server and attempting to locate a specific entry. If the server succeeds in locating the entry, it returns the contents of the entry to the monitor. The LDAP monitor can use SSL to authenticate and connect to the LDAP server.

To configure the LDAP monitor, it is necessary to understand how the LDAP protocol and the monitored directory service work. LDAP is an Internet Protocol for accessing and managing Directory Services. A directory service is a distributed database application. A directory consists of entries. For example, a directory might contain entries that relate to an organization's employees or resources. Each entry contains a set of attributes, for example the entries in a directory of employees might contain an employee's name, telephone number and address.

Individual Directory Services can be constructed differently, so the monitoring procedure can also differ.

LDAP versions
The LDAP monitor supports both version 2 and 3 of LDAP. By default, the monitor attempts to connect to the target LDAP server that uses version 3, then automatically falls back to version 2 if the attempt fails. You can force the monitor to always use version 2 by setting the NOLDAPV3 property.
Example directory service
This example directory service stores the personal details of all employees. The directory is divided into countries and then into departments. Employees and their attributes are stored under each department.

Directory hierarchy example

The Directory hierarchy example image shows an extract from an example directory. This figure shows a directory structure. At the apex level is root. The two subdirectories represent countries and are labeled UK and US. The UK subdirectory is further divided into three other subdirectories representing the organization units. They are labeled as Development, Accounting, and Help Desk. Within the Development organization unit there are two subdirectories, for common names which are Shirley Clee and Hamish Wednesday.

Entities are referenced by their distinguished names. A distinguished name is the route to the entity. For example, the distinguished names of the accounting department and Hamish Wednesday would be:

dn="ou=accounting, c=UK"
dn="cn=Hamish Wednesday, ou=Development, c=UK"

The entry for each employee has multiple attributes. For example, the entry for Hamish Wednesday contains the following details.

cn: Hamish Wednesday
uid: ham
mail: HWednesday@development.mycompany.com
telephoneNumber: 88 88 55 44

Each entity in the directory hierarchy can be protected by a username (in LDAP it is a distinguished name) and password. The monitor uses this username and password to access the LDAP server.

When the monitor accesses the server, it indicates where in the directory hierarchy the search for the target entity begins. This is specified in the searchBase field as a distinguished name. For example, the search could begin at the department level:

ou=Accounting, c=UK
Note: The entities that make up a distinguished name are in reverse order. That is, they start at the lowest point in the hierarchy, then list each preceding entity.

The target entity is passed to the server in the filter field. This field contains an attribute of the target entity. For example, to search for Hamish Wednesday's entity, the filter field might contain:


The LDAP server uses the fields that are supplied by the monitor to search for the target entity. The result of the search is returned to the monitor.

If the search is successful, the server also returns the attributes of the target entity. The monitor converts it into elements whose names are created dynamically. For example, the monitor would convert the entry for Hamish Wednesday into:

$dnMatched = "cn=Hamish Wednesday, ou=Development, c=UK"
$cn = "Hamish Wednesday"
$uid = "ham"
$mail = "HWednesday@development.mycompany.com"
$telephoneNumber = "88 88 55 44"
LDAP Authentication
SSL LDAP Server Authentication relies on public-private key certificates, signed by certificate authorities, such as Verisign and Thawte. For SSL authentication, the LDAP monitor uses the Netscape cert7db database of public certificates to verify LDAP server certificate signatures issued by certificate authorities.

If you are using certificates that are signed by a certificate authority that is recognized by Netscape, such as Verisign or Thawte, the LDAP monitor recognizes them automatically. If you are using certificates that are signed by your organization or by an organization not in the Netscape database, you must add them to the cert7db database.

Use the certutil utility, available from Netscape to add your certificates to the database. The cert7db database for the LDAP monitor is in the file $ISHOME/certificates/cert7.db.

To monitor LDAP servers that are secured by SSL or TLS encryption, set the environment variables as described in the following table:
Table 2. Environment variables required to monitor secure LDAP servers
Variable Description Setting
LDAPTLS_CACERT Specifies the file that contains the CA certificates File containing server certificate.

For example, cacert.pem.

LDAPTLS_REQCERT Specifies the checks to perform on a server certificate Select from never|allow|try|demand.
For more information, see http://www.openldap.org.

Properties that are specific to the LDAP monitor are described in the following table:

Table 3. LDAP monitor properties options 

Property name

Property parameter



Force the monitor to use LDAP v2 instead of LDAP v3.

0 - use LDAP v3

1 - use LDAP v2

Cipher suites
The SSLCipherSuite property specifies the cipher suite that is used by the LDAP monitor. For more information about SSL settings, see SSL setting in Internet Service Monitoring.
Configuring LDAP monitor service tests
Use the LDAP monitor configuration parameters to define service tests.

When you configure the monitor, default values are shown for the timeout parameter is 30 seconds and poll interval parameter is 300 seconds. Other defaults that are listed in the table are not shown during configuration but are applied when the configuration details are saved if value is not specified.

Following table describes the LDAP monitor configurations:

Table 4. LDAP monitor configuration
Field Description
server The name or IP address of the LDAP server to be monitored. For example, ldap.mycompany.in.
searchbase The distinguished name of the location from which to start the search. For example, ou=Accounting, c=UK.
filter An attribute of the target entity to search for. For example, (uid=ham).
description A text field for providing descriptive information on the element. For example, LDAP monitor.
Active Selects whether the profile element is to be activated after it is created. For example, Selected.
port The port on the LDAP server to connect to. You must specify the SSL port if you are using SSL authentication.

Default: 389

username The username used to log in to the directory service. The format of the username depends on the setting of Authentication Type.

You can specify a Windows domain, that is, DOMAIN\username. For example, jbloggs.

password The password used to log in to the directory service, if necessary. For example, secret9.
authenticationtype The LDAP authentication method to use:
  • SIMPLE (anonymous or plain text password)
Note: SASL-DIGEST-MD5 authentication is not available on Linux® operating system.

If you set the authenticationtype to SIMPLE or SSL-SIMPLE, enter the username in distinguished name format. If you set the authenticationtype to SASL-DIGEST-MD5, enter the username as SASL bind-ids. To log in to the LDAP server as an anonymous user, set the authenticationtype to SIMPLE and leave the username and password fields blank.

Default: SIMPLE

saslrealm The authentication realm for the LDAP server; usually the fully qualified domain name of the server. If you want to share passwords between multiple systems, you might use a domain name. For example, mycompany.com.
timeout The time, in seconds, to wait for the server to respond.

Default: 30

poll The time, in seconds, between each poll.

Default: 300

failureretests The number of times to retest before failure is indicated.

Default: 0

retestinterval The time, in seconds, to wait between each failure retest.

Default: 10

Service level classifications
Available service level classification options for the LDAP monitor are:
In service level classifications:
  • Specify extra service level classifications by manually entering the name of the monitor element. The name must match the name that is shown for the element in the Monitor elements section.
  • message can be any message that is forwarded in the $message element to IBM® Application Performance Management server if used in any widget. For a list of possible values, see Status messages.
  • The operand is a string or a positive number.
Monitor elements
In addition to the test results common to all elements, the LDAP monitor generates a set of test results that contains data specific to LDAP service tests.

The following table lists the additional elements for the LDAP monitor.

Table 5. LDAP monitor elements 




The type of user authentication method required by the LDAP server (Standard or CRAM-MD5).



The time taken to connect to the LDAP server.



The distinguished name used to log in to the directory service.


The entity matched in the search.



The attribute used to locate the target entity.



The time taken to initialize the LDAP client.



The port on the LDAP server to which the monitor is connected.


The SASL realm that you specified after new LDAP element is added.



The distinguished name of the entity from which the search was started.



The time taken to complete the search.

Status messages
The LDAP monitor provides status messages in the ResultMessage attribute when using IBM Application Performance Management. These messages indicate the result of the test.

The following table describes the LDAP status messages.

Table 6. LDAP monitor status messages



Search successful

The request succeeded.

Search failed

The request failed

No match

The server might not find a matching entry in the search criteria.

Connection timed out

The connection succeeded, but then the server stopped responding.

Initialisation failed - an unrecognised authentication type was specified

Occurs if an authentication type is used that the LDAP monitor does not support.

Client initialisation failed

Initialization of the LDAP structures failed because of inadequate memory.

Bind (authentication) failed

The server that is waiting for the bind to complete is timed out.

SASL bind is not possible because server does not support LDAPv3

The server must support LDAPv3 to create an SASL bind.

SASL bind is not possible because one of 'bind_id' (username), password or sasl_realm is blank

In order for a bind to occur, all authentication fields must have a value. Therefore, an SASL bind is not possible if the user is logged in anonymously (in plain text) by using the SIMPLE authentication type.

SASL bind error

The reason for SASL bind failure cannot be identified.

SASL bind authorisation error

The SASL bind failed because the authorization credentials were incorrect.