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

   1 # $OpenLDAP$
   2 # Copyright 1999-2000, 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 !endif
  18
  19
  20 H2: Subordinate Knowledge Information
  21
  22 Subordinate knowledge information may be provided to delegate
  23 a subtree.
  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 servcies
  27 together.
  28 This mechanism allows for hierarchial directory services to to be
  29 constructed.
  30
  31 A referral object has an 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.
  37
  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 {{a.example.net}}:
  42
  43 E:      dn: dc=subtree, dc=example, dc=net
  44 E:      objectClass: referral
  45 E:      objectClass: extensibleObject
  46 E:      dc: subtree
  47 E:      ref: ldap://b.example.net/dc=subtree,dc=example,dc=net/
  48
  49 Adding, modify, and deleting referral objects is generally done
  50 using {{ldapmodify}}(1) or similiar tools which support the
  51 ManageDsaIT control.  The ManageDsaIT control informs the server
  52 that you intend to manage the referral object as a regular
  53 entry.  This keeps the server from sending a referral result
  54 for requests to updating referral objects.  The -M option of
  55 {{ldapmodify}}(1) (and other tools) enables ManageDsaIT.  For
  56 example:
  57
  58 E:  ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W
  59
  60 The server uses this information to generate referrals and
  61 search continuations to subordinate servers.
  62
  63 For those familiar with X.500, a {{named referral}} object is
  64 similar to an X.500 knowledge reference held in a {{subr}}
  65 {{TERM:DSE}}.
  66
  67
  68 !if 0
  69 H2: Immediate Superior Knowledge Information
  70
  71 Immediate superior knowledge information may be provided in the
  72 entry at the root of a delegated subtree.  The knowledge information
  73 is contained with {{ref}} operational attribute.
  74
  75 Extending the example above, a {{ref}} attribute can be added
  76 to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating
  77 that A holds the immediate superior naming context.
  78
  79 E:      dn: dc=subtree, dc=example, dc=net
  80 E:      changetype: modify
  81 E:      add: ref
  82 E:      ref: ldap://a.example.net/
  83
  84 The server uses this information to generate referrals to
  85 management operations.
  86
  87 For those familiar with X.500, this use of the {{ref}} attribute
  88 is similar to an X.500 knowledge reference held in a
  89 {{immSupr}} {{TERM:DSE}}.
  90 !endif
  91
  92
  93 H2: Superior Knowledge Information
  94
  95 Superior knowledge information may be specified using the
  96 {{EX:referral}} directive.  The value is a list of {{TERM:URI}}s
  97 referring to superior directory services.  For servers
  98 without immediate superiors, such as for {{EX:a.example.net}}
  99 in the example above, the server can be configured to use
 100 directory service with {{global knowledge}}, such as the
 101 OpenLDAP Root Service.
 102
 103 E:      referral        ldap://root.openldap.org/
 104
 105 However, as {{EX:a.example.net}} is the {{immediate superior}}
 106 to {{EX:b.example.net}}, {{a.example.net}} would be configured
 107 as follows:
 108
 109 E:      referral        ldap://a.example.net/
 110
 111 The server uses this information to generate referrals to
 112 operations acting upon operations not within or subordinate
 113 to any of the naming contexts held by the server.
 114
 115 For those familiar with X.500, this use of the {{ref}} attribute
 116 is similar to an X.500 knowledge reference held in a
 117 {{Supr}} {{TERM:DSE}}.