git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-asyncmeta.5

   1 .TH SLAPD-ASYNCMETA 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" Copyright 2016-2017 The OpenLDAP Foundation.
   3 .\" Portions Copyright 2016 Symas Corporation.
   4 .\" Copying restrictions apply.  See the COPYRIGHT file.
   5 .\" $OpenLDAP$
   6 .\"
   7
   8 .SH NAME
   9 slapd\-asyncmeta \- asynchronous metadirectory backend to slapd
  10 .SH SYNOPSIS
  11 ETCDIR/slapd.conf
  12 .SH DESCRIPTION
  13 The
  14 .B asyncmeta
  15 backend to
  16 .BR slapd (8)
  17 performs basic LDAP proxying with respect to a set of remote LDAP
  18 servers, called "targets".
  19 The information contained in these servers can be presented as
  20 belonging to a single Directory Information Tree (DIT).
  21
  22 .LP
  23 A good knowledge of the functionality of the
  24 .BR slapd\-meta(5)
  25 backend  is recommended.   This  backend has been designed as
  26 an asynchronous version of the
  27 .B meta
  28 backend. Unlike
  29 .B meta
  30 , the operation handling threads are no longer pending
  31 on the response from the remote server, thus decreasing the
  32 number of threads necessary to handle the same load. While
  33 .B asyncmeta
  34 maintains the functionality of
  35 .B meta
  36 and has a largely similar codebase,
  37 some changes in operation and some new configuration directives have been
  38 added. Some configuration options, such as
  39 .B conn-ttl,
  40 .B single-conn
  41 and
  42 .B use-temporary-conn
  43 have been removed, as they are no longer relevant.
  44 .LP
  45 .B New connection handling:
  46 .LP
  47
  48 Unlike
  49 .B meta,
  50 which caches bound connections, the
  51 .B asyncmeta
  52 works with a configured maximum number of connections per target.
  53 For each request redirected to a target, a different connection is selected.
  54 Each connection has a queue, to which the request is added before it is sent to the
  55 remote server, and is removed after the last response for that request is received.
  56  For each new request, the connection with the smallest number of pending requests
  57 is selected, or using round\-robin if the numbers are equal.
  58 .LP
  59 .B Overlays:
  60 .LP
  61 Due to implementation specifics, there is no guarantee that any of the existing OpenLDAP overlays will work with
  62 .B asyncmeta
  63 backend.
  64
  65 .SH EXAMPLES
  66 Refer to
  67 .B slapd\-meta(5)
  68 for configuration examples.
  69
  70 .SH CONFIGURATION
  71 These
  72 .B slapd.conf
  73 options apply to the ASYNCMETA backend database.
  74 That is, they must follow a "database asyncmeta" line and come before any
  75 subsequent "backend" or "database" lines.
  76 Other database options are described in the
  77 .BR slapd.conf (5)
  78 manual page.
  79
  80 .SH SPECIAL CONFIGURATION DIRECTIVES
  81 Target configuration starts with the "uri" directive.
  82 All the configuration directives that are not specific to targets
  83 should be defined first for clarity, including those that are common
  84 to all backends.
  85 They are:
  86
  87 .TP
  88 .B default\-target none
  89 This directive forces the backend to reject all those operations
  90 that must resolve to a single target in case none or multiple
  91 targets are selected.
  92 They include: add, delete, modify, modrdn; compare is not included, as
  93 well as bind since, as they don't alter entries, in case of multiple
  94 matches an attempt is made to perform the operation on any candidate
  95 target, with the constraint that at most one must succeed.
  96 This directive can also be used when processing targets to mark a
  97 specific target as default.
  98
  99 .TP
 100 .B dncache\-ttl {DISABLED|forever|<ttl>}
 101 This directive sets the time-to-live of the DN cache.
 102 This caches the target that holds a given DN to speed up target
 103 selection in case multiple targets would result from an uncached
 104 search; forever means cache never expires; disabled means no DN
 105 caching; otherwise a valid ( > 0 ) ttl is required, in the format
 106 illustrated for the
 107 .B idle\-timeout
 108 directive.
 109
 110 .TP
 111 .B onerr {CONTINUE|report|stop}
 112 This directive allows one to select the behavior in case an error is returned
 113 by one target during a search.
 114 The default, \fBcontinue\fP, consists in continuing the operation,
 115 trying to return as much data as possible.
 116 If the value is set to \fBstop\fP, the search is terminated as soon
 117 as an error is returned by one target, and the error is immediately
 118 propagated to the client.
 119 If the value is set to \fBreport\fP, the search is continuated to the end
 120 but, in case at least one target returned an error code, the first
 121 non-success error code is returned.
 122
 123 .TP
 124 .B max\-timeout\-ops <number>
 125 Specify the number of consecutive timed out requests,
 126 after which the connection will be considered faulty and dropped.
 127
 128 .TP
 129 .B max-pending-ops <number>
 130 The maximum number of pending requests stored in a connection's queue.
 131 The default is 128. When this number is exceeded,
 132 .B LDAP_BUSY
 133 will be returned to the client.
 134
 135 .TP
 136 .B max-target-conns <number>
 137 The maximum number of connections per target. Unlike
 138 .B slapd\-meta(5),
 139 no new connections will be created
 140 once this number is reached. The default value is 255.
 141
 142 .TP
 143 .B norefs <NO|yes>
 144 If
 145 .BR yes ,
 146 do not return search reference responses.
 147 By default, they are returned unless request is LDAPv2.
 148 If set before any target specification, it affects all targets, unless
 149 overridden by any per-target directive.
 150
 151 .TP
 152 .B noundeffilter <NO|yes>
 153 If
 154 .BR yes ,
 155 return success instead of searching if a filter is undefined or contains
 156 undefined portions.
 157 By default, the search is propagated after replacing undefined portions
 158 with
 159 .BR (!(objectClass=*)) ,
 160 which corresponds to the empty result set.
 161 If set before any target specification, it affects all targets, unless
 162 overridden by any per-target directive.
 163
 164 .TP
 165 .B protocol\-version {0,2,3}
 166 This directive indicates what protocol version must be used to contact
 167 the remote server.
 168 If set to 0 (the default), the proxy uses the same protocol version
 169 used by the client, otherwise the requested protocol is used.
 170 The proxy returns \fIunwillingToPerform\fP if an operation that is
 171 incompatible with the requested protocol is attempted.
 172 If set before any target specification, it affects all targets, unless
 173 overridden by any per-target directive.
 174
 175 .TP
 176 .B pseudoroot\-bind\-defer {YES|no}
 177 This directive, when set to
 178 .BR yes ,
 179 causes the authentication to the remote servers with the pseudo-root
 180 identity (the identity defined in each
 181 .B idassert-bind
 182 directive) to be deferred until actually needed by subsequent operations.
 183 Otherwise, all binds as the rootdn are propagated to the targets.
 184
 185 .TP
 186 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
 187 Turns on quarantine of URIs that returned
 188 .IR LDAP_UNAVAILABLE ,
 189 so that an attempt to reconnect only occurs at given intervals instead
 190 of any time a client requests an operation.
 191 The pattern is: retry only after at least
 192 .I interval
 193 seconds elapsed since last attempt, for exactly
 194 .I num
 195 times; then use the next pattern.
 196 If
 197 .I num
 198 for the last pattern is "\fB+\fP", it retries forever; otherwise,
 199 no more retries occur.
 200 This directive must appear before any target specification;
 201 it affects all targets with the same pattern.
 202
 203 .TP
 204 .B rebind\-as\-user {NO|yes}
 205 If this option is given, the client's bind credentials are remembered
 206 for rebinds, when trying to re-establish a broken connection,
 207 or when chasing a referral, if
 208 .B chase\-referrals
 209 is set to
 210 .IR yes .
 211
 212 .TP
 213 .B session\-tracking\-request {NO|yes}
 214 Adds session tracking control for all requests.
 215 The client's IP and hostname, and the identity associated to each request,
 216 if known, are sent to the remote server for informational purposes.
 217 This directive is incompatible with setting \fIprotocol\-version\fP to 2.
 218 If set before any target specification, it affects all targets, unless
 219 overridden by any per-target directive.
 220
 221 .SH TARGET SPECIFICATION
 222 Target specification starts with a "uri" directive:
 223
 224 .TP
 225 .B uri <protocol>://[<host>]/<naming context> [...]
 226 Identical to
 227 .B meta.
 228 See
 229 .B slapd\-meta(5)
 230 for details.
 231
 232 .TP
 233 .B acl\-authcDN "<administrative DN for access control purposes>"
 234 DN which is used to query the target server for acl checking,
 235 as in the LDAP backend; it is supposed to have read access
 236 on the target server to attributes used on the proxy for acl checking.
 237 There is no risk of giving away such values; they are only used to
 238 check permissions.
 239 .B The acl\-authcDN identity is by no means implicitly used by the proxy
 240 .B when the client connects anonymously.
 241
 242 .TP
 243 .B acl\-passwd <password>
 244 Password used with the
 245 .B
 246 acl\-authcDN
 247 above.
 248
 249 .TP
 250 .B bind\-timeout <microseconds>
 251 This directive defines the timeout, in microseconds, used when polling
 252 for response after an asynchronous bind connection. See
 253 .B slapd\-meta(5)
 254 for details.
 255
 256 .TP
 257 .B chase\-referrals {YES|no}
 258 enable/disable automatic referral chasing, which is delegated to the
 259 underlying libldap, with rebinding eventually performed if the
 260 \fBrebind\-as\-user\fP directive is used.  The default is to chase referrals.
 261 If set before any target specification, it affects all targets, unless
 262 overridden by any per-target directive.
 263
 264 .TP
 265 .B client\-pr {accept-unsolicited|DISABLE|<size>}
 266 This feature allows one to use RFC 2696 Paged Results control when performing
 267 search operations with a specific target,
 268 irrespective of the client's request. See
 269 .B slapd\-meta(5)
 270 for details.
 271
 272 .TP
 273 .B default\-target [<target>]
 274 The "default\-target" directive can also be used during target specification.
 275 With no arguments it marks the current target as the default.
 276 The optional number marks target <target> as the default one, starting
 277 from 1.
 278 Target <target> must be defined.
 279
 280 .TP
 281 .B filter <pattern>
 282 This directive allows specifying a
 283 .BR regex (5)
 284 pattern to indicate what search filter terms are actually served by a target.
 285
 286 In a search request, if the search filter matches the \fIpattern\fP
 287 the target is considered while fulfilling the request; otherwise
 288 the target is ignored. There may be multiple occurrences of
 289 the
 290 .B filter
 291 directive for each target.
 292
 293 .TP
 294 .B idassert\-authzFrom <authz-regexp>
 295 if defined, selects what
 296 .I local
 297 identities are authorized to exploit the identity assertion feature.
 298 The string
 299 .B <authz-regexp>
 300 follows the rules defined for the
 301 .I authzFrom
 302 attribute.
 303 See
 304 .BR slapd.conf (5),
 305 section related to
 306 .BR authz\-policy ,
 307 for details on the syntax of this field.
 308
 309 .HP
 310 .hy 0
 311 .B idassert\-bind
 312 .B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
 313 .B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
 314 .B [authcId=<authentication ID>] [authzId=<authorization ID>]
 315 .B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
 316 .B [starttls=no|yes|critical]
 317 .B [tls_cert=<file>]
 318 .B [tls_key=<file>]
 319 .B [tls_cacert=<file>]
 320 .B [tls_cacertdir=<path>]
 321 .B [tls_reqcert=never|allow|try|demand]
 322 .B [tls_cipher_suite=<ciphers>]
 323 .B [tls_protocol_min=<major>[.<minor>]]
 324 .B [tls_crlcheck=none|peer|all]
 325 Allows one to define the parameters of the authentication method that is
 326 internally used by the proxy to authorize connections that are
 327 authenticated by other databases. See
 328 .B slapd\-meta(5)
 329 for details.
 330
 331 .TP
 332 .B idle\-timeout <time>
 333 This directive causes a a persistent connection  to  be  dropped after
 334 it  has been idle for the specified time. The connection will be re-created
 335 the next time it is selected for use. A connection is considered idle if no
 336 attempts have been made by the backend to use it to send a request to
 337 the backend server. If there are still pending requests in
 338 its queue, the connection will be dropped after the last
 339 request one has either received a result or has timed out.
 340
 341 [<d>d][<h>h][<m>m][<s>[s]]
 342
 343 where <d>, <h>, <m> and <s> are respectively treated as days, hours,
 344 minutes and seconds.
 345 If set before any target specification, it affects all targets, unless
 346 overridden by any per-target directive.
 347
 348 .TP
 349 .B keepalive  <idle>:<probes>:<interval>
 350 The
 351 .B keepalive
 352 parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP
 353 used to check whether a socket is alive;
 354 .I idle
 355 is the number of seconds a connection needs to remain idle before TCP
 356 starts sending keepalive probes;
 357 .I probes
 358 is the maximum number of keepalive probes TCP should send before dropping
 359 the connection;
 360 .I interval
 361 is interval in seconds between individual keepalive probes.
 362 Only some systems support the customization of these values;
 363 the
 364 .B keepalive
 365 parameter is ignored otherwise, and system-wide settings are used.
 366
 367 .TP
 368 .B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
 369 This maps object classes and attributes as in the LDAP backend.
 370 See
 371 .BR slapd\-ldap (5).
 372
 373 .TP
 374 .B network\-timeout <time>
 375 Sets the network timeout value after which
 376 .BR poll (2)/ select (2)
 377 following a
 378 .BR connect (2)
 379 returns in case of no activity.
 380 The value is in seconds, and it can be specified as for
 381 .BR idle\-timeout .
 382 If set before any target specification, it affects all targets, unless
 383 overridden by any per-target directive.
 384
 385 .TP
 386 .B nretries {forever|never|<nretries>}
 387 This directive defines how many times a bind should be retried
 388 in case of temporary failure in contacting a target.  If defined
 389 before any target specification, it applies to all targets (by default,
 390 .BR 3
 391 times);
 392 the global value can be overridden by redefinitions inside each target
 393 specification.
 394
 395 .TP
 396 .B rewrite* ...
 397 The rewrite options are identical to the
 398 .B meta
 399 backend. See the
 400 .B REWRITING
 401 section of
 402 .B slapd\-meta(5).
 403
 404 .TP
 405 .B subtree\-{exclude|include} "<rule>"
 406 This directive allows one to indicate what subtrees are actually served
 407 by a target. See
 408 .B slapd\-meta(5)
 409 for details.
 410
 411 .TP
 412 .B suffixmassage "<virtual naming context>" "<real naming context>"
 413 All the directives starting with "rewrite" refer to the rewrite engine
 414 that has been added to slapd. See
 415 .B slapd\-meta(5)
 416 for details.
 417
 418 .TP
 419 .B t\-f\-support {NO|yes|discover}
 420 enable if the remote server supports absolute filters
 421 (see \fIRFC 4526\fP for details).
 422 If set to
 423 .BR discover ,
 424 support is detected by reading the remote server's root DSE.
 425 If set before any target specification, it affects all targets, unless
 426 overridden by any per-target directive.
 427
 428 .TP
 429 .B timeout [<op>=]<val> [...]
 430 This directive allows one to set per-operation timeouts.
 431 Operations can be
 432
 433 \fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
 434
 435 See
 436 .B slapd\-meta(5)
 437 for details.
 438
 439 .TP
 440 .B tls {[try\-]start|[try\-]propagate}
 441 execute the StartTLS extended operation when the connection is initialized;
 442 only works if the URI directive protocol scheme is not \fBldaps://\fP.
 443 \fBpropagate\fP issues the StartTLS operation only if the original
 444 connection did.
 445 The \fBtry\-\fP prefix instructs the proxy to continue operations
 446 if the StartTLS operation failed; its use is highly deprecated.
 447 If set before any target specification, it affects all targets, unless
 448 overridden by any per-target directive.
 449
 450 .SH SCENARIOS
 451 See
 452 .B slapd\-meta(5)
 453 for configuration scenarios.
 454
 455 .SH ACLs
 456 ACL behavior is identical to meta. See
 457 .B slapd\-meta(5).
 458
 459 .SH ACCESS CONTROL
 460 The
 461 .B asyncmeta
 462 backend does not honor all ACL semantics as described in
 463 .BR slapd.access (5).
 464 In general, access checking is delegated to the remote server(s).
 465 Only
 466 .B read (=r)
 467 access to the
 468 .B entry
 469 pseudo-attribute and to the other attribute values of the entries
 470 returned by the
 471 .B search
 472 operation is honored, which is performed by the frontend.
 473
 474 .SH FILES
 475 .TP
 476 ETCDIR/slapd.conf
 477 default slapd configuration file
 478 .SH SEE ALSO
 479 .BR slapd.conf (5),
 480 .BR slapd\-meta (5),
 481 .BR slapd\-ldap (5),
 482 .BR slapo\-pcache (5),
 483 .BR slapd (8),
 484 .BR regex (7),
 485 .BR re_format (7).
 486 .SH AUTHOR
 487 Nadezhda Ivanova, based on back-meta by Pierangelo Masarati.