How do I perform a heartbeat check against DS (All versions)?
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 -> DISCONNECTor
CONNECT -> BIND -> UNBIND -> DISCONNECTCaution
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.
See Also
How do I check if a backend is online in DS (All versions)?
How do I use the Access log to troubleshoot DS (All versions)?
Performance tuning and monitoring ForgeRock products
Related Training
N/A
Related Issue Tracker IDs
N/A