2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Constructing a Distributed Directory Service
7 For many sites, running one or more {{slapd}}(8) that hold an
8 entire subtree of data is sufficient. But often it is desirable
9 to have one {{slapd}} refer to other directory services for a
10 certain part of the tree (which may or may not be running {{slapd}}).
13 {{slapd}} supports {{subordinate}}, {{immediate superior}},
14 and {{superior}} knowledge information.
16 {{slapd}} supports {{subordinate}} and {{superior}} knowledge information.
20 H2: Subordinate Knowledge Information
22 Subordinate knowledge information may be provided to delegate
24 Subordinate knowledge information is maintained in the directory
25 as a special {{referral}} object at the delegate point.
26 The referral object acts as a delegation point, gluing two services
28 This mechanism allows for hierarchical directory services to be
31 A referral object has a structural object class of
32 {{EX:referral}} and has the same {{TERM[expand]DN}} as the
33 delegated subtree. Generally, the referral object will also
34 provide the auxiliary object class {{EX:extensibleObject}}.
35 This allows the entry to contain appropriate {{TERM[expand]RDN}}
36 values. This is best demonstrated by example.
38 If the server {{EX:a.example.net}} holds {{EX:dc=example,dc=net}}
39 and wished to delegate the subtree {{EX:ou=subtree,dc=example,dc=net}}
40 to another server {{EX:b.example.net}}, the following named referral
41 object would be added to {{EX:a.example.net}}:
43 > dn: dc=subtree,dc=example,dc=net
44 > objectClass: referral
45 > objectClass: extensibleObject
47 > ref: ldap://b.example.net/dc=subtree,dc=example,dc=net
49 The server uses this information to generate referrals and
50 search continuations to subordinate servers.
52 For those familiar with X.500, a {{named referral}} object is
53 similar to an X.500 knowledge reference held in a {{subr}}
58 H2: Immediate Superior Knowledge Information
60 Immediate superior knowledge information may be provided in the
61 entry at the root of a delegated subtree. The knowledge information
62 is contained with {{EX:ref}} operational attribute.
64 Extending the example above, a {{ref}} attribute can be added
65 to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating
66 that A holds the immediate superior naming context.
68 > dn: dc=subtree,dc=example,dc=net
71 > ref: ldap://a.example.net/
73 The server uses this information to generate referrals to
74 management operations.
76 For those familiar with X.500, this use of the {{EX:ref}} attribute
77 is similar to an X.500 knowledge reference held in a
78 {{immSupr}} {{TERM:DSE}}.
82 H2: Superior Knowledge Information
84 Superior knowledge information may be specified using the
85 {{EX:referral}} directive. The value is a list of {{TERM:URI}}s
86 referring to superior directory services. For servers without
87 immediate superiors, such as for {{EX:a.example.net}} in the example
88 above, the server can be configured to use a directory service with
89 {{global knowledge}}, such as the {{OpenLDAP Root Service}}
90 ({{URL:http://www.openldap.org/faq/index.cgi?file=393}}).
92 > referral ldap://root.openldap.org/
94 However, as {{EX:a.example.net}} is the {{immediate superior}}
95 to {{EX:b.example.net}}, {{b.example.net}} would be configured
98 > referral ldap://a.example.net/
100 The server uses this information to generate referrals for
101 operations acting upon entries not within or subordinate
102 to any of the naming contexts held by the server.
104 For those familiar with X.500, this use of the {{EX:ref}} attribute
105 is similar to an X.500 knowledge reference held in a
106 {{Supr}} {{TERM:DSE}}.
109 H2: The ManageDsaIT Control
111 Adding, modifying, and deleting referral objects is generally done
112 using {{ldapmodify}}(1) or similar tools which support the ManageDsaIT
113 control. The ManageDsaIT control informs the server that you intend
114 to manage the referral object as a regular entry. This keeps the
115 server from sending a referral result for requests which interrogate
116 or update referral objects.
118 The ManageDsaIT control should not be specified when managing regular
121 The {{EX:-M}} option of {{ldapmodify}}(1) (and other tools) enables
122 ManageDsaIT. For example:
124 > ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W
126 or with {{ldapsearch}}(1):
128 > ldapsearch -M -b "dc=example,dc=net" -x "(objectclass=referral)" '*' ref
130 Note: the {{EX:ref}} attribute is operational and must be explicitly
131 requested when desired in search results.