1SLAPD-ASYNCMETA(5)            File Formats Manual           SLAPD-ASYNCMETA(5)
2
3
4

NAME

6       slapd-asyncmeta - asynchronous metadirectory backend to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

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
17
18       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
29       New connection handling:
30
31       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
41       Overlays:
42
43       Due to implementation specifics, there is no guarantee that any of  the
44       existing OpenLDAP overlays will work with asyncmeta backend.
45
46

EXAMPLES

48       Refer to slapd-meta(5) for configuration examples.
49
50

CONFIGURATION

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
57

SPECIAL CONFIGURATION DIRECTIVES

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
64
65       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
76
77       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
85
86       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
97
98       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
102
103       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
108
109       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
114
115       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
121
122       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
130
131       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
141
142       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
149
150       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
161
162       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
168
169       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
177

TARGET SPECIFICATION

179       Target specification starts with a "uri" directive:
180
181
182       uri <protocol>://[<host>]/<naming context> [...]
183              Identical to meta.  See slapd-meta(5) for details.
184
185
186       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
195
196       acl-passwd <password>
197              Password used with the acl-authcDN above.
198
199
200       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
205
206       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
213
214       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
219
220       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
226
227       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
231              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
236
237       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
244
245       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
259
260       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
270              [<d>d][<h>h][<m>m][<s>[s]]
271
272              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
277
278       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
289
290       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
296
297       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
301
302       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
310
311       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
321
322       rewrite* ...
323              The  rewrite  options are identical to the meta backend. See the
324              REWRITING section of slapd-meta(5).
325
326
327       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
331
332       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
338
339       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
346
347       timeout [<op>=]<val> [...]
348              This  directive  allows  one  to  set  per-operation   timeouts.
349              Operations can be
350
351              <op> ::= bind, add, delete, modrdn, modify, compare, search
352
353              By default, the timeout for all operations is 2 seconds.
354
355              See slapd-meta(5) for details.
356
357
358       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
366              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
373              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
378              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
383              If set before any target specification, it affects all  targets,
384              unless overridden by any per-target directive.
385
386

SCENARIOS

388       See slapd-meta(5) for configuration scenarios.
389
390

ACLs

392       ACL behavior is identical to meta. See slapd-meta(5).
393
394

ACCESS CONTROL

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
402

FILES

404       /etc/openldap/slapd.conf
405              default slapd configuration file
406

SEE ALSO

408       slapd.conf(5), slapd-ldap(5), slapd-meta(5), slapo-pcache(5), slapd(8),
409       regex(7), re_format(7).
410

AUTHOR

412       Nadezhda Ivanova, based on back-meta by Pierangelo Masarati.
413
414
415
416OpenLDAP 2.6.3                    2022/07/14                SLAPD-ASYNCMETA(5)
Impressum