NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | CONFIGURATION | SPECIAL CONFIGURATION DIRECTIVES | TARGET SPECIFICATION | SCENARIOS | ACLs | ACCESS CONTROL | FILES | SEE ALSO | AUTHOR | COLOPHON

SLAPD-ASYNCMETA(5)           File Formats Manual          SLAPD-ASYNCMETA(5)

NAME         top

       slapd-asyncmeta - asynchronous metadirectory backend to slapd

SYNOPSIS         top

       ETCDIR/slapd.conf

DESCRIPTION         top

       The asyncmeta backend to 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).

       A good knowledge of the functionality of the slapd-meta(5) backend
       is recommended.   This  backend has been designed as an asynchronous
       version of the meta backend. Unlike 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 asyncmeta maintains the functionality of meta and has a
       largely similar codebase, some changes in operation and some new
       configuration directives have been added. Some configuration options,
       such as conn-ttl, single-conn and use-temporary-conn have been
       removed, as they are no longer relevant.

       New connection handling:

       Unlike meta, which caches bound connections, the 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.

       Overlays:

       Due to implementation specifics, there is no guarantee that any of
       the existing OpenLDAP overlays will work with asyncmeta backend.

EXAMPLES         top

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

CONFIGURATION         top

       These 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 slapd.conf(5) manual page.

SPECIAL CONFIGURATION DIRECTIVES         top

       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:

       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.

       dncache-ttl {DISABLED|forever|<ttl>}
              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 idle-timeout
              directive.

       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,
              continue, consists in continuing the operation, trying to
              return as much data as possible.  If the value is set to stop,
              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 report, the search is
              continuated to the end but, in case at least one target
              returned an error code, the first non-success error code is
              returned.

       max-timeout-ops <number>
              Specify the number of consecutive timed out requests, after
              which the connection will be considered faulty and dropped.

       max-pending-ops <number>
              The maximum number of pending requests stored in a
              connection's queue.  The default is 128. When this number is
              exceeded, LDAP_BUSY will be returned to the client.

       max-target-conns <number>
              The maximum number of connections per target. Unlike
              slapd-meta(5), no new connections will be created once this
              number is reached. The default value is 255.

       norefs <NO|yes>
              If 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.

       noundeffilter <NO|yes>
              If 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
              (!(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.

       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
              unwillingToPerform 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.

       pseudoroot-bind-defer {YES|no}
              This directive, when set to yes, causes the authentication to
              the remote servers with the pseudo-root identity (the identity
              defined in each idassert-bind directive) to be deferred until
              actually needed by subsequent operations.  Otherwise, all
              binds as the rootdn are propagated to the targets.

       quarantine <interval>,<num>[;<interval>,<num>[...]]
              Turns on quarantine of URIs that returned 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 interval seconds elapsed
              since last attempt, for exactly num times; then use the next
              pattern.  If num for the last pattern is "+", it retries
              forever; otherwise, no more retries occur.  This directive
              must appear before any target specification; it affects all
              targets with the same pattern.

       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 chase-referrals is
              set to yes.

       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
              protocol-version to 2.  If set before any target
              specification, it affects all targets, unless overridden by
              any per-target directive.

TARGET SPECIFICATION         top

       Target specification starts with a "uri" directive:

       uri <protocol>://[<host>]/<naming context> [...]
              Identical to meta.  See slapd-meta(5) for details.

       acl-authcDN <administrative DN for access control purposes>
              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.  The acl-authcDN identity
              is by no means implicitly used by the proxy when the client
              connects anonymously.

       acl-passwd <password>
              Password used with the acl-authcDN above.

       bind-timeout <microseconds>
              This directive defines the timeout, in microseconds, used when
              polling for response after an asynchronous bind connection.
              See slapd-meta(5) for details.

       chase-referrals {YES|no}
              enable/disable automatic referral chasing, which is delegated
              to the underlying libldap, with rebinding eventually performed
              if the rebind-as-user 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.

       client-pr {accept-unsolicited|DISABLE|<size>}
              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 slapd-meta(5) for
              details.

       default-target [<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 <target> as
              the default one, starting from 1.  Target <target> must be
              defined.

       filter <pattern>
              This directive allows specifying a 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 pattern
              the target is considered while fulfilling the request;
              otherwise the target is ignored. There may be multiple
              occurrences of the filter directive for each target.

       idassert-authzFrom <authz-regexp>
              if defined, selects what local identities are authorized to
              exploit the identity assertion feature.  The string <authz-
              regexp> follows the rules defined for the authzFrom attribute.
              See slapd.conf(5), section related to authz-policy, for
              details on the syntax of this field.

       idassert-bind bindmethod=none|simple|sasl [binddn=<simple DN>]
              [credentials=<simple password>] [saslmech=<SASL mech>]
              [secprops=<properties>] [realm=<realm>]
              [authcId=<authentication ID>] [authzId=<authorization ID>]
              [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
              [starttls=no|yes|critical] [tls_cert=<file>] [tls_key=<file>]
              [tls_cacert=<file>] [tls_cacertdir=<path>]
              [tls_reqcert=never|allow|try|demand]
              [tls_cipher_suite=<ciphers>]
              [tls_protocol_min=<major>[.<minor>]]
              [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 slapd-meta(5) for
              details.

       idle-timeout <time>
              This directive causes a a persistent connection  to  be
              dropped after it  has been idle for the specified time. The
              connection will be re-created the next time it is selected for
              use. A connection is considered idle if no attempts have been
              made by the backend to use it to send a request to the backend
              server. If there are still pending requests in its queue, the
              connection will be dropped after the last request one has
              either received a result or has timed out.

              [<d>d][<h>h][<m>m][<s>[s]]

              where <d>, <h>, <m> and <s> are respectively treated as days,
              hours, minutes and seconds.  If set before any target
              specification, it affects all targets, unless overridden by
              any per-target directive.

       keepalive <idle>:<probes>:<interval>
              The keepalive parameter sets the values of idle, probes, and
              interval used to check whether a socket is alive; idle is the
              number of seconds a connection needs to remain idle before TCP
              starts sending keepalive probes; probes is the maximum number
              of keepalive probes TCP should send before dropping the
              connection; interval is interval in seconds between individual
              keepalive probes.  Only some systems support the customization
              of these values; the keepalive parameter is ignored otherwise,
              and system-wide settings are used.

       map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
              This maps object classes and attributes as in the LDAP
              backend.  See slapd-ldap(5).

       network-timeout <time>
              Sets the network timeout value after which poll(2)/select(2)
              following a connect(2) returns in case of no activity.  The
              value is in seconds, and it can be specified as for
              idle-timeout.  If set before any target specification, it
              affects all targets, unless overridden by any per-target
              directive.

       nretries {forever|never|<nretries>}
              This directive defines how many times a bind should be retried
              in case of temporary failure in contacting a target.  If
              defined before any target specification, it applies to all
              targets (by default, 3 times); the global value can be
              overridden by redefinitions inside each target specification.

       rewrite* ...
              The rewrite options are identical to the meta backend. See the
              REWRITING section of slapd-meta(5).

       subtree-{exclude|include} <rule>
              This directive allows one to indicate what subtrees are
              actually served by a target. See slapd-meta(5) for details.

       suffixmassage <virtual naming context> <real naming context>
              All the directives starting with "rewrite" refer to the
              rewrite engine that has been added to slapd. See slapd-meta(5)
              for details.

       t-f-support {NO|yes|discover}
              enable if the remote server supports absolute filters (see RFC
              4526 for details).  If set to discover, support is detected by
              reading the remote server's root DSE.  If set before any
              target specification, it affects all targets, unless
              overridden by any per-target directive.

       timeout [<op>=]<val> [...]
              This directive allows one to set per-operation timeouts.
              Operations can be

              <op> ::= bind, add, delete, modrdn, modify, compare, search

              See slapd-meta(5) for details.

       tls {[try-]start|[try-]propagate}
              execute the StartTLS extended operation when the connection is
              initialized; only works if the URI directive protocol scheme
              is not ldaps://.  propagate issues the StartTLS operation only
              if the original connection did.  The try- prefix instructs the
              proxy to continue operations if the StartTLS operation failed;
              its use is highly deprecated.  If set before any target
              specification, it affects all targets, unless overridden by
              any per-target directive.

SCENARIOS         top

       See slapd-meta(5) for configuration scenarios.

ACLs         top

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

ACCESS CONTROL         top

       The asyncmeta backend does not honor all ACL semantics as described
       in slapd.access(5).  In general, access checking is delegated to the
       remote server(s).  Only read (=r) access to the entry pseudo-
       attribute and to the other attribute values of the entries returned
       by the search operation is honored, which is performed by the
       frontend.

FILES         top

       ETCDIR/slapd.conf
              default slapd configuration file

SEE ALSO         top

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

AUTHOR         top

       Nadezhda Ivanova, based on back-meta by Pierangelo Masarati.

COLOPHON         top

       This page is part of the OpenLDAP (an open source implementation of
       the Lightweight Directory Access Protocol) project.  Information
       about the project can be found at ⟨http://www.openldap.org/⟩.  If you
       have a bug report for this manual page, see 
       ⟨http://www.openldap.org/its/⟩.  This page was obtained from the
       project's upstream Git repository 
       ⟨git://git.openldap.org/openldap.git⟩ on 2017-03-13.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

OpenLDAP LDVERSION               RELEASEDATE              SLAPD-ASYNCMETA(5)