.TH SLAPO-CHAIN 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2005 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2006 The OpenLDAP Foundation, All Rights Reserved.
.\" Copying restrictions apply. See the COPYRIGHT file.
.\" $OpenLDAP$
.SH NAME
.BR slapd (8)
allows automatic referral chasing.
Any time a referral is returned (except for bind operations),
-it chased by using an instance of the ldap backend.
+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 \fIidentity assertion\fP feature of back-ldap
(see
.BR slapd-ldap (5)
for details), which is essentially based on the
-.B proxyAuthz
-control (see \fIdraft-weltman-ldapv3-proxy\fP for details.)
+.B proxied authorization
+control [RFC 4370].
Referral chasing can be controlled by the client by issuing the
\fBchaining\fP control
(see \fIdraft-sermersheim-ldap-chaining\fP for details.)
instantiated by the overlay may assume a special meaning when used
in conjunction with this overlay. They are described in
.BR slapd-ldap (5),
-and they also need be prefixed by
+and they also need to be prefixed by
.BR chain\- .
.TP
.B overlay chain
[Note: this may change in the future, as the \fBldap\fP(5) and
\fBmeta\fP(5) backends might no longer chase referrals on their own.]
.TP
+.B chain-cache-uri {FALSE|true}
+This directive instructs the \fIchain\fP 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
+\fBslapd-ldap\fP(5) before any occurrence of the \fBchain-uri\fP
+directive; basically, they are chained anonymously.
+.TP
.B chain-chaining [resolve=<r>] [continuation=<c>] [critical]
This directive enables the \fIchaining\fP control
(see \fIdraft-sermersheim-ldap-chaining\fP for details)
If the \fBcritical\fP flag affects the control criticality if provided.
[This control is experimental and its support may change in the future.]
.TP
-.B chain-cache-uri {FALSE|true}
-This directive instructs the \fIchain\fP 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
-\fBslapd-ldap\fP(5) before any occurrence of the \fBchain-uri\fP
-directive; in detail, they are essentially chained anonymously.
+.B chain-max-depth <n>
+In case a referral is returned during referral chasing, further chasing
+occurs at most \fB<n>\fP levels deep. Set to \fB1\fP (the default)
+to disable further referral chasing.
+.TP
+.B 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).
.TP
.B chain-uri <ldapuri>
This directive instantiates a new underlying \fIldap\fP database