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.
72
73
74       pcacheMaxQueries <queries>
75              Specify  the  maximum number of queries to cache. The default is
76              10000.
77
78
79       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
87
88       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
96
97       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
103              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
112
113       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
130
131       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
155
156       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
168
169       There are some constraints:
170
171              all values must be positive;
172
173              <entry_limit> must be less than or equal to <max_entries>;
174
175              <numattrsets> attribute sets SHOULD be defined by using the  di‐
176              rective pcacheAttrset;
177
178              all  attribute  sets SHOULD be referenced by (at least) one pca‐
179              cheTemplate directive;
180
181
182       The following adds a template with filter  string  (&(sn=)(givenName=))
183       and  attributes  mail,  postaladdress,  telephonenumber  and a TTL of 1
184       hour.
185
186              pcacheAttrset 0 mail postaladdress telephonenumber
187              pcacheTemplate (&(sn=)(givenName=)) 0 3600
188
189
190       Directives for configuring the underlying database must also be  given,
191       as shown here:
192
193              directory /var/tmp/cache
194              cachesize 100
195
196       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

BACKWARD COMPATIBILITY

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

CAVEATS

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
241       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
245       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
253       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

FILES

280       /etc/openldap/slapd.conf
281              default slapd configuration file
282

SEE ALSO

284       slapd.conf(5),     slapd-config(5),    slapd-ldap(5),    slapd-meta(5),
285       slapd-sql(5), slapd(8).
286

AUTHOR

288       Originally implemented by Apurva Kumar as an  extension  to  back-meta;
289       turned into an overlay by Howard Chu.
290
291
292
293OpenLDAP                          2021/06/03                   SLAPO-PCACHE(5)
Impressum