1.lf 1 stdin 2.TH SLAPD-LDAP 5 "2020/04/28" "OpenLDAP 2.4.50" 3.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved. 4.\" Copying restrictions apply. See COPYRIGHT/LICENSE. 5.\" $OpenLDAP$ 6.SH NAME 7slapd\-ldap \- LDAP backend to slapd 8.SH SYNOPSIS 9/etc/openldap/slapd.conf 10.SH DESCRIPTION 11The LDAP backend to 12.BR slapd (8) 13is not an actual database; instead it acts as a proxy to forward incoming 14requests to another LDAP server. While processing requests it will also 15chase referrals, so that referrals are fully processed instead of being 16returned to the slapd client. 17 18Sessions that explicitly Bind to the back-ldap database always create their 19own private connection to the remote LDAP server. Anonymous sessions will 20share a single anonymous connection to the remote server. For sessions bound 21through other mechanisms, all sessions with the same DN will share the 22same connection. This connection pooling strategy can enhance the proxy's 23efficiency by reducing the overhead of repeatedly making/breaking multiple 24connections. 25 26The ldap database can also act as an information service, i.e. the identity 27of locally authenticated clients is asserted to the remote server, possibly 28in some modified form. 29For this purpose, the proxy binds to the remote server with some 30administrative identity, and, if required, authorizes the asserted identity. 31See the 32.IR idassert\- * 33rules below. 34The administrative identity of the proxy, on the remote server, must be 35allowed to authorize by means of appropriate 36.B authzTo 37rules; see 38.BR slapd.conf (5) 39for details. 40 41The proxy instance of 42.BR slapd (8) 43must contain schema information for the attributes and objectClasses 44used in filters, request DNs and request-related data in general. 45It should also contain schema information for the data returned 46by the proxied server. 47It is the responsibility of the proxy administrator to keep the schema 48of the proxy lined up with that of the proxied server. 49 50.LP 51Note: When looping back to the same instance of 52.BR slapd (8), 53each connection requires a new thread; as a consequence, 54.BR slapd (8) 55must be compiled with thread support, and the \fBthreads\fP parameter 56may need some tuning; in those cases, one may consider using 57.BR slapd\-relay (5) 58instead, which performs the relayed operation 59internally and thus reuses the same connection. 60 61.SH CONFIGURATION 62These 63.B slapd.conf 64options apply to the LDAP backend database. 65That is, they must follow a "database ldap" line and come before any 66subsequent "backend" or "database" lines. 67Other database options are described in the 68.BR slapd.conf (5) 69manual page. 70 71.LP 72Note: In early versions of back-ldap it was recommended to always set 73.LP 74.RS 75.nf 76lastmod off 77.fi 78.RE 79.LP 80for 81.B ldap 82and 83.B meta 84databases. 85This was required because operational attributes related to entry creation 86and modification should not be proxied, as they could be mistakenly written 87to the target server(s), generating an error. 88The current implementation automatically sets lastmod to \fBoff\fP, 89so its use is redundant and should be omitted. 90 91.TP 92.B uri <ldapurl> 93LDAP server to use. Multiple URIs can be set in a single 94.B ldapurl 95argument, resulting in the underlying library automatically 96calling the first server of the list that responds, e.g. 97 98\fBuri "ldap://host/ ldap://backup\-host/"\fP 99 100The URI list is space- or comma-separated. 101Whenever the server that responds is not the first one in the list, 102the list is rearranged and the responsive server is moved to the head, 103so that it will be first contacted the next time a connection 104needs to be created. 105.HP 106.hy 0 107.B acl\-bind 108.B bindmethod=simple|sasl [binddn=<simple DN>] [credentials=<simple password>] 109.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] 110.B [authcId=<authentication ID>] [authzId=<authorization ID>] 111.B [starttls=no|yes|critical] 112.B [tls_cert=<file>] 113.B [tls_key=<file>] 114.B [tls_cacert=<file>] 115.B [tls_cacertdir=<path>] 116.B [tls_reqcert=never|allow|try|demand] 117.B [tls_cipher_suite=<ciphers>] 118.B [tls_protocol_min=<major>[.<minor>]] 119.B [tls_crlcheck=none|peer|all] 120.RS 121Allows one to define the parameters of the authentication method that is 122internally used by the proxy to collect info related to access control, 123and whenever an operation occurs with the identity of the rootdn 124of the LDAP proxy database. 125The identity defined by this directive, according to the properties 126associated to the authentication method, is supposed to have read access 127on the target server to attributes used on the proxy for ACL checking. 128 129There is no risk of giving away such values; they are only used to 130check permissions. 131The default is to use 132.BR simple 133bind, with empty \fIbinddn\fP and \fIcredentials\fP, 134which means that the related operations will be performed anonymously. 135If not set, and if \fBidassert\-bind\fP is defined, this latter identity 136is used instead. See \fBidassert\-bind\fP for details. 137 138The connection between the proxy database and the remote server 139associated to this identity is cached regardless of the lifespan 140of the client-proxy connection that first established it. 141 142.B This identity is not implicitly used by the proxy 143.B when the client connects anonymously. 144The 145.B idassert\-bind 146feature, instead, in some cases can be crafted to implement that behavior, 147which is \fIintrinsically unsafe and should be used with extreme care\fP. 148This directive obsoletes 149.BR acl\-authcDN , 150and 151.BR acl\-passwd . 152 153The TLS settings default to the same as the main slapd TLS settings, 154except for 155.B tls_reqcert 156which defaults to "demand". 157.RE 158 159.TP 160.B cancel {ABANDON|ignore|exop[\-discover]} 161Defines how to handle operation cancellation. 162By default, 163.B abandon 164is invoked, so the operation is abandoned immediately. 165If set to 166.BR ignore , 167no action is taken and any further response is ignored; this may result 168in further response messages to be queued for that connection, so it is 169recommended that long lasting connections are timed out either by 170.I idle\-timeout 171or 172.IR conn\-ttl , 173so that resources eventually get released. 174If set to 175.BR exop , 176a 177.I cancel 178operation (RFC 3909) is issued, resulting in the cancellation 179of the current operation; the 180.I cancel 181operation waits for remote server response, so its use 182may not be recommended. 183If set to 184.BR exop\-discover , 185support of the 186.I cancel 187extended operation is detected by reading the remote server's root DSE. 188 189.TP 190.B chase\-referrals {YES|no} 191enable/disable automatic referral chasing, which is delegated to the 192underlying libldap, with rebinding eventually performed if the 193\fBrebind\-as\-user\fP directive is used. The default is to chase referrals. 194 195.TP 196.B conn\-ttl <time> 197This directive causes a cached connection to be dropped and recreated 198after a given ttl, regardless of being idle or not. 199 200.TP 201.B idassert\-authzFrom <authz-regexp> 202if defined, selects what 203.I local 204identities are authorized to exploit the identity assertion feature. 205The string 206.B <authz-regexp> 207mostly follows the rules defined for the 208.I authzFrom 209attribute. 210See 211.BR slapd.conf (5), 212section related to 213.BR authz\-policy , 214for details on the syntax of this field. This parameter differs from 215the documented behavior in relation to the meaning of *, which in this 216case allows anonymous rather than denies. 217 218.HP 219.hy 0 220.B idassert\-bind 221.B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>] 222.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>] 223.B [authcId=<authentication ID>] [authzId=<authorization ID>] 224.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>] 225.B [starttls=no|yes|critical] 226.B [tls_cert=<file>] 227.B [tls_key=<file>] 228.B [tls_cacert=<file>] 229.B [tls_cacertdir=<path>] 230.B [tls_reqcert=never|allow|try|demand] 231.B [tls_cipher_suite=<ciphers>] 232.B [tls_protocol_min=<version>] 233.B [tls_crlcheck=none|peer|all] 234.RS 235Allows one to define the parameters of the authentication method that is 236internally used by the proxy to authorize connections that are 237authenticated by other databases. 238Direct binds are always proxied without any idassert handling. 239 240The identity defined by this directive, according to the properties 241associated to the authentication method, is supposed to have auth access 242on the target server to attributes used on the proxy for authentication 243and authorization, and to be allowed to authorize the users. 244This requires to have 245.B proxyAuthz 246privileges on a wide set of DNs, e.g. 247.BR authzTo=dn.subtree:"" , 248and the remote server to have 249.B authz\-policy 250set to 251.B to 252or 253.BR both . 254See 255.BR slapd.conf (5) 256for details on these statements and for remarks and drawbacks about 257their usage. 258The supported bindmethods are 259 260\fBnone|simple|sasl\fP 261 262where 263.B none 264is the default, i.e. no \fIidentity assertion\fP is performed. 265 266The authz parameter is used to instruct the SASL bind to exploit 267.B native 268SASL authorization, if available; since connections are cached, 269this should only be used when authorizing with a fixed identity 270(e.g. by means of the 271.B authzDN 272or 273.B authzID 274parameters). 275Otherwise, the default 276.B proxyauthz 277is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370) 278is added to all operations. 279 280The supported modes are: 281 282\fB<mode> := {legacy|anonymous|none|self}\fP 283 284If 285.B <mode> 286is not present, and 287.B authzId 288is given, the proxy always authorizes that identity. 289.B <authorization ID> 290can be 291 292\fBu:<user>\fP 293 294\fB[dn:]<DN>\fP 295 296The former is supposed to be expanded by the remote server according 297to the authz rules; see 298.BR slapd.conf (5) 299for details. 300In the latter case, whether or not the 301.B dn: 302prefix is present, the string must pass DN validation and normalization. 303 304The default mode is 305.BR legacy , 306which implies that the proxy will either perform a simple bind as the 307.I authcDN 308or a SASL bind as the 309.I authcID 310and assert the client's identity when it is not anonymous. 311The other modes imply that the proxy will always either perform a simple bind 312as the 313.IR authcDN 314or a SASL bind as the 315.IR authcID , 316unless restricted by 317.BR idassert\-authzFrom 318rules (see below), in which case the operation will fail; 319eventually, it will assert some other identity according to 320.BR <mode> . 321Other identity assertion modes are 322.BR anonymous 323and 324.BR self , 325which respectively mean that the 326.I empty 327or the 328.IR client 's 329identity 330will be asserted; 331.BR none , 332which means that no proxyAuthz control will be used, so the 333.I authcDN 334or the 335.I authcID 336identity will be asserted. 337For all modes that require the use of the 338.I proxyAuthz 339control, on the remote server the proxy identity must have appropriate 340.I authzTo 341permissions, or the asserted identities must have appropriate 342.I authzFrom 343permissions. Note, however, that the ID assertion feature is mostly 344useful when the asserted identities do not exist on the remote server. 345 346Flags can be 347 348\fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP 349 350When the 351.B override 352flag is used, identity assertion takes place even when the database 353is authorizing for the identity of the client, i.e. after binding 354with the provided identity, and thus authenticating it, the proxy 355performs the identity assertion using the configured identity and 356authentication method. 357 358When the 359.B prescriptive 360flag is used (the default), operations fail with 361\fIinappropriateAuthentication\fP 362for those identities whose assertion is not allowed by the 363.B idassert\-authzFrom 364patterns. 365If the 366.B non\-prescriptive 367flag is used, operations are performed anonymously for those identities 368whose assertion is not allowed by the 369.B idassert\-authzFrom 370patterns. 371 372When the 373.B proxy\-authz\-non\-critical 374flag is used (the default), the proxyAuthz control is not marked as critical, 375in violation of RFC 4370. Use of 376.B proxy\-authz\-critical 377is recommended. 378 379The TLS settings default to the same as the main slapd TLS settings, 380except for 381.B tls_reqcert 382which defaults to "demand". 383 384The identity associated to this directive is also used for privileged 385operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP 386is not. See \fBacl\-bind\fP for details. 387 388This directive obsoletes 389.BR idassert\-authcDN , 390.BR idassert\-passwd , 391.BR idassert\-mode , 392and 393.BR idassert\-method . 394.RE 395 396.TP 397.B idassert-passthru <authz-regexp> 398if defined, selects what 399.I local 400identities bypass the identity assertion feature. 401Those identities need to be known by the remote host. 402The string 403.B <authz-regexp> 404follows the rules defined for the 405.I authzFrom 406attribute. 407See 408.BR slapd.conf (5), 409section related to 410.BR authz\-policy , 411for details on the syntax of this field. 412 413 414.TP 415.B idle\-timeout <time> 416This directive causes a cached connection to be dropped an recreated 417after it has been idle for the specified time. 418 419.TP 420.B keepalive <idle>:<probes>:<interval> 421The 422.B keepalive 423parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP 424used to check whether a socket is alive; 425.I idle 426is the number of seconds a connection needs to remain idle before TCP 427starts sending keepalive probes; 428.I probes 429is the maximum number of keepalive probes TCP should send before dropping 430the connection; 431.I interval 432is interval in seconds between individual keepalive probes. 433Only some systems support the customization of these values; 434the 435.B keepalive 436parameter is ignored otherwise, and system-wide settings are used. 437 438.TP 439.B network\-timeout <time> 440Sets the network timeout value after which 441.BR poll (2)/ select (2) 442following a 443.BR connect (2) 444returns in case of no activity. 445The value is in seconds, and it can be specified as for 446.BR idle\-timeout . 447 448.TP 449.B norefs <NO|yes> 450If 451.BR yes , 452do not return search reference responses. 453By default, they are returned unless request is LDAPv2. 454 455.TP 456.B omit-unknown-schema <NO|yes> 457If 458.BR yes , 459do not return objectClasses or attributes that are not known to the local server. 460The default is to return all schema elements. 461 462.TP 463.B noundeffilter <NO|yes> 464If 465.BR yes , 466return success instead of searching if a filter is undefined or contains 467undefined portions. 468By default, the search is propagated after replacing undefined portions 469with 470.BR (!(objectClass=*)) , 471which corresponds to the empty result set. 472 473.TP 474.B onerr {CONTINUE|stop} 475This directive allows one to select the behavior in case an error is returned 476by the remote server during a search. 477The default, \fBcontinue\fP, consists in returning success. 478If the value is set to \fBstop\fP, the error is returned to the client. 479 480.TP 481.B protocol\-version {0,2,3} 482This directive indicates what protocol version must be used to contact 483the remote server. 484If set to 0 (the default), the proxy uses the same protocol version 485used by the client, otherwise the requested protocol is used. 486The proxy returns \fIunwillingToPerform\fP if an operation that is 487incompatible with the requested protocol is attempted. 488 489.TP 490.B proxy\-whoami {NO|yes} 491Turns on proxying of the WhoAmI extended operation. If this option is 492given, back-ldap will replace slapd's original WhoAmI routine with its 493own. On slapd sessions that were authenticated by back-ldap, the WhoAmI 494request will be forwarded to the remote LDAP server. Other sessions will 495be handled by the local slapd, as before. This option is mainly useful 496in conjunction with Proxy Authorization. 497 498.TP 499.B quarantine <interval>,<num>[;<interval>,<num>[...]] 500Turns on quarantine of URIs that returned 501.IR LDAP_UNAVAILABLE , 502so that an attempt to reconnect only occurs at given intervals instead 503of any time a client requests an operation. 504The pattern is: retry only after at least 505.I interval 506seconds elapsed since last attempt, for exactly 507.I num 508times; then use the next pattern. 509If 510.I num 511for the last pattern is "\fB+\fP", it retries forever; otherwise, 512no more retries occur. 513The process can be restarted by resetting the \fIolcDbQuarantine\fP 514attribute of the database entry in the configuration backend. 515 516.TP 517.B rebind\-as\-user {NO|yes} 518If this option is given, the client's bind credentials are remembered 519for rebinds, when trying to re-establish a broken connection, 520or when chasing a referral, if 521.B chase\-referrals 522is set to 523.IR yes . 524 525.TP 526.B session\-tracking\-request {NO|yes} 527Adds session tracking control for all requests. 528The client's IP and hostname, and the identity associated to each request, 529if known, are sent to the remote server for informational purposes. 530This directive is incompatible with setting \fIprotocol\-version\fP to 2. 531 532.TP 533.B single\-conn {NO|yes} 534Discards current cached connection when the client rebinds. 535 536.TP 537.B t\-f\-support {NO|yes|discover} 538enable if the remote server supports absolute filters 539(see \fIRFC 4526\fP for details). 540If set to 541.BR discover , 542support is detected by reading the remote server's root DSE. 543 544.TP 545.B timeout [<op>=]<val> [...] 546This directive allows one to set per-operation timeouts. 547Operations can be 548 549\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP 550 551The overall duration of the \fBsearch\fP operation is controlled either 552by the \fBtimelimit\fP parameter or by server-side enforced 553time limits (see \fBtimelimit\fP and \fBlimits\fP in 554.BR slapd.conf (5) 555for details). 556This \fBtimeout\fP parameter controls how long the target can be 557irresponsive before the operation is aborted. 558Timeout is meaningless for the remaining operations, 559\fBunbind\fP and \fBabandon\fP, which do not imply any response, 560while it is not yet implemented in currently supported \fBextended\fP 561operations. 562If no operation is specified, the timeout \fBval\fP affects all 563supported operations. 564 565Note: if the timelimit is exceeded, the operation is cancelled 566(according to the \fBcancel\fP directive); 567the protocol does not provide any means to rollback operations, 568so the client will not be notified about the result of the operation, 569which may eventually succeeded or not. 570In case the timeout is exceeded during a bind operation, the connection 571is destroyed, according to RFC4511. 572 573Note: in some cases, this backend may issue binds prior 574to other operations (e.g. to bind anonymously or with some prescribed 575identity according to the \fBidassert\-bind\fP directive). 576In this case, the timeout of the operation that resulted in the bind 577is used. 578 579.HP 580.hy 0 581.B tls {none|[try\-]start|[try\-]propagate|ldaps} 582.B [starttls=no] 583.B [tls_cert=<file>] 584.B [tls_key=<file>] 585.B [tls_cacert=<file>] 586.B [tls_cacertdir=<path>] 587.B [tls_reqcert=never|allow|try|demand] 588.B [tls_cipher_suite=<ciphers>] 589.B [tls_crlcheck=none|peer|all] 590.RS 591Specify TLS settings for regular connections. 592 593The first parameter only applies to \fBldap://\fP connections and so 594at the moment, \fBnone\fP and \fBldaps\fP are equivalent. 595 596With \fBpropagate\fP, the proxy issues StartTLS operation only if 597the original connection has a TLS layer set up. 598The \fBtry\-\fP prefix instructs the proxy to continue operations 599if the StartTLS operation failed; its use is \fBnot\fP recommended. 600 601The TLS settings default to the same as the main slapd TLS settings, 602except for 603.B tls_reqcert 604which defaults to "demand" and 605.B starttls 606which is overshadowed by the first keyword and thus ignored. 607.RE 608 609.TP 610.B use\-temporary\-conn {NO|yes} 611when set to 612.BR yes , 613create a temporary connection whenever competing with other threads 614for a shared one; otherwise, wait until the shared connection is available. 615 616.SH BACKWARD COMPATIBILITY 617The LDAP backend has been heavily reworked between releases 2.2 and 2.3, 618and subsequently between 2.3 and 2.4. 619As a side-effect, some of the traditional directives have been 620deprecated and should be no longer used, as they might disappear 621in future releases. 622 623.TP 624.B acl\-authcDN "<administrative DN for access control purposes>" 625Formerly known as the 626.BR binddn , 627it is the DN that is used to query the target server for acl checking; 628it is supposed to have read access on the target server to attributes used 629on the proxy for acl checking. 630There is no risk of giving away such values; they are only used to 631check permissions. 632 633.B The acl\-authcDN identity is by no means implicitly used by the proxy 634.B when the client connects anonymously. 635The 636.B idassert\-* 637feature can be used (at own risk) for that purpose instead. 638 639This directive is obsoleted by the 640.B binddn 641arg of 642.B acl\-bind 643when \fIbindmethod\fP=\fBsimple\fP, and will be dismissed in the future. 644 645.TP 646.B acl\-passwd <password> 647Formerly known as the 648.BR bindpw , 649it is the password used with the above 650.B acl\-authcDN 651directive. 652This directive is obsoleted by the 653.B credentials 654arg of 655.B acl\-bind 656when \fIbindmethod\fP=\fBsimple\fP, and will be dismissed in the future. 657 658.TP 659.B idassert\-authcDN "<administrative DN for proxyAuthz purposes>" 660DN which is used to propagate the client's identity to the target 661by means of the proxyAuthz control when the client does not 662belong to the DIT fragment that is being proxied by back-ldap. 663This directive is obsoleted by the 664.B binddn 665arg of 666.BR idassert\-bind 667when \fIbindmethod\fP=\fBsimple\fP, and will be dismissed in the future. 668 669.TP 670.B idassert\-passwd <password> 671Password used with the 672.B idassert\-authcDN 673above. 674This directive is obsoleted by the 675.B crendentials 676arg of 677.B idassert\-bind 678when \fIbindmethod\fP=\fBsimple\fP, and will be dismissed in the future. 679 680.TP 681.B idassert\-mode <mode> [<flags>] 682defines what type of 683.I identity assertion 684is used. 685This directive is obsoleted by the 686.B mode 687arg of 688.BR idassert\-bind , 689and will be dismissed in the future. 690 691.TP 692.B idassert\-method <method> [<saslargs>] 693This directive is obsoleted by the 694.B bindmethod 695arg of 696.BR idassert\-bind , 697and will be dismissed in the future. 698 699.TP 700.B port <port> 701this directive is no longer supported. Use the 702.B uri 703directive as described above. 704 705.TP 706.B server <hostname[:port]> 707this directive is no longer supported. Use the 708.B uri 709directive as described above. 710 711.TP 712.B suffixmassage, map, rewrite* 713These directives are no longer supported by back-ldap; their 714functionality is now delegated to the 715.B rwm 716overlay. Essentially, add a statement 717 718.B overlay rwm 719 720first, and prefix all rewrite/map statements with 721.B rwm\- 722to obtain the original behavior. 723See 724.BR slapo\-rwm (5) 725for details. 726.\" However, to ease update from existing configurations, back-ldap still 727.\" recognizes them and automatically instantiates the 728.\" .B rwm 729.\" overlay if available and not instantiated yet. 730.\" This behavior may change in the future. 731 732.SH ACCESS CONTROL 733The 734.B ldap 735backend does not honor all ACL semantics as described in 736.BR slapd.access (5). 737In general, access checking is delegated to the remote server(s). 738Only 739.B read (=r) 740access to the 741.B entry 742pseudo-attribute and to the other attribute values of the entries 743returned by the 744.B search 745operation is honored, which is performed by the frontend. 746 747.SH OVERLAYS 748The LDAP backend provides basic proxying functionalities to many overlays. 749The 750.B chain 751overlay, described in 752.BR slapo\-chain (5), 753and the 754.B translucent 755overlay, described in 756.BR slapo\-translucent (5), 757deserve a special mention. 758 759Conversely, there are many overlays that are best used in conjunction 760with the LDAP backend. 761The 762.B proxycache 763overlay allows caching of LDAP search requests (queries) 764in a local database. 765See 766.BR slapo\-pcache (5) 767for details. 768The 769.B rwm 770overlay provides DN rewrite and attribute/objectClass mapping 771capabilities to the underlying database. 772See 773.BR slapo\-rwm (5) 774for details. 775 776.SH FILES 777.TP 778/etc/openldap/slapd.conf 779default slapd configuration file 780.SH SEE ALSO 781.BR slapd.conf (5), 782.BR slapd\-config (5), 783.BR slapd\-meta (5), 784.BR slapo\-chain (5), 785.BR slapo\-pcache (5), 786.BR slapo\-rwm (5), 787.BR slapo\-translucent (5), 788.BR slapd (8), 789.BR ldap (3). 790.SH AUTHOR 791Howard Chu, with enhancements by Pierangelo Masarati 792