cleanup and clarify aspects of the overlay usage

diff --git a/doc/man/man5/slapo-chain.5 b/doc/man/man5/slapo-chain.5
index 9f53458f5119f1320682203ba21a8017f6141433..94351d642c3e7546ddacf3239c0275061b967162 100644 (file)
--- a/doc/man/man5/slapo-chain.5
+++ b/doc/man/man5/slapo-chain.5
@@ -15,11 +15,11 @@ 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),
-the referrals are chased with the 
-.B acl-authcDN 
-(if any; see
+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), with the original identity asserted by means of the
+for details), which is essentially based on the
 .B proxyAuthz
 control (see \fIdraft-weltman-ldapv3-proxy\fP for details).
 
@@ -28,36 +28,39 @@ The config directives that are specific to the
 .B chain
 overlay can be prefixed by
 .BR chain\- ,
-to avoid conflicts with directives specific to the underlying database
-or to other stacked overlays.
+to avoid potential conflicts with directives specific to the underlying 
+database or to other stacked overlays.
 
 .LP
 There are no chain overlay specific directives; however, directives 
-related to the instance of the ldap backend that is implicitly 
-instantiated by the overlay may assume a special meaning when used 
-in conjuction with this overlay.
+related to the \fIldap\fP database that is implicitly instantiated 
+by the overlay may assume a special meaning when used in conjuction 
+with this overlay.  They are described in
+.BR slapd-ldap (5).
 .TP
 .B overlay chain
 This directive adds the chain overlay to the current backend.
-The chain overlay may be used with any backend but is intended 
-for use with local storage backends that may return referrals.
-It is useless in conjunction with the ldap and meta backends
-because they exploit the libldap specific referral chase feature.
+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 \fIldap\fP and \fImeta\fP backends
+because they already exploit the libldap specific referral chase feature.
 .TP
 .B chain-uri <ldapuri>
 This directive instructs the underlying ldap database about which
-URI to contact to follow referrals.
-If not given, the referral itself is parsed, and the protocol/host/port
+URI to contact to chase referrals.
+If not present, the referral itself is parsed, and the protocol/host/port
 portions are used to establish a connection.
 
 .LP
-Directives for configuring the underlying ldap database must also be given, 
-as shown here:
+Directives for configuring the underlying ldap database mmay also 
+be required, as shown here:
 .LP
 .RS
 .nf
-chain-acl-authcDN      cn=Auth,dc=example,dc=com
-chain-acl-passwd       secret
+chain-idassert-method  "simple"
+chain-idassert-authcDN "cn=Auth,dc=example,dc=com"
+chain-idassert-passwd  "secret"
+chain-idassert-mode    "self"
 .fi
 .RE
 .LP