1SLAPO-PCACHE(5) File Formats Manual SLAPO-PCACHE(5)
2
6 slapo-pcache - proxy cache overlay to slapd
7
9 /etc/openldap/slapd.conf
10
12 The pcache overlay to slapd(8) allows caching of LDAP search requests
13 (queries) in a local database. For an incoming query, the proxy cache
14 determines its corresponding template. If the template was specified as
15 cacheable using the pcacheTemplate directive and the request is con‐
16 tained in a cached request, it is answered from the proxy cache. Oth‐
17 erwise, the search is performed as usual and cacheable search results
18 are saved in the cache for use in future queries.
19 A template is defined by a filter string and an index identifying a set
21 of attributes. The template string for a query can be obtained by re‐
22 moving assertion values from the RFC 4515 representation of its search
23 filter. A query belongs to a template if its template string and set of
24 projected attributes correspond to a cacheable template. Examples of
25 template strings are (mail=), (|(sn=)(cn=)), (&(sn=)(givenName=)).
26 The config directives that are specific to the pcache overlay can be
29 prefixed by pcache-, to avoid conflicts with directives specific to the
30 underlying database or to other stacked overlays. This may be particu‐
31 larly useful for those directives that refer to the backend used for
32 local storage. The following cache specific directives can be used to
33 configure the proxy cache:
34 overlay pcache
36 This directive adds the proxy cache overlay to the current back‐
37 end. The proxy cache overlay may be used with any backend but is
38 intended for use with the ldap, meta, and sql backends. Please
39 note that the underlying backend must have a configured rootdn.
40 pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>
42 The directive enables proxy caching in the current backend and
43 sets general cache parameters. A <database> backend will be used
44 internally to maintain the cached entries. The chosen database
45 will need to be configured as well, as shown below. Cache re‐
46 placement is invoked when the cache size grows to <max_entries>
47 entries and continues till the cache size drops below this size.
48 <numattrsets> should be equal to the number of following
49 pcacheAttrset directives. Queries are cached only if they corre‐
50 spond to a cacheable template (specified by the pcacheTemplate
51 directive) and the number of entries returned is less than <en‐
52 try_limit>. Consistency check is performed every <cc_period> du‐
53 ration (specified in secs). In each cycle queries with expired
54 "time to live(TTL)" are removed. A sample cache configuration
55 is:
56 pcache mdb 10000 1 50 100
58 pcacheAttrset <index> <attrs...>
61 Used to associate a set of attributes <attrs..> with an <index>.
62 Each attribute set is associated with an integer from 0 to <nu‐
63 mattrsets>-1. These indices are used by the pcacheTemplate di‐
64 rective to define cacheable templates. A set of attributes can‐
65 not be empty. A set of attributes can contain the special at‐
66 tributes "*" (all user attributes), "+" (all operational at‐
67 tributes) or both; in the latter case, any other attribute is
68 redundant and should be avoided for clarity. A set of at‐
69 tributes can contain "1.1" as the only attribute; in this case,
70 only the presence of the entries is cached. Attributes prefixed
71 by "undef:" need not be present in the schema. The "undef" key‐
72 word cannot be used with the slapd-mdb(5) backend as it requires
73 all schema elements be fully defined.
74 pcacheMaxQueries <queries>
77 Specify the maximum number of queries to cache. The default is
78 10000.
79 pcacheValidate { TRUE | FALSE }
82 Check whether the results of a query being cached can actually
83 be returned from the cache by the proxy DSA. When enabled, the
84 entries being returned while caching the results of a query are
85 checked to ensure consistency with the schema known to the proxy
86 DSA. In case of failure, the query is not cached. By default,
87 the check is off.
88 pcacheOffline { TRUE | FALSE }
91 Set the cache to offline mode. While offline, the consistency
92 checker will be stopped and no expirations will occur. This al‐
93 lows the cache contents to be used indefinitely while the proxy
94 is cut off from network access to the remote DSA. The default
95 is FALSE, i.e. consistency checks and expirations will be per‐
96 formed.
97 pcachePersist { TRUE | FALSE }
100 Specify whether the cached queries should be saved across
101 restarts of the caching proxy, to provide hot startup of the
102 cache. Only non-expired queries are reloaded. The default is
103 FALSE.
104 CAVEAT: of course, the configuration of the proxy cache must not
106 change across restarts; the pcache overlay does not perform any
107 consistency checks in this sense. In detail, this option should
108 be disabled unless the existing pcacheAttrset and pcacheTemplate
109 directives are not changed neither in order nor in contents. If
110 new sets and templates are added, or if other details of the
111 pcache overlay configuration changed, this feature should not be
112 affected.
113 pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl>
116 [<limitttl> [<ttr>]]]
117 Specifies a cacheable template and "time to live" <ttl> of
118 queries belonging to the template. An optional <negttl> can be
119 used to specify that negative results (i.e., queries that re‐
120 turned zero entries) should also be cached for the specified
121 amount of time. Negative results are not cached by default
122 (<negttl> set to 0). An optional <limitttl> can be used to
123 specify that results hitting a sizelimit should also be cached
124 for the specified amount of time. Results hitting a sizelimit
125 are not cached by default (<limitttl> set to 0). An optional
126 <ttr> "time to refresh" can be used to specify that cached en‐
127 tries should be automatically refreshed after a certain time.
128 Entries will only be refreshed while they have not expired, so
129 the <ttl> should be larger than the <ttr> for this option to be
130 useful. Entries are not refreshed by default (<ttr> set to 0).
131 pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>
134 Specifies a template for caching Simple Bind credentials based
135 on an already defined pcacheTemplate. The <filter_template> is
136 similar to a <template_string> except that it may have some val‐
137 ues present. Its purpose is to allow the overlay to generate
138 filters similar to what other applications do when they do a
139 Search immediately before a Bind. E.g., if a client like
140 nss_ldap is configured to search for a user with the filter
141 "(&(objectClass=posixAccount)(uid=<username>))" then the corre‐
142 sponding template "(&(objectClass=posixAccount)(uid=))" should
143 be used here. When converted to a regular template e.g. "(&(ob‐
144 jectClass=)(uid=))" this template and the <attrset_index> must
145 match an already defined pcacheTemplate clause. The "time to re‐
146 fresh" <ttr> determines the time interval after which the cached
147 credentials may be refreshed. The first Bind request that occurs
148 after that time will trigger the refresh attempt. Refreshes are
149 not performed when the overlay is Offline. There is no "time to
150 live" parameter for the Bind credentials; the credentials will
151 expire according to the pcacheTemplate ttl. The <scope> and
152 <base> should match the search scope and base used by the au‐
153 thentication clients. The cached credentials are not stored in
154 cleartext, they are hashed using the default password hash. By
155 default Bind caching is not enabled.
156 pcachePosition { head | tail }
159 Specifies whether the response callback should be placed at the
160 tail (the default) or at the head (actually, wherever the stack‐
161 ing sequence would make it appear) of the callback list. This
162 affects how the overlay interacts with other overlays, since the
163 proxycache overlay should be executed as early as possible (and
164 thus configured as late as possible), to get a chance to return
165 the cached results; however, if executed early at response, it
166 would cache entries that may be later "massaged" by other data‐
167 bases and thus returned after massaging the first time, and be‐
168 fore massaging when cached.
169 There are some constraints:
172 all values must be positive;
174 <entry_limit> must be less than or equal to <max_entries>;
176 <numattrsets> attribute sets SHOULD be defined by using the di‐
178 rective pcacheAttrset;
179 all attribute sets SHOULD be referenced by (at least) one pca‐
181 cheTemplate directive;
182 The following adds a template with filter string (&(sn=)(givenName=))
185 and attributes mail, postaladdress, telephonenumber and a TTL of 1
186 hour.
187 pcacheAttrset 0 mail postaladdress telephonenumber
189 pcacheTemplate (&(sn=)(givenName=)) 0 3600
190 Directives for configuring the underlying database must also be given,
193 as shown here:
194 directory /var/tmp/cache
196 maxsize 1073741824
197 Any valid directives for the chosen database type may be used. Indexing
199 should be used as appropriate for the queries being handled. In addi‐
200 tion, an equality index on the pcacheQueryid attribute should be con‐
201 figured, to assist in the removal of expired query data.
202
204 The configuration keywords have been renamed and the older form is dep‐
205 recated. These older keywords are still recognized but may disappear in
206 future releases.
207 proxycache
210 use pcache
211 proxyattrset
214 use pcacheAttrset
215 proxycachequeries
218 use pcacheMaxQueries
219 proxycheckcacheability
222 use pcacheValidate
223 proxysavequeries
226 use pcachePersist
227 proxytemplate
230 use pcacheTemplate
231 response-callback
234 use pcachePosition
235
238 Caching data is prone to inconsistencies because updates on the remote
239 server will not be reflected in the response of the cache at least (and
240 at most) for the duration of the pcacheTemplate TTL. These inconsis‐
241 tencies can be minimized by careful use of the TTR.
242 The proxy cache overlay requires a full result set of data to properly
244 function. Therefore it will strip out the paged results control if it
245 is requested by the client.
246 The remote server should expose the objectClass attribute because the
248 underlying database that actually caches the entries may need it for
249 optimal local processing of the queries.
250 The proxy server should contain all the schema information required for
252 caching. Significantly, it needs the schema of attributes used in the
253 query templates. If the objectClass attribute is used in a query tem‐
254 plate, it needs the definition of the objectClasses of the entries it
255 is supposed to cache. It is the responsibility of the proxy adminis‐
256 trator to keep the proxy schema lined up with that of the proxied
257 server.
258 Another potential (and subtle) inconsistency may occur when data is re‐
260 trieved with different identities and specific per-identity access con‐
261 trol is enforced by the remote server. If data was retrieved with an
262 identity that collected only partial results because of access rules
263 enforcement on the remote server, other users with different access
264 privileges on the remote server will get different results from the re‐
265 mote server and from the cache. If those users have higher access
266 privileges on the remote server, they will get from the cache only a
267 subset of the results they would get directly from the remote server;
268 but if they have lower access privileges, they will get from the cache
269 a superset of the results they would get directly from the remote
270 server. Either occurrence may or may not be acceptable, based on the
271 security policy of the cache and of the remote server. It is important
272 to note that in this case the proxy is violating the security of the
273 remote server by disclosing to an identity data that was collected by
274 another identity. For this reason, it is suggested that, when using
275 back-ldap, proxy caching be used in conjunction with the identity as‐
276 sertion feature of slapd-ldap(5) (see the idassert-bind and the
277 idassert-authz statements), so that remote server interrogation occurs
278 with a vanilla identity that has some relatively high search and read
279 access privileges, and the "real" access control is delegated to the
280 proxy's ACLs. Beware that since only the cached fraction of the real
281 datum is available to the cache, it may not be possible to enforce the
282 same access rules that are defined on the remote server. When security
283 is a concern, cached proxy access must be carefully tailored.
284
286 /etc/openldap/slapd.conf
287 default slapd configuration file
288
290 slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5),
291 slapd-sql(5), slapd(8).
292
294 Originally implemented by Apurva Kumar as an extension to back-meta;
295 turned into an overlay by Howard Chu.
296OpenLDAP 2.6.6 2023/07/31 SLAPO-PCACHE(5)