git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-relay.5

   1 .TH SLAPD-RELAY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 slapd-relay \- relay backend to slapd
   4 .SH SYNOPSIS
   5 ETCDIR/slapd.conf
   6 .SH DESCRIPTION
   7 The primary purpose of this
   8 .BR slapd (8)
   9 backend is to map a naming context defined in a database
  10 running in the same
  11 .BR slapd (8)
  12 instance into a virtual naming context, with attributeType
  13 and objectClass manipulation, if required.
  14 It requires the
  15 .B rwm
  16 .BR overlay .
  17 .LP
  18 This backend and the above mentioned overlay are experimental.
  19 .SH CONFIGURATION
  20 The following
  21 .B slapd.conf
  22 directives apply to the relay backend database.
  23 That is, they must follow a "database relay" line and come before any
  24 subsequent "backend" or "database" lines.
  25 Other database options are described in the
  26 .BR slapd.conf (5)
  27 manual page; only the
  28 .B suffix
  29 directive is required by the
  30 .I relay
  31 backend.
  32 .TP
  33 .B relay <real naming context> [massage]
  34 The naming context of the database that is presented
  35 under a virtual naming context.
  36 The presence of this directive implies that one specific database,
  37 i.e. the one serving the
  38 .BR "real naming context" ,
  39 will be presented under a virtual naming context.
  40 This directive automatically instantiates the
  41 .IR "rwm overlay" .
  42 If the optional
  43 .B massage
  44 keyword is present, the suffix massaging is automatically
  45 configured as well; otherwise, specific massaging instructions
  46 are required by means of the
  47 .I rewrite
  48 directives described in
  49 .BR slapo-rwm (5).
  50
  51 .SH ACCESS RULES
  52 One important issue is that access rules are based on the identity
  53 that issued the operation.
  54 After massaging from the virtual to the real naming context, the
  55 frontend sees the operation as performed by the identty in the
  56 real naming context.
  57 Moreover, since
  58 .B back-relay
  59 bypasses the real database frontend operations by short-circuiting
  60 operations thru the internal backend API, the original database
  61 access rules do not apply but in selected cases, i.e. when the
  62 backend itself applies access control.
  63 As a consequence, the instances of the relay database must provide
  64 own access rules that are consistent with those of the original
  65 database, possibly adding further specific restrictions.
  66 So, access rules in the
  67 .B relay
  68 database must refer to identities in the real naming context.
  69 Examples are reported in the EXAMPLES section.
  70
  71 .SH SCENARIOS
  72 .LP
  73 If no
  74 .B relay
  75 directive is given, the
  76 .I relay
  77 database does not refer to any specific database, but the most
  78 appropriate one is looked-up after rewriting the request DN
  79 for the operation that is being handled.
  80 .LP
  81 This allows to write carefully crafted rewrite rules that
  82 cause some of the requests to be directed to one database, and
  83 some to another; e.g., authentication can be mapped to one
  84 database, and searches to another, or different target databases
  85 can be selected based on the DN of the request, and so.
  86 .LP
  87 Another possibility is to map the same operation to different
  88 databases based on details of the virtual naming context,
  89 e.g. groups on one database and persons on another.
  90 .LP
  91 .SH Caveats
  92 The
  93 .B rwm overlay
  94 is experimental.
  95 .LP
  96 .SH EXAMPLES
  97 To implement a plain virtual naming context mapping
  98 that refers to a single database, use
  99 .LP
 100 .nf
 101   database        relay
 102   suffix          "dc=virtual,dc=naming,dc=context"
 103   relay           "dc=real,dc=naming,dc=context" massage
 104 .fi
 105 .LP
 106 To implement a plain virtual naming context mapping
 107 that looks up the real naming context for each operation, use
 108 .LP
 109 .nf
 110   database        relay
 111   suffix          "dc=virtual,dc=naming,dc=context"
 112   overlay         rwm
 113   suffixmassage   "dc=virtual,dc=naming,dc=context"
 114           "dc=real,dc=naming,dc=context"
 115 .fi
 116 .LP
 117 This is useful, for instance, to relay different databases that
 118 share the terminal portion of the naming context (the one that
 119 is rewritten).
 120 .LP
 121 To implement the old-fashioned suffixalias, e.g. mapping
 122 the virtual to the real naming context, but not the results
 123 back from the real to the virtual naming context, use
 124 .LP
 125 .nf
 126   database        relay
 127   suffix          "dc=virtual,dc=naming,dc=context"
 128   relay           "dc=real,dc=naming,dc=context"
 129   rewriteEngine   on
 130   rewriteContext  default
 131   rewriteRule     "dc=virtual,dc=naming,dc=context"
 132           "dc=real,dc=naming,dc=context" ":@"
 133   rewriteContext  searchFilter
 134   rewriteContext  searchEntryDN
 135   rewriteContext  searchAttrDN
 136   rewriteContext  matchedDN
 137 .fi
 138 .LP
 139 Note that the virtual database is bound to a single real database,
 140 so the
 141 .B rwm overlay
 142 is automatically instantiated, but the rewrite rules
 143 are written explicitly to map all the virtual to real
 144 naming context data flow, but none of the real to virtual.
 145 .LP
 146 Access rules:
 147 .LP
 148 .nf
 149   database        bdb
 150   suffix          "dc=example,dc=com"
 151   # skip...
 152   access to dn.subtree="dc=example,dc=com"
 153           by dn.exact="cn=Supervisor,dc=example,dc=com" write
 154           by * read
 155
 156   database        relay
 157   suffix          "o=Example,c=US"
 158   relay           "dc=example,dc=com" massage
 159   # skip ...
 160   access to dn.subtree="o=Example,c=US"
 161           by dn.exact="cn=Supervisor,dc=example,dc=com" write
 162           by dn.exact="cn=Relay Supervisor,dc=example,dc=com" write
 163           by * read
 164 .fi
 165 .LP
 166 Note that, in both databases, the identities (the
 167 .B <who>
 168 clause) are in the
 169 .BR "real naming context" ,
 170 i.e.
 171 .BR "`dc=example,dc=com'" ,
 172 while the targets (the
 173 .B <what>
 174 clause) are in the
 175 .B real
 176 and in the
 177 .BR "virtual naming context" ,
 178 respectively.
 179 .SH FILES
 180 .TP
 181 ETCDIR/slapd.conf
 182 default slapd configuration file
 183 .SH SEE ALSO
 184 .BR slapd.conf (5),
 185 .BR slapo-rwm (5),
 186 .BR slapd (8).