From 8ea2f6e1576e089ea0503f716534edc4ab6a7da8 Mon Sep 17 00:00:00 2001
From: Pierangelo Masarati <ando@openldap.org>
Date: Thu, 15 Apr 2004 01:16:53 +0000
Subject: [PATCH] further clarify size limits

---
 doc/man/man5/slapd.conf.5 | 397 ++++++++++++++++++++------------------
 1 file changed, 208 insertions(+), 189 deletions(-)

diff --git a/doc/man/man5/slapd.conf.5 b/doc/man/man5/slapd.conf.5
index 5857fb2889..e642a476f5 100644
--- a/doc/man/man5/slapd.conf.5
+++ b/doc/man/man5/slapd.conf.5
@@ -284,195 +284,6 @@ feature.  The default is 0.
 .B include <filename>
 Read additional configuration information from the given file before
 continuing with the next line of the current file.
-.TP
-.B limits <who> <limit> [<limit> [...]]
-Specify time and size limits based on who initiated an operation.
-The argument
-.B who
-can be any of
-.RS
-.RS
-.TP
-anonymous | users | [dn[.<style>]=]<pattern> | group[/oc[/at]]=<pattern>
-
-.RE
-with
-.RS
-.TP
-<style> ::= exact | base | onelevel | subtree | children | regex | anonymous
-
-.RE
-The term
-.B anonymous
-matches all unauthenticated clients.
-The term
-.B users
-matches all authenticated clients;
-otherwise an
-.B exact
-dn pattern is assumed unless otherwise specified by qualifying 
-the (optional) key string
-.B dn
-with 
-.B exact
-or
-.B base
-(which are synonyms), to require an exact match; with
-.BR onelevel , 
-to require exactly one level of depth match; with
-.BR subtree ,
-to allow any level of depth match, including the exact match; with
-.BR children ,
-to allow any level of depth match, not including the exact match;
-.BR regex
-explicitly requires the (default) match based on regular expression
-pattern, as detailed in
-.BR regex (7).
-Finally,
-.B anonymous
-matches unbound operations; the 
-.B pattern
-field is ignored.
-The same behavior is obtained by using the 
-.B anonymous
-form of the
-.B who
-clause.
-The term
-.BR group ,
-with the optional objectClass
-.B oc
-and attributeType
-.B at
-fields, followed by
-.BR pattern ,
-sets the limits for any DN listed in the values of the
-.B at
-attribute (default
-.BR member )
-of the 
-.B oc
-group objectClass (default
-.BR groupOfNames )
-whose DN exactly matches
-.BR pattern .
-
-The currently supported limits are 
-.B size
-and 
-.BR time .
-
-The syntax for time limits is 
-.BR time[.{soft|hard}]=<integer> ,
-where 
-.BR integer
-is the number of seconds slapd will spend answering a search request.
-If no time limit is explicitly requested by the client, the 
-.BR soft
-limit is used; if the requested time limit exceeds the
-.BR hard
-limit, an
-.I \"Administrative limit exceeded\"
-is returned.
-If the
-.BR hard
-limit is set to 0 or to the keyword 
-.IR soft ,
-the soft limit is used in either case; if it is set to 
-.I -1 
-or to the keyword 
-.IR none , 
-no hard limit is enforced.
-Explicit requests for time limits smaller or equal to the
-.BR hard 
-limit are honored.
-If no flag is set, the value is assigned to the 
-.BR soft 
-limit, and the
-.BR hard
-limit is set to zero, to preserve the original behavior.
-
-The syntax for size limits is
-.BR size[.{soft|hard|unchecked}]=<integer> ,
-where
-.BR integer
-is the maximum number of entries slapd will return answering a search 
-request.
-If no size limit is explicitly requested by the client, the
-.BR soft
-limit is used; if the requested size limit exceeds the
-.BR hard
-limit, an 
-.I \"Administrative limit exceeded\"
-is returned.
-If the 
-.BR hard
-limit is set to 0 or to the keyword 
-.IR soft , 
-the soft limit is used in either case; if it is set to 
-.I -1 
-or to the keyword
-.IR none , 
-no hard limit is enforced.
-Explicit requests for size limits smaller or equal to the
-.BR hard
-limit are honored.
-The
-.BR unchecked
-flag sets a limit on the number of candidates a search request is allowed
-to examine.
-If the selected candidates exceed the 
-.BR unchecked
-limit, the search will abort with 
-.IR \"Unwilling to perform\" .
-If it is set to
-.I -1 
-or to the keyword 
-.IR none , 
-no limit is applied (the default).
-If it is set to
-.IR disable ,
-the search is not even performed; this can be used to disallow searches
-for a specific set of users.
-If no flag is set, the value is assigned to the
-.BR soft 
-limit, and the
-.BR hard
-limit is set to zero, to preserve the original behavior.
-
-In case of no match, the global limits are used.
-The default values are the same of
-.B sizelimit
-and
-.BR timelimit ;
-no limit is set on 
-.BR unchecked .
-
-If 
-.B pagedResults
-control is defined, additional size limits may be enforced; the syntax is
-.BR size.pr={<integer>|noEstimate|disabled|none} ,
-where
-.B integer
-is the max page size if no explicit limit is set; the keyword
-.I noEstimate
-inhibits the server to return an estimate of the total number
-of entries that will be returned; the keyword
-.I disabled
-disables the control; the keyword
-.I none
-indicates that no limit is applied to the pagedResults control page size.
-The syntax
-.B size.prtotal={<integer>|none}
-allows to set a limit on the total number of entries that a pagedResults
-control allows to return.
-By default it is unlimited, which is indicated by the keyword
-.IR none .
-When set, 
-.B integer
-is the max number of entries that the whole search with pagedResults control
-can return.
-.RE
 .\"-- NEW_LOGGING option --
 .\".TP
 .\".B logfile <filename>
