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
22       removing  assertion  values  from  the  RFC  4515 representation of its
23       search filter. A query belongs to a template if its template string and
24       set  of projected attributes correspond to a cacheable template.  Exam‐
25       ples of template strings  are  (mail=),  (|(sn=)(cn=)),  (&(sn=)(given‐
26       Name=)).
27
28
29       The  config  directives  that are specific to the pcache overlay can be
30       prefixed by pcache-, to avoid conflicts with directives specific to the
31       underlying database or to other stacked overlays.  This may be particu‐
32       larly useful for those directives that refer to the  backend  used  for
33       local  storage.  The following cache specific directives can be used to
34       configure the proxy cache:
35
36       overlay pcache
37              This directive adds the proxy cache overlay to the current back‐
38              end. The proxy cache overlay may be used with any backend but is
39              intended for use with the ldap, meta, and sql  backends.  Please
40              note that the underlying backend must have a configured rootdn.
41
42       pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>
43              The  directive  enables proxy caching in the current backend and
44              sets general cache parameters. A <database> backend will be used
45              internally  to  maintain the cached entries. The chosen database
46              will need to be  configured  as  well,  as  shown  below.  Cache
47              replacement   is   invoked   when   the   cache  size  grows  to
48              <max_entries> entries and continues till the  cache  size  drops
49              below this size.  <numattrsets> should be equal to the number of
50              following pcacheAttrset directives. Queries are cached  only  if
51              they  correspond  to a cacheable template (specified by the pca‐
52              cheTemplate directive) and the number  of  entries  returned  is
53              less  than  <entry_limit>.  Consistency check is performed every
54              <cc_period> duration (specified in secs). In each cycle  queries
55              with  expired  "time  to  live(TTL)" are removed. A sample cache
56              configuration is:
57
58              pcache mdb 10000 1 50 100
59
60
61       pcacheAttrset <index> <attrs...>
62              Used to associate a set of attributes <attrs..> with an <index>.
63              Each  attribute  set  is  associated  with  an integer from 0 to
64              <numattrsets>-1. These indices are used  by  the  pcacheTemplate
65              directive  to  define  cacheable templates.  A set of attributes
66              cannot be empty.  A set of attributes can  contain  the  special
67              attributes  "*"  (all  user  attributes),  "+"  (all operational
68              attributes) or both; in the latter case, any other attribute  is
69              redundant   and  should  be  avoided  for  clarity.   A  set  of
70              attributes can contain "1.1" as  the  only  attribute;  in  this
71              case,  only  the  presence of the entries is cached.  Attributes
72              prefixed by "undef:" need not be present in the schema.
73
74
75       pcacheMaxQueries <queries>
76              Specify the maximum number of queries to cache. The  default  is
77              10000.
78
79
80       pcacheValidate { TRUE | FALSE }
81              Check  whether  the results of a query being cached can actually
82              be returned from the cache by the proxy DSA.  When enabled,  the
83              entries  being returned while caching the results of a query are
84              checked to ensure consistency with the schema known to the proxy
85              DSA.   In case of failure, the query is not cached.  By default,
86              the check is off.
87
88
89       pcacheOffline { TRUE | FALSE }
90              Set the cache to offline mode. While  offline,  the  consistency
91              checker  will  be  stopped  and  no expirations will occur. This
92              allows the cache contents to  be  used  indefinitely  while  the
93              proxy  is  cut  off  from network access to the remote DSA.  The
94              default is FALSE, i.e. consistency checks and  expirations  will
95              be performed.
96
97
98       pcachePersist { TRUE | FALSE }
99              Specify  whether  the  cached  queries  should  be  saved across
100              restarts of the caching proxy, to provide  hot  startup  of  the
101              cache.   Only  non-expired queries are reloaded.  The default is
102              FALSE.
103
104              CAVEAT: of course, the configuration of the proxy cache must not
105              change  across restarts; the pcache overlay does not perform any
106              consistency checks in this sense.  In detail, this option should
107              be disabled unless the existing pcacheAttrset and pcacheTemplate
108              directives are not changed neither in order nor in contents.  If
109              new  sets  and  templates  are added, or if other details of the
110              pcache overlay configuration changed, this feature should not be
111              affected.
112
113
114       pcacheTemplate   <template_string>   <attrset_index>   <ttl>  [<negttl>
115       [<limitttl> [<ttr>]]]
116              Specifies a cacheable template  and  "time  to  live"  <ttl>  of
117              queries  belonging  to the template. An optional <negttl> can be
118              used to  specify  that  negative  results  (i.e.,  queries  that
119              returned  zero  entries) should also be cached for the specified
120              amount of time. Negative  results  are  not  cached  by  default
121              (<negttl>  set  to  0).   An  optional <limitttl> can be used to
122              specify that results hitting a sizelimit should also  be  cached
123              for  the  specified amount of time.  Results hitting a sizelimit
124              are not cached by default (<limitttl> set to  0).   An  optional
125              <ttr>  "time  to  refresh"  can  be  used to specify that cached
126              entries should be automatically refreshed after a certain  time.
127              Entries  will  only be refreshed while they have not expired, so
128              the <ttl> should be larger than the <ttr> for this option to  be
129              useful. Entries are not refreshed by default (<ttr> set to 0).
130
131
132       pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>
133              Specifies  a  template for caching Simple Bind credentials based
134              on an already defined pcacheTemplate. The  <filter_template>  is
135              similar to a <template_string> except that it may have some val‐
136              ues present. Its purpose is to allow  the  overlay  to  generate
137              filters  similar  to  what  other applications do when they do a
138              Search immediately  before  a  Bind.  E.g.,  if  a  client  like
139              nss_ldap  is  configured  to  search  for a user with the filter
140              "(&(objectClass=posixAccount)(uid=<username>))" then the  corre‐
141              sponding  template  "(&(objectClass=posixAccount)(uid=))" should
142              be  used  here.  When  converted  to  a  regular  template  e.g.
143              "(&(objectClass=)(uid=))"  this template and the <attrset_index>
144              must match an already defined pcacheTemplate clause.  The  "time
145              to  refresh"  <ttr> determines the time interval after which the
146              cached credentials may be refreshed. The first Bind request that
147              occurs  after  that  time  will  trigger  the  refresh  attempt.
148              Refreshes are not performed when the overlay is  Offline.  There
149              is  no  "time  to  live" parameter for the Bind credentials; the
150              credentials will expire according to the pcacheTemplate ttl. The
151              <scope>  and  <base> should match the search scope and base used
152              by the authentication clients. The cached  credentials  are  not
153              stored  in cleartext, they are hashed using the default password
154              hash.  By default Bind caching is not enabled.
155
156
157       pcachePosition { head | tail }
158              Specifies whether the response callback should be placed at  the
159              tail (the default) or at the head (actually, wherever the stack‐
160              ing sequence would make it appear) of the callback  list.   This
161              affects how the overlay interacts with other overlays, since the
162              proxycache overlay should be executed as early as possible  (and
163              thus  configured as late as possible), to get a chance to return
164              the cached results; however, if executed early at  response,  it
165              would  cache entries that may be later "massaged" by other data‐
166              bases and thus returned after  massaging  the  first  time,  and
167              before massaging when cached.
168
169
170       There are some constraints:
171
172              all values must be positive;
173
174              <entry_limit> must be less than or equal to <max_entries>;
175
176              <numattrsets>  attribute  sets  SHOULD  be  defined by using the
177              directive pcacheAttrset;
178
179              all attribute sets SHOULD be referenced by (at least)  one  pca‐
180              cheTemplate directive;
181
182
183       The  following  adds a template with filter string (&(sn=)(givenName=))
184       and attributes mail, postaladdress, telephonenumber  and  a  TTL  of  1
185       hour.
186
187              pcacheAttrset 0 mail postaladdress telephonenumber
188              pcacheTemplate (&(sn=)(givenName=)) 0 3600
189
190
191       Directives  for configuring the underlying database must also be given,
192       as shown here:
193
194              directory /var/tmp/cache
195              cachesize 100
196
197       Any valid directives for the chosen database type may be used. Indexing
198       should  be  used as appropriate for the queries being handled. In addi‐
199       tion, an equality index on the pcacheQueryid attribute should  be  con‐
200       figured, to assist in the removal of expired query data.
201

