<?xml version="1.0" encoding="UTF-8"?>
|
<!--
|
! CCPL HEADER START
|
!
|
! This work is licensed under the Creative Commons
|
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
|
! To view a copy of this license, visit
|
! http://creativecommons.org/licenses/by-nc-nd/3.0/
|
! or send a letter to Creative Commons, 444 Castro Street,
|
! Suite 900, Mountain View, California, 94041, USA.
|
!
|
! You can also obtain a copy of the license at
|
! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
|
! See the License for the specific language governing permissions
|
! and limitations under the License.
|
!
|
! If applicable, add the following below this CCPL HEADER, with the fields
|
! enclosed by brackets "[]" replaced with your own identifying information:
|
! Portions Copyright [yyyy] [name of copyright owner]
|
!
|
! CCPL HEADER END
|
!
|
! Copyright 2011 ForgeRock AS
|
!
|
-->
|
<chapter xml:id='chap-referrals'
|
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
|
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
|
xmlns:xlink='http://www.w3.org/1999/xlink'
|
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
|
<title>Working With Referrals</title>
|
|
<para>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.</para>
|
|
<para>This chapter demonstrates how to add and remove referrals with the
|
<command>ldapmodify</command> command. You can also use the Manage Entries
|
window of the Control Panel to handle referrals.</para>
|
|
<section>
|
<title>About Referrals</title>
|
|
<para>Referrals are implemented as entries with <link
|
xlink:href="http://tools.ietf.org/html/rfc4516">LDAP URL</link>
|
<literal>ref</literal> attribute values that point elsewhere. The
|
<literal>ref</literal> 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 <literal>ref</literal> attribute type to an existing
|
entry, you can use the <literal>extensibleObject</literal> auxiliary
|
object class.</para>
|
|
<para>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.</para>
|
</section>
|
|
<section>
|
<title>Managing Referrals</title>
|
|
<para>To create an LDAP referral either you create a referral entry, or
|
you add the <literal>extensibleObject</literal> object class and the
|
<literal>ref</literal> attribute with an LDAP URL to an existing entry.
|
This section demonstrates use of the latter approach.</para>
|
|
<screen width="80">$ 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</screen>
|
|
<para>The example above adds a referral to
|
<literal>ou=People,dc=example,dc=com</literal>. OpenDJ can now return
|
a referral for operations under the People organizational unit.</para>
|
|
<screen width="80">$ 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?})</screen>
|
|
<para>To access the entry instead of the referral, use the Manage DSAIT
|
control.</para>
|
|
<screen width="80">$ 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</screen>
|
|
<para>The example above shows how to remove the referral using the Manage
|
DSAIT control with the <command>ldapmodify</command> command.</para>
|
</section>
|
</chapter>
|