@@ -1148,6 +959,214 @@ will automatically maintain the
 modifiersName, modifyTimestamp, creatorsName, and 
 createTimestamp attributes for entries.  By default, lastmod is on.
 .TP
+.B limits <who> <limit> [<limit> [...]]
+Specify time and size limits based on who initiated an operation.
+The argument
+.B who
+can be any of
+.RS
+.RS
+.TP
+anonymous | users | [dn[.<style>]=]<pattern> | group[/oc[/at]]=<pattern>
+
+.RE
+with
+.RS
+.TP
+<style> ::= exact | base | onelevel | subtree | children | regex | anonymous
+
+.RE
+The term
+.B anonymous
+matches all unauthenticated clients.
+The term
+.B users
+matches all authenticated clients;
+otherwise an
+.B exact
+dn pattern is assumed unless otherwise specified by qualifying 
+the (optional) key string
+.B dn
+with 
+.B exact
+or
+.B base
+(which are synonyms), to require an exact match; with
+.BR onelevel , 
+to require exactly one level of depth match; with
+.BR subtree ,
+to allow any level of depth match, including the exact match; with
+.BR children ,
+to allow any level of depth match, not including the exact match;
+.BR regex
+explicitly requires the (default) match based on regular expression
+pattern, as detailed in
+.BR regex (7).
+Finally,
+.B anonymous
+matches unbound operations; the 
+.B pattern
+field is ignored.
+The same behavior is obtained by using the 
+.B anonymous
+form of the
+.B who
+clause.
+The term
+.BR group ,
+with the optional objectClass
+.B oc
+and attributeType
+.B at
+fields, followed by
+.BR pattern ,
+sets the limits for any DN listed in the values of the
+.B at
+attribute (default
+.BR member )
+of the 
+.B oc
+group objectClass (default
+.BR groupOfNames )
+whose DN exactly matches
+.BR pattern .
+
+The currently supported limits are 
+.B size
+and 
+.BR time .
+
+The syntax for time limits is 
+.BR time[.{soft|hard}]=<integer> ,
+where 
+.BR integer
+is the number of seconds slapd will spend answering a search request.
+If no time limit is explicitly requested by the client, the 
+.BR soft
+limit is used; if the requested time limit exceeds the
+.BR hard
+limit, an
+.I \"Administrative limit exceeded\"
+error is returned.
+If the
+.BR hard
+limit is set to 0 or to the keyword 
+.IR soft ,
+the soft limit is used in either case; if it is set to 
+.I -1 
+or to the keyword 
+.IR none , 
+no hard limit is enforced.
+Explicit requests for time limits smaller or equal to the
+.BR hard 
+limit are honored.
+If no flag is set, the value is assigned to the 
+.BR soft 
+limit, and the
+.BR hard
+limit is set to zero, to preserve the original behavior.
+
+The syntax for size limits is
+.BR size[.{soft|hard|unchecked}]=<integer> ,
+where
+.BR integer
+is the maximum number of entries slapd will return answering a search 
+request.
+If no size limit is explicitly requested by the client, the
+.BR soft
+limit is used; if the requested size limit exceeds the
+.BR hard
+limit, an 
+.I \"Administrative limit exceeded\"
+error is returned.
+If the 
+.BR hard
+limit is set to 0 or to the keyword 
+.IR soft , 
+the soft limit is used in either case; if it is set to 
+.I -1 
+or to the keyword
+.IR none , 
+no hard limit is enforced.
+Explicit requests for size limits smaller or equal to the
+.BR hard
+limit are honored.
+The
+.BR unchecked
+flag sets a limit on the number of candidates a search request is allowed
+to examine.
+If the selected candidates exceed the 
+.BR unchecked
+limit, the search will abort with 
+.IR \"Unwilling to perform\" .
+If it is set to
+.I -1 
+or to the keyword 
+.IR none , 
+no limit is applied (the default).
+If it is set to
+.IR disable ,
+the search is not even performed; this can be used to disallow searches
+for a specific set of users.
+If no flag is set, the value is assigned to the
+.BR soft 
+limit, and the
+.BR hard
+limit is set to zero, to preserve the original behavior.
+
+In case of no match, the global limits are used.
+The default values are the same of
+.B sizelimit
+and
+.BR timelimit ;
+no limit is set on 
+.BR unchecked .
+
+If 
+.B pagedResults
+control is requested, the 
+.B hard
+size limit is used by default, because the request of a specific page size
+is considered as an explicit request for a limitation on the number
+of entries to be returned.
+However, the size limit applies to the total count of entries returned within
+the search, and not to a single page.
+Additional size limits may be enforced; the syntax is
+.BR size.pr={<integer>|noEstimate|disabled|none} ,
+where
+.B integer
+is the max page size if no explicit limit is set; the keyword
+.I noEstimate
+inhibits the server to return an estimate of the total number
+of entries that will be returned; the keyword
+.I disabled
+disables the control, i.e. no paged results can be returned; the keyword
+.I none
+indicates that no limit is applied to the pagedResults control page size.
+The syntax
+.B size.prtotal={<integer>|none}
+allows to set a limit on the total number of entries that a pagedResults
+control allows to return.
+By default it is set to the 
+.B hard
+limit.
+When set, 
+.B integer
+is the max number of entries that the whole search with pagedResults control
+can return.
+Use 
+.B none
+to allow unlimited number of entries to be returned, i.e. to use 
+pagedResults as a means to allow clients to circumvent size limitations 
+on regular searches.
+Note that the total number of entries returned when the pagedResults control 
+is requested cannot exceed the 
+.B hard 
+size limit of regular searches unless extended by the
+.B prtotal
+switch.
+.RE
+.TP
 .B maxderefdepth <depth>
 Specifies the maximum number of aliases to dereference when trying to
 resolve an entry, used to avoid infinite alias loops. The default is 1.
-- 
2.39.5