1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2006 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.
42 Note: When looping back to the same instance of \fBslapd\fP(8),
43 each connection requires a new thread; as a consequence, \fBslapd\fP(8)
44 must be compiled with thread support, and the \fBthreads\fP parameter
45 may need some tuning; in those cases, unless the multiple target feature
46 is required, one may consider using \fBslapd-relay\fP(5) instead,
47 which performs the relayed operation internally and thus reuses
51 There are examples in various places in this document, as well as in the
52 slapd/back-meta/data/ directory in the OpenLDAP source tree.
56 options apply to the META backend database.
57 That is, they must follow a "database meta" line and come before any
58 subsequent "backend" or "database" lines.
59 Other database options are described in the
63 Note: In early versions of back-ldap and back-meta it was recommended to always set
76 This is because operational attributes related to entry creation and
77 modification should not be proxied, as they could be mistakenly written
78 to the target server(s), generating an error.
79 The current implementation automatically sets lastmod to off, so its use
80 is redundant and should be omitted, because the lastmod directive will
81 be deprecated in the future.
83 .SH SPECIAL CONFIGURATION DIRECTIVES
84 Target configuration starts with the "uri" directive.
85 All the configuration directives that are not specific to targets
86 should be defined first for clarity, including those that are common
91 .B default-target none
92 This directive forces the backend to reject all those operations
93 that must resolve to a single target in case none or multiple
95 They include: add, delete, modify, modrdn; compare is not included, as
96 well as bind since, as they don't alter entries, in case of multiple
97 matches an attempt is made to perform the operation on any candidate
98 target, with the constraint that at most one must succeed.
99 This directive can also be used when processing targets to mark a
100 specific target as default.
103 .B dncache-ttl {DISABLED|forever|<ttl>}
104 This directive sets the time-to-live of the DN cache.
105 This caches the target that holds a given DN to speed up target
106 selection in case multiple targets would result from an uncached
107 search; forever means cache never expires; disabled means no DN
108 caching; otherwise a valid ( > 0 ) ttl is required, in the format
115 This directive causes a cached connection to be dropped an recreated
116 after a given ttl, regardless of being idle or not.
119 .B onerr {CONTINUE|stop}
120 This directive allows to select the behavior in case an error is returned
121 by one target during a search.
122 The default, \fBcontinue\fP, consists in continuing the operation,
123 trying to return as much data as possible.
124 If this statement is set to \fBstop\fP, the search is terminated as soon
125 as an error is returned by one target, and the error is immediately
126 propagated to the client.
129 .B pseudoroot-bind-defer {NO|yes}
130 This directive, when set to
132 causes the authentication to the remote servers with the pseudo-root
133 identity to be deferred until actually needed by subsequent operations.
136 .B rebind-as-user {NO|yes}
137 If this option is given, the client's bind credentials are remembered
138 for rebinds when chasing referrals.
140 .SH TARGET SPECIFICATION
141 Target specification starts with a "uri" directive:
144 .B uri <protocol>://[<host>[:<port>]]/<naming context>
145 The "server" directive that was allowed in the LDAP backend (although
146 deprecated) has been completely discarded in the Meta backend.
147 The <protocol> part can be anything
148 .BR ldap_initialize (3)
149 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
150 omitted, defaulting to whatever is set in
152 The <naming context> part is mandatory.
153 It must end with one of the naming contexts defined for the backend,
158 suffix "\fBdc=foo,dc=com\fP"
159 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
164 The <naming context> part doesn't need to be unique across the targets;
165 it may also match one of the values of the "suffix" directive.
166 Multiple URIs may be defined in a single argument. The URIs must
167 be separated by TABs (e.g. '\\t'; commas or spaces, unlike back-ldap,
169 because they are legal in the <naming context>, and we don't want to use
170 URL-encoded <naming context>s), and the additional URIs must have
171 no <naming context> part. This causes the underlying library
172 to contact the first server of the list that responds.
173 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
174 of the same server, the directive
177 suffix "\fBdc=foo,dc=com\fP"
178 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP ldap://l2.foo.com/"
183 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
188 .B subtree-exclude "<DN>"
189 This directive instructs back-meta to ignore the current target
190 for operations whose requestDN is subordinate to
192 There may be multiple occurrences of the
194 directive for each of the targets.
197 .B acl-authcDN "<administrative DN for access control purposes>"
198 DN which is used to query the target server for acl checking,
199 as in the LDAP backend; it is supposed to have read access
200 on the target server to attributes used on the proxy for acl checking.
201 There is no risk of giving away such values; they are only used to
203 .B The acl-authcDN identity is by no means implicitly used by the proxy
204 .B when the client connects anonymously.
207 .B acl-passwd <password>
208 Password used with the
214 .B bind-timeout <microseconds>
215 This directive defines the timeout, in microseconds, used when polling
216 for response after an asynchronous bind connection. The initial call
217 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
218 if that results in a timeout exceeded, subsequent calls use the value
221 The default value is used also for subsequent calls if
224 If set before any target specification, it affects all targets, unless
225 overridden by any per-target directive.
228 .B chase-referrals {YES|no}
229 enable/disable automatic referral chasing, which is delegated to the
230 underlying libldap, with rebinding eventually performed if the
231 \fBrebind-as-user\fP directive is used. The default is to chase referrals.
232 If set before any target specification, it affects all targets, unless
233 overridden by any per-target directive.
236 .B default-target [<target>]
237 The "default-target" directive can also be used during target specification.
238 With no arguments it marks the current target as the default.
239 The optional number marks target <target> as the default one, starting
241 Target <target> must be defined.
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.
247 The value can be specified as
249 [<d>d][<h>h][<m>m][<s>[s]]
251 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
253 If set before any target specification, it affects all targets, unless
254 overridden by any per-target directive.
257 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
258 This maps object classes and attributes as in the LDAP backend.
263 .B nretries {forever|never|<nretries>}
264 This directive defines how many times a bind should be retried
265 in case of temporary failure in contacting a target. If defined
266 before any target specification, it applies to all targets (by default,
269 the global value can be overridden by redefinitions inside each target
273 .B pseudorootdn "<substitute DN in case of rootdn bind>"
274 This directive, if present, sets the DN that will be substituted to
275 the bind DN if a bind with the backend's "rootdn" succeeds.
276 The true "rootdn" of the target server ought not be used; an arbitrary
277 administrative DN should used instead.
280 .B pseudorootpw "<substitute password in case of rootdn bind>"
281 This directive sets the credential that will be used in case a bind
282 with the backend's "rootdn" succeeds, and the bind is propagated to
283 the target using the "pseudorootdn" DN.
285 Note: cleartext credentials must be supplied here; as a consequence,
286 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
290 The rewrite options are described in the "REWRITING" section.
293 .B suffixmassage "<virtual naming context>" "<real naming context>"
294 All the directives starting with "rewrite" refer to the rewrite engine
295 that has been added to slapd.
296 The "suffixmassage" directive was introduced in the LDAP backend to
297 allow suffix massaging while proxying.
298 It has been obsoleted by the rewriting tools.
299 However, both for backward compatibility and for ease of configuration
300 when simple suffix massage is required, it has been preserved.
301 It wraps the basic rewriting instructions that perform suffix
302 massaging. See the "REWRITING" section for a detailed list
303 of the rewrite rules it implies.
306 .B t-f-support {NO|yes|discover}
307 enable if the remote server supports absolute filters
308 (see \fIdraft-zeilenga-ldap-t-f\fP for details).
311 support is detected by reading the remote server's root DSE.
312 If set before any target specification, it affects all targets, unless
313 overridden by any per-target directive.
316 .B timeout [{add|delete|modify|modrdn}=]<seconds> [...]
317 This directive allows to set per-database, per-target and per-operation
319 If no operation is specified, it affects all.
320 Currently, only write operations are addressed, because searches
321 can already be limited by means of the
325 for details), and other operations are not supposed to incur into the
327 Note: if the timelimit is exceeded, the operation is abandoned;
328 the protocol does not provide any means to rollback the operation,
329 so the client will not know if the operation eventually succeeded or not.
330 If set before any target specification, it affects all targets, unless
331 overridden by any per-target directive.
334 .B tls {[try-]start|[try-]propagate}
335 execute the StartTLS extended operation when the connection is initialized;
336 only works if the URI directive protocol scheme is not \fBldaps://\fP.
337 \fBpropagate\fP issues the StartTLS operation only if the original
339 The \fBtry-\fP prefix instructs the proxy to continue operations
340 if the StartTLS operation failed; its use is highly deprecated.
341 If set before any target specification, it affects all targets, unless
342 overridden by any per-target directive.
345 A powerful (and in some sense dangerous) rewrite engine has been added
346 to both the LDAP and Meta backends.
347 While the former can gain limited beneficial effects from rewriting
348 stuff, the latter can become an amazingly powerful tool.
350 Consider a couple of scenarios first.
352 1) Two directory servers share two levels of naming context;
353 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
354 Then, an unambiguous Meta database can be configured as:
359 suffix "\fBdc=foo,dc=com\fP"
360 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
361 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
365 Operations directed to a specific target can be easily resolved
366 because there are no ambiguities.
367 The only operation that may resolve to multiple targets is a search
368 with base "dc=foo,dc=com" and scope at least "one", which results in
369 spawning two searches to the targets.
371 2a) Two directory servers don't share any portion of naming context,
372 but they'd present as a single DIT
373 [Caveat: uniqueness of (massaged) entries among the two servers is
374 assumed; integrity checks risk to incur in excessive overhead and have
375 not been implemented].
376 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
377 and we'd like them to appear as branches of "dc=foo,dc=com", say
378 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
379 Then we need to configure our Meta backend as:
384 suffix "dc=foo,dc=com"
386 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
387 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
389 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
390 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
394 Again, operations can be resolved without ambiguity, although
395 some rewriting is required.
396 Notice that the virtual naming context of each target is a branch of
397 the database's naming context; it is rewritten back and forth when
398 operations are performed towards the target servers.
399 What "back and forth" means will be clarified later.
401 When a search with base "dc=foo,dc=com" is attempted, if the
402 scope is "base" it fails with "no such object"; in fact, the
403 common root of the two targets (prior to massaging) does not
405 If the scope is "one", both targets are contacted with the base
406 replaced by each target's base; the scope is derated to "base".
407 In general, a scope "one" search is honored, and the scope is derated,
408 only when the incoming base is at most one level lower of a target's
409 naming context (prior to massaging).
411 Finally, if the scope is "sub" the incoming base is replaced
412 by each target's unmassaged naming context, and the scope
415 2b) Consider the above reported scenario with the two servers
416 sharing the same naming context:
421 suffix "\fBdc=foo,dc=com\fP"
423 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
424 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
426 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
427 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
431 All the previous considerations hold, except that now there is
432 no way to unambiguously resolve a DN.
433 In this case, all the operations that require an unambiguous target
434 selection will fail unless the DN is already cached or a default
436 Practical configurations may result as a combination of all the
439 Note on ACLs: at present you may add whatever ACL rule you desire
440 to to the Meta (and LDAP) backends.
441 However, the meaning of an ACL on a proxy may require some
443 Two philosophies may be considered:
445 a) the remote server dictates the permissions; the proxy simply passes
446 back what it gets from the remote server.
448 b) the remote server unveils "everything"; the proxy is responsible
449 for protecting data from unauthorized access.
451 Of course the latter sounds unreasonable, but it is not.
452 It is possible to imagine scenarios in which a remote host discloses
453 data that can be considered "public" inside an intranet, and a proxy
454 that connects it to the internet may impose additional constraints.
455 To this purpose, the proxy should be able to comply with all the ACL
456 matching criteria that the server supports.
457 This has been achieved with regard to all the criteria supported by
458 slapd except a special subtle case (please drop me a note if you can
459 find other exceptions: <ando@openldap.org>).
464 access to dn="<dn>" attr=<attr>
465 by dnattr=<dnattr> read
470 cannot be matched iff the attribute that is being requested, <attr>,
471 is NOT <dnattr>, and the attribute that determines membership,
472 <dnattr>, has not been requested (e.g. in a search)
474 In fact this ACL is resolved by slapd using the portion of entry it
475 retrieved from the remote server without requiring any further
476 intervention of the backend, so, if the <dnattr> attribute has not
477 been fetched, the match cannot be assessed because the attribute is
478 not present, not because no value matches the requirement!
480 Note on ACLs and attribute mapping: ACLs are applied to the mapped
481 attributes; for instance, if the attribute locally known as "foo" is
482 mapped to "bar" on a remote server, then local ACLs apply to attribute
483 "foo" and are totally unaware of its remote name.
484 The remote server will check permissions for "bar", and the local
485 server will possibly enforce additional restrictions to "foo".
487 .\" If this section is moved, also update the reference in
488 .\" libraries/librewrite/RATIONALE.
491 A string is rewritten according to a set of rules, called a `rewrite
493 The rules are based on POSIX (''extended'') regular expressions (regex)
494 with substring matching; basic variable substitution and map resolution
495 of substrings is allowed by specific mechanisms detailed in the following.
496 The behavior of pattern matching/substitution can be altered by a set
499 The underlying concept is to build a lightweight rewrite module
500 for the slapd server (initially dedicated to the LDAP backend).
502 An incoming string is matched against a set of rules.
503 Rules are made of a regex match pattern, a substitution pattern
504 and a set of actions, described by a set of flags.
505 In case of match a string rewriting is performed according to the
506 substitution pattern that allows to refer to substrings matched in the
508 The actions, if any, are finally performed.
509 The substitution pattern allows map resolution of substrings.
510 A map is a generic object that maps a substitution pattern to a value.
511 The flags are divided in "Pattern matching Flags" and "Action Flags";
512 the former alter the regex match pattern behavior while the latter
513 alter the action that is taken after substitution.
514 .SH "Pattern Matching Flags"
517 honors case in matching (default is case insensitive)
520 use POSIX ''basic'' regular expressions (default is ''extended'')
525 recursive passes for a specific rule; does not alter the max total count
526 of passes, so it can only enforce a stricter limit for a specific rule.
530 apply the rule once only (default is recursive)
533 stop applying rules in case of match; the current rule is still applied
534 recursively; combine with `:' to apply the current rule only once
538 stop current operation if the rule matches, and issue an `unwilling to
544 rules back and forth (watch for loops!).
545 Note that `G{1}' is implicit in every rule.
548 ignores errors in rule; this means, in case of error, e.g. issued by a
549 map, the error is treated as a missed match.
550 The `unwilling to perform' is not overridden.
556 as return code if the rule matches; the flag does not alter the recursive
557 behavior of the rule, so, to have it performed only once, it must be used
558 in combination with `:', e.g.
560 returns the value `16' after exactly one execution of the rule, if the
562 As a consequence, its behavior is equivalent to `@', with the return
565 or, in other words, `@' is equivalent to `U{0}'.
566 By convention, the freely available codes are above 16 included;
567 the others are reserved.
569 The ordering of the flags can be significant.
570 For instance: `IG{2}' means ignore errors and jump two lines ahead
571 both in case of match and in case of error, while `G{2}I' means ignore
572 errors, but jump two lines ahead only in case of match.
574 More flags (mainly Action Flags) will be added as needed.
575 .SH "Pattern matching:"
580 .SH "Substitution Pattern Syntax:"
581 Everything starting with `%' requires substitution;
583 the only obvious exception is `%%', which is left as is;
585 the basic substitution is `%d', where `d' is a digit;
586 0 means the whole string, while 1-9 is a submatch;
588 a `%' followed by a `{' invokes an advanced substitution.
592 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
595 where <name> must be a legal name for the map, i.e.
599 <name> ::= [a-z][a-z0-9]* (case insensitive)
600 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
604 and <substitution> must be a legal substitution
605 pattern, with no limits on the nesting level.
610 sub context invocation; <name> must be a legal, already defined
614 external command invocation; <name> must refer to a legal, already
615 defined command name (NOT IMPL.)
618 variable assignment; <name> defines a variable in the running
619 operation structure which can be dereferenced later; operator
621 assigns a variable in the rewrite context scope; operator
623 assigns a variable that scopes the entire session, e.g. its value
624 can be dereferenced later by other rewrite contexts
627 variable dereferencing; <name> must refer to a variable that is
628 defined and assigned for the running operation; operator
630 dereferences a variable scoping the rewrite context; operator
632 dereferences a variable scoping the whole session, e.g. the value
633 is passed across rewrite contexts
636 parameter dereferencing; <name> must refer to an existing parameter;
637 the idea is to make some run-time parameters set by the system
638 available to the rewrite engine, as the client host name, the bind DN
639 if any, constant parameters initialized at config time, and so on;
640 no parameter is currently set by either
644 but constant parameters can be defined in the configuration file
649 Substitution escaping has been delegated to the `%' symbol,
650 which is used instead of `\e' in string substitution patterns
651 because `\e' is already escaped by slapd's low level parsing routines;
652 as a consequence, regex escaping requires two `\e' symbols,
653 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
655 .\" The symbol can be altered at will by redefining the related macro in
658 .SH "Rewrite context:"
659 A rewrite context is a set of rules which are applied in sequence.
660 The basic idea is to have an application initialize a rewrite
661 engine (think of Apache's mod_rewrite ...) with a set of rewrite
662 contexts; when string rewriting is required, one invokes the
663 appropriate rewrite context with the input string and obtains the
664 newly rewritten one if no errors occur.
666 Each basic server operation is associated to a rewrite context;
667 they are divided in two main groups: client \-> server and
668 server \-> client rewriting.
674 (default) if defined and no specific context
679 searchFilterAttrDN search
681 compareAttrDN compare AVA
685 modifyAttrDN modify AVA
689 exopPasswdDN password modify extended operation DN if proxy
697 searchResult search (only if defined; no default;
698 acts on DN and DN-syntax attributes
700 searchAttrDN search AVA
701 matchedDN all ops (only if applicable)
705 .SH "Basic configuration syntax"
707 .B rewriteEngine { on | off }
708 If `on', the requested rewriting is performed; if `off', no
709 rewriting takes place (an easy way to stop rewriting without
710 altering too much the configuration file).
712 .B rewriteContext <context name> "[ alias <aliased context name> ]"
713 <Context name> is the name that identifies the context, i.e. the name
714 used by the application to refer to the set of rules it contains.
715 It is used also to reference sub contexts in string rewriting.
716 A context may alias another one.
717 In this case the alias context contains no rule, and any reference to
718 it will result in accessing the aliased one.
720 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
721 Determines how a string can be rewritten if a pattern is matched.
722 Examples are reported below.
723 .SH "Additional configuration syntax:"
725 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
726 Allows to define a map that transforms substring rewriting into
728 The map is referenced inside the substitution pattern of a rule.
730 .B rewriteParam <param name> <param value>
731 Sets a value with global scope, that can be dereferenced by the
732 command `%{$paramName}'.
734 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
735 Sets the maximum number of total rewriting passes that can be
736 performed in a single rewrite operation (to avoid loops).
737 A safe default is set to 100; note that reaching this limit is still
738 treated as a success; recursive invocation of rules is simply
740 The count applies to the rewriting operation as a whole, not
741 to any single rule; an optional per-rule limit can be set.
742 This limit is overridden by setting specific per-rule limits
743 with the `M{n}' flag.
744 .SH "Configuration examples:"
746 # set to `off' to disable rewriting
749 # the rules the "suffixmassage" directive implies
751 # all dataflow from client to server referring to DNs
752 rewriteContext default
753 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
755 rewriteContext searchFilter
756 # all dataflow from server to client
757 rewriteContext searchResult
758 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
759 rewriteContext searchAttrDN alias searchResult
760 rewriteContext matchedDN alias searchResult
762 # Everything defined here goes into the `default' context.
763 # This rule changes the naming context of anything sent
764 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
766 rewriteRule "(.*)dc=home,[ ]?dc=net"
767 "%1dc=OpenLDAP, dc=org" ":"
769 # since a pretty/normalized DN does not include spaces
770 # after rdn separators, e.g. `,', this rule suffices:
772 rewriteRule "(.*)dc=home,dc=net"
773 "%1dc=OpenLDAP,dc=org" ":"
775 # Start a new context (ends input of the previous one).
776 # This rule adds blanks between DN parts if not present.
777 rewriteContext addBlanks
778 rewriteRule "(.*),([^ ].*)" "%1, %2"
780 # This one eats blanks
781 rewriteContext eatBlanks
782 rewriteRule "(.*),[ ](.*)" "%1,%2"
784 # Here control goes back to the default rewrite
785 # context; rules are appended to the existing ones.
786 # anything that gets here is piped into rule `addBlanks'
787 rewriteContext default
788 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
790 .\" # Anything with `uid=username' is looked up in
791 .\" # /etc/passwd for gecos (I know it's nearly useless,
792 .\" # but it is there just as a guideline to implementing
794 .\" # Note the `I' flag that leaves `uid=username' in place
795 .\" # if `username' does not have a valid account, and the
796 .\" # `:' that forces the rule to be processed exactly once.
797 .\" rewriteContext uid2Gecos
798 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
799 .\" "%1cn=%2{xpasswd},%3" "I:"
801 .\" # Finally, in a bind, if one uses a `uid=username' DN,
802 .\" # it is rewritten in `cn=name surname' if possible.
803 .\" rewriteContext bindDN
804 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
806 # Rewrite the search base according to `default' rules.
807 rewriteContext searchBase alias default
809 # Search results with OpenLDAP DN are rewritten back with
810 # `dc=home,dc=net' naming context, with spaces eaten.
811 rewriteContext searchResult
812 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
813 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
815 # Bind with email instead of full DN: we first need
816 # an ldap map that turns attributes into a DN (the
817 # argument used when invoking the map is appended to
818 # the URI and acts as the filter portion)
819 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
821 # Then we need to detect DN made up of a single email,
822 # e.g. `mail=someone@example.com'; note that the rule
823 # in case of match stops rewriting; in case of error,
824 # it is ignored. In case we are mapping virtual
825 # to real naming contexts, we also need to rewrite
826 # regular DNs, because the definition of a bindDn
827 # rewrite context overrides the default definition.
828 rewriteContext bindDN
829 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
831 # This is a rather sophisticated example. It massages a
832 # search filter in case who performs the search has
833 # administrative privileges. First we need to keep
834 # track of the bind DN of the incoming request, which is
835 # stored in a variable called `binddn' with session scope,
836 # and left in place to allow regular binding:
837 rewriteContext bindDN
838 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
840 # A search filter containing `uid=' is rewritten only
841 # if an appropriate DN is bound.
842 # To do this, in the first rule the bound DN is
843 # dereferenced, while the filter is decomposed in a
844 # prefix, in the value of the `uid=<arg>' AVA, and
845 # in a suffix. A tag `<>' is appended to the DN.
846 # If the DN refers to an entry in the `ou=admin' subtree,
847 # the filter is rewritten OR-ing the `uid=<arg>' with
848 # `cn=<arg>'; otherwise it is left as is. This could be
849 # useful, for instance, to allow apache's auth_ldap-1.4
850 # module to authenticate users with both `uid' and
851 # `cn', but only if the request comes from a possible
852 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
853 rewriteContext searchFilter
854 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
855 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
857 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
858 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
859 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
861 # This example shows how to strip unwanted DN-valued
862 # attribute values from a search result; the first rule
863 # matches DN values below "ou=People,dc=example,dc=com";
864 # in case of match the rewriting exits successfully.
865 # The second rule matches everything else and causes
866 # the value to be rejected.
867 rewriteContext searchResult
868 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
869 rewriteRule ".*" "" "#"
871 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
872 In case the rewritten DN is an LDAP URI, the operation is initiated
873 towards the host[:port] indicated in the uri, if it does not refer
878 rewriteRule '^cn=root,.*' '%0' 'G{3}'
879 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
880 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
881 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
884 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
888 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
891 with the advantage of saving one rewrite pass ...)
896 backend does not honor all ACL semantics as described in
897 .BR slapd.access (5).
898 In general, access checking is delegated to the remote server(s).
903 pseudo-attribute and to the other attribute values of the entries
906 operation is honored, which is performed by the frontend.
908 .SH PROXY CACHE OVERLAY
909 The proxy cache overlay
910 allows caching of LDAP search requests (queries) in a local database.
917 default slapd configuration file
921 .BR slapo\-pcache (5),
926 Pierangelo Masarati, based on back-ldap by Howard Chu