]> git.sur5r.net Git - openldap/blob - servers/slapd/back-meta/Documentation
Fixup bdb_entry_release now that entry_decode uses two memory blocks
[openldap] / servers / slapd / back-meta / Documentation
1 Copyright 1998-2001 The OpenLDAP Foundation, All Rights Reserved.
2 COPYING RESTRICTIONS APPLY, see COPYRIGHT file
3
4 Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
5
6
7
8    Metadirectory backend.
9
10 This is a brief introduction to the core functionalities of back-meta.
11
12
13
14  - Introduction.
15
16 Back-meta implements a backend for OpenLDAP's slapd.  It performs basic
17 LDAP proxying with respect to a set of remote LDAP servers, called
18 "targets".  The information contained in these servers can be presented
19 as belonging to a single Directory Information Tree (DIT).
20
21 A basic knowledge of the functionality of back-ldap is recommended.
22 This backend has been designed as an enhancement of back-ldap.
23 The two backends share many features (actually they also share portions
24 of code).  While back-ldap is intended to proxy operations directed
25 to a single server, back-meta is mainly intended for proxying
26 of multiple servers and possibly naming context masquerading.
27 These features, although useful in many scenarios, may result in
28 excessive overhead for some applications, so its use should be
29 carefully considered.
30
31 In the examples section, some typical scenarios will be discussed.
32
33
34
35  - Common configuration directives
36
37 The backend uses most of the common configuration directives.  Its
38 configuration block starts with the "database" directive:
39
40         database        meta
41
42 At least a "suffix" directive is required.
43
44 Note: as with back-ldap, operational attributes related to entry
45 creation/modification should not be used, as they would be passed
46 to the target servers, generating an error.  Moreover, it makes
47 little sense to use such attributes in proxying, as the proxy
48 server doesn't actually store data, so it should have no knowledge
49 of such attributes.  While code to strip the modification attributes
50 has been put in place (and #ifdef'd), it implies unmotivated overhead.
51 So it is strongly recommended to set
52
53         lastmod         off
54
55 for every back-ldap/back-meta backend.
56
57
58
59  - Special configuration directives
60
61 Target configuration starts with the "uri" directive.  All the 
62 configuration directives that are not specific to targets should
63 be defined first for clarity, including those that are common to
64 all backends.  They are:
65
66         default-target  none
67
68 This directive forces the backend to reject all those operations
69 that must resolve to a single target in case none or multiple
70 targets are selected.  They include: add, delete, modify, modrdn;
71 compare is not included, as well as bind since, as they don't
72 alter entries, in case of multiple matches an attempt is made
73 to perform the operation on any candidate target, with the
74 constraint that at most on must succeed.  This directive can also
75 be used when processing targets to mark a specific target as default.
76
77         dncache-ttl     {forever|disabled|<ttl>}
78
79 This directive sets the time-to-live of the dn cache.  This caches
80 the target that holds a given dn to speed up target selection
81 in case multiple targets would result from an uncached search;
82 forever means cache never expires; disabled means no dn caching;
83 otherwise a valid ( > 0 ) ttl in seconds is required.
84
85
86
87  - Target specification
88
89 Target specification starts with a "uri" directive:
90
91         uri             <protocol>://[<host>[:<port>]]/<naming context>
92
93 The "server" directive that was allowed in back-ldap (although deprecated)
94 has been discarded in back-meta.  The <protocol> part can be anything
95 ldap_initialize(3) accepts ({ldap|ldaps|ldapi} and variants); <host>
96 and <port> may be omitted, defaulting to whatever is set in
97 /etc/ldap.conf (correct me!?!).
98 The <naming context> part is mandatory.  It must end with one of the
99 naming contexts defined for the backend, e.g.:
100
101                 suffix          "dc=foo,dc=com"
102                 uri             "ldap://x.foo.com/dc=x,dc=foo,dc=com"
103
104 The <naming context> part doesn't need to be unique across the targets;
105 it may also match one of the values of the "suffix" directive.
106
107         default-target  [<target>]
108
109 the "default-target" directive can also be used during target 
110 specification.  With no arguments it marks the current target as
111 the default.  The optional number marks target <target> as the
112 default one, starting from 1.  Target <target> must be defined.
113
114         binddn          <administrative dn for ac purposes>
115
116 This directive, as in back-ldap, allows to define the dn that is
117 used to query the target server for acl checking; it should have
118 read access on the target server to attributes used on the proxy
119 for acl checking.  There is no risk of giving away such values;
120 they are only used to check permissions.
121
122         bindpw          <password for ac purposes>
123
124 This directive sets the password for acl checking in conjunction
125 with the above mentioned "binddn" directive.
126
127         pseudorootdn    <substitute dn in case of rootdn bind>
128
129 This directive, if present, sets the dn that will be substituted
130 to the bind dn if a bind with the backend's "rootdn" succeeds.  The true
131 "rootdn" of the target server ought not be used; an arbitrary administrative
132 dn should used instead.
133
134         pseudorootpw    <substitute password in case of rootdn bind>
135
136 This directive sets the credential that will be used in case a bind
137 with the backend's "rootdn" succeeds, and the bind is propagated to
138 the target using the "pseudorootdn" dn.
139
140         rewrite*        ...
141
142         suffixmassage   <virtual naming context> <real naming context>
143
144 All the directives starting with "rewrite" refer to the rewrite engine
145 that has been added to slapd.  The "suffixmassage" directive was
146 introduced in back-ldap to allow suffix massaging while proxying.
147 It has been obsoleted by the rewriting tools.  However, both for
148 backward compatibility and for ease of configuration when simple
149 suffix massage is required, it has been preserved.  It wraps the
150 basic rewriting instructions that perform suffix massaging.
151
152 Note: this also fixes a flaw in suffix massaging, which operated
153 on (case insensitive) DNs instead of normalized DNs,
154 so "dc=foo, dc=com" would not match "dc=foo,dc=com".
155
156 See the "rewrite" section.
157
158         map             {objectClass|attribute} {<source>|*} [<dest>|*]
159
160 objectClass/attribute mapping stuff.  This has been inherited from
161 the work made by Mark Valence on the back-ldap backend.
162 See the mapping section.
163
164
165
166  - Scenarios
167
168 A powerful (and in some sense dangerous) rewrite engine has been added
169 to both back-ldap and back-meta.  While the former can gain limited
170 beneficial effects from rewriting stuff, the latter can become
171 an amazingly powerful tool.
172
173 Consider a couple of scenarios first.
174
175 1) Two directory servers share two levels of naming context;
176 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".  Then, an
177 unambiguous back-meta can be configured as:
178
179         database        meta
180         suffix          "dc=foo,dc=com"
181
182         uri             "ldap://a.foo.com/dc=a,dc=foo,dc=com"
183
184         uri             "ldap://b.foo.com/dc=b,dc=foo,dc=com"
185
186 Operations directed to a specific target can be easily resolved
187 because there are no ambiguities.  The only operation that may
188 resolve to multiple targets is a search with base "dc=foo,dc=com" 
189 and scope at least "one", which results in spawning two searches
190 to the targets.
191
192 2a) Two directory servers don't share any portion of naming context,
193 but they'd present as a single DIT.  [Caveat: uniqueness of
194 (massaged) entries among the two servers is assumed; integrity 
195 checks risk to incurr in excessive overhead and have not been implemented.]
196 Say we have "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to
197 appear as branches of "dc=foo,dc=com", say "dc=a,dc=foo,dc=com"
198 and "dc=b,dc=foo,dc=com".  Then we need to configure our back-meta as:
199
200         database        meta
201         suffix          "dc=foo,dc=com"
202
203         uri             "ldap://a.bar.com/dc=a,dc=foo,dc=com"
204         suffixmassage   "dc=a,dc=foo,dc=com" "dc=bar,dc=org"
205         
206         uri             "ldap://b.foo.com/dc=b,dc=foo,dc=com"
207         suffixmassage   "dc=b,dc=foo,dc=com" "o=Foo,c=US"
208
209 Again, operations can be resolved without ambiguity, although
210 some rewriting is required.  Notice that the virtual naming context
211 of each target is a branch of the database's naming context; it
212 is rewritten back and forth when operations are performed towards
213 the target servers.  What "back and forth" means will be clarified
214 later.
215
216 When a search with base "dc=foo,dc=com" is attempted, if the 
217 scope is "base" it fails with "no such object"; in fact, the
218 common root of the two targets (prior to massaging) does not
219 exist.  If the scope is "one", both targets are contacted with
220 the base replaced by each target's base; the scope is derated
221 to "base".  In general, a scope "one" search is honored,
222 and the scope is derated, only when the incoming base is
223 at most one level lower of a target's naming context (prior
224 to massaging).
225 Finally, if the scope is "sub" the incoming base is replaced
226 by each target's unmassaged naming context, and the scope
227 is not altered.
228
229 2b) Consider the above reported scenario with the two servers
230 sharing the same naming context:
231
232         database        meta
233         suffix          "dc=foo,dc=com"
234
235         uri             "ldap://a.bar.com/dc=foo,dc=com"
236         suffixmassage   "dc=foo,dc=com" "dc=bar,dc=org"
237         
238         uri             "ldap://b.foo.com/dc=foo,dc=com"
239         suffixmassage   "dc=foo,dc=com" "o=Foo,c=US"
240         
241 All the previous considerations hold, except that now there is
242 no way to unambiguously resolve a dn.  In this case, all the
243 operations that require an unambiguous target selection will
244 fail unless the dn is already cached or a default target has
245 been set.
246
247
248
249  - Rewriting
250
251 This part of the document is being prepared.  At present you may consult
252 the RATIONALE in libraries/librewrite.
253
254
255
256  - Objectclass/attribute mapping
257
258 This part of the document is being prepared.  At present you may stick with 
259
260 http://www.openldap.org/lists/openldap-devel/200102/msg00006.html
261
262
263
264  - ACL
265 Note on ACLs: at present you may add whatever ACL rule you desire
266 to back-meta (as well as to back-ldap).  However, the meaning of an ACL
267 on a proxy may require some considerations.  Two philosophies may be
268 considered:
269
270 a) the remote server dictates the permissions; the proxy simply passes
271 back what it gets from the remote server.
272
273 b) the remote server unveils "everything"; the proxy is responsible
274 for protecting data from unauthorized access.
275
276 Of course the latter sounds unreasonable, but it is not.  It is possible
277 to imagine scenarios in which a remote host discloses data that can
278 be considered "public" inside an intranet, and a proxy that connects it
279 to the internet may impose additional constraints.  To this purpose, the
280 proxy should be able to comply with all the ACL matching criteria that
281 the server supports.  This has been achieved with regard to all the
282 criteria supported by slapd except a special subtle case (please drop
283 me a note if you can find other exceptions: <ando@openldap.org>).
284 The rule
285
286 access to dn="<dn>" attr=<attr>
287         by dnattr=<dnattr> read
288         by * none
289
290 cannot be matched IFF:
291 - the attribute that is being requested, <attr>, is NOT <dnattr>, and
292 - the attribute that determines membership, <dnattr>, has not
293   been requested (e.g. in a search)
294
295 In fact this ACL is resolved by slapd using the portion of entry it retrieved
296 from the remote server without requiring any further intervention of the
297 backend, so, if the <dnattr> attribute has not been fetched, the match
298 cannot be assessed because the attribute is not present, not because
299 no value matches the requirement!
300
301
302 Note on ACLS and attribute mapping: ACLs are applied to the mapped
303 attributes; for instance, if the attribute locally known as "foo" 
304 is mapped to "bar" on a remote server, then local ACLs apply to 
305 attribute "foo" and are totally unaware of its remote name.  The 
306 remote server will check permissions for "bar", and the local server 
307 will possibly enforce additional restrictions to "foo".
308