clarify DN regex match quirks

diff --git a/doc/man/man5/slapd.access.5 b/doc/man/man5/slapd.access.5
index ef4111db4eaac7b9796d57d4b24ab5371dfad60f..34afa8e692388e4fa6383f76e1ca856330a3f245 100644 (file)
--- a/doc/man/man5/slapd.access.5
+++ b/doc/man/man5/slapd.access.5
@@ -425,6 +425,48 @@ or the (even more silly) example
 .LP
 which grants everybody search and compare privileges, and adds read
 privileges to authenticated clients.
 .LP
 which grants everybody search and compare privileges, and adds read
 privileges to authenticated clients.

+.SH CAVEATS
+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
+.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.
+.LP
+Another quirk is related to the 
+.B by
+clause:
+a rule of the form
+.LP
+.nf
+       access to *
+               by dn="cn=User,dc=example,dc=com" write
+.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
+.LP
+.nf
+       access to *
+               by dn.exact="cn=User,dc=example,dc=com" write
+.fi
+.LP

 .SH FILES
 .TP
 ETCDIR/slapd.conf
 .SH FILES
 .TP
 ETCDIR/slapd.conf