1SLAPD-LDAP(5) File Formats Manual SLAPD-LDAP(5)
2
6 slapd-ldap - LDAP backend to slapd
7
9 /etc/openldap/slapd.conf
10
12 The LDAP backend to slapd(8) is not an actual database; instead it acts
13 as a proxy to forward incoming requests to another LDAP server. While
14 processing requests it will also chase referrals, so that referrals are
15 fully processed instead of being returned to the slapd client.
16 Sessions that explicitly Bind to the back-ldap database always create
18 their own private connection to the remote LDAP server. Anonymous ses‐
19 sions will share a single anonymous connection to the remote server.
20 For sessions bound through other mechanisms, all sessions with the same
21 DN will share the same connection. This connection pooling strategy can
22 enhance the proxy's efficiency by reducing the overhead of repeatedly
23 making/breaking multiple connections.
24 The ldap database can also act as an information service, i.e. the
26 identity of locally authenticated clients is asserted to the remote
27 server, possibly in some modified form. For this purpose, the proxy
28 binds to the remote server with some administrative identity, and, if
29 required, authorizes the asserted identity. See the idassert-* rules
30 below. The administrative identity of the proxy, on the remote server,
31 must be allowed to authorize by means of appropriate authzTo rules; see
32 slapd.conf(5) for details.
33 The proxy instance of slapd(8) must contain schema information for the
35 attributes and objectClasses used in filters, request DNs and request-
36 related data in general. It should also contain schema information for
37 the data returned by the proxied server. It is the responsibility of
38 the proxy administrator to keep the schema of the proxy lined up with
39 that of the proxied server.
40 Note: When looping back to the same instance of slapd(8), each connec‐
43 tion requires a new thread; as a consequence, slapd(8) must be compiled
44 with thread support, and the threads parameter may need some tuning; in
45 those cases, one may consider using slapd-relay(5) instead, which per‐
46 forms the relayed operation internally and thus reuses the same connec‐
47 tion.
48
51 These slapd.conf options apply to the LDAP backend database. That is,
52 they must follow a "database ldap" line and come before any subsequent
53 "backend" or "database" lines. Other database options are described in
54 the slapd.conf(5) manual page.
55 Note: In early versions of back-ldap it was recommended to always set
58 lastmod off
60 for ldap and meta databases. This was required because operational at‐
62 tributes related to entry creation and modification should not be prox‐
63 ied, as they could be mistakenly written to the target server(s), gen‐
64 erating an error. The current implementation automatically sets last‐
65 mod to off, so its use is redundant and should be omitted.
66 uri <ldapurl>
69 LDAP server to use. Multiple URIs can be set in a single lda‐
70 purl argument, resulting in the underlying library automatically
71 calling the first server of the list that responds, e.g.
72 uri "ldap://host/ ldap://backup-host/"
74 The URI list is space- or comma-separated. Whenever the server
76 that responds is not the first one in the list, the list is re‐
77 arranged and the responsive server is moved to the head, so that
78 it will be first contacted the next time a connection needs to
79 be created.
80 acl-bind bindmethod=simple|sasl [binddn=<simple DN>]
82 [credentials=<simple password>] [saslmech=<SASL mech>]
83 [secprops=<properties>] [realm=<realm>] [authcId=<authentication
84 ID>] [authzId=<authorization ID>] [starttls=no|yes|critical]
85 [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>]
86 [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand]
87 [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
88 [tls_ecname=<names>] [tls_protocol_min=<major>[.<minor>]]
89 [tls_crlcheck=none|peer|all]
90 Allows one to define the parameters of the authentication method
91 that is internally used by the proxy to collect info related to
92 access control, and whenever an operation occurs with the
93 identity of the rootdn of the LDAP proxy database. The identity
94 defined by this directive, according to the properties
95 associated to the authentication method, is supposed to have
96 read access on the target server to attributes used on the proxy
97 for ACL checking.
98 There is no risk of giving away such values; they are only used
100 to check permissions. The default is to use simple bind, with
101 empty binddn and credentials, which means that the related
102 operations will be performed anonymously. If not set, and if
103 idassert-bind is defined, this latter identity is used instead.
104 See idassert-bind for details.
105 The connection between the proxy database and the remote server
107 associated to this identity is cached regardless of the lifespan
108 of the client-proxy connection that first established it.
109 This identity is not implicitly used by the proxy when the
111 client connects anonymously. The idassert-bind feature,
112 instead, in some cases can be crafted to implement that
113 behavior, which is intrinsically unsafe and should be used with
114 extreme care. This directive obsoletes acl-authcDN, and
115 acl-passwd.
116 The TLS settings default to the same as the main slapd TLS
118 settings, except for tls_reqcert which defaults to "demand", and
119 tls_reqsan which defaults to "allow".
120 cancel {ABANDON|ignore|exop[-discover]}
123 Defines how to handle operation cancellation. By default,
124 abandon is invoked, so the operation is abandoned immediately.
125 If set to ignore, no action is taken and any further response is
126 ignored; this may result in further response messages to be
127 queued for that connection, so it is recommended that long
128 lasting connections are timed out either by idle-timeout or
129 conn-ttl, so that resources eventually get released. If set to
130 exop, a cancel operation (RFC 3909) is issued, resulting in the
131 cancellation of the current operation; the cancel operation
132 waits for remote server response, so its use may not be
133 recommended. If set to exop-discover, support of the cancel
134 extended operation is detected by reading the remote server's
135 root DSE.
136 chase-referrals {YES|no}
139 enable/disable automatic referral chasing, which is delegated to
140 the underlying libldap, with rebinding eventually performed if
141 the rebind-as-user directive is used. The default is to chase
142 referrals.
143 conn-ttl <time>
146 This directive causes a cached connection to be dropped and
147 recreated after a given ttl, regardless of being idle or not.
148 idassert-authzFrom <authz-regexp>
151 if defined, selects what local identities are authorized to
152 exploit the identity assertion feature. The string <authz-
153 regexp> mostly follows the rules defined for the authzFrom
154 attribute. See slapd.conf(5), section related to authz-policy,
155 for details on the syntax of this field. This parameter differs
156 from the documented behavior in relation to the meaning of *,
157 which in this case allows anonymous rather than denies.
158 idassert-bind bindmethod=none|simple|sasl [binddn=<simple DN>]
161 [credentials=<simple password>] [saslmech=<SASL mech>]
162 [secprops=<properties>] [realm=<realm>] [authcId=<authentication
163 ID>] [authzId=<authorization ID>] [authz={native|proxyauthz}]
164 [mode=<mode>] [flags=<flags>] [starttls=no|yes|critical]
165 [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>]
166 [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand]
167 [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
168 [tls_ecname=<names>] [tls_protocol_min=<version>]
169 [tls_crlcheck=none|peer|all]
170 Allows one to define the parameters of the authentication method
171 that is internally used by the proxy to authorize connections
172 that are authenticated by other databases. Direct binds are
173 always proxied without any idassert handling.
174 The identity defined by this directive, according to the
176 properties associated to the authentication method, is supposed
177 to have auth access on the target server to attributes used on
178 the proxy for authentication and authorization, and to be
179 allowed to authorize the users. This requires to have
180 proxyAuthz privileges on a wide set of DNs, e.g.
181 authzTo=dn.subtree:"", and the remote server to have
182 authz-policy set to to or both. See slapd.conf(5) for details
183 on these statements and for remarks and drawbacks about their
184 usage. The supported bindmethods are
185 none|simple|sasl
187 where none is the default, i.e. no identity assertion is
189 performed.
190 The authz parameter is used to instruct the SASL bind to exploit
192 native SASL authorization, if available; since connections are
193 cached, this should only be used when authorizing with a fixed
194 identity (e.g. by means of the authzDN or authzID parameters).
195 Otherwise, the default proxyauthz is used, i.e. the proxyAuthz
196 control (Proxied Authorization, RFC 4370) is added to all
197 operations.
198 The supported modes are:
200 <mode> := {legacy|anonymous|none|self}
202 If <mode> is not present, and authzId is given, the proxy always
204 authorizes that identity. <authorization ID> can be
205 u:<user>
207 [dn:]<DN>
209 The former is supposed to be expanded by the remote server
211 according to the authz rules; see slapd.conf(5) for details. In
212 the latter case, whether or not the dn: prefix is present, the
213 string must pass DN validation and normalization.
214 The default mode is legacy, which implies that the proxy will
216 either perform a simple bind as the authcDN or a SASL bind as
217 the authcID and assert the client's identity when it is not
218 anonymous. The other modes imply that the proxy will always
219 either perform a simple bind as the authcDN or a SASL bind as
220 the authcID, unless restricted by idassert-authzFrom rules (see
221 below), in which case the operation will fail; eventually, it
222 will assert some other identity according to <mode>. Other
223 identity assertion modes are anonymous and self, which
224 respectively mean that the empty or the client's identity will
225 be asserted; none, which means that no proxyAuthz control will
226 be used, so the authcDN or the authcID identity will be
227 asserted. For all modes that require the use of the proxyAuthz
228 control, on the remote server the proxy identity must have
229 appropriate authzTo permissions, or the asserted identities must
230 have appropriate authzFrom permissions. Note, however, that the
231 ID assertion feature is mostly useful when the asserted
232 identities do not exist on the remote server.
233 Flags can be
235 override,[non-]prescriptive,proxy-authz-[non-]critical
237 When the override flag is used, identity assertion takes place
239 even when the database is authorizing for the identity of the
240 client, i.e. after binding with the provided identity, and thus
241 authenticating it, the proxy performs the identity assertion
242 using the configured identity and authentication method.
243 When the prescriptive flag is used (the default), operations
245 fail with inappropriateAuthentication for those identities whose
246 assertion is not allowed by the idassert-authzFrom patterns. If
247 the non-prescriptive flag is used, operations are performed
248 anonymously for those identities whose assertion is not allowed
249 by the idassert-authzFrom patterns.
250 When the proxy-authz-non-critical flag is used (the default),
252 the proxyAuthz control is not marked as critical, in violation
253 of RFC 4370. Use of proxy-authz-critical is recommended.
254 The TLS settings default to the same as the main slapd TLS
256 settings, except for tls_reqcert which defaults to "demand", and
257 tls_reqsan which defaults to "allow".
258 The identity associated to this directive is also used for
260 privileged operations whenever idassert-bind is defined and
261 acl-bind is not. See acl-bind for details.
262 This directive obsoletes idassert-authcDN, idassert-passwd,
264 idassert-mode, and idassert-method.
265 idassert-passthru <authz-regexp>
268 if defined, selects what local identities bypass the identity
269 assertion feature. Those identities need to be known by the
270 remote host. The string <authz-regexp> follows the rules
271 defined for the authzFrom attribute. See slapd.conf(5), section
272 related to authz-policy, for details on the syntax of this
273 field.
274 idle-timeout <time>
278 This directive causes a cached connection to be dropped an
279 recreated after it has been idle for the specified time.
280 keepalive <idle>:<probes>:<interval>
283 The keepalive parameter sets the values of idle, probes, and
284 interval used to check whether a socket is alive; idle is the
285 number of seconds a connection needs to remain idle before TCP
286 starts sending keepalive probes; probes is the maximum number of
287 keepalive probes TCP should send before dropping the connection;
288 interval is interval in seconds between individual keepalive
289 probes. Only some systems support the customization of these
290 values; the keepalive parameter is ignored otherwise, and
291 system-wide settings are used.
292 network-timeout <time>
295 Sets the network timeout value after which poll(2)/select(2)
296 following a connect(2) returns in case of no activity. The
297 value is in seconds, and it can be specified as for
298 idle-timeout.
299 norefs <NO|yes>
302 If yes, do not return search reference responses. By default,
303 they are returned unless request is LDAPv2.
304 omit-unknown-schema <NO|yes>
307 If yes, do not return objectClasses or attributes that are not
308 known to the local server. The default is to return all schema
309 elements.
310 noundeffilter <NO|yes>
313 If yes, return success instead of searching if a filter is
314 undefined or contains undefined portions. By default, the
315 search is propagated after replacing undefined portions with
316 (!(objectClass=*)), which corresponds to the empty result set.
317 onerr {CONTINUE|stop}
320 This directive allows one to select the behavior in case an
321 error is returned by the remote server during a search. The
322 default, continue, consists in returning success. If the value
323 is set to stop, the error is returned to the client.
324 protocol-version {0,2,3}
327 This directive indicates what protocol version must be used to
328 contact the remote server. If set to 0 (the default), the proxy
329 uses the same protocol version used by the client, otherwise the
330 requested protocol is used. The proxy returns
331 unwillingToPerform if an operation that is incompatible with the
332 requested protocol is attempted.
333 proxy-whoami {NO|yes}
336 Turns on proxying of the WhoAmI extended operation. If this
337 option is given, back-ldap will replace slapd's original WhoAmI
338 routine with its own. On slapd sessions that were authenticated
339 by back-ldap, the WhoAmI request will be forwarded to the remote
340 LDAP server. Other sessions will be handled by the local slapd,
341 as before. This option is mainly useful in conjunction with
342 Proxy Authorization.
343 quarantine <interval>,<num>[;<interval>,<num>[...]]
346 Turns on quarantine of URIs that returned LDAP_UNAVAILABLE, so
347 that an attempt to reconnect only occurs at given intervals
348 instead of any time a client requests an operation. The pattern
349 is: retry only after at least interval seconds elapsed since
350 last attempt, for exactly num times; then use the next pattern.
351 If num for the last pattern is "+", it retries forever;
352 otherwise, no more retries occur. The process can be restarted
353 by resetting the olcDbQuarantine attribute of the database entry
354 in the configuration backend.
355 rebind-as-user {NO|yes}
358 If this option is given, the client's bind credentials are
359 remembered for rebinds, when trying to re-establish a broken
360 connection, or when chasing a referral, if chase-referrals is
361 set to yes.
362 session-tracking-request {NO|yes}
365 Adds session tracking control for all requests. The client's IP
366 and hostname, and the identity associated to each request, if
367 known, are sent to the remote server for informational purposes.
368 This directive is incompatible with setting protocol-version to
369 2.
370 single-conn {NO|yes}
373 Discards current cached connection when the client rebinds.
374 t-f-support {NO|yes|discover}
377 enable if the remote server supports absolute filters (see RFC
378 4526 for details). If set to discover, support is detected by
379 reading the remote server's root DSE.
380 timeout [<op>=]<val> [...]
383 This directive allows one to set per-operation timeouts.
384 Operations can be
385 <op> ::= bind, add, delete, modrdn, modify, compare, search
387 The overall duration of the search operation is controlled
389 either by the timelimit parameter or by server-side enforced
390 time limits (see timelimit and limits in slapd.conf(5) for
391 details). This timeout parameter controls how long the target
392 can be irresponsive before the operation is aborted. Timeout is
393 meaningless for the remaining operations, unbind and abandon,
394 which do not imply any response, while it is not yet implemented
395 in currently supported extended operations. If no operation is
396 specified, the timeout val affects all supported operations.
397 Note: if the timelimit is exceeded, the operation is cancelled
399 (according to the cancel directive); the protocol does not
400 provide any means to rollback operations, so the client will not
401 be notified about the result of the operation, which may
402 eventually succeeded or not. In case the timeout is exceeded
403 during a bind operation, the connection is destroyed, according
404 to RFC4511.
405 Note: in some cases, this backend may issue binds prior to other
407 operations (e.g. to bind anonymously or with some prescribed
408 identity according to the idassert-bind directive). In this
409 case, the timeout of the operation that resulted in the bind is
410 used.
411 tls {none|[try-]start|[try-]propagate|ldaps} [starttls=no]
414 [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>]
415 [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand]
416 [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
417 [tls_ecname=<names>] [tls_crlcheck=none|peer|all]
418 Specify TLS settings for regular connections.
419 The first parameter only applies to ldap:// connections and so
421 at the moment, none and ldaps are equivalent.
422 With propagate, the proxy issues StartTLS operation only if the
424 original connection has a TLS layer set up. The try- prefix
425 instructs the proxy to continue operations if the StartTLS
426 operation failed; its use is not recommended.
427 The TLS settings default to the same as the main slapd TLS
429 settings, except for tls_reqcert which defaults to "demand",
430 tls_reqsan which defaults to "allow", and starttls which is
431 overshadowed by the first keyword and thus ignored.
432 use-temporary-conn {NO|yes}
435 when set to yes, create a temporary connection whenever
436 competing with other threads for a shared one; otherwise, wait
437 until the shared connection is available.
438
441 The LDAP backend has been heavily reworked between releases 2.2 and
442 2.3, and subsequently between 2.3 and 2.4. As a side-effect, some of
443 the traditional directives have been deprecated and should be no longer
444 used, as they might disappear in future releases.
445 acl-authcDN <administrative DN for access control purposes>
448 Formerly known as the binddn, it is the DN that is used to query
449 the target server for acl checking; it is supposed to have read
450 access on the target server to attributes used on the proxy for
451 acl checking. There is no risk of giving away such values; they
452 are only used to check permissions.
453 The acl-authcDN identity is by no means implicitly used by the
455 proxy when the client connects anonymously. The idassert-*
456 feature can be used (at own risk) for that purpose instead.
457 This directive is obsoleted by the binddn arg of acl-bind when
459 bindmethod=simple, and will be dismissed in the future.
460 acl-passwd <password>
463 Formerly known as the bindpw, it is the password used with the
464 above acl-authcDN directive. This directive is obsoleted by the
465 credentials arg of acl-bind when bindmethod=simple, and will be
466 dismissed in the future.
467 idassert-authcDN <administrative DN for proxyAuthz purposes>
470 DN which is used to propagate the client's identity to the
471 target by means of the proxyAuthz control when the client does
472 not belong to the DIT fragment that is being proxied by back-
473 ldap. This directive is obsoleted by the binddn arg of
474 idassert-bind when bindmethod=simple, and will be dismissed in
475 the future.
476 idassert-passwd <password>
479 Password used with the idassert-authcDN above. This directive
480 is obsoleted by the crendentials arg of idassert-bind when
481 bindmethod=simple, and will be dismissed in the future.
482 idassert-mode <mode> [<flags>]
485 defines what type of identity assertion is used. This directive
486 is obsoleted by the mode arg of idassert-bind, and will be
487 dismissed in the future.
488 idassert-method <method> [<saslargs>]
491 This directive is obsoleted by the bindmethod arg of
492 idassert-bind, and will be dismissed in the future.
493 port <port>
496 this directive is no longer supported. Use the uri directive as
497 described above.
498 server <hostname[:port]>
501 this directive is no longer supported. Use the uri directive as
502 described above.
503 suffixmassage, map, rewrite*
506 These directives are no longer supported by back-ldap; their
507 functionality is now delegated to the rwm overlay. Essentially,
508 add a statement
509 overlay rwm
511 first, and prefix all rewrite/map statements with rwm- to obtain
513 the original behavior. See slapo-rwm(5) for details.
514
517 The ldap backend does not honor all ACL semantics as described in
518 slapd.access(5). In general, access checking is delegated to the
519 remote server(s). Only read (=r) access to the entry pseudo-attribute
520 and to the other attribute values of the entries returned by the search
521 operation is honored, which is performed by the frontend.
522
525 The LDAP backend provides basic proxying functionalities to many
526 overlays. The chain overlay, described in slapo-chain(5), and the
527 translucent overlay, described in slapo-translucent(5), deserve a
528 special mention.
529 Conversely, there are many overlays that are best used in conjunction
531 with the LDAP backend. The proxycache overlay allows caching of LDAP
532 search requests (queries) in a local database. See slapo-pcache(5) for
533 details. The rwm overlay provides DN rewrite and attribute/objectClass
534 mapping capabilities to the underlying database. See slapo-rwm(5) for
535 details.
536
539 /etc/openldap/slapd.conf
540 default slapd configuration file
541
543 slapd.conf(5), slapd-config(5), slapd-meta(5), slapo-chain(5),
544 slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
545
547 Howard Chu, with enhancements by Pierangelo Masarati
548OpenLDAP 2021/06/03 SLAPD-LDAP(5)