Rework CAVEATS

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index 34afa8e692388e4fa6383f76e1ca856330a3f245..215357e9aa11f943be71b74d5974c5d3843cca16 100644 (file)
--- a/doc/man/man5/slapd.access.5
+++ b/doc/man/man5/slapd.access.5
@@ -429,42 +429,36 @@ privileges to authenticated clients.
 It is strongly recommended to explicitly use the most appropriate
 DN 
 .BR style ,
-for performance (avoid unrequired regex matching when
-an exact match suffices) but also to avoid possible 
-misimplementations of the access rules.
-In fact, a rule of the form
+to avoid possible 
+incorrect specifications of the access rules as well
+as for performance (avoid unrequired regex matching when
+an exact match suffices) reasons.
+.LP
+An adminisistrator might create a rule of the form:
 .LP
 .nf
        access to dn="dc=example,dc=com"
                by ...
 .fi
 .LP
-implies that all the subtree "dc=example,dc=com" matches, and the
-match is done using a regex. 
-.LP
-.nf
-access to dn.subtree="dc=example,dc=com"
-       by ...
-.fi
-.LP
-would be far more appropriate.
+expecting it to match all entries in the subtree "dc=example,dc=com".
+However, this rule actually matches any DN which contains anywhere
+the substring "dc=example,dc=com".  That is, the rule matches both
+"uid=joe,dc=example,dc=com" and "dc=example,dc=com,uid=joe".
 .LP
-Another quirk is related to the 
-.B by
-clause:
-a rule of the form
+To match the desired subtree, the rule would be more precisely
+written:
 .LP
 .nf
-       access to *
-               by dn="cn=User,dc=example,dc=com" write
+       access to dn.regex="^(.+,)?dc=example,dc=com$$"
+               by ...
 .fi
 .LP
-gives write access to every DN below "cn=User,dc=example,dc=com";
-if only that DN should have write access, the correct rule would be
+For performance reasons, it would be better to use the subtree style.
 .LP
 .nf
-       access to *
-               by dn.exact="cn=User,dc=example,dc=com" write
+access to dn.subtree="dc=example,dc=com"
+       by ...
 .fi
 .LP
 .SH FILES