From ef59029e5b099b9aeab9662b3e3b4b58b3806923 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Mon, 20 Jun 2011 14:16:07 +0000
Subject: [PATCH] Draft chapter on working with referrals
---
opendj3/src/main/docbkx/admin-guide/chap-referrals.xml | 91 ++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 89 insertions(+), 2 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-referrals.xml b/opendj3/src/main/docbkx/admin-guide/chap-referrals.xml
index 8cb0c06..630f993 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-referrals.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-referrals.xml
@@ -38,8 +38,95 @@
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 set up referrals, and how to follow
- them with the command-line tools.</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>
--
Gitblit v1.10.0