X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Freferrals.sdf;h=327b28ce7ab5afbf303c31145291fcab685a7f42;hb=f9844ba92f20f75566e295f37ab361952006810b;hp=e7b4415868b5de0882e5f161eccac184fde05f82;hpb=3b71ba0f15ba7d774276292c04ef078448d47fdf;p=openldap

diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf
index e7b4415868..327b28ce7a 100644
--- a/doc/guide/admin/referrals.sdf
+++ b/doc/guide/admin/referrals.sdf
@@ -23,9 +23,9 @@ Subordinate knowledge information may be provided to delegate
 a subtree.
 Subordinate knowledge information is maintained in the directory
 as a special {{referral}} object at the delegate point.
-The referral object acts as a delegation point, gluing two servcies
+The referral object acts as a delegation point, gluing two services
 together.
-This mechanism allows for hierarchial directory services to to be
+This mechanism allows for hierarchical directory services to to be
 constructed.
 
 A referral object has an structural object class of
@@ -38,24 +38,13 @@ values.  This is best demonstrated by example.
 If the server {{EX:a.example.net}} holds {{EX:dc=example,dc=net}}
 and wished to delegate the subtree {{EX:ou=subtree,dc=example,dc=net}}
 to another server {{EX:b.example.net}}, the following named referral
-object would be added to {{a.example.net}}:
+object would be added to {{EX:a.example.net}}:
 
-E:	dn: dc=subtree, dc=example, dc=net
-E:	objectClass: referral
-E:	objectClass: extensibleObject
-E:	dc: subtree
-E:	ref: ldap://b.example.net/dc=subtree,dc=example,dc=net/
-
-Adding, modify, and deleting referral objects is generally done
-using {{ldapmodify}}(1) or similiar tools which support the
-ManageDsaIT control.  The ManageDsaIT control informs the server
-that you intend to manage the referral object as a regular
-entry.  This keeps the server from sending a referral result
-for requests to updating referral objects.  The -M option of
-{{ldapmodify}}(1) (and other tools) enables ManageDsaIT.  For
-example:
-
-E:  ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W
+>	dn: dc=subtree, dc=example, dc=net
+>	objectClass: referral
+>	objectClass: extensibleObject
+>	dc: subtree
+>	ref: ldap://b.example.net/dc=subtree,dc=example,dc=net/
 
 The server uses this information to generate referrals and
 search continuations to subordinate servers.
@@ -64,27 +53,26 @@ For those familiar with X.500, a {{named referral}} object is
 similar to an X.500 knowledge reference held in a {{subr}}
 {{TERM:DSE}}.
 
-
 !if 0
 H2: Immediate Superior Knowledge Information
 
 Immediate superior knowledge information may be provided in the
 entry at the root of a delegated subtree.  The knowledge information
-is contained with {{ref}} operational attribute.
+is contained with {{EX:ref}} operational attribute.
 
 Extending the example above, a {{ref}} attribute can be added
 to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating
 that A holds the immediate superior naming context.
 
-E:	dn: dc=subtree, dc=example, dc=net
-E:	changetype: modify
-E:	add: ref
-E:	ref: ldap://a.example.net/
+>	dn: dc=subtree, dc=example, dc=net
+>	changetype: modify
+>	add: ref
+>	ref: ldap://a.example.net/
 
 The server uses this information to generate referrals to
 management operations.
 
-For those familiar with X.500, this use of the {{ref}} attribute
+For those familiar with X.500, this use of the {{EX:ref}} attribute
 is similar to an X.500 knowledge reference held in a
 {{immSupr}} {{TERM:DSE}}.
 !endif
@@ -94,24 +82,45 @@ H2: Superior Knowledge Information
 
 Superior knowledge information may be specified using the
 {{EX:referral}} directive.  The value is a list of {{TERM:URI}}s
-referring to superior directory services.  For servers
-without immediate superiors, such as for {{EX:a.example.net}}
-in the example above, the server can be configured to use
-directory service with {{global knowledge}}, such as the
-OpenLDAP Root Service.
+referring to superior directory services.  For servers without
+immediate superiors, such as for {{EX:a.example.net}} in the example
+above, the server can be configured to use directory service with
+{{global knowledge}}, such as the {{OpenLDAP Root Service}}
+({{URL:http://www.openldap.org/faq/index.cgi?file=393}}).
 
-E:	referral	ldap://root.openldap.org/
+>	referral	ldap://root.openldap.org/
 
 However, as {{EX:a.example.net}} is the {{immediate superior}}
 to {{EX:b.example.net}}, {{a.example.net}} would be configured
 as follows:
 
-E:	referral	ldap://a.example.net/
+>	referral	ldap://a.example.net/
 
 The server uses this information to generate referrals to
 operations acting upon operations not within or subordinate
 to any of the naming contexts held by the server.
 
-For those familiar with X.500, this use of the {{ref}} attribute
+For those familiar with X.500, this use of the {{EX:ref}} attribute
 is similar to an X.500 knowledge reference held in a
 {{Supr}} {{TERM:DSE}}.
+
+H2: The ManageDsaIT Control
+
+Adding, modify, and deleting referral objects is generally done
+using {{ldapmodify}}(1) or similar tools which support the
+ManageDsaIT control.  The ManageDsaIT control informs the server
+that you intend to manage the referral object as a regular
+entry.  This keeps the server from sending a referral result
+for requests which interrogate or update referral objects.
+The -M option of {{ldapmodify}}(1) (and other tools) enables
+ManageDsaIT.  For example:
+
+>	ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W
+
+or with {{ldapsearch}}(1):
+
+>	ldapsearch -M -b "dc=example,dc=net" -x "(objectclass=referral)" '*' ref
+
+Note: the {{EX:ref}} attribute is operational and must be explicitly
+requested when desired in search results.
+