1SLAPO-PCACHE(5)               File Formats Manual              SLAPO-PCACHE(5)
2
3
4

NAME

6       slapo-pcache - proxy cache overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

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
20       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
27
28       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
35       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
41       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
57              pcache mdb 10000 1 50 100
58
59
60       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
75
76       pcacheMaxQueries <queries>
77              Specify  the  maximum number of queries to cache. The default is
78              10000.
79
80
81       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
89
90       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
98
99       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
105              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
114
115       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
132
133       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
157
158       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
170
171       There are some constraints:
172
173              all values must be positive;
174
175              <entry_limit> must be less than or equal to <max_entries>;
176
177              <numattrsets> attribute sets SHOULD be defined by using the  di‐
178              rective pcacheAttrset;
179
180              all  attribute  sets SHOULD be referenced by (at least) one pca‐
181              cheTemplate directive;
182
183
184       The following adds a template with filter  string  (&(sn=)(givenName=))
185       and  attributes  mail,  postaladdress,  telephonenumber  and a TTL of 1
186       hour.
187
188              pcacheAttrset 0 mail postaladdress telephonenumber
189              pcacheTemplate (&(sn=)(givenName=)) 0 3600
190
191
192       Directives for configuring the underlying database must also be  given,
193       as shown here:
194
195              directory /var/tmp/cache
196              maxsize   1073741824
197
198       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

BACKWARD COMPATIBILITY

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
208
209       proxycache
210              use pcache
211
212
213       proxyattrset
214              use pcacheAttrset
215
216
217       proxycachequeries
218              use pcacheMaxQueries
219
220
221       proxycheckcacheability
222              use pcacheValidate
223
224
225       proxysavequeries
226              use pcachePersist
227
228
229       proxytemplate
230              use pcacheTemplate
231
232
233       response-callback
234              use pcachePosition
235
236

CAVEATS

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
243       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
247       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
251       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
259       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

FILES

286       /etc/openldap/slapd.conf
287              default slapd configuration file
288

SEE ALSO

290       slapd.conf(5),     slapd-config(5),    slapd-ldap(5),    slapd-meta(5),
291       slapd-sql(5), slapd(8).
292

AUTHOR

294       Originally implemented by Apurva Kumar as an  extension  to  back-meta;
295       turned into an overlay by Howard Chu.
296
297
298
299OpenLDAP 2.6.6                    2023/07/31                   SLAPO-PCACHE(5)
Impressum