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