1# $OpenLDAP$
2# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved.
3# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5H1: Constructing a Distributed Directory Service
6
7For many sites, running one or more {{slapd}}(8) that hold an
8entire subtree of data is sufficient. But often it is desirable
9to have one {{slapd}} refer to other directory services for a
10certain part of the tree (which may or may not be running {{slapd}}).
11
12!if 0
13{{slapd}} supports {{subordinate}}, {{immediate superior}},
14and {{superior}} knowledge information.
15!else
16{{slapd}} supports {{subordinate}} and {{superior}} knowledge information.
17Subordinate knowledge information is held in {{EX:referral}}
18objects ({{REF:RFC3296}}).
19!endif
20
21
22H2: Subordinate Knowledge Information
23
24Subordinate knowledge information may be provided to delegate
25a subtree.
26Subordinate knowledge information is maintained in the directory
27as a special {{referral}} object at the delegate point.
28The referral object acts as a delegation point, gluing two services
29together.
30This mechanism allows for hierarchical directory services to be
31constructed.
32
33A referral object has a structural object class of
34{{EX:referral}} and has the same {{TERM[expand]DN}} as the
35delegated subtree.  Generally, the referral object will also
36provide the auxiliary object class {{EX:extensibleObject}}.
37This allows the entry to contain appropriate {{TERM[expand]RDN}}
38values.  This is best demonstrated by example.
39
40If the server {{EX:a.example.net}} holds {{EX:dc=example,dc=net}}
41and wished to delegate the subtree {{EX:ou=subtree,dc=example,dc=net}}
42to another server {{EX:b.example.net}}, the following named referral
43object would be added to {{EX:a.example.net}}:
44
45>	dn: dc=subtree,dc=example,dc=net
46>	objectClass: referral
47>	objectClass: extensibleObject
48>	dc: subtree
49>	ref: ldap://b.example.net/dc=subtree,dc=example,dc=net
50
51The server uses this information to generate referrals and
52search continuations to subordinate servers.
53
54For those familiar with {{TERM:X.500}}, a {{named referral}} object is
55similar to an X.500 knowledge reference held in a {{subr}}
56{{TERM:DSE}}.
57
58
59!if 0
60H2: Immediate Superior Knowledge Information
61
62Immediate superior knowledge information may be provided in the
63entry at the root of a delegated subtree.  The knowledge information
64is contained with {{EX:ref}} operational attribute.
65
66Extending the example above, a {{ref}} attribute can be added
67to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating
68that A holds the immediate superior naming context.
69
70>	dn: dc=subtree,dc=example,dc=net
71>	changetype: modify
72>	add: ref
73>	ref: ldap://a.example.net/
74
75The server uses this information to generate referrals to
76management operations.
77
78For those familiar with {{TERM:X.500}}, this use of the {{EX:ref}}
79attribute is similar to an X.500 knowledge reference held in a
80{{immSupr}} {{TERM:DSE}}.
81!endif
82
83
84H2: Superior Knowledge Information
85
86Superior knowledge information may be specified using the {{EX:referral}}
87directive.  The value is a list of {{TERM:URI}}s referring to
88superior directory services.  For servers without immediate superiors,
89such as for {{EX:a.example.net}} in the example above, the server
90can be configured to use a directory service with {{global knowledge}},
91such as the {{OpenLDAP Root Service}}
92({{URL:http://www.openldap.org/faq/index.cgi?file=393}}).
93
94>	referral	ldap://root.openldap.org/
95
96However, as {{EX:a.example.net}} is the {{immediate superior}}
97to {{EX:b.example.net}}, {{b.example.net}} would be configured
98as follows:
99
100>	referral	ldap://a.example.net/
101
102The server uses this information to generate referrals for operations
103acting upon entries not within or subordinate to any of the naming
104contexts held by the server.
105
106For those familiar with {{TERM:X.500}}, this use of the {{EX:ref}}
107attribute is similar to an X.500 knowledge reference held in a
108{{Supr}} {{TERM:DSE}}.
109
110
111H2: The ManageDsaIT Control
112
113Adding, modifying, and deleting referral objects is generally done
114using {{ldapmodify}}(1) or similar tools which support the ManageDsaIT
115control.  The ManageDsaIT control informs the server that you intend
116to manage the referral object as a regular entry.  This keeps the
117server from sending a referral result for requests which interrogate
118or update referral objects.
119
120The ManageDsaIT control should not be specified when managing regular
121entries.
122
123The {{EX:-M}} option of {{ldapmodify}}(1) (and other tools) enables
124ManageDsaIT.  For example:
125
126>	ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W
127
128or with {{ldapsearch}}(1):
129
130>	ldapsearch -M -b "dc=example,dc=net" -x "(objectclass=referral)" '*' ref
131
132Note: the {{EX:ref}} attribute is operational and must be explicitly
133requested when desired in search results.
134
135Note: the use of referrals to construct a Distributed Directory Service is
136extremely clumsy and not well supported by common clients. If an existing
137installation has already been built using referrals, the use of the
138{{chain}} overlay to hide the referrals will greatly improve the usability
139of the Directory system. A better approach would be to use explicitly
140defined local and proxy databases in {{subordinate}} configurations to
141provide a seamless view of the Distributed Directory.
142
143Note: LDAP operations, even subtree searches, normally access only one
144database. That can be changed by gluing databases together with the
145{{B:subordinate}}/{{B:olcSubordinate}} keyword. Please see {{slapd.conf}}(5)
146and {{slapd-config}}(5).
147