1.lf 1 stdin 2.TH SLAPD-META 5 "2020/04/28" "OpenLDAP 2.4.50" 3.\" Copyright 1998-2020 The OpenLDAP Foundation, All Rights Reserved. 4.\" Copying restrictions apply. See the COPYRIGHT file. 5.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> 6.\" $OpenLDAP$ 7.\" 8.\" Portions of this document should probably be moved to slapd-ldap(5) 9.\" and maybe manual pages for librewrite. 10.\" 11.SH NAME 12slapd\-meta \- metadirectory backend to slapd 13.SH SYNOPSIS 14/etc/openldap/slapd.conf 15.SH DESCRIPTION 16The 17.B meta 18backend to 19.BR slapd (8) 20performs basic LDAP proxying with respect to a set of remote LDAP 21servers, called "targets". 22The information contained in these servers can be presented as 23belonging to a single Directory Information Tree (DIT). 24.LP 25A basic knowledge of the functionality of the 26.BR slapd\-ldap (5) 27backend is recommended. 28This backend has been designed as an enhancement of the ldap backend. 29The two backends share many features (actually they also share 30portions of code). 31While the 32.B ldap 33backend is intended to proxy operations directed to a single server, the 34.B meta 35backend is mainly intended for proxying of multiple servers and possibly 36naming context masquerading. 37These features, although useful in many scenarios, may result in 38excessive overhead for some applications, so its use should be 39carefully considered. 40In the examples section, some typical scenarios will be discussed. 41 42The proxy instance of 43.BR slapd (8) 44must contain schema information for the attributes and objectClasses 45used in filters, request DN and request-related data in general. 46It should also contain schema information for the data returned 47by the proxied server. 48It is the responsibility of the proxy administrator to keep the schema 49of the proxy lined up with that of the proxied server. 50 51.LP 52Note: When looping back to the same instance of \fBslapd\fP(8), 53each connection requires a new thread; as a consequence, \fBslapd\fP(8) 54must be compiled with thread support, and the \fBthreads\fP parameter 55may need some tuning; in those cases, unless the multiple target feature 56is required, one may consider using \fBslapd\-relay\fP(5) instead, 57which performs the relayed operation internally and thus reuses 58the same connection. 59 60.SH EXAMPLES 61There are examples in various places in this document, as well as in the 62slapd/back\-meta/data/ directory in the OpenLDAP source tree. 63.SH CONFIGURATION 64These 65.B slapd.conf 66options apply to the META backend database. 67That is, they must follow a "database meta" line and come before any 68subsequent "backend" or "database" lines. 69Other database options are described in the 70.BR slapd.conf (5) 71manual page. 72.LP 73Note: In early versions of back-ldap and back-meta it was recommended to always set 74.LP 75.RS 76.nf 77lastmod off 78.fi 79.RE 80.LP 81for 82.B ldap 83and 84.B meta 85databases. 86This was required because operational attributes related to entry creation 87and modification should not be proxied, as they could be mistakenly written 88to the target server(s), generating an error. 89The current implementation automatically sets lastmod to \fBoff\fP, 90so its use is redundant and should be omitted. 91 92.SH SPECIAL CONFIGURATION DIRECTIVES 93Target configuration starts with the "uri" directive. 94All the configuration directives that are not specific to targets 95should be defined first for clarity, including those that are common 96to all backends. 97They are: 98 99.TP 100.B conn\-ttl <time> 101This directive causes a cached connection to be dropped an recreated 102after a given ttl, regardless of being idle or not. 103 104.TP 105.B default\-target none 106This directive forces the backend to reject all those operations 107that must resolve to a single target in case none or multiple 108targets are selected. 109They include: add, delete, modify, modrdn; compare is not included, as 110well as bind since, as they don't alter entries, in case of multiple 111matches an attempt is made to perform the operation on any candidate 112target, with the constraint that at most one must succeed. 113This directive can also be used when processing targets to mark a 114specific target as default. 115 116.TP 117.B dncache\-ttl {DISABLED|forever|<ttl>} 118This directive sets the time-to-live of the DN cache. 119This caches the target that holds a given DN to speed up target 120selection in case multiple targets would result from an uncached 121search; forever means cache never expires; disabled means no DN 122caching; otherwise a valid ( > 0 ) ttl is required, in the format 123illustrated for the 124.B idle\-timeout 125directive. 126 127.TP 128.B onerr {CONTINUE|report|stop} 129This directive allows one to select the behavior in case an error is returned 130by one target during a search. 131The default, \fBcontinue\fP, consists in continuing the operation, 132trying to return as much data as possible. 133If the value is set to \fBstop\fP, the search is terminated as soon 134as an error is returned by one target, and the error is immediately 135propagated to the client. 136If the value is set to \fBreport\fP, the search is continuated to the end 137but, in case at least one target returned an error code, the first 138non-success error code is returned. 139 140.TP 141.B norefs <NO|yes> 142If 143.BR yes , 144do not return search reference responses. 145By default, they are returned unless request is LDAPv2. 146If set before any target specification, it affects all targets, unless 147overridden by any per-target directive. 148 149.TP 150.B noundeffilter <NO|yes> 151If 152.BR yes , 153return success instead of searching if a filter is undefined or contains 154undefined portions. 155By default, the search is propagated after replacing undefined portions 156with 157.BR (!(objectClass=*)) , 158which corresponds to the empty result set. 159If set before any target specification, it affects all targets, unless 160overridden by any per-target directive. 161 162.TP 163.B protocol\-version {0,2,3} 164This directive indicates what protocol version must be used to contact 165the remote server. 166If set to 0 (the default), the proxy uses the same protocol version 167used by the client, otherwise the requested protocol is used. 168The proxy returns \fIunwillingToPerform\fP if an operation that is 169incompatible with the requested protocol is attempted. 170If set before any target specification, it affects all targets, unless 171overridden by any per-target directive. 172 173.TP 174.B pseudoroot\-bind\-defer {YES|no} 175This directive, when set to 176.BR yes , 177causes the authentication to the remote servers with the pseudo-root 178identity (the identity defined in each 179.B idassert-bind 180directive) to be deferred until actually needed by subsequent operations. 181Otherwise, all binds as the rootdn are propagated to the targets. 182 183.TP 184.B quarantine <interval>,<num>[;<interval>,<num>[...]] 185Turns on quarantine of URIs that returned 186.IR LDAP_UNAVAILABLE , 187so that an attempt to reconnect only occurs at given intervals instead 188of any time a client requests an operation. 189The pattern is: retry only after at least 190.I interval 191seconds elapsed since last attempt, for exactly 192.I num 193times; then use the next pattern. 194If 195.I num 196for the last pattern is "\fB+\fP", it retries forever; otherwise, 197no more retries occur. 198This directive must appear before any target specification; 199it affects all targets with the same pattern. 200 201.TP 202.B rebind\-as\-user {NO|yes} 203If this option is given, the client's bind credentials are remembered 204for rebinds, when trying to re-establish a broken connection, 205or when chasing a referral, if 206.B chase\-referrals 207is set to 208.IR yes . 209 210.TP 211.B session\-tracking\-request {NO|yes} 212Adds session tracking control for all requests. 213The client's IP and hostname, and the identity associated to each request, 214if known, are sent to the remote server for informational purposes. 215This directive is incompatible with setting \fIprotocol\-version\fP to 2. 216If set before any target specification, it affects all targets, unless 217overridden by any per-target directive. 218 219.TP 220.B single\-conn {NO|yes} 221Discards current cached connection when the client rebinds. 222 223.TP 224.B use\-temporary\-conn {NO|yes} 225when set to 226.BR yes , 227create a temporary connection whenever competing with other threads 228for a shared one; otherwise, wait until the shared connection is available. 229 230.SH TARGET SPECIFICATION 231Target specification starts with a "uri" directive: 232 233.TP 234.B uri <protocol>://[<host>]/<naming context> [...] 235The <protocol> part can be anything 236.BR ldap_initialize (3) 237accepts ({ldap|ldaps|ldapi} and variants); the <host> may be 238omitted, defaulting to whatever is set in 239.BR ldap.conf (5). 240The <naming context> part is \fImandatory\fP for the first URI, 241but it \fImust be omitted\fP for subsequent ones, if any. 242The naming context part must be within the naming context defined for the backend, 243e.g.: 244.LP 245.RS 246.nf 247suffix "\fBdc=foo,dc=com\fP" 248uri "ldap://x.foo.com/dc=x,\fBdc=foo,dc=com\fP" 249.fi 250 251.RE 252.RS 253The <naming context> part doesn't need to be unique across the targets; 254it may also match one of the values of the "suffix" directive. 255Multiple URIs may be defined in a single URI statement. 256The additional URIs must be separate arguments and must not have any 257<naming context> part. This causes the underlying library 258to contact the first server of the list that responds. 259For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows 260of the same server, the directive 261.LP 262.nf 263suffix "\fBdc=foo,dc=com\fP" 264uri "ldap://l1.foo.com/\fBdc=foo,dc=com\fP" "ldap://l2.foo.com/" 265.fi 266 267.RE 268.RS 269causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP 270does not respond. 271In that case, the URI list is internally rearranged, by moving unavailable 272URIs to the end, so that further connection attempts occur with respect to 273the last URI that succeeded. 274.RE 275 276.TP 277.B acl\-authcDN "<administrative DN for access control purposes>" 278DN which is used to query the target server for acl checking, 279as in the LDAP backend; it is supposed to have read access 280on the target server to attributes used on the proxy for acl checking. 281There is no risk of giving away such values; they are only used to 282check permissions. 283.B The acl\-authcDN identity is by no means implicitly used by the proxy 284.B when the client connects anonymously. 285 286.TP 287.B acl\-passwd <password> 288Password used with the 289.B 290acl\-authcDN 291above. 292 293.TP 294.B bind\-timeout <microseconds> 295This directive defines the timeout, in microseconds, used when polling 296for response after an asynchronous bind connection. The initial call 297to ldap_result(3) is performed with a trade-off timeout of 100000 us; 298if that results in a timeout exceeded, subsequent calls use the value 299provided with 300.BR bind\-timeout . 301The default value is used also for subsequent calls if 302.B bind\-timeout 303is not specified. 304If set before any target specification, it affects all targets, unless 305overridden by any per-target directive. 306 307.TP 308.B chase\-referrals {YES|no} 309enable/disable automatic referral chasing, which is delegated to the 310underlying libldap, with rebinding eventually performed if the 311\fBrebind\-as\-user\fP directive is used. The default is to chase referrals. 312If set before any target specification, it affects all targets, unless 313overridden by any per-target directive. 314 315.TP 316.B default\-target [<target>] 317The "default\-target" directive can also be used during target specification. 318With no arguments it marks the current target as the default. 319The optional number marks target <target> as the default one, starting 320from 1. 321Target <target> must be defined. 322 323.TP 324.B filter <pattern> 325This directive allows specifying a 326.BR regex (5) 327pattern to indicate what search filter terms are actually served by a target. 328 329In a search request, if the search filter matches the \fIpattern\fP 330the target is considered while fulfilling the request; otherwise 331the target is ignored. There may be multiple occurrences of 332the 333.B filter 334directive for each target. 335 336.TP 337.B idassert\-authzFrom <authz-regexp> 338if defined, selects what 339.I local 340identities are authorized to exploit the identity assertion feature. 341The string 342.B <authz-regexp> 343follows the rules defined for the 344.I authzFrom 345attribute. 346See 347.BR slapd.conf (5), 348section related to 349.BR authz\-policy , 350for details on the syntax of this field. 351 352.HP 353.hy 0 354.B idassert\-bind 355.B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>] 356.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] 357.B [authcId=<authentication ID>] [authzId=<authorization ID>] 358.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>] 359.B [starttls=no|yes|critical] 360.B [tls_cert=<file>] 361.B [tls_key=<file>] 362.B [tls_cacert=<file>] 363.B [tls_cacertdir=<path>] 364.B [tls_reqcert=never|allow|try|demand] 365.B [tls_cipher_suite=<ciphers>] 366.B [tls_protocol_min=<major>[.<minor>]] 367.B [tls_crlcheck=none|peer|all] 368.RS 369Allows one to define the parameters of the authentication method that is 370internally used by the proxy to authorize connections that are 371authenticated by other databases. 372The identity defined by this directive, according to the properties 373associated to the authentication method, is supposed to have auth access 374on the target server to attributes used on the proxy for authentication 375and authorization, and to be allowed to authorize the users. 376This requires to have 377.B proxyAuthz 378privileges on a wide set of DNs, e.g. 379.BR authzTo=dn.subtree:"" , 380and the remote server to have 381.B authz\-policy 382set to 383.B to 384or 385.BR both . 386See 387.BR slapd.conf (5) 388for details on these statements and for remarks and drawbacks about 389their usage. 390The supported bindmethods are 391 392\fBnone|simple|sasl\fP 393 394where 395.B none 396is the default, i.e. no \fIidentity assertion\fP is performed. 397 398The authz parameter is used to instruct the SASL bind to exploit 399.B native 400SASL authorization, if available; since connections are cached, 401this should only be used when authorizing with a fixed identity 402(e.g. by means of the 403.B authzDN 404or 405.B authzID 406parameters). 407Otherwise, the default 408.B proxyauthz 409is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370) 410is added to all operations. 411 412The supported modes are: 413 414\fB<mode> := {legacy|anonymous|none|self}\fP 415 416If 417.B <mode> 418is not present, and 419.B authzId 420is given, the proxy always authorizes that identity. 421.B <authorization ID> 422can be 423 424\fBu:<user>\fP 425 426\fB[dn:]<DN>\fP 427 428The former is supposed to be expanded by the remote server according 429to the authz rules; see 430.BR slapd.conf (5) 431for details. 432In the latter case, whether or not the 433.B dn: 434prefix is present, the string must pass DN validation and normalization. 435 436The default mode is 437.BR legacy , 438which implies that the proxy will either perform a simple bind as the 439.I authcDN 440or a SASL bind as the 441.I authcID 442and assert the client's identity when it is not anonymous. 443Direct binds are always proxied. 444The other modes imply that the proxy will always either perform a simple bind 445as the 446.IR authcDN 447or a SASL bind as the 448.IR authcID , 449unless restricted by 450.BR idassert\-authzFrom 451rules (see below), in which case the operation will fail; 452eventually, it will assert some other identity according to 453.BR <mode> . 454Other identity assertion modes are 455.BR anonymous 456and 457.BR self , 458which respectively mean that the 459.I empty 460or the 461.IR client 's 462identity 463will be asserted; 464.BR none , 465which means that no proxyAuthz control will be used, so the 466.I authcDN 467or the 468.I authcID 469identity will be asserted. 470For all modes that require the use of the 471.I proxyAuthz 472control, on the remote server the proxy identity must have appropriate 473.I authzTo 474permissions, or the asserted identities must have appropriate 475.I authzFrom 476permissions. Note, however, that the ID assertion feature is mostly 477useful when the asserted identities do not exist on the remote server. 478 479Flags can be 480 481\fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP 482 483When the 484.B override 485flag is used, identity assertion takes place even when the database 486is authorizing for the identity of the client, i.e. after binding 487with the provided identity, and thus authenticating it, the proxy 488performs the identity assertion using the configured identity and 489authentication method. 490 491When the 492.B prescriptive 493flag is used (the default), operations fail with 494\fIinappropriateAuthentication\fP 495for those identities whose assertion is not allowed by the 496.B idassert\-authzFrom 497patterns. 498If the 499.B non\-prescriptive 500flag is used, operations are performed anonymously for those identities 501whose assertion is not allowed by the 502.B idassert\-authzFrom 503patterns. 504 505When the 506.B proxy\-authz\-non\-critical 507flag is used (the default), the proxyAuthz control is not marked as critical, 508in violation of RFC 4370. Use of 509.B proxy\-authz\-critical 510is recommended. 511 512The TLS settings default to the same as the main slapd TLS settings, 513except for 514.B tls_reqcert 515which defaults to "demand". 516 517The identity associated to this directive is also used for privileged 518operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP 519is not. See \fBacl\-bind\fP for details. 520.RE 521 522.TP 523.B idle\-timeout <time> 524This directive causes a cached connection to be dropped an recreated 525after it has been idle for the specified time. 526The value can be specified as 527 528[<d>d][<h>h][<m>m][<s>[s]] 529 530where <d>, <h>, <m> and <s> are respectively treated as days, hours, 531minutes and seconds. 532If set before any target specification, it affects all targets, unless 533overridden by any per-target directive. 534 535.TP 536.B keepalive <idle>:<probes>:<interval> 537The 538.B keepalive 539parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP 540used to check whether a socket is alive; 541.I idle 542is the number of seconds a connection needs to remain idle before TCP 543starts sending keepalive probes; 544.I probes 545is the maximum number of keepalive probes TCP should send before dropping 546the connection; 547.I interval 548is interval in seconds between individual keepalive probes. 549Only some systems support the customization of these values; 550the 551.B keepalive 552parameter is ignored otherwise, and system-wide settings are used. 553 554.TP 555.B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}" 556This maps object classes and attributes as in the LDAP backend. 557See 558.BR slapd\-ldap (5). 559 560.TP 561.B network\-timeout <time> 562Sets the network timeout value after which 563.BR poll (2)/ select (2) 564following a 565.BR connect (2) 566returns in case of no activity. 567The value is in seconds, and it can be specified as for 568.BR idle\-timeout . 569If set before any target specification, it affects all targets, unless 570overridden by any per-target directive. 571 572.TP 573.B nretries {forever|never|<nretries>} 574This directive defines how many times a bind should be retried 575in case of temporary failure in contacting a target. If defined 576before any target specification, it applies to all targets (by default, 577.BR 3 578times); 579the global value can be overridden by redefinitions inside each target 580specification. 581 582.TP 583.B rewrite* ... 584The rewrite options are described in the "REWRITING" section. 585 586.TP 587.B subtree\-{exclude|include} "<rule>" 588This directive allows one to indicate what subtrees are actually served 589by a target. 590The syntax of the supported rules is 591 592\fB<rule>: [dn[.<style>]:]<pattern>\fP 593 594\fB<style>: subtree|children|regex\fP 595 596When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP 597the \fB<pattern>\fP is a DN that must be within the naming context 598served by the target. 599When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a 600.BR regex (5) 601pattern. 602If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP 603is implicitly assumed for backward compatibility. 604 605In the 606.B subtree\-exclude 607form if the \fIrequest DN\fP matches at least one rule, 608the target is not considered while fulfilling the request; 609otherwise, the target is considered based on the value of the \fIrequest DN\fP. 610When the request is a search, also the \fIscope\fP is considered. 611 612In the 613.B subtree\-include 614form if the \fIrequest DN\fP matches at least one rule, 615the target is considered while fulfilling the request; 616otherwise the target is ignored. 617 618.LP 619.RS 620.nf 621 | match | exclude | 622 +---------+---------+-------------------+ 623 | T | T | not candidate | 624 | F | T | continue checking | 625 +---------+---------+-------------------+ 626 | T | F | candidate | 627 | F | F | not candidate | 628 +---------+---------+-------------------+ 629.fi 630 631.RE 632.RS 633There may be multiple occurrences of the 634.B subtree\-exclude 635or 636.B subtree\-include 637directive for each of the targets, but they are mutually exclusive. 638.RE 639 640.TP 641.B suffixmassage "<virtual naming context>" "<real naming context>" 642All the directives starting with "rewrite" refer to the rewrite engine 643that has been added to slapd. 644The "suffixmassage" directive was introduced in the LDAP backend to 645allow suffix massaging while proxying. 646It has been obsoleted by the rewriting tools. 647However, both for backward compatibility and for ease of configuration 648when simple suffix massage is required, it has been preserved. 649It wraps the basic rewriting instructions that perform suffix 650massaging. See the "REWRITING" section for a detailed list 651of the rewrite rules it implies. 652 653.TP 654.B t\-f\-support {NO|yes|discover} 655enable if the remote server supports absolute filters 656(see \fIRFC 4526\fP for details). 657If set to 658.BR discover , 659support is detected by reading the remote server's root DSE. 660If set before any target specification, it affects all targets, unless 661overridden by any per-target directive. 662 663.TP 664.B timeout [<op>=]<val> [...] 665This directive allows one to set per-operation timeouts. 666Operations can be 667 668\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP 669 670The overall duration of the \fBsearch\fP operation is controlled either 671by the \fBtimelimit\fP parameter or by server-side enforced 672time limits (see \fBtimelimit\fP and \fBlimits\fP in 673.BR slapd.conf (5) 674for details). 675This \fBtimeout\fP parameter controls how long the target can be 676irresponsive before the operation is aborted. 677Timeout is meaningless for the remaining operations, 678\fBunbind\fP and \fBabandon\fP, which do not imply any response, 679while it is not yet implemented in currently supported \fBextended\fP 680operations. 681If no operation is specified, the timeout \fBval\fP affects all 682supported operations. 683If specified before any target definition, it affects all targets 684unless overridden by per-target directives. 685 686Note: if the timeout is exceeded, the operation is cancelled 687(according to the \fBcancel\fP directive); 688the protocol does not provide any means to rollback operations, 689so the client will not be notified about the result of the operation, 690which may eventually succeeded or not. 691In case the timeout is exceeded during a bind operation, the connection 692is destroyed, according to RFC4511. 693 694.TP 695.B tls {[try\-]start|[try\-]propagate} 696execute the StartTLS extended operation when the connection is initialized; 697only works if the URI directive protocol scheme is not \fBldaps://\fP. 698\fBpropagate\fP issues the StartTLS operation only if the original 699connection did. 700The \fBtry\-\fP prefix instructs the proxy to continue operations 701if the StartTLS operation failed; its use is highly deprecated. 702If set before any target specification, it affects all targets, unless 703overridden by any per-target directive. 704 705.SH SCENARIOS 706A powerful (and in some sense dangerous) rewrite engine has been added 707to both the LDAP and Meta backends. 708While the former can gain limited beneficial effects from rewriting 709stuff, the latter can become an amazingly powerful tool. 710.LP 711Consider a couple of scenarios first. 712.LP 7131) Two directory servers share two levels of naming context; 714say "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". 715Then, an unambiguous Meta database can be configured as: 716.LP 717.RS 718.nf 719database meta 720suffix "\fBdc=foo,dc=com\fP" 721uri "ldap://a.foo.com/dc=a,\fBdc=foo,dc=com\fP" 722uri "ldap://b.foo.com/dc=b,\fBdc=foo,dc=com\fP" 723.fi 724.RE 725.LP 726Operations directed to a specific target can be easily resolved 727because there are no ambiguities. 728The only operation that may resolve to multiple targets is a search 729with base "dc=foo,dc=com" and scope at least "one", which results in 730spawning two searches to the targets. 731.LP 7322a) Two directory servers don't share any portion of naming context, 733but they'd present as a single DIT 734[Caveat: uniqueness of (massaged) entries among the two servers is 735assumed; integrity checks risk to incur in excessive overhead and have 736not been implemented]. 737Say we have "dc=bar,dc=org" and "o=Foo,c=US", 738and we'd like them to appear as branches of "dc=foo,dc=com", say 739"dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com". 740Then we need to configure our Meta backend as: 741.LP 742.RS 743.nf 744database meta 745suffix "dc=foo,dc=com" 746 747uri "ldap://a.bar.com/\fBdc=a,dc=foo,dc=com\fP" 748suffixmassage "\fBdc=a,dc=foo,dc=com\fP" "dc=bar,dc=org" 749 750uri "ldap://b.foo.com/\fBdc=b,dc=foo,dc=com\fP" 751suffixmassage "\fBdc=b,dc=foo,dc=com\fP" "o=Foo,c=US" 752.fi 753.RE 754.LP 755Again, operations can be resolved without ambiguity, although 756some rewriting is required. 757Notice that the virtual naming context of each target is a branch of 758the database's naming context; it is rewritten back and forth when 759operations are performed towards the target servers. 760What "back and forth" means will be clarified later. 761.LP 762When a search with base "dc=foo,dc=com" is attempted, if the 763scope is "base" it fails with "no such object"; in fact, the 764common root of the two targets (prior to massaging) does not 765exist. 766If the scope is "one", both targets are contacted with the base 767replaced by each target's base; the scope is derated to "base". 768In general, a scope "one" search is honored, and the scope is derated, 769only when the incoming base is at most one level lower of a target's 770naming context (prior to massaging). 771.LP 772Finally, if the scope is "sub" the incoming base is replaced 773by each target's unmassaged naming context, and the scope 774is not altered. 775.LP 7762b) Consider the above reported scenario with the two servers 777sharing the same naming context: 778.LP 779.RS 780.nf 781database meta 782suffix "\fBdc=foo,dc=com\fP" 783 784uri "ldap://a.bar.com/\fBdc=foo,dc=com\fP" 785suffixmassage "\fBdc=foo,dc=com\fP" "dc=bar,dc=org" 786 787uri "ldap://b.foo.com/\fBdc=foo,dc=com\fP" 788suffixmassage "\fBdc=foo,dc=com\fP" "o=Foo,c=US" 789.fi 790.RE 791.LP 792All the previous considerations hold, except that now there is 793no way to unambiguously resolve a DN. 794In this case, all the operations that require an unambiguous target 795selection will fail unless the DN is already cached or a default 796target has been set. 797Practical configurations may result as a combination of all the 798above scenarios. 799.SH ACLs 800Note on ACLs: at present you may add whatever ACL rule you desire 801to the Meta (and LDAP) backends. 802However, the meaning of an ACL on a proxy may require some 803considerations. 804Two philosophies may be considered: 805.LP 806a) the remote server dictates the permissions; the proxy simply passes 807back what it gets from the remote server. 808.LP 809b) the remote server unveils "everything"; the proxy is responsible 810for protecting data from unauthorized access. 811.LP 812Of course the latter sounds unreasonable, but it is not. 813It is possible to imagine scenarios in which a remote host discloses 814data that can be considered "public" inside an intranet, and a proxy 815that connects it to the internet may impose additional constraints. 816To this purpose, the proxy should be able to comply with all the ACL 817matching criteria that the server supports. 818This has been achieved with regard to all the criteria supported by 819slapd except a special subtle case (please file an ITS if you can 820find other exceptions: <http://www.openldap.org/its/>). 821The rule 822.LP 823.RS 824.nf 825access to dn="<dn>" attrs=<attr> 826 by dnattr=<dnattr> read 827 by * none 828.fi 829.RE 830.LP 831cannot be matched iff the attribute that is being requested, <attr>, 832is NOT <dnattr>, and the attribute that determines membership, 833<dnattr>, has not been requested (e.g. in a search) 834.LP 835In fact this ACL is resolved by slapd using the portion of entry it 836retrieved from the remote server without requiring any further 837intervention of the backend, so, if the <dnattr> attribute has not 838been fetched, the match cannot be assessed because the attribute is 839not present, not because no value matches the requirement! 840.LP 841Note on ACLs and attribute mapping: ACLs are applied to the mapped 842attributes; for instance, if the attribute locally known as "foo" is 843mapped to "bar" on a remote server, then local ACLs apply to attribute 844"foo" and are totally unaware of its remote name. 845The remote server will check permissions for "bar", and the local 846server will possibly enforce additional restrictions to "foo". 847.\" 848.\" If this section is moved, also update the reference in 849.\" libraries/librewrite/RATIONALE. 850.\" 851.SH REWRITING 852A string is rewritten according to a set of rules, called a `rewrite 853context'. 854The rules are based on POSIX (''extended'') regular expressions (regex) 855with substring matching; basic variable substitution and map resolution 856of substrings is allowed by specific mechanisms detailed in the following. 857The behavior of pattern matching/substitution can be altered by a set 858of flags. 859.LP 860The underlying concept is to build a lightweight rewrite module 861for the slapd server (initially dedicated to the LDAP backend). 862.SH Passes 863An incoming string is matched against a set of rules. 864Rules are made of a regex match pattern, a substitution pattern 865and a set of actions, described by a set of flags. 866In case of match a string rewriting is performed according to the 867substitution pattern that allows one to refer to substrings matched in the 868incoming string. 869The actions, if any, are finally performed. 870The substitution pattern allows map resolution of substrings. 871A map is a generic object that maps a substitution pattern to a value. 872The flags are divided in "Pattern matching Flags" and "Action Flags"; 873the former alter the regex match pattern behavior while the latter 874alter the action that is taken after substitution. 875.SH "Pattern Matching Flags" 876.TP 877.B `C' 878honors case in matching (default is case insensitive) 879.TP 880.B `R' 881use POSIX ''basic'' regular expressions (default is ''extended'') 882.TP 883.B `M{n}' 884allow no more than 885.B n 886recursive passes for a specific rule; does not alter the max total count 887of passes, so it can only enforce a stricter limit for a specific rule. 888.SH "Action Flags" 889.TP 890.B `:' 891apply the rule once only (default is recursive) 892.TP 893.B `@' 894stop applying rules in case of match; the current rule is still applied 895recursively; combine with `:' to apply the current rule only once 896and then stop. 897.TP 898.B `#' 899stop current operation if the rule matches, and issue an `unwilling to 900perform' error. 901.TP 902.B `G{n}' 903jump 904.B n 905rules back and forth (watch for loops!). 906Note that `G{1}' is implicit in every rule. 907.TP 908.B `I' 909ignores errors in rule; this means, in case of error, e.g. issued by a 910map, the error is treated as a missed match. 911The `unwilling to perform' is not overridden. 912.TP 913.B `U{n}' 914uses 915.B 916n 917as return code if the rule matches; the flag does not alter the recursive 918behavior of the rule, so, to have it performed only once, it must be used 919in combination with `:', e.g. 920.B `:U{16}' 921returns the value `16' after exactly one execution of the rule, if the 922pattern matches. 923As a consequence, its behavior is equivalent to `@', with the return 924code set to 925.BR n ; 926or, in other words, `@' is equivalent to `U{0}'. 927By convention, the freely available codes are above 16 included; 928the others are reserved. 929.LP 930The ordering of the flags can be significant. 931For instance: `IG{2}' means ignore errors and jump two lines ahead 932both in case of match and in case of error, while `G{2}I' means ignore 933errors, but jump two lines ahead only in case of match. 934.LP 935More flags (mainly Action Flags) will be added as needed. 936.SH "Pattern matching:" 937See 938.BR regex (7) 939and/or 940.BR re_format (7). 941.SH "Substitution Pattern Syntax:" 942Everything starting with `%' requires substitution; 943.LP 944the only obvious exception is `%%', which is left as is; 945.LP 946the basic substitution is `%d', where `d' is a digit; 9470 means the whole string, while 1-9 is a submatch; 948.LP 949a `%' followed by a `{' invokes an advanced substitution. 950The pattern is: 951.LP 952.RS 953`%' `{' [ <op> ] <name> `(' <substitution> `)' `}' 954.RE 955.LP 956where <name> must be a legal name for the map, i.e. 957.LP 958.RS 959.nf 960<name> ::= [a-z][a-z0-9]* (case insensitive) 961<op> ::= `>' `|' `&' `&&' `*' `**' `$' 962.fi 963.RE 964.LP 965and <substitution> must be a legal substitution 966pattern, with no limits on the nesting level. 967.LP 968The operators are: 969.TP 970.B > 971sub context invocation; <name> must be a legal, already defined 972rewrite context name 973.TP 974.B | 975external command invocation; <name> must refer to a legal, already 976defined command name (NOT IMPL.) 977.TP 978.B & 979variable assignment; <name> defines a variable in the running 980operation structure which can be dereferenced later; operator 981.B & 982assigns a variable in the rewrite context scope; operator 983.B && 984assigns a variable that scopes the entire session, e.g. its value 985can be dereferenced later by other rewrite contexts 986.TP 987.B * 988variable dereferencing; <name> must refer to a variable that is 989defined and assigned for the running operation; operator 990.B * 991dereferences a variable scoping the rewrite context; operator 992.B ** 993dereferences a variable scoping the whole session, e.g. the value 994is passed across rewrite contexts 995.TP 996.B $ 997parameter dereferencing; <name> must refer to an existing parameter; 998the idea is to make some run-time parameters set by the system 999available to the rewrite engine, as the client host name, the bind DN 1000if any, constant parameters initialized at config time, and so on; 1001no parameter is currently set by either 1002.B back\-ldap 1003or 1004.BR back\-meta , 1005but constant parameters can be defined in the configuration file 1006by using the 1007.B rewriteParam 1008directive. 1009.LP 1010Substitution escaping has been delegated to the `%' symbol, 1011which is used instead of `\e' in string substitution patterns 1012because `\e' is already escaped by slapd's low level parsing routines; 1013as a consequence, regex escaping requires two `\e' symbols, 1014e.g. `\fB.*\e.foo\e.bar\fP' must be written as `\fB.*\e\e.foo\e\e.bar\fP'. 1015.\" 1016.\" The symbol can be altered at will by redefining the related macro in 1017.\" "rewrite-int.h". 1018.\" 1019.SH "Rewrite context:" 1020A rewrite context is a set of rules which are applied in sequence. 1021The basic idea is to have an application initialize a rewrite 1022engine (think of Apache's mod_rewrite ...) with a set of rewrite 1023contexts; when string rewriting is required, one invokes the 1024appropriate rewrite context with the input string and obtains the 1025newly rewritten one if no errors occur. 1026.LP 1027Each basic server operation is associated to a rewrite context; 1028they are divided in two main groups: client \-> server and 1029server \-> client rewriting. 1030.LP 1031client \-> server: 1032.LP 1033.RS 1034.nf 1035(default) if defined and no specific context 1036 is available 1037bindDN bind 1038searchBase search 1039searchFilter search 1040searchFilterAttrDN search 1041compareDN compare 1042compareAttrDN compare AVA 1043addDN add 1044addAttrDN add AVA 1045modifyDN modify 1046modifyAttrDN modify AVA 1047modrDN modrdn 1048newSuperiorDN modrdn 1049deleteDN delete 1050exopPasswdDN password modify extended operation DN if proxy 1051.fi 1052.RE 1053.LP 1054server \-> client: 1055.LP 1056.RS 1057.nf 1058searchResult search (only if defined; no default; 1059 acts on DN and DN-syntax attributes 1060 of search results) 1061searchAttrDN search AVA 1062matchedDN all ops (only if applicable) 1063.fi 1064.RE 1065.LP 1066.SH "Basic configuration syntax" 1067.TP 1068.B rewriteEngine { on | off } 1069If `on', the requested rewriting is performed; if `off', no 1070rewriting takes place (an easy way to stop rewriting without 1071altering too much the configuration file). 1072.TP 1073.B rewriteContext <context name> "[ alias <aliased context name> ]" 1074<Context name> is the name that identifies the context, i.e. the name 1075used by the application to refer to the set of rules it contains. 1076It is used also to reference sub contexts in string rewriting. 1077A context may alias another one. 1078In this case the alias context contains no rule, and any reference to 1079it will result in accessing the aliased one. 1080.TP 1081.B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]" 1082Determines how a string can be rewritten if a pattern is matched. 1083Examples are reported below. 1084.SH "Additional configuration syntax:" 1085.TP 1086.B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]" 1087Allows one to define a map that transforms substring rewriting into 1088something else. 1089The map is referenced inside the substitution pattern of a rule. 1090.TP 1091.B rewriteParam <param name> <param value> 1092Sets a value with global scope, that can be dereferenced by the 1093command `%{$paramName}'. 1094.TP 1095.B rewriteMaxPasses <number of passes> [<number of passes per rule>] 1096Sets the maximum number of total rewriting passes that can be 1097performed in a single rewrite operation (to avoid loops). 1098A safe default is set to 100; note that reaching this limit is still 1099treated as a success; recursive invocation of rules is simply 1100interrupted. 1101The count applies to the rewriting operation as a whole, not 1102to any single rule; an optional per-rule limit can be set. 1103This limit is overridden by setting specific per-rule limits 1104with the `M{n}' flag. 1105.SH "Configuration examples:" 1106.nf 1107# set to `off' to disable rewriting 1108rewriteEngine on 1109 1110# the rules the "suffixmassage" directive implies 1111rewriteEngine on 1112# all dataflow from client to server referring to DNs 1113rewriteContext default 1114rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":" 1115# empty filter rule 1116rewriteContext searchFilter 1117# all dataflow from server to client 1118rewriteContext searchResult 1119rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":" 1120rewriteContext searchAttrDN alias searchResult 1121rewriteContext matchedDN alias searchResult 1122 1123# Everything defined here goes into the `default' context. 1124# This rule changes the naming context of anything sent 1125# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org' 1126 1127rewriteRule "(.*)dc=home,[ ]?dc=net" 1128 "%1dc=OpenLDAP, dc=org" ":" 1129 1130# since a pretty/normalized DN does not include spaces 1131# after rdn separators, e.g. `,', this rule suffices: 1132 1133rewriteRule "(.*)dc=home,dc=net" 1134 "%1dc=OpenLDAP,dc=org" ":" 1135 1136# Start a new context (ends input of the previous one). 1137# This rule adds blanks between DN parts if not present. 1138rewriteContext addBlanks 1139rewriteRule "(.*),([^ ].*)" "%1, %2" 1140 1141# This one eats blanks 1142rewriteContext eatBlanks 1143rewriteRule "(.*),[ ](.*)" "%1,%2" 1144 1145# Here control goes back to the default rewrite 1146# context; rules are appended to the existing ones. 1147# anything that gets here is piped into rule `addBlanks' 1148rewriteContext default 1149rewriteRule ".*" "%{>addBlanks(%0)}" ":" 1150 1151.\" # Anything with `uid=username' is looked up in 1152.\" # /etc/passwd for gecos (I know it's nearly useless, 1153.\" # but it is there just as a guideline to implementing 1154.\" # custom maps). 1155.\" # Note the `I' flag that leaves `uid=username' in place 1156.\" # if `username' does not have a valid account, and the 1157.\" # `:' that forces the rule to be processed exactly once. 1158.\" rewriteContext uid2Gecos 1159.\" rewriteRule "(.*)uid=([a-z0-9]+),(.+)" 1160.\" "%1cn=%2{xpasswd},%3" "I:" 1161.\" 1162.\" # Finally, in a bind, if one uses a `uid=username' DN, 1163.\" # it is rewritten in `cn=name surname' if possible. 1164.\" rewriteContext bindDN 1165.\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":" 1166.\" 1167# Rewrite the search base according to `default' rules. 1168rewriteContext searchBase alias default 1169 1170# Search results with OpenLDAP DN are rewritten back with 1171# `dc=home,dc=net' naming context, with spaces eaten. 1172rewriteContext searchResult 1173rewriteRule "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org" 1174 "%{>eatBlanks(%1)}dc=home,dc=net" ":" 1175 1176# Bind with email instead of full DN: we first need 1177# an ldap map that turns attributes into a DN (the 1178# argument used when invoking the map is appended to 1179# the URI and acts as the filter portion) 1180rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" 1181 1182# Then we need to detect DN made up of a single email, 1183# e.g. `mail=someone@example.com'; note that the rule 1184# in case of match stops rewriting; in case of error, 1185# it is ignored. In case we are mapping virtual 1186# to real naming contexts, we also need to rewrite 1187# regular DNs, because the definition of a bindDn 1188# rewrite context overrides the default definition. 1189rewriteContext bindDN 1190rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I" 1191 1192# This is a rather sophisticated example. It massages a 1193# search filter in case who performs the search has 1194# administrative privileges. First we need to keep 1195# track of the bind DN of the incoming request, which is 1196# stored in a variable called `binddn' with session scope, 1197# and left in place to allow regular binding: 1198rewriteContext bindDN 1199rewriteRule ".+" "%{&&binddn(%0)}%0" ":" 1200 1201# A search filter containing `uid=' is rewritten only 1202# if an appropriate DN is bound. 1203# To do this, in the first rule the bound DN is 1204# dereferenced, while the filter is decomposed in a 1205# prefix, in the value of the `uid=<arg>' AVA, and 1206# in a suffix. A tag `<>' is appended to the DN. 1207# If the DN refers to an entry in the `ou=admin' subtree, 1208# the filter is rewritten OR-ing the `uid=<arg>' with 1209# `cn=<arg>'; otherwise it is left as is. This could be 1210# useful, for instance, to allow apache's auth_ldap-1.4 1211# module to authenticate users with both `uid' and 1212# `cn', but only if the request comes from a possible 1213# `cn=Web auth,ou=admin,dc=home,dc=net' user. 1214rewriteContext searchFilter 1215rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)" 1216 "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}" 1217 ":I" 1218rewriteRule "[^,]+,ou=admin,dc=home,dc=net" 1219 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I" 1220rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":" 1221 1222# This example shows how to strip unwanted DN-valued 1223# attribute values from a search result; the first rule 1224# matches DN values below "ou=People,dc=example,dc=com"; 1225# in case of match the rewriting exits successfully. 1226# The second rule matches everything else and causes 1227# the value to be rejected. 1228rewriteContext searchResult 1229rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@" 1230rewriteRule ".*" "" "#" 1231.fi 1232.SH "LDAP Proxy resolution (a possible evolution of slapd\-ldap(5)):" 1233In case the rewritten DN is an LDAP URI, the operation is initiated 1234towards the host[:port] indicated in the uri, if it does not refer 1235to the local server. 1236E.g.: 1237.LP 1238.nf 1239 rewriteRule '^cn=root,.*' '%0' 'G{3}' 1240 rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@' 1241 rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@' 1242 rewriteRule '.*' 'ldap://ldap3.my.org/%0' ':@' 1243.fi 1244.LP 1245(Rule 1 is simply there to illustrate the `G{n}' action; it could have 1246been written: 1247.LP 1248.nf 1249 rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@' 1250.fi 1251.LP 1252with the advantage of saving one rewrite pass ...) 1253 1254.SH ACCESS CONTROL 1255The 1256.B meta 1257backend does not honor all ACL semantics as described in 1258.BR slapd.access (5). 1259In general, access checking is delegated to the remote server(s). 1260Only 1261.B read (=r) 1262access to the 1263.B entry 1264pseudo-attribute and to the other attribute values of the entries 1265returned by the 1266.B search 1267operation is honored, which is performed by the frontend. 1268 1269.SH PROXY CACHE OVERLAY 1270The proxy cache overlay 1271allows caching of LDAP search requests (queries) in a local database. 1272See 1273.BR slapo\-pcache (5) 1274for details. 1275 1276.SH DEPRECATED STATEMENTS 1277The following statements have been deprecated and should no longer be used. 1278 1279.TP 1280.B pseudorootdn "<substitute DN in case of rootdn bind>" 1281Use 1282.B idassert\-bind 1283instead. 1284 1285.TP 1286.B pseudorootpw "<substitute password in case of rootdn bind>" 1287Use 1288.B idassert\-bind 1289instead. 1290 1291 1292 1293.SH FILES 1294.TP 1295/etc/openldap/slapd.conf 1296default slapd configuration file 1297.SH SEE ALSO 1298.BR slapd.conf (5), 1299.BR slapd\-ldap (5), 1300.BR slapo\-pcache (5), 1301.BR slapd (8), 1302.BR regex (7), 1303.BR re_format (7). 1304.SH AUTHOR 1305Pierangelo Masarati, based on back-ldap by Howard Chu 1306