ITS#5818

CHANGES

@@ -28,6 +28,8 @@ OpenLDAP 2.4.14 Engineering
 		Fixed test049,test050 to work on windows (ITS#5842)
 		Removed patch for BerkeleyDB 4.7.25 (Official patch available)
 		Fixed MSVC 9.0 build issues (ITS#5888)
+	Documentation
+		admin24 added limits chapter (ITS#5818)
 
 OpenLDAP 2.4.13 Release (2008/11/24)
 	Added libldap dereference control support (ITS#5768)

doc/guide/admin/aspell.en.pws

-personal_ws-1.1 en 1682 
+personal_ws-1.1 en 1687 
 commonName
 bla
 Masarati
@@ -6,8 +6,8 @@ subjectAltName
 api
 usnCreated
 BhY
-olcSyncrepl
 olcSyncRepl
+olcSyncrepl
 adamsom
 adamson
 CER
@@ -25,8 +25,8 @@ TLSCACertificateFile
 BNF
 TLSEphemeralDHParamFile
 ppolicy
-ASN
 gavin
+ASN
 ava
 Chu
 del
@@ -40,8 +40,8 @@ DIB
 dev
 reqNewSuperior
 librewrite
-memberOf
 memberof
+memberOf
 BSI
 updateref
 buf
@@ -92,14 +92,15 @@ dlopen
 eng
 AttributeValue
 attributevalue
-EOF
 DUA
+EOF
 inputfile
 DSP
 refreshDone
 dst
 NOSYNC
 env
+pagedResultsControl
 dup
 hdb
 LDIFv
@@ -112,6 +113,7 @@ testdb
 gif
 memfree
 struct
+dirsync
 IAB
 fmt
 SysNet
@@ -129,10 +131,10 @@ iff
 contextCSN
 auditModify
 auditSearch
-openldap
 OpenLDAP
-resultCode
+openldap
 resultcode
+resultCode
 sysconfig
 indices
 blen
@@ -172,13 +174,13 @@ argv
 kdz
 notAllowedOnRDN
 hostport
-starttls
 StartTLS
+starttls
 ldb
 servercredp
 ldd
-ipv
 IPv
+ipv
 hyc
 joe
 bindmethods
@@ -210,8 +212,8 @@ libpath
 acknowledgements
 jts
 createTimestamp
-LLL
 MIB
+LLL
 OpenSSL
 openssl
 LOF
@@ -251,10 +253,10 @@ Subbarao
 aeeiib
 oidlen
 submatches
-olc
 PEM
-PDU
+olc
 OLF
+PDU
 LDAPSchemaExtensionItem
 auth
 Pierangelo
@@ -270,8 +272,8 @@ cleartext
 numattrsets
 requestDN
 caseExactSubstringsMatch
-PKI
 NSS
+PKI
 olcSyncProvConfig
 ple
 jones
@@ -295,9 +297,9 @@ rdn
 wZFQrDD
 OTP
 olcSizeLimit
-pos
-sbi
 PRD
+sbi
+pos
 pre
 sudoadm
 stringal
@@ -317,8 +319,8 @@ bvec
 HtZhZS
 TBC
 stringbv
-Sep
 SHA
+Sep
 ptr
 conn
 pwd
@@ -335,8 +337,8 @@ myOID
 supportedSASLMechanism
 supportedSASLmechanism
 realnamingcontext
-SMD
 UCD
+SMD
 keytab
 portnumber
 uncached
@@ -349,8 +351,8 @@ sasldb
 UCS
 searchDN
 keytbl
-tgz
 UDP
+tgz
 freemods
 prepend
 nssov
@@ -368,23 +370,23 @@ crit
 objectClassViolation
 ssf
 ldapfilter
-rwm
-TOC
 vec
+TOC
+rwm
 pwdChangedTime
 tls
 peernamestyle
 xpasswd
-tmp
 SRP
+tmp
 SSL
 dupbv
 CPUs
 itsupport
 SRV
 entrymods
-rwx
 sss
+rwx
 reqNewRDN
 nopresent
 rebindproc
@@ -447,8 +449,8 @@ pseudorootdn
 MezRroT
 GDBM
 LIBRELEASE
-DSAs
 DSA's
+DSAs
 realloc
 booleanMatch
 compareTrue
@@ -490,6 +492,7 @@ hh
 regexec
 IG
 msgidp
+noEstimate
 kb
 organizationalUnit
 Warper
@@ -508,8 +511,8 @@ pwdMinLength
 iZ
 ldapdelete
 xyz
-RDBMs
 rdbms
+RDBMs
 extparam
 mk
 ng
@@ -574,8 +577,8 @@ ZZ
 LDVERSION
 testAttr
 backend
-backend's
 backends
+backend's
 BerValues
 Solaris
 structs
@@ -587,15 +590,16 @@ ostring
 policyDN
 testObject
 pwdMaxAge
-bindDn
-bindDN
 binddn
+bindDN
+bindDn
 distributedOperation
 schemachecking
 strvals
 dataflow
 robert
 fqdn
+prtotal
 admittable
 Makefile
 IANA
@@ -634,14 +638,14 @@ IEEE
 regex
 SIGINT
 slappasswd
-errAbsObject
 errABsObject
+errAbsObject
 ldapexop
-objectidentifier
 objectIdentifier
+objectidentifier
 deallocators
-MirrorMode
 mirrormode
+MirrorMode
 loopDetect
 SIGHUP
 authMethodNotSupported
@@ -658,8 +662,8 @@ filtercomp
 expr
 syntaxes
 memrealloc
-returnCode
 returncode
+returnCode
 OpenLDAP's
 exts
 bitstringa
@@ -683,8 +687,8 @@ lastName
 lldap
 cachesize
 slapauth
-attributetype
 attributeType
+attributetype
 GSER
 olcDbNosync
 typedef
@@ -702,13 +706,14 @@ TLSVerifyClient
 noidlen
 LDAPNOINIT
 henry
-pwdGraceAuthNLimit
 pwdGraceAuthnLimit
+pwdGraceAuthNLimit
 hnPk
-userPassword
 userpassword
+userPassword
 noanonymous
 LIBVERSION
+anyuser
 symas
 dcedn
 glibc
@@ -725,9 +730,9 @@ IMAP
 organisations
 rewriteMap
 monitoredInfo
-modrdn
-ModRDN
 modrDN
+ModRDN
+modrdn
 HREF
 DQTxCYEApdUtNXGgdUac
 inline
@@ -742,8 +747,8 @@ reqReferral
 rlookups
 siiiib
 LTSTATIC
-timeLimitExceeded
 timelimitExceeded
+timeLimitExceeded
 XKYnrjvGT
 subtrees
 unixODBC
@@ -755,8 +760,8 @@ reqDN
 dnstyle
 inet
 schemas
-pwdPolicySubEntry
 pwdPolicySubentry
+pwdPolicySubEntry
 reqId
 backsql
 scanf
@@ -1096,8 +1101,8 @@ noop
 errObject
 XXLIBS
 reqAssertion
-PDUs
 nops
+PDUs
 baseObject
 bvecadd
 perl
@@ -1542,8 +1547,8 @@ nattrsets
 saslargs
 OBJEXT
 LDAPAttributeType
-newPasswdFile
 newpasswdfile
+newPasswdFile
 boolean
 liblber
 ucdata
@@ -1606,12 +1611,12 @@ jpegPhoto
 supportedSASLMechanisms
 ACLs
 reqMethod
-authzID
-authzid
 authzId
+authzid
+authzID
 hasSubordintes
-proxycache
 proxyCache
+proxycache
 slaptest
 olcLogLevel
 LDAPDN
@@ -1636,8 +1641,8 @@ wBDARESEhgVG
 multi
 aaa
 ldaprc
-updatedn
 UpdateDN
+updatedn
 LDAPBASE
 LDAPAPIFeatureInfo
 authzTo
@@ -1678,6 +1683,6 @@ ali
 attributeoptions
 BfQ
 uidNumber
-CAs
 CA's
+CAs
 namingContext

doc/guide/admin/limits.sdf

+# $Id$
+# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+
+# This contribution is derived from OpenLDAP Software.
+# All of the modifications to OpenLDAP Software represented in this contribution
+# were developed by Andrew Findlay <andrew.findlay@skills-1st.co.uk>.
+# I have not assigned rights and/or interest in this work to any party.
+#
+# Copyright 2008 Andrew Findlay
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted only as authorized by the OpenLDAP Public License.
+
+H1: Limits
+
+H2: Introduction
+
+It is usually desirable to limit the server resources that can be
+consumed by each LDAP client. OpenLDAP provides two sets of limits:
+a size limit, which can restrict the {{number}} of entries that a
+client can retrieve in a single operation, and a time limit
+which restricts the length of time that an operation may continue.
+Both types of limit can be given different values depending on who
+initiated the operation.
+
+H2: Soft and Hard limits
+
+The server administrator can specify both {{soft limits}} and
+{{hard limits}}. Soft limits can be thought of as being the
+default limit value. Hard limits cannot be exceeded by ordinary
+LDAP users.
+
+LDAP clients can specify their own
+size and time limits when issuing search operations.
+This feature has been present since the earliest version of X.500.
+
+If the client specifies a limit then the lower of the requested value
+and the {{hard limit}} will become the limit for the operation.
+
+If the client does not specify a limit then the server applies the
+{{soft limit}}.
+
+Soft and Hard limits are often referred to together as {{administrative
+limits}}. Thus, if an LDAP client requests a search that would return
+more results than the limits allow it will get an {{adminLimitExceeded}}
+error. Note that the server will usually return some results even if
+the limit has been exceeded: this feature is useful to clients that
+just want to check for the existence of some entries without needing
+to see them all.
+
+The {{rootdn}} is not subject to any limits.
+
+H2: Global Limits
+
+Limits specified in the global part of the server configuration act
+as defaults which are used if no database has more specific limits set.
+
+In a {{slapd.conf}}(5) configuration the keywords are {{EX:sizelimit}} and
+{{EX:timelimit}}. When using the {{slapd config}} backend, the corresponding
+attributes are {{EX:olcSizeLimit}} and {{EX:olcTimeLimit}}. The syntax of
+these values are the same in both cases.
+
+The simple form sets both soft and hard limits to the same value:
+
+>   sizelimit {<integer>|unlimited}
+>   timelimit {<integer>|unlimited}
+
+The default sizelimit is 500 entries and the default timelimit is
+3600 seconds.
+
+An extended form allows soft and hard limits to be set separately:
+
+>   sizelimit size[.{soft|hard|unchecked}]=<integer> [...]
+>   timelimit time[.{soft|hard}]=<integer> [...]
+
+Thus, to set a soft sizelimit of 10 entries and a hard limit of 75 entries:
+
+E:  sizelimit size.soft=10 size.hard=75
+
+The {{unchecked}} keyword sets a limit on how many entries the server
+will examine once it has created an initial set of candidate results by
+using indices. This can be very important in a large directory, as a
+search that cannot be satisfied from an index might cause the server to
+examine millions of entries, therefore always make sure the correct indexes
+are configured.
+
+H2: Per-Database Limits
+
+Each database can have its own set of limits that override the global
+ones. The syntax is more flexible, and it allows different limits to
+be applied to different entities. Note that an {{entity}} is different from
+an {{entry}}: the term {{entity}} is used here to indicate the ID of the
+person or process that has initiated the LDAP operation.
+
+In a {{slapd.conf}}(5) configuration the keyword is {{EX:limits}}.
+When using the {{slapd config}} backend, the corresponding
+attribute is {{EX:olcLimits}}. The syntax of
+the values is the same in both cases.
+
+>   limits <who> <limit> [<limit> [...]]
+
+The {{limits}} clause can be specified multiple times to apply different
+limits to different initiators. The server examines each clause in turn
+until it finds one that matches the ID that requested the operation.
+If no match is found, the global limits will be used.
+
+H3: Specify who the limits apply to
+
+The {{EX:<who>}} part of the {{limits}} clause can take any of these values:
+
+!block table; align=Center; coltags="EX,N"; \
+    title="Table ZZZ.ZZZ: Entity Specifiers"
+Specifier|Entities
+*|All, including anonymous and authenticated users
+anonymous|Anonymous (non-authenticated) users
+users|Authenticated users
+self|User associated with target entry
+dn[.<basic-style>]=<regex>|Users matching a regular expression
+dn.<scope-style>=<DN>|Users within scope of a DN
+group[/oc[/at]]=<pattern>|Members of a group
+!endblock
+
+The rules for specifying {{EX:<who>}} are the same as those used in
+access-control rules.
+
+H3: Specify time limits
+
+The syntax for time limits is 
+
+E:   time[.{soft|hard}]=<integer>
+
+where integer is the number of seconds slapd will spend
+answering a search request.
+
+If neither {{soft}} nor {{hard}} is specified, the value is used for both,
+e.g.:
+
+E:   limits anonymous time=27
+
+The value {{unlimited}} may be used to remove the hard time limit entirely,
+e.g.:
+
+E:   limits dn.exact="cn=anyuser,dc=example,dc=org" time.hard=unlimited
+
+H3: Specifying size limits
+
+The syntax for size limit is 
+
+E:   size[.{soft|hard|unchecked}]=<integer>
+
+where {{EX:<integer>}} is the maximum number of entries slapd will return
+when answering a search request.
+
+Soft, hard, and "unchecked" limits are available, with the same meanings
+described for the global limits configuration above.
+
+H3: Size limits and Paged Results
+
+If the LDAP client adds the {{pagedResultsControl}} to the search operation,
+the hard size limit is used by default, because the request for a specific
+page size is considered an explicit request for a limitation on the number
+of entries to be returned. However, the size limit applies to the total
+count of entries returned within the search, and not to a single page.
+
+Additional size limits may be enforced for paged searches.
+
+The {{EX:size.pr}} limit controls the maximum page size:
+
+>   size.pr={<integer>|noEstimate|unlimited}
+
+{{EX:<integer>}} is the maximum page size if no explicit size is set.
+{{EX:noEstimate}} has no effect in the current implementation as the
+server does not return an estimate of the result size anyway.
+{{EX:unlimited}} indicates that no limit is applied to the maximum
+page size.
+
+The {{EX:size.prtotal}} limit controls the total number of entries
+that can be returned by a paged search. By default the limit is the
+same as the normal {{EX:size.hard}} limit.
+
+>   size.prtotal={<integer>|unlimited|disabled}
+
+{{EX:unlimited}} removes the limit on the number of entries that can be
+returned by a paged search.
+{{EX:disabled}} can be used to selectively disable paged result searches.
+
+H2: Example Limit Configurations
+
+H3: Simple Global Limits
+
+This simple global configuration fragment applies size and time limits
+to all searches by all users except {{rootdn}}. It limits searches to
+50 results and sets an overall time limit of 10 seconds.
+
+E:   sizelimit 50
+E:   timelimit 10
+
+H3: Global Hard and Soft Limits
+
+It is sometimes useful to limit the size of result sets but to allow
+clients to request a higher limit where needed. This can be achieved
+by setting separate hard and soft limits.
+
+E:   sizelimit size.soft=5 size.hard=100
+
+To prevent clients from doing very inefficient non-indexed searches,
+add the {{unchecked}} limit:
+
+E:   sizelimit size.soft=5 size.hard=100 size.unchecked=100
+
+H3: Giving specific users larger limits
+
+Having set appropriate default limits in the global configuration,
+you may want to give certain users the ability to retrieve larger
+result sets. Here is a way to do that in the per-database configuration:
+
+E:   limits dn.exact="cn=anyuser,dc=example,dc=org" size=100000
+E:   limits dn.exact="cn=personnel,dc=example,dc=org" size=100000
+E:   limits dn.exact="cn=dirsync,dc=example,dc=org" size=100000
+
+It is generally best to avoid mentioning specific users in the server
+configuration. A better way is to give the higher limits to a group:
+
+E:   limits group/groupOfNames/member="cn=bigwigs,dc=example,dc=org" size=100000
+
+H3: Limiting who can do paged searches
+
+It may be required that certain applications need very large result sets that
+they retrieve using paged searches, but that you do not want ordinary
+LDAP users to use the pagedResults control. The {{pr}} and {{prtotal}}
+limits can help:
+
+E:   limits group/groupOfNames/member="cn=dirsync,dc=example,dc=org" size.prtotal=unlimited
+E:   limits users size.soft=5 size.hard=100 size.prtotal=disabled
+E:   limits anonymous size.soft=2 size.hard=5 size.prtotal=disabled
+
+H2: Further Information
+
+For further information please see {{slapd.conf}}(5), {{ldapsearch}}(1) and {{slapd.access}}(5)
+

doc/guide/admin/master.sdf

@@ -48,6 +48,9 @@ PB:
 !include "access-control.sdf"; chapter
 PB:
 
+!include "limits.sdf"; chapter
+PB:
+
 !include "dbtools.sdf"; chapter
 PB:
 

doc/guide/admin/slapdconf2.sdf

@@ -474,6 +474,8 @@ from a search operation.
 
 >	olcSizeLimit: 500
 
+See the {{SECT:Limits}} section of this guide and slapd-config(5)
+for more details.
 
 
 H4: olcSuffix: <dn suffix>
@@ -668,6 +670,9 @@ exceeded timelimit will be returned.
 
 >	olcTimeLimit: 3600
 
+See the {{SECT:Limits}} section of this guide and slapd-config(5)
+for more details.
+
 
 H4: olcUpdateref: <URL>
 

doc/guide/admin/slapdconfig.sdf

@@ -203,6 +203,8 @@ from a search operation.
 
 >	sizelimit 500
 
+See the {{SECT:Limits}} section of this guide and slapd.conf(5)
+for more details.
 
 H4: timelimit <integer>
 
@@ -215,6 +217,9 @@ exceeded timelimit will be returned.
 
 >	timelimit 3600
 
+See the {{SECT:Limits}} section of this guide and slapd.conf(5)
+for more details.
+
 
 H3: General Backend Directives
 
@@ -273,6 +278,14 @@ This marks the beginning of a new {{TERM:BDB}} database instance
 declaration.
 
 
+H4: limits <who> <limit> [<limit> [...]]
+
+Specify time and size limits based on who initiated an operation.
+
+See the {{SECT:Limits}} section of this guide and slapd.conf(5)
+for more details.
+
+
 H4: readonly { on | off }
 
 This directive puts the database into "read-only" mode. Any