1SLAPD-ASYNCMETA(5) File Formats Manual SLAPD-ASYNCMETA(5)
2
6 slapd-asyncmeta - asynchronous metadirectory backend to slapd
7
9 /etc/openldap/slapd.conf
10
12 The asyncmeta backend to slapd(8) performs basic LDAP proxying with re‐
13 spect to a set of remote LDAP servers, called "targets". The informa‐
14 tion contained in these servers can be presented as belonging to a sin‐
15 gle Directory Information Tree (DIT).
16 A good knowledge of the functionality of the slapd-meta(5) backend is
19 recommended. This backend has been designed as an asynchronous ver‐
20 sion of the meta backend. Unlike meta , the operation handling threads
21 are no longer pending on the response from the remote server, thus de‐
22 creasing the number of threads necessary to handle the same load. While
23 asyncmeta maintains the functionality of meta and has a largely similar
24 codebase, some changes in operation and some new configuration direc‐
25 tives have been added. Some configuration options, such as
26 conn-pool-max , conn-ttl , single-conn , and use-temporary-conn have
27 been removed, as they are no longer relevant.
28 New connection handling:
30 Unlike meta, which caches bound connections, the asyncmeta works with a
32 configured maximum number of connections per target. For each request
33 redirected to a target, a different connection is selected. Each con‐
34 nection has a queue, to which the request is added before it is sent to
35 the remote server, and is removed after the last response for that re‐
36 quest is received.
37 For each new request, a new connection is chosen using round-robin
38 scheduling.
39 Overlays:
41 Due to implementation specifics, there is no guarantee that any of the
43 existing OpenLDAP overlays will work with asyncmeta backend.
44
47 Refer to slapd-meta(5) for configuration examples.
48
51 These slapd.conf options apply to the ASYNCMETA backend database. That
52 is, they must follow a "database asyncmeta" line and come before any
53 subsequent "backend" or "database" lines. Other database options are
54 described in the slapd.conf(5) manual page.
55
58 Target configuration starts with the "uri" directive. All the configu‐
59 ration directives that are not specific to targets should be defined
60 first for clarity, including those that are common to all backends.
61 They are:
62 default-target none
65 This directive forces the backend to reject all those operations
66 that must resolve to a single target in case none or multiple
67 targets are selected. They include: add, delete, modify, mod‐
68 rdn; compare is not included, as well as bind since, as they
69 don't alter entries, in case of multiple matches an attempt is
70 made to perform the operation on any candidate target, with the
71 constraint that at most one must succeed. This directive can
72 also be used when processing targets to mark a specific target
73 as default.
74 dncache-ttl {DISABLED|forever|<ttl>}
77 This directive sets the time-to-live of the DN cache. This
78 caches the target that holds a given DN to speed up target se‐
79 lection in case multiple targets would result from an uncached
80 search; forever means cache never expires; disabled means no DN
81 caching; otherwise a valid ( > 0 ) ttl is required, in the for‐
82 mat illustrated for the idle-timeout directive.
83 onerr {CONTINUE|report|stop}
86 This directive allows one to select the behavior in case an er‐
87 ror is returned by one target during a search. The default,
88 continue, consists in continuing the operation, trying to return
89 as much data as possible. If the value is set to stop, the
90 search is terminated as soon as an error is returned by one tar‐
91 get, and the error is immediately propagated to the client. If
92 the value is set to report, the search is continued to the end
93 but, in case at least one target returned an error code, the
94 first non-success error code is returned.
95 max-timeout-ops <number>
98 Specify the number of consecutive timed out requests, after
99 which the connection will be considered faulty and dropped.
100 max-pending-ops <number>
103 The maximum number of pending requests stored in a connection's
104 queue. The default is 128. When this number is exceeded,
105 LDAP_BUSY will be returned to the client.
106 max-target-conns <number>
109 The maximum number of connections per target. Unlike
110 slapd-meta(5), no new connections will be created once this num‐
111 ber is reached. The default value is 255.
112 norefs <NO|yes>
115 If yes, do not return search reference responses. By default,
116 they are returned unless request is LDAPv2. If set before any
117 target specification, it affects all targets, unless overridden
118 by any per-target directive.
119 noundeffilter <NO|yes>
122 If yes, return success instead of searching if a filter is unde‐
123 fined or contains undefined portions. By default, the search is
124 propagated after replacing undefined portions with (!(object‐
125 Class=*)), which corresponds to the empty result set. If set
126 before any target specification, it affects all targets, unless
127 overridden by any per-target directive.
128 protocol-version {0,2,3}
131 This directive indicates what protocol version must be used to
132 contact the remote server. If set to 0 (the default), the proxy
133 uses the same protocol version used by the client, otherwise the
134 requested protocol is used. The proxy returns unwillingToPer‐
135 form if an operation that is incompatible with the requested
136 protocol is attempted. If set before any target specification,
137 it affects all targets, unless overridden by any per-target di‐
138 rective.
139 pseudoroot-bind-defer {YES|no}
142 This directive, when set to yes, causes the authentication to
143 the remote servers with the pseudo-root identity (the identity
144 defined in each idassert-bind directive) to be deferred until
145 actually needed by subsequent operations. Otherwise, all binds
146 as the rootdn are propagated to the targets.
147 quarantine <interval>,<num>[;<interval>,<num>[...]]
150 Turns on quarantine of URIs that returned LDAP_UNAVAILABLE, so
151 that an attempt to reconnect only occurs at given intervals in‐
152 stead of any time a client requests an operation. The pattern
153 is: retry only after at least interval seconds elapsed since
154 last attempt, for exactly num times; then use the next pattern.
155 If num for the last pattern is "+", it retries forever; other‐
156 wise, no more retries occur. This directive must appear before
157 any target specification; it affects all targets with the same
158 pattern.
159 rebind-as-user {NO|yes}
162 If this option is given, the client's bind credentials are re‐
163 membered for rebinds, when trying to re-establish a broken con‐
164 nection, or when chasing a referral, if chase-referrals is set
165 to yes.
166 session-tracking-request {NO|yes}
169 Adds session tracking control for all requests. The client's IP
170 and hostname, and the identity associated to each request, if
171 known, are sent to the remote server for informational purposes.
172 This directive is incompatible with setting protocol-version to
173 2. If set before any target specification, it affects all tar‐
174 gets, unless overridden by any per-target directive.
175
178 Target specification starts with a "uri" directive:
179 uri <protocol>://[<host>]/<naming context> [...]
182 Identical to meta. See slapd-meta(5) for details.
183 acl-authcDN <administrative DN for access control purposes>
186 DN which is used to query the target server for acl checking, as
187 in the LDAP backend; it is supposed to have read access on the
188 target server to attributes used on the proxy for acl checking.
189 There is no risk of giving away such values; they are only used
190 to check permissions. The acl-authcDN identity is by no means
191 implicitly used by the proxy when the client connects anony‐
192 mously.
193 acl-passwd <password>
196 Password used with the acl-authcDN above.
197 bind-timeout <microseconds>
200 This directive defines the timeout, in microseconds, used when
201 polling for response after an asynchronous bind connection. See
202 slapd-meta(5) for details.
203 chase-referrals {YES|no}
206 enable/disable automatic referral chasing, which is delegated to
207 the underlying libldap, with rebinding eventually performed if
208 the rebind-as-user directive is used. The default is to chase
209 referrals. If set before any target specification, it affects
210 all targets, unless overridden by any per-target directive.
211 client-pr {accept-unsolicited|DISABLE|<size>}
214 This feature allows one to use RFC 2696 Paged Results control
215 when performing search operations with a specific target, irre‐
216 spective of the client's request. See slapd-meta(5) for details.
217 default-target [<target>]
220 The "default-target" directive can also be used during target
221 specification. With no arguments it marks the current target as
222 the default. The optional number marks target <target> as the
223 default one, starting from 1. Target <target> must be defined.
224 filter <pattern>
227 This directive allows specifying a regex(5) pattern to indicate
228 what search filter terms are actually served by a target.
229 In a search request, if the search filter matches the pattern
231 the target is considered while fulfilling the request; otherwise
232 the target is ignored. There may be multiple occurrences of the
233 filter directive for each target.
234 idassert-authzFrom <authz-regexp>
237 if defined, selects what local identities are authorized to ex‐
238 ploit the identity assertion feature. The string <authz-regexp>
239 follows the rules defined for the authzFrom attribute. See
240 slapd.conf(5), section related to authz-policy, for details on
241 the syntax of this field.
242 idassert-bind bindmethod=none|simple|sasl [binddn=<simple DN>]
245 [credentials=<simple password>] [saslmech=<SASL mech>]
246 [secprops=<properties>] [realm=<realm>] [authcId=<authentication
247 ID>] [authzId=<authorization ID>] [authz={native|proxyauthz}]
248 [mode=<mode>] [flags=<flags>] [starttls=no|yes|critical]
249 [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>]
250 [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand]
251 [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
252 [tls_ecname=<names>] [tls_protocol_min=<major>[.<minor>]]
253 [tls_crlcheck=none|peer|all] Allows one to define the parameters
254 of the authentication method that is internally used by the
255 proxy to authorize connections that are authenticated by other
256 databases. See slapd-meta(5) for details.
257 idle-timeout <time>
260 This directive causes a a persistent connection to be dropped
261 after it has been idle for the specified time. The connection
262 will be re-created the next time it is selected for use. A
263 connection is considered idle if no attempts have been made by
264 the backend to use it to send a request to the backend server.
265 If there are still pending requests in its queue, the connection
266 will be dropped after the last request one has either received a
267 result or has timed out.
268 [<d>d][<h>h][<m>m][<s>[s]]
270 where <d>, <h>, <m> and <s> are respectively treated as days,
272 hours, minutes and seconds. If set before any target
273 specification, it affects all targets, unless overridden by any
274 per-target directive.
275 keepalive <idle>:<probes>:<interval>
278 The keepalive parameter sets the values of idle, probes, and
279 interval used to check whether a socket is alive; idle is the
280 number of seconds a connection needs to remain idle before TCP
281 starts sending keepalive probes; probes is the maximum number of
282 keepalive probes TCP should send before dropping the connection;
283 interval is interval in seconds between individual keepalive
284 probes. Only some systems support the customization of these
285 values; the keepalive parameter is ignored otherwise, and
286 system-wide settings are used.
287 tcp-user-timeout <milliseconds>
290 If non-zero, corresponds to the TCP_USER_TIMEOUT set on the
291 target connections, overriding the operating system setting.
292 Only some systems support the customization of this parameter,
293 it is ignored otherwise and system-wide settings are used.
294 map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
297 This maps object classes and attributes as in the LDAP backend.
298 See slapd-ldap(5).
299 network-timeout <time>
302 Sets the network timeout value after which poll(2)/select(2)
303 following a connect(2) returns in case of no activity while
304 sending an operation to the remote target. The value is in
305 milliseconds, and it can be specified as for idle-timeout. If
306 set before any target specification, it affects all targets,
307 unless overridden by any per-target directive.
308 nretries {forever|never|<nretries>}
311 This directive defines how many times forwarding an operation
312 should be retried in case of temporary failure in contacting a
313 target. The number of retries is per operation, so if a bind to
314 the target is necessary first, the remaining number is
315 decremented. If defined before any target specification, it
316 applies to all targets (by default, 3 times); the global value
317 can be overridden by redefinitions inside each target
318 specification.
319 rewrite* ...
322 The rewrite options are identical to the meta backend. See the
323 REWRITING section of slapd-meta(5).
324 subtree-{exclude|include} <rule>
327 This directive allows one to indicate what subtrees are actually
328 served by a target. See slapd-meta(5) for details.
329 suffixmassage <local suffix> <remote suffix>
332 slapd-asyncmeta does not support the rewrite engine used by the
333 LDAP and META backends. suffixmassage can be used to perform DN
334 suffix rewriting, the same way as the obsoleted suffixmassage
335 directive previously used by the LDAP backend.
336 t-f-support {NO|yes|discover}
339 enable if the remote server supports absolute filters (see RFC
340 4526 for details). If set to discover, support is detected by
341 reading the remote server's root DSE. If set before any target
342 specification, it affects all targets, unless overridden by any
343 per-target directive.
344 timeout [<op>=]<val> [...]
347 This directive allows one to set per-operation timeouts.
348 Operations can be
349 <op> ::= bind, add, delete, modrdn, modify, compare, search
351 By default, the timeout for all operations is 2 seconds.
353 See slapd-meta(5) for details.
355 tls {none|[try-]start|[try-]propagate|ldaps}
358 B [starttls=no] [tls_cert=<file>] [tls_key=<file>]
359 [tls_cacert=<file>] [tls_cacertdir=<path>]
360 [tls_reqcert=never|allow|try|demand]
361 [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
362 [tls_ecname=<names>] [tls_crlcheck=none|peer|all]
363 Specify TLS settings regular connections.
364 If the first parameter is not "none" then this configures the
366 TLS settings to be used for regular connections. The StartTLS
367 extended operation will be used when establishing the connection
368 unless the URI directive protocol scheme is ldaps://. In that
369 case this keyword may only be set to "ldaps" and the StartTLS
370 operation will not be used.
371 With propagate, the proxy issues the StartTLS operation only if
373 the original connection has a TLS layer set up. The try- prefix
374 instructs the proxy to continue operations if the StartTLS
375 operation failed; its use is not recommended.
376 The TLS settings default to the same as the main slapd TLS
378 settings, except for tls_reqcert which defaults to "demand",
379 tls_reqsan which defaults to "allow", and starttls which is
380 overshadowed by the first keyword and thus ignored.
381 If set before any target specification, it affects all targets,
383 unless overridden by any per-target directive.
384
387 See slapd-meta(5) for configuration scenarios.
388
391 ACL behavior is identical to meta. See slapd-meta(5).
392
395 The asyncmeta backend does not honor all ACL semantics as described in
396 slapd.access(5). In general, access checking is delegated to the
397 remote server(s). Only read (=r) access to the entry pseudo-attribute
398 and to the other attribute values of the entries returned by the search
399 operation is honored, which is performed by the frontend.
400
403 /etc/openldap/slapd.conf
404 default slapd configuration file
405
407 slapd.conf(5), slapd-ldap(5), slapd-meta(5), slapo-pcache(5), slapd(8),
408 regex(7), re_format(7).
409
411 Nadezhda Ivanova, based on back-meta by Pierangelo Masarati.
412OpenLDAP 2.6.6 2023/07/31 SLAPD-ASYNCMETA(5)