external/bsd/openldap/dist/servers/slapd/back-relay/README

   1 Relay backend sets up a relay virtual database that allows
   2 to access other databases in the same instance of slapd
   3 through different naming contexts and remapping attribute
   4 values.
   5
   6 The DN rewrite, filter rewrite and attributeType/objectClass
   7 mapping is done by means of the rewrite-remap overlay.
   8
   9 The database containing the real naming context can be
  10 explicitly selected by means of the "relay" directive,
  11 which must contain the naming context of the target
  12 database.  This also causes the rewrite-remap overlay
  13 to be automatically instantiated.  If the optional keyword
  14 "massage" is present, the rewrite-remap overlay is
  15 automatically configured to map the virtual to the real
  16 naming context and vice-versa.
  17
  18 Otherwise, the rewrite-remap overlay must be explicitly
  19 instantiated, by using the "overlay" directive, as
  20 illustrated below.  This allows much more freedom in target
  21 database selection and DN rewriting.
  22
  23 If the "relay" directive is not present, the backend is
  24 not bound to a single target database; on the contrary,
  25 the target database is selected on a per-operation basis.
  26
  27 This allows, for instance, to relay one database for
  28 authentication and anotheir for search/modify, or allows
  29 to use one target for persons and another for groups
  30 and so on.
  31
  32 To summarize: the "relay" directive:
  33 - explicitly bounds the database to a single database
  34   holding the real naming context;
  35 - automatically instantiates the rewrite-remap overlay;
  36 - automatically configures the naming context massaging
  37   if the optional "massage" keyword is added
  38
  39 If the "relay" directive is not used, the rewrite-remap
  40 overlay must be explicitly instantiated and the massaging
  41 must be configured, either by using the "suffixmassage"
  42 directive, or by issuing more sophisticate rewrite
  43 instructions.
  44
  45 AttributeType/objectClass mapping must be explicitly
  46 required.
  47
  48 Note that the rewrite-remap overlay is not complete nor
  49 production- ready yet.
  50 Examples are given of all the suggested usages.
  51
  52 # automatically massage from virtual to real naming context
  53 database        relay
  54 suffix          "dc=virtual,dc=naming,dc=context"
  55 relay           "dc=real,dc=naming,dc=context" massage
  56
  57 # explicitly massage (same as above)
  58 database        relay
  59 suffix          "dc=virtual,dc=naming,dc=context"
  60 relay           "dc=real,dc=naming,dc=context"
  61 suffixmassage   "dc=virtual,dc=naming,dc=context" \
  62                         "dc=real,dc=naming,dc=context"
  63
  64 # explicitly massage (same as above, but dynamic backend resolution)
  65 database        relay
  66 suffix          "dc=virtual,dc=naming,dc=context"
  67 overlay         rewrite-remap
  68 suffixmassage   "dc=virtual,dc=naming,dc=context" \
  69                         "dc=real,dc=naming,dc=context"
  70
  71 # old fashioned suffixalias, applied also to DN-valued attributes
  72 # from virtual to real naming context, but not the reverse...
  73 database        relay
  74 suffix          "dc=virtual,dc=naming,dc=context"
  75 relay           "dc=real,dc=naming,dc=context"
  76 rewriteContext  default
  77 rewriteRule     "(.*)dc=virtual,dc=naming,dc=context$" \
  78                         "$1dc=real,dc=naming,dc=context"
  79 rewriteContext  searchFilter
  80 rewriteContext  searchResult
  81 rewriteContext  searchResultAttrDN
  82 rewriteContext  matchedDN
  83