1 .TH SLAPO-PCACHE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2011 The OpenLDAP Foundation, All Rights Reserved.
3 .\" Copying restrictions apply. See the COPYRIGHT file.
4 .\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
7 slapo\-pcache \- proxy cache overlay to slapd
15 allows caching of LDAP search requests (queries) in a local database.
16 For an incoming query, the
17 proxy cache determines its corresponding \fBtemplate\fP. If the template
18 was specified as cacheable using the \fBpcacheTemplate\fP directive
19 and the request is contained in a cached request, it is answered from
21 Otherwise, the search is performed as usual and cacheable search results
22 are saved in the cache for use in future queries.
25 A template is defined by a filter string and an index identifying a set of
26 attributes. The \fBtemplate string\fP for a query can be obtained by
27 removing assertion values from the RFC 4515 representation of its search
28 filter. A query belongs to a template if its template string and set of
29 projected attributes correspond to a cacheable template.
30 Examples of template strings are \fB(mail=)\fP, \fB(|(sn=)(cn=))\fP,
31 \fB(&(sn=)(givenName=))\fP.
34 The config directives that are specific to the
36 overlay can be prefixed by
38 to avoid conflicts with directives specific to the underlying database
39 or to other stacked overlays. This may be particularly useful for those
40 directives that refer to the backend used for local storage.
41 The following cache specific directives can be used to configure the proxy
45 This directive adds the proxy cache overlay to the current backend. The
46 proxy cache overlay may be used with any backend but is intended for use
52 backends. Please note that the underlying backend must have a configured
55 .B pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>
56 The directive enables proxy caching in the current backend and sets general
57 cache parameters. A <database> backend will be used internally to maintain
58 the cached entries. The chosen database will need to be configured as well,
59 as shown below. Cache replacement is invoked when the cache size grows to
60 <max_entries> entries and continues till the cache size drops below this size.
61 <numattrsets> should be equal to the number of following \fBpcacheAttrset\fP
62 directives. Queries are cached only if they correspond to a cacheable template
63 (specified by the \fBpcacheTemplate\fP directive) and the number of entries
64 returned is less than <entry_limit>. Consistency check is performed every
65 <cc_period> duration (specified in secs). In each cycle queries with expired
66 "time to live(\fBTTL\fP)" are removed. A sample cache configuration is:
69 pcache \fBbdb 10000 1 50 100\fP
73 .B pcacheAttrset <index> <attrs...>
74 Used to associate a set of attributes <attrs..> with an <index>. Each attribute
75 set is associated with an integer from 0 to <numattrsets>\-1. These indices are
76 used by the \fBpcacheTemplate\fP directive to define cacheable templates.
77 A set of attributes cannot be empty. A set of attributes can contain the
78 special attributes "*" (all user attributes), "+" (all operational attributes)
79 or both; in the latter case, any other attribute is redundant and should
80 be avoided for clarity. A set of attributes can contain "1.1" as the only
81 attribute; in this case, only the presence of the entries is cached.
84 .B pcacheMaxQueries <queries>
85 Specify the maximum number of queries to cache. The default is 10000.
88 .B pcacheValidate { TRUE | FALSE }
89 Check whether the results of a query being cached can actually be returned
90 from the cache by the proxy DSA. When enabled, the entries being returned
91 while caching the results of a query are checked to ensure consistency
92 with the schema known to the proxy DSA. In case of failure, the query
93 is not cached. By default, the check is off.
96 .B pcacheOffline { TRUE | FALSE }
97 Set the cache to offline mode. While offline, the consistency checker
98 will be stopped and no expirations will occur. This allows the cache
99 contents to be used indefinitely while the proxy is cut off from network
100 access to the remote DSA. The default is FALSE, i.e. consistency
101 checks and expirations will be performed.
104 .B pcachePersist { TRUE | FALSE }
105 Specify whether the cached queries should be saved across restarts
106 of the caching proxy, to provide hot startup of the cache. Only non-expired
107 queries are reloaded. The default is FALSE.
110 of course, the configuration of the proxy cache must not change
111 across restarts; the pcache overlay does not perform any consistency
112 checks in this sense.
113 In detail, this option should be disabled unless the existing
117 directives are not changed neither in order nor in contents.
118 If new sets and templates are added, or if other details of the pcache
119 overlay configuration changed, this feature should not be affected.
122 .B pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]]
123 Specifies a cacheable template and "time to live" <ttl> of queries
124 belonging to the template. An optional <negttl> can be used to specify
125 that negative results (i.e., queries that returned zero entries)
126 should also be cached for the specified amount of time. Negative
127 results are not cached by default (<negttl> set to 0).
128 An optional <limitttl> can be used to specify that results
129 hitting a sizelimit should also be cached for the specified amount of time.
130 Results hitting a sizelimit are not cached by default (<limitttl> set to 0).
131 An optional <ttr> "time to refresh" can be used to specify that cached
132 entries should be automatically refreshed after a certain time. Entries
133 will only be refreshed while they have not expired, so the <ttl> should
134 be larger than the <ttr> for this option to be useful. Entries are not
135 refreshed by default (<ttr> set to 0).
138 .B pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>
139 Specifies a template for caching Simple Bind credentials based on an
140 already defined \fBpcacheTemplate\fP. The <filter_template> is similar
141 to a <template_string> except that it may have some values present. Its
142 purpose is to allow the overlay to generate filters similar to what other
143 applications do when they do a Search immediately before a Bind. E.g.,
144 if a client like nss_ldap is configured to search for a user with the
145 filter "(&(objectClass=posixAccount)(uid=<username>))" then the corresponding
146 template "(&(objectClass=posixAccount)(uid=))" should be used here. When
147 converted to a regular template e.g. "(&(objectClass=)(uid=))" this
148 template and the <attrset_index> must match an already defined
149 \fBpcacheTemplate\fP clause. The "time to refresh" <ttr> determines the
150 time interval after which the cached credentials may be refreshed. The
151 first Bind request that occurs after that time will trigger the refresh
152 attempt. Refreshes are not performed when the overlay is Offline. There
153 is no "time to live" parameter for the Bind credentials; the credentials
154 will expire according to the \fBpcacheTemplate\fP ttl. The <scope> and
155 <base> should match the search scope and base used by the authentication
156 clients. The cached credentials are not stored in cleartext, they are
157 hashed using the default password hash.
158 By default Bind caching is not enabled.
161 .B pcachePosition { head | tail }
162 Specifies whether the response callback should be placed at the
164 (the default) or at the
166 (actually, wherever the stacking sequence would make it appear)
167 of the callback list. This affects how the overlay interacts with other
168 overlays, since the proxycache overlay should be executed as early
169 as possible (and thus configured as late as possible), to get
170 a chance to return the cached results; however, if executed early
171 at response, it would cache entries that may be later "massaged"
172 by other databases and thus returned \fIafter\fP massaging the first
173 time, and \fIbefore\fP massaging when cached.
176 There are some constraints:
178 all values must be positive;
181 must be less than or equal to
185 attribute sets SHOULD be defined by using the directive
188 all attribute sets SHOULD be referenced by (at least) one
193 The following adds a template with filter string \fB(&(sn=)(givenName=))\fP
194 and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour.
198 pcacheAttrset \fB0 mail postaladdress telephonenumber\fP
199 pcacheTemplate \fB(&(sn=)(givenName=)) 0 3600\fP
204 Directives for configuring the underlying database must also be given, as
209 directory /var/tmp/cache
214 Any valid directives for the chosen database type may be used. Indexing
215 should be used as appropriate for the queries being handled. In addition,
216 an equality index on the \fBpcacheQueryid\fP attribute should be configured, to
217 assist in the removal of expired query data.
218 .SH BACKWARD COMPATIBILITY
219 The configuration keywords have been renamed and the older form is
220 deprecated. These older keywords are still recognized but may disappear
236 .B proxycheckcacheability
252 Caching data is prone to inconsistencies because updates on the remote server
253 will not be reflected in the response of the cache at least (and at most)
254 for the duration of the
257 These inconsistencies can be minimized by careful use of the TTR.
259 The remote server should expose the
261 attribute because the underlying database that actually caches the entries
262 may need it for optimal local processing of the queries.
264 The proxy server should contain all the schema information required for caching.
265 Significantly, it needs the schema of attributes used in the query templates.
266 If the objectClass attribute is used in a query template, it needs the definition
267 of the objectClasses of the entries it is supposed to cache.
268 It is the responsibility of the proxy administrator to keep the proxy schema
269 lined up with that of the proxied server.
271 Another potential (and subtle) inconsistency may occur when data is retrieved
272 with different identities and specific per-identity access control
273 is enforced by the remote server.
274 If data was retrieved with an identity that collected only partial results
275 because of access rules enforcement on the remote server, other users
276 with different access privileges on the remote server will get different
277 results from the remote server and from the cache.
278 If those users have higher access privileges on the remote server, they will
279 get from the cache only a subset of the results they would get directly
280 from the remote server; but if they have lower access privileges, they will
281 get from the cache a superset of the results they would get directly
282 from the remote server.
283 Either occurrence may or may not be acceptable, based on the security policy
284 of the cache and of the remote server.
285 It is important to note that in this case the proxy is violating the security
286 of the remote server by disclosing to an identity data that was collected
288 For this reason, it is suggested that, when using
290 proxy caching be used in conjunction with the
291 .I identity assertion
298 statements), so that remote server interrogation occurs with a vanilla identity
299 that has some relatively high
303 access privileges, and the "real" access control is delegated to the proxy's ACLs.
304 Beware that since only the cached fraction of the real datum is available
305 to the cache, it may not be possible to enforce the same access rules that
306 are defined on the remote server.
307 When security is a concern, cached proxy access must be carefully tailored.
312 default slapd configuration file
315 .BR slapd\-config (5),
321 Originally implemented by Apurva Kumar as an extension to back-meta;
322 turned into an overlay by Howard Chu.
projects / openldap / blob