]> git.sur5r.net Git - openldap/blob - doc/guide/admin/limits.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / 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