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 {DISABLED|forever|<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 is required, in the format
104 .B onerr {CONTINUE|stop}
105 This directive allows to select the behavior in case an error is returned
106 by one target during a search.
107 The default, \fBcontinue\fP, consists in continuing the operation,
108 trying to return as much data as possible.
109 If this statement is set to \fBstop\fP, the search is terminated as soon
110 as an error is returned by one target, and the error is immediately
111 propagated to the client.
114 .B pseudoroot-bind-defer {NO|yes}
115 This directive, when set to
117 causes the authentication to the remote servers with the pseudo-root
118 identity to be deferred until actually needed by subsequent operations.
121 .B rebind-as-user {NO|yes}
122 If this option is given, the client's bind credentials are remembered
123 for rebinds when chasing referrals.
125 .SH TARGET SPECIFICATION
126 Target specification starts with a "uri" directive:
129 .B uri <protocol>://[<host>[:<port>]]/<naming context>
130 The "server" directive that was allowed in the LDAP backend (although
131 deprecated) has been completely discarded in the Meta backend.
132 The <protocol> part can be anything
133 .BR ldap_initialize (3)
134 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
135 omitted, defaulting to whatever is set in
137 The <naming context> part is mandatory.
138 It must end with one of the naming contexts defined for the backend,
143 suffix "\fBdc=foo,dc=com\fP"
144 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
149 The <naming context> part doesn't need to be unique across the targets;
150 it may also match one of the values of the "suffix" directive.
151 Multiple URIs may be defined in a single argument. The URIs must
152 be separated by TABs (e.g. '\\t'; commas or spaces, unlike back-ldap,
154 because they are legal in the <naming context>, and we don't want to use
155 URL-encoded <naming context>s), and the additional URIs must have
156 no <naming context> part. This causes the underlying library
157 to contact the first server of the list that responds.
158 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
159 of the same server, the directive
162 suffix "\fBdc=foo,dc=com\fP"
163 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP ldap://l2.foo.com/"
168 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
173 .B acl-authcDN "<administrative DN for access control purposes>"
174 DN which is used to query the target server for acl checking,
175 as in the LDAP backend; it is supposed to have read access
176 on the target server to attributes used on the proxy for acl checking.
177 There is no risk of giving away such values; they are only used to
179 .B The acl-authcDN identity is by no means implicitly used by the proxy
180 .B when the client connects anonymously.
183 .B acl-passwd <password>
184 Password used with the
190 .B bind-timeout <microseconds>
191 This directive defines the timeout, in microseconds, used when polling
192 for response after an asynchronous bind connection. The initial call
193 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
194 if that results in a timeout exceeded, subsequent calls use the value
197 The default value is used also for subsequent calls if
200 If set before any target specification, it affects all targets, unless
201 overridden by any per-target directive.
204 .B chase-referrals {YES|no}
205 enable/disable automatic referral chasing, which is delegated to the
206 underlying libldap, with rebinding eventually performed if the
207 \fBrebind-as-user\fP directive is used. The default is to chase referrals.
208 If set before any target specification, it affects all targets, unless
209 overridden by any per-target directive.
212 .B default-target [<target>]
213 The "default-target" directive can also be used during target specification.
214 With no arguments it marks the current target as the default.
215 The optional number marks target <target> as the default one, starting
217 Target <target> must be defined.
220 .B idle-timeout <time>
221 This directive causes a cached connection to be dropped an recreated
222 after it has been idle for the specified time.
223 The value can be specified as
225 [<d>d][<h>h][<m>m][<s>[s]]
227 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
229 If set before any target specification, it affects all targets, unless
230 overridden by any per-target directive.
233 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
234 This maps object classes and attributes as in the LDAP backend.
239 .B nretries {forever|never|<nretries>}
240 This directive defines how many times a bind should be retried
241 in case of temporary failure in contacting a target. If defined
242 before any target specification, it applies to all targets (by default,
245 the global value can be overridden by redefinitions inside each target
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.
266 The rewrite options are described in the "REWRITING" section.
269 .B suffixmassage "<virtual naming context>" "<real naming context>"
270 All the directives starting with "rewrite" refer to the rewrite engine
271 that has been added to slapd.
272 The "suffixmassage" directive was introduced in the LDAP backend to
273 allow suffix massaging while proxying.
274 It has been obsoleted by the rewriting tools.
275 However, both for backward compatibility and for ease of configuration
276 when simple suffix massage is required, it has been preserved.
277 It wraps the basic rewriting instructions that perform suffix
278 massaging. See the "REWRITING" section for a detailed list
279 of the rewrite rules it implies.
282 .B t-f-support {NO|yes|discover}
283 enable if the remote server supports absolute filters
284 (see \fIdraft-zeilenga-ldap-t-f\fP for details).
287 support is detected by reading the remote server's root DSE.
288 If set before any target specification, it affects all targets, unless
289 overridden by any per-target directive.
292 .B timeout [{add|delete|modify|modrdn}=]<seconds> [...]
293 This directive allows to set per-database, per-target and per-operation
295 If no operation is specified, it affects all.
296 Currently, only write operations are addressed, because searches
297 can already be limited by means of the
301 for details), and other operations are not supposed to incur into the
303 Note: if the timelimit is exceeded, the operation is abandoned;
304 the protocol does not provide any means to rollback the operation,
305 so the client will not know if the operation eventually succeeded or not.
306 If set before any target specification, it affects all targets, unless
307 overridden by any per-target directive.
310 .B tls {[try-]start|[try-]propagate}
311 execute the StartTLS extended operation when the connection is initialized;
312 only works if the URI directive protocol scheme is not \fBldaps://\fP.
313 \fBpropagate\fP issues the StartTLS operation only if the original
315 The \fBtry-\fP prefix instructs the proxy to continue operations
316 if the StartTLS operation failed; its use is highly deprecated.
317 If set before any target specification, it affects all targets, unless
318 overridden by any per-target directive.
321 A powerful (and in some sense dangerous) rewrite engine has been added
322 to both the LDAP and Meta backends.
323 While the former can gain limited beneficial effects from rewriting
324 stuff, the latter can become an amazingly powerful tool.
326 Consider a couple of scenarios first.
328 1) Two directory servers share two levels of naming context;
329 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
330 Then, an unambiguous Meta database can be configured as:
335 suffix "\fBdc=foo,dc=com\fP"
336 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
337 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
341 Operations directed to a specific target can be easily resolved
342 because there are no ambiguities.
343 The only operation that may resolve to multiple targets is a search
344 with base "dc=foo,dc=com" and scope at least "one", which results in
345 spawning two searches to the targets.
347 2a) Two directory servers don't share any portion of naming context,
348 but they'd present as a single DIT
349 [Caveat: uniqueness of (massaged) entries among the two servers is
350 assumed; integrity checks risk to incur in excessive overhead and have
351 not been implemented].
352 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
353 and we'd like them to appear as branches of "dc=foo,dc=com", say
354 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
355 Then we need to configure our Meta backend as:
360 suffix "dc=foo,dc=com"
362 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
363 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
365 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
366 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
370 Again, operations can be resolved without ambiguity, although
371 some rewriting is required.
372 Notice that the virtual naming context of each target is a branch of
373 the database's naming context; it is rewritten back and forth when
374 operations are performed towards the target servers.
375 What "back and forth" means will be clarified later.
377 When a search with base "dc=foo,dc=com" is attempted, if the
378 scope is "base" it fails with "no such object"; in fact, the
379 common root of the two targets (prior to massaging) does not
381 If the scope is "one", both targets are contacted with the base
382 replaced by each target's base; the scope is derated to "base".
383 In general, a scope "one" search is honored, and the scope is derated,
384 only when the incoming base is at most one level lower of a target's
385 naming context (prior to massaging).
387 Finally, if the scope is "sub" the incoming base is replaced
388 by each target's unmassaged naming context, and the scope
391 2b) Consider the above reported scenario with the two servers
392 sharing the same naming context:
397 suffix "\fBdc=foo,dc=com\fP"
399 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
400 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
402 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
403 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
407 All the previous considerations hold, except that now there is
408 no way to unambiguously resolve a DN.
409 In this case, all the operations that require an unambiguous target
410 selection will fail unless the DN is already cached or a default
412 Practical configurations may result as a combination of all the
415 Note on ACLs: at present you may add whatever ACL rule you desire
416 to to the Meta (and LDAP) backends.
417 However, the meaning of an ACL on a proxy may require some
419 Two philosophies may be considered:
421 a) the remote server dictates the permissions; the proxy simply passes
422 back what it gets from the remote server.
424 b) the remote server unveils "everything"; the proxy is responsible
425 for protecting data from unauthorized access.
427 Of course the latter sounds unreasonable, but it is not.
428 It is possible to imagine scenarios in which a remote host discloses
429 data that can be considered "public" inside an intranet, and a proxy
430 that connects it to the internet may impose additional constraints.
431 To this purpose, the proxy should be able to comply with all the ACL
432 matching criteria that the server supports.
433 This has been achieved with regard to all the criteria supported by
434 slapd except a special subtle case (please drop me a note if you can
435 find other exceptions: <ando@openldap.org>).
440 access to dn="<dn>" attr=<attr>
441 by dnattr=<dnattr> read
446 cannot be matched iff the attribute that is being requested, <attr>,
447 is NOT <dnattr>, and the attribute that determines membership,
448 <dnattr>, has not been requested (e.g. in a search)
450 In fact this ACL is resolved by slapd using the portion of entry it
451 retrieved from the remote server without requiring any further
452 intervention of the backend, so, if the <dnattr> attribute has not
453 been fetched, the match cannot be assessed because the attribute is
454 not present, not because no value matches the requirement!
456 Note on ACLs and attribute mapping: ACLs are applied to the mapped
457 attributes; for instance, if the attribute locally known as "foo" is
458 mapped to "bar" on a remote server, then local ACLs apply to attribute
459 "foo" and are totally unaware of its remote name.
460 The remote server will check permissions for "bar", and the local
461 server will possibly enforce additional restrictions to "foo".
463 .\" If this section is moved, also update the reference in
464 .\" libraries/librewrite/RATIONALE.
467 A string is rewritten according to a set of rules, called a `rewrite
469 The rules are based on POSIX (''extended'') regular expressions (regex)
470 with substring matching; basic variable substitution and map resolution
471 of substrings is allowed by specific mechanisms detailed in the following.
472 The behavior of pattern matching/substitution can be altered by a set
475 The underlying concept is to build a lightweight rewrite module
476 for the slapd server (initially dedicated to the LDAP backend).
478 An incoming string is matched against a set of rules.
479 Rules are made of a regex match pattern, a substitution pattern
480 and a set of actions, described by a set of flags.
481 In case of match a string rewriting is performed according to the
482 substitution pattern that allows to refer to substrings matched in the
484 The actions, if any, are finally performed.
485 The substitution pattern allows map resolution of substrings.
486 A map is a generic object that maps a substitution pattern to a value.
487 The flags are divided in "Pattern matching Flags" and "Action Flags";
488 the former alter the regex match pattern behavior while the latter
489 alter the action that is taken after substitution.
490 .SH "Pattern Matching Flags"
493 honors case in matching (default is case insensitive)
496 use POSIX ''basic'' regular expressions (default is ''extended'')
501 recursive passes for a specific rule; does not alter the max total count
502 of passes, so it can only enforce a stricter limit for a specific rule.
506 apply the rule once only (default is recursive)
509 stop applying rules in case of match; the current rule is still applied
510 recursively; combine with `:' to apply the current rule only once
514 stop current operation if the rule matches, and issue an `unwilling to
520 rules back and forth (watch for loops!).
521 Note that `G{1}' is implicit in every rule.
524 ignores errors in rule; this means, in case of error, e.g. issued by a
525 map, the error is treated as a missed match.
526 The `unwilling to perform' is not overridden.
532 as return code if the rule matches; the flag does not alter the recursive
533 behavior of the rule, so, to have it performed only once, it must be used
534 in combination with `:', e.g.
536 returns the value `16' after exactly one execution of the rule, if the
538 As a consequence, its behavior is equivalent to `@', with the return
541 or, in other words, `@' is equivalent to `U{0}'.
542 By convention, the freely available codes are above 16 included;
543 the others are reserved.
545 The ordering of the flags can be significant.
546 For instance: `IG{2}' means ignore errors and jump two lines ahead
547 both in case of match and in case of error, while `G{2}I' means ignore
548 errors, but jump two lines ahead only in case of match.
550 More flags (mainly Action Flags) will be added as needed.
551 .SH "Pattern matching:"
556 .SH "Substitution Pattern Syntax:"
557 Everything starting with `%' requires substitution;
559 the only obvious exception is `%%', which is left as is;
561 the basic substitution is `%d', where `d' is a digit;
562 0 means the whole string, while 1-9 is a submatch;
564 a `%' followed by a `{' invokes an advanced substitution.
568 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
571 where <name> must be a legal name for the map, i.e.
575 <name> ::= [a-z][a-z0-9]* (case insensitive)
576 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
580 and <substitution> must be a legal substitution
581 pattern, with no limits on the nesting level.
586 sub context invocation; <name> must be a legal, already defined
590 external command invocation; <name> must refer to a legal, already
591 defined command name (NOT IMPL.)
594 variable assignment; <name> defines a variable in the running
595 operation structure which can be dereferenced later; operator
597 assigns a variable in the rewrite context scope; operator
599 assigns a variable that scopes the entire session, e.g. its value
600 can be dereferenced later by other rewrite contexts
603 variable dereferencing; <name> must refer to a variable that is
604 defined and assigned for the running operation; operator
606 dereferences a variable scoping the rewrite context; operator
608 dereferences a variable scoping the whole session, e.g. the value
609 is passed across rewrite contexts
612 parameter dereferencing; <name> must refer to an existing parameter;
613 the idea is to make some run-time parameters set by the system
614 available to the rewrite engine, as the client host name, the bind DN
615 if any, constant parameters initialized at config time, and so on;
616 no parameter is currently set by either
620 but constant parameters can be defined in the configuration file
625 Substitution escaping has been delegated to the `%' symbol,
626 which is used instead of `\e' in string substitution patterns
627 because `\e' is already escaped by slapd's low level parsing routines;
628 as a consequence, regex escaping requires two `\e' symbols,
629 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
631 .\" The symbol can be altered at will by redefining the related macro in
634 .SH "Rewrite context:"
635 A rewrite context is a set of rules which are applied in sequence.
636 The basic idea is to have an application initialize a rewrite
637 engine (think of Apache's mod_rewrite ...) with a set of rewrite
638 contexts; when string rewriting is required, one invokes the
639 appropriate rewrite context with the input string and obtains the
640 newly rewritten one if no errors occur.
642 Each basic server operation is associated to a rewrite context;
643 they are divided in two main groups: client \-> server and
644 server \-> client rewriting.
650 (default) if defined and no specific context
655 searchFilterAttrDN search
657 compareAttrDN compare AVA
661 modifyAttrDN modify AVA
665 exopPasswdDN password modify extended operation DN if proxy
673 searchResult search (only if defined; no default;
674 acts on DN and DN-syntax attributes
676 searchAttrDN search AVA
677 matchedDN all ops (only if applicable)
681 .SH "Basic configuration syntax"
683 .B rewriteEngine { on | off }
684 If `on', the requested rewriting is performed; if `off', no
685 rewriting takes place (an easy way to stop rewriting without
686 altering too much the configuration file).
688 .B rewriteContext <context name> "[ alias <aliased context name> ]"
689 <Context name> is the name that identifies the context, i.e. the name
690 used by the application to refer to the set of rules it contains.
691 It is used also to reference sub contexts in string rewriting.
692 A context may alias another one.
693 In this case the alias context contains no rule, and any reference to
694 it will result in accessing the aliased one.
696 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
697 Determines how a string can be rewritten if a pattern is matched.
698 Examples are reported below.
699 .SH "Additional configuration syntax:"
701 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
702 Allows to define a map that transforms substring rewriting into
704 The map is referenced inside the substitution pattern of a rule.
706 .B rewriteParam <param name> <param value>
707 Sets a value with global scope, that can be dereferenced by the
708 command `%{$paramName}'.
710 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
711 Sets the maximum number of total rewriting passes that can be
712 performed in a single rewrite operation (to avoid loops).
713 A safe default is set to 100; note that reaching this limit is still
714 treated as a success; recursive invocation of rules is simply
716 The count applies to the rewriting operation as a whole, not
717 to any single rule; an optional per-rule limit can be set.
718 This limit is overridden by setting specific per-rule limits
719 with the `M{n}' flag.
720 .SH "Configuration examples:"
722 # set to `off' to disable rewriting
725 # the rules the "suffixmassage" directive implies
727 # all dataflow from client to server referring to DNs
728 rewriteContext default
729 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
731 rewriteContext searchFilter
732 # all dataflow from server to client
733 rewriteContext searchResult
734 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
735 rewriteContext searchAttrDN alias searchResult
736 rewriteContext matchedDN alias searchResult
738 # Everything defined here goes into the `default' context.
739 # This rule changes the naming context of anything sent
740 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
742 rewriteRule "(.*)dc=home,[ ]?dc=net"
743 "%1dc=OpenLDAP, dc=org" ":"
745 # since a pretty/normalized DN does not include spaces
746 # after rdn separators, e.g. `,', this rule suffices:
748 rewriteRule "(.*)dc=home,dc=net"
749 "%1dc=OpenLDAP,dc=org" ":"
751 # Start a new context (ends input of the previous one).
752 # This rule adds blanks between DN parts if not present.
753 rewriteContext addBlanks
754 rewriteRule "(.*),([^ ].*)" "%1, %2"
756 # This one eats blanks
757 rewriteContext eatBlanks
758 rewriteRule "(.*),[ ](.*)" "%1,%2"
760 # Here control goes back to the default rewrite
761 # context; rules are appended to the existing ones.
762 # anything that gets here is piped into rule `addBlanks'
763 rewriteContext default
764 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
766 .\" # Anything with `uid=username' is looked up in
767 .\" # /etc/passwd for gecos (I know it's nearly useless,
768 .\" # but it is there just as a guideline to implementing
770 .\" # Note the `I' flag that leaves `uid=username' in place
771 .\" # if `username' does not have a valid account, and the
772 .\" # `:' that forces the rule to be processed exactly once.
773 .\" rewriteContext uid2Gecos
774 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
775 .\" "%1cn=%2{xpasswd},%3" "I:"
777 .\" # Finally, in a bind, if one uses a `uid=username' DN,
778 .\" # it is rewritten in `cn=name surname' if possible.
779 .\" rewriteContext bindDN
780 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
782 # Rewrite the search base according to `default' rules.
783 rewriteContext searchBase alias default
785 # Search results with OpenLDAP DN are rewritten back with
786 # `dc=home,dc=net' naming context, with spaces eaten.
787 rewriteContext searchResult
788 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
789 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
791 # Bind with email instead of full DN: we first need
792 # an ldap map that turns attributes into a DN (the
793 # argument used when invoking the map is appended to
794 # the URI and acts as the filter portion)
795 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
797 # Then we need to detect DN made up of a single email,
798 # e.g. `mail=someone@example.com'; note that the rule
799 # in case of match stops rewriting; in case of error,
800 # it is ignored. In case we are mapping virtual
801 # to real naming contexts, we also need to rewrite
802 # regular DNs, because the definition of a bindDn
803 # rewrite context overrides the default definition.
804 rewriteContext bindDN
805 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
807 # This is a rather sophisticated example. It massages a
808 # search filter in case who performs the search has
809 # administrative privileges. First we need to keep
810 # track of the bind DN of the incoming request, which is
811 # stored in a variable called `binddn' with session scope,
812 # and left in place to allow regular binding:
813 rewriteContext bindDN
814 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
816 # A search filter containing `uid=' is rewritten only
817 # if an appropriate DN is bound.
818 # To do this, in the first rule the bound DN is
819 # dereferenced, while the filter is decomposed in a
820 # prefix, in the value of the `uid=<arg>' AVA, and
821 # in a suffix. A tag `<>' is appended to the DN.
822 # If the DN refers to an entry in the `ou=admin' subtree,
823 # the filter is rewritten OR-ing the `uid=<arg>' with
824 # `cn=<arg>'; otherwise it is left as is. This could be
825 # useful, for instance, to allow apache's auth_ldap-1.4
826 # module to authenticate users with both `uid' and
827 # `cn', but only if the request comes from a possible
828 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
829 rewriteContext searchFilter
830 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
831 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
833 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
834 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
835 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
837 # This example shows how to strip unwanted DN-valued
838 # attribute values from a search result; the first rule
839 # matches DN values below "ou=People,dc=example,dc=com";
840 # in case of match the rewriting exits successfully.
841 # The second rule matches everything else and causes
842 # the value to be rejected.
843 rewriteContext searchResult
844 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
845 rewriteRule ".*" "" "#"
847 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
848 In case the rewritten DN is an LDAP URI, the operation is initiated
849 towards the host[:port] indicated in the uri, if it does not refer
854 rewriteRule '^cn=root,.*' '%0' 'G{3}'
855 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
856 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
857 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
860 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
864 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
867 with the advantage of saving one rewrite pass ...)
872 backend does not honor all ACL semantics as described in
873 .BR slapd.access (5).
874 In general, access checking is delegated to the remote server(s).
879 pseudo-attribute and to the other attribute values of the entries
882 operation is honored, which is performed by the frontend.
884 .SH PROXY CACHE OVERLAY
885 The proxy cache overlay
886 allows caching of LDAP search requests (queries) in a local database.
893 default slapd configuration file
897 .BR slapo\-pcache (5),
902 Pierangelo Masarati, based on back-ldap by Howard Chu