BACKWARD COMPATIBILITY

203       The configuration keywords have been renamed and the older form is dep‐
204       recated. These older keywords are still recognized but may disappear in
205       future releases.
206
207
208       proxycache
209              use pcache
210
211
212       proxyattrset
213              use pcacheAttrset
214
215
216       proxycachequeries
217              use pcacheMaxQueries
218
219
220       proxycheckcacheability
221              use pcacheValidate
222
223
224       proxysavequeries
225              use pcachePersist
226
227
228       proxytemplate
229              use pcacheTemplate
230
231
232       response-callback
233              use pcachePosition
234
235

CAVEATS

237       Caching  data is prone to inconsistencies because updates on the remote
238       server will not be reflected in the response of the cache at least (and
239       at  most)  for the duration of the pcacheTemplate TTL.  These inconsis‐
240       tencies can be minimized by careful use of the TTR.
241
242       The remote server should expose the objectClass attribute  because  the
243       underlying  database  that  actually caches the entries may need it for
244       optimal local processing of the queries.
245
246       The proxy server should contain all the schema information required for
247       caching.   Significantly, it needs the schema of attributes used in the
248       query templates.  If the objectClass attribute is used in a query  tem‐
249       plate,  it  needs the definition of the objectClasses of the entries it
250       is supposed to cache.  It is the responsibility of the  proxy  adminis‐
251       trator  to  keep  the  proxy  schema  lined up with that of the proxied
252       server.
253
254       Another potential (and subtle) inconsistency may  occur  when  data  is
255       retrieved  with  different  identities and specific per-identity access
256       control is enforced by the remote server.  If data was  retrieved  with
257       an identity that collected only partial results because of access rules
258       enforcement on the remote server, other  users  with  different  access
259       privileges  on  the  remote  server will get different results from the
260       remote server and from the cache.  If those users  have  higher  access
261       privileges  on  the  remote server, they will get from the cache only a
262       subset of the results they would get directly from the  remote  server;
263       but  if they have lower access privileges, they will get from the cache
264       a superset of the results they  would  get  directly  from  the  remote
265       server.   Either  occurrence may or may not be acceptable, based on the
266       security policy of the cache and of the remote server.  It is important
267       to  note  that  in this case the proxy is violating the security of the
268       remote server by disclosing to an identity data that was  collected  by
269       another  identity.   For  this reason, it is suggested that, when using
270       back-ldap, proxy caching be  used  in  conjunction  with  the  identity
271       assertion  feature  of  slapd-ldap(5)  (see  the  idassert-bind and the
272       idassert-authz statements), so that remote server interrogation  occurs
273       with  a  vanilla identity that has some relatively high search and read
274       access privileges, and the "real" access control is  delegated  to  the
275       proxy's  ACLs.   Beware that since only the cached fraction of the real
276       datum is available to the cache, it may not be possible to enforce  the
277       same access rules that are defined on the remote server.  When security
278       is a concern, cached proxy access must be carefully tailored.
279

FILES

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

SEE ALSO

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

AUTHOR

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