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:

(uid=ham)

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

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

Table 3. LDAP monitor properties options
Property name	Property parameter	Description
NOLDAPV3	0\|1	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) SSL-SIMPLE SASL-DIGEST-MD5 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:

totalTime
connectTime
searchTime
initTime
dnMatched
message

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
Element	Description
$authentication	The type of user authentication method required by the LDAP server (Standard or CRAM-MD5).
$connectTime* (ConnectTime)	The time taken to connect to the LDAP server.
$distinguishedName* (UserName)	The distinguished name used to log in to the directory service.
$dnMatched	The entity matched in the search.
$filter* (SrchFilter)	The attribute used to locate the target entity.
$initTime* (InitTime)	The time taken to initialize the LDAP client.
$port* (Port)	The port on the LDAP server to which the monitor is connected.
$saslRealm	The SASL realm that you specified after new LDAP element is added.
$searchBase* (SearchBase)	The distinguished name of the entity from which the search was started.
$searchTime* (SearchTime)	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
Message	Description
`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.