1 # Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
2 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
13 H3: Access Logging Configuration
22 H3: Audit Logging Configuration
31 H3: Constraint Configuration
34 H2: Dynamic Directory Services
40 H3: Dynamic Directory Service Configuration
49 H3: Dynamic Group Configuration
58 H3: Dynamic List Configuration
61 H2: The Proxy Cache Engine
63 {{TERM:LDAP}} servers typically hold one or more subtrees of a
64 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
65 entries held by one or more master servers. Changes are propagated
66 from the master server to replica (slave) servers using LDAP Sync
67 replication. An LDAP cache is a special type of replica which holds
68 entries corresponding to search filters instead of subtrees.
72 The proxy cache extension of slapd is designed to improve the
73 responseiveness of the ldap and meta backends. It handles a search
75 by first determining whether it is contained in any cached search
76 filter. Contained requests are answered from the proxy cache's local
77 database. Other requests are passed on to the underlying ldap or
78 meta backend and processed as usual.
80 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
81 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
83 Correct matching rules and syntaxes are used while comparing
84 assertions for query containment. To simplify the query containment
85 problem, a list of cacheable "templates" (defined below) is specified
86 at configuration time. A query is cached or answered only if it
87 belongs to one of these templates. The entries corresponding to
88 cached queries are stored in the proxy cache local database while
89 its associated meta information (filter, scope, base, attributes)
90 is stored in main memory.
92 A template is a prototype for generating LDAP search requests.
93 Templates are described by a prototype search filter and a list of
94 attributes which are required in queries generated from the template.
95 The representation for prototype filter is similar to {{REF:RFC4515}},
96 except that the assertion values are missing. Examples of prototype
97 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
98 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
100 The cache replacement policy removes the least recently used (LRU)
101 query and entries belonging to only that query. Queries are allowed
102 a maximum time to live (TTL) in the cache thus providing weak
103 consistency. A background task periodically checks the cache for
104 expired queries and removes them.
106 The Proxy Cache paper
107 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
108 design and implementation details.
111 H3: Proxy Cache Configuration
113 The cache configuration specific directives described below must
114 appear after a {{EX:overlay proxycache}} directive within a
115 {{EX:"database meta"}} or {{EX:database ldap}} section of
116 the server's {{slapd.conf}}(5) file.
118 H4: Setting cache parameters
120 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
122 This directive enables proxy caching and sets general cache
123 parameters. The <DB> parameter specifies which underlying database
124 is to be used to hold cached entries. It should be set to
125 {{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the
126 total number of entries which may be held in the cache. The
127 <nattrsets> parameter specifies the total number of attribute sets
128 (as specified by the {{EX:proxyAttrSet}} directive) that may be
129 defined. The <entrylimit> parameter specifies the maximum number of
130 entries in a cachable query. The <period> specifies the consistency
131 check period (in seconds). In each period, queries with expired
134 H4: Defining attribute sets
136 > proxyAttrset <index> <attrs...>
138 Used to associate a set of attributes to an index. Each attribute
139 set is associated with an index number from 0 to <numattrsets>-1.
140 These indices are used by the proxyTemplate directive to define
143 H4: Specifying cacheable templates
145 > proxyTemplate <prototype_string> <attrset_index> <TTL>
147 Specifies a cacheable template and the "time to live" (in sec) <TTL>
148 for queries belonging to the template. A template is described by
149 its prototype filter string and set of required attributes identified
155 An example {{slapd.conf}}(5) database section for a caching server
156 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
157 at server {{EX:ldap.example.com}}.
160 > suffix "dc=example,dc=com"
161 > rootdn "dc=example,dc=com"
162 > uri ldap://ldap.example.com/dc=example%2cdc=com
164 > proxycache bdb 100000 1 1000 100
165 > proxyAttrset 0 mail postaladdress telephonenumber
166 > proxyTemplate (sn=) 0 3600
167 > proxyTemplate (&(sn=)(givenName=)) 0 3600
168 > proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
171 > directory ./testrun/db.2.a
172 > index objectClass eq
173 > index cn,sn,uid,mail pres,eq,sub
176 H5: Cacheable Queries
178 A LDAP search query is cacheable when its filter matches one of the
179 templates as defined in the "proxyTemplate" statements and when it references
180 only the attributes specified in the corresponding attribute set.
181 In the example above the attribute set number 0 defines that only the
182 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
187 > Filter: (&(sn=Richard*)(givenName=jack))
188 > Attrs: mail telephoneNumber
190 is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
191 attributes are contained in proxyAttrset 0.
193 > Filter: (&(sn=Richard*)(telephoneNumber))
196 is not cacheable, because the filter does not match the template,
197 nor is the attribute givenName stored in the cache
199 > Filter: (|(sn=Richard*)(givenName=jack))
200 > Attrs: mail telephoneNumber
202 is not cacheable, because the filter does not match the template ( logical
203 OR "|" condition instead of logical AND "&" )
206 H2: Password Policies
212 H3: Password Policy Configuration
215 H2: Referential Integrity
221 H3: Referential Integrity Configuration
230 H3: Return Code Configuration
239 H3: Rewrite/Remap Configuration
248 H3: Sync Provider Configuration
251 H2: Translucent Proxy
257 H3: Translucent Proxy Configuration
260 H2: Attribute Uniqueness
266 H3: Attribute Uniqueness Configuration
275 H3: Value Sorting Configuration