From 5ea77a75dd2d2158401331879f3c8f47940a732c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:35:32 +0200 Subject: Adding upstream version 2.5.13+dfsg. Signed-off-by: Daniel Baumann --- doc/man/man5/slapd-asyncmeta.5 | 532 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 doc/man/man5/slapd-asyncmeta.5 (limited to 'doc/man/man5/slapd-asyncmeta.5') diff --git a/doc/man/man5/slapd-asyncmeta.5 b/doc/man/man5/slapd-asyncmeta.5 new file mode 100644 index 0000000..743d3ef --- /dev/null +++ b/doc/man/man5/slapd-asyncmeta.5 @@ -0,0 +1,532 @@ +.TH SLAPD-ASYNCMETA 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 2016-2022 The OpenLDAP Foundation. +.\" Portions Copyright 2016 Symas Corporation. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" $OpenLDAP$ +.\" + +.SH NAME +slapd\-asyncmeta \- asynchronous metadirectory backend to slapd +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B asyncmeta +backend to +.BR slapd (8) +performs basic LDAP proxying with respect to a set of remote LDAP +servers, called "targets". +The information contained in these servers can be presented as +belonging to a single Directory Information Tree (DIT). + +.LP +A good knowledge of the functionality of the +.BR slapd\-meta(5) +backend is recommended. This backend has been designed as +an asynchronous version of the +.B meta +backend. Unlike +.B meta +, the operation handling threads are no longer pending +on the response from the remote server, thus decreasing the +number of threads necessary to handle the same load. While +.B asyncmeta +maintains the functionality of +.B meta +and has a largely similar codebase, +some changes in operation and some new configuration directives have been +added. Some configuration options, such as +.B conn\-pool\-max , +.B conn\-ttl , +.B single\-conn , +and +.B use\-temporary\-conn +have been removed, as they are no longer relevant. +.LP +.B New connection handling: +.LP + +Unlike +.B meta, +which caches bound connections, the +.B asyncmeta +works with a configured maximum number of connections per target. +For each request redirected to a target, a different connection is selected. +Each connection has a queue, to which the request is added before it is sent to the +remote server, and is removed after the last response for that request is received. + For each new request, the connection with the smallest number of pending requests +is selected, or using round\-robin if the numbers are equal. +.LP +.B Overlays: +.LP +Due to implementation specifics, there is no guarantee that any of the existing OpenLDAP overlays will work with +.B asyncmeta +backend. + +.SH EXAMPLES +Refer to +.B slapd\-meta(5) +for configuration examples. + +.SH CONFIGURATION +These +.B slapd.conf +options apply to the ASYNCMETA backend database. +That is, they must follow a "database asyncmeta" line and come before any +subsequent "backend" or "database" lines. +Other database options are described in the +.BR slapd.conf (5) +manual page. + +.SH SPECIAL CONFIGURATION DIRECTIVES +Target configuration starts with the "uri" directive. +All the configuration directives that are not specific to targets +should be defined first for clarity, including those that are common +to all backends. +They are: + +.TP +.B default\-target none +This directive forces the backend to reject all those operations +that must resolve to a single target in case none or multiple +targets are selected. +They include: add, delete, modify, modrdn; compare is not included, as +well as bind since, as they don't alter entries, in case of multiple +matches an attempt is made to perform the operation on any candidate +target, with the constraint that at most one must succeed. +This directive can also be used when processing targets to mark a +specific target as default. + +.TP +.B dncache\-ttl {DISABLED|forever|} +This directive sets the time-to-live of the DN cache. +This caches the target that holds a given DN to speed up target +selection in case multiple targets would result from an uncached +search; forever means cache never expires; disabled means no DN +caching; otherwise a valid ( > 0 ) ttl is required, in the format +illustrated for the +.B idle\-timeout +directive. + +.TP +.B onerr {CONTINUE|report|stop} +This directive allows one to select the behavior in case an error is returned +by one target during a search. +The default, \fBcontinue\fP, consists in continuing the operation, +trying to return as much data as possible. +If the value is set to \fBstop\fP, the search is terminated as soon +as an error is returned by one target, and the error is immediately +propagated to the client. +If the value is set to \fBreport\fP, the search is continued to the end +but, in case at least one target returned an error code, the first +non-success error code is returned. + +.TP +.B max\-timeout\-ops +Specify the number of consecutive timed out requests, +after which the connection will be considered faulty and dropped. + +.TP +.B max\-pending\-ops +The maximum number of pending requests stored in a connection's queue. +The default is 128. When this number is exceeded, +.B LDAP_BUSY +will be returned to the client. + +.TP +.B max\-target\-conns +The maximum number of connections per target. Unlike +.B slapd\-meta(5), +no new connections will be created +once this number is reached. The default value is 255. + +.TP +.B norefs +If +.BR yes , +do not return search reference responses. +By default, they are returned unless request is LDAPv2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B noundeffilter +If +.BR yes , +return success instead of searching if a filter is undefined or contains +undefined portions. +By default, the search is propagated after replacing undefined portions +with +.BR (!(objectClass=*)) , +which corresponds to the empty result set. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B protocol\-version {0,2,3} +This directive indicates what protocol version must be used to contact +the remote server. +If set to 0 (the default), the proxy uses the same protocol version +used by the client, otherwise the requested protocol is used. +The proxy returns \fIunwillingToPerform\fP if an operation that is +incompatible with the requested protocol is attempted. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B pseudoroot\-bind\-defer {YES|no} +This directive, when set to +.BR yes , +causes the authentication to the remote servers with the pseudo-root +identity (the identity defined in each +.B idassert-bind +directive) to be deferred until actually needed by subsequent operations. +Otherwise, all binds as the rootdn are propagated to the targets. + +.TP +.B quarantine ,[;,[...]] +Turns on quarantine of URIs that returned +.IR LDAP_UNAVAILABLE , +so that an attempt to reconnect only occurs at given intervals instead +of any time a client requests an operation. +The pattern is: retry only after at least +.I interval +seconds elapsed since last attempt, for exactly +.I num +times; then use the next pattern. +If +.I num +for the last pattern is "\fB+\fP", it retries forever; otherwise, +no more retries occur. +This directive must appear before any target specification; +it affects all targets with the same pattern. + +.TP +.B rebind\-as\-user {NO|yes} +If this option is given, the client's bind credentials are remembered +for rebinds, when trying to re-establish a broken connection, +or when chasing a referral, if +.B chase\-referrals +is set to +.IR yes . + +.TP +.B session\-tracking\-request {NO|yes} +Adds session tracking control for all requests. +The client's IP and hostname, and the identity associated to each request, +if known, are sent to the remote server for informational purposes. +This directive is incompatible with setting \fIprotocol\-version\fP to 2. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.SH TARGET SPECIFICATION +Target specification starts with a "uri" directive: + +.TP +.B uri ://[]/ [...] +Identical to +.B meta. +See +.B slapd\-meta(5) +for details. + +.TP +.B acl\-authcDN "" +DN which is used to query the target server for acl checking, +as in the LDAP backend; it is supposed to have read access +on the target server to attributes used on the proxy for acl checking. +There is no risk of giving away such values; they are only used to +check permissions. +.B The acl\-authcDN identity is by no means implicitly used by the proxy +.B when the client connects anonymously. + +.TP +.B acl\-passwd +Password used with the +.B acl\-authcDN +above. + +.TP +.B bind\-timeout +This directive defines the timeout, in microseconds, used when polling +for response after an asynchronous bind connection. See +.B slapd\-meta(5) +for details. + +.TP +.B chase\-referrals {YES|no} +enable/disable automatic referral chasing, which is delegated to the +underlying libldap, with rebinding eventually performed if the +\fBrebind\-as\-user\fP directive is used. The default is to chase referrals. +If set before any target specification, it affects all targets, unless +overridden by any per-target directive. + +.TP +.B client\-pr {accept-unsolicited|DISABLE|} +This feature allows one to use RFC 2696 Paged Results control when performing +search operations with a specific target, +irrespective of the client's request. See +.B slapd\-meta(5) +for details. + +.TP +.B default\-target [] +The "default\-target" directive can also be used during target specification. +With no arguments it marks the current target as the default. +The optional number marks target as the default one, starting +from 1. +Target must be defined. + +.TP +.B filter +This directive allows specifying a +.BR regex (5) +pattern to indicate what search filter terms are actually served by a target. + +In a search request, if the search filter matches the \fIpattern\fP +the target is considered while fulfilling the request; otherwise +the target is ignored. There may be multiple occurrences of +the +.B filter +directive for each target. + +.TP +.B idassert\-authzFrom +if defined, selects what +.I local +identities are authorized to exploit the identity assertion feature. +The string +.B +follows the rules defined for the +.I authzFrom +attribute. +See +.BR slapd.conf (5), +section related to +.BR authz\-policy , +for details on the syntax of this field. + +.HP +.hy 0 +.B idassert\-bind +.B bindmethod=none|simple|sasl [binddn=] [credentials=] +.B [saslmech=] [secprops=] [realm=] +.B [authcId=] [authzId=] +.B [authz={native|proxyauthz}] [mode=] [flags=] +.B [starttls=no|yes|critical] +.B [tls_cert=] +.B [tls_key=] +.B [tls_cacert=] +.B [tls_cacertdir=] +.B [tls_reqcert=never|allow|try|demand] +.B [tls_reqsan=never|allow|try|demand] +.B [tls_cipher_suite=] +.B [tls_ecname=] +.B [tls_protocol_min=[.]] +.B [tls_crlcheck=none|peer|all] +Allows one to define the parameters of the authentication method that is +internally used by the proxy to authorize connections that are +authenticated by other databases. See +.B slapd\-meta(5) +for details. + +.TP +.B idle\-timeout