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