slapo-pcache - proxycache overlay




     The pcache overlay to slapd(8) allows caching of LDAP search
     requests  (queries)  in  a  local database.  For an incoming
     query, the proxy cache  determines  its  corresponding  tem-
     plate.  If the template was specified as cacheable using the
     proxytemplate directive and the request is  contained  in  a
     cached request, it is answered from the proxy cache.  Other-
     wise, the search is performed as usual and cacheable  search
     results are saved in the cache for use in future queries.

     A template is defined by a filter string and an index  iden-
     tifying a set of attributes. The template string for a query
     can be obtained by removing assertion values  from  the  RFC
     2254 representation of its search filter. A query belongs to
     a template if its  template  string  and  set  of  projected
     attributes  correspond to a cacheable template.  Examples of
     template     strings     are     (mail=),     (|(sn=)(cn=)),

     The config directives that are specific  to  the  proxycache
     overlay  can  be prefixed by proxycache-, to avoid conflicts
     with directives specific to the underlying  database  or  to
     other stacked overlays.  This may be particularly useful for
     those directives that refer to the backend  used  for  local
     storage.   The  following  cache  specific directives can be
     used to configure the proxy cache:

     overlay pcache
          This directive adds the  proxy  cache  overlay  to  the
          current  backend.  The  proxy cache overlay may be used
          with any backend but is intended for use with the ldap,
          meta, and sql backends.

     proxycache <database> <max_entries>  <numattrsets>  <entry_limit>
          The  directive  enables  proxy  caching  in the current
          backend and sets general cache parameters. A <database>
          backend  will be used internally to maintain the cached
          entries. The chosen database will need to be configured
          as  well,  as shown below. Cache replacement is invoked
          when the cache size grows to <max_entries> entries  and
          continues  till  the  cache size drops below this size.
          <numattrsets> should be equal to the number of  follow-
          ing proxyattrset directives. Queries are cached only if
          they correspond to a cacheable template  (specified  by

OpenLDAP 2.3.27      Last change: 2006/08/19                    1


          the  proxytemplate directive) and the number of entries
          returned is less than <entry_limit>. Consistency  check
          is  performed  every <cc_period> duration (specified in
          secs). In each cycle  queries  with  expired  "time  to
          live(TTL)"  are  removed.  A sample cache configuration

          proxycache bdb 10000 1 50 100

     proxycachequeries <queries>
          Specify the maximum number of  queries  to  cache.  The
          default is 10000.

     proxyattrset <index> <attrs...>
          Used to associate a set of attributes <attrs..> with an
          <index>.  Each  attribute  set  is  associated  with an
          integer from 0 to <numattrsets>-1.  These  indices  are
          used by the proxytemplate directive to define cacheable

     proxytemplate <template_string> <attrset_index> <ttl> [<negttl>]
          Specifies  a  cacheable template and "time to live" (in
          sec) <ttl> of queries belonging  to  the  template.  An
          optional  <negttl> can be used to specify that negative
          results (i.e.,  queries  that  returned  zero  entries)
          should  also  be  cached  for  the  specified number of
          seconds. Negative results are not cached by default.

     response-callback { head | tail }
          Specifies  whether  the  response  callback  should  be
          placed  at the tail (the default) or at the head (actu-
          ally, wherever the  stacking  sequence  would  make  it
          appear)  of  the  callback  list.  This affects how the
          overlay interacts with other overlays, since the proxy-
          cache  overlay  should be executed as early as possible
          (and thus configured as late as  possible),  to  get  a
          chance  to  return the cached results; however, if exe-
          cuted early at response, it would  cache  entries  that
          may  be  later  "massaged"  by other databases and thus
          returned after massaging the  first  time,  and  before
          massaging when cached.

     There are some constraints:

          all values must be positive;

          <entry_limit>  must  be   less   than   or   equal   to

OpenLDAP 2.3.27      Last change: 2006/08/19                    2


          <numattrsets> attribute sets SHOULD be defined by using
          the directive proxyattrset;

          all attribute sets SHOULD be referenced by  (at  least)
          one proxytemplate directive;

     The  following  adds   a   template   with   filter   string
     (&(sn=)(givenName=))  and  attributes  mail,  postaladdress,
     telephonenumber and a TTL of 1 hour.

          proxyattrset 0 mail postaladdress telephonenumber
          proxytemplate (&(sn=)(givenName=)) 0 3600

     Directives for configuring the underlying database must also
     be given, as shown here:

          directory /var/tmp/cache
          cachesize 100

     Any valid directives for the chosen  database  type  may  be
     used. Indexing should be used as appropriate for the queries
     being handled. In addition, an equality index on the queryid
     attribute  should be configured, to assist in the removal of
     expired query data.


     Caching data is prone to inconsistencies because updates  on
     the  remote  server will not be reflected in the response of
     the cache at least (and at most) for  the  duration  of  the
     proxytemplate TTL.

     The remote server should expose  the  objectClass  attribute
     because  the  underlying  database  that actually caches the
     entries may need it for  optimal  local  processing  of  the

     Another potential (and subtle) inconsistency may occur  when
     data  is  retrieved  with  different identities and specific
     per-identity  access  control  is  enforced  by  the  remote
     server.   If  data  was retrieved with an identity that col-
     lected only partial results because of access rules enforce-
     ment on the remote server, other users with different access
     privileges on the remote server will get  different  results
     from  the  remote server and from the cache.  If those users
     have higher access privileges on  the  remote  server,  they
     will  get  from  the cache only a subset of the results they
     would get directly from the remote server; but if they  have
     lower  access  privileges,  they  will  get from the cache a
     superset of the results they would  get  directly  from  the
     remote   server.   Either  occurrence  may  or  may  not  be

OpenLDAP 2.3.27      Last change: 2006/08/19                    3


     acceptable, based on the security policy of the cache and of
     the  remote  server.   It  is important to note that in this
     case the proxy is  violating  the  security  of  the  remote
     server  by disclosing to an identity data that was collected
     by another identity.  For this reason, it is suggested that,
     when  using  back-ldap, proxy caching be used in conjunction
     with the identity assertion feature  of  slapd-ldap(5)  (see
     the  idassert-bind  and  the  idassert-authz statements), so
     that remote server interrogation occurs with a vanilla iden-
     tity  that  has  some relatively high search and read access
     privileges, and the "real" access control  is  delegated  to
     the  proxy's  ACLs.  Beware that since only the cached frac-
     tion of the real datum is available to the cache, it may not
     be  possible  to  enforce  the  same  access  rules that are
     defined on the remote server.  When security is  a  concern,
     cached proxy access must be carefully tailored.


          default slapd configuration file


     slapd.conf(5), slapd-ldap(5),  slapd-meta(5),  slapd-sql(5),


     Originally implemented by Apurva Kumar as  an  extension  to
     back-meta; turned into an overlay by Howard Chu.

OpenLDAP 2.3.27      Last change: 2006/08/19                    4

Man(1) output converted with man2html