From 567ab7727550d46c92b501e76d1b19b42e478b99 Mon Sep 17 00:00:00 2001
From: Pierangelo Masarati <ando@openldap.org>
Date: Sat, 19 Nov 2005 23:40:48 +0000
Subject: [PATCH] reflect recent code changes
---
doc/man/man5/slapd.conf.5 | 3 +-
doc/man/man5/slapo-chain.5 | 72 ++++++++++++++++++++++++++------------
2 files changed, 51 insertions(+), 24 deletions(-)
diff --git a/doc/man/man5/slapd.conf.5 b/doc/man/man5/slapd.conf.5
index 580a084765..a552f4db8c 100644
--- a/doc/man/man5/slapd.conf.5
+++ b/doc/man/man5/slapd.conf.5
@@ -1758,7 +1758,8 @@ By default it is not built.
.B chain
Chaining.
This overlay allows automatic referral chasing when a referral would
-have been returned.
+have been returned, either when configured by the server or when
+requested by the client.
.TP
.B denyop
Deny Operation.
diff --git a/doc/man/man5/slapo-chain.5 b/doc/man/man5/slapo-chain.5
index cba284dfda..96cc0d4904 100644
--- a/doc/man/man5/slapo-chain.5
+++ b/doc/man/man5/slapo-chain.5
@@ -13,7 +13,7 @@ overlay to
.BR 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.
+it 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
@@ -21,12 +21,15 @@ by means of the \fIidentity assertion\fP feature of back-ldap
.BR slapd-ldap (5)
for details), which is essentially based on the
.B proxyAuthz
-control (see \fIdraft-weltman-ldapv3-proxy\fP for details).
+control (see \fIdraft-weltman-ldapv3-proxy\fP for details.)
+Referral chasing can be controlled by the client by issuing the
+\fBchaining\fP control
+(see \fIdraft-sermersheim-ldap-chaining\fP for details.)
.LP
The config directives that are specific to the
.B chain
-overlay can be prefixed by
+overlay are prefixed by
.BR chain\- ,
to avoid potential conflicts with directives specific to the underlying
database or to other stacked overlays.
@@ -36,7 +39,9 @@ There are very few chain overlay specific directives; however, directives
related to the instances of the \fIldap\fP 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
-.BR slapd-ldap (5).
+.BR slapd-ldap (5),
+and they also need be prefixed by
+.BR chain\- .
.TP
.B overlay chain
This directive adds the chain overlay to the current backend.
@@ -47,17 +52,24 @@ backends because they already exploit the libldap specific referral chase
feature.
[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-chaining [resolve=<r>] [continuation=<c>] [critical]
-.\"This directive enables the \fIchaining\fP control
-.\"(see \fIdraft-sermersheim-ldap-chaining\fP for details)
-.\"with the desired resolve and continuation behaviors and criticality.
-.\"The values \fBr\fP and \fBc\fP can be any of
-.\".BR chainingPreferred ,
-.\".BR chainingRequired ,
-.\".BR referralsPreferred ,
-.\".BR referralsRequired .
-.\"[This control is experimental and its support may change in the future.]
+.TP
+.B chain-chaining [resolve=<r>] [continuation=<c>] [critical]
+This directive enables the \fIchaining\fP control
+(see \fIdraft-sermersheim-ldap-chaining\fP for details)
+with the desired resolve and continuation behaviors and criticality.
+The \fBresolve\fP parameter refers to the behavior while discovering
+a resource, namely when accessing the object indicated by the request DN;
+the \fBcontinuation\fP 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 \fBr\fP and \fBc\fP can be any of
+.BR chainingPreferred ,
+.BR chainingRequired ,
+.BR referralsPreferred ,
+.BR referralsRequired .
+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-uris {FALSE|true}
This directive instructs the \fIchain\fP overlay to cache
@@ -68,18 +80,32 @@ to be reused for later chaining.
This directive instantiates a new underlying \fIldap\fP database
and instructs it about which URI to contact to chase referrals.
As opposed to what stated in \fBslapd-ldap\fP(5), only one URI
-can appear after this directive.
-
+can appear after this directive; all subsequent \fBslapd-ldap\fP(5)
+directives prefixed by \fBchain-\fP refer to this specific instance
+of a remote server.
.LP
+
Directives for configuring the underlying ldap database may also
-be required, as shown here:
+be required, as shown in this example:
.LP
.RS
.nf
-chain-idassert-bind bindmethod="simple"
- binddn="cn=Auth,dc=example,dc=com"
- credentials="secret"
- mode="self"
+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"
+
.fi
.RE
.LP
@@ -91,7 +117,7 @@ to define multiple "trusted" URIs where operations with
\fIidentity assertion\fP are chained.
All URIs not listed in the configuration are chained anonymously.
All \fBslapd-ldap\fP(5) directives appearing before the first
-occurrence of \fBchain-uri\fP are shared among all operations,
+occurrence of \fBchain-uri\fP are inherited by all URIs,
unless specifically overridden inside each URI configuration.
.SH FILES
.TP
--
GitLab