Referrals Referrals point directory clients to another directory container, which can be another directory server running elsewhere, or another container on the same server. The client receiving a referral must then connect to the other container to complete the request. Some clients follow referrals on your behalf by default. The OpenDJ ldapsearch command does not follow referrals. Referrals are used for example when a some directory data are temporarily unavailable due to maintenance. Referrals can also be used when a container holds only some of the directory data for a suffix and points to other containers for branches whose data is not available locally. This chapter demonstrates how to add and remove referrals with the ldapmodify command. You can also use the Manage Entries window of the Control Panel to handle referrals.

Referrals are implemented as entries with LDAP URL ref attribute values that point elsewhere. The ref attribute type is required by the referral object class. The referral object class is structural, however, and therefore cannot by default be added to an entry that already has a structural object class defined. When adding a ref attribute type to an existing entry, you can use the extensibleObject auxiliary object class. When a referral is set, OpenDJ returns the referral to client applications requesting the entry or child entries affected. Client applications must be capable of following the referral returned. When the directory server responds for example to your search with referrals to one or more LDAP URLs, your client then constructs new searches from the LDAP URLs returned, and tries again.

To create an LDAP referral either you create a referral entry, or you add the extensibleObject object class and the ref attribute with an LDAP URL to an existing entry. This section demonstrates use of the latter approach. $ cat referral.ldif dn: ou=People,dc=example,dc=com changetype: modify add: objectClass objectClass: extensibleObject - add: ref ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com $ ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --filename referral.ldif Processing MODIFY request for ou=People,dc=example,dc=com MODIFY operation successful for DN ou=People,dc=example,dc=com The example above adds a referral to ou=People,dc=example,dc=com. OpenDJ can now return a referral for operations under the People organizational unit. $ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description SearchReference(referralURLs= {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?}) $ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people SearchReference(referralURLs= {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?}) To access the entry instead of the referral, use the Manage DSAIT control. $ ldapsearch --port 1389 --baseDN dc=example,dc=com --control ManageDSAIT:true ou=people ref dn: ou=People,dc=example,dc=com ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com $ cat people.ldif dn: ou=People,dc=example,dc=com changetype: modify delete: ref ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com $ ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --filename people.ldif Processing MODIFY request for ou=People,dc=example,dc=com MODIFY operation successful for DN ou=People,dc=example,dc=com A referral entry ou=People,dc=example,dc=com indicates that the operation must be processed at a different server [ldap://opendj.example.com:2389/ou=People,dc=example,dc=com] $ ldapmodify --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --control ManageDSAIT --filename people.ldif Processing MODIFY request for ou=People,dc=example,dc=com MODIFY operation successful for DN ou=People,dc=example,dc=com $ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people dn: ou=People,dc=example,dc=com ou: People objectClass: organizationalunit objectClass: extensibleObject objectClass: top The example above shows how to remove the referral using the Manage DSAIT control with the ldapmodify command.