X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Freferrals.sdf;h=327b28ce7ab5afbf303c31145291fcab685a7f42;hb=f9844ba92f20f75566e295f37ab361952006810b;hp=bc4539e1e4a69ac2bf19862eb05174681d175297;hpb=b7b1f8e3ba0012094b89d007a51b0f881cc7e797;p=openldap diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf index bc4539e1e4..327b28ce7a 100644 --- a/doc/guide/admin/referrals.sdf +++ b/doc/guide/admin/referrals.sdf @@ -1,40 +1,126 @@ -# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved. +# $OpenLDAP$ +# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Distributing {{I: slapd}} DATA - -For many sites, running one or more {{I: slapds}} that hold an -entire subtree of data is sufficient. But sometimes it may be -desirable to have one slapd refer to other {{I: slapds}} for a -certain part of the tree. This can be accomplished by -creating a referral entry in one {{I:slapd}}'s database pointing -to another {{I: slapd}}. For those familiar with X.500, a {{I:slapd}} -{{I: referral}} entry is similar to an X.500 knowledge reference. - -The referral entry acts as a mount point, glueing two slapd -databases together. A referral entry has an {{I: objectclass}} of -"referral" and is named by a {{I: ref}} attribute containing a URL -pointing to the slapd holding the data below the mount -point. This mechanism is very general and allows slapd -databases that are not normally hierarchical to be grafted + +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. +!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 to be +constructed. + +A referral object has an 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 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 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 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}}, {{a.example.net}} would be configured +as follows: + +> 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. + +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}}. -An example should help illustrate things. Suppose your -company is running a slapd and just purchased a new -company, also running a slapd. You can easily connect -the two databases by creating an entry like this in your -slapd's database. +H2: The ManageDsaIT Control -E: dn: ref="ldap://new.host/o=New Company,c=US", o=Your +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: -company, c=US +> ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W -E: objectclass: referral +or with {{ldapsearch}}(1): -Now any subtree search that has this entry in its scope -will return a referral to the new company, in addition to any -entries matched in your database. Referral-aware clients -will continue the search at the new company's server. +> ldapsearch -M -b "dc=example,dc=net" -x "(objectclass=referral)" '*' ref -A mechanism similar to this is used to support distributed -indexing, described in Appendix C. +Note: the {{EX:ref}} attribute is operational and must be explicitly +requested when desired in search results.