git.sur5r.net Git - openldap/blob - doc/guide/admin/referrals.sdf

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