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

BACKWARD COMPATIBILITY

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

CAVEATS

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

FILES

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

SEE ALSO

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

AUTHOR

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