1 files changed, 146 insertions, 0 deletions
diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf
new file mode 100644
index 0000000..e00df79
--- /dev/null
+++ b/doc/guide/admin/referrals.sdf
@@ -0,0 +1,146 @@
+# $OpenLDAP$
+# Copyright 1999-2022 The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+
+H1: Constructing a Distributed Directory Service
+
+For many sites, running one or more {{slapd}}(8) that hold an
+entire subtree of data is sufficient. But often it is desirable
+to have one {{slapd}} refer to other directory services for a
+certain part of the tree (which may or may not be running {{slapd}}).
+
+!if 0
+{{slapd}} supports {{subordinate}}, {{immediate superior}},
+and {{superior}} knowledge information.
+!else
+{{slapd}} supports {{subordinate}} and {{superior}} knowledge information.
+Subordinate knowledge information is held in {{EX:referral}}
+objects ({{REF:RFC3296}}).
+!endif
+
+
+H2: Subordinate Knowledge Information
+
+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 services
+together.
+This mechanism allows for hierarchical directory services to be
+constructed.
+
+A referral object has a structural object class of
+{{EX:referral}} and has the same {{TERM[expand]DN}} as the
+delegated subtree.  Generally, the referral object will also
+provide the auxiliary object class {{EX:extensibleObject}}.
+This allows the entry to contain appropriate {{TERM[expand]RDN}}
+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 {{EX:a.example.net}}:
+
+>	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.
+
+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}}.
+
+
+!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 {{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.
+
+>	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 {{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}}
+({{URL:http://www.openldap.org/faq/index.cgi?file=393}}).
+
+>	referral	ldap://root.openldap.org/
+
+However, as {{EX:a.example.net}} is the {{immediate superior}}
+to {{EX:b.example.net}}, {{b.example.net}} would be configured
+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.
+
+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}}.
+
+
+H2: The ManageDsaIT Control
+
+Adding, modifying, 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 ManageDsaIT control should not be specified when managing regular
+entries.
+
+The {{EX:-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.
+
+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.
+
+Note: LDAP operations, even subtree searches, normally access only one
+database. That can be changed by gluing databases together with the
+{{B:subordinate}}/{{B:olcSubordinate}} keyword. Please see {{slapd.conf}}(5) 
+and {{slapd-config}}(5).