1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2008 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.
134 do not return search reference responses.
135 By default, they are returned unless request is LDAPv2.
136 If set before any target specification, it affects all targets, unless
137 overridden by any per-target directive.
140 .B noundeffilter <NO|yes>
143 return success instead of searching if a filter is undefined or contains
145 By default, the search is propagated after replacing undefined portions
147 .BR (!(objectClass=*)) ,
148 which corresponds to the empty result set.
149 If set before any target specification, it affects all targets, unless
150 overridden by any per-target directive.
153 .B protocol\-version {0,2,3}
154 This directive indicates what protocol version must be used to contact
156 If set to 0 (the default), the proxy uses the same protocol version
157 used by the client, otherwise the requested protocol is used.
158 The proxy returns \fIunwillingToPerform\fP if an operation that is
159 incompatible with the requested protocol is attempted.
160 If set before any target specification, it affects all targets, unless
161 overridden by any per-target directive.
164 .B pseudoroot-bind-defer {YES|no}
165 This directive, when set to
167 causes the authentication to the remote servers with the pseudo-root
168 identity to be deferred until actually needed by subsequent operations.
169 Otherwise, all binds as the rootdn are propagated to the targets.
172 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
173 Turns on quarantine of URIs that returned
174 .IR LDAP_UNAVAILABLE ,
175 so that an attempt to reconnect only occurs at given intervals instead
176 of any time a client requests an operation.
177 The pattern is: retry only after at least
179 seconds elapsed since last attempt, for exactly
181 times; then use the next pattern.
184 for the last pattern is "\fB+\fP", it retries forever; otherwise,
185 no more retries occur.
186 This directive must appear before any target specification;
187 it affects all targets with the same pattern.
190 .B rebind-as-user {NO|yes}
191 If this option is given, the client's bind credentials are remembered
192 for rebinds, when trying to re-establish a broken connection,
193 or when chasing a referral, if
199 .B session\-tracking\-request {NO|yes}
200 Adds session tracking control for all requests.
201 The client's IP and hostname, and the identity associated to each request,
202 if known, are sent to the remote server for informational purposes.
203 This directive is incompatible with setting \fIprotocol\-version\fP to 2.
204 If set before any target specification, it affects all targets, unless
205 overridden by any per-target directive.
208 .B single\-conn {NO|yes}
209 Discards current cached connection when the client rebinds.
212 .B use-temporary-conn {NO|yes}
215 create a temporary connection whenever competing with other threads
216 for a shared one; otherwise, wait until the shared connection is available.
218 .SH TARGET SPECIFICATION
219 Target specification starts with a "uri" directive:
222 .B uri <protocol>://[<host>]/<naming context> [...]
223 The <protocol> part can be anything
224 .BR ldap_initialize (3)
225 accepts ({ldap|ldaps|ldapi} and variants); the <host> may be
226 omitted, defaulting to whatever is set in
228 The <naming context> part is \fImandatory\fP for the first URI,
229 but it \fImust be omitted\fP for subsequent ones, if any.
230 The naming context part must be within the naming context defined for the backend,
235 suffix "\fBdc=foo,dc=com\fP"
236 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
241 The <naming context> part doesn't need to be unique across the targets;
242 it may also match one of the values of the "suffix" directive.
243 Multiple URIs may be defined in a single URI statement.
244 The additional URIs must be separate arguments and must not have any
245 <naming context> part. This causes the underlying library
246 to contact the first server of the list that responds.
247 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
248 of the same server, the directive
251 suffix "\fBdc=foo,dc=com\fP"
252 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP" "ldap://l2.foo.com/"
257 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
259 In that case, the URI list is internally rearranged, by moving unavailable
260 URIs to the end, so that further connection attempts occur with respect to
261 the last URI that succeeded.
265 .B acl-authcDN "<administrative DN for access control purposes>"
266 DN which is used to query the target server for acl checking,
267 as in the LDAP backend; it is supposed to have read access
268 on the target server to attributes used on the proxy for acl checking.
269 There is no risk of giving away such values; they are only used to
271 .B The acl-authcDN identity is by no means implicitly used by the proxy
272 .B when the client connects anonymously.
275 .B acl-passwd <password>
276 Password used with the
282 .B bind-timeout <microseconds>
283 This directive defines the timeout, in microseconds, used when polling
284 for response after an asynchronous bind connection. The initial call
285 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
286 if that results in a timeout exceeded, subsequent calls use the value
289 The default value is used also for subsequent calls if
292 If set before any target specification, it affects all targets, unless
293 overridden by any per-target directive.
296 .B chase-referrals {YES|no}
297 enable/disable automatic referral chasing, which is delegated to the
298 underlying libldap, with rebinding eventually performed if the
299 \fBrebind-as-user\fP directive is used. The default is to chase referrals.
300 If set before any target specification, it affects all targets, unless
301 overridden by any per-target directive.
304 .B default-target [<target>]
305 The "default-target" directive can also be used during target specification.
306 With no arguments it marks the current target as the default.
307 The optional number marks target <target> as the default one, starting
309 Target <target> must be defined.
312 .B idassert-authzFrom <authz-regexp>
313 if defined, selects what
315 identities are authorized to exploit the identity assertion feature.
318 follows the rules defined for the
325 for details on the syntax of this field.
330 .B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
331 .B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
332 .B [authcId=<authentication ID>] [authzId=<authorization ID>]
333 .B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
336 .B [tls_cacert=<file>]
337 .B [tls_cacertdir=<path>]
338 .B [tls_reqcert=never|allow|try|demand]
339 .B [tls_ciphersuite=<ciphers>]
340 .B [tls_crlcheck=none|peer|all]
342 Allows to define the parameters of the authentication method that is
343 internally used by the proxy to authorize connections that are
344 authenticated by other databases.
345 The identity defined by this directive, according to the properties
346 associated to the authentication method, is supposed to have auth access
347 on the target server to attributes used on the proxy for authentication
348 and authorization, and to be allowed to authorize the users.
349 This requires to have
351 privileges on a wide set of DNs, e.g.
352 .BR authzTo=dn.subtree:"" ,
353 and the remote server to have
361 for details on these statements and for remarks and drawbacks about
363 The supported bindmethods are
365 \fBnone|simple|sasl\fP
369 is the default, i.e. no \fIidentity assertion\fP is performed.
371 The authz parameter is used to instruct the SASL bind to exploit
373 SASL authorization, if available; since connections are cached,
374 this should only be used when authorizing with a fixed identity
375 (e.g. by means of the
380 Otherwise, the default
382 is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370)
383 is added to all operations.
385 The supported modes are:
387 \fB<mode> := {legacy|anonymous|none|self}\fP
393 is given, the proxy always authorizes that identity.
394 .B <authorization ID>
401 The former is supposed to be expanded by the remote server according
402 to the authz rules; see
405 In the latter case, whether or not the
407 prefix is present, the string must pass DN validation and normalization.
411 which implies that the proxy will either perform a simple bind as the
413 or a SASL bind as the
415 and assert the client's identity when it is not anonymous.
416 Direct binds are always proxied.
417 The other modes imply that the proxy will always either perform a simple bind
420 or a SASL bind as the
423 .BR idassert-authzFrom
424 rules (see below), in which case the operation will fail;
425 eventually, it will assert some other identity according to
427 Other identity assertion modes are
431 which respectively mean that the
438 which means that no proxyAuthz control will be used, so the
442 identity will be asserted.
443 For all modes that require the use of the
445 control, on the remote server the proxy identity must have appropriate
447 permissions, or the asserted identities must have appropriate
449 permissions. Note, however, that the ID assertion feature is mostly
450 useful when the asserted identities do not exist on the remote server.
454 \fBoverride,[non-]prescriptive\fP
458 flag is used, identity assertion takes place even when the database
459 is authorizing for the identity of the client, i.e. after binding
460 with the provided identity, and thus authenticating it, the proxy
461 performs the identity assertion using the configured identity and
462 authentication method.
466 flag is used (the default), operations fail with
467 \fIinappropriateAuthentication\fP
468 for those identities whose assertion is not allowed by the
469 .B idassert-authzFrom
473 flag is used, operations are performed anonymously for those identities
474 whose assertion is not allowed by the
475 .B idassert-authzFrom
478 The TLS settings default to the same as the main slapd TLS settings,
481 which defaults to "demand".
483 The identity associated to this directive is also used for privileged
484 operations whenever \fBidassert-bind\fP is defined and \fBacl-bind\fP
485 is not. See \fBacl-bind\fP for details.
489 .B idle-timeout <time>
490 This directive causes a cached connection to be dropped an recreated
491 after it has been idle for the specified time.
492 The value can be specified as
494 [<d>d][<h>h][<m>m][<s>[s]]
496 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
498 If set before any target specification, it affects all targets, unless
499 overridden by any per-target directive.
502 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
503 This maps object classes and attributes as in the LDAP backend.
508 .B network-timeout <time>
509 Sets the network timeout value after which
510 .BR poll (2)/ select (2)
513 returns in case of no activity.
514 The value is in seconds, and it can be specified as for
516 If set before any target specification, it affects all targets, unless
517 overridden by any per-target directive.
520 .B nretries {forever|never|<nretries>}
521 This directive defines how many times a bind should be retried
522 in case of temporary failure in contacting a target. If defined
523 before any target specification, it applies to all targets (by default,
526 the global value can be overridden by redefinitions inside each target
530 .B pseudorootdn "<substitute DN in case of rootdn bind>"
531 This directive, if present, sets the DN that will be substituted to
532 the bind DN if a bind with the backend's "rootdn" succeeds.
533 The true "rootdn" of the target server ought not be used; an arbitrary
534 administrative DN should used instead.
537 .B pseudorootpw "<substitute password in case of rootdn bind>"
538 This directive sets the credential that will be used in case a bind
539 with the backend's "rootdn" succeeds, and the bind is propagated to
540 the target using the "pseudorootdn" DN.
542 Note: cleartext credentials must be supplied here; as a consequence,
543 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
547 The rewrite options are described in the "REWRITING" section.
550 .B subtree-exclude "<DN>"
551 This directive instructs back-meta to ignore the current target
552 for operations whose requestDN is subordinate to
554 There may be multiple occurrences of the
556 directive for each of the targets.
559 .B suffixmassage "<virtual naming context>" "<real naming context>"
560 All the directives starting with "rewrite" refer to the rewrite engine
561 that has been added to slapd.
562 The "suffixmassage" directive was introduced in the LDAP backend to
563 allow suffix massaging while proxying.
564 It has been obsoleted by the rewriting tools.
565 However, both for backward compatibility and for ease of configuration
566 when simple suffix massage is required, it has been preserved.
567 It wraps the basic rewriting instructions that perform suffix
568 massaging. See the "REWRITING" section for a detailed list
569 of the rewrite rules it implies.
572 .B t-f-support {NO|yes|discover}
573 enable if the remote server supports absolute filters
574 (see \fIdraft-zeilenga-ldap-t-f\fP for details).
577 support is detected by reading the remote server's root DSE.
578 If set before any target specification, it affects all targets, unless
579 overridden by any per-target directive.
582 .B timeout [<op>=]<val> [...]
583 This directive allows to set per-operation timeouts.
586 \fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
588 The overall duration of the \fBsearch\fP operation is controlled either
589 by the \fBtimelimit\fP parameter or by server-side enforced
590 time limits (see \fBtimelimit\fP and \fBlimits\fP in
593 This \fBtimeout\fP parameter controls how long the target can be
594 irresponsive before the operation is aborted.
595 Timeout is meaningless for the remaining operations,
596 \fBunbind\fP and \fBabandon\fP, which do not imply any response,
597 while it is not yet implemented in currently supported \fBextended\fP
599 If no operation is specified, the timeout \fBval\fP affects all
600 supported operations.
601 If specified before any target definition, it affects all targets
602 unless overridden by per-target directives.
604 Note: if the timeout is exceeded, the operation is cancelled
605 (according to the \fBcancel\fP directive);
606 the protocol does not provide any means to rollback operations,
607 so the client will not be notified about the result of the operation,
608 which may eventually succeeded or not.
609 In case the timeout is exceeded during a bind operation, the connection
610 is destroyed, according to RFC4511.
613 .B tls {[try-]start|[try-]propagate}
614 execute the StartTLS extended operation when the connection is initialized;
615 only works if the URI directive protocol scheme is not \fBldaps://\fP.
616 \fBpropagate\fP issues the StartTLS operation only if the original
618 The \fBtry-\fP prefix instructs the proxy to continue operations
619 if the StartTLS operation failed; its use is highly deprecated.
620 If set before any target specification, it affects all targets, unless
621 overridden by any per-target directive.
624 A powerful (and in some sense dangerous) rewrite engine has been added
625 to both the LDAP and Meta backends.
626 While the former can gain limited beneficial effects from rewriting
627 stuff, the latter can become an amazingly powerful tool.
629 Consider a couple of scenarios first.
631 1) Two directory servers share two levels of naming context;
632 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
633 Then, an unambiguous Meta database can be configured as:
638 suffix "\fBdc=foo,dc=com\fP"
639 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
640 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
644 Operations directed to a specific target can be easily resolved
645 because there are no ambiguities.
646 The only operation that may resolve to multiple targets is a search
647 with base "dc=foo,dc=com" and scope at least "one", which results in
648 spawning two searches to the targets.
650 2a) Two directory servers don't share any portion of naming context,
651 but they'd present as a single DIT
652 [Caveat: uniqueness of (massaged) entries among the two servers is
653 assumed; integrity checks risk to incur in excessive overhead and have
654 not been implemented].
655 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
656 and we'd like them to appear as branches of "dc=foo,dc=com", say
657 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
658 Then we need to configure our Meta backend as:
663 suffix "dc=foo,dc=com"
665 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
666 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
668 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
669 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
673 Again, operations can be resolved without ambiguity, although
674 some rewriting is required.
675 Notice that the virtual naming context of each target is a branch of
676 the database's naming context; it is rewritten back and forth when
677 operations are performed towards the target servers.
678 What "back and forth" means will be clarified later.
680 When a search with base "dc=foo,dc=com" is attempted, if the
681 scope is "base" it fails with "no such object"; in fact, the
682 common root of the two targets (prior to massaging) does not
684 If the scope is "one", both targets are contacted with the base
685 replaced by each target's base; the scope is derated to "base".
686 In general, a scope "one" search is honored, and the scope is derated,
687 only when the incoming base is at most one level lower of a target's
688 naming context (prior to massaging).
690 Finally, if the scope is "sub" the incoming base is replaced
691 by each target's unmassaged naming context, and the scope
694 2b) Consider the above reported scenario with the two servers
695 sharing the same naming context:
700 suffix "\fBdc=foo,dc=com\fP"
702 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
703 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
705 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
706 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
710 All the previous considerations hold, except that now there is
711 no way to unambiguously resolve a DN.
712 In this case, all the operations that require an unambiguous target
713 selection will fail unless the DN is already cached or a default
715 Practical configurations may result as a combination of all the
718 Note on ACLs: at present you may add whatever ACL rule you desire
719 to to the Meta (and LDAP) backends.
720 However, the meaning of an ACL on a proxy may require some
722 Two philosophies may be considered:
724 a) the remote server dictates the permissions; the proxy simply passes
725 back what it gets from the remote server.
727 b) the remote server unveils "everything"; the proxy is responsible
728 for protecting data from unauthorized access.
730 Of course the latter sounds unreasonable, but it is not.
731 It is possible to imagine scenarios in which a remote host discloses
732 data that can be considered "public" inside an intranet, and a proxy
733 that connects it to the internet may impose additional constraints.
734 To this purpose, the proxy should be able to comply with all the ACL
735 matching criteria that the server supports.
736 This has been achieved with regard to all the criteria supported by
737 slapd except a special subtle case (please drop me a note if you can
738 find other exceptions: <ando@openldap.org>).
743 access to dn="<dn>" attrs=<attr>
744 by dnattr=<dnattr> read
749 cannot be matched iff the attribute that is being requested, <attr>,
750 is NOT <dnattr>, and the attribute that determines membership,
751 <dnattr>, has not been requested (e.g. in a search)
753 In fact this ACL is resolved by slapd using the portion of entry it
754 retrieved from the remote server without requiring any further
755 intervention of the backend, so, if the <dnattr> attribute has not
756 been fetched, the match cannot be assessed because the attribute is
757 not present, not because no value matches the requirement!
759 Note on ACLs and attribute mapping: ACLs are applied to the mapped
760 attributes; for instance, if the attribute locally known as "foo" is
761 mapped to "bar" on a remote server, then local ACLs apply to attribute
762 "foo" and are totally unaware of its remote name.
763 The remote server will check permissions for "bar", and the local
764 server will possibly enforce additional restrictions to "foo".
766 .\" If this section is moved, also update the reference in
767 .\" libraries/librewrite/RATIONALE.
770 A string is rewritten according to a set of rules, called a `rewrite
772 The rules are based on POSIX (''extended'') regular expressions (regex)
773 with substring matching; basic variable substitution and map resolution
774 of substrings is allowed by specific mechanisms detailed in the following.
775 The behavior of pattern matching/substitution can be altered by a set
778 The underlying concept is to build a lightweight rewrite module
779 for the slapd server (initially dedicated to the LDAP backend).
781 An incoming string is matched against a set of rules.
782 Rules are made of a regex match pattern, a substitution pattern
783 and a set of actions, described by a set of flags.
784 In case of match a string rewriting is performed according to the
785 substitution pattern that allows to refer to substrings matched in the
787 The actions, if any, are finally performed.
788 The substitution pattern allows map resolution of substrings.
789 A map is a generic object that maps a substitution pattern to a value.
790 The flags are divided in "Pattern matching Flags" and "Action Flags";
791 the former alter the regex match pattern behavior while the latter
792 alter the action that is taken after substitution.
793 .SH "Pattern Matching Flags"
796 honors case in matching (default is case insensitive)
799 use POSIX ''basic'' regular expressions (default is ''extended'')
804 recursive passes for a specific rule; does not alter the max total count
805 of passes, so it can only enforce a stricter limit for a specific rule.
809 apply the rule once only (default is recursive)
812 stop applying rules in case of match; the current rule is still applied
813 recursively; combine with `:' to apply the current rule only once
817 stop current operation if the rule matches, and issue an `unwilling to
823 rules back and forth (watch for loops!).
824 Note that `G{1}' is implicit in every rule.
827 ignores errors in rule; this means, in case of error, e.g. issued by a
828 map, the error is treated as a missed match.
829 The `unwilling to perform' is not overridden.
835 as return code if the rule matches; the flag does not alter the recursive
836 behavior of the rule, so, to have it performed only once, it must be used
837 in combination with `:', e.g.
839 returns the value `16' after exactly one execution of the rule, if the
841 As a consequence, its behavior is equivalent to `@', with the return
844 or, in other words, `@' is equivalent to `U{0}'.
845 By convention, the freely available codes are above 16 included;
846 the others are reserved.
848 The ordering of the flags can be significant.
849 For instance: `IG{2}' means ignore errors and jump two lines ahead
850 both in case of match and in case of error, while `G{2}I' means ignore
851 errors, but jump two lines ahead only in case of match.
853 More flags (mainly Action Flags) will be added as needed.
854 .SH "Pattern matching:"
859 .SH "Substitution Pattern Syntax:"
860 Everything starting with `%' requires substitution;
862 the only obvious exception is `%%', which is left as is;
864 the basic substitution is `%d', where `d' is a digit;
865 0 means the whole string, while 1-9 is a submatch;
867 a `%' followed by a `{' invokes an advanced substitution.
871 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
874 where <name> must be a legal name for the map, i.e.
878 <name> ::= [a-z][a-z0-9]* (case insensitive)
879 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
883 and <substitution> must be a legal substitution
884 pattern, with no limits on the nesting level.
889 sub context invocation; <name> must be a legal, already defined
893 external command invocation; <name> must refer to a legal, already
894 defined command name (NOT IMPL.)
897 variable assignment; <name> defines a variable in the running
898 operation structure which can be dereferenced later; operator
900 assigns a variable in the rewrite context scope; operator
902 assigns a variable that scopes the entire session, e.g. its value
903 can be dereferenced later by other rewrite contexts
906 variable dereferencing; <name> must refer to a variable that is
907 defined and assigned for the running operation; operator
909 dereferences a variable scoping the rewrite context; operator
911 dereferences a variable scoping the whole session, e.g. the value
912 is passed across rewrite contexts
915 parameter dereferencing; <name> must refer to an existing parameter;
916 the idea is to make some run-time parameters set by the system
917 available to the rewrite engine, as the client host name, the bind DN
918 if any, constant parameters initialized at config time, and so on;
919 no parameter is currently set by either
923 but constant parameters can be defined in the configuration file
928 Substitution escaping has been delegated to the `%' symbol,
929 which is used instead of `\e' in string substitution patterns
930 because `\e' is already escaped by slapd's low level parsing routines;
931 as a consequence, regex escaping requires two `\e' symbols,
932 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
934 .\" The symbol can be altered at will by redefining the related macro in
937 .SH "Rewrite context:"
938 A rewrite context is a set of rules which are applied in sequence.
939 The basic idea is to have an application initialize a rewrite
940 engine (think of Apache's mod_rewrite ...) with a set of rewrite
941 contexts; when string rewriting is required, one invokes the
942 appropriate rewrite context with the input string and obtains the
943 newly rewritten one if no errors occur.
945 Each basic server operation is associated to a rewrite context;
946 they are divided in two main groups: client \-> server and
947 server \-> client rewriting.
953 (default) if defined and no specific context
958 searchFilterAttrDN search
960 compareAttrDN compare AVA
964 modifyAttrDN modify AVA
968 exopPasswdDN password modify extended operation DN if proxy
976 searchResult search (only if defined; no default;
977 acts on DN and DN-syntax attributes
979 searchAttrDN search AVA
980 matchedDN all ops (only if applicable)
984 .SH "Basic configuration syntax"
986 .B rewriteEngine { on | off }
987 If `on', the requested rewriting is performed; if `off', no
988 rewriting takes place (an easy way to stop rewriting without
989 altering too much the configuration file).
991 .B rewriteContext <context name> "[ alias <aliased context name> ]"
992 <Context name> is the name that identifies the context, i.e. the name
993 used by the application to refer to the set of rules it contains.
994 It is used also to reference sub contexts in string rewriting.
995 A context may alias another one.
996 In this case the alias context contains no rule, and any reference to
997 it will result in accessing the aliased one.
999 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
1000 Determines how a string can be rewritten if a pattern is matched.
1001 Examples are reported below.
1002 .SH "Additional configuration syntax:"
1004 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
1005 Allows to define a map that transforms substring rewriting into
1007 The map is referenced inside the substitution pattern of a rule.
1009 .B rewriteParam <param name> <param value>
1010 Sets a value with global scope, that can be dereferenced by the
1011 command `%{$paramName}'.
1013 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
1014 Sets the maximum number of total rewriting passes that can be
1015 performed in a single rewrite operation (to avoid loops).
1016 A safe default is set to 100; note that reaching this limit is still
1017 treated as a success; recursive invocation of rules is simply
1019 The count applies to the rewriting operation as a whole, not
1020 to any single rule; an optional per-rule limit can be set.
1021 This limit is overridden by setting specific per-rule limits
1022 with the `M{n}' flag.
1023 .SH "Configuration examples:"
1025 # set to `off' to disable rewriting
1028 # the rules the "suffixmassage" directive implies
1030 # all dataflow from client to server referring to DNs
1031 rewriteContext default
1032 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
1034 rewriteContext searchFilter
1035 # all dataflow from server to client
1036 rewriteContext searchResult
1037 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
1038 rewriteContext searchAttrDN alias searchResult
1039 rewriteContext matchedDN alias searchResult
1041 # Everything defined here goes into the `default' context.
1042 # This rule changes the naming context of anything sent
1043 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
1045 rewriteRule "(.*)dc=home,[ ]?dc=net"
1046 "%1dc=OpenLDAP, dc=org" ":"
1048 # since a pretty/normalized DN does not include spaces
1049 # after rdn separators, e.g. `,', this rule suffices:
1051 rewriteRule "(.*)dc=home,dc=net"
1052 "%1dc=OpenLDAP,dc=org" ":"
1054 # Start a new context (ends input of the previous one).
1055 # This rule adds blanks between DN parts if not present.
1056 rewriteContext addBlanks
1057 rewriteRule "(.*),([^ ].*)" "%1, %2"
1059 # This one eats blanks
1060 rewriteContext eatBlanks
1061 rewriteRule "(.*),[ ](.*)" "%1,%2"
1063 # Here control goes back to the default rewrite
1064 # context; rules are appended to the existing ones.
1065 # anything that gets here is piped into rule `addBlanks'
1066 rewriteContext default
1067 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
1069 .\" # Anything with `uid=username' is looked up in
1070 .\" # /etc/passwd for gecos (I know it's nearly useless,
1071 .\" # but it is there just as a guideline to implementing
1073 .\" # Note the `I' flag that leaves `uid=username' in place
1074 .\" # if `username' does not have a valid account, and the
1075 .\" # `:' that forces the rule to be processed exactly once.
1076 .\" rewriteContext uid2Gecos
1077 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
1078 .\" "%1cn=%2{xpasswd},%3" "I:"
1080 .\" # Finally, in a bind, if one uses a `uid=username' DN,
1081 .\" # it is rewritten in `cn=name surname' if possible.
1082 .\" rewriteContext bindDN
1083 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
1085 # Rewrite the search base according to `default' rules.
1086 rewriteContext searchBase alias default
1088 # Search results with OpenLDAP DN are rewritten back with
1089 # `dc=home,dc=net' naming context, with spaces eaten.
1090 rewriteContext searchResult
1091 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
1092 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
1094 # Bind with email instead of full DN: we first need
1095 # an ldap map that turns attributes into a DN (the
1096 # argument used when invoking the map is appended to
1097 # the URI and acts as the filter portion)
1098 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
1100 # Then we need to detect DN made up of a single email,
1101 # e.g. `mail=someone@example.com'; note that the rule
1102 # in case of match stops rewriting; in case of error,
1103 # it is ignored. In case we are mapping virtual
1104 # to real naming contexts, we also need to rewrite
1105 # regular DNs, because the definition of a bindDn
1106 # rewrite context overrides the default definition.
1107 rewriteContext bindDN
1108 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
1110 # This is a rather sophisticated example. It massages a
1111 # search filter in case who performs the search has
1112 # administrative privileges. First we need to keep
1113 # track of the bind DN of the incoming request, which is
1114 # stored in a variable called `binddn' with session scope,
1115 # and left in place to allow regular binding:
1116 rewriteContext bindDN
1117 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
1119 # A search filter containing `uid=' is rewritten only
1120 # if an appropriate DN is bound.
1121 # To do this, in the first rule the bound DN is
1122 # dereferenced, while the filter is decomposed in a
1123 # prefix, in the value of the `uid=<arg>' AVA, and
1124 # in a suffix. A tag `<>' is appended to the DN.
1125 # If the DN refers to an entry in the `ou=admin' subtree,
1126 # the filter is rewritten OR-ing the `uid=<arg>' with
1127 # `cn=<arg>'; otherwise it is left as is. This could be
1128 # useful, for instance, to allow apache's auth_ldap-1.4
1129 # module to authenticate users with both `uid' and
1130 # `cn', but only if the request comes from a possible
1131 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
1132 rewriteContext searchFilter
1133 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
1134 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
1136 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
1137 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
1138 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
1140 # This example shows how to strip unwanted DN-valued
1141 # attribute values from a search result; the first rule
1142 # matches DN values below "ou=People,dc=example,dc=com";
1143 # in case of match the rewriting exits successfully.
1144 # The second rule matches everything else and causes
1145 # the value to be rejected.
1146 rewriteContext searchResult
1147 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
1148 rewriteRule ".*" "" "#"
1150 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
1151 In case the rewritten DN is an LDAP URI, the operation is initiated
1152 towards the host[:port] indicated in the uri, if it does not refer
1153 to the local server.
1157 rewriteRule '^cn=root,.*' '%0' 'G{3}'
1158 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
1159 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
1160 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
1163 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
1167 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
1170 with the advantage of saving one rewrite pass ...)
1175 backend does not honor all ACL semantics as described in
1176 .BR slapd.access (5).
1177 In general, access checking is delegated to the remote server(s).
1182 pseudo-attribute and to the other attribute values of the entries
1185 operation is honored, which is performed by the frontend.
1187 .SH PROXY CACHE OVERLAY
1188 The proxy cache overlay
1189 allows caching of LDAP search requests (queries) in a local database.
1191 .BR slapo-pcache (5)
1196 default slapd configuration file
1199 .BR slapd\-ldap (5),
1200 .BR slapo\-pcache (5),
1205 Pierangelo Masarati, based on back-ldap by Howard Chu
projects / openldap / blob