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.
72 pcacheMaxQueries <queries>
75 Specify the maximum number of queries to cache. The default is
76 10000.
77 pcacheValidate { TRUE | FALSE }
80 Check whether the results of a query being cached can actually
81 be returned from the cache by the proxy DSA. When enabled, the
82 entries being returned while caching the results of a query are
83 checked to ensure consistency with the schema known to the proxy
84 DSA. In case of failure, the query is not cached. By default,
85 the check is off.
86 pcacheOffline { TRUE | FALSE }
89 Set the cache to offline mode. While offline, the consistency
90 checker will be stopped and no expirations will occur. This al‐
91 lows the cache contents to be used indefinitely while the proxy
92 is cut off from network access to the remote DSA. The default
93 is FALSE, i.e. consistency checks and expirations will be per‐
94 formed.
95 pcachePersist { TRUE | FALSE }
98 Specify whether the cached queries should be saved across
99 restarts of the caching proxy, to provide hot startup of the
100 cache. Only non-expired queries are reloaded. The default is
101 FALSE.
102 CAVEAT: of course, the configuration of the proxy cache must not
104 change across restarts; the pcache overlay does not perform any
105 consistency checks in this sense. In detail, this option should
106 be disabled unless the existing pcacheAttrset and pcacheTemplate
107 directives are not changed neither in order nor in contents. If
108 new sets and templates are added, or if other details of the
109 pcache overlay configuration changed, this feature should not be
110 affected.
111 pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl>
114 [<limitttl> [<ttr>]]]
115 Specifies a cacheable template and "time to live" <ttl> of
116 queries belonging to the template. An optional <negttl> can be
117 used to specify that negative results (i.e., queries that re‐
118 turned zero entries) should also be cached for the specified
119 amount of time. Negative results are not cached by default
120 (<negttl> set to 0). An optional <limitttl> can be used to
121 specify that results hitting a sizelimit should also be cached
122 for the specified amount of time. Results hitting a sizelimit
123 are not cached by default (<limitttl> set to 0). An optional
124 <ttr> "time to refresh" can be used to specify that cached en‐
125 tries should be automatically refreshed after a certain time.
126 Entries will only be refreshed while they have not expired, so
127 the <ttl> should be larger than the <ttr> for this option to be
128 useful. Entries are not refreshed by default (<ttr> set to 0).
129 pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>
132 Specifies a template for caching Simple Bind credentials based
133 on an already defined pcacheTemplate. The <filter_template> is
134 similar to a <template_string> except that it may have some val‐
135 ues present. Its purpose is to allow the overlay to generate
136 filters similar to what other applications do when they do a
137 Search immediately before a Bind. E.g., if a client like
138 nss_ldap is configured to search for a user with the filter
139 "(&(objectClass=posixAccount)(uid=<username>))" then the corre‐
140 sponding template "(&(objectClass=posixAccount)(uid=))" should
141 be used here. When converted to a regular template e.g. "(&(ob‐
142 jectClass=)(uid=))" this template and the <attrset_index> must
143 match an already defined pcacheTemplate clause. The "time to re‐
144 fresh" <ttr> determines the time interval after which the cached
145 credentials may be refreshed. The first Bind request that occurs
146 after that time will trigger the refresh attempt. Refreshes are
147 not performed when the overlay is Offline. There is no "time to
148 live" parameter for the Bind credentials; the credentials will
149 expire according to the pcacheTemplate ttl. The <scope> and
150 <base> should match the search scope and base used by the au‐
151 thentication clients. The cached credentials are not stored in
152 cleartext, they are hashed using the default password hash. By
153 default Bind caching is not enabled.
154 pcachePosition { head | tail }
157 Specifies whether the response callback should be placed at the
158 tail (the default) or at the head (actually, wherever the stack‐
159 ing sequence would make it appear) of the callback list. This
160 affects how the overlay interacts with other overlays, since the
161 proxycache overlay should be executed as early as possible (and
162 thus configured as late as possible), to get a chance to return
163 the cached results; however, if executed early at response, it
164 would cache entries that may be later "massaged" by other data‐
165 bases and thus returned after massaging the first time, and be‐
166 fore massaging when cached.
167 There are some constraints:
170 all values must be positive;
172 <entry_limit> must be less than or equal to <max_entries>;
174 <numattrsets> attribute sets SHOULD be defined by using the di‐
176 rective pcacheAttrset;
177 all attribute sets SHOULD be referenced by (at least) one pca‐
179 cheTemplate directive;
180 The following adds a template with filter string (&(sn=)(givenName=))
183 and attributes mail, postaladdress, telephonenumber and a TTL of 1
184 hour.
185 pcacheAttrset 0 mail postaladdress telephonenumber
187 pcacheTemplate (&(sn=)(givenName=)) 0 3600
188 Directives for configuring the underlying database must also be given,
191 as shown here:
192 directory /var/tmp/cache
194 cachesize 100
195 Any valid directives for the chosen database type may be used. Indexing
197 should be used as appropriate for the queries being handled. In addi‐
198 tion, an equality index on the pcacheQueryid attribute should be con‐
199 figured, to assist in the removal of expired query data.
200
202 The configuration keywords have been renamed and the older form is dep‐
203 recated. These older keywords are still recognized but may disappear in
204 future releases.
205 proxycache
208 use pcache
209 proxyattrset
212 use pcacheAttrset
213 proxycachequeries
216 use pcacheMaxQueries
217 proxycheckcacheability
220 use pcacheValidate
221 proxysavequeries
224 use pcachePersist
225 proxytemplate
228 use pcacheTemplate
229 response-callback
232 use pcachePosition
233
236 Caching data is prone to inconsistencies because updates on the remote
237 server will not be reflected in the response of the cache at least (and
238 at most) for the duration of the pcacheTemplate TTL. These inconsis‐
239 tencies can be minimized by careful use of the TTR.
240 The remote server should expose the objectClass attribute because the
242 underlying database that actually caches the entries may need it for
243 optimal local processing of the queries.
244 The proxy server should contain all the schema information required for
246 caching. Significantly, it needs the schema of attributes used in the
247 query templates. If the objectClass attribute is used in a query tem‐
248 plate, it needs the definition of the objectClasses of the entries it
249 is supposed to cache. It is the responsibility of the proxy adminis‐
250 trator to keep the proxy schema lined up with that of the proxied
251 server.
252 Another potential (and subtle) inconsistency may occur when data is re‐
254 trieved with different identities and specific per-identity access con‐
255 trol is enforced by the remote server. If data was retrieved with an
256 identity that collected only partial results because of access rules
257 enforcement on the remote server, other users with different access
258 privileges on the remote server will get different results from the re‐
259 mote server and from the cache. If those users have higher access
260 privileges on the remote server, they will get from the cache only a
261 subset of the results they would get directly from the remote server;
262 but if they have lower access privileges, they will get from the cache
263 a superset of the results they would get directly from the remote
264 server. Either occurrence may or may not be acceptable, based on the
265 security policy of the cache and of the remote server. It is important
266 to note that in this case the proxy is violating the security of the
267 remote server by disclosing to an identity data that was collected by
268 another identity. For this reason, it is suggested that, when using
269 back-ldap, proxy caching be used in conjunction with the identity as‐
270 sertion feature of slapd-ldap(5) (see the idassert-bind and the
271 idassert-authz statements), so that remote server interrogation occurs
272 with a vanilla identity that has some relatively high search and read
273 access privileges, and the "real" access control is delegated to the
274 proxy's ACLs. Beware that since only the cached fraction of the real
275 datum is available to the cache, it may not be possible to enforce the
276 same access rules that are defined on the remote server. When security
277 is a concern, cached proxy access must be carefully tailored.
278
280 /etc/openldap/slapd.conf
281 default slapd configuration file
282
284 slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5),
285 slapd-sql(5), slapd(8).
286
288 Originally implemented by Apurva Kumar as an extension to back-meta;
289 turned into an overlay by Howard Chu.
290OpenLDAP 2021/06/03 SLAPO-PCACHE(5)