1 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2022 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, the \fBslapd\fP(8)
53 \fBthreads\fP parameter may need some tuning. In those cases, unless the
54 multiple target feature is required, one may consider using \fBslapd\-relay\fP(5) instead,
55 which performs the relayed operation internally and thus reuses
59 There are examples in various places in this document, as well as in the
60 slapd/back-meta/data/ directory in the OpenLDAP source tree.
64 options apply to the META backend database.
65 That is, they must follow a "database meta" line and come before any
66 subsequent "backend" or "database" lines.
67 Other database options are described in the
71 Note: In early versions of back-ldap and back-meta it was recommended to always set
84 This was required because operational attributes related to entry creation
85 and modification should not be proxied, as they could be mistakenly written
86 to the target server(s), generating an error.
87 The current implementation automatically sets lastmod to \fBoff\fP,
88 so its use is redundant and should be omitted.
90 .SH SPECIAL CONFIGURATION DIRECTIVES
91 Target configuration starts with the "uri" directive.
92 All the configuration directives that are not specific to targets
93 should be defined first for clarity, including those that are common
98 .B conn\-pool\-max <int>
99 This directive defines the maximum size of the privileged connections pool.
103 This directive causes a cached connection to be dropped an recreated
104 after a given ttl, regardless of being idle or not.
107 .B default\-target none
108 This directive forces the backend to reject all those operations
109 that must resolve to a single target in case none or multiple
110 targets are selected.
111 They include: add, delete, modify, modrdn; compare is not included, as
112 well as bind since, as they don't alter entries, in case of multiple
113 matches an attempt is made to perform the operation on any candidate
114 target, with the constraint that at most one must succeed.
115 This directive can also be used when processing targets to mark a
116 specific target as default.
119 .B dncache\-ttl {DISABLED|forever|<ttl>}
120 This directive sets the time-to-live of the DN cache.
121 This caches the target that holds a given DN to speed up target
122 selection in case multiple targets would result from an uncached
123 search; forever means cache never expires; disabled means no DN
124 caching; otherwise a valid ( > 0 ) ttl is required, in the format
130 .B onerr {CONTINUE|report|stop}
131 This directive allows one to select the behavior in case an error is returned
132 by one target during a search.
133 The default, \fBcontinue\fP, consists in continuing the operation,
134 trying to return as much data as possible.
135 If the value is set to \fBstop\fP, the search is terminated as soon
136 as an error is returned by one target, and the error is immediately
137 propagated to the client.
138 If the value is set to \fBreport\fP, the search is continued to the end
139 but, in case at least one target returned an error code, the first
140 non-success error code is returned.
146 do not return search reference responses.
147 By default, they are returned unless request is LDAPv2.
148 If set before any target specification, it affects all targets, unless
149 overridden by any per-target directive.
152 .B noundeffilter <NO|yes>
155 return success instead of searching if a filter is undefined or contains
157 By default, the search is propagated after replacing undefined portions
159 .BR (!(objectClass=*)) ,
160 which corresponds to the empty result set.
161 If set before any target specification, it affects all targets, unless
162 overridden by any per-target directive.
165 .B protocol\-version {0,2,3}
166 This directive indicates what protocol version must be used to contact
168 If set to 0 (the default), the proxy uses the same protocol version
169 used by the client, otherwise the requested protocol is used.
170 The proxy returns \fIunwillingToPerform\fP if an operation that is
171 incompatible with the requested protocol is attempted.
172 If set before any target specification, it affects all targets, unless
173 overridden by any per-target directive.
176 .B pseudoroot\-bind\-defer {YES|no}
177 This directive, when set to
179 causes the authentication to the remote servers with the pseudo-root
180 identity (the identity defined in each
182 directive) to be deferred until actually needed by subsequent operations.
183 Otherwise, all binds as the rootdn are propagated to the targets.
186 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
187 Turns on quarantine of URIs that returned
188 .IR LDAP_UNAVAILABLE ,
189 so that an attempt to reconnect only occurs at given intervals instead
190 of any time a client requests an operation.
191 The pattern is: retry only after at least
193 seconds elapsed since last attempt, for exactly
195 times; then use the next pattern.
198 for the last pattern is "\fB+\fP", it retries forever; otherwise,
199 no more retries occur.
200 This directive must appear before any target specification;
201 it affects all targets with the same pattern.
204 .B rebind\-as\-user {NO|yes}
205 If this option is given, the client's bind credentials are remembered
206 for rebinds, when trying to re-establish a broken connection,
207 or when chasing a referral, if
213 .B session\-tracking\-request {NO|yes}
214 Adds session tracking control for all requests.
215 The client's IP and hostname, and the identity associated to each request,
216 if known, are sent to the remote server for informational purposes.
217 This directive is incompatible with setting \fIprotocol\-version\fP to 2.
218 If set before any target specification, it affects all targets, unless
219 overridden by any per-target directive.
222 .B single\-conn {NO|yes}
223 Discards current cached connection when the client rebinds.
226 .B use\-temporary\-conn {NO|yes}
229 create a temporary connection whenever competing with other threads
230 for a shared one; otherwise, wait until the shared connection is available.
232 .SH TARGET SPECIFICATION
233 Target specification starts with a "uri" directive:
236 .B uri <protocol>://[<host>]/<naming context> [...]
237 The <protocol> part can be anything
238 .BR ldap_initialize (3)
239 accepts ({ldap|ldaps|ldapi} and variants); the <host> may be
240 omitted, defaulting to whatever is set in
242 The <naming context> part is \fImandatory\fP for the first URI,
243 but it \fImust be omitted\fP for subsequent ones, if any.
244 The naming context part must be within the naming context defined for the backend,
249 suffix "\fBdc=foo,dc=com\fP"
250 uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP"
255 The <naming context> part doesn't need to be unique across the targets;
256 it may also match one of the values of the "suffix" directive.
257 Multiple URIs may be defined in a single URI statement.
258 The additional URIs must be separate arguments and must not have any
259 <naming context> part. This causes the underlying library
260 to contact the first server of the list that responds.
261 For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
262 of the same server, the directive
265 suffix "\fBdc=foo,dc=com\fP"
266 uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP" "ldap://l2.foo.com/"
271 causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
273 In that case, the URI list is internally rearranged, by moving unavailable
274 URIs to the end, so that further connection attempts occur with respect to
275 the last URI that succeeded.
279 .B acl\-authcDN "<administrative DN for access control purposes>"
280 DN which is used to query the target server for acl checking,
281 as in the LDAP backend; it is supposed to have read access
282 on the target server to attributes used on the proxy for acl checking.
283 There is no risk of giving away such values; they are only used to
285 .B The acl\-authcDN identity is by no means implicitly used by the proxy
286 .B when the client connects anonymously.
289 .B acl\-passwd <password>
290 Password used with the
295 .B bind\-timeout <microseconds>
296 This directive defines the timeout, in microseconds, used when polling
297 for response after an asynchronous bind connection. The initial call
298 to ldap_result(3) is performed with a trade-off timeout of 100000 us;
299 if that results in a timeout exceeded, subsequent calls use the value
302 The default value is used also for subsequent calls if
305 If set before any target specification, it affects all targets, unless
306 overridden by any per-target directive.
309 .B chase\-referrals {YES|no}
310 enable/disable automatic referral chasing, which is delegated to the
311 underlying libldap, with rebinding eventually performed if the
312 \fBrebind\-as\-user\fP directive is used. The default is to chase referrals.
313 If set before any target specification, it affects all targets, unless
314 overridden by any per-target directive.
317 .B client\-pr {accept-unsolicited|DISABLE|<size>}
318 This feature allows one to use RFC 2696 Paged Results control when performing
319 search operations with a specific target,
320 irrespective of the client's request.
321 When set to a numeric value, Paged Results control is always
322 used with \fIsize\fP as the page size.
323 When set to \fIaccept\-unsolicited\fP, unsolicited Paged Results
324 control responses are accepted and honored
325 for compatibility with broken remote DSAs.
326 The client is not exposed to paged results handling
329 and the remote servers.
330 By default (disabled), Paged Results control is not used
331 and responses are not accepted.
332 If set before any target specification, it affects all targets, unless
333 overridden by any per-target directive.
336 .B default\-target [<target>]
337 The "default\-target" directive can also be used during target specification.
338 With no arguments it marks the current target as the default.
339 The optional number marks target <target> as the default one, starting
341 Target <target> must be defined.
345 This directive allows specifying a
347 pattern to indicate what search filter terms are actually served by a target.
349 In a search request, if the search filter matches the \fIpattern\fP
350 the target is considered while fulfilling the request; otherwise
351 the target is ignored. There may be multiple occurrences of
354 directive for each target.
357 .B idassert\-authzFrom <authz-regexp>
358 if defined, selects what
360 identities are authorized to exploit the identity assertion feature.
363 follows the rules defined for the
370 for details on the syntax of this field.
375 .B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
376 .B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
377 .B [authcId=<authentication ID>] [authzId=<authorization ID>]
378 .B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
379 .B [starttls=no|yes|critical]
382 .B [tls_cacert=<file>]
383 .B [tls_cacertdir=<path>]
384 .B [tls_reqcert=never|allow|try|demand]
385 .B [tls_reqsan=never|allow|try|demand]
386 .B [tls_cipher_suite=<ciphers>]
387 .B [tls_ecname=<ciphers>]
388 .B [tls_protocol_min=<major>[.<minor>]]
389 .B [tls_crlcheck=none|peer|all]
391 Allows one to define the parameters of the authentication method that is
392 internally used by the proxy to authorize connections that are
393 authenticated by other databases.
394 The identity defined by this directive, according to the properties
395 associated to the authentication method, is supposed to have auth access
396 on the target server to attributes used on the proxy for authentication
397 and authorization, and to be allowed to authorize the users.
398 This requires to have
400 privileges on a wide set of DNs, e.g.
401 .BR authzTo=dn.subtree:"" ,
402 and the remote server to have
410 for details on these statements and for remarks and drawbacks about
412 The supported bindmethods are
414 \fBnone|simple|sasl\fP
418 is the default, i.e. no \fIidentity assertion\fP is performed.
420 The authz parameter is used to instruct the SASL bind to exploit
422 SASL authorization, if available; since connections are cached,
423 this should only be used when authorizing with a fixed identity
424 (e.g. by means of the
429 Otherwise, the default
431 is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370)
432 is added to all operations.
434 The supported modes are:
436 \fB<mode> := {legacy|anonymous|none|self}\fP
442 is given, the proxy always authorizes that identity.
443 .B <authorization ID>
450 The former is supposed to be expanded by the remote server according
451 to the authz rules; see
454 In the latter case, whether or not the
456 prefix is present, the string must pass DN validation and normalization.
460 which implies that the proxy will either perform a simple bind as the
462 or a SASL bind as the
464 and assert the client's identity when it is not anonymous.
465 Direct binds are always proxied.
466 The other modes imply that the proxy will always either perform a simple bind
469 or a SASL bind as the
472 .BR idassert\-authzFrom
473 rules (see below), in which case the operation will fail;
474 eventually, it will assert some other identity according to
476 Other identity assertion modes are
480 which respectively mean that the
487 which means that no proxyAuthz control will be used, so the
491 identity will be asserted.
492 For all modes that require the use of the
494 control, on the remote server the proxy identity must have appropriate
496 permissions, or the asserted identities must have appropriate
498 permissions. Note, however, that the ID assertion feature is mostly
499 useful when the asserted identities do not exist on the remote server.
506 must be specified in addition to the
508 although it is not used within the authentication process.
512 \fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP
516 flag is used, identity assertion takes place even when the database
517 is authorizing for the identity of the client, i.e. after binding
518 with the provided identity, and thus authenticating it, the proxy
519 performs the identity assertion using the configured identity and
520 authentication method.
524 flag is used (the default), operations fail with
525 \fIinappropriateAuthentication\fP
526 for those identities whose assertion is not allowed by the
527 .B idassert\-authzFrom
531 flag is used, operations are performed anonymously for those identities
532 whose assertion is not allowed by the
533 .B idassert\-authzFrom
537 .B proxy\-authz\-non\-critical
538 flag is used (the default), the proxyAuthz control is not marked as critical,
539 in violation of RFC 4370. Use of
540 .B proxy\-authz\-critical
543 The TLS settings default to the same as the main slapd TLS settings,
546 which defaults to "demand", and
548 which defaults to "allow"..
550 The identity associated to this directive is also used for privileged
551 operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP
552 is not. See \fBacl\-bind\fP for details.
556 .B idle\-timeout <time>
557 This directive causes a cached connection to be dropped an recreated
558 after it has been idle for the specified time.
559 The value can be specified as
561 [<d>d][<h>h][<m>m][<s>[s]]
563 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
565 If set before any target specification, it affects all targets, unless
566 overridden by any per-target directive.
569 .B keepalive <idle>:<probes>:<interval>
572 parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP
573 used to check whether a socket is alive;
575 is the number of seconds a connection needs to remain idle before TCP
576 starts sending keepalive probes;
578 is the maximum number of keepalive probes TCP should send before dropping
581 is interval in seconds between individual keepalive probes.
582 Only some systems support the customization of these values;
585 parameter is ignored otherwise, and system-wide settings are used.
588 .B tcp\-user\-timeout <milliseconds>
589 If non-zero, corresponds to the
591 set on the target connections, overriding the operating system setting.
592 Only some systems support the customization of this parameter, it is
593 ignored otherwise and system-wide settings are used.
596 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
597 This maps object classes and attributes as in the LDAP backend.
602 .B network\-timeout <time>
603 Sets the network timeout value after which
604 .BR poll (2)/ select (2)
607 returns in case of no activity.
608 The value is in seconds, and it can be specified as for
610 If set before any target specification, it affects all targets, unless
611 overridden by any per-target directive.
614 .B nretries {forever|never|<nretries>}
615 This directive defines how many times a bind should be retried
616 in case of temporary failure in contacting a target. If defined
617 before any target specification, it applies to all targets (by default,
620 the global value can be overridden by redefinitions inside each target
625 The rewrite options are described in the "REWRITING" section.
628 .B subtree\-{exclude|include} "<rule>"
629 This directive allows one to indicate what subtrees are actually served
631 The syntax of the supported rules is
633 \fB<rule>: [dn[.<style>]:]<pattern>\fP
635 \fB<style>: subtree|children|regex\fP
637 When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP
638 the \fB<pattern>\fP is a DN that must be within the naming context
639 served by the target.
640 When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a
643 If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP
644 is implicitly assumed for backward compatibility.
648 form if the \fIrequest DN\fP matches at least one rule,
649 the target is not considered while fulfilling the request;
650 otherwise, the target is considered based on the value of the \fIrequest DN\fP.
651 When the request is a search, also the \fIscope\fP is considered.
655 form if the \fIrequest DN\fP matches at least one rule,
656 the target is considered while fulfilling the request;
657 otherwise the target is ignored.
663 +---------+---------+-------------------+
664 | T | T | not candidate |
665 | F | T | continue checking |
666 +---------+---------+-------------------+
667 | T | F | candidate |
668 | F | F | not candidate |
669 +---------+---------+-------------------+
674 There may be multiple occurrences of the
678 directive for each of the targets, but they are mutually exclusive.
682 .B suffixmassage "<virtual naming context>" "<real naming context>"
683 All the directives starting with "rewrite" refer to the rewrite engine
684 that has been added to slapd.
685 The "suffixmassage" directive was introduced in the LDAP backend to
686 allow suffix massaging while proxying.
687 It has been obsoleted by the rewriting tools.
688 However, both for backward compatibility and for ease of configuration
689 when simple suffix massage is required, it has been preserved.
690 It wraps the basic rewriting instructions that perform suffix
691 massaging. See the "REWRITING" section for a detailed list
692 of the rewrite rules it implies.
695 .B t\-f\-support {NO|yes|discover}
696 enable if the remote server supports absolute filters
697 (see \fIRFC 4526\fP for details).
700 support is detected by reading the remote server's root DSE.
701 If set before any target specification, it affects all targets, unless
702 overridden by any per-target directive.
705 .B timeout [<op>=]<val> [...]
706 This directive allows one to set per-operation timeouts.
709 \fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
711 The overall duration of the \fBsearch\fP operation is controlled either
712 by the \fBtimelimit\fP parameter or by server-side enforced
713 time limits (see \fBtimelimit\fP and \fBlimits\fP in
716 This \fBtimeout\fP parameter controls how long the target can be
717 irresponsive before the operation is aborted.
718 Timeout is meaningless for the remaining operations,
719 \fBunbind\fP and \fBabandon\fP, which do not imply any response,
720 while it is not yet implemented in currently supported \fBextended\fP
722 If no operation is specified, the timeout \fBval\fP affects all
723 supported operations.
724 If specified before any target definition, it affects all targets
725 unless overridden by per-target directives.
727 Note: if the timeout is exceeded, the operation is cancelled
728 (according to the \fBcancel\fP directive);
729 the protocol does not provide any means to rollback operations,
730 so the client will not be notified about the result of the operation,
731 which may eventually succeeded or not.
732 In case the timeout is exceeded during a bind operation, the connection
733 is destroyed, according to RFC4511.
736 .B tls {none|[try\-]start|[try\-]propagate|ldaps}
740 .B [tls_cacert=<file>]
741 .B [tls_cacertdir=<path>]
742 .B [tls_reqcert=never|allow|try|demand]
743 .B [tls_reqsan=never|allow|try|demand]
744 .B [tls_cipher_suite=<ciphers>]
745 .B [tls_ecname=<names>]
746 .B [tls_crlcheck=none|peer|all]
748 Specify TLS settings regular connections.
750 If the first parameter is not "none" then this configures the TLS
751 settings to be used for regular connections.
752 The StartTLS extended operation will be used when establishing the
753 connection unless the URI directive protocol scheme is \fBldaps://\fP.
754 In that case this keyword may only be set to "ldaps" and the StartTLS
755 operation will not be used.
757 With \fBpropagate\fP, the proxy issues the StartTLS operation only if
758 the original connection has a TLS layer set up.
759 The \fBtry\-\fP prefix instructs the proxy to continue operations
760 if the StartTLS operation failed; its use is \fBnot\fP recommended.
762 The TLS settings default to the same as the main slapd TLS settings,
765 which defaults to "demand",
767 which defaults to "allow", and
769 which is overshadowed by the first keyword and thus ignored.
771 If set before any target specification, it affects all targets, unless
772 overridden by any per-target directive.
776 A powerful (and in some sense dangerous) rewrite engine has been added
777 to both the LDAP and Meta backends.
778 While the former can gain limited beneficial effects from rewriting
779 stuff, the latter can become an amazingly powerful tool.
781 Consider a couple of scenarios first.
783 1) Two directory servers share two levels of naming context;
784 say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
785 Then, an unambiguous Meta database can be configured as:
790 suffix "\fBdc=foo,dc=com\fP"
791 uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP"
792 uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP"
796 Operations directed to a specific target can be easily resolved
797 because there are no ambiguities.
798 The only operation that may resolve to multiple targets is a search
799 with base "dc=foo,dc=com" and scope at least "one", which results in
800 spawning two searches to the targets.
802 2a) Two directory servers don't share any portion of naming context,
803 but they'd present as a single DIT
804 [Caveat: uniqueness of (massaged) entries among the two servers is
805 assumed; integrity checks risk to incur in excessive overhead and have
806 not been implemented].
807 Say we have "dc=bar,dc=org" and "o=Foo,c=US",
808 and we'd like them to appear as branches of "dc=foo,dc=com", say
809 "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".
810 Then we need to configure our Meta backend as:
815 suffix "dc=foo,dc=com"
817 uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP"
818 suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org"
820 uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP"
821 suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US"
825 Again, operations can be resolved without ambiguity, although
826 some rewriting is required.
827 Notice that the virtual naming context of each target is a branch of
828 the database's naming context; it is rewritten back and forth when
829 operations are performed towards the target servers.
830 What "back and forth" means will be clarified later.
832 When a search with base "dc=foo,dc=com" is attempted, if the
833 scope is "base" it fails with "no such object"; in fact, the
834 common root of the two targets (prior to massaging) does not
836 If the scope is "one", both targets are contacted with the base
837 replaced by each target's base; the scope is derated to "base".
838 In general, a scope "one" search is honored, and the scope is derated,
839 only when the incoming base is at most one level lower of a target's
840 naming context (prior to massaging).
842 Finally, if the scope is "sub" the incoming base is replaced
843 by each target's unmassaged naming context, and the scope
846 2b) Consider the above reported scenario with the two servers
847 sharing the same naming context:
852 suffix "\fBdc=foo,dc=com\fP"
854 uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP"
855 suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org"
857 uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP"
858 suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US"
862 All the previous considerations hold, except that now there is
863 no way to unambiguously resolve a DN.
864 In this case, all the operations that require an unambiguous target
865 selection will fail unless the DN is already cached or a default
867 Practical configurations may result as a combination of all the
870 Note on ACLs: at present you may add whatever ACL rule you desire
871 to the Meta (and LDAP) backends.
872 However, the meaning of an ACL on a proxy may require some
874 Two philosophies may be considered:
876 a) the remote server dictates the permissions; the proxy simply passes
877 back what it gets from the remote server.
879 b) the remote server unveils "everything"; the proxy is responsible
880 for protecting data from unauthorized access.
882 Of course the latter sounds unreasonable, but it is not.
883 It is possible to imagine scenarios in which a remote host discloses
884 data that can be considered "public" inside an intranet, and a proxy
885 that connects it to the internet may impose additional constraints.
886 To this purpose, the proxy should be able to comply with all the ACL
887 matching criteria that the server supports.
888 This has been achieved with regard to all the criteria supported by
889 slapd except a special subtle case (please file an ITS if you can
890 find other exceptions: <http://www.openldap.org/its/>).
895 access to dn="<dn>" attrs=<attr>
896 by dnattr=<dnattr> read
901 cannot be matched iff the attribute that is being requested, <attr>,
902 is NOT <dnattr>, and the attribute that determines membership,
903 <dnattr>, has not been requested (e.g. in a search)
905 In fact this ACL is resolved by slapd using the portion of entry it
906 retrieved from the remote server without requiring any further
907 intervention of the backend, so, if the <dnattr> attribute has not
908 been fetched, the match cannot be assessed because the attribute is
909 not present, not because no value matches the requirement!
911 Note on ACLs and attribute mapping: ACLs are applied to the mapped
912 attributes; for instance, if the attribute locally known as "foo" is
913 mapped to "bar" on a remote server, then local ACLs apply to attribute
914 "foo" and are totally unaware of its remote name.
915 The remote server will check permissions for "bar", and the local
916 server will possibly enforce additional restrictions to "foo".
918 .\" If this section is moved, also update the reference in
919 .\" libraries/librewrite/RATIONALE.
922 A string is rewritten according to a set of rules, called a `rewrite
924 The rules are based on POSIX (''extended'') regular expressions (regex)
925 with substring matching; basic variable substitution and map resolution
926 of substrings is allowed by specific mechanisms detailed in the following.
927 The behavior of pattern matching/substitution can be altered by a set
930 The underlying concept is to build a lightweight rewrite module
931 for the slapd server (initially dedicated to the LDAP backend).
933 An incoming string is matched against a set of rules.
934 Rules are made of a regex match pattern, a substitution pattern
935 and a set of actions, described by a set of flags.
936 In case of match a string rewriting is performed according to the
937 substitution pattern that allows one to refer to substrings matched in the
939 The actions, if any, are finally performed.
940 The substitution pattern allows map resolution of substrings.
941 A map is a generic object that maps a substitution pattern to a value.
942 The flags are divided in "Pattern matching Flags" and "Action Flags";
943 the former alter the regex match pattern behavior while the latter
944 alter the action that is taken after substitution.
945 .SH "Pattern Matching Flags"
948 honors case in matching (default is case insensitive)
951 use POSIX ''basic'' regular expressions (default is ''extended'')
956 recursive passes for a specific rule; does not alter the max total count
957 of passes, so it can only enforce a stricter limit for a specific rule.
961 apply the rule once only (default is recursive)
964 stop applying rules in case of match; the current rule is still applied
965 recursively; combine with `:' to apply the current rule only once
969 stop current operation if the rule matches, and issue an `unwilling to
975 rules back and forth (watch for loops!).
976 Note that `G{1}' is implicit in every rule.
979 ignores errors in rule; this means, in case of error, e.g. issued by a
980 map, the error is treated as a missed match.
981 The `unwilling to perform' is not overridden.
987 as return code if the rule matches; the flag does not alter the recursive
988 behavior of the rule, so, to have it performed only once, it must be used
989 in combination with `:', e.g.
991 returns the value `16' after exactly one execution of the rule, if the
993 As a consequence, its behavior is equivalent to `@', with the return
996 or, in other words, `@' is equivalent to `U{0}'.
997 By convention, the freely available codes are above 16 included;
998 the others are reserved.
1000 The ordering of the flags can be significant.
1001 For instance: `IG{2}' means ignore errors and jump two lines ahead
1002 both in case of match and in case of error, while `G{2}I' means ignore
1003 errors, but jump two lines ahead only in case of match.
1005 More flags (mainly Action Flags) will be added as needed.
1006 .SH "Pattern matching:"
1011 .SH "Substitution Pattern Syntax:"
1012 Everything starting with `%' requires substitution;
1014 the only obvious exception is `%%', which is left as is;
1016 the basic substitution is `%d', where `d' is a digit;
1017 0 means the whole string, while 1-9 is a submatch;
1019 a `%' followed by a `{' invokes an advanced substitution.
1023 `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
1026 where <name> must be a legal name for the map, i.e.
1030 <name> ::= [a-z][a-z0-9]* (case insensitive)
1031 <op> ::= `>' `|' `&' `&&' `*' `**' `$'
1035 and <substitution> must be a legal substitution
1036 pattern, with no limits on the nesting level.
1041 sub context invocation; <name> must be a legal, already defined
1042 rewrite context name
1045 external command invocation; <name> must refer to a legal, already
1046 defined command name (NOT IMPL.)
1049 variable assignment; <name> defines a variable in the running
1050 operation structure which can be dereferenced later; operator
1052 assigns a variable in the rewrite context scope; operator
1054 assigns a variable that scopes the entire session, e.g. its value
1055 can be dereferenced later by other rewrite contexts
1058 variable dereferencing; <name> must refer to a variable that is
1059 defined and assigned for the running operation; operator
1061 dereferences a variable scoping the rewrite context; operator
1063 dereferences a variable scoping the whole session, e.g. the value
1064 is passed across rewrite contexts
1067 parameter dereferencing; <name> must refer to an existing parameter;
1068 the idea is to make some run-time parameters set by the system
1069 available to the rewrite engine, as the client host name, the bind DN
1070 if any, constant parameters initialized at config time, and so on;
1071 no parameter is currently set by either
1075 but constant parameters can be defined in the configuration file
1080 Substitution escaping has been delegated to the `%' symbol,
1081 which is used instead of `\e' in string substitution patterns
1082 because `\e' is already escaped by slapd's low level parsing routines;
1083 as a consequence, regex escaping requires two `\e' symbols,
1084 e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'.
1086 .\" The symbol can be altered at will by redefining the related macro in
1087 .\" "rewrite-int.h".
1089 .SH "Rewrite context:"
1090 A rewrite context is a set of rules which are applied in sequence.
1091 The basic idea is to have an application initialize a rewrite
1092 engine (think of Apache's mod_rewrite ...) with a set of rewrite
1093 contexts; when string rewriting is required, one invokes the
1094 appropriate rewrite context with the input string and obtains the
1095 newly rewritten one if no errors occur.
1097 Each basic server operation is associated to a rewrite context;
1098 they are divided in two main groups: client \-> server and
1099 server \-> client rewriting.
1105 (default) if defined and no specific context
1110 searchFilterAttrDN search
1112 compareAttrDN compare AVA
1116 modifyAttrDN modify AVA
1118 newSuperiorDN modrdn
1120 exopPasswdDN password modify extended operation DN if proxy
1128 searchResult search (only if defined; no default;
1129 acts on DN and DN-syntax attributes
1131 searchAttrDN search AVA
1132 matchedDN all ops (only if applicable)
1136 .SH "Basic configuration syntax"
1138 .B rewriteEngine { on | off }
1139 If `on', the requested rewriting is performed; if `off', no
1140 rewriting takes place (an easy way to stop rewriting without
1141 altering too much the configuration file).
1143 .B rewriteContext <context name> "[ alias <aliased context name> ]"
1144 <Context name> is the name that identifies the context, i.e. the name
1145 used by the application to refer to the set of rules it contains.
1146 It is used also to reference sub contexts in string rewriting.
1147 A context may alias another one.
1148 In this case the alias context contains no rule, and any reference to
1149 it will result in accessing the aliased one.
1151 .B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
1152 Determines how a string can be rewritten if a pattern is matched.
1153 Examples are reported below.
1154 .SH "Additional configuration syntax:"
1156 .B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
1157 Allows one to define a map that transforms substring rewriting into
1159 The map is referenced inside the substitution pattern of a rule.
1161 .B rewriteParam <param name> <param value>
1162 Sets a value with global scope, that can be dereferenced by the
1163 command `%{$paramName}'.
1165 .B rewriteMaxPasses <number of passes> [<number of passes per rule>]
1166 Sets the maximum number of total rewriting passes that can be
1167 performed in a single rewrite operation (to avoid loops).
1168 A safe default is set to 100; note that reaching this limit is still
1169 treated as a success; recursive invocation of rules is simply
1171 The count applies to the rewriting operation as a whole, not
1172 to any single rule; an optional per-rule limit can be set.
1173 This limit is overridden by setting specific per-rule limits
1174 with the `M{n}' flag.
1175 .SH "Configuration examples:"
1177 # set to `off' to disable rewriting
1180 # the rules the "suffixmassage" directive implies
1182 # all dataflow from client to server referring to DNs
1183 rewriteContext default
1184 rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
1186 rewriteContext searchFilter
1187 # all dataflow from server to client
1188 rewriteContext searchResult
1189 rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
1190 rewriteContext searchAttrDN alias searchResult
1191 rewriteContext matchedDN alias searchResult
1193 # Everything defined here goes into the `default' context.
1194 # This rule changes the naming context of anything sent
1195 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
1197 rewriteRule "(.*)dc=home,[ ]?dc=net"
1198 "%1dc=OpenLDAP, dc=org" ":"
1200 # since a pretty/normalized DN does not include spaces
1201 # after rdn separators, e.g. `,', this rule suffices:
1203 rewriteRule "(.*)dc=home,dc=net"
1204 "%1dc=OpenLDAP,dc=org" ":"
1206 # Start a new context (ends input of the previous one).
1207 # This rule adds blanks between DN parts if not present.
1208 rewriteContext addBlanks
1209 rewriteRule "(.*),([^ ].*)" "%1, %2"
1211 # This one eats blanks
1212 rewriteContext eatBlanks
1213 rewriteRule "(.*),[ ](.*)" "%1,%2"
1215 # Here control goes back to the default rewrite
1216 # context; rules are appended to the existing ones.
1217 # anything that gets here is piped into rule `addBlanks'
1218 rewriteContext default
1219 rewriteRule ".*" "%{>addBlanks(%0)}" ":"
1221 .\" # Anything with `uid=username' is looked up in
1222 .\" # /etc/passwd for gecos (I know it's nearly useless,
1223 .\" # but it is there just as a guideline to implementing
1225 .\" # Note the `I' flag that leaves `uid=username' in place
1226 .\" # if `username' does not have a valid account, and the
1227 .\" # `:' that forces the rule to be processed exactly once.
1228 .\" rewriteContext uid2Gecos
1229 .\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)"
1230 .\" "%1cn=%2{xpasswd},%3" "I:"
1232 .\" # Finally, in a bind, if one uses a `uid=username' DN,
1233 .\" # it is rewritten in `cn=name surname' if possible.
1234 .\" rewriteContext bindDN
1235 .\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
1237 # Rewrite the search base according to `default' rules.
1238 rewriteContext searchBase alias default
1240 # Search results with OpenLDAP DN are rewritten back with
1241 # `dc=home,dc=net' naming context, with spaces eaten.
1242 rewriteContext searchResult
1243 rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
1244 "%{>eatBlanks(%1)}dc=home,dc=net" ":"
1246 # Bind with email instead of full DN: we first need
1247 # an ldap map that turns attributes into a DN (the
1248 # argument used when invoking the map is appended to
1249 # the URI and acts as the filter portion)
1250 rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
1252 # Then we need to detect DN made up of a single email,
1253 # e.g. `mail=someone@example.com'; note that the rule
1254 # in case of match stops rewriting; in case of error,
1255 # it is ignored. In case we are mapping virtual
1256 # to real naming contexts, we also need to rewrite
1257 # regular DNs, because the definition of a bindDn
1258 # rewrite context overrides the default definition.
1259 rewriteContext bindDN
1260 rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
1262 # This is a rather sophisticated example. It massages a
1263 # search filter in case who performs the search has
1264 # administrative privileges. First we need to keep
1265 # track of the bind DN of the incoming request, which is
1266 # stored in a variable called `binddn' with session scope,
1267 # and left in place to allow regular binding:
1268 rewriteContext bindDN
1269 rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
1271 # A search filter containing `uid=' is rewritten only
1272 # if an appropriate DN is bound.
1273 # To do this, in the first rule the bound DN is
1274 # dereferenced, while the filter is decomposed in a
1275 # prefix, in the value of the `uid=<arg>' AVA, and
1276 # in a suffix. A tag `<>' is appended to the DN.
1277 # If the DN refers to an entry in the `ou=admin' subtree,
1278 # the filter is rewritten OR-ing the `uid=<arg>' with
1279 # `cn=<arg>'; otherwise it is left as is. This could be
1280 # useful, for instance, to allow apache's auth_ldap-1.4
1281 # module to authenticate users with both `uid' and
1282 # `cn', but only if the request comes from a possible
1283 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
1284 rewriteContext searchFilter
1285 rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)"
1286 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
1288 rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
1289 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
1290 rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
1292 # This example shows how to strip unwanted DN-valued
1293 # attribute values from a search result; the first rule
1294 # matches DN values below "ou=People,dc=example,dc=com";
1295 # in case of match the rewriting exits successfully.
1296 # The second rule matches everything else and causes
1297 # the value to be rejected.
1298 rewriteContext searchResult
1299 rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
1300 rewriteRule ".*" "" "#"
1302 .SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):"
1303 In case the rewritten DN is an LDAP URI, the operation is initiated
1304 towards the host[:port] indicated in the uri, if it does not refer
1305 to the local server.
1309 rewriteRule '^cn=root,.*' '%0' 'G{3}'
1310 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
1311 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
1312 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@'
1315 (Rule 1 is simply there to illustrate the `G{n}' action; it could have
1319 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
1322 with the advantage of saving one rewrite pass ...)
1327 backend does not honor all ACL semantics as described in
1328 .BR slapd.access (5).
1329 In general, access checking is delegated to the remote server(s).
1334 pseudo-attribute and to the other attribute values of the entries
1337 operation is honored, which is performed by the frontend.
1339 .SH PROXY CACHE OVERLAY
1340 The proxy cache overlay
1341 allows caching of LDAP search requests (queries) in a local database.
1343 .BR slapo\-pcache (5)
1346 .SH DEPRECATED STATEMENTS
1347 The following statements have been deprecated and should no longer be used.
1350 .B pseudorootdn "<substitute DN in case of rootdn bind>"
1356 .B pseudorootpw "<substitute password in case of rootdn bind>"
1366 default slapd configuration file
1369 .BR slapd\-asyncmeta (5),
1370 .BR slapd\-ldap (5),
1371 .BR slapo\-pcache (5),
1376 Pierangelo Masarati, based on back-ldap by Howard Chu