reflect recent code changes

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.

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