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

   1 # $Id$
   2 # Copyright 1999-2012 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 <who> <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 ID that requested the operation.
 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:<who>}} part of the {{limits}} clause can take any of these values:
 110
 111 !block table; align=Center; coltags="EX,N"; \
 112     title="Table ZZZ.ZZZ: Entity Specifiers"
 113 Specifier|Entities
 114 *|All, including anonymous and authenticated users
 115 anonymous|Anonymous (non-authenticated) users
 116 users|Authenticated users
 117 self|User associated with target entry
 118 dn[.<basic-style>]=<regex>|Users matching a regular expression
 119 dn.<scope-style>=<DN>|Users within scope of a DN
 120 group[/oc[/at]]=<pattern>|Members of a group
 121 !endblock
 122
 123 The rules for specifying {{EX:<who>}} are the same as those used in
 124 access-control rules.
 125
 126 H3: Specify time limits
 127
 128 The syntax for time limits is
 129
 130 E:   time[.{soft|hard}]=<integer>
 131
 132 where integer is the number of seconds slapd will spend
 133 answering a search request.
 134
 135 If neither {{soft}} nor {{hard}} is specified, the value is used for both,
 136 e.g.:
 137
 138 E:   limits anonymous time=27
 139
 140 The value {{unlimited}} may be used to remove the hard time limit entirely,
 141 e.g.:
 142
 143 E:   limits dn.exact="cn=anyuser,dc=example,dc=org" time.hard=unlimited
 144
 145 H3: Specifying size limits
 146
 147 The syntax for size limit is
 148
 149 E:   size[.{soft|hard|unchecked}]=<integer>
 150
 151 where {{EX:<integer>}} is the maximum number of entries slapd will return
 152 when answering a search request.
 153
 154 Soft, hard, and "unchecked" limits are available, with the same meanings
 155 described for the global limits configuration above.
 156
 157 H3: Size limits and Paged Results
 158
 159 If the LDAP client adds the {{pagedResultsControl}} to the search operation,
 160 the hard size limit is used by default, because the request for a specific
 161 page size is considered an explicit request for a limitation on the number
 162 of entries to be returned. However, the size limit applies to the total
 163 count of entries returned within the search, and not to a single page.
 164
 165 Additional size limits may be enforced for paged searches.
 166
 167 The {{EX:size.pr}} limit controls the maximum page size:
 168
 169 >   size.pr={<integer>|noEstimate|unlimited}
 170
 171 {{EX:<integer>}} is the maximum page size if no explicit size is set.
 172 {{EX:noEstimate}} has no effect in the current implementation as the
 173 server does not return an estimate of the result size anyway.
 174 {{EX:unlimited}} indicates that no limit is applied to the maximum
 175 page size.
 176
 177 The {{EX:size.prtotal}} limit controls the total number of entries
 178 that can be returned by a paged search. By default the limit is the
 179 same as the normal {{EX:size.hard}} limit.
 180
 181 >   size.prtotal={<integer>|unlimited|disabled}
 182
 183 {{EX:unlimited}} removes the limit on the number of entries that can be
 184 returned by a paged search.
 185 {{EX:disabled}} can be used to selectively disable paged result searches.
 186
 187 H2: Example Limit Configurations
 188
 189 H3: Simple Global Limits
 190
 191 This simple global configuration fragment applies size and time limits
 192 to all searches by all users except {{rootdn}}. It limits searches to
 193 50 results and sets an overall time limit of 10 seconds.
 194
 195 E:   sizelimit 50
 196 E:   timelimit 10
 197
 198 H3: Global Hard and Soft Limits
 199
 200 It is sometimes useful to limit the size of result sets but to allow
 201 clients to request a higher limit where needed. This can be achieved
 202 by setting separate hard and soft limits.
 203
 204 E:   sizelimit size.soft=5 size.hard=100
 205
 206 To prevent clients from doing very inefficient non-indexed searches,
 207 add the {{unchecked}} limit:
 208
 209 E:   sizelimit size.soft=5 size.hard=100 size.unchecked=100
 210
 211 H3: Giving specific users larger limits
 212
 213 Having set appropriate default limits in the global configuration,
 214 you may want to give certain users the ability to retrieve larger
 215 result sets. Here is a way to do that in the per-database configuration:
 216
 217 E:   limits dn.exact="cn=anyuser,dc=example,dc=org" size=100000
 218 E:   limits dn.exact="cn=personnel,dc=example,dc=org" size=100000
 219 E:   limits dn.exact="cn=dirsync,dc=example,dc=org" size=100000
 220
 221 It is generally best to avoid mentioning specific users in the server
 222 configuration. A better way is to give the higher limits to a group:
 223
 224 E:   limits group/groupOfNames/member="cn=bigwigs,dc=example,dc=org" size=100000
 225
 226 H3: Limiting who can do paged searches
 227
 228 It may be required that certain applications need very large result sets that
 229 they retrieve using paged searches, but that you do not want ordinary
 230 LDAP users to use the pagedResults control. The {{pr}} and {{prtotal}}
 231 limits can help:
 232
 233 E:   limits group/groupOfNames/member="cn=dirsync,dc=example,dc=org" size.prtotal=unlimited
 234 E:   limits users size.soft=5 size.hard=100 size.prtotal=disabled
 235 E:   limits anonymous size.soft=2 size.hard=5 size.prtotal=disabled
 236
 237 H2: Further Information
 238
 239 For further information please see {{slapd.conf}}(5), {{ldapsearch}}(1) and {{slapd.access}}(5)
 240