Provided by: slapd_2.5.13+dfsg-1ubuntu1_amd64 bug


       slapd-ldap - LDAP backend to slapd




       The  LDAP  backend  to  slapd(8)  is not an actual database; instead it acts as a proxy to
       forward incoming requests to another LDAP server. While processing requests it  will  also
       chase  referrals,  so  that referrals are fully processed instead of being returned to the
       slapd client.

       Sessions that explicitly Bind to the back-ldap database always create  their  own  private
       connection  to  the  remote  LDAP server. Anonymous sessions will share a single anonymous
       connection to the remote server. For sessions bound through other mechanisms, all sessions
       with  the  same  DN  will  share the same connection. This connection pooling strategy can
       enhance the proxy's efficiency by reducing  the  overhead  of  repeatedly  making/breaking
       multiple connections.

       The  ldap  database  can  also act as an information service, i.e. the identity of locally
       authenticated clients is asserted to the remote server, possibly in  some  modified  form.
       For  this purpose, the proxy binds to the remote server with some administrative identity,
       and, if required, authorizes the asserted identity.  See the idassert-* rules below.   The
       administrative  identity  of the proxy, on the remote server, must be allowed to authorize
       by means of appropriate authzTo rules; see slapd.conf(5) for details.

       The proxy instance of slapd(8) must contain schema  information  for  the  attributes  and
       objectClasses used in filters, request DNs and request-related data in general.  It should
       also contain schema information for the data returned by the proxied server.   It  is  the
       responsibility  of  the  proxy administrator to keep the schema of the proxy lined up with
       that of the proxied server.

       Note: When looping back to the same instance of slapd(8), each connection requires  a  new
       thread;  as  a  consequence, the slapd(8) threads parameter may need some tuning. In those
       cases, one may consider using slapd-relay(5) instead, which performs the relayed operation
       internally and thus reuses the same connection.


       These  slapd.conf options apply to the LDAP backend database.  That is, they must follow a
       "database ldap" line and come before any subsequent "backend" or "database" lines.   Other
       database options are described in the slapd.conf(5) manual page.

       Note: In early versions of back-ldap it was recommended to always set

              lastmod  off

       for  ldap and meta databases.  This was required because operational attributes related to
       entry creation and modification should not be proxied, as they could be mistakenly written
       to  the  target  server(s), generating an error.  The current implementation automatically
       sets lastmod to off, so its use is redundant and should be omitted.

       uri <ldapurl>
              LDAP server to use.  Multiple URIs  can  be  set  in  a  single  ldapurl  argument,
              resulting  in  the underlying library automatically calling the first server of the
              list that responds, e.g.

              uri "ldap://host/ ldap://backup-host/"

              The URI list is space- or comma-separated.  Whenever the server  that  responds  is
              not  the first one in the list, the list is rearranged and the responsive server is
              moved to the head, so that it will be first contacted the next  time  a  connection
              needs to be created.

       acl-bind   bindmethod=simple|sasl  [binddn=<simple  DN>]  [credentials=<simple  password>]
              [saslmech=<SASL        mech>]        [secprops=<properties>]        [realm=<realm>]
              [authcId=<authentication          ID>]         [authzId=<authorization         ID>]
              [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>]]
              Allows one to define the parameters of the authentication method that is internally
              used  by  the  proxy  to  collect  info  related to access control, and whenever an
              operation occurs with the identity of the rootdn of the LDAP proxy  database.   The
              identity  defined  by this directive, according to the properties associated to the
              authentication method, 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 default is to use simple bind, with empty binddn and credentials,
              which means that the related operations will be performed anonymously.  If not set,
              and if idassert-bind is  defined,  this  latter  identity  is  used  instead.   See
              idassert-bind for details.

              The  connection between the proxy database and the remote server associated to this
              identity is cached regardless of the lifespan of the client-proxy  connection  that
              first established it.

              This  identity  is  not  implicitly  used  by  the  proxy  when the client connects
              anonymously.  The idassert-bind feature, instead, in some cases can be  crafted  to
              implement  that  behavior,  which  is  intrinsically unsafe and should be used with
              extreme care.

              The TLS settings default to the same as the main slapd  TLS  settings,  except  for
              tls_reqcert which defaults to "demand", and tls_reqsan which defaults to "allow".

       cancel {ABANDON|ignore|exop[-discover]}
              Defines  how  to handle operation cancellation.  By default, abandon is invoked, so
              the operation is abandoned immediately.  If set to ignore, no action is  taken  and
              any further response is ignored; this may result in further response messages to be
              queued for that connection, so it is recommended that long lasting connections  are
              timed  out  either  by  idle-timeout  or conn-ttl, so that resources eventually get
              released.  If set to exop, a cancel operation (RFC 3909) is  issued,  resulting  in
              the  cancellation  of  the current operation; the cancel operation waits for remote
              server response, so its use may not  be  recommended.   If  set  to  exop-discover,
              support of the cancel extended operation is detected by reading the remote server's
              root DSE.

       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.

       conn-pool-max <int>
              This directive defines the maximum size of the privileged connections pool.

       conn-ttl <time>
              This directive causes a cached connection to be dropped and recreated after a given
              ttl, regardless of being idle or not.

       idassert-authzFrom <authz-regexp>
              if  defined,  selects  what local identities are authorized to exploit the identity
              assertion feature.  The string <authz-regexp> mostly 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.  This parameter differs  from  the  documented
              behavior  in  relation  to  the  meaning  of *, which in this case allows anonymous
              rather than denies.

       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=<version>] [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.  Direct binds are always proxied without any idassert handling.

              The  identity  defined by this directive, according to the properties associated to
              the authentication method, is supposed to have auth access on the target server  to
              attributes  used  on  the  proxy  for  authentication  and authorization, and to be
              allowed to authorize the users.  This requires to have proxyAuthz privileges  on  a
              wide  set  of  DNs,  e.g.   authzTo=dn.subtree:"",  and  the  remote server to have
              authz-policy set to to or both.  See slapd.conf(5) for details on these  statements
              and for remarks and drawbacks about their usage.  The supported bindmethods are


              where none is the default, i.e. no identity assertion is performed.

              The  authz  parameter  is  used  to  instruct  the SASL bind to exploit native SASL
              authorization, if available; since connections are cached, this should only be used
              when  authorizing  with  a  fixed identity (e.g. by means of the authzDN or authzID
              parameters).  Otherwise, the  default  proxyauthz  is  used,  i.e.  the  proxyAuthz
              control (Proxied Authorization, RFC 4370) is added to all operations.

              The supported modes are:

              <mode> := {legacy|anonymous|none|self}

              If  <mode>  is  not present, and authzId is given, the proxy always authorizes that
              identity.  <authorization ID> can be



              The former is supposed to be expanded by the remote server according to  the  authz
              rules;  see  slapd.conf(5) for details.  In the latter case, whether or not the dn:
              prefix is present, the string must pass DN validation and normalization.

              The default mode is legacy, which implies that the  proxy  will  either  perform  a
              simple  bind  as  the authcDN or a SASL bind as the authcID and assert the client's
              identity when it is not anonymous.  The other  modes  imply  that  the  proxy  will
              always  either  perform a simple bind as the authcDN or a SASL bind as the authcID,
              unless restricted by idassert-authzFrom  rules  (see  below),  in  which  case  the
              operation  will  fail;  eventually, it will assert some other identity according to
              <mode>.  Other identity assertion modes are anonymous and self, which  respectively
              mean  that  the  empty or the client's identity will be asserted; none, which means
              that no proxyAuthz control will be used, so the authcDN  or  the  authcID  identity
              will be asserted.  For all modes that require the use of the proxyAuthz control, on
              the remote server the proxy identity must have appropriate authzTo permissions,  or
              the  asserted  identities  must  have  appropriate  authzFrom  permissions.   Note,
              however, that  the  ID  assertion  feature  is  mostly  useful  when  the  asserted
              identities do not exist on the remote server.

              Flags can be


              When  the  override  flag  is  used,  identity  assertion takes place even when the
              database is authorizing for the identity of the client, i.e. after binding with the
              provided  identity,  and  thus  authenticating  it, the proxy performs the identity
              assertion using the configured identity and authentication method.

              When  the  prescriptive  flag  is  used  (the  default),   operations   fail   with
              inappropriateAuthentication  for those identities whose assertion is not allowed by
              the idassert-authzFrom patterns.  If the non-prescriptive flag is used,  operations
              are  performed  anonymously  for those identities whose assertion is not allowed by
              the idassert-authzFrom patterns.

              When the proxy-authz-non-critical  flag  is  used  (the  default),  the  proxyAuthz
              control   is   not   marked  as  critical,  in  violation  of  RFC  4370.   Use  of
              proxy-authz-critical is recommended.

              When the dn-authzid flag is used, RFC 3829 LDAP Authorization Identity Controls  is
              used  to  retrieve the identity associated to the SASL identity; when the dn-whoami
              flag is used, RFC 4532 LDAP Who am I? Operation is performed after the bind for the
              same purpose.

              The  TLS  settings  default  to the same as the main slapd TLS settings, except for
              tls_reqcert which defaults to "demand", and tls_reqsan which defaults to "allow".

              The identity associated to this directive is also used  for  privileged  operations
              whenever idassert-bind is defined and acl-bind is not.  See acl-bind for details.

              idassert-passthru <authz-regexp>
                     if  defined,  selects  what  local  identities bypass the identity assertion
                     feature.  Those identities need to be known by the remote host.  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.

              idle-timeout <time>
                     This  directive  causes a cached connection to be dropped an recreated after
                     it has been idle for the specified time.

              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.

              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.

              norefs <NO|yes>
                     If yes, do not return search reference  responses.   By  default,  they  are
                     returned unless request is LDAPv2.

              omit-unknown-schema <NO|yes>
                     If  yes, do not return objectClasses or attributes that are not known to the
                     local server.  The default is to return all schema elements.

              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.

              onerr {CONTINUE|stop}
                     This  directive  allows  one  to  select  the  behavior  in case an error is
                     returned by the remote server  during  a  search.   The  default,  continue,
                     consists  in  returning  success.  If the value is set to stop, the error is
                     returned to the client.

              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.

              proxy-whoami {NO|yes}
                     Turns on proxying of the WhoAmI extended operation. If this option is given,
                     back-ldap  will  replace  slapd's  original  WhoAmI routine with its own. On
                     slapd sessions that were authenticated by back-ldap, the WhoAmI request will
                     be  forwarded  to  the remote LDAP server. Other sessions will be handled by
                     the local slapd, as before. This option is mainly useful in conjunction with
                     Proxy Authorization.

              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.  The process can be restarted by resetting
                     the  olcDbQuarantine  attribute  of  the database entry in the configuration

              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.

              single-conn {NO|yes}
                     Discards current cached connection when the client rebinds.

              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.

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

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

                     The  overall  duration  of  the search operation is controlled either by the
                     timelimit parameter or by server-side enforced time  limits  (see  timelimit
                     and  limits  in slapd.conf(5) for details).  This timeout parameter controls
                     how long the target can be irresponsive before  the  operation  is  aborted.
                     Timeout  is  meaningless  for  the remaining operations, unbind and abandon,
                     which do not imply  any  response,  while  it  is  not  yet  implemented  in
                     currently  supported extended operations.  If no operation is specified, the
                     timeout val affects all supported operations.

                     Note: if the timelimit is exceeded, the operation is cancelled (according to
                     the  cancel  directive); the protocol does not provide any means to rollback
                     operations, so the client will not be  notified  about  the  result  of  the
                     operation,  which  may  eventually succeeded or not.  In case the timeout is
                     exceeded during a bind operation, the connection is destroyed, according  to

                     Note:  in some cases, this backend may issue binds prior to other operations
                     (e.g. to bind anonymously or with some prescribed identity according to  the
                     idassert-bind  directive).   In this case, the timeout of the operation that
                     resulted in the bind is used.

              tls   {none|[try-]start|[try-]propagate|ldaps}   [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>]
                     Specify TLS settings for 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

                     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

              use-temporary-conn {NO|yes}
                     when set to yes, create a temporary connection whenever competing with other
                     threads  for  a  shared  one; otherwise, wait until the shared connection is


       The ldap 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.


       The  LDAP  backend  provides  basic  proxying functionalities to many overlays.  The chain
       overlay,  described  in  slapo-chain(5),  and  the  translucent  overlay,   described   in
       slapo-translucent(5), deserve a special mention.

       Conversely,  there  are  many  overlays  that  are  best used in conjunction with the LDAP
       backend.  The proxycache overlay allows caching of LDAP search  requests  (queries)  in  a
       local database.  See slapo-pcache(5) for details.  The rwm overlay provides DN rewrite and
       attribute/objectClass mapping capabilities to the underlying database.   See  slapo-rwm(5)
       for details.


              default slapd configuration file


       slapd.conf(5),    slapd-config(5),    slapd-meta(5),    slapo-chain(5),   slapo-pcache(5),
       slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).


       Howard Chu, with enhancements by Pierangelo Masarati