1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2007 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 to slapd
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 was required because operational attributes related to entry creation
77 and 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 \fBoff\fP,
80 so its use is redundant and should be omitted.
82 .SH SPECIAL CONFIGURATION DIRECTIVES
83 Target configuration starts with the "uri" directive.
84 All the configuration directives that are not specific to targets
85 should be defined first for clarity, including those that are common
91 This directive causes a cached connection to be dropped an recreated
92 after a given ttl, regardless of being idle or not.
95 .B default-target none
96 This directive forces the backend to reject all those operations
97 that must resolve to a single target in case none or multiple
99 They include: add, delete, modify, modrdn; compare is not included, as
100 well as bind since, as they don't alter entries, in case of multiple
101 matches an attempt is made to perform the operation on any candidate
102 target, with the constraint that at most one must succeed.
103 This directive can also be used when processing targets to mark a
104 specific target as default.
107 .B dncache-ttl {DISABLED|forever|<ttl>}
108 This directive sets the time-to-live of the DN cache.
109 This caches the target that holds a given DN to speed up target
110 selection in case multiple targets would result from an uncached
111 search; forever means cache never expires; disabled means no DN
112 caching; otherwise a valid ( > 0 ) ttl is required, in the format
118 .B onerr {CONTINUE|report|stop}
119 This directive allows to select the behavior in case an error is returned
120 by one target during a search.
121 The default, \fBcontinue\fP, consists in continuing the operation,
122 trying to return as much data as possible.
123 If the value is set to \fBstop\fP, the search is terminated as soon
124 as an error is returned by one target, and the error is immediately
125 propagated to the client.
126 If the value is set to \fBreport\fP, the search is continuated to the end
127 but, in case at least one target returned an error code, the first
128 non-success error code is returned.
131 .B protocol\-version {0,2,3}
132 This directive indicates what protocol version must be used to contact
134 If set to 0 (the default), the proxy uses the same protocol version
135 used by the client, otherwise the requested protocol is used.
136 The proxy returns \fIunwillingToPerform\fP if an operation that is
137 incompatible with the requested protocol is attempted.
138 If set before any target specification, it affects all targets, unless
139 overridden by any per-target directive.
142 .B pseudoroot-bind-defer {NO|yes}
143 This directive, when set to
145 causes the authentication to the remote servers with the pseudo-root
146 identity to be deferred until actually needed by subsequent operations.
149 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
150 Turns on quarantine of URIs that returned
151 .IR LDAP_UNAVAILABLE ,
152 so that an attempt to reconnect only occurs at given intervals instead
153 of any time a client requests an operation.
154 The pattern is: retry only after at least
156 seconds elapsed since last attempt, for exactly
158 times; then use the next pattern.
161 for the last pattern is "\fB+\fP", it retries forever; otherwise,
162 no more retries occur.
163 This directive must appear before any target specification;
164 it affects all targets with the same pattern.
167 .B rebind-as-user {NO|yes}
168 If this option is given, the client's bind credentials are remembered
169 for rebinds, when trying to re-establish a broken connection,
170 or when chasing a referral, if
176 .B session\-tracking\-request {NO|yes}
177 Adds session tracking control for all requests.
178 The client's IP and hostname, and the identity associated to each request,
179 if known, are sent to the remote server for informational purposes.
180 This directive is incompatible with setting \fIprotocol\-version\fP to 2.
181 If set before any target specification, it affects all targets, unless
182 overridden by any per-target directive.
185 .B single\-conn {NO|yes}
186 Discards current cached connection when the client rebinds.
189 .B use-temporary-conn {NO|yes}
192 create a temporary connection whenever competing with other threads
193 for a shared one; otherwise, wait until the shared connection is available.
195 .SH TARGET SPECIFICATION
196 Target specification starts with a "uri" directive:
199 .B uri <protocol>://[<host>[:<port>]]/<naming context>
200 The "server" directive that was allowed in the LDAP backend (although
201 deprecated) has been completely discarded in the Meta backend.
202 The <protocol> part can be anything
203 .BR ldap_initialize (3)
204 accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
205 omitted, defaulting to whatever is set in
207 The <naming context> part is mandatory.
208 It must end with one of the naming contexts defined for the backend,
213 suffix "\fBdc=foo,dc=com\fP"
214 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
219 The <naming context> part doesn't need to be unique across the targets;
220 it may also match one of the values of the "suffix" directive.
221 Multiple URIs may be defined in a single argument. The URIs must
222 be separated by TABs (e.g. '\\t'; commas or spaces, unlike back-ldap,
224 because they are legal in the <naming context>, and we don't want to use
225 URL-encoded <naming context>s), and the additional URIs must have
226 no <naming context> part. This causes the underlying library
227 to contact the first server of the list that responds.
228 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
229 of the same server, the directive
232 suffix "\fBdc=foo,dc=com\fP"
233 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP ldap://l2.foo.com/"
238 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
243 .B acl-authcDN "<administrative DN for access control purposes>"
244 DN which is used to query the target server for acl checking,
245 as in the LDAP backend; it is supposed to have read access
246 on the target server to attributes used on the proxy for acl checking.
247 There is no risk of giving away such values; they are only used to
249 .B The acl-authcDN identity is by no means implicitly used by the proxy
250 .B when the client connects anonymously.
253 .B acl-passwd <password>
254 Password used with the
260 .B bind-timeout <microseconds>
261 This directive defines the timeout, in microseconds, used when polling
262 for response after an asynchronous bind connection. The initial call
263 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
264 if that results in a timeout exceeded, subsequent calls use the value
267 The default value is used also for subsequent calls if
270 If set before any target specification, it affects all targets, unless
271 overridden by any per-target directive.
274 .B chase-referrals {YES|no}
275 enable/disable automatic referral chasing, which is delegated to the
276 underlying libldap, with rebinding eventually performed if the
277 \fBrebind-as-user\fP directive is used. The default is to chase referrals.
278 If set before any target specification, it affects all targets, unless
279 overridden by any per-target directive.
282 .B default-target [<target>]
283 The "default-target" directive can also be used during target specification.
284 With no arguments it marks the current target as the default.
285 The optional number marks target <target> as the default one, starting
287 Target <target> must be defined.
290 .B idle-timeout <time>
291 This directive causes a cached connection to be dropped an recreated
292 after it has been idle for the specified time.
293 The value can be specified as
295 [<d>d][<h>h][<m>m][<s>[s]]
297 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
299 If set before any target specification, it affects all targets, unless
300 overridden by any per-target directive.
303 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
304 This maps object classes and attributes as in the LDAP backend.
309 .B network-timeout <time>
310 Sets the network timeout value after which
311 .BR poll (2)/ select (2)
314 returns in case of no activity.
315 The value is in seconds, and it can be specified as for
317 If set before any target specification, it affects all targets, unless
318 overridden by any per-target directive.
321 .B nretries {forever|never|<nretries>}
322 This directive defines how many times a bind should be retried
323 in case of temporary failure in contacting a target. If defined
324 before any target specification, it applies to all targets (by default,
327 the global value can be overridden by redefinitions inside each target
331 .B pseudorootdn "<substitute DN in case of rootdn bind>"
332 This directive, if present, sets the DN that will be substituted to
333 the bind DN if a bind with the backend's "rootdn" succeeds.
334 The true "rootdn" of the target server ought not be used; an arbitrary
335 administrative DN should used instead.
338 .B pseudorootpw "<substitute password in case of rootdn bind>"
339 This directive sets the credential that will be used in case a bind
340 with the backend's "rootdn" succeeds, and the bind is propagated to
341 the target using the "pseudorootdn" DN.
343 Note: cleartext credentials must be supplied here; as a consequence,
344 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
348 The rewrite options are described in the "REWRITING" section.
351 .B subtree-exclude "<DN>"
352 This directive instructs back-meta to ignore the current target
353 for operations whose requestDN is subordinate to
355 There may be multiple occurrences of the
357 directive for each of the targets.
360 .B suffixmassage "<virtual naming context>" "<real naming context>"
361 All the directives starting with "rewrite" refer to the rewrite engine
362 that has been added to slapd.
363 The "suffixmassage" directive was introduced in the LDAP backend to
364 allow suffix massaging while proxying.
365 It has been obsoleted by the rewriting tools.
366 However, both for backward compatibility and for ease of configuration
367 when simple suffix massage is required, it has been preserved.
368 It wraps the basic rewriting instructions that perform suffix
369 massaging. See the "REWRITING" section for a detailed list
370 of the rewrite rules it implies.
373 .B t-f-support {NO|yes|discover}
374 enable if the remote server supports absolute filters
375 (see \fIdraft-zeilenga-ldap-t-f\fP for details).
378 support is detected by reading the remote server's root DSE.
379 If set before any target specification, it affects all targets, unless
380 overridden by any per-target directive.
383 .B timeout [<op>=]<val> [...]
384 This directive allows to set per-operation timeouts.
387 \fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
389 The overall duration of the \fBsearch\fP operation is controlled either
390 by the \fBtimelimit\fP parameter or by server-side enforced
391 time limits (see \fBtimelimit\fP and \fBlimits\fP in
394 This \fBtimeout\fP parameter controls how long the target can be
395 irresponsive before the operation is aborted.
396 Timeout is meaningless for the remaining operations,
397 \fBunbind\fP and \fBabandon\fP, which do not imply any response,
398 while it is not yet implemented in currently supported \fBextended\fP
400 If no operation is specified, the timeout \fBval\fP affects all
401 supported operations.
402 If specified before any target definition, it affects all targets
403 unless overridden by per-target directives.
405 Note: if the timelimit is exceeded, the operation is cancelled
406 (according to the \fBcancel\fP directive);
407 the protocol does not provide any means to rollback operations,
408 so the client will not be notified about the result of the operation,
409 which may eventually succeeded or not.
410 In case the timeout is exceeded during a bind operation, the connection
411 is destroyed, according to RFC4511.
414 .B tls {[try-]start|[try-]propagate}
415 execute the StartTLS extended operation when the connection is initialized;
416 only works if the URI directive protocol scheme is not \fBldaps://\fP.
417 \fBpropagate\fP issues the StartTLS operation only if the original
419 The \fBtry-\fP prefix instructs the proxy to continue operations
420 if the StartTLS operation failed; its use is highly deprecated.
421 If set before any target specification, it affects all targets, unless
422 overridden by any per-target directive.
425 A powerful (and in some sense dangerous) rewrite engine has been added
426 to both the LDAP and Meta backends.
427 While the former can gain limited beneficial effects from rewriting
428 stuff, the latter can become an amazingly powerful tool.
430 Consider a couple of scenarios first.
432 1) Two directory servers share two levels of naming context;
433 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
434 Then, an unambiguous Meta database can be configured as:
439 suffix "\fBdc=foo,dc=com\fP"
440 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
441 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
445 Operations directed to a specific target can be easily resolved
446 because there are no ambiguities.
447 The only operation that may resolve to multiple targets is a search
448 with base "dc=foo,dc=com" and scope at least "one", which results in
449 spawning two searches to the targets.
451 2a) Two directory servers don't share any portion of naming context,
452 but they'd present as a single DIT
453 [Caveat: uniqueness of (massaged) entries among the two servers is
454 assumed; integrity checks risk to incur in excessive overhead and have
455 not been implemented].
456 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
457 and we'd like them to appear as branches of "dc=foo,dc=com", say
458 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
459 Then we need to configure our Meta backend as:
464 suffix "dc=foo,dc=com"
466 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
467 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
469 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
470 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
474 Again, operations can be resolved without ambiguity, although
475 some rewriting is required.
476 Notice that the virtual naming context of each target is a branch of
477 the database's naming context; it is rewritten back and forth when
478 operations are performed towards the target servers.
479 What "back and forth" means will be clarified later.
481 When a search with base "dc=foo,dc=com" is attempted, if the
482 scope is "base" it fails with "no such object"; in fact, the
483 common root of the two targets (prior to massaging) does not
485 If the scope is "one", both targets are contacted with the base
486 replaced by each target's base; the scope is derated to "base".
487 In general, a scope "one" search is honored, and the scope is derated,
488 only when the incoming base is at most one level lower of a target's
489 naming context (prior to massaging).
491 Finally, if the scope is "sub" the incoming base is replaced
492 by each target's unmassaged naming context, and the scope
495 2b) Consider the above reported scenario with the two servers
496 sharing the same naming context:
501 suffix "\fBdc=foo,dc=com\fP"
503 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
504 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
506 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
507 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
511 All the previous considerations hold, except that now there is
512 no way to unambiguously resolve a DN.
513 In this case, all the operations that require an unambiguous target
514 selection will fail unless the DN is already cached or a default
516 Practical configurations may result as a combination of all the
519 Note on ACLs: at present you may add whatever ACL rule you desire
520 to to the Meta (and LDAP) backends.
521 However, the meaning of an ACL on a proxy may require some
523 Two philosophies may be considered:
525 a) the remote server dictates the permissions; the proxy simply passes
526 back what it gets from the remote server.
528 b) the remote server unveils "everything"; the proxy is responsible
529 for protecting data from unauthorized access.
531 Of course the latter sounds unreasonable, but it is not.
532 It is possible to imagine scenarios in which a remote host discloses
533 data that can be considered "public" inside an intranet, and a proxy
534 that connects it to the internet may impose additional constraints.
535 To this purpose, the proxy should be able to comply with all the ACL
536 matching criteria that the server supports.
537 This has been achieved with regard to all the criteria supported by
538 slapd except a special subtle case (please drop me a note if you can
539 find other exceptions: <ando@openldap.org>).
544 access to dn="<dn>" attrs=<attr>
545 by dnattr=<dnattr> read
550 cannot be matched iff the attribute that is being requested, <attr>,
551 is NOT <dnattr>, and the attribute that determines membership,
552 <dnattr>, has not been requested (e.g. in a search)
554 In fact this ACL is resolved by slapd using the portion of entry it
555 retrieved from the remote server without requiring any further
556 intervention of the backend, so, if the <dnattr> attribute has not
557 been fetched, the match cannot be assessed because the attribute is
558 not present, not because no value matches the requirement!
560 Note on ACLs and attribute mapping: ACLs are applied to the mapped
561 attributes; for instance, if the attribute locally known as "foo" is
562 mapped to "bar" on a remote server, then local ACLs apply to attribute
563 "foo" and are totally unaware of its remote name.
564 The remote server will check permissions for "bar", and the local
565 server will possibly enforce additional restrictions to "foo".
567 .\" If this section is moved, also update the reference in
568 .\" libraries/librewrite/RATIONALE.
571 A string is rewritten according to a set of rules, called a `rewrite
573 The rules are based on POSIX (''extended'') regular expressions (regex)
574 with substring matching; basic variable substitution and map resolution
575 of substrings is allowed by specific mechanisms detailed in the following.
576 The behavior of pattern matching/substitution can be altered by a set
579 The underlying concept is to build a lightweight rewrite module
580 for the slapd server (initially dedicated to the LDAP backend).
582 An incoming string is matched against a set of rules.
583 Rules are made of a regex match pattern, a substitution pattern
584 and a set of actions, described by a set of flags.
585 In case of match a string rewriting is performed according to the
586 substitution pattern that allows to refer to substrings matched in the
588 The actions, if any, are finally performed.
589 The substitution pattern allows map resolution of substrings.
590 A map is a generic object that maps a substitution pattern to a value.
591 The flags are divided in "Pattern matching Flags" and "Action Flags";
592 the former alter the regex match pattern behavior while the latter
593 alter the action that is taken after substitution.
594 .SH "Pattern Matching Flags"
597 honors case in matching (default is case insensitive)
600 use POSIX ''basic'' regular expressions (default is ''extended'')
605 recursive passes for a specific rule; does not alter the max total count
606 of passes, so it can only enforce a stricter limit for a specific rule.
610 apply the rule once only (default is recursive)
613 stop applying rules in case of match; the current rule is still applied
614 recursively; combine with `:' to apply the current rule only once
618 stop current operation if the rule matches, and issue an `unwilling to
624 rules back and forth (watch for loops!).
625 Note that `G{1}' is implicit in every rule.
628 ignores errors in rule; this means, in case of error, e.g. issued by a
629 map, the error is treated as a missed match.
630 The `unwilling to perform' is not overridden.
636 as return code if the rule matches; the flag does not alter the recursive
637 behavior of the rule, so, to have it performed only once, it must be used
638 in combination with `:', e.g.
640 returns the value `16' after exactly one execution of the rule, if the
642 As a consequence, its behavior is equivalent to `@', with the return
645 or, in other words, `@' is equivalent to `U{0}'.
646 By convention, the freely available codes are above 16 included;
647 the others are reserved.
649 The ordering of the flags can be significant.
650 For instance: `IG{2}' means ignore errors and jump two lines ahead
651 both in case of match and in case of error, while `G{2}I' means ignore
652 errors, but jump two lines ahead only in case of match.
654 More flags (mainly Action Flags) will be added as needed.
655 .SH "Pattern matching:"
660 .SH "Substitution Pattern Syntax:"
661 Everything starting with `%' requires substitution;
663 the only obvious exception is `%%', which is left as is;
665 the basic substitution is `%d', where `d' is a digit;
666 0 means the whole string, while 1-9 is a submatch;
668 a `%' followed by a `{' invokes an advanced substitution.
672 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
675 where <name> must be a legal name for the map, i.e.
679 <name> ::= [a-z][a-z0-9]* (case insensitive)
680 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
684 and <substitution> must be a legal substitution
685 pattern, with no limits on the nesting level.
690 sub context invocation; <name> must be a legal, already defined
694 external command invocation; <name> must refer to a legal, already
695 defined command name (NOT IMPL.)
698 variable assignment; <name> defines a variable in the running
699 operation structure which can be dereferenced later; operator
701 assigns a variable in the rewrite context scope; operator
703 assigns a variable that scopes the entire session, e.g. its value
704 can be dereferenced later by other rewrite contexts
707 variable dereferencing; <name> must refer to a variable that is
708 defined and assigned for the running operation; operator
710 dereferences a variable scoping the rewrite context; operator
712 dereferences a variable scoping the whole session, e.g. the value
713 is passed across rewrite contexts
716 parameter dereferencing; <name> must refer to an existing parameter;
717 the idea is to make some run-time parameters set by the system
718 available to the rewrite engine, as the client host name, the bind DN
719 if any, constant parameters initialized at config time, and so on;
720 no parameter is currently set by either
724 but constant parameters can be defined in the configuration file
729 Substitution escaping has been delegated to the `%' symbol,
730 which is used instead of `\e' in string substitution patterns
731 because `\e' is already escaped by slapd's low level parsing routines;
732 as a consequence, regex escaping requires two `\e' symbols,
733 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
735 .\" The symbol can be altered at will by redefining the related macro in
738 .SH "Rewrite context:"
739 A rewrite context is a set of rules which are applied in sequence.
740 The basic idea is to have an application initialize a rewrite
741 engine (think of Apache's mod_rewrite ...) with a set of rewrite
742 contexts; when string rewriting is required, one invokes the
743 appropriate rewrite context with the input string and obtains the
744 newly rewritten one if no errors occur.
746 Each basic server operation is associated to a rewrite context;
747 they are divided in two main groups: client \-> server and
748 server \-> client rewriting.
754 (default) if defined and no specific context
759 searchFilterAttrDN search
761 compareAttrDN compare AVA
765 modifyAttrDN modify AVA
769 exopPasswdDN password modify extended operation DN if proxy
777 searchResult search (only if defined; no default;
778 acts on DN and DN-syntax attributes
780 searchAttrDN search AVA
781 matchedDN all ops (only if applicable)
785 .SH "Basic configuration syntax"
787 .B rewriteEngine { on | off }
788 If `on', the requested rewriting is performed; if `off', no
789 rewriting takes place (an easy way to stop rewriting without
790 altering too much the configuration file).
792 .B rewriteContext <context name> "[ alias <aliased context name> ]"
793 <Context name> is the name that identifies the context, i.e. the name
794 used by the application to refer to the set of rules it contains.
795 It is used also to reference sub contexts in string rewriting.
796 A context may alias another one.
797 In this case the alias context contains no rule, and any reference to
798 it will result in accessing the aliased one.
800 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
801 Determines how a string can be rewritten if a pattern is matched.
802 Examples are reported below.
803 .SH "Additional configuration syntax:"
805 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
806 Allows to define a map that transforms substring rewriting into
808 The map is referenced inside the substitution pattern of a rule.
810 .B rewriteParam <param name> <param value>
811 Sets a value with global scope, that can be dereferenced by the
812 command `%{$paramName}'.
814 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
815 Sets the maximum number of total rewriting passes that can be
816 performed in a single rewrite operation (to avoid loops).
817 A safe default is set to 100; note that reaching this limit is still
818 treated as a success; recursive invocation of rules is simply
820 The count applies to the rewriting operation as a whole, not
821 to any single rule; an optional per-rule limit can be set.
822 This limit is overridden by setting specific per-rule limits
823 with the `M{n}' flag.
824 .SH "Configuration examples:"
826 # set to `off' to disable rewriting
829 # the rules the "suffixmassage" directive implies
831 # all dataflow from client to server referring to DNs
832 rewriteContext default
833 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
835 rewriteContext searchFilter
836 # all dataflow from server to client
837 rewriteContext searchResult
838 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
839 rewriteContext searchAttrDN alias searchResult
840 rewriteContext matchedDN alias searchResult
842 # Everything defined here goes into the `default' context.
843 # This rule changes the naming context of anything sent
844 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
846 rewriteRule "(.*)dc=home,[ ]?dc=net"
847 "%1dc=OpenLDAP, dc=org" ":"
849 # since a pretty/normalized DN does not include spaces
850 # after rdn separators, e.g. `,', this rule suffices:
852 rewriteRule "(.*)dc=home,dc=net"
853 "%1dc=OpenLDAP,dc=org" ":"
855 # Start a new context (ends input of the previous one).
856 # This rule adds blanks between DN parts if not present.
857 rewriteContext addBlanks
858 rewriteRule "(.*),([^ ].*)" "%1, %2"
860 # This one eats blanks
861 rewriteContext eatBlanks
862 rewriteRule "(.*),[ ](.*)" "%1,%2"
864 # Here control goes back to the default rewrite
865 # context; rules are appended to the existing ones.
866 # anything that gets here is piped into rule `addBlanks'
867 rewriteContext default
868 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
870 .\" # Anything with `uid=username' is looked up in
871 .\" # /etc/passwd for gecos (I know it's nearly useless,
872 .\" # but it is there just as a guideline to implementing
874 .\" # Note the `I' flag that leaves `uid=username' in place
875 .\" # if `username' does not have a valid account, and the
876 .\" # `:' that forces the rule to be processed exactly once.
877 .\" rewriteContext uid2Gecos
878 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
879 .\" "%1cn=%2{xpasswd},%3" "I:"
881 .\" # Finally, in a bind, if one uses a `uid=username' DN,
882 .\" # it is rewritten in `cn=name surname' if possible.
883 .\" rewriteContext bindDN
884 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
886 # Rewrite the search base according to `default' rules.
887 rewriteContext searchBase alias default
889 # Search results with OpenLDAP DN are rewritten back with
890 # `dc=home,dc=net' naming context, with spaces eaten.
891 rewriteContext searchResult
892 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
893 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
895 # Bind with email instead of full DN: we first need
896 # an ldap map that turns attributes into a DN (the
897 # argument used when invoking the map is appended to
898 # the URI and acts as the filter portion)
899 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
901 # Then we need to detect DN made up of a single email,
902 # e.g. `mail=someone@example.com'; note that the rule
903 # in case of match stops rewriting; in case of error,
904 # it is ignored. In case we are mapping virtual
905 # to real naming contexts, we also need to rewrite
906 # regular DNs, because the definition of a bindDn
907 # rewrite context overrides the default definition.
908 rewriteContext bindDN
909 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
911 # This is a rather sophisticated example. It massages a
912 # search filter in case who performs the search has
913 # administrative privileges. First we need to keep
914 # track of the bind DN of the incoming request, which is
915 # stored in a variable called `binddn' with session scope,
916 # and left in place to allow regular binding:
917 rewriteContext bindDN
918 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
920 # A search filter containing `uid=' is rewritten only
921 # if an appropriate DN is bound.
922 # To do this, in the first rule the bound DN is
923 # dereferenced, while the filter is decomposed in a
924 # prefix, in the value of the `uid=<arg>' AVA, and
925 # in a suffix. A tag `<>' is appended to the DN.
926 # If the DN refers to an entry in the `ou=admin' subtree,
927 # the filter is rewritten OR-ing the `uid=<arg>' with
928 # `cn=<arg>'; otherwise it is left as is. This could be
929 # useful, for instance, to allow apache's auth_ldap-1.4
930 # module to authenticate users with both `uid' and
931 # `cn', but only if the request comes from a possible
932 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
933 rewriteContext searchFilter
934 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
935 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
937 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
938 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
939 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
941 # This example shows how to strip unwanted DN-valued
942 # attribute values from a search result; the first rule
943 # matches DN values below "ou=People,dc=example,dc=com";
944 # in case of match the rewriting exits successfully.
945 # The second rule matches everything else and causes
946 # the value to be rejected.
947 rewriteContext searchResult
948 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
949 rewriteRule ".*" "" "#"
951 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
952 In case the rewritten DN is an LDAP URI, the operation is initiated
953 towards the host[:port] indicated in the uri, if it does not refer
958 rewriteRule '^cn=root,.*' '%0' 'G{3}'
959 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
960 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
961 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
964 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
968 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
971 with the advantage of saving one rewrite pass ...)
976 backend does not honor all ACL semantics as described in
977 .BR slapd.access (5).
978 In general, access checking is delegated to the remote server(s).
983 pseudo-attribute and to the other attribute values of the entries
986 operation is honored, which is performed by the frontend.
988 .SH PROXY CACHE OVERLAY
989 The proxy cache overlay
990 allows caching of LDAP search requests (queries) in a local database.
997 default slapd configuration file
1000 .BR slapd\-ldap (5),
1001 .BR slapo\-pcache (5),
1006 Pierangelo Masarati, based on back-ldap by Howard Chu