git.sur5r.net Git - openldap/blob - doc/guide/admin/limits.sdf

   1 # $Id$
   2 # Copyright 1999-2017 The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4
   5 # This contribution is derived from OpenLDAP Software.
   6 # All of the modifications to OpenLDAP Software represented in this contribution
   7 # were developed by Andrew Findlay <andrew.findlay@skills-1st.co.uk>.
   8 # I have not assigned rights and/or interest in this work to any party.
   9 #
  10 # Copyright 2008 Andrew Findlay
  11 # Redistribution and use in source and binary forms, with or without
  12 # modification, are permitted only as authorized by the OpenLDAP Public License.
  13
  14 H1: Limits
  15
  16 H2: Introduction
  17
  18 It is usually desirable to limit the server resources that can be
  19 consumed by each LDAP client. OpenLDAP provides two sets of limits:
  20 a size limit, which can restrict the {{number}} of entries that a
  21 client can retrieve in a single operation, and a time limit
  22 which restricts the length of time that an operation may continue.
  23 Both types of limit can be given different values depending on who
  24 initiated the operation.
  25
  26 H2: Soft and Hard limits
  27
  28 The server administrator can specify both {{soft limits}} and
  29 {{hard limits}}. Soft limits can be thought of as being the
  30 default limit value. Hard limits cannot be exceeded by ordinary
  31 LDAP users.
  32
  33 LDAP clients can specify their own
  34 size and time limits when issuing search operations.
  35 This feature has been present since the earliest version of X.500.
  36
  37 If the client specifies a limit then the lower of the requested value
  38 and the {{hard limit}} will become the limit for the operation.
  39
  40 If the client does not specify a limit then the server applies the
  41 {{soft limit}}.
  42
  43 Soft and Hard limits are often referred to together as {{administrative
  44 limits}}. Thus, if an LDAP client requests a search that would return
  45 more results than the limits allow it will get an {{adminLimitExceeded}}
  46 error. Note that the server will usually return some results even if
  47 the limit has been exceeded: this feature is useful to clients that
  48 just want to check for the existence of some entries without needing
  49 to see them all.
  50
  51 The {{rootdn}} is not subject to any limits.
  52
  53 H2: Global Limits
  54
  55 Limits specified in the global part of the server configuration act
  56 as defaults which are used if no database has more specific limits set.
  57
  58 In a {{slapd.conf}}(5) configuration the keywords are {{EX:sizelimit}} and
  59 {{EX:timelimit}}. When using the {{slapd config}} backend, the corresponding
  60 attributes are {{EX:olcSizeLimit}} and {{EX:olcTimeLimit}}. The syntax of
  61 these values are the same in both cases.
  62
  63 The simple form sets both soft and hard limits to the same value:
  64
  65 >   sizelimit {<integer>|unlimited}
  66 >   timelimit {<integer>|unlimited}
  67
  68 The default sizelimit is 500 entries and the default timelimit is
  69 3600 seconds.
  70
  71 An extended form allows soft and hard limits to be set separately:
  72
  73 >   sizelimit size[.{soft|hard|unchecked}]=<integer> [...]
  74 >   timelimit time[.{soft|hard}]=<integer> [...]
  75
  76 Thus, to set a soft sizelimit of 10 entries and a hard limit of 75 entries:
  77
  78 E:  sizelimit size.soft=10 size.hard=75
  79
  80 The {{unchecked}} keyword sets a limit on how many entries the server
  81 will examine once it has created an initial set of candidate results by
  82 using indices. This can be very important in a large directory, as a
  83 search that cannot be satisfied from an index might cause the server to
  84 examine millions of entries, therefore always make sure the correct indexes
  85 are configured.
  86
  87 H2: Per-Database Limits
  88
  89 Each database can have its own set of limits that override the global
  90 ones. The syntax is more flexible, and it allows different limits to
  91 be applied to different entities. Note that an {{entity}} is different from
  92 an {{entry}}: the term {{entity}} is used here to indicate the ID of the
  93 person or process that has initiated the LDAP operation.
  94
  95 In a {{slapd.conf}}(5) configuration the keyword is {{EX:limits}}.
  96 When using the {{slapd config}} backend, the corresponding
  97 attribute is {{EX:olcLimits}}. The syntax of
  98 the values is the same in both cases.
  99
 100 >   limits <selector> <limit> [<limit> [...]]
 101
 102 The {{limits}} clause can be specified multiple times to apply different
 103 limits to different initiators. The server examines each clause in turn
 104 until it finds one that matches the operation's initiator or base DN.
 105 If no match is found, the global limits will be used.
 106
 107 H3: Specify who the limits apply to
 108
 109 The {{EX:<selector>}} part of the {{limits}} clause can take any of these values:
 110
 111 !block table; align=Center; coltags="EX,N"; \
 112     title="Table 9.1: Limits Entity Specifiers"
 113 Specifier|Entities
 114 *|All, including anonymous and authenticated users
 115 anonymous|Anonymous (non-authenticated) users
 116 users|Authenticated users
 117 dn[.<type>][.<style>]=<pattern>]|Entry or entries within a scope that match <pattern>
 118 group[/oc[/at]]=<pattern>|Members of a group
 119 !endblock
 120
 121 Where
 122
 123 {{type}} can be one of self or this and
 124
 125 {{style}} can be one of exact, base, onelevel, subtree, children, regex, or anonymous
 126
 127 More information can be found in the {{slapd.conf}}(5) or {{slapd-config}}(5) manual
 128 pages.
 129
 130 H3: Specify time limits
 131
 132 The syntax for time limits is
 133
 134 E:   time[.{soft|hard}]=<integer>
 135
 136 where integer is the number of seconds slapd will spend
 137 answering a search request.
 138
 139 If neither {{soft}} nor {{hard}} is specified, the value is used for both,
 140 e.g.:
 141
 142 E:   limits anonymous time=27
 143
 144 The value {{unlimited}} may be used to remove the hard time limit entirely,
 145 e.g.:
 146
 147 E:   limits dn.exact="cn=anyuser,dc=example,dc=org" time.hard=unlimited
 148
 149 H3: Specifying size limits
 150
 151 The syntax for size limit is
 152
 153 E:   size[.{soft|hard|unchecked}]=<integer>
 154
 155 where {{EX:<integer>}} is the maximum number of entries slapd will return
 156 when answering a search request.
 157
 158 Soft, hard, and "unchecked" limits are available, with the same meanings
 159 described for the global limits configuration above.
 160
 161 H3: Size limits and Paged Results
 162
 163 If the LDAP client adds the {{pagedResultsControl}} to the search operation,
 164 the hard size limit is used by default, because the request for a specific
 165 page size is considered an explicit request for a limitation on the number
 166 of entries to be returned. However, the size limit applies to the total
 167 count of entries returned within the search, and not to a single page.
 168
 169 Additional size limits may be enforced for paged searches.
 170
 171 The {{EX:size.pr}} limit controls the maximum page size:
 172
 173 >   size.pr={<integer>|noEstimate|unlimited}
 174
 175 {{EX:<integer>}} is the maximum page size if no explicit size is set.
 176 {{EX:noEstimate}} has no effect in the current implementation as the
 177 server does not return an estimate of the result size anyway.
 178 {{EX:unlimited}} indicates that no limit is applied to the maximum
 179 page size.
 180
 181 The {{EX:size.prtotal}} limit controls the total number of entries
 182 that can be returned by a paged search. By default the limit is the
 183 same as the normal {{EX:size.hard}} limit.
 184
 185 >   size.prtotal={<integer>|unlimited|disabled}
 186
 187 {{EX:unlimited}} removes the limit on the number of entries that can be
 188 returned by a paged search.
 189 {{EX:disabled}} can be used to selectively disable paged result searches.
 190
 191 H2: Example Limit Configurations
 192
 193 H3: Simple Global Limits
 194
 195 This simple global configuration fragment applies size and time limits
 196 to all searches by all users except {{rootdn}}. It limits searches to
 197 50 results and sets an overall time limit of 10 seconds.
 198
 199 E:   sizelimit 50
 200 E:   timelimit 10
 201
 202 H3: Global Hard and Soft Limits
 203
 204 It is sometimes useful to limit the size of result sets but to allow
 205 clients to request a higher limit where needed. This can be achieved
 206 by setting separate hard and soft limits.
 207
 208 E:   sizelimit size.soft=5 size.hard=100
 209
 210 To prevent clients from doing very inefficient non-indexed searches,
 211 add the {{unchecked}} limit:
 212
 213 E:   sizelimit size.soft=5 size.hard=100 size.unchecked=100
 214
 215 H3: Giving specific users larger limits
 216
 217 Having set appropriate default limits in the global configuration,
 218 you may want to give certain users the ability to retrieve larger
 219 result sets. Here is a way to do that in the per-database configuration:
 220
 221 E:   limits dn.exact="cn=anyuser,dc=example,dc=org" size=100000
 222 E:   limits dn.exact="cn=personnel,dc=example,dc=org" size=100000
 223 E:   limits dn.exact="cn=dirsync,dc=example,dc=org" size=100000
 224
 225 It is generally best to avoid mentioning specific users in the server
 226 configuration. A better way is to give the higher limits to a group:
 227
 228 E:   limits group/groupOfNames/member="cn=bigwigs,dc=example,dc=org" size=100000
 229
 230 H3: Limiting who can do paged searches
 231
 232 It may be required that certain applications need very large result sets that
 233 they retrieve using paged searches, but that you do not want ordinary
 234 LDAP users to use the pagedResults control. The {{pr}} and {{prtotal}}
 235 limits can help:
 236
 237 E:   limits group/groupOfNames/member="cn=dirsync,dc=example,dc=org" size.prtotal=unlimited
 238 E:   limits users size.soft=5 size.hard=100 size.prtotal=disabled
 239 E:   limits anonymous size.soft=2 size.hard=5 size.prtotal=disabled
 240
 241 H2: Further Information
 242
 243 For further information please see {{slapd.conf}}(5), {{ldapsearch}}(1) and {{slapd.access}}(5)
 244