Provided by: slapd_2.4.45+dfsg-1ubuntu1.11_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, slapd(8) must be compiled with thread support, and the 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_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  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.  This directive obsoletes acl-authcDN, and acl-passwd.

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

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

              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.

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

              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.

              This directive  obsoletes  idassert-authcDN,  idassert-passwd,  idassert-mode,  and
              idassert-method.

       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.

       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.

       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.

       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       {[try-]start|[try-]propagate|ldaps}      [tls_cert=<file>]      [tls_key=<file>]
              [tls_cacert=<file>]   [tls_cacertdir=<path>]   [tls_reqcert=never|allow|try|demand]
              [tls_cipher_suite=<ciphers>] [tls_crlcheck=none|peer|all]
              Specify  the  use  of  TLS  when  a regular connection is initialized. The StartTLS
              extended operation will be  used  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.  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 not recommended.

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

       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.

BACKWARD COMPATIBILITY

       The LDAP backend has been heavily reworked between releases 2.2 and 2.3, and  subsequently
       between  2.3  and  2.4.   As  a  side-effect, some of the traditional directives have been
       deprecated and should be no longer used, as they might disappear in future releases.

       acl-authcDN <administrative DN for access control purposes>
              Formerly known as the binddn, it is the DN that is used to query the target  server
              for  acl  checking;  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.  The idassert-* feature can be used (at own risk)  for
              that purpose instead.

              This  directive  is obsoleted by the binddn arg of acl-bind when bindmethod=simple,
              and will be dismissed in the future.

       acl-passwd <password>
              Formerly known as the bindpw, it is the password used with  the  above  acl-authcDN
              directive.   This  directive  is  obsoleted by the credentials arg of acl-bind when
              bindmethod=simple, and will be dismissed in the future.

       idassert-authcDN <administrative DN for proxyAuthz purposes>
              DN which is used to propagate the client's identity to the target by means  of  the
              proxyAuthz  control  when  the  client  does not belong to the DIT fragment that is
              being proxied by back-ldap.  This directive is  obsoleted  by  the  binddn  arg  of
              idassert-bind when bindmethod=simple, and will be dismissed in the future.

       idassert-passwd <password>
              Password  used with the idassert-authcDN above.  This directive is obsoleted by the
              crendentials arg of idassert-bind when bindmethod=simple, and will be dismissed  in
              the future.

       idassert-mode <mode> [<flags>]
              defines  what  type  of identity assertion is used.  This directive is obsoleted by
              the mode arg of idassert-bind, and will be dismissed in the future.

       idassert-method <method> [<saslargs>]
              This directive is obsoleted by the bindmethod arg of  idassert-bind,  and  will  be
              dismissed in the future.

       port <port>
              this directive is no longer supported.  Use the uri directive as described above.

       server <hostname[:port]>
              this directive is no longer supported.  Use the uri directive as described above.

       suffixmassage, map, rewrite*
              These  directives  are no longer supported by back-ldap; their functionality is now
              delegated to the rwm overlay.  Essentially, add a statement

              overlay rwm

              first, and prefix all rewrite/map statements  with  rwm-  to  obtain  the  original
              behavior.  See slapo-rwm(5) for details.

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