51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
08248b5c5b494aff8d1922e8e0b5777796d7450dmark ! Copyright 2011-2014 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para><firstterm>Referrals</firstterm> point directory clients to another
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory container, which can be another directory server running elsewhere,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark or another container on the same server. The client receiving a referral must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark then connect to the other container to complete the request.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Some clients follow referrals on your behalf by default. The OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>ldapsearch</command> command does not follow referrals.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Referrals are used for example when a some directory data are temporarily
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark unavailable due to maintenance. Referrals can also be used when a container
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark holds only some of the directory data for a suffix and points to other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark containers for branches whose data is not available locally.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This chapter demonstrates how to add and remove referrals with the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>ldapmodify</command> command. You can also use the Manage Entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark window of the Control Panel to handle referrals.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="http://tools.ietf.org/html/rfc4516">LDAP URL</link>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ref</literal> attribute values that point elsewhere. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ref</literal> attribute type is required by the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>referral</literal> object class. The <literal>referral</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark object class is structural, however, and therefore cannot by default be added
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to an entry that already has a structural object class defined. When adding
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a <literal>ref</literal> attribute type to an existing entry, you can use
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <literal>extensibleObject</literal> auxiliary object class.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When a referral is set, OpenDJ returns the referral to client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications requesting the entry or child entries affected. Client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications must be capable of following the referral returned. When the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server responds for example to your search with referrals to one
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark or more LDAP URLs, your client then constructs new searches from the LDAP
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark URLs returned, and tries again.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To create an LDAP referral either you create a referral entry, or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you add the <literal>extensibleObject</literal> object class and the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ref</literal> attribute with an LDAP URL to an existing entry.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark This section demonstrates use of the latter approach.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: objectClass
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: extensibleObject
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN ou=People,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The example above adds a referral to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal>. OpenDJ can now return
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a referral for operations under the People organizational unit.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSearchReference(referralURLs=
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})
08248b5c5b494aff8d1922e8e0b5777796d7450dmark</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSearchReference(referralURLs=
08248b5c5b494aff8d1922e8e0b5777796d7450dmark {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To access the entry instead of the referral, use the Manage DSAIT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark control.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --control ManageDSAIT:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark ou=people \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark ref</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdelete: ref
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkA referral entry ou=People,dc=example,dc=com indicates that the operation must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark be processed at a different server
08248b5c5b494aff8d1922e8e0b5777796d7450dmark[ldap://opendj.example.com:2389/ou=People,dc=example,dc=com]</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapmodify \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --control ManageDSAIT \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Processing MODIFY request for ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN ou=People,dc=example,dc=com</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalunit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: extensibleObject
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkobjectClass: top</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The example above shows how to remove the referral using the Manage
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark DSAIT control with the <command>ldapmodify</command> command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>