(ITS#5479) Pasword Policy docs from Symas

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

diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf
index a62a7ad7076d772f9693c7ee85feb324da7b1d0b..bc499c91b79ab3ae45633b30ce22f8e0a08c8a0c 100644 (file)
--- a/doc/guide/admin/referrals.sdf
+++ b/doc/guide/admin/referrals.sdf
@@ -1,5 +1,5 @@
 # $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Constructing a Distributed Directory Service
@@ -14,6 +14,8 @@ certain part of the tree (which may or may not be running {{slapd}}).
 and {{superior}} knowledge information.
 !else
 {{slapd}} supports {{subordinate}} and {{superior}} knowledge information.
+Subordinate knowledge information is held in {{EX:referral}}
+objects ({{REF:RFC3296}}).
 !endif
 
 
@@ -49,7 +51,7 @@ object would be added to {{EX:a.example.net}}:
 The server uses this information to generate referrals and
 search continuations to subordinate servers.
 
-For those familiar with X.500, a {{named referral}} object is
+For those familiar with {{TERM:X.500}}, a {{named referral}} object is
 similar to an X.500 knowledge reference held in a {{subr}}
 {{TERM:DSE}}.
 
@@ -73,20 +75,20 @@ that A holds the immediate superior naming context.
 The server uses this information to generate referrals to
 management operations.
 
-For those familiar with X.500, this use of the {{EX:ref}} attribute
-is similar to an X.500 knowledge reference held in a
+For those familiar with {{TERM:X.500}}, this use of the {{EX:ref}}
+attribute is similar to an X.500 knowledge reference held in a
 {{immSupr}} {{TERM:DSE}}.
 !endif
 
 
 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 a directory service with
-{{global knowledge}}, such as the {{OpenLDAP Root Service}}
+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 a directory service with {{global knowledge}},
+such as the {{OpenLDAP Root Service}}
 ({{URL:http://www.openldap.org/faq/index.cgi?file=393}}).
 
 >      referral        ldap://root.openldap.org/
@@ -97,12 +99,12 @@ as follows:
 
 >      referral        ldap://a.example.net/
 
-The server uses this information to generate referrals for
-operations acting upon entries not within or subordinate
-to any of the naming contexts held by the server.
+The server uses this information to generate referrals for operations
+acting upon entries not within or subordinate to any of the naming
+contexts held by the server.
 
-For those familiar with X.500, this use of the {{EX:ref}} attribute
-is similar to an X.500 knowledge reference held in a
+For those familiar with {{TERM:X.500}}, this use of the {{EX:ref}}
+attribute is similar to an X.500 knowledge reference held in a
 {{Supr}} {{TERM:DSE}}.
 
 
@@ -130,3 +132,10 @@ or with {{ldapsearch}}(1):
 Note: the {{EX:ref}} attribute is operational and must be explicitly
 requested when desired in search results.
 
+Note: the use of referrals to construct a Distributed Directory Service is
+extremely clumsy and not well supported by common clients. If an existing
+installation has already been built using referrals, the use of the
+{{chain}} overlay to hide the referrals will greatly improve the usability
+of the Directory system. A better approach would be to use explicitly
+defined local and proxy databases in {{subordinate}} configurations to
+provide a seamless view of the Distributed Directory.