Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

slapd-ldap (5oldap)

Name

slapd-ldap - LDAP backend to slapd

Synopsis

/etc/openldap/slapd.conf

Description

SLAPD-LDAP(5oldap)                                          SLAPD-LDAP(5oldap)



NAME
       slapd-ldap - LDAP backend to slapd

SYNOPSIS
       /etc/openldap/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 ses-
       sions 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  connec-
       tion 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 per-
       forms the relayed operation internally and thus reuses the same connec-
       tion.


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  lda-
              purl 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.   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", 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-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

              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", 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.

              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.


       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.


       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.

              The  first  parameter only applies to ldap:// connections and so
              at the moment, none and ldaps are equivalent.

              With propagate, the proxy issues 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.


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/openldap/slapd.conf
              default slapd configuration file


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-------------------------------+
       |ATTRIBUTE TYPE |       ATTRIBUTE VALUE         |
       +---------------+-------------------------------+
       |Availability   | service/network/ldap/openldap |
       +---------------+-------------------------------+
       |Stability      | Pass-through uncommitted      |
       +---------------+-------------------------------+

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



NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source                was                downloaded                from
       ftp://ftp.openldap.org/pub/OpenLDAP/openldap-
       release/openldap-2.4.57.tgz.

       Further information about this software can be found on the open source
       community website at http://www.openldap.org/.



OpenLDAP 2.4.57                   2021/01/18                SLAPD-LDAP(5oldap)