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