Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

SLAPO-PCACHE(5)                                                                              SLAPO-PCACHE(5)



NAME
       slapo-pcache - proxy cache overlay to slapd

SYNOPSIS
       /etc/openldap/slapd.conf

DESCRIPTION
       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 template.  If  the  template  was
       specified  as  cacheable  using the pcacheTemplate directive and the request is contained in a cached
       request, it is answered from the proxy cache.  Otherwise,  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 identifying a set of attributes. The template
       string for a query can be obtained by removing assertion values from the RFC 4515  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=)), (&(sn=)(givenName=)).


       The  config  directives  that are specific to the pcache overlay can be prefixed by pcache-, 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.
              Please note that the underlying backend must have a configured rootdn.

       pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>
              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 data-base database
              base 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  following  pcacheAttrset  directives.
              Queries  are  cached  only  if  they correspond to a cacheable template (specified by the pca-cheTemplate pcacheTemplate
              cheTemplate directive) and the number of entries returned is less than <entry_limit>.  Consis-tency Consistency
              tency 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 is:

              pcache bdb 10000 1 50 100


       pcacheAttrset <index> <attrs...>
              Used to associate a set of attributes <attrs..> with an <index>. Each attribute set is associ-ated associated
              ated  with  an integer from 0 to <numattrsets>-1. These indices are used by the pcacheTemplate
              directive to define cacheable templates.  A set of attributes  cannot  be  empty.   A  set  of
              attributes  can contain the special attributes "*" (all user attributes), "+" (all operational
              attributes) or both; in the latter case, any  other  attribute  is  redundant  and  should  be
              avoided  for  clarity.   A  set of attributes can contain "1.1" as the only attribute; in this
              case, only the presence of the entries is cached.  Attributes prefixed by "undef:" need not be
              present in the schema.


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


       pcacheValidate { TRUE | FALSE }
              Check  whether  the results of a query being cached can actually be returned from the cache by
              the proxy DSA.  When enabled, the entries being returned while caching the results of a  query
              are checked to ensure consistency with the schema known to the proxy DSA.  In case of failure,
              the query is not cached.  By default, the check is off.


       pcacheOffline { TRUE | FALSE }
              Set the cache to offline mode. While offline, the consistency checker will be stopped  and  no
              expirations will occur. This allows the cache contents to be used indefinitely while the proxy
              is cut off from network access to the remote DSA.  The  default  is  FALSE,  i.e.  consistency
              checks and expirations will be performed.


       pcachePersist { TRUE | FALSE }
              Specify  whether  the  cached queries should be saved across restarts of the caching proxy, to
              provide hot startup of the cache.  Only non-expired queries  are  reloaded.   The  default  is
              FALSE.

              CAVEAT:  of  course, the configuration of the proxy cache must not change across restarts; the
              pcache overlay does not perform any consistency checks in this sense.  In detail, this  option
              should  be  disabled  unless  the existing pcacheAttrset and pcacheTemplate directives are not
              changed neither in order nor in contents.  If new sets and templates are added,  or  if  other
              details of the pcache overlay configuration changed, this feature should not be affected.


       pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]]
              Specifies  a cacheable template and "time to live" <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 amount of time. Negative results are not
              cached by default (<negttl> set to 0).  An optional <limitttl> can be  used  to  specify  that
              results  hitting  a sizelimit should also be cached for the specified amount of time.  Results
              hitting a sizelimit are not cached by default (<limitttl> set to 0).  An optional <ttr>  "time
              to refresh" can be used to specify that cached entries should be automatically refreshed after
              a certain time. Entries will only be refreshed while they  have  not  expired,  so  the  <ttl>
              should  be  larger  than  the <ttr> for this option to be useful. Entries are not refreshed by
              default (<ttr> set to 0).


       pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>
              Specifies a template for caching Simple Bind credentials based  on  an  already  defined  pca-cheTemplate. pcacheTemplate.
              cheTemplate.  The  <filter_template> is similar to a <template_string> except that it may have
              some values present. Its purpose is to allow the overlay to generate filters similar  to  what
              other  applications do when they do a Search immediately before a Bind. E.g., if a client like
              nss_ldap is  configured  to  search  for  a  user  with  the  filter  "(&(objectClass=posixAc-count)(uid=<username>))" "(&(objectClass=posixAccount)(uid=<username>))"
              count)(uid=<username>))" then the corresponding template "(&(objectClass=posixAccount)(uid=))"
              should be used here. When converted to a regular template e.g. "(&(objectClass=)(uid=))"  this
              template  and  the  <attrset_index>  must  match an already defined pcacheTemplate clause. The
              "time to refresh" <ttr> determines the time interval after which the cached credentials may be
              refreshed.  The  first  Bind  request  that  occurs  after  that time will trigger the refresh
              attempt. Refreshes are not performed when the overlay is Offline. There is no "time  to  live"
              parameter  for  the  Bind credentials; the credentials will expire according to the pcacheTem-plate pcacheTemplate
              plate ttl. The <scope> and <base> should match the search scope and base used by the authenti-cation authentication
              cation  clients. The cached credentials are not stored in cleartext, they are hashed using the
              default password hash.  By default Bind caching is not enabled.


       pcachePosition { head | tail }
              Specifies whether the response callback should be placed at the tail (the default) or  at  the
              head  (actually,  wherever  the  stacking sequence would make it appear) of the callback list.
              This affects how the overlay interacts with  other  overlays,  since  the  proxycache  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 executed 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 <max_entries>;

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

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


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

              pcacheAttrset 0 mail postaladdress telephonenumber
              pcacheTemplate (&(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 pcacheQueryid  attribute  should
       be configured, to assist in the removal of expired query data.

BACKWARD COMPATIBILITY
       The  configuration  keywords have been renamed and the older form is deprecated. These older keywords
       are still recognized but may disappear in future releases.


       proxycache
              use pcache


       proxyattrset
              use pcacheAttrset


       proxycachequeries
              use pcacheMaxQueries


       proxycheckcacheability
              use pcacheValidate


       proxysavequeries
              use pcachePersist


       proxytemplate
              use pcacheTemplate


       response-callback
              use pcachePosition


CAVEATS
       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 pcacheTemplate TTL.
       These inconsistencies can be minimized by careful use of the TTR.

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

       The  proxy  server should contain all the schema information required for caching.  Significantly, it
       needs the schema of attributes used in the query templates.  If the objectClass attribute is used  in
       a  query  template,  it  needs  the  definition of the objectClasses of the entries it is supposed to
       cache.  It is the responsibility of the proxy administrator to keep the proxy schema  lined  up  with
       that of the proxied server.

       Another  potential (and subtle) inconsistency may occur when data is retrieved with different identi-ties identities
       ties and specific per-identity access control  is  enforced  by  the  remote  server.   If  data  was
       retrieved with an identity that collected only partial results because of access rules enforcement on
       the remote server, other users with different access privileges on the remote server will get differ-ent different
       ent  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 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 sug-gested suggested
       gested 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 identity 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 fraction 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.

FILES
       /etc/openldap/slapd.conf
              default slapd configuration file

SEE ALSO
       slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5), slapd-sql(5), slapd(8).

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



OpenLDAP 2.4.28                                  2011/11/24                                  SLAPO-PCACHE(5)