1SLAPD-LDAP(5) File Formats Manual SLAPD-LDAP(5)
2
3
4
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
17 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
25 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
34 The proxy instance of slapd(8) must contain schema information for the
35 attributes and objectClasses used in filters, request DN 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
41
42 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
49
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
56
57 Note: In early versions of back-ldap it was recommended to always set
58
59 lastmod off
60
61 for ldap and meta databases. This was required because operational
62 attributes related to entry creation and modification should not be
63 proxied, as they could be mistakenly written to the target server(s),
64 generating an error. The current implementation automatically sets
65 lastmod to off, so its use is redundant and should be omitted.
66
67
68 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 call the first server of the list that responds, e.g.
72
73 uri "ldap://host/ ldap://backup-host/"
74
75 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
77 rearranged and the responsive server is moved to the head, so
78 that it will be first contacted the next time a connection needs
79 be created.
80
81 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_ciphersuite=<ciphers>] [tls_protocol_min=<version>]
88 [tls_crlcheck=none|peer|all]
89 Allows to define the parameters of the authentication method
90 that is internally used by the proxy to collect info related to
91 access control, and whenever an operation occurs with the
92 identity of the rootdn of the LDAP proxy database. The identity
93 defined by this directive, according to the properties
94 associated to the authentication method, is supposed to have
95 read access on the target server to attributes used on the proxy
96 for ACL checking.
97
98 There is no risk of giving away such values; they are only used
99 to check permissions. The default is to use simple bind, with
100 empty binddn and credentials, which means that the related
101 operations will be performed anonymously. If not set, and if
102 idassert-bind is defined, this latter identity is used instead.
103 See idassert-bind for details.
104
105 The connection between the proxy database and the remote server
106 associated to this identity is cached regardless of the lifespan
107 of the client-proxy connection that first established it.
108
109 This identity is by no means implicitly used by the proxy when
110 the client connects anonymously. The idassert-bind feature,
111 instead, in some cases can be crafted to implement that
112 behavior, which is intrinsically unsafe and should be used with
113 extreme care. This directive obsoletes acl-authcDN, and
114 acl-passwd.
115
116 The TLS settings default to the same as the main slapd TLS
117 settings, except for tls_reqcert which defaults to "demand".
118
119
120 cancel {ABANDON|ignore|exop[-discover]}
121 Defines how to handle operation cancellation. By default,
122 abandon is invoked, so the operation is abandoned immediately.
123 If set to ignore, no action is taken and any further response is
124 ignored; this may result in further response messages to be
125 queued for that connection, so it is recommended that long
126 lasting connections are timed out either by idle-timeout or
127 conn-ttl, so that resources eventually get released. If set to
128 exop, a cancel operation (RFC 3909) is issued, resulting in the
129 cancellation of the current operation; the cancel operation
130 waits for remote server response, so its use may not be
131 recommended. If set to exop-discover, support of the cancel
132 extended operation is detected by reading the remote server's
133 root DSE.
134
135
136 chase-referrals {YES|no}
137 enable/disable automatic referral chasing, which is delegated to
138 the underlying libldap, with rebinding eventually performed if
139 the rebind-as-user directive is used. The default is to chase
140 referrals.
141
142
143 conn-ttl <time>
144 This directive causes a cached connection to be dropped an
145 recreated after a given ttl, regardless of being idle or not.
146
147
148 idassert-authzFrom <authz-regexp>
149 if defined, selects what local identities are authorized to
150 exploit the identity assertion feature. The string <authz-
151 regexp> follows the rules defined for the authzFrom attribute.
152 See slapd.conf(5), section related to authz-policy, for details
153 on the syntax of this field.
154
155
156 idassert-bind bindmethod=none|simple|sasl [binddn=<simple DN>]
157 [credentials=<simple password>] [saslmech=<SASL mech>]
158 [secprops=<properties>] [realm=<realm>] [authcId=<authentication
159 ID>] [authzId=<authorization ID>] [authz={native|proxyauthz}]
160 [mode=<mode>] [flags=<flags>] [starttls=no|yes|critical]
161 [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>]
162 [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand]
163 [tls_ciphersuite=<ciphers>] [tls_protocol_min=<version>]
164 [tls_crlcheck=none|peer|all]
165 Allows to define the parameters of the authentication method
166 that is internally used by the proxy to authorize connections
167 that are authenticated by other databases. The identity defined
168 by this directive, according to the properties associated to the
169 authentication method, is supposed to have auth access on the
170 target server to attributes used on the proxy for authentication
171 and authorization, and to be allowed to authorize the users.
172 This requires to have proxyAuthz privileges on a wide set of
173 DNs, e.g. authzTo=dn.subtree:"", and the remote server to have
174 authz-policy set to to or both. See slapd.conf(5) for details
175 on these statements and for remarks and drawbacks about their
176 usage. The supported bindmethods are
177
178 none|simple|sasl
179
180 where none is the default, i.e. no identity assertion is
181 performed.
182
183 The authz parameter is used to instruct the SASL bind to exploit
184 native SASL authorization, if available; since connections are
185 cached, this should only be used when authorizing with a fixed
186 identity (e.g. by means of the authzDN or authzID parameters).
187 Otherwise, the default proxyauthz is used, i.e. the proxyAuthz
188 control (Proxied Authorization, RFC 4370) is added to all
189 operations.
190
191 The supported modes are:
192
193 <mode> := {legacy|anonymous|none|self}
194
195 If <mode> is not present, and authzId is given, the proxy always
196 authorizes that identity. <authorization ID> can be
197
198 u:<user>
199
200 [dn:]<DN>
201
202 The former is supposed to be expanded by the remote server
203 according to the authz rules; see slapd.conf(5) for details. In
204 the latter case, whether or not the dn: prefix is present, the
205 string must pass DN validation and normalization.
206
207 The default mode is legacy, which implies that the proxy will
208 either perform a simple bind as the authcDN or a SASL bind as
209 the authcID and assert the client's identity when it is not
210 anonymous. Direct binds are always proxied. The other modes
211 imply that the proxy will always either perform a simple bind as
212 the authcDN or a SASL bind as the authcID, unless restricted by
213 idassert-authzFrom rules (see below), in which case the
214 operation will fail; eventually, it will assert some other
215 identity according to <mode>. Other identity assertion modes
216 are anonymous and self, which respectively mean that the empty
217 or the client's identity will be asserted; none, which means
218 that no proxyAuthz control will be used, so the authcDN or the
219 authcID identity will be asserted. For all modes that require
220 the use of the proxyAuthz control, on the remote server the
221 proxy identity must have appropriate authzTo permissions, or the
222 asserted identities must have appropriate authzFrom permissions.
223 Note, however, that the ID assertion feature is mostly useful
224 when the asserted identities do not exist on the remote server.
225
226 Flags can be
227
228 override,[non-]prescriptive,proxy-authz-[non-]critical
229
230 When the override flag is used, identity assertion takes place
231 even when the database is authorizing for the identity of the
232 client, i.e. after binding with the provided identity, and thus
233 authenticating it, the proxy performs the identity assertion
234 using the configured identity and authentication method.
235
236 When the prescriptive flag is used (the default), operations
237 fail with inappropriateAuthentication for those identities whose
238 assertion is not allowed by the idassert-authzFrom patterns. If
239 the non-prescriptive flag is used, operations are performed
240 anonymously for those identities whose assertion is not allowed
241 by the idassert-authzFrom patterns.
242
243 When the proxy-authz-non-critical flag is used (the default),
244 the proxyAuthz control is not marked as critical, in violation
245 of RFC 4370. Use of proxy-authz-critical is recommended.
246
247 The TLS settings default to the same as the main slapd TLS
248 settings, except for tls_reqcert which defaults to "demand".
249
250 The identity associated to this directive is also used for
251 privileged operations whenever idassert-bind is defined and
252 acl-bind is not. See acl-bind for details.
253
254 This directive obsoletes idassert-authcDN, idassert-passwd,
255 idassert-mode, and idassert-method.
256
257
258 idassert-passthru <authz-regexp>
259 if defined, selects what local identities bypass the identity
260 assertion feature. Those identities need to be known by the
261 remote host. The string <authz-regexp> follows the rules
262 defined for the authzFrom attribute. See slapd.conf(5), section
263 related to authz-policy, for details on the syntax of this
264 field.
265
266
267
268 idle-timeout <time>
269 This directive causes a cached connection to be dropped an
270 recreated after it has been idle for the specified time.
271
272
273 network-timeout <time>
274 Sets the network timeout value after which poll(2)/select(2)
275 following a connect(2) returns in case of no activity. The
276 value is in seconds, and it can be specified as for
277 idle-timeout.
278
279
280 norefs <NO|yes>
281 If yes, do not return search reference responses. By default,
282 they are returned unless request is LDAPv2.
283
284
285 noundeffilter <NO|yes>
286 If yes, return success instead of searching if a filter is
287 undefined or contains undefined portions. By default, the
288 search is propagated after replacing undefined portions with
289 (!(objectClass=*)), which corresponds to the empty result set.
290
291
292 protocol-version {0,2,3}
293 This directive indicates what protocol version must be used to
294 contact the remote server. If set to 0 (the default), the proxy
295 uses the same protocol version used by the client, otherwise the
296 requested protocol is used. The proxy returns
297 unwillingToPerform if an operation that is incompatible with the
298 requested protocol is attempted.
299
300
301 proxy-whoami {NO|yes}
302 Turns on proxying of the WhoAmI extended operation. If this
303 option is given, back-ldap will replace slapd's original WhoAmI
304 routine with its own. On slapd sessions that were authenticated
305 by back-ldap, the WhoAmI request will be forwarded to the remote
306 LDAP server. Other sessions will be handled by the local slapd,
307 as before. This option is mainly useful in conjunction with
308 Proxy Authorization.
309
310
311 quarantine <interval>,<num>[;<interval>,<num>[...]]
312 Turns on quarantine of URIs that returned LDAP_UNAVAILABLE, so
313 that an attempt to reconnect only occurs at given intervals
314 instead of any time a client requests an operation. The pattern
315 is: retry only after at least interval seconds elapsed since
316 last attempt, for exactly num times; then use the next pattern.
317 If num for the last pattern is "+", it retries forever;
318 otherwise, no more retries occur. The process can be restarted
319 by resetting the olcDbQuarantine attribute of the database entry
320 in the configuration backend.
321
322
323 rebind-as-user {NO|yes}
324 If this option is given, the client's bind credentials are
325 remembered for rebinds, when trying to re-establish a broken
326 connection, or when chasing a referral, if chase-referrals is
327 set to yes.
328
329
330 session-tracking-request {NO|yes}
331 Adds session tracking control for all requests. The client's IP
332 and hostname, and the identity associated to each request, if
333 known, are sent to the remote server for informational purposes.
334 This directive is incompatible with setting protocol-version to
335 2.
336
337
338 single-conn {NO|yes}
339 Discards current cached connection when the client rebinds.
340
341
342 t-f-support {NO|yes|discover}
343 enable if the remote server supports absolute filters (see
344 draft-zeilenga-ldap-t-f for details). If set to discover,
345 support is detected by reading the remote server's root DSE.
346
347
348 timeout [<op>=]<val> [...]
349 This directive allows to set per-operation timeouts. Operations
350 can be
351
352 <op> ::= bind, add, delete, modrdn, modify, compare, search
353
354 The overall duration of the search operation is controlled
355 either by the timelimit parameter or by server-side enforced
356 time limits (see timelimit and limits in slapd.conf(5) for
357 details). This timeout parameter controls how long the target
358 can be irresponsive before the operation is aborted. Timeout is
359 meaningless for the remaining operations, unbind and abandon,
360 which do not imply any response, while it is not yet implemented
361 in currently supported extended operations. If no operation is
362 specified, the timeout val affects all supported operations.
363
364 Note: if the timelimit is exceeded, the operation is cancelled
365 (according to the cancel directive); the protocol does not
366 provide any means to rollback operations, so the client will not
367 be notified about the result of the operation, which may
368 eventually succeeded or not. In case the timeout is exceeded
369 during a bind operation, the connection is destroyed, according
370 to RFC4511.
371
372 Note: in some cases, this backend may issue binds prior to other
373 operations (e.g. to bind anonymously or with some prescribed
374 identity according to the idassert-bind directive). In this
375 case, the timeout of the operation that resulted in the bind is
376 used.
377
378
379 tls {[try-]start|[try-]propagate|ldaps} [tls_cert=<file>]
380 [tls_key=<file>] [tls_cacert=<file>] [tls_cacertdir=<path>]
381 [tls_reqcert=never|allow|try|demand] [tls_ciphersuite=<ciphers>]
382 [tls_crlcheck=none|peer|all]
383 Specify the use of TLS when a regular connection is initialized.
384 The StartTLS extended operation will be used unless the URI
385 directive protocol scheme is ldaps://. In that case this keyword
386 may only be set to "ldaps" and the StartTLS operation will not
387 be used. propagate issues the StartTLS operation only if the
388 original connection did. The try- prefix instructs the proxy to
389 continue operations if the StartTLS operation failed; its use is
390 not recommended.
391
392 The TLS settings default to the same as the main slapd TLS
393 settings, except for tls_reqcert which defaults to "demand".
394
395
396 use-temporary-conn {NO|yes}
397 when set to yes, create a temporary connection whenever
398 competing with other threads for a shared one; otherwise, wait
399 until the shared connection is available.
400
401
403 The LDAP backend has been heavily reworked between releases 2.2 and
404 2.3, and subsequently between 2.3 and 2.4. As a side-effect, some of
405 the traditional directives have been deprecated and should be no longer
406 used, as they might disappear in future releases.
407
408
409 acl-authcDN <administrative DN for access control purposes>
410 Formerly known as the binddn, it is the DN that is used to query
411 the target server for acl checking; it is supposed to have read
412 access on the target server to attributes used on the proxy for
413 acl checking. There is no risk of giving away such values; they
414 are only used to check permissions.
415
416 The acl-authcDN identity is by no means implicitly used by the
417 proxy when the client connects anonymously. The idassert-*
418 feature can be used (at own risk) for that purpose instead.
419
420 This directive is obsoleted by the binddn arg of acl-bind when
421 bindmethod=simple, and will be dismissed in the future.
422
423
424 acl-passwd <password>
425 Formerly known as the bindpw, it is the password used with the
426 above acl-authcDN directive. This directive is obsoleted by the
427 credentials arg of acl-bind when bindmethod=simple, and will be
428 dismissed in the future.
429
430
431 idassert-authcDN <administrative DN for proxyAuthz purposes>
432 DN which is used to propagate the client's identity to the
433 target by means of the proxyAuthz control when the client does
434 not belong to the DIT fragment that is being proxied by back-
435 ldap. This directive is obsoleted by the binddn arg of
436 idassert-bind when bindmethod=simple, and will be dismissed in
437 the future.
438
439
440 idassert-passwd <password>
441 Password used with the idassert-authcDN above. This directive
442 is obsoleted by the crendentials arg of idassert-bind when
443 bindmethod=simple, and will be dismissed in the future.
444
445
446 idassert-mode <mode> [<flags>]
447 defines what type of identity assertion is used. This directive
448 is obsoleted by the mode arg of idassert-bind, and will be
449 dismissed in the future.
450
451
452 idassert-method <method> [<saslargs>]
453 This directive is obsoleted by the bindmethod arg of
454 idassert-bind, and will be dismissed in the future.
455
456
457 port <port>
458 this directive is no longer supported. Use the uri directive as
459 described above.
460
461
462 server <hostname[:port]>
463 this directive is no longer supported. Use the uri directive as
464 described above.
465
466
467 suffixmassage, map, rewrite*
468 These directives are no longer supported by back-ldap; their
469 functionality is now delegated to the rwm overlay. Essentially,
470 add a statement
471
472 overlay rwm
473
474 first, and prefix all rewrite/map statements with rwm- to obtain
475 the original behavior. See slapo-rwm(5) for details.
476
477
479 The ldap backend does not honor all ACL semantics as described in
480 slapd.access(5). In general, access checking is delegated to the
481 remote server(s). Only read (=r) access to the entry pseudo-attribute
482 and to the other attribute values of the entries returned by the search
483 operation is honored, which is performed by the frontend.
484
485
487 The LDAP backend provides basic proxying functionalities to many
488 overlays. The chain overlay, described in slapo-chain(5), and the
489 translucent overlay, described in slapo-translucent(5), deserve a
490 special mention.
491
492 Conversely, there are many overlays that are best used in conjunction
493 with the LDAP backend. The proxycache overlay allows caching of LDAP
494 search requests (queries) in a local database. See slapo-pcache(5) for
495 details. The rwm overlay provides DN rewrite and attribute/objectClass
496 mapping capabilities to the underlying database. See slapo-rwm(5) for
497 details.
498
499
501 /etc/openldap/slapd.conf
502 default slapd configuration file
503
505 slapd.conf(5), slapd-config(5), slapd-meta(5), slapo-chain(5),
506 slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
507
509 Howard Chu, with enhancements by Pierangelo Masarati
510
511
512
513OpenLDAP 2.4.23 2010/06/30 SLAPD-LDAP(5)