NAME

       slapo-chain - chain overlay to slapd

SYNOPSIS

       /etc/ldap/slapd.conf

DESCRIPTION

       The  chain  overlay to slapd(8) allows automatic referral chasing.  Any time a referral is
       returned (except for bind operations), it is chased by  using  an  instance  of  the  ldap
       backend.   If operations are performed with an identity (i.e. after a bind), that identity
       can be asserted while chasing the referrals by means of the identity assertion feature  of
       back-ldap  (see  slapd-ldap(5)  for  details),  which  is essentially based on the proxied
       authorization control [RFC 4370].  Referral chasing can be controlled  by  the  client  by
       issuing the chaining control (see draft-sermersheim-ldap-chaining for details.)

       The  config  directives  that are specific to the chain overlay are prefixed by chain-, to
       avoid potential conflicts with directives specific to the underlying database or to  other
       stacked overlays.

       There  are  very few chain overlay specific directives; however, directives related to the
       instances of the ldap backend that may be  implicitly  instantiated  by  the  overlay  may
       assume  a  special meaning when used in conjunction with this overlay.  They are described
       in slapd-ldap(5), and they also need to be prefixed by chain-.

       Note: this overlay is built into the ldap backend; it is not a separate module.

       overlay chain
              This directive adds the chain overlay to the current backend.   The  chain  overlay
              may  be used with any backend, but it is mainly intended for use with local storage
              backends that may  return  referrals.   It  is  useless  in  conjunction  with  the
              slapd-ldap  and  slapd-meta  backends  because  they  already  exploit  the libldap
              specific referral chase feature.  [Note: this may change  in  the  future,  as  the
              ldap(5) and meta(5) backends might no longer chase referrals on their own.]

       chain-cache-uri {FALSE|true}
              This  directive instructs the chain overlay to cache connections to URIs parsed out
              of referrals that are not predefined, to be reused for later chaining.  These  URIs
              inherit  the  properties  configured  for  the  underlying slapd-ldap(5) before any
              occurrence of the chain-uri directive; basically, they are chained anonymously.

       chain-chaining [resolve=<r>] [continuation=<c>] [critical]
              This directive enables the chaining  control  (see  draft-sermersheim-ldap-chaining
              for  details)  with the desired resolve and continuation behaviors and criticality.
              The resolve parameter refers to the behavior while discovering a  resource,  namely
              when  accessing  the object indicated by the request DN; the continuation parameter
              refers to the behavior while  handling  intermediate  responses,  which  is  mostly
              significant  for  the  search  operation,  but  may affect extended operations that
              return intermediate responses.  The values r and c can be any of chainingPreferred,
              chainingRequired,  referralsPreferred,  referralsRequired.   If  the  critical flag
              affects the control criticality if provided.  [This control is experimental and its
              support may change in the future.]

       chain-max-depth <n>
              In  case  a referral is returned during referral chasing, further chasing occurs at
              most <n> levels deep.  Set to 1 (the default) to disable further referral chasing.

       chain-return-error {FALSE|true}
              In case referral chasing fails, the real error is returned instead of the  original
              referral.   In  case  multiple  referral  URIs are present, only the first error is
              returned.  This behavior  may  not  be  always  appropriate  nor  desirable,  since
              failures  in  referral  chasing  might  be better resolved by the client (e.g. when
              caused by distributed authentication issues).

       chain-uri <ldapuri>
              This directive instantiates a new underlying ldap database and instructs  it  about
              which   URI  to  contact  to  chase  referrals.   As  opposed  to  what  stated  in
              slapd-ldap(5), only one  URI  can  appear  after  this  directive;  all  subsequent
              slapd-ldap(5)  directives  prefixed  by chain- refer to this specific instance of a
              remote server.

       Directives for configuring the underlying ldap database may also be required, as shown  in
       this example:

              overlay                 chain
              chain-rebind-as-user    FALSE

              chain-uri               "ldap://ldap1.example.com"
              chain-rebind-as-user    TRUE
              chain-idassert-bind     bindmethod="simple"
                                      binddn="cn=Auth,dc=example,dc=com"
                                      credentials="secret"
                                      mode="self"

              chain-uri               "ldap://ldap2.example.com"
              chain-idassert-bind     bindmethod="simple"
                                      binddn="cn=Auth,dc=example,dc=com"
                                      credentials="secret"
                                      mode="none"

       Any  valid  directives  for  the ldap database may be used; see slapd-ldap(5) for details.
       Multiple occurrences of the chain-uri directive may appear, to define  multiple  "trusted"
       URIs  where  operations  with  identity assertion are chained.  All URIs not listed in the
       configuration are chained anonymously.  All slapd-ldap(5) directives appearing before  the
       first  occurrence  of  chain-uri are inherited by all URIs, unless specifically overridden
       inside each URI configuration.

FILES

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

SEE ALSO

       slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd(8).

AUTHOR

       Originally implemented by Howard Chu; extended by Pierangelo Masarati.