1# OpenLDAP: pkg/openldap-guide/admin/referrals.sdf,v 1.25.2.8 2010/04/13 20:22:34 kurt Exp 2# Copyright 1999-2010 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