# slapd-ldap

## NAME



           slapd-ldap - LDAP backend to slapd
    


## SYNOPSIS



           ETCDIR/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



           ETCDIR/slapd.conf
                  default slapd configuration file
    


* * *