add support for subtree-include (ITS#6801); improve support for subtree-exclude

[openldap] / doc / man / man5 / slapd-meta.5

diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5
index 301d3584171c0908805bcfd815921b34d03429fc..2d984d5f37d7c57a276c3cc353e8f698b2c9be82 100644 (file)
--- a/doc/man/man5/slapd-meta.5
+++ b/doc/man/man5/slapd-meta.5
@@ -570,13 +570,58 @@ specification.
 The rewrite options are described in the "REWRITING" section.
 
 .TP
-.B subtree\-exclude "<DN>"
-This directive instructs back-meta to ignore the current target
-for operations whose requestDN is subordinate to
-.BR DN .
+.B subtree\-{exclude|include} "<rule>"
+This directive allows to indicate what subtrees are actually served
+by a target.
+The syntax of the supported rules is
+
+\fB<rule>: [dn[.<style>]:]<pattern>\fP
+
+\fB<style>: subtree|children|regex\fP
+
+When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP
+the \fB<pattern>\fP is a DN that must be within the naming context
+served by the target.
+When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a
+.BR regex (5)
+pattern.
+If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP
+is implicitly assumed for backward compatibility.
+
+In the
+.B subtree\-exclude
+form if the \fIrequest DN\fP matches at least one rule,
+the target is not considered while fulfilling the request;
+otherwise, the target is considered based on the value of the \fIrequest DN\fP.
+When the request is a search, also the \fIscope\fP is considered.
+
+In the
+.B subtree\-include
+form if the \fIrequest DN\fP matches at least one rule,
+the target is considered while fulfilling the request;
+otherwise the target is ignored.
+
+.LP
+.RS
+.nf
+    |  match  | exclude |
+    +---------+---------+-------------------+
+    |    T    |    T    | not candidate     |
+    |    F    |    T    | continue checking |
+    +---------+---------+-------------------+
+    |    T    |    F    | candidate         |
+    |    F    |    F    | not candidate     |
+    +---------+---------+-------------------+
+.fi
+
+.RE
+.RS
 There may be multiple occurrences of the
 .B subtree\-exclude
-directive for each of the targets.
+or
+.B subtree\-include
+directive for each of the targets, but they are mutually exclusive.
+.RE
 
 .TP
 .B suffixmassage "<virtual naming context>" "<real naming context>"