Fix up a SASL terms and links

[openldap] / doc / guide / admin / referrals.sdf

diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf
index e7b4415868b5de0882e5f161eccac184fde05f82..327b28ce7ab5afbf303c31145291fcab685a7f42 100644 (file)
--- 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.
 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.
 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
 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
 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.
 
 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}}.
 
 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
 !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.
 
 
 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.
 
 
 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
 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
 
 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:
 
 
 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.
 
 
 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}}.
 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.
+