1 Copyright 1998-2001 The OpenLDAP Foundation, All Rights Reserved.
2 COPYING RESTRICTIONS APPLY, see COPYRIGHT file
4 Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
10 This is a brief introduction to the core functionalities of back-meta.
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).
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
31 In the examples section, some typical scenarios will be discussed.
35 - Common configuration directives
37 The backend uses most of the common configuration directives. Its
38 configuration block starts with the "database" directive:
42 At least a "suffix" directive is required.
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's), it implies unmotivated overhead.
51 So it is strongly recommended to set
55 for every back-ldap/back-meta backend.
59 - Special configuration directives
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:
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 also included, although a different behavior might be
72 considered in the future. This directive can also be used when
73 processing targets to mark a specific target as default.
75 dncache-ttl {forever|disabled|<ttl>}
77 This directive sets the time-to-live of the dn cache. This caches
78 the target that holds a given dn to speed up target selection
79 in case multiple targets would result from an uncached search;
80 forever means cache never expires; disabled means no dn caching;
81 otherwise a valid ( > 0 ) ttl in seconds is required.
85 - Target specification
87 Target specification starts with a "uri" directive:
89 uri <protocol>://[<host>[:<port>]]/<naming context>
91 The "server" directive that was allowed in back-ldap has been discarded
92 in back-meta. The <protocol> part can be anything ldap_initialize(3)
93 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
94 omitted, defaulting to whatever is set in /etc/ldap.conf (correct me!?!).
95 The <naming context> part is mandatory. It must end with one of the
96 naming contexts defined for the backend, e.g.:
98 suffix "dc=foo,dc=com"
99 uri "ldap://x.foo.com/dc=x,dc=foo,dc=com"
101 The <naming context> part doesn't need to be unique across the targets;
102 it may also match one of the values of the "suffix" directive.
104 default-target [<target>]
106 the "default-target" directive can also be used during target
107 specification. With no arguments it marks the current target as
108 the default. The optional number marks target <target> as the
109 default one, starting from 1. Target <target> must be defined.
111 binddn <administrative dn for ac purposes>
113 This directive, as in back-ldap, allows to define the dn that is
114 used to query the target server for acl checking; it should have
115 read access on the target server to attributes used on the proxy
116 for acl checking. There is no risk of giving away such values;
117 they are only used to check permissions.
119 bindpw <plaintext password for ac purposes>
121 This directive sets the password for acl checking in conjunction
122 with the above mentioned "binddn" directive.
126 suffixmassage <virtual naming context> <real naming context>
128 All the directives starting with "rewrite" refer to the rewrite engine
129 that has been added to slapd. The "suffixmassage" directive was
130 introduced in back-ldap to allow suffix massaging while proxying.
131 It has been obsoleted by the rewriting tools. However, both for
132 backward compatibility and for ease of configuration when simple
133 suffix massage is required, it has been preserved. It wraps the
134 basic rewriting instruction that perform suffix massaging.
136 Note: this also fixes a flaw in suffix massaging, which operated
137 on (case insensitive) DNs instead of normalized DNs,
138 so "dc=foo, dc=com" would not match "dc=foo,dc=com".
140 See the "rewrite" section.
142 map {objectClass|attribute} {<source>|*} [<dest>|*]
144 objectClass/attribute mapping stuff. This has been inherited from
145 the work made by Mark Valence on the back-ldap backend.
146 See the mapping section.
152 A powerful (and in some sense dangerous) rewrite engine has been added
153 to both back-ldap and back-meta. While the former can gain limited
154 beneficial effects from rewriting stuff, the latter can become
155 an amazingly powerful tool.
157 Consider a couple of scenarios first.
159 1) Two directory servers share two levels of naming context;
160 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". Then, an
161 unambiguous back-meta can be configured as:
164 suffix "dc=foo,dc=com"
166 uri "ldap://a.foo.com/dc=a,dc=foo,dc=com"
168 uri "ldap://b.foo.com/dc=b,dc=foo,dc=com"
170 Operations directed to a specific target can be easily resolved
171 because there are no ambiguities. The only operation that may
172 resolve to multiple targets is a search with base "dc=foo,dc=com"
173 and scope at least "one", which results in spawning two searches
176 2a) Two directory servers don't share any portion of naming context,
177 but they'd present as a single DIT. [Caveat: uniqueness of
178 (massaged) entries among the two servers is assumed; integrity
179 checks risk to incurr in excessive overhead.]
180 Say we have "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to
181 present as branches of "dc=foo,dc=com", say "dc=a,dc=foo,dc=com"
182 and "dc=b,dc=foo,dc=com". Then we need to configure our back-meta as:
185 suffix "dc=foo,dc=com"
187 uri "ldap://a.bar.com/dc=a,dc=foo,dc=com"
188 suffixmassage "dc=a,dc=foo,dc=com" "dc=bar,dc=org"
190 uri "ldap://b.foo.com/dc=b,dc=foo,dc=com"
191 suffixmassage "dc=b,dc=foo,dc=com" "o=Foo,c=US"
193 Again, operations can be resolved without ambiguity, although
194 some rewriting is required. Notice that the virtual naming context
195 of each target is a branch of the database's naming context; it
196 is rewritten back and forth when operations are performed towards
197 the target servers. What "back and forth" means will be clarified
200 When a search with base "dc=foo,dc=com" is attempted, if the
201 scope is "base" it fails with "no such object"; in fact, the
202 common root of the two targets (prior to massaging) does not
203 exists. If the scope is "one", both targets are contacted with
204 the base replaced by each target's base; the scope is decreased
205 to "base". In general, the scope "one" search is honored,
206 and the scope is decreased, only when the incoming base is
207 at most one level lower of a target's naming context (prior
209 Finally, if the scope is "sub" the incoming base is replaced
210 by each target's unmassaged naming context, and the scope
213 2b) Consider the above reported scenario with the two servers
214 sharing the same naming context:
217 suffix "dc=foo,dc=com"
219 uri "ldap://a.bar.com/dc=foo,dc=com"
220 suffixmassage "dc=foo,dc=com" "dc=bar,dc=org"
222 uri "ldap://b.foo.com/dc=foo,dc=com"
223 suffixmassage "dc=foo,dc=com" "o=Foo,c=US"
225 All the previous considerations hold, except that now there is
226 no way to unambiguously resolve a dn. In this case, all the
227 operations that require an unambiguous target selection will
228 fail unless the dn is already cached or a default target has
235 This part of the document is being prepared. At present you may consult
236 the RATIONALE in libraries/librewrite.
240 - Objectclass/attribute mapping
242 This part of the document is being prepared. At present you may stick with
244 http://www.openldap.org/lists/openldap-devel/200102/msg00006.html
249 Note on ACLs: at present you may add whatever ACL rule you desire
250 to back-meta (as well as to back-ldap). However, the meaning of an ACL
251 on a proxy may require some considerations. Two philosophies may be
254 a) the remote server dictates the permissions; the proxy simply passes
255 back what it gets from the remore server.
257 b) the remote server unveils "everything"; the proxy is responsible
258 for protecting data from unauthorized access.
260 Of course the latter sounds unreasonable, but it is not. It is possible
261 to imagine scenarios in which a remote host discloses data that can
262 be considered "public" in an intranet, and a proxy that connects it to
263 the internet may impose additional constraints. To this purpose, the
264 proxy should be able to comply with all the ACL matching criteria that
265 the server supports. This has been achieved with regard to all the
266 criteria supported by slapd except a secial subtle case (please notify
267 me if you can find other exceptions).
270 access to dn="<dn>" attr=<attr>
271 by dnattr=<dnattr> read
274 cannot be matched IFF:
275 - the operation dn (the one that bound) is "<dn>", and
276 - the entry whose <attr> is being accessed is again <dn>, and
277 - the attribute that determines membership, <dnattr>, has not
278 been required (e.g. in a search)
280 In fact this ACL is resolved by slapd considering the entry it retrieved
281 from the remote server without requiring any further intervention of the
282 backend, so, if the <dnattr> attribute has not been fetched, the match
283 cannot be accomplished because the attribute is not present, not because
284 no value matches the requirement.