1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2004 The OpenLDAP Foundation, All Rights Reserved.
3 .\" Copying restrictions apply. See the COPYRIGHT file.
4 .\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
7 .\" Portions of this document should probably be moved to slapd-ldap(5)
8 .\" and maybe manual pages for librewrite.
11 slapd-meta \- metadirectory backend
19 performs basic LDAP proxying with respect to a set of remote LDAP
20 servers, called "targets".
21 The information contained in these servers can be presented as
22 belonging to a single Directory Information Tree (DIT).
24 A basic knowledge of the functionality of the
26 backend is recommended.
27 This backend has been designed as an enhancement of the ldap backend.
28 The two backends share many features (actually they also share
32 backend is intended to proxy operations directed to a single server, the
34 backend is mainly intended for proxying of multiple servers and possibly
35 naming context masquerading.
36 These features, although useful in many scenarios, may result in
37 excessive overhead for some applications, so its use should be
39 In the examples section, some typical scenarios will be discussed.
41 There are examples in various places in this document, as well as in the
42 slapd/back-meta/data/ directory in the OpenLDAP source tree.
46 options apply to the META backend database.
47 That is, they must follow a "database meta" line and come before any
48 subsequent "backend" or "database" lines.
49 Other database options are described in the
55 backend, operational attributes related to entry creation/modification
56 should not be used, as they would be passed to the target servers,
58 Moreover, it makes little sense to use such attributes in proxying, as
59 the proxy server doesn't actually store data, so it should have no
60 knowledge of such attributes.
61 While code to strip the modification attributes has been put in place
62 (and #ifdef'd), it implies unmotivated overhead.
63 So it is strongly recommended to set
72 .SH SPECIAL CONFIGURATION DIRECTIVES
73 Target configuration starts with the "uri" directive.
74 All the configuration directives that are not specific to targets
75 should be defined first for clarity, including those that are common
79 .B default-target none
80 This directive forces the backend to reject all those operations
81 that must resolve to a single target in case none or multiple
83 They include: add, delete, modify, modrdn; compare is not included, as
84 well as bind since, as they don't alter entries, in case of multiple
85 matches an attempt is made to perform the operation on any candidate
86 target, with the constraint that at most one must succeed.
87 This directive can also be used when processing targets to mark a
88 specific target as default.
90 .B dncache-ttl {forever|disabled|<ttl>}
91 This directive sets the time-to-live of the DN cache.
92 This caches the target that holds a given DN to speed up target
93 selection in case multiple targets would result from an uncached
94 search; forever means cache never expires; disabled means no DN
95 caching; otherwise a valid ( > 0 ) ttl in seconds is required.
96 .SH TARGET SPECIFICATION
97 Target specification starts with a "uri" directive:
99 .B uri <protocol>://[<host>[:<port>]]/<naming context>
100 The "server" directive that was allowed in the LDAP backend (although
101 deprecated) has been discarded in the Meta backend.
102 The <protocol> part can be anything
103 .BR ldap_initialize (3)
104 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
105 omitted, defaulting to whatever is set in /etc/ldap.conf.
106 The <naming context> part is mandatory.
107 It must end with one of the naming contexts defined for the backend,
112 suffix "\fBdc=foo,dc=com\fP"
113 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
117 The <naming context> part doesn't need to be unique across the targets;
118 it may also match one of the values of the "suffix" directive.
119 Multiple URIs may be defined in a single argument. The URIs must
120 be separated by TABs (e.g. '\\t'), and the additional URIs must have
121 no <naming context> part. This causes the underlying library
122 to contact the first server of the list that responds.
124 .B default-target [<target>]
125 The "default-target" directive can also be used during target specification.
126 With no arguments it marks the current target as the default.
127 The optional number marks target <target> as the default one, starting
129 Target <target> must be defined.
131 .B binddn "<administrative DN for access control purposes>"
132 This directive, as in the LDAP backend, allows to define the DN that is
133 used to query the target server for acl checking; it should have read
134 access on the target server to attributes used on the proxy for acl
136 There is no risk of giving away such values; they are only used to
139 .B bindpw <password for access control purposes>
140 This directive sets the password for acl checking in conjunction
141 with the above mentioned "binddn" directive.
144 If this option is given, the client's bind credentials are remembered
145 for rebinds when chasing referrals.
147 .B pseudorootdn "<substitute DN in case of rootdn bind>"
148 This directive, if present, sets the DN that will be substituted to
149 the bind DN if a bind with the backend's "rootdn" succeeds.
150 The true "rootdn" of the target server ought not be used; an arbitrary
151 administrative DN should used instead.
153 .B pseudorootpw "<substitute password in case of rootdn bind>"
154 This directive sets the credential that will be used in case a bind
155 with the backend's "rootdn" succeeds, and the bind is propagated to
156 the target using the "pseudorootdn" DN.
158 Note: cleartext credentials must be supplied here; as a consequence,
159 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
162 The rewrite options are described in the "REWRITING" section.
164 .B suffixmassage "<virtual naming context>" "<real naming context>"
165 All the directives starting with "rewrite" refer to the rewrite engine
166 that has been added to slapd.
167 The "suffixmassage" directive was introduced in the LDAP backend to
168 allow suffix massaging while proxying.
169 It has been obsoleted by the rewriting tools.
170 However, both for backward compatibility and for ease of configuration
171 when simple suffix massage is required, it has been preserved.
172 It wraps the basic rewriting instructions that perform suffix
173 massaging. See the "REWRITING" section for a detailed list
174 of the rewrite rules it implies.
176 Note: this also fixes a flaw in suffix massaging, which operated
177 on (case insensitive) DNs instead of normalized DNs,
178 so "dc=foo, dc=com" would not match "dc=foo,dc=com".
180 See the "REWRITING" section.
182 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
183 This maps object classes and attributes as in the LDAP backend.
187 A powerful (and in some sense dangerous) rewrite engine has been added
188 to both the LDAP and Meta backends.
189 While the former can gain limited beneficial effects from rewriting
190 stuff, the latter can become an amazingly powerful tool.
192 Consider a couple of scenarios first.
194 1) Two directory servers share two levels of naming context;
195 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
196 Then, an unambiguous Meta database can be configured as:
201 suffix "\fBdc=foo,dc=com\fP"
202 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
203 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
207 Operations directed to a specific target can be easily resolved
208 because there are no ambiguities.
209 The only operation that may resolve to multiple targets is a search
210 with base "dc=foo,dc=com" and scope at least "one", which results in
211 spawning two searches to the targets.
213 2a) Two directory servers don't share any portion of naming context,
214 but they'd present as a single DIT
215 [Caveat: uniqueness of (massaged) entries among the two servers is
216 assumed; integrity checks risk to incur in excessive overhead and have
217 not been implemented].
218 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
219 and we'd like them to appear as branches of "dc=foo,dc=com", say
220 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
221 Then we need to configure our Meta backend as:
226 suffix "dc=foo,dc=com"
228 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
229 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
231 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
232 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
236 Again, operations can be resolved without ambiguity, although
237 some rewriting is required.
238 Notice that the virtual naming context of each target is a branch of
239 the database's naming context; it is rewritten back and forth when
240 operations are performed towards the target servers.
241 What "back and forth" means will be clarified later.
243 When a search with base "dc=foo,dc=com" is attempted, if the
244 scope is "base" it fails with "no such object"; in fact, the
245 common root of the two targets (prior to massaging) does not
247 If the scope is "one", both targets are contacted with the base
248 replaced by each target's base; the scope is derated to "base".
249 In general, a scope "one" search is honored, and the scope is derated,
250 only when the incoming base is at most one level lower of a target's
251 naming context (prior to massaging).
253 Finally, if the scope is "sub" the incoming base is replaced
254 by each target's unmassaged naming context, and the scope
257 2b) Consider the above reported scenario with the two servers
258 sharing the same naming context:
263 suffix "\fBdc=foo,dc=com\fP"
265 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
266 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
268 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
269 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
273 All the previous considerations hold, except that now there is
274 no way to unambiguously resolve a DN.
275 In this case, all the operations that require an unambiguous target
276 selection will fail unless the DN is already cached or a default
278 Practical configurations may result as a combination of all the
281 Note on ACLs: at present you may add whatever ACL rule you desire
282 to to the Meta (and LDAP) backends.
283 However, the meaning of an ACL on a proxy may require some
285 Two philosophies may be considered:
287 a) the remote server dictates the permissions; the proxy simply passes
288 back what it gets from the remote server.
290 b) the remote server unveils "everything"; the proxy is responsible
291 for protecting data from unauthorized access.
293 Of course the latter sounds unreasonable, but it is not.
294 It is possible to imagine scenarios in which a remote host discloses
295 data that can be considered "public" inside an intranet, and a proxy
296 that connects it to the internet may impose additional constraints.
297 To this purpose, the proxy should be able to comply with all the ACL
298 matching criteria that the server supports.
299 This has been achieved with regard to all the criteria supported by
300 slapd except a special subtle case (please drop me a note if you can
301 find other exceptions: <ando@openldap.org>).
306 access to dn="<dn>" attr=<attr>
307 by dnattr=<dnattr> read
312 cannot be matched iff the attribute that is being requested, <attr>,
313 is NOT <dnattr>, and the attribute that determines membership,
314 <dnattr>, has not been requested (e.g. in a search)
316 In fact this ACL is resolved by slapd using the portion of entry it
317 retrieved from the remote server without requiring any further
318 intervention of the backend, so, if the <dnattr> attribute has not
319 been fetched, the match cannot be assessed because the attribute is
320 not present, not because no value matches the requirement!
322 Note on ACLs and attribute mapping: ACLs are applied to the mapped
323 attributes; for instance, if the attribute locally known as "foo" is
324 mapped to "bar" on a remote server, then local ACLs apply to attribute
325 "foo" and are totally unaware of its remote name.
326 The remote server will check permissions for "bar", and the local
327 server will possibly enforce additional restrictions to "foo".
329 .\" If this section is moved, also update the reference in
330 .\" libraries/librewrite/RATIONALE.
333 A string is rewritten according to a set of rules, called a `rewrite
335 The rules are based on Regular Expressions (POSIX regex) with
336 substring matching; basic variable substitution and map resolution
337 of substrings is allowed by specific mechanisms detailed in the following.
338 The behavior of pattern matching/substitution can be altered by a set
341 The underlying concept is to build a lightweight rewrite module
342 for the slapd server (initially dedicated to the LDAP backend).
344 An incoming string is matched agains a set of rules.
345 Rules are made of a regex match pattern, a substitution pattern
346 and a set of actions, described by a set of flags.
347 In case of match a string rewriting is performed according to the
348 substitution pattern that allows to refer to substrings matched in the
350 The actions, if any, are finally performed.
351 The substitution pattern allows map resolution of substrings.
352 A map is a generic object that maps a substitution pattern to a value.
353 The flags are divided in "Pattern matching Flags" and "Action Flags";
354 the former alter the regex match pattern behaviorm while the latter
355 alter the action that is taken after substitution.
356 .SH "Pattern Matching Flags"
359 honors case in matching (default is case insensitive)
362 use POSIX Basic Regular Expressions (default is Extended)
367 recursive passes for a specific rule; does not alter the max total count
368 of passes, so it can only enforce a stricter limit for a specific rule.
372 apply the rule once only (default is recursive)
375 stop applying rules in case of match; the current rule is still applied
376 recursively; combine with `:' to apply the current rule only once
380 stop current operation if the rule matches, and issue an `unwilling to
386 rules back and forth (watch for loops!).
387 Note that `G{1}' is implicit in every rule.
390 ignores errors in rule; this means, in case of error, e.g. issued by a
391 map, the error is treated as a missed match.
392 The `unwilling to perform' is not overridden.
398 as return code if the rule matches; the flag does not alter the recursive
399 behavior of the rule, so, to have it performed only once, it must be used
400 in combination with `:', e.g.
402 returns the value `16' after exactly one execution of the rule, if the
404 As a consequence, its behavior is equivalent to `@', with the return
407 or, in other words, `@' is equivalent to `U{0}'.
408 By convention, the freely available codes are above 16 included;
409 the others are reserved.
411 The ordering of the flags can be significant.
412 For instance: `IG{2}' means ignore errors and jump two lines ahead
413 both in case of match and in case of error, while `G{2}I' means ignore
414 errors, but jump two lines ahead only in case of match.
416 More flags (mainly Action Flags) will be added as needed.
417 .SH "Pattern matching:"
420 .SH "Substitution Pattern Syntax:"
421 Everything starting with `%' requires substitution;
423 the only obvious exception is `%%', which is left as is;
425 the basic substitution is `%d', where `d' is a digit;
426 0 means the whole string, while 1-9 is a submatch, as discussed in
429 a `%' followed by a `{' invokes an advanced substitution.
433 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
436 where <name> must be a legal name for the map, i.e.
440 <name> ::= [a-z][a-z0-9]* (case insensitive)
441 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
445 and <substitution> must be a legal substitution
446 pattern, with no limits on the nesting level.
451 sub context invocation; <name> must be a legal, already defined
455 external command invocation; <name> must refer to a legal, already
456 defined command name (NOT IMPL.)
459 variable assignment; <name> defines a variable in the running
460 operation structure which can be dereferenced later; operator
462 assigns a variable in the rewrite context scope; operator
464 assigns a variable that scopes the entire session, e.g. its value
465 can be derefenced later by other rewrite contexts
468 variable dereferencing; <name> must refer to a variable that is
469 defined and assigned for the running operation; operator
471 dereferences a variable scoping the rewrite context; operator
473 dereferences a variable scoping the whole session, e.g. the value
474 is passed across rewrite contexts
477 parameter dereferencing; <name> must refer to an existing parameter;
478 the idea is to make some run-time parameters set by the system
479 available to the rewrite engine, as the client host name, the bind DN
480 if any, constant parameters initialized at config time, and so on;
481 no parameter is currently set by either
485 but constant parameters can be defined in the configuration file
490 Substitution escaping has been delegated to the `%' symbol,
491 which is used instead of `\e' in string substitution patterns
492 because `\e' is already escaped by slapd's low level parsing routines;
495 escaping requires two `\e' symbols, e.g. `\fB.*\e.foo\e.bar\fP' must
496 be written as `\fB.*\e\e.foo\e\e.bar\fP'.
498 .\" The symbol can be altered at will by redefining the related macro in
501 .SH "Rewrite context:"
502 A rewrite context is a set of rules which are applied in sequence.
503 The basic idea is to have an application initialize a rewrite
504 engine (think of Apache's mod_rewrite ...) with a set of rewrite
505 contexts; when string rewriting is required, one invokes the
506 appropriate rewrite context with the input string and obtains the
507 newly rewritten one if no errors occur.
509 Each basic server operation is associated to a rewrite context;
510 they are divided in two main groups: client \-> server and
511 server \-> client rewriting.
517 (default) if defined and no specific context
522 searchFilterAttrDN search
524 compareAttrDN compare AVA
528 modifyAttrDN modify AVA
532 exopPasswdDN passwd exop DN if proxy
540 searchResult search (only if defined; no default;
541 acts on DN and DN-syntax attributes
543 searchAttrDN search AVA
544 matchedDN all ops (only if applicable)
548 .SH "Basic configuration syntax"
550 .B rewriteEngine { on | off }
551 If `on', the requested rewriting is performed; if `off', no
552 rewriting takes place (an easy way to stop rewriting without
553 altering too much the configuration file).
555 .B rewriteContext <context name> "[ alias <aliased context name> ]"
556 <Context name> is the name that identifies the context, i.e. the name
557 used by the application to refer to the set of rules it contains.
558 It is used also to reference sub contexts in string rewriting.
559 A context may aliase another one.
560 In this case the alias context contains no rule, and any reference to
561 it will result in accessing the aliased one.
563 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
564 Determines how a string can be rewritten if a pattern is matched.
565 Examples are reported below.
566 .SH "Additional configuration syntax:"
568 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
569 Allows to define a map that transforms substring rewriting into
571 The map is referenced inside the substitution pattern of a rule.
573 .B rewriteParam <param name> <param value>
574 Sets a value with global scope, that can be dereferenced by the
575 command `%{$paramName}'.
577 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
578 Sets the maximum number of total rewriting passes that can be
579 performed in a single rewrite operation (to avoid loops).
580 A safe default is set to 100; note that reaching this limit is still
581 treated as a success; recursive invocation of rules is simply
583 The count applies to the rewriting operation as a whole, not
584 to any single rule; an optional per-rule limit can be set.
585 This limit is overridden by setting specific per-rule limits
586 with the `M{n}' flag.
587 .SH "Configuration examples:"
589 # set to `off' to disable rewriting
592 # the rules the "suffixmassage" directive implies
594 # all dataflow from client to server referring to DNs
595 rewriteContext default
596 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
598 rewriteContext searchFilter
599 # all dataflow from server to client
600 rewriteContext searchResult
601 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
602 rewriteContext searchAttrDN alias searchResult
603 rewriteContext matchedDN alias searchResult
605 # Everything defined here goes into the `default' context.
606 # This rule changes the naming context of anything sent
607 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
609 rewriteRule "(.*)dc=home,[ ]?dc=net"
610 "%1dc=OpenLDAP, dc=org" ":"
612 # since a pretty/normalized DN does not include spaces
613 # after rdn separators, e.g. `,', this rule suffices:
615 rewriteRule "(.*)dc=home,dc=net"
616 "%1dc=OpenLDAP,dc=org" ":"
618 # Start a new context (ends input of the previous one).
619 # This rule adds blanks between DN parts if not present.
620 rewriteContext addBlanks
621 rewriteRule "(.*),([^ ].*)" "%1, %2"
623 # This one eats blanks
624 rewriteContext eatBlanks
625 rewriteRule "(.*),[ ](.*)" "%1,%2"
627 # Here control goes back to the default rewrite
628 # context; rules are appended to the existing ones.
629 # anything that gets here is piped into rule `addBlanks'
630 rewriteContext default
631 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
633 .\" # Anything with `uid=username' is looked up in
634 .\" # /etc/passwd for gecos (I know it's nearly useless,
635 .\" # but it is there just as a guideline to implementing
637 .\" # Note the `I' flag that leaves `uid=username' in place
638 .\" # if `username' does not have a valid account, and the
639 .\" # `:' that forces the rule to be processed exactly once.
640 .\" rewriteContext uid2Gecos
641 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
642 .\" "%1cn=%2{xpasswd},%3" "I:"
644 .\" # Finally, in a bind, if one uses a `uid=username' DN,
645 .\" # it is rewritten in `cn=name surname' if possible.
646 .\" rewriteContext bindDN
647 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
649 # Rewrite the search base according to `default' rules.
650 rewriteContext searchBase alias default
652 # Search results with OpenLDAP DN are rewritten back with
653 # `dc=home,dc=net' naming context, with spaces eaten.
654 rewriteContext searchResult
655 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
656 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
658 # Bind with email instead of full DN: we first need
659 # an ldap map that turns attributes into a DN (the
660 # argument used when invoking the map is appended to
661 # the URI and acts as the filter portion)
662 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
664 # Then we need to detect DN made up of a single email,
665 # e.g. `mail=someone@example.com'; note that the rule
666 # in case of match stops rewriting; in case of error,
667 # it is ignored. In case we are mapping virtual
668 # to real naming contexts, we also need to rewrite
669 # regular DNs, because the definition of a bindDn
670 # rewrite context overrides the default definition.
671 rewriteContext bindDN
672 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
674 # This is a rather sophisticated example. It massages a
675 # search filter in case who performs the search has
676 # administrative privileges. First we need to keep
677 # track of the bind DN of the incoming request, which is
678 # stored in a variable called `binddn' with session scope,
679 # and left in place to allow regular binding:
680 rewriteContext bindDN
681 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
683 # A search filter containing `uid=' is rewritten only
684 # if an appropriate DN is bound.
685 # To do this, in the first rule the bound DN is
686 # dereferenced, while the filter is decomposed in a
687 # prefix, in the value of the `uid=<arg>' AVA, and
688 # in a suffix. A tag `<>' is appended to the DN.
689 # If the DN refers to an entry in the `ou=admin' subtree,
690 # the filter is rewritten OR-ing the `uid=<arg>' with
691 # `cn=<arg>'; otherwise it is left as is. This could be
692 # useful, for instance, to allow apache's auth_ldap-1.4
693 # module to authenticate users with both `uid' and
694 # `cn', but only if the request comes from a possible
695 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
696 rewriteContext searchFilter
697 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
698 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
700 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
701 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
702 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
704 # This example shows how to strip unwanted DN-valued
705 # attribute values from a search result; the first rule
706 # matches DN values below "ou=People,dc=example,dc=com";
707 # in case of match the rewriting exits successfully.
708 # The second rule matches everything else and causes
709 # the value to be rejected.
710 rewriteContext searchResult
711 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
712 rewriteRule ".*" "" "#"
714 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
715 In case the rewritten DN is an LDAP URI, the operation is initiated
716 towards the host[:port] indicated in the uri, if it does not refer
721 rewriteRule '^cn=root,.*' '%0' 'G{3}'
722 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
723 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
724 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
727 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
731 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
734 with the advantage of saving one rewrite pass ...)
735 .SH PROXY CACHE OVERLAY
736 The proxy cache overlay
737 allows caching of LDAP search requests (queries) in a local database.
738 For an incoming query, the
739 proxy cache determines its corresponding \fBtemplate\fP. If the template was
740 specified as cacheable using the \fBproxytemplate\fP directive and the request is
741 contained in a cached request, it is answered from the proxy cache. Otherwise,
742 the search is performed as usual and cacheable search results are saved in the
743 cache for use in future queries.
746 A template is defined by a filter string and an index identifying a set of
747 attributes. The \fBtemplate string\fP for a query can be obtained by
748 removing assertion values from the RFC 2254 representation of its search
749 filter. A query belongs to a template if its template string and set of
750 projected attributes correspond to a cacheable template. Examples of template strings are (mail=), (|(sn=)(cn=)), (&(sn=)(givenName=)).
753 The following cache specific directives can be used to configure the proxy
756 .B overlay proxycache
757 This directive adds the proxycache overlay to the current backend. The
758 proxycache overlay may be used with any backend but is intended for use
765 .B proxycache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>
766 The directive enables proxy caching in the current backend and sets general
767 cache parameters. A <database> backend will be used internally to maintain
768 the cached entries. The chosen database will need to be configured as well,
769 as shown below. Cache replacement is invoked when the cache size grows to
770 <max_entries> entries and continues till the cache size drops below this size.
771 <numattrsets> should be equal to the number of following \fBproxyattrset\fP
772 directives. Queries are cached only if they correspond to a cacheable template
773 (specified by the \fBproxytemplate\fP directive) and the number of entries
774 returned is less than <entry_limit>. Consistency check is performed every
775 <cc_period> duration (specified in secs). In each cycle queries with expired
776 "time to live(\fBTTL\fP)" are removed. A sample cache configuration is:
779 proxycache \fBbdb 10000 1 50 100\fP
782 .B proxyattrset <index> <attrs...>
783 Used to associate a set of attributes <attrs..> with an <index>. Each attribute
784 set is associated with an integer from 0 to <numattrsets>-1. These indices are
785 used by the \fBproxytemplate\fP directive to define cacheable templates.
788 .B proxytemplate <template_string> <attrset_index> <ttl>
789 Specifies a cacheable template and "time to live" (in sec) <ttl> of queries
790 belonging to the template.
793 The following adds a template with filter string (&sn=)(givenName=)) and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour.
797 proxyattrset \fB0 mail postaladdress telephonenumber\fP
798 proxytemplate \fB(&(sn=)(givenName=)) 0 3600\fP
802 Directives for configuring the underlying database must also be given, as
807 directory /var/tmp/cache
812 Any valid directives for the chosen database type may be used.
816 default slapd configuration file
823 Pierangelo Masarati, based on back-ldap by Howard Chu