1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2013 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.
43 must contain schema information for the attributes and objectClasses
44 used in filters, request DN and request-related data in general.
45 It should also contain schema information for the data returned
46 by the proxied server.
47 It is the responsibility of the proxy administrator to keep the schema
48 of the proxy lined up with that of the proxied server.
51 Note: When looping back to the same instance of \fBslapd\fP(8),
52 each connection requires a new thread; as a consequence, \fBslapd\fP(8)
53 must be compiled with thread support, and the \fBthreads\fP parameter
54 may need some tuning; in those cases, unless the multiple target feature
55 is required, one may consider using \fBslapd\-relay\fP(5) instead,
56 which performs the relayed operation internally and thus reuses
60 There are examples in various places in this document, as well as in the
61 slapd/back\-meta/data/ directory in the OpenLDAP source tree.
65 options apply to the META backend database.
66 That is, they must follow a "database meta" line and come before any
67 subsequent "backend" or "database" lines.
68 Other database options are described in the
72 Note: In early versions of back-ldap and back-meta it was recommended to always set
85 This was required because operational attributes related to entry creation
86 and modification should not be proxied, as they could be mistakenly written
87 to the target server(s), generating an error.
88 The current implementation automatically sets lastmod to \fBoff\fP,
89 so its use is redundant and should be omitted.
91 .SH SPECIAL CONFIGURATION DIRECTIVES
92 Target configuration starts with the "uri" directive.
93 All the configuration directives that are not specific to targets
94 should be defined first for clarity, including those that are common
100 This directive causes a cached connection to be dropped an recreated
101 after a given ttl, regardless of being idle or not.
104 .B default\-target none
105 This directive forces the backend to reject all those operations
106 that must resolve to a single target in case none or multiple
107 targets are selected.
108 They include: add, delete, modify, modrdn; compare is not included, as
109 well as bind since, as they don't alter entries, in case of multiple
110 matches an attempt is made to perform the operation on any candidate
111 target, with the constraint that at most one must succeed.
112 This directive can also be used when processing targets to mark a
113 specific target as default.
116 .B dncache\-ttl {DISABLED|forever|<ttl>}
117 This directive sets the time-to-live of the DN cache.
118 This caches the target that holds a given DN to speed up target
119 selection in case multiple targets would result from an uncached
120 search; forever means cache never expires; disabled means no DN
121 caching; otherwise a valid ( > 0 ) ttl is required, in the format
127 .B onerr {CONTINUE|report|stop}
128 This directive allows to select the behavior in case an error is returned
129 by one target during a search.
130 The default, \fBcontinue\fP, consists in continuing the operation,
131 trying to return as much data as possible.
132 If the value is set to \fBstop\fP, the search is terminated as soon
133 as an error is returned by one target, and the error is immediately
134 propagated to the client.
135 If the value is set to \fBreport\fP, the search is continuated to the end
136 but, in case at least one target returned an error code, the first
137 non-success error code is returned.
143 do not return search reference responses.
144 By default, they are returned unless request is LDAPv2.
145 If set before any target specification, it affects all targets, unless
146 overridden by any per-target directive.
149 .B noundeffilter <NO|yes>
152 return success instead of searching if a filter is undefined or contains
154 By default, the search is propagated after replacing undefined portions
156 .BR (!(objectClass=*)) ,
157 which corresponds to the empty result set.
158 If set before any target specification, it affects all targets, unless
159 overridden by any per-target directive.
162 .B protocol\-version {0,2,3}
163 This directive indicates what protocol version must be used to contact
165 If set to 0 (the default), the proxy uses the same protocol version
166 used by the client, otherwise the requested protocol is used.
167 The proxy returns \fIunwillingToPerform\fP if an operation that is
168 incompatible with the requested protocol is attempted.
169 If set before any target specification, it affects all targets, unless
170 overridden by any per-target directive.
173 .B pseudoroot\-bind\-defer {YES|no}
174 This directive, when set to
176 causes the authentication to the remote servers with the pseudo-root
177 identity (the identity defined in each
179 directive) to be deferred until actually needed by subsequent operations.
180 Otherwise, all binds as the rootdn are propagated to the targets.
183 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
184 Turns on quarantine of URIs that returned
185 .IR LDAP_UNAVAILABLE ,
186 so that an attempt to reconnect only occurs at given intervals instead
187 of any time a client requests an operation.
188 The pattern is: retry only after at least
190 seconds elapsed since last attempt, for exactly
192 times; then use the next pattern.
195 for the last pattern is "\fB+\fP", it retries forever; otherwise,
196 no more retries occur.
197 This directive must appear before any target specification;
198 it affects all targets with the same pattern.
201 .B rebind\-as\-user {NO|yes}
202 If this option is given, the client's bind credentials are remembered
203 for rebinds, when trying to re-establish a broken connection,
204 or when chasing a referral, if
210 .B session\-tracking\-request {NO|yes}
211 Adds session tracking control for all requests.
212 The client's IP and hostname, and the identity associated to each request,
213 if known, are sent to the remote server for informational purposes.
214 This directive is incompatible with setting \fIprotocol\-version\fP to 2.
215 If set before any target specification, it affects all targets, unless
216 overridden by any per-target directive.
219 .B single\-conn {NO|yes}
220 Discards current cached connection when the client rebinds.
223 .B use\-temporary\-conn {NO|yes}
226 create a temporary connection whenever competing with other threads
227 for a shared one; otherwise, wait until the shared connection is available.
229 .SH TARGET SPECIFICATION
230 Target specification starts with a "uri" directive:
233 .B uri <protocol>://[<host>]/<naming context> [...]
234 The <protocol> part can be anything
235 .BR ldap_initialize (3)
236 accepts ({ldap|ldaps|ldapi} and variants); the <host> may be
237 omitted, defaulting to whatever is set in
239 The <naming context> part is \fImandatory\fP for the first URI,
240 but it \fImust be omitted\fP for subsequent ones, if any.
241 The naming context part must be within the naming context defined for the backend,
246 suffix "\fBdc=foo,dc=com\fP"
247 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
252 The <naming context> part doesn't need to be unique across the targets;
253 it may also match one of the values of the "suffix" directive.
254 Multiple URIs may be defined in a single URI statement.
255 The additional URIs must be separate arguments and must not have any
256 <naming context> part. This causes the underlying library
257 to contact the first server of the list that responds.
258 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
259 of the same server, the directive
262 suffix "\fBdc=foo,dc=com\fP"
263 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP" "ldap://l2.foo.com/"
268 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
270 In that case, the URI list is internally rearranged, by moving unavailable
271 URIs to the end, so that further connection attempts occur with respect to
272 the last URI that succeeded.
276 .B acl\-authcDN "<administrative DN for access control purposes>"
277 DN which is used to query the target server for acl checking,
278 as in the LDAP backend; it is supposed to have read access
279 on the target server to attributes used on the proxy for acl checking.
280 There is no risk of giving away such values; they are only used to
282 .B The acl\-authcDN identity is by no means implicitly used by the proxy
283 .B when the client connects anonymously.
286 .B acl\-passwd <password>
287 Password used with the
293 .B bind\-timeout <microseconds>
294 This directive defines the timeout, in microseconds, used when polling
295 for response after an asynchronous bind connection. The initial call
296 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
297 if that results in a timeout exceeded, subsequent calls use the value
300 The default value is used also for subsequent calls if
303 If set before any target specification, it affects all targets, unless
304 overridden by any per-target directive.
307 .B chase\-referrals {YES|no}
308 enable/disable automatic referral chasing, which is delegated to the
309 underlying libldap, with rebinding eventually performed if the
310 \fBrebind\-as\-user\fP directive is used. The default is to chase referrals.
311 If set before any target specification, it affects all targets, unless
312 overridden by any per-target directive.
315 .B client\-pr {accept-unsolicited|DISABLE|<size>}
316 This feature allows to use RFC 2696 Paged Results control when performing
317 search operations with a specific target,
318 irrespective of the client's request.
319 When set to a numeric value, Paged Results control is always
320 used with \fIsize\fP as the page size.
321 When set to \fIaccept-unsolicited\fP, unsolicited Paged Results
322 control responses are accepted and honored
323 for compatibility with broken remote DSAs.
324 The client is not exposed to paged results handling
327 and the remote servers.
328 By default (disabled), Paged Results control is not used
329 and responses are not accepted.
330 If set before any target specification, it affects all targets, unless
331 overridden by any per-target directive.
334 .B default\-target [<target>]
335 The "default\-target" directive can also be used during target specification.
336 With no arguments it marks the current target as the default.
337 The optional number marks target <target> as the default one, starting
339 Target <target> must be defined.
342 .B idassert\-authzFrom <authz-regexp>
343 if defined, selects what
345 identities are authorized to exploit the identity assertion feature.
348 follows the rules defined for the
355 for details on the syntax of this field.
360 .B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
361 .B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
362 .B [authcId=<authentication ID>] [authzId=<authorization ID>]
363 .B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
364 .B [starttls=no|yes|critical]
367 .B [tls_cacert=<file>]
368 .B [tls_cacertdir=<path>]
369 .B [tls_reqcert=never|allow|try|demand]
370 .B [tls_ciphersuite=<ciphers>]
371 .B [tls_protocol_min=<version>]
372 .B [tls_crlcheck=none|peer|all]
374 Allows to define the parameters of the authentication method that is
375 internally used by the proxy to authorize connections that are
376 authenticated by other databases.
377 The identity defined by this directive, according to the properties
378 associated to the authentication method, is supposed to have auth access
379 on the target server to attributes used on the proxy for authentication
380 and authorization, and to be allowed to authorize the users.
381 This requires to have
383 privileges on a wide set of DNs, e.g.
384 .BR authzTo=dn.subtree:"" ,
385 and the remote server to have
393 for details on these statements and for remarks and drawbacks about
395 The supported bindmethods are
397 \fBnone|simple|sasl\fP
401 is the default, i.e. no \fIidentity assertion\fP is performed.
403 The authz parameter is used to instruct the SASL bind to exploit
405 SASL authorization, if available; since connections are cached,
406 this should only be used when authorizing with a fixed identity
407 (e.g. by means of the
412 Otherwise, the default
414 is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370)
415 is added to all operations.
417 The supported modes are:
419 \fB<mode> := {legacy|anonymous|none|self}\fP
425 is given, the proxy always authorizes that identity.
426 .B <authorization ID>
433 The former is supposed to be expanded by the remote server according
434 to the authz rules; see
437 In the latter case, whether or not the
439 prefix is present, the string must pass DN validation and normalization.
443 which implies that the proxy will either perform a simple bind as the
445 or a SASL bind as the
447 and assert the client's identity when it is not anonymous.
448 Direct binds are always proxied.
449 The other modes imply that the proxy will always either perform a simple bind
452 or a SASL bind as the
455 .BR idassert\-authzFrom
456 rules (see below), in which case the operation will fail;
457 eventually, it will assert some other identity according to
459 Other identity assertion modes are
463 which respectively mean that the
470 which means that no proxyAuthz control will be used, so the
474 identity will be asserted.
475 For all modes that require the use of the
477 control, on the remote server the proxy identity must have appropriate
479 permissions, or the asserted identities must have appropriate
481 permissions. Note, however, that the ID assertion feature is mostly
482 useful when the asserted identities do not exist on the remote server.
489 must be specified in addition to the
491 although it is not used within the authentication process.
495 \fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP
499 flag is used, identity assertion takes place even when the database
500 is authorizing for the identity of the client, i.e. after binding
501 with the provided identity, and thus authenticating it, the proxy
502 performs the identity assertion using the configured identity and
503 authentication method.
507 flag is used (the default), operations fail with
508 \fIinappropriateAuthentication\fP
509 for those identities whose assertion is not allowed by the
510 .B idassert\-authzFrom
514 flag is used, operations are performed anonymously for those identities
515 whose assertion is not allowed by the
516 .B idassert\-authzFrom
520 .B proxy\-authz\-non\-critical
521 flag is used (the default), the proxyAuthz control is not marked as critical,
522 in violation of RFC 4370. Use of
523 .B proxy\-authz\-critical
526 The TLS settings default to the same as the main slapd TLS settings,
529 which defaults to "demand".
531 The identity associated to this directive is also used for privileged
532 operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP
533 is not. See \fBacl\-bind\fP for details.
537 .B idle\-timeout <time>
538 This directive causes a cached connection to be dropped an recreated
539 after it has been idle for the specified time.
540 The value can be specified as
542 [<d>d][<h>h][<m>m][<s>[s]]
544 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
546 If set before any target specification, it affects all targets, unless
547 overridden by any per-target directive.
550 .B keepalive <idle>:<probes>:<interval>
553 parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP
554 used to check whether a socket is alive;
556 is the number of seconds a connection needs to remain idle before TCP
557 starts sending keepalive probes;
559 is the maximum number of keepalive probes TCP should send before dropping
562 is interval in seconds between individual keepalive probes.
563 Only some systems support the customization of these values;
566 parameter is ignored otherwise, and system-wide settings are used.
569 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
570 This maps object classes and attributes as in the LDAP backend.
575 .B network\-timeout <time>
576 Sets the network timeout value after which
577 .BR poll (2)/ select (2)
580 returns in case of no activity.
581 The value is in seconds, and it can be specified as for
583 If set before any target specification, it affects all targets, unless
584 overridden by any per-target directive.
587 .B nretries {forever|never|<nretries>}
588 This directive defines how many times a bind should be retried
589 in case of temporary failure in contacting a target. If defined
590 before any target specification, it applies to all targets (by default,
593 the global value can be overridden by redefinitions inside each target
598 The rewrite options are described in the "REWRITING" section.
601 .B subtree\-{exclude|include} "<rule>"
602 This directive allows to indicate what subtrees are actually served
604 The syntax of the supported rules is
606 \fB<rule>: [dn[.<style>]:]<pattern>\fP
608 \fB<style>: subtree|children|regex\fP
610 When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP
611 the \fB<pattern>\fP is a DN that must be within the naming context
612 served by the target.
613 When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a
616 If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP
617 is implicitly assumed for backward compatibility.
621 form if the \fIrequest DN\fP matches at least one rule,
622 the target is not considered while fulfilling the request;
623 otherwise, the target is considered based on the value of the \fIrequest DN\fP.
624 When the request is a search, also the \fIscope\fP is considered.
628 form if the \fIrequest DN\fP matches at least one rule,
629 the target is considered while fulfilling the request;
630 otherwise the target is ignored.
636 +---------+---------+-------------------+
637 | T | T | not candidate |
638 | F | T | continue checking |
639 +---------+---------+-------------------+
640 | T | F | candidate |
641 | F | F | not candidate |
642 +---------+---------+-------------------+
647 There may be multiple occurrences of the
651 directive for each of the targets, but they are mutually exclusive.
655 .B suffixmassage "<virtual naming context>" "<real naming context>"
656 All the directives starting with "rewrite" refer to the rewrite engine
657 that has been added to slapd.
658 The "suffixmassage" directive was introduced in the LDAP backend to
659 allow suffix massaging while proxying.
660 It has been obsoleted by the rewriting tools.
661 However, both for backward compatibility and for ease of configuration
662 when simple suffix massage is required, it has been preserved.
663 It wraps the basic rewriting instructions that perform suffix
664 massaging. See the "REWRITING" section for a detailed list
665 of the rewrite rules it implies.
668 .B t\-f\-support {NO|yes|discover}
669 enable if the remote server supports absolute filters
670 (see \fIRFC 4526\fP for details).
673 support is detected by reading the remote server's root DSE.
674 If set before any target specification, it affects all targets, unless
675 overridden by any per-target directive.
678 .B timeout [<op>=]<val> [...]
679 This directive allows to set per-operation timeouts.
682 \fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
684 The overall duration of the \fBsearch\fP operation is controlled either
685 by the \fBtimelimit\fP parameter or by server-side enforced
686 time limits (see \fBtimelimit\fP and \fBlimits\fP in
689 This \fBtimeout\fP parameter controls how long the target can be
690 irresponsive before the operation is aborted.
691 Timeout is meaningless for the remaining operations,
692 \fBunbind\fP and \fBabandon\fP, which do not imply any response,
693 while it is not yet implemented in currently supported \fBextended\fP
695 If no operation is specified, the timeout \fBval\fP affects all
696 supported operations.
697 If specified before any target definition, it affects all targets
698 unless overridden by per-target directives.
700 Note: if the timeout is exceeded, the operation is cancelled
701 (according to the \fBcancel\fP directive);
702 the protocol does not provide any means to rollback operations,
703 so the client will not be notified about the result of the operation,
704 which may eventually succeeded or not.
705 In case the timeout is exceeded during a bind operation, the connection
706 is destroyed, according to RFC4511.
709 .B tls {[try\-]start|[try\-]propagate}
710 execute the StartTLS extended operation when the connection is initialized;
711 only works if the URI directive protocol scheme is not \fBldaps://\fP.
712 \fBpropagate\fP issues the StartTLS operation only if the original
714 The \fBtry\-\fP prefix instructs the proxy to continue operations
715 if the StartTLS operation failed; its use is highly deprecated.
716 If set before any target specification, it affects all targets, unless
717 overridden by any per-target directive.
720 A powerful (and in some sense dangerous) rewrite engine has been added
721 to both the LDAP and Meta backends.
722 While the former can gain limited beneficial effects from rewriting
723 stuff, the latter can become an amazingly powerful tool.
725 Consider a couple of scenarios first.
727 1) Two directory servers share two levels of naming context;
728 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
729 Then, an unambiguous Meta database can be configured as:
734 suffix "\fBdc=foo,dc=com\fP"
735 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
736 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
740 Operations directed to a specific target can be easily resolved
741 because there are no ambiguities.
742 The only operation that may resolve to multiple targets is a search
743 with base "dc=foo,dc=com" and scope at least "one", which results in
744 spawning two searches to the targets.
746 2a) Two directory servers don't share any portion of naming context,
747 but they'd present as a single DIT
748 [Caveat: uniqueness of (massaged) entries among the two servers is
749 assumed; integrity checks risk to incur in excessive overhead and have
750 not been implemented].
751 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
752 and we'd like them to appear as branches of "dc=foo,dc=com", say
753 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
754 Then we need to configure our Meta backend as:
759 suffix "dc=foo,dc=com"
761 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
762 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
764 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
765 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
769 Again, operations can be resolved without ambiguity, although
770 some rewriting is required.
771 Notice that the virtual naming context of each target is a branch of
772 the database's naming context; it is rewritten back and forth when
773 operations are performed towards the target servers.
774 What "back and forth" means will be clarified later.
776 When a search with base "dc=foo,dc=com" is attempted, if the
777 scope is "base" it fails with "no such object"; in fact, the
778 common root of the two targets (prior to massaging) does not
780 If the scope is "one", both targets are contacted with the base
781 replaced by each target's base; the scope is derated to "base".
782 In general, a scope "one" search is honored, and the scope is derated,
783 only when the incoming base is at most one level lower of a target's
784 naming context (prior to massaging).
786 Finally, if the scope is "sub" the incoming base is replaced
787 by each target's unmassaged naming context, and the scope
790 2b) Consider the above reported scenario with the two servers
791 sharing the same naming context:
796 suffix "\fBdc=foo,dc=com\fP"
798 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
799 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
801 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
802 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
806 All the previous considerations hold, except that now there is
807 no way to unambiguously resolve a DN.
808 In this case, all the operations that require an unambiguous target
809 selection will fail unless the DN is already cached or a default
811 Practical configurations may result as a combination of all the
814 Note on ACLs: at present you may add whatever ACL rule you desire
815 to to the Meta (and LDAP) backends.
816 However, the meaning of an ACL on a proxy may require some
818 Two philosophies may be considered:
820 a) the remote server dictates the permissions; the proxy simply passes
821 back what it gets from the remote server.
823 b) the remote server unveils "everything"; the proxy is responsible
824 for protecting data from unauthorized access.
826 Of course the latter sounds unreasonable, but it is not.
827 It is possible to imagine scenarios in which a remote host discloses
828 data that can be considered "public" inside an intranet, and a proxy
829 that connects it to the internet may impose additional constraints.
830 To this purpose, the proxy should be able to comply with all the ACL
831 matching criteria that the server supports.
832 This has been achieved with regard to all the criteria supported by
833 slapd except a special subtle case (please file an ITS if you can
834 find other exceptions: <http://www.openldap.org/its/>).
839 access to dn="<dn>" attrs=<attr>
840 by dnattr=<dnattr> read
845 cannot be matched iff the attribute that is being requested, <attr>,
846 is NOT <dnattr>, and the attribute that determines membership,
847 <dnattr>, has not been requested (e.g. in a search)
849 In fact this ACL is resolved by slapd using the portion of entry it
850 retrieved from the remote server without requiring any further
851 intervention of the backend, so, if the <dnattr> attribute has not
852 been fetched, the match cannot be assessed because the attribute is
853 not present, not because no value matches the requirement!
855 Note on ACLs and attribute mapping: ACLs are applied to the mapped
856 attributes; for instance, if the attribute locally known as "foo" is
857 mapped to "bar" on a remote server, then local ACLs apply to attribute
858 "foo" and are totally unaware of its remote name.
859 The remote server will check permissions for "bar", and the local
860 server will possibly enforce additional restrictions to "foo".
862 .\" If this section is moved, also update the reference in
863 .\" libraries/librewrite/RATIONALE.
866 A string is rewritten according to a set of rules, called a `rewrite
868 The rules are based on POSIX (''extended'') regular expressions (regex)
869 with substring matching; basic variable substitution and map resolution
870 of substrings is allowed by specific mechanisms detailed in the following.
871 The behavior of pattern matching/substitution can be altered by a set
874 The underlying concept is to build a lightweight rewrite module
875 for the slapd server (initially dedicated to the LDAP backend).
877 An incoming string is matched against a set of rules.
878 Rules are made of a regex match pattern, a substitution pattern
879 and a set of actions, described by a set of flags.
880 In case of match a string rewriting is performed according to the
881 substitution pattern that allows to refer to substrings matched in the
883 The actions, if any, are finally performed.
884 The substitution pattern allows map resolution of substrings.
885 A map is a generic object that maps a substitution pattern to a value.
886 The flags are divided in "Pattern matching Flags" and "Action Flags";
887 the former alter the regex match pattern behavior while the latter
888 alter the action that is taken after substitution.
889 .SH "Pattern Matching Flags"
892 honors case in matching (default is case insensitive)
895 use POSIX ''basic'' regular expressions (default is ''extended'')
900 recursive passes for a specific rule; does not alter the max total count
901 of passes, so it can only enforce a stricter limit for a specific rule.
905 apply the rule once only (default is recursive)
908 stop applying rules in case of match; the current rule is still applied
909 recursively; combine with `:' to apply the current rule only once
913 stop current operation if the rule matches, and issue an `unwilling to
919 rules back and forth (watch for loops!).
920 Note that `G{1}' is implicit in every rule.
923 ignores errors in rule; this means, in case of error, e.g. issued by a
924 map, the error is treated as a missed match.
925 The `unwilling to perform' is not overridden.
931 as return code if the rule matches; the flag does not alter the recursive
932 behavior of the rule, so, to have it performed only once, it must be used
933 in combination with `:', e.g.
935 returns the value `16' after exactly one execution of the rule, if the
937 As a consequence, its behavior is equivalent to `@', with the return
940 or, in other words, `@' is equivalent to `U{0}'.
941 By convention, the freely available codes are above 16 included;
942 the others are reserved.
944 The ordering of the flags can be significant.
945 For instance: `IG{2}' means ignore errors and jump two lines ahead
946 both in case of match and in case of error, while `G{2}I' means ignore
947 errors, but jump two lines ahead only in case of match.
949 More flags (mainly Action Flags) will be added as needed.
950 .SH "Pattern matching:"
955 .SH "Substitution Pattern Syntax:"
956 Everything starting with `%' requires substitution;
958 the only obvious exception is `%%', which is left as is;
960 the basic substitution is `%d', where `d' is a digit;
961 0 means the whole string, while 1-9 is a submatch;
963 a `%' followed by a `{' invokes an advanced substitution.
967 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
970 where <name> must be a legal name for the map, i.e.
974 <name> ::= [a-z][a-z0-9]* (case insensitive)
975 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
979 and <substitution> must be a legal substitution
980 pattern, with no limits on the nesting level.
985 sub context invocation; <name> must be a legal, already defined
989 external command invocation; <name> must refer to a legal, already
990 defined command name (NOT IMPL.)
993 variable assignment; <name> defines a variable in the running
994 operation structure which can be dereferenced later; operator
996 assigns a variable in the rewrite context scope; operator
998 assigns a variable that scopes the entire session, e.g. its value
999 can be dereferenced later by other rewrite contexts
1002 variable dereferencing; <name> must refer to a variable that is
1003 defined and assigned for the running operation; operator
1005 dereferences a variable scoping the rewrite context; operator
1007 dereferences a variable scoping the whole session, e.g. the value
1008 is passed across rewrite contexts
1011 parameter dereferencing; <name> must refer to an existing parameter;
1012 the idea is to make some run-time parameters set by the system
1013 available to the rewrite engine, as the client host name, the bind DN
1014 if any, constant parameters initialized at config time, and so on;
1015 no parameter is currently set by either
1019 but constant parameters can be defined in the configuration file
1024 Substitution escaping has been delegated to the `%' symbol,
1025 which is used instead of `\e' in string substitution patterns
1026 because `\e' is already escaped by slapd's low level parsing routines;
1027 as a consequence, regex escaping requires two `\e' symbols,
1028 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
1030 .\" The symbol can be altered at will by redefining the related macro in
1031 .\" "rewrite-int.h".
1033 .SH "Rewrite context:"
1034 A rewrite context is a set of rules which are applied in sequence.
1035 The basic idea is to have an application initialize a rewrite
1036 engine (think of Apache's mod_rewrite ...) with a set of rewrite
1037 contexts; when string rewriting is required, one invokes the
1038 appropriate rewrite context with the input string and obtains the
1039 newly rewritten one if no errors occur.
1041 Each basic server operation is associated to a rewrite context;
1042 they are divided in two main groups: client \-> server and
1043 server \-> client rewriting.
1049 (default) if defined and no specific context
1054 searchFilterAttrDN search
1056 compareAttrDN compare AVA
1060 modifyAttrDN modify AVA
1062 newSuperiorDN modrdn
1064 exopPasswdDN password modify extended operation DN if proxy
1072 searchResult search (only if defined; no default;
1073 acts on DN and DN-syntax attributes
1075 searchAttrDN search AVA
1076 matchedDN all ops (only if applicable)
1080 .SH "Basic configuration syntax"
1082 .B rewriteEngine { on | off }
1083 If `on', the requested rewriting is performed; if `off', no
1084 rewriting takes place (an easy way to stop rewriting without
1085 altering too much the configuration file).
1087 .B rewriteContext <context name> "[ alias <aliased context name> ]"
1088 <Context name> is the name that identifies the context, i.e. the name
1089 used by the application to refer to the set of rules it contains.
1090 It is used also to reference sub contexts in string rewriting.
1091 A context may alias another one.
1092 In this case the alias context contains no rule, and any reference to
1093 it will result in accessing the aliased one.
1095 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
1096 Determines how a string can be rewritten if a pattern is matched.
1097 Examples are reported below.
1098 .SH "Additional configuration syntax:"
1100 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
1101 Allows to define a map that transforms substring rewriting into
1103 The map is referenced inside the substitution pattern of a rule.
1105 .B rewriteParam <param name> <param value>
1106 Sets a value with global scope, that can be dereferenced by the
1107 command `%{$paramName}'.
1109 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
1110 Sets the maximum number of total rewriting passes that can be
1111 performed in a single rewrite operation (to avoid loops).
1112 A safe default is set to 100; note that reaching this limit is still
1113 treated as a success; recursive invocation of rules is simply
1115 The count applies to the rewriting operation as a whole, not
1116 to any single rule; an optional per-rule limit can be set.
1117 This limit is overridden by setting specific per-rule limits
1118 with the `M{n}' flag.
1119 .SH "Configuration examples:"
1121 # set to `off' to disable rewriting
1124 # the rules the "suffixmassage" directive implies
1126 # all dataflow from client to server referring to DNs
1127 rewriteContext default
1128 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
1130 rewriteContext searchFilter
1131 # all dataflow from server to client
1132 rewriteContext searchResult
1133 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
1134 rewriteContext searchAttrDN alias searchResult
1135 rewriteContext matchedDN alias searchResult
1137 # Everything defined here goes into the `default' context.
1138 # This rule changes the naming context of anything sent
1139 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
1141 rewriteRule "(.*)dc=home,[ ]?dc=net"
1142 "%1dc=OpenLDAP, dc=org" ":"
1144 # since a pretty/normalized DN does not include spaces
1145 # after rdn separators, e.g. `,', this rule suffices:
1147 rewriteRule "(.*)dc=home,dc=net"
1148 "%1dc=OpenLDAP,dc=org" ":"
1150 # Start a new context (ends input of the previous one).
1151 # This rule adds blanks between DN parts if not present.
1152 rewriteContext addBlanks
1153 rewriteRule "(.*),([^ ].*)" "%1, %2"
1155 # This one eats blanks
1156 rewriteContext eatBlanks
1157 rewriteRule "(.*),[ ](.*)" "%1,%2"
1159 # Here control goes back to the default rewrite
1160 # context; rules are appended to the existing ones.
1161 # anything that gets here is piped into rule `addBlanks'
1162 rewriteContext default
1163 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
1165 .\" # Anything with `uid=username' is looked up in
1166 .\" # /etc/passwd for gecos (I know it's nearly useless,
1167 .\" # but it is there just as a guideline to implementing
1169 .\" # Note the `I' flag that leaves `uid=username' in place
1170 .\" # if `username' does not have a valid account, and the
1171 .\" # `:' that forces the rule to be processed exactly once.
1172 .\" rewriteContext uid2Gecos
1173 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
1174 .\" "%1cn=%2{xpasswd},%3" "I:"
1176 .\" # Finally, in a bind, if one uses a `uid=username' DN,
1177 .\" # it is rewritten in `cn=name surname' if possible.
1178 .\" rewriteContext bindDN
1179 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
1181 # Rewrite the search base according to `default' rules.
1182 rewriteContext searchBase alias default
1184 # Search results with OpenLDAP DN are rewritten back with
1185 # `dc=home,dc=net' naming context, with spaces eaten.
1186 rewriteContext searchResult
1187 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
1188 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
1190 # Bind with email instead of full DN: we first need
1191 # an ldap map that turns attributes into a DN (the
1192 # argument used when invoking the map is appended to
1193 # the URI and acts as the filter portion)
1194 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
1196 # Then we need to detect DN made up of a single email,
1197 # e.g. `mail=someone@example.com'; note that the rule
1198 # in case of match stops rewriting; in case of error,
1199 # it is ignored. In case we are mapping virtual
1200 # to real naming contexts, we also need to rewrite
1201 # regular DNs, because the definition of a bindDn
1202 # rewrite context overrides the default definition.
1203 rewriteContext bindDN
1204 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
1206 # This is a rather sophisticated example. It massages a
1207 # search filter in case who performs the search has
1208 # administrative privileges. First we need to keep
1209 # track of the bind DN of the incoming request, which is
1210 # stored in a variable called `binddn' with session scope,
1211 # and left in place to allow regular binding:
1212 rewriteContext bindDN
1213 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
1215 # A search filter containing `uid=' is rewritten only
1216 # if an appropriate DN is bound.
1217 # To do this, in the first rule the bound DN is
1218 # dereferenced, while the filter is decomposed in a
1219 # prefix, in the value of the `uid=<arg>' AVA, and
1220 # in a suffix. A tag `<>' is appended to the DN.
1221 # If the DN refers to an entry in the `ou=admin' subtree,
1222 # the filter is rewritten OR-ing the `uid=<arg>' with
1223 # `cn=<arg>'; otherwise it is left as is. This could be
1224 # useful, for instance, to allow apache's auth_ldap-1.4
1225 # module to authenticate users with both `uid' and
1226 # `cn', but only if the request comes from a possible
1227 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
1228 rewriteContext searchFilter
1229 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
1230 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
1232 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
1233 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
1234 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
1236 # This example shows how to strip unwanted DN-valued
1237 # attribute values from a search result; the first rule
1238 # matches DN values below "ou=People,dc=example,dc=com";
1239 # in case of match the rewriting exits successfully.
1240 # The second rule matches everything else and causes
1241 # the value to be rejected.
1242 rewriteContext searchResult
1243 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
1244 rewriteRule ".*" "" "#"
1246 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
1247 In case the rewritten DN is an LDAP URI, the operation is initiated
1248 towards the host[:port] indicated in the uri, if it does not refer
1249 to the local server.
1253 rewriteRule '^cn=root,.*' '%0' 'G{3}'
1254 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
1255 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
1256 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
1259 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
1263 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
1266 with the advantage of saving one rewrite pass ...)
1271 backend does not honor all ACL semantics as described in
1272 .BR slapd.access (5).
1273 In general, access checking is delegated to the remote server(s).
1278 pseudo-attribute and to the other attribute values of the entries
1281 operation is honored, which is performed by the frontend.
1283 .SH PROXY CACHE OVERLAY
1284 The proxy cache overlay
1285 allows caching of LDAP search requests (queries) in a local database.
1287 .BR slapo\-pcache (5)
1290 .SH DEPRECATED STATEMENTS
1291 The following statements have been deprecated and should no longer be used.
1294 .B pseudorootdn "<substitute DN in case of rootdn bind>"
1300 .B pseudorootpw "<substitute password in case of rootdn bind>"
1310 default slapd configuration file
1313 .BR slapd\-ldap (5),
1314 .BR slapo\-pcache (5),
1319 Pierangelo Masarati, based on back-ldap by Howard Chu