1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2005 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
53 Note: In early versions of back-ldap and back-meta it was recommended to always set
66 This is because operational attributes related to entry creation and
67 modification should not be proxied, as they could be mistakenly written
68 to the target server(s), generating an error.
69 The current implementation automatically sets lastmod to off, so its use
70 is redundant and should be omitted, because the lastmod directive will
71 be deprecated in the future.
73 .SH SPECIAL CONFIGURATION DIRECTIVES
74 Target configuration starts with the "uri" directive.
75 All the configuration directives that are not specific to targets
76 should be defined first for clarity, including those that are common
81 .B default-target none
82 This directive forces the backend to reject all those operations
83 that must resolve to a single target in case none or multiple
85 They include: add, delete, modify, modrdn; compare is not included, as
86 well as bind since, as they don't alter entries, in case of multiple
87 matches an attempt is made to perform the operation on any candidate
88 target, with the constraint that at most one must succeed.
89 This directive can also be used when processing targets to mark a
90 specific target as default.
93 .B dncache-ttl {forever|disabled|<ttl>}
94 This directive sets the time-to-live of the DN cache.
95 This caches the target that holds a given DN to speed up target
96 selection in case multiple targets would result from an uncached
97 search; forever means cache never expires; disabled means no DN
98 caching; otherwise a valid ( > 0 ) ttl in seconds is required.
101 .B nretries {forever|never|<nretries>}
102 This directive defines how many times a bind should be retried
103 in case of temporary failure in contacting a target. If defined
104 before any target specification, it applies to all targets (by default,
106 the global value can be overridden by redefinitions inside each target
110 .B onerr {CONTINUE|stop}
111 This directive allows to select the behavior in case an error is returned
112 by one target during a search.
113 The default, \fBcontinue\fP, consists in continuing the operation,
114 trying to return as much data as possible.
115 If this statement is set to \fBstop\fP, the search is terminated as soon
116 as an error is returned by one target, and the error is immediately
117 propagated to the client.
120 .B rebind-as-user {NO|yes}
121 If this option is given, the client's bind credentials are remembered
122 for rebinds when chasing referrals.
124 .SH TARGET SPECIFICATION
125 Target specification starts with a "uri" directive:
128 .B uri <protocol>://[<host>[:<port>]]/<naming context>
129 The "server" directive that was allowed in the LDAP backend (although
130 deprecated) has been completely discarded in the Meta backend.
131 The <protocol> part can be anything
132 .BR ldap_initialize (3)
133 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
134 omitted, defaulting to whatever is set in
136 The <naming context> part is mandatory.
137 It must end with one of the naming contexts defined for the backend,
142 suffix "\fBdc=foo,dc=com\fP"
143 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
148 The <naming context> part doesn't need to be unique across the targets;
149 it may also match one of the values of the "suffix" directive.
150 Multiple URIs may be defined in a single argument. The URIs must
151 be separated by TABs (e.g. '\\t'; commas or spaces, unlike back-ldap,
153 because they are legal in the <naming context>, and we don't want to use
154 URL-encoded <naming context>s), and the additional URIs must have
155 no <naming context> part. This causes the underlying library
156 to contact the first server of the list that responds.
157 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
158 of the same server, the directive
161 suffix "\fBdc=foo,dc=com\fP"
162 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP ldap://l2.foo.com/"
167 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
172 .B default-target [<target>]
173 The "default-target" directive can also be used during target specification.
174 With no arguments it marks the current target as the default.
175 The optional number marks target <target> as the default one, starting
177 Target <target> must be defined.
180 .B acl-authcDN "<administrative DN for access control purposes>"
181 DN which is used to query the target server for acl checking,
182 as in the LDAP backend; it is supposed to have read access
183 on the target server to attributes used on the proxy for acl checking.
184 There is no risk of giving away such values; they are only used to
186 .B The acl-authcDN identity is by no means implicitly used by the proxy
187 .B when the client connects anonymously.
190 .B acl-passwd <password>
191 Password used with the
197 .B chase-referrals {YES|no}
198 enable/disable automatic referral chasing, which is delegated to the
199 underlying libldap, with rebinding eventually performed if the
200 \fBrebind-as-user\fP directive is used. The default is to chase referrals.
201 If set before any target specification, it affects all targets, unless
202 overridden by any per-target directive.
205 .B tls {[try-]start|[try-]propagate}
206 execute the start TLS extended operation when the connection is initialized;
207 only works if the URI directive protocol scheme is not \fBldaps://\fP.
208 \fBpropagate\fP issues the Start TLS exop only if the original
210 The \fBtry-\fP prefix instructs the proxy to continue operations
211 if start TLS failed; its use is highly deprecated.
212 If set before any target specification, it affects all targets, unless
213 overridden by any per-target directive.
216 .B t-f-support {NO|yes|discover}
217 enable if the remote server supports absolute filters
218 (see \fIdraft-zeilenga-ldap-t-f\fP for details).
221 support is detected by reading the remote server's root DSE.
222 If set before any target specification, it affects all targets, unless
223 overridden by any per-target directive.
226 .B timeout [{add|delete|modify|modrdn}=]<val> [...]
227 This directive allows to set per-database, per-target and per-operation
229 If no operation is specified, it affects all.
230 Currently, only write operations are addressed, because searches
231 can already be limited by means of the
235 for details), and other operations are not supposed to incur into the
237 Note: if the timelimit is exceeded, the operation is abandoned;
238 the protocol does not provide any means to rollback the operation,
239 so the client will not know if the operation eventually succeeded or not.
240 If set before any target specification, it affects all targets, unless
241 overridden by any per-target directive.
244 .B idle-timeout <time>
245 This directive causes a cached connection to be dropped an recreated
246 after it has been idle for the specified time.
249 .B pseudorootdn "<substitute DN in case of rootdn bind>"
250 This directive, if present, sets the DN that will be substituted to
251 the bind DN if a bind with the backend's "rootdn" succeeds.
252 The true "rootdn" of the target server ought not be used; an arbitrary
253 administrative DN should used instead.
256 .B pseudorootpw "<substitute password in case of rootdn bind>"
257 This directive sets the credential that will be used in case a bind
258 with the backend's "rootdn" succeeds, and the bind is propagated to
259 the target using the "pseudorootdn" DN.
261 Note: cleartext credentials must be supplied here; as a consequence,
262 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
265 .B pseudoroot-bind-defer {NO|yes}
266 This directive, when set to
268 causes the authentication to the remote servers with the pseudo-root
269 identity to be deferred until actually needed by subsequent operations.
273 The rewrite options are described in the "REWRITING" section.
276 .B suffixmassage "<virtual naming context>" "<real naming context>"
277 All the directives starting with "rewrite" refer to the rewrite engine
278 that has been added to slapd.
279 The "suffixmassage" directive was introduced in the LDAP backend to
280 allow suffix massaging while proxying.
281 It has been obsoleted by the rewriting tools.
282 However, both for backward compatibility and for ease of configuration
283 when simple suffix massage is required, it has been preserved.
284 It wraps the basic rewriting instructions that perform suffix
285 massaging. See the "REWRITING" section for a detailed list
286 of the rewrite rules it implies.
288 Note: this also fixes a flaw in suffix massaging, which operated
289 on (case insensitive) DNs instead of normalized DNs,
290 so "dc=foo, dc=com" would not match "dc=foo,dc=com".
292 See the "REWRITING" section.
295 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
296 This maps object classes and attributes as in the LDAP backend.
300 A powerful (and in some sense dangerous) rewrite engine has been added
301 to both the LDAP and Meta backends.
302 While the former can gain limited beneficial effects from rewriting
303 stuff, the latter can become an amazingly powerful tool.
305 Consider a couple of scenarios first.
307 1) Two directory servers share two levels of naming context;
308 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
309 Then, an unambiguous Meta database can be configured as:
314 suffix "\fBdc=foo,dc=com\fP"
315 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
316 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
320 Operations directed to a specific target can be easily resolved
321 because there are no ambiguities.
322 The only operation that may resolve to multiple targets is a search
323 with base "dc=foo,dc=com" and scope at least "one", which results in
324 spawning two searches to the targets.
326 2a) Two directory servers don't share any portion of naming context,
327 but they'd present as a single DIT
328 [Caveat: uniqueness of (massaged) entries among the two servers is
329 assumed; integrity checks risk to incur in excessive overhead and have
330 not been implemented].
331 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
332 and we'd like them to appear as branches of "dc=foo,dc=com", say
333 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
334 Then we need to configure our Meta backend as:
339 suffix "dc=foo,dc=com"
341 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
342 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
344 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
345 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
349 Again, operations can be resolved without ambiguity, although
350 some rewriting is required.
351 Notice that the virtual naming context of each target is a branch of
352 the database's naming context; it is rewritten back and forth when
353 operations are performed towards the target servers.
354 What "back and forth" means will be clarified later.
356 When a search with base "dc=foo,dc=com" is attempted, if the
357 scope is "base" it fails with "no such object"; in fact, the
358 common root of the two targets (prior to massaging) does not
360 If the scope is "one", both targets are contacted with the base
361 replaced by each target's base; the scope is derated to "base".
362 In general, a scope "one" search is honored, and the scope is derated,
363 only when the incoming base is at most one level lower of a target's
364 naming context (prior to massaging).
366 Finally, if the scope is "sub" the incoming base is replaced
367 by each target's unmassaged naming context, and the scope
370 2b) Consider the above reported scenario with the two servers
371 sharing the same naming context:
376 suffix "\fBdc=foo,dc=com\fP"
378 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
379 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
381 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
382 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
386 All the previous considerations hold, except that now there is
387 no way to unambiguously resolve a DN.
388 In this case, all the operations that require an unambiguous target
389 selection will fail unless the DN is already cached or a default
391 Practical configurations may result as a combination of all the
394 Note on ACLs: at present you may add whatever ACL rule you desire
395 to to the Meta (and LDAP) backends.
396 However, the meaning of an ACL on a proxy may require some
398 Two philosophies may be considered:
400 a) the remote server dictates the permissions; the proxy simply passes
401 back what it gets from the remote server.
403 b) the remote server unveils "everything"; the proxy is responsible
404 for protecting data from unauthorized access.
406 Of course the latter sounds unreasonable, but it is not.
407 It is possible to imagine scenarios in which a remote host discloses
408 data that can be considered "public" inside an intranet, and a proxy
409 that connects it to the internet may impose additional constraints.
410 To this purpose, the proxy should be able to comply with all the ACL
411 matching criteria that the server supports.
412 This has been achieved with regard to all the criteria supported by
413 slapd except a special subtle case (please drop me a note if you can
414 find other exceptions: <ando@openldap.org>).
419 access to dn="<dn>" attr=<attr>
420 by dnattr=<dnattr> read
425 cannot be matched iff the attribute that is being requested, <attr>,
426 is NOT <dnattr>, and the attribute that determines membership,
427 <dnattr>, has not been requested (e.g. in a search)
429 In fact this ACL is resolved by slapd using the portion of entry it
430 retrieved from the remote server without requiring any further
431 intervention of the backend, so, if the <dnattr> attribute has not
432 been fetched, the match cannot be assessed because the attribute is
433 not present, not because no value matches the requirement!
435 Note on ACLs and attribute mapping: ACLs are applied to the mapped
436 attributes; for instance, if the attribute locally known as "foo" is
437 mapped to "bar" on a remote server, then local ACLs apply to attribute
438 "foo" and are totally unaware of its remote name.
439 The remote server will check permissions for "bar", and the local
440 server will possibly enforce additional restrictions to "foo".
442 .\" If this section is moved, also update the reference in
443 .\" libraries/librewrite/RATIONALE.
446 A string is rewritten according to a set of rules, called a `rewrite
448 The rules are based on POSIX (''extended'') regular expressions (regex)
449 with substring matching; basic variable substitution and map resolution
450 of substrings is allowed by specific mechanisms detailed in the following.
451 The behavior of pattern matching/substitution can be altered by a set
454 The underlying concept is to build a lightweight rewrite module
455 for the slapd server (initially dedicated to the LDAP backend).
457 An incoming string is matched against a set of rules.
458 Rules are made of a regex match pattern, a substitution pattern
459 and a set of actions, described by a set of flags.
460 In case of match a string rewriting is performed according to the
461 substitution pattern that allows to refer to substrings matched in the
463 The actions, if any, are finally performed.
464 The substitution pattern allows map resolution of substrings.
465 A map is a generic object that maps a substitution pattern to a value.
466 The flags are divided in "Pattern matching Flags" and "Action Flags";
467 the former alter the regex match pattern behavior while the latter
468 alter the action that is taken after substitution.
469 .SH "Pattern Matching Flags"
472 honors case in matching (default is case insensitive)
475 use POSIX ''basic'' regular expressions (default is ''extended'')
480 recursive passes for a specific rule; does not alter the max total count
481 of passes, so it can only enforce a stricter limit for a specific rule.
485 apply the rule once only (default is recursive)
488 stop applying rules in case of match; the current rule is still applied
489 recursively; combine with `:' to apply the current rule only once
493 stop current operation if the rule matches, and issue an `unwilling to
499 rules back and forth (watch for loops!).
500 Note that `G{1}' is implicit in every rule.
503 ignores errors in rule; this means, in case of error, e.g. issued by a
504 map, the error is treated as a missed match.
505 The `unwilling to perform' is not overridden.
511 as return code if the rule matches; the flag does not alter the recursive
512 behavior of the rule, so, to have it performed only once, it must be used
513 in combination with `:', e.g.
515 returns the value `16' after exactly one execution of the rule, if the
517 As a consequence, its behavior is equivalent to `@', with the return
520 or, in other words, `@' is equivalent to `U{0}'.
521 By convention, the freely available codes are above 16 included;
522 the others are reserved.
524 The ordering of the flags can be significant.
525 For instance: `IG{2}' means ignore errors and jump two lines ahead
526 both in case of match and in case of error, while `G{2}I' means ignore
527 errors, but jump two lines ahead only in case of match.
529 More flags (mainly Action Flags) will be added as needed.
530 .SH "Pattern matching:"
535 .SH "Substitution Pattern Syntax:"
536 Everything starting with `%' requires substitution;
538 the only obvious exception is `%%', which is left as is;
540 the basic substitution is `%d', where `d' is a digit;
541 0 means the whole string, while 1-9 is a submatch;
543 a `%' followed by a `{' invokes an advanced substitution.
547 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
550 where <name> must be a legal name for the map, i.e.
554 <name> ::= [a-z][a-z0-9]* (case insensitive)
555 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
559 and <substitution> must be a legal substitution
560 pattern, with no limits on the nesting level.
565 sub context invocation; <name> must be a legal, already defined
569 external command invocation; <name> must refer to a legal, already
570 defined command name (NOT IMPL.)
573 variable assignment; <name> defines a variable in the running
574 operation structure which can be dereferenced later; operator
576 assigns a variable in the rewrite context scope; operator
578 assigns a variable that scopes the entire session, e.g. its value
579 can be dereferenced later by other rewrite contexts
582 variable dereferencing; <name> must refer to a variable that is
583 defined and assigned for the running operation; operator
585 dereferences a variable scoping the rewrite context; operator
587 dereferences a variable scoping the whole session, e.g. the value
588 is passed across rewrite contexts
591 parameter dereferencing; <name> must refer to an existing parameter;
592 the idea is to make some run-time parameters set by the system
593 available to the rewrite engine, as the client host name, the bind DN
594 if any, constant parameters initialized at config time, and so on;
595 no parameter is currently set by either
599 but constant parameters can be defined in the configuration file
604 Substitution escaping has been delegated to the `%' symbol,
605 which is used instead of `\e' in string substitution patterns
606 because `\e' is already escaped by slapd's low level parsing routines;
607 as a consequence, regex escaping requires two `\e' symbols,
608 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
610 .\" The symbol can be altered at will by redefining the related macro in
613 .SH "Rewrite context:"
614 A rewrite context is a set of rules which are applied in sequence.
615 The basic idea is to have an application initialize a rewrite
616 engine (think of Apache's mod_rewrite ...) with a set of rewrite
617 contexts; when string rewriting is required, one invokes the
618 appropriate rewrite context with the input string and obtains the
619 newly rewritten one if no errors occur.
621 Each basic server operation is associated to a rewrite context;
622 they are divided in two main groups: client \-> server and
623 server \-> client rewriting.
629 (default) if defined and no specific context
634 searchFilterAttrDN search
636 compareAttrDN compare AVA
640 modifyAttrDN modify AVA
644 exopPasswdDN passwd exop DN if proxy
652 searchResult search (only if defined; no default;
653 acts on DN and DN-syntax attributes
655 searchAttrDN search AVA
656 matchedDN all ops (only if applicable)
660 .SH "Basic configuration syntax"
662 .B rewriteEngine { on | off }
663 If `on', the requested rewriting is performed; if `off', no
664 rewriting takes place (an easy way to stop rewriting without
665 altering too much the configuration file).
667 .B rewriteContext <context name> "[ alias <aliased context name> ]"
668 <Context name> is the name that identifies the context, i.e. the name
669 used by the application to refer to the set of rules it contains.
670 It is used also to reference sub contexts in string rewriting.
671 A context may alias another one.
672 In this case the alias context contains no rule, and any reference to
673 it will result in accessing the aliased one.
675 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
676 Determines how a string can be rewritten if a pattern is matched.
677 Examples are reported below.
678 .SH "Additional configuration syntax:"
680 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
681 Allows to define a map that transforms substring rewriting into
683 The map is referenced inside the substitution pattern of a rule.
685 .B rewriteParam <param name> <param value>
686 Sets a value with global scope, that can be dereferenced by the
687 command `%{$paramName}'.
689 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
690 Sets the maximum number of total rewriting passes that can be
691 performed in a single rewrite operation (to avoid loops).
692 A safe default is set to 100; note that reaching this limit is still
693 treated as a success; recursive invocation of rules is simply
695 The count applies to the rewriting operation as a whole, not
696 to any single rule; an optional per-rule limit can be set.
697 This limit is overridden by setting specific per-rule limits
698 with the `M{n}' flag.
699 .SH "Configuration examples:"
701 # set to `off' to disable rewriting
704 # the rules the "suffixmassage" directive implies
706 # all dataflow from client to server referring to DNs
707 rewriteContext default
708 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
710 rewriteContext searchFilter
711 # all dataflow from server to client
712 rewriteContext searchResult
713 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
714 rewriteContext searchAttrDN alias searchResult
715 rewriteContext matchedDN alias searchResult
717 # Everything defined here goes into the `default' context.
718 # This rule changes the naming context of anything sent
719 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
721 rewriteRule "(.*)dc=home,[ ]?dc=net"
722 "%1dc=OpenLDAP, dc=org" ":"
724 # since a pretty/normalized DN does not include spaces
725 # after rdn separators, e.g. `,', this rule suffices:
727 rewriteRule "(.*)dc=home,dc=net"
728 "%1dc=OpenLDAP,dc=org" ":"
730 # Start a new context (ends input of the previous one).
731 # This rule adds blanks between DN parts if not present.
732 rewriteContext addBlanks
733 rewriteRule "(.*),([^ ].*)" "%1, %2"
735 # This one eats blanks
736 rewriteContext eatBlanks
737 rewriteRule "(.*),[ ](.*)" "%1,%2"
739 # Here control goes back to the default rewrite
740 # context; rules are appended to the existing ones.
741 # anything that gets here is piped into rule `addBlanks'
742 rewriteContext default
743 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
745 .\" # Anything with `uid=username' is looked up in
746 .\" # /etc/passwd for gecos (I know it's nearly useless,
747 .\" # but it is there just as a guideline to implementing
749 .\" # Note the `I' flag that leaves `uid=username' in place
750 .\" # if `username' does not have a valid account, and the
751 .\" # `:' that forces the rule to be processed exactly once.
752 .\" rewriteContext uid2Gecos
753 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
754 .\" "%1cn=%2{xpasswd},%3" "I:"
756 .\" # Finally, in a bind, if one uses a `uid=username' DN,
757 .\" # it is rewritten in `cn=name surname' if possible.
758 .\" rewriteContext bindDN
759 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
761 # Rewrite the search base according to `default' rules.
762 rewriteContext searchBase alias default
764 # Search results with OpenLDAP DN are rewritten back with
765 # `dc=home,dc=net' naming context, with spaces eaten.
766 rewriteContext searchResult
767 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
768 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
770 # Bind with email instead of full DN: we first need
771 # an ldap map that turns attributes into a DN (the
772 # argument used when invoking the map is appended to
773 # the URI and acts as the filter portion)
774 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
776 # Then we need to detect DN made up of a single email,
777 # e.g. `mail=someone@example.com'; note that the rule
778 # in case of match stops rewriting; in case of error,
779 # it is ignored. In case we are mapping virtual
780 # to real naming contexts, we also need to rewrite
781 # regular DNs, because the definition of a bindDn
782 # rewrite context overrides the default definition.
783 rewriteContext bindDN
784 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
786 # This is a rather sophisticated example. It massages a
787 # search filter in case who performs the search has
788 # administrative privileges. First we need to keep
789 # track of the bind DN of the incoming request, which is
790 # stored in a variable called `binddn' with session scope,
791 # and left in place to allow regular binding:
792 rewriteContext bindDN
793 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
795 # A search filter containing `uid=' is rewritten only
796 # if an appropriate DN is bound.
797 # To do this, in the first rule the bound DN is
798 # dereferenced, while the filter is decomposed in a
799 # prefix, in the value of the `uid=<arg>' AVA, and
800 # in a suffix. A tag `<>' is appended to the DN.
801 # If the DN refers to an entry in the `ou=admin' subtree,
802 # the filter is rewritten OR-ing the `uid=<arg>' with
803 # `cn=<arg>'; otherwise it is left as is. This could be
804 # useful, for instance, to allow apache's auth_ldap-1.4
805 # module to authenticate users with both `uid' and
806 # `cn', but only if the request comes from a possible
807 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
808 rewriteContext searchFilter
809 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
810 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
812 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
813 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
814 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
816 # This example shows how to strip unwanted DN-valued
817 # attribute values from a search result; the first rule
818 # matches DN values below "ou=People,dc=example,dc=com";
819 # in case of match the rewriting exits successfully.
820 # The second rule matches everything else and causes
821 # the value to be rejected.
822 rewriteContext searchResult
823 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
824 rewriteRule ".*" "" "#"
826 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
827 In case the rewritten DN is an LDAP URI, the operation is initiated
828 towards the host[:port] indicated in the uri, if it does not refer
833 rewriteRule '^cn=root,.*' '%0' 'G{3}'
834 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
835 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
836 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
839 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
843 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
846 with the advantage of saving one rewrite pass ...)
851 backend does not honor all ACL semantics as described in
852 .BR slapd.access (5).
853 In general, access checking is delegated to the remote server(s).
858 pseudo-attribute and to the other attribute values of the entries
861 operation is honored, which is performed by the frontend.
863 .SH PROXY CACHE OVERLAY
864 The proxy cache overlay
865 allows caching of LDAP search requests (queries) in a local database.
872 default slapd configuration file
876 .BR slapo\-pcache (5),
881 Pierangelo Masarati, based on back-ldap by Howard Chu