How do I perform a heartbeat check against DS (All versions)?

Last updated Jan 12, 2023

The purpose of this article is to provide information on performing a heartbeat check against DS. A heartbeat check allows you to perform a simple health check on the server to ensure it is up and running.

3 readers recommend this article

Overview

DS 6.5 and later servers provide health status checks for anonymous requests over HTTP and LDAP. This allows a remote application to check that a server is alive. See HTTP-Based Monitoring and LDAP-Based Monitoring for further information.

In all versions, you can perform a simple health check using heartbeat connections.

Heartbeat connections

If your load balancer or application is capable of using a heartbeat connection to check if DS is online and responding, use of a proper LDAP connection is key.

A proper heartbeat check should progress as follows to fully verify the status of the DS server:

CONNECT -> BIND -> SEARCH -> UNBIND -> DISCONNECT

CONNECT -> BIND -> UNBIND -> DISCONNECT

Caution

It is important to disconnect again, else the heartbeat check can remain open and consume server resources.

Performing a heartbeat check

You can use a command such as the following to connect, bind, issue a base (scope) level search on the baseDN of "", unbind and finally disconnect:

DS 7.1 and later: $ ./ldapsearch --hostname localhost --port 1636 --bindDN uid=admin --bindPassword password --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --baseDN "" --searchScope base "(objectClass=*)" 1.1 dn:
DS 7: $ ./ldapsearch --hostname localhost --port 1636 --bindDN uid=admin --bindPassword password --useSsl --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --baseDN "" --searchScope base "(objectClass=*)" 1.1 dn:
DS 6.x: $ ./ldapsearch --hostname localhost --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --useSsl --trustAll --baseDN "" --searchScope base "(objectClass=*)" 1.1 dn:

Replacing uid=admin or "cn=Directory Manager" with the bind DN of the account used to bind to the Configuration store in AM if different.

The results of the search operation show "dn:" (only). This is expected as the LDAP request attribute "1.1." returns the distinguished name only. In this case, you are searching the "rootDSE" and the expected dn: is "null".

An example entry seen in the access logs for a successful heartbeat check is shown below:{"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"CONNECT","connId":2},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS"},"timestamp":"2018-03-15T16:44:49.400Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-1"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"BIND","connId":2,"msgId":1,"version":"3","dn":"uid=admin","authType":"SIMPLE"},"transactionId":"5009191b-a09a-4c7f-84cd-e240b2810a67-2","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":3,"elapsedTimeUnits":"MILLISECONDS"},"userId":"uid-admin","timestamp":"2021-0315T16:44:49.687Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-4"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"SEARCH","connId":2,"msgId":2,"dn":"","scope":"base","filter":"(objectClass=*)","attrs":["1.1"]},"transactionId":"5009191b-a09a-4c7f-84cd-e240b2810a67-5","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":1,"elapsedTimeUnits":"MILLISECONDS","nentries":1},"timestamp":"2021-03-15T16:44:49.717Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-7"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"UNBIND","connId":2,"msgId":3},"transactionId":"5009191b-a09a-4c7f-84cd-e240b2810a67-8","timestamp":"2018-03-15T16:44:49.729Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-10"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"DISCONNECT","connId":2},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS","reason":"Client Unbind"},"timestamp":"2018-03-15T16:44:49.734Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-12"}

Alternately, if your application can perform a Connect with a Bind only, this is a viable alternative: {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"CONNECT","connId":2},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS"},"timestamp":"2018-03-15T16:44:49.400Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-1"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"BIND","connId":2,"msgId":1,"version":"3","dn":"cn=Heartbeat Admins":"SUCCESSFUL","statusCode":"0","elapsedTime":3,"elapsedTimeUnits":"MILLISECONDS"},"userId":"cn=Heartbeat Admin,cn=Root DNs,cn=config","timestamp":"2018-0315T16:44:49.687Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-4"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"UNBIND","connId":2,"msgId":3},"transactionId":"5009191b-a09a-4c7f-84cd-e240b2810a67-8","timestamp":"2018-03-15T16:44:49.729Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-10"} {"eventName":"DJ-LDAP","client":{"ip":"203.0.113.0","port":8443},"server":{"ip":"203.0.113.0","port":1636},"request":{"protocol":"LDAPS","operation":"DISCONNECT","connId":2},"transactionId":"0","response":{"status":"SUCCESSFUL","statusCode":"0","elapsedTime":0,"elapsedTimeUnits":"MILLISECONDS","reason":"Client Unbind"},"timestamp":"2018-03-15T16:44:49.734Z","_id":"5009191b-a09a-4c7f-84cd-e240b2810a67-12"}

Note

You can also perform a ldapsearch against cn=monitor for a complete status of the DS server as detailed in LDAP-Based Monitoring (DS 7 and later) or How do I use cn=monitor entry in DS 6.x for monitoring? Alternatively, you can use the Connections.newHeartBeatConnectionFactory() method detailed in Check Connection Health if your load balancer can use a Java-based application.

Related Training

N/A

Related Issue Tracker IDs

N/A