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