Referrals Referrals point directory clients to another directory server. The client receiving a referral must then connect to the other server to complete the request. Referrals are used for example when a directory server is temporarily unavailable for maintenance. Referrals can also be used when a server contains only some of the directory data for a suffix and points to other servers 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.

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 -p 1389 -D "cn=Directory Manager" -w password -f 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 -p 1389 -b dc=example,dc=com uid=bjensen description SearchReference(referralURLs= {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?}) $ ldapsearch -p 1389 -b 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 -p 1389 -b dc=example,dc=com -J ManageDSAIT ou=people dn: ou=People,dc=example,dc=com ou: People objectClass: organizationalunit objectClass: extensibleObject objectClass: top $ 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 -p 1389 -D "cn=Directory Manager" -w password -f 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 -p 1389 -D "cn=Directory Manager" -w password -J ManageDSAIT -f people.ldif Processing MODIFY request for ou=People,dc=example,dc=com MODIFY operation successful for DN ou=People,dc=example,dc=com $ ldapsearch -p 1389 -b 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.