1 .TH SLAPD-META 5 "2 May 2002" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2002 The OpenLDAP Foundation, All Rights Reserved.
3 .\" Copying restrictions apply. See the COPYRIGHT file.
4 .\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
7 .\" Portions of this document should probably be moved to slapd-ldap(5)
8 .\" and maybe manual pages for librewrite.
11 slapd-meta \- metadirectory backend
19 performs basic LDAP proxying with respect to a set of remote LDAP
20 servers, called "targets".
21 The information contained in these servers can be presented as
22 belonging to a single Directory Information Tree (DIT).
24 A basic knowledge of the functionality of the
26 backend is recommended.
27 This backend has been designed as an enhancement of the ldap backend.
28 The two backends share many features (actually they also share
32 backend is intended to proxy operations directed to a single server, the
34 backend is mainly intended for proxying of multiple servers and possibly
35 naming context masquerading.
36 These features, although useful in many scenarios, may result in
37 excessive overhead for some applications, so its use should be
39 In the examples section, some typical scenarios will be discussed.
41 There are examples in various places in this document, as well as in the
42 slapd/back-meta/data/ directory in the OpenLDAP source tree.
46 options apply to the META backend database.
47 That is, they must follow a "database meta" line and come before any
48 subsequent "backend" or "database" lines.
49 Other database options are described in the
55 backend, operational attributes related to entry creation/modification
56 should not be used, as they would be passed to the target servers,
58 Moreover, it makes little sense to use such attributes in proxying, as
59 the proxy server doesn't actually store data, so it should have no
60 knowledge of such attributes.
61 While code to strip the modification attributes has been put in place
62 (and #ifdef'd), it implies unmotivated overhead.
63 So it is strongly recommended to set
72 .SH SPECIAL CONFIGURATION DIRECTIVES
73 Target configuration starts with the "uri" directive.
74 All the configuration directives that are not specific to targets
75 should be defined first for clarity, including those that are common
79 .B default-target none
80 This directive forces the backend to reject all those operations
81 that must resolve to a single target in case none or multiple
83 They include: add, delete, modify, modrdn; compare is not included, as
84 well as bind since, as they don't alter entries, in case of multiple
85 matches an attempt is made to perform the operation on any candidate
86 target, with the constraint that at most one must succeed.
87 This directive can also be used when processing targets to mark a
88 specific target as default.
90 .B dncache-ttl {forever|disabled|<ttl>}
91 This directive sets the time-to-live of the DN cache.
92 This caches the target that holds a given DN to speed up target
93 selection in case multiple targets would result from an uncached
94 search; forever means cache never expires; disabled means no DN
95 caching; otherwise a valid ( > 0 ) ttl in seconds is required.
96 .SH TARGET SPECIFICATION
97 Target specification starts with a "uri" directive:
99 .B uri <protocol>://[<host>[:<port>]]/<naming context>
100 The "server" directive that was allowed in the LDAP backend (although
101 deprecated) has been discarded in the Meta backend.
102 The <protocol> part can be anything ldap_initialize(3) accepts
103 ({ldap|ldaps|ldapi} and variants); <host> and <port> may be omitted,
104 defaulting to whatever is set in /etc/ldap.conf.
105 The <naming context> part is mandatory.
106 It must end with one of the naming contexts defined for the backend,
111 suffix "\fBdc=foo,dc=com\fP"
112 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
116 The <naming context> part doesn't need to be unique across the targets;
117 it may also match one of the values of the "suffix" directive.
119 .B default-target [<target>]
120 The "default-target" directive can also be used during target specification.
121 With no arguments it marks the current target as the default.
122 The optional number marks target <target> as the default one, starting
124 Target <target> must be defined.
126 .B binddn "<administrative DN for access control purposes>"
127 This directive, as in the LDAP backend, allows to define the DN that is
128 used to query the target server for acl checking; it should have read
129 access on the target server to attributes used on the proxy for acl
131 There is no risk of giving away such values; they are only used to
134 .B bindpw <password for access control purposes>
135 This directive sets the password for acl checking in conjunction
136 with the above mentioned "binddn" directive.
138 .B pseudorootdn "<substitute DN in case of rootdn bind>"
139 This directive, if present, sets the DN that will be substituted to
140 the bind DN if a bind with the backend's "rootdn" succeeds.
141 The true "rootdn" of the target server ought not be used; an arbitrary
142 administrative DN should used instead.
144 .B pseudorootpw "<substitute password in case of rootdn bind>"
145 This directive sets the credential that will be used in case a bind
146 with the backend's "rootdn" succeeds, and the bind is propagated to
147 the target using the "pseudorootdn" DN.
149 Note: cleartext credentials must be supplied here; as a consequence,
150 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
153 The rewrite options are described in the "REWRITING" section.
155 .B suffixmassage "<virtual naming context>" "<real naming context>"
156 All the directives starting with "rewrite" refer to the rewrite engine
157 that has been added to slapd.
158 The "suffixmassage" directive was introduced in the LDAP backend to
159 allow suffix massaging while proxying.
160 It has been obsoleted by the rewriting tools.
161 However, both for backward compatibility and for ease of configuration
162 when simple suffix massage is required, it has been preserved.
163 It wraps the basic rewriting instructions that perform suffix
166 Note: this also fixes a flaw in suffix massaging, which operated
167 on (case insensitive) DNs instead of normalized DNs,
168 so "dc=foo, dc=com" would not match "dc=foo,dc=com".
170 See the "REWRITING" section.
172 .B map {objectClass|attribute} {<source>|*} [<dest>|*]
173 This maps object classes and attributes as in the LDAP backend.
177 A powerful (and in some sense dangerous) rewrite engine has been added
178 to both the LDAP and Meta backends.
179 While the former can gain limited beneficial effects from rewriting
180 stuff, the latter can become an amazingly powerful tool.
182 Consider a couple of scenarios first.
184 1) Two directory servers share two levels of naming context;
185 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
186 Then, an unambiguous Meta database can be configured as:
191 suffix "\fBdc=foo,dc=com\fP"
192 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
193 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
197 Operations directed to a specific target can be easily resolved
198 because there are no ambiguities.
199 The only operation that may resolve to multiple targets is a search
200 with base "dc=foo,dc=com" and scope at least "one", which results in
201 spawning two searches to the targets.
203 2a) Two directory servers don't share any portion of naming context,
204 but they'd present as a single DIT
205 [Caveat: uniqueness of (massaged) entries among the two servers is
206 assumed; integrity checks risk to incur in excessive overhead and have
207 not been implemented].
208 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
209 and we'd like them to appear as branches of "dc=foo,dc=com", say
210 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
211 Then we need to configure our Meta backend as:
216 suffix "dc=foo,dc=com"
218 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
219 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
221 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
222 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
226 Again, operations can be resolved without ambiguity, although
227 some rewriting is required.
228 Notice that the virtual naming context of each target is a branch of
229 the database's naming context; it is rewritten back and forth when
230 operations are performed towards the target servers.
231 What "back and forth" means will be clarified later.
233 When a search with base "dc=foo,dc=com" is attempted, if the
234 scope is "base" it fails with "no such object"; in fact, the
235 common root of the two targets (prior to massaging) does not
237 If the scope is "one", both targets are contacted with the base
238 replaced by each target's base; the scope is derated to "base".
239 In general, a scope "one" search is honored, and the scope is derated,
240 only when the incoming base is at most one level lower of a target's
241 naming context (prior to massaging).
243 Finally, if the scope is "sub" the incoming base is replaced
244 by each target's unmassaged naming context, and the scope
247 2b) Consider the above reported scenario with the two servers
248 sharing the same naming context:
253 suffix "\fBdc=foo,dc=com\fP"
255 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
256 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
258 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
259 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
263 All the previous considerations hold, except that now there is
264 no way to unambiguously resolve a DN.
265 In this case, all the operations that require an unambiguous target
266 selection will fail unless the DN is already cached or a default
268 Practical configurations may result as a combination of all the
271 Note on ACLs: at present you may add whatever ACL rule you desire
272 to to the Meta (and LDAP) backends.
273 However, the meaning of an ACL on a proxy may require some
275 Two philosophies may be considered:
277 a) the remote server dictates the permissions; the proxy simply passes
278 back what it gets from the remote server.
280 b) the remote server unveils "everything"; the proxy is responsible
281 for protecting data from unauthorized access.
283 Of course the latter sounds unreasonable, but it is not.
284 It is possible to imagine scenarios in which a remote host discloses
285 data that can be considered "public" inside an intranet, and a proxy
286 that connects it to the internet may impose additional constraints.
287 To this purpose, the proxy should be able to comply with all the ACL
288 matching criteria that the server supports.
289 This has been achieved with regard to all the criteria supported by
290 slapd except a special subtle case (please drop me a note if you can
291 find other exceptions: <ando@openldap.org>).
296 access to dn="<dn>" attr=<attr>
297 by dnattr=<dnattr> read
302 cannot be matched iff the attribute that is being requested, <attr>,
303 is NOT <dnattr>, and the attribute that determines membership,
304 <dnattr>, has not been requested (e.g. in a search)
306 In fact this ACL is resolved by slapd using the portion of entry it
307 retrieved from the remote server without requiring any further
308 intervention of the backend, so, if the <dnattr> attribute has not
309 been fetched, the match cannot be assessed because the attribute is
310 not present, not because no value matches the requirement!
312 Note on ACLs and attribute mapping: ACLs are applied to the mapped
313 attributes; for instance, if the attribute locally known as "foo" is
314 mapped to "bar" on a remote server, then local ACLs apply to attribute
315 "foo" and are totally unaware of its remote name.
316 The remote server will check permissions for "bar", and the local
317 server will possibly enforce additional restrictions to "foo".
319 .\" If this section is moved, also update the reference in
320 .\" libraries/librewrite/RATIONALE.
323 A string is rewritten according to a set of rules, called a `rewrite
325 The rules are based on Regular Expressions (POSIX regex) with
326 substring matching; extensions are planned to allow basic variable
327 substitution and map resolution of substrings.
328 The behavior of pattern matching/substitution can be altered by a set
331 The underlying concept is to build a lightweight rewrite module
332 for the slapd server (initially dedicated to the LDAP backend).
334 An incoming string is matched agains a set of rules.
335 Rules are made of a match pattern, a substitution pattern and a set of
337 In case of match a string rewriting is performed according to the
338 substitution pattern that allows to refer to substrings matched in the
340 The actions, if any, are finally performed.
341 The substitution pattern allows map resolution of substrings.
342 A map is a generic object that maps a substitution pattern to a value.
343 .SH "Pattern Matching Flags"
346 honors case in matching (default is case insensitive)
349 use POSIX Basic Regular Expressions (default is Extended)
353 apply the rule once only (default is recursive)
356 stop applying rules in case of match.
359 stop current operation if the rule matches, and issue an `unwilling to
363 jump n rules back and forth (watch for loops!).
364 Note that `G{1}' is implicit in every rule.
367 ignores errors in rule; this means, in case of error, e.g. issued by a
368 map, the error is treated as a missed match.
369 The `unwilling to perform' is not overridden.
371 The ordering of the flags is significant.
372 For instance: `IG{2}' means ignore errors and jump two lines ahead
373 both in case of match and in case of error, while `G{2}I' means ignore
374 errors, but jump thwo lines ahead only in case of match.
376 More flags (mainly Action Flags) will be added as needed.
377 .SH "Pattern matching:"
380 .SH "Substitution Pattern Syntax:"
381 Everything starting with `%' requires substitution;
383 the only obvious exception is `%%', which is left as is;
385 the basic substitution is `%d', where `d' is a digit;
386 0 means the whole string, while 1-9 is a submatch, as discussed in
389 a `%' followed by a `{' invokes an advanced substitution.
393 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
396 where <name> must be a legal name for the map, i.e.
400 <name> ::= [a-z][a-z0-9]* (case insensitive)
401 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
405 and <substitution> must be a legal substitution
406 pattern, with no limits on the nesting level.
411 sub context invocation; <name> must be a legal, already defined
415 external command invocation; <name> must refer to a legal, already
416 defined command name (NOT IMPL.)
419 variable assignment; <name> defines a variable in the running
420 operation structure which can be dereferenced later; operator
422 assigns a variable in the rewrite context scope; operator
424 assigns a variable that scopes the entire session, e.g. its value
425 can be derefenced later by other rewrite contexts
428 variable dereferencing; <name> must refer to a variable that is
429 defined and assigned for the running operation; operator
431 dereferences a variable scoping the rewrite context; operator
433 dereferences a variable scoping the whole session, e.g. the value
434 is passed across rewrite contexts
437 parameter dereferencing; <name> must refer to an existing parameter;
438 the idea is to make some run-time parameters set by the system
439 available to the rewrite engine, as the client host name, the bind DN
440 if any, constant parameters initialized at config time, and so on;
441 no parameter is currently set by either
445 but constant parameters can be defined in the configuration file
450 Substitution escaping has been delegated to the `%' symbol,
451 which is used instead of `\e' in string substitution patterns
452 because `\e' is already escaped by slapd's low level parsing routines;
455 escaping requires two `\e' symbols, e.g. `\fB.*\e.foo\e.bar\fP' must
456 be written as `\fB.*\e\e.foo\e\e.bar\fP'.
458 .\" The symbol can be altered at will by redefining the related macro in
461 .SH "Rewrite context:"
462 A rewrite context is a set of rules which are applied in sequence.
463 The basic idea is to have an application initialize a rewrite
464 engine (think of Apache's mod_rewrite ...) with a set of rewrite
465 contexts; when string rewriting is required, one invokes the
466 appropriate rewrite context with the input string and obtains the
467 newly rewritten one if no errors occur.
469 Each basic server operation is associated to a rewrite context;
470 they are divided in two main groups: client \-> server and
471 server \-> client rewriting.
477 (default) if defined and no specific context
495 searchResult search (only if defined; no default;
496 acts on DN and DN-syntax attributes
498 matchedDn all ops (only if defined; no default;
499 NOT IMPL. except in search)
503 .SH "Basic configuration syntax"
505 .B rewriteEngine { on | off }
506 If `on', the requested rewriting is performed; if `off', no
507 rewriting takes place (an easy way to stop rewriting without
508 altering too much the configuration file).
510 .B rewriteContext <context name> "[ alias <aliased context name> ]"
511 <Context name> is the name that identifies the context, i.e. the name
512 used by the application to refer to the set of rules it contains.
513 It is used also to reference sub contexts in string rewriting.
514 A context may aliase another one.
515 In this case the alias context contains no rule, and any reference to
516 it will result in accessing the aliased one.
518 .B rewriteRule "<regex pattern>" "<substitution pattern>" "[ <flags> ]"
519 Determines how a tring can be rewritten if a pattern is matched.
520 Examples are reported below.
521 .SH "Additional configuration syntax:"
523 .B rewriteMap "<map name>" "<map type>" "[ <map attrs> ]"
524 Allows to define a map that transforms substring rewriting into
526 The map is referenced inside the substitution pattern of a rule.
528 .B rewriteParam <param name> <param value>
529 Sets a value with global scope, that can be dereferenced by the
530 command `%{$paramName}'.
532 .B rewriteMaxPasses <number of passes>
533 Sets the maximum number of total rewriting passes that can be
534 performed in a single rewrite operation (to avoid loops).
535 .SH "Configuration examples:"
537 # set to `off' to disable rewriting
540 # Everything defined here goes into the `default' context.
541 # This rule changes the naming context of anything sent
542 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
544 rewriteRule "(.*)dc=home,[ ]?dc=net"
545 "%1dc=OpenLDAP, dc=org" ":"
547 # since a pretty/normalized DN does not include spaces
548 # after rdn separators, e.g. `,', this rule suffices:
550 rewriteRule "(.*)dc=home,dc=net"
551 "%1dc=OpenLDAP,dc=org" ":"
553 # Start a new context (ends input of the previous one).
554 # This rule adds blanks between DN parts if not present.
555 rewriteContext addBlanks
556 rewriteRule "(.*),([^ ].*)" "%1, %2"
558 # This one eats blanks
559 rewriteContext eatBlanks
560 rewriteRule "(.*),[ ](.*)" "%1,%2"
562 # Here control goes back to the default rewrite
563 # context; rules are appended to the existing ones.
564 # anything that gets here is piped into rule `addBlanks'
565 rewriteContext default
566 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
568 .\" # Anything with `uid=username' is looked up in
569 .\" # /etc/passwd for gecos (I know it's nearly useless,
570 .\" # but it is there just as a guideline to implementing
572 .\" # Note the `I' flag that leaves `uid=username' in place
573 .\" # if `username' does not have a valid account, and the
574 .\" # `:' that forces the rule to be processed exactly once.
575 .\" rewriteContext uid2Gecos
576 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
577 .\" "%1cn=%2{xpasswd},%3" "I:"
579 .\" # Finally, in a bind, if one uses a `uid=username' DN,
580 .\" # it is rewritten in `cn=name surname' if possible.
581 .\" rewriteContext bindDn
582 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
584 # Rewrite the search base according to `default' rules.
585 rewriteContext searchBase alias default
587 # Search results with OpenLDAP DN are rewritten back with
588 # `dc=home,dc=net' naming context, with spaces eaten.
589 rewriteContext searchResult
590 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
591 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
593 # Bind with email instead of full DN: we first need
594 # an ldap map that turns attributes into a DN (the
595 # argument used when invoking the map is appended to
596 # the URI and acts as the filter portion)
597 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
599 # Then we need to detect DN made up of a single email,
600 # e.g. `mail=someone@example.com'; note that the rule
601 # in case of match stops rewriting; in case of error,
602 # it is ignored. In case we are mapping virtual
603 # to real naming contexts, we also need to rewrite
604 # regular DNs, because the definition of a bindDn
605 # rewrite context overrides the default definition.
606 rewriteContext bindDn
607 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" "@I"
609 # This is a rather sophisticated example. It massages a
610 # search filter in case who performs the search has
611 # administrative privileges. First we need to keep
612 # track of the bind DN of the incoming request, which is
613 # stored in a variable called `binddn' with session scope,
614 # and left in place to allow regular binding:
615 rewriteContext bindDn
616 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
618 # A search filter containing `uid=' is rewritten only
619 # if an appropriate DN is bound.
620 # To do this, in the first rule the bound DN is
621 # dereferenced, while the filter is decomposed in a
622 # prefix, in the value of the `uid=<arg>' AVA, and
623 # in a suffix. A tag `<>' is appended to the DN.
624 # If the DN refers to an entry in the `ou=admin' subtree,
625 # the filter is rewritten OR-ing the `uid=<arg>' with
626 # `cn=<arg>'; otherwise it is left as is. This could be
627 # useful, for instance, to allow apache's auth_ldap-1.4
628 # module to authenticate users with both `uid' and
629 # `cn', but only if the request comes from a possible
630 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
631 rewriteContext searchFilter
632 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
633 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
635 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
636 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" "@I"
637 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
639 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
640 In case the rewritten DN is an LDAP URI, the operation is initiated
641 towards the host[:port] indicated in the uri, if it does not refer
646 rewriteRule '^cn=root,.*' '%0' 'G{3}'
647 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' '@'
648 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' '@'
649 rewriteRule '.*' 'ldap://ldap3.my.org/%0' '@'
652 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
656 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' '@'
659 with the advantage of saving one rewrite pass ...)
663 default slapd configuration file