LDAP: The root DSE

Updates to this article are located at “The Root DSE”, a shared technical note, and this article will no longer be updated.

---

Directory Servers must provide information about themselves when asked, although that information is subject to access control. If a client knows the hostname and port upon which a directory server is listening, the client should query the root DSE for the information. The root DSE may contain information about the vendor, the naming contexts the server supports (or shadows), the request controls the server supports, the supported SASL mechanisms, features, and other information.

The root DSE is that entry with zero RDNs, that is, it is the entry that is defined as a zero-length string. The root DSE must not be present when the client does a subtree search that starts at the root. To query the root DSE, use the following command:

ldapsearch -h host -p port -D bindDn -w bindDnPassword \
    --sizeLimit 1 --timeLimit 10 \
    -b '' -s base '(&)' attribute ...

Since the attributes defined in the root DSE are operational attributes they have to be requested explicitly. Some attributes that might be requested are:

• altServer – a multi-valued attribute whose values are a list of alternative servers that can be used when the server is not available.
• namingContexts – a multi-valued attribute whose values are context prefixes that the server masters.
• supportedControl – a multi-valued attribute whose values are request control OIDs that the server supports. Note: the supported controls are the request controls. The response controls the server supports need not be listed. Some incorrectly written software, notably ldap_cachemgr on Solaris and OpenSolaris, expects supported response controls to be listed in the root DSE, and fail to operate correctly in some cases when the response controls are not listed.
• supportedExtension – a multi-valued attribute whose values are ‘elective’ features that the server supports. Listed as OIDs.
• supportedLDAPVersion – a multi-valued attribute describing which LDAP protocol versions that the server supports.
• supportedSASLMechanisms – a multi-valued attribute whose values are a list of SASL mechanisms that the server recognizes and/or supports.
• vendorName – the name of the LDAP server implementer
• vendorVersion – the version of the LDAP server implementation

This is the output of the ldapsearch tool that is the result of retrieving the root DSE of a public LDAP server, directory.verisign.com. Note that the root DSE is specified by the zero-length base DN, and the search scope is specified as base:

$ /usr/bin/ldapsearch -x -LLL -h directory.verisign.com -p 389 \
 -b '' -s base '(&)' \
 supportedExtension supportedControl \
 supportedSASLMechanisms supportedLdapVersion \
 dataVersion vendorName vendorVersion namingContexts
dn:
supportedExtension: 2.16.840.1.113730.3.5.7
...
supportedControl: 2.16.840.1.113730.3.4.2
...
supportedSASLMechanisms: EXTERNAL
...
supportedLdapVersion: 2
supportedLdapVersion: 3
dataVersion: 020110728042805
#
# Using the more modern ldapsearch
# syntax:
#
ldapsearch --hostname directory.verisign.com --port 389 \
 --baseDn '' --searchScope base '(&)' \
 supportedExtension supportedControl \
 supportedSASLMechanisms supportedLdapVersion \
 dataVersion vendorName vendorVersion namingContext
dn:
supportedExtension: 2.16.840.1.113730.3.5.7
...
supportedSASLMechanisms: EXTERNAL
...
supportedLdapVersion: 2
supportedLdapVersion: 3
dataVersion: 020110728042805

Example: Retrieve the root DSE

import com.unboundid.ldap.sdk.LDAPConnection;
import com.unboundid.ldap.sdk.RootDSE;

...

// Get the root DSE and from it get the naming contexts ...
LDAPConnection ldapConnection = new LDAPConnection(hostname,port);
RootDSE rootDSE = ldapConnection.getRootDSE();
String[] namingContexts = rootDSE.getNamingContextDNs();

This information is also available as a shared note at Evernote.

References

• UnboundID LDAP SDK for Java
• LDAP Parameter Assignments
• RFC 4512
• RFC 4422 (SASL)
• RFC 3045

Updates

• 30-Oct-2011: Added example of retrieving the root DSE using Java
• 05-Nov-2011: Removed some of the output of the ldapsearch
• 24-Nov-2011: Added reference to the shared note at Evernote.