chap-referrals.xml revision 51607ea01068c9047391e4c8b46bc9dbd0edb7fd
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
391d13679315472c5e7b2abcde000787152da4c6mark ! Copyright 2011-2012 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
089bd21b4d1cee267b5ca4663cb8a2fe6c029e1cmark xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
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
08248b5c5b494aff8d1922e8e0b5777796d7450dmark directory server responds for example to your search with referrals to one
08248b5c5b494aff8d1922e8e0b5777796d7450dmark or more LDAP URLs, your client then constructs new searches from the LDAP
08248b5c5b494aff8d1922e8e0b5777796d7450dmark URLs returned, and tries again.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark </section>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark <para>To create an LDAP referral either you create a referral entry, or
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: objectClass
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: extensibleObject
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN ou=People,dc=example,dc=com</screen>
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>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSearchReference(referralURLs=
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkSearchReference(referralURLs=
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})</screen>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark <para>To access the entry instead of the referral, use the Manage DSAIT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark control.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --control ManageDSAIT:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangetype: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdelete: ref
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapmodify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkProcessing MODIFY request for ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkMODIFY operation successful for DN ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkA referral entry ou=People,dc=example,dc=com indicates that the operation must
08248b5c5b494aff8d1922e8e0b5777796d7450dmark be processed at a different server
08248b5c5b494aff8d1922e8e0b5777796d7450dmark[ldap://opendj.example.com:2389/ou=People,dc=example,dc=com]
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ ldapmodify
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager"
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --control ManageDSAIT
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkProcessing MODIFY request for ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkMODIFY operation successful for DN ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: organizationalunit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: extensibleObject
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top</screen>
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>