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

NAME

       slapd-ldap - LDAP backend to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

DESCRIPTION

       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.

CONFIGURATION

       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>]]
              [tls_crlcheck=none|peer|all]
              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  after  a  given  ttl,
              regardless  of  being  idle  or  not.   If  a client connection outlives the remote
              connection, the client will receive LDAP_UNAVAILABLE  when  it  executes  the  next
              operation.

       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

              none|simple|sasl

              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

              u:<user>

              [dn:]<DN>

              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

              override,[non-]prescriptive,proxy-authz-[non-]critical,dn-{authzid|whoami}

              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 after it has been idle  for
              the  specified  time.   If  a client connection outlives the remote connection, the
              client will receive LDAP_UNAVAILABLE when it executes the next operation.

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

       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.   Note,  however,  that  connection  is  not re-
              established automatically after it was dropped due to idle-timeout or conn-ttl .

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

              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>] [tls_crlcheck=none|peer|all]
              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 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.

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

ACCESS CONTROL

       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.

OVERLAYS

       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.

FILES

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

SEE ALSO

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

AUTHOR

       Howard Chu, with enhancements by Pierangelo Masarati