ITS#6694 reorganize unchecked/pagedresults limits descriptions

doc/guide/admin/limits.sdf

@@ -70,19 +70,63 @@ The default sizelimit is 500 entries and the default timelimit is
 
 An extended form allows soft and hard limits to be set separately:
 
->   sizelimit size[.{soft|hard|unchecked}]=<integer> [...]
+>   sizelimit size[.{soft|hard}]=<integer> [...]
 >   timelimit time[.{soft|hard}]=<integer> [...]
 
 Thus, to set a soft sizelimit of 10 entries and a hard limit of 75 entries:
 
 E:  sizelimit size.soft=10 size.hard=75
 
+H3: Special Size Limits
+
+There are other forms of size limits in addition to the soft and hard limits.
+Note that when using the simple {{sizelimit}} form, none of these special
+limits are changed.
+
+H4: Unchecked Limits
+
 The {{unchecked}} keyword sets a limit on how many entries the server
-will examine once it has created an initial set of candidate results by
-using indices. This can be very important in a large directory, as a
-search that cannot be satisfied from an index might cause the server to
-examine millions of entries, therefore always make sure the correct indexes
-are configured.
+will examine after doing index lookups but before evaluating filter
+matches. If the set of candidates exceeds this limit, the search is aborted.
+The purpose is to avoid causing excessive workload on {{slapd}}
+if a filter uses attributes that are not properly indexed, and can
+be critical for very large directories.
+
+>   sizelimit size.unchecked={<integer>|unlimited|disabled}
+
+The default is unlimited. The {{disabled}} setting prevents a search
+from being performed at all. This may be useful in the per-database
+limits described below, to disallow searches for a specific set of users.
+
+H4: Paged Results Limits
+
+If the LDAP client adds the {{pagedResultsControl}} to the search operation,
+the hard size limit is used by default, because the request for a specific
+page size is considered 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 for paged searches.
+
+The {{EX:size.pr}} limit controls the maximum page size:
+
+>   sizelimit size.pr={<integer>|noEstimate|unlimited}
+
+{{EX:<integer>}} is the maximum page size if no explicit size is set.
+{{EX:noEstimate}} has no effect in the current implementation as the
+server does not return an estimate of the result size anyway.
+{{EX:unlimited}} indicates that no limit is applied to the maximum
+page size.
+
+The {{EX:size.prtotal}} limit controls the total number of entries
+that can be returned by a paged search. By default the limit is the
+same as the normal {{EX:size.hard}} limit.
+
+>   size.prtotal={<integer>|unlimited|disabled}
+
+{{EX:unlimited}} removes the limit on the number of entries that can be
+returned by a paged search.
+{{EX:disabled}} can be used to selectively disable paged result searches.
 
 H2: Per-Database Limits
 
@@ -150,43 +194,14 @@ H3: Specifying size limits
 
 The syntax for size limit is 
 
-E:   size[.{soft|hard|unchecked}]=<integer>
+E:   size[.{soft|hard}]=<integer>
 
 where {{EX:<integer>}} is the maximum number of entries slapd will return
 when answering a search request.
 
-Soft, hard, and "unchecked" limits are available, with the same meanings
-described for the global limits configuration above.
+In addition to soft and hard limits, other limits are also available,
+with the same meanings described for the global limits configuration above.
 
-H3: Size limits and Paged Results
-
-If the LDAP client adds the {{pagedResultsControl}} to the search operation,
-the hard size limit is used by default, because the request for a specific
-page size is considered 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 for paged searches.
-
-The {{EX:size.pr}} limit controls the maximum page size:
-
->   size.pr={<integer>|noEstimate|unlimited}
-
-{{EX:<integer>}} is the maximum page size if no explicit size is set.
-{{EX:noEstimate}} has no effect in the current implementation as the
-server does not return an estimate of the result size anyway.
-{{EX:unlimited}} indicates that no limit is applied to the maximum
-page size.
-
-The {{EX:size.prtotal}} limit controls the total number of entries
-that can be returned by a paged search. By default the limit is the
-same as the normal {{EX:size.hard}} limit.
-
->   size.prtotal={<integer>|unlimited|disabled}
-
-{{EX:unlimited}} removes the limit on the number of entries that can be
-returned by a paged search.
-{{EX:disabled}} can be used to selectively disable paged result searches.
 
 H2: Example Limit Configurations
 

doc/man/man5/slapd-config.5

@@ -1327,16 +1327,18 @@ e.g. ldapi:// (and eventually IPSEC).  It is not normally used.
 .TP
 .B olcSizeLimit: {<integer>|unlimited}
 .TP
-.B olcSizeLimit: size[.{soft|hard|unchecked}]=<integer> [...]
+.B olcSizeLimit: size[.{soft|hard}]=<integer> [...]
 Specify the maximum number of entries to return from a search operation.
 The default size limit is 500.
 Use
 .B unlimited
 to specify no limits.
 The second format allows a fine grain setting of the size limits.
-Extra args can be added in the same value. See
+If no special qualifiers are specified, both soft and hard limits are set.
+Extra args can be added in the same value.
+Additional qualifiers are available. See
 .BR olcLimits
-for an explanation of the different flags.
+for an explanation of all of the different flags.
 .TP
 .B olcSortVals: <attr> [...]
 Specify a list of multi-valued attributes whose values will always

doc/man/man5/slapd.conf.5

@@ -979,17 +979,18 @@ Example:
 .TP
 .B sizelimit {<integer>|unlimited}
 .TP
-.B sizelimit size[.{soft|hard|unchecked}]=<integer> [...]
+.B sizelimit size[.{soft|hard}]=<integer> [...]
 Specify the maximum number of entries to return from a search operation.
 The default size limit is 500.
 Use
 .B unlimited
 to specify no limits.
 The second format allows a fine grain setting of the size limits.
+If no special qualifiers are specified, both soft and hard limits are set.
 Extra args can be added on the same line.
-See
+Additional qualifiers are available; see
 .BR limits
-for an explanation of the different flags.
+for an explanation of all of the different flags.
 .TP
 .B sockbuf_max_incoming <integer>
 Specify the maximum incoming LDAP PDU size for anonymous sessions.