Provided by: slapd_2.6.6+dfsg-1~exp1ubuntu1_amd64 bug

NAME

       slapd-asyncmeta - asynchronous metadirectory backend to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

DESCRIPTION

       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-pool-max   ,  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, a new connection is chosen using round-robin scheduling.

       Overlays:

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

EXAMPLES

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

CONFIGURATION

       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

       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 continued 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

       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_reqsan=never|allow|try|demand]                    [tls_cipher_suite=<ciphers>]
              [tls_ecname=<names>]                           [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.

       tcp-user-timeout <milliseconds>
              If non-zero, corresponds to the TCP_USER_TIMEOUT set  on  the  target  connections,
              overriding   the   operating   system  setting.   Only  some  systems  support  the
              customization of this parameter, it 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 while sending an operation  to  the  remote  target.
              The  value is in milliseconds, 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 forwarding an operation should be retried in
              case of temporary failure in contacting a target. The  number  of  retries  is  per
              operation,  so  if a bind to the target is necessary first, the remaining number is
              decremented. 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 <local suffix> <remote suffix>
              slapd-asyncmeta does not support the rewrite engine  used  by  the  LDAP  and  META
              backends.   suffixmassage  can be used to perform DN suffix rewriting, the same way
              as the obsoleted suffixmassage directive previously used by the LDAP backend.

       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

              By default, the timeout for all operations is 2 seconds.

              See slapd-meta(5) for details.

       tls {none|[try-]start|[try-]propagate|ldaps}
              B     [starttls=no]    [tls_cert=<file>]    [tls_key=<file>]    [tls_cacert=<file>]
              [tls_cacertdir=<path>]                         [tls_reqcert=never|allow|try|demand]
              [tls_reqsan=never|allow|try|demand]                    [tls_cipher_suite=<ciphers>]
              [tls_ecname=<names>] [tls_crlcheck=none|peer|all]
              Specify TLS settings regular connections.

              If the first parameter is not "none" then this configures the TLS  settings  to  be
              used  for  regular  connections.  The StartTLS extended operation will be used when
              establishing the connection unless the URI directive protocol scheme  is  ldaps://.
              In  that  case  this  keyword may only be set to "ldaps" and the StartTLS operation
              will not be used.

              With propagate, the proxy issues  the  StartTLS  operation  only  if  the  original
              connection has a TLS layer set up.  The try- prefix instructs the proxy to continue
              operations if the StartTLS operation failed; its use is not recommended.

              The TLS settings default to the same as the main slapd  TLS  settings,  except  for
              tls_reqcert  which  defaults to "demand", tls_reqsan which defaults to "allow", and
              starttls which is overshadowed by the first keyword and thus ignored.

              If set before any target specification, it affects all targets,  unless  overridden
              by any per-target directive.

SCENARIOS

       See slapd-meta(5) for configuration scenarios.

ACLs

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

ACCESS CONTROL

       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

       /etc/ldap/slapd.conf
              default slapd configuration file

SEE ALSO

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

AUTHOR

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