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 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 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
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 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 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
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 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 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 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 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 The TLS settings default to the same as the main slapd TLS
117 settings, except for tls_reqcert which defaults to "demand".
118 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 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 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 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 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 none|simple|sasl
179 where none is the default, i.e. no identity assertion is
181 performed.
182 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 The supported modes are:
192 <mode> := {legacy|anonymous|none|self}
194 If <mode> is not present, and authzId is given, the proxy always
196 authorizes that identity. <authorization ID> can be
197 u:<user>
199 [dn:]<DN>
201 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 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 Flags can be
227 override,[non-]prescriptive,proxy-authz-[non-]critical
229 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 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 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 The TLS settings default to the same as the main slapd TLS
248 settings, except for tls_reqcert which defaults to "demand".
249 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 This directive obsoletes idassert-authcDN, idassert-passwd,
255 idassert-mode, and idassert-method.
256 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 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 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 norefs <NO|yes>
281 If yes, do not return search reference responses. By default,
282 they are returned unless request is LDAPv2.
283 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 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 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 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 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 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 single-conn {NO|yes}
339 Discards current cached connection when the client rebinds.
340 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 timeout [<op>=]<val> [...]
349 This directive allows to set per-operation timeouts. Operations
350 can be
351 <op> ::= bind, add, delete, modrdn, modify, compare, search
353 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 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 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 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 The TLS settings default to the same as the main slapd TLS
393 settings, except for tls_reqcert which defaults to "demand".
394 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
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 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 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 This directive is obsoleted by the binddn arg of acl-bind when
421 bindmethod=simple, and will be dismissed in the future.
422 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 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 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 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 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 port <port>
458 this directive is no longer supported. Use the uri directive as
459 described above.
460 server <hostname[:port]>
463 this directive is no longer supported. Use the uri directive as
464 described above.
465 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 overlay rwm
473 first, and prefix all rewrite/map statements with rwm- to obtain
475 the original behavior. See slapo-rwm(5) for details.
476
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
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 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
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
510OpenLDAP 2.4.23 2010/06/30 SLAPD-LDAP(5)