Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SLAPO-PCACHE(5)		      File Formats Manual	       SLAPO-PCACHE(5)

NAME
       slapo-pcache - proxy cache overlay to slapd

SYNOPSIS
       /usr/local/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  con-
       tained  in a cached request, it is answered from	the proxy cache.  Oth-
       erwise, 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  re-
       moving  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 particu-
       larly  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 back-
	      end. 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  database
	      will  need  to  be configured as well, as	shown below. Cache re-
	      placement	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	corre-
	      spond to a cacheable template (specified by  the	pcacheTemplate
	      directive)  and the number of entries returned is	less than <en-
	      try_limit>. Consistency check is performed every <cc_period> du-
	      ration  (specified  in secs). In each cycle queries with expired
	      "time to live(TTL)" are removed. A  sample  cache	 configuration
	      is:

	      pcache mdb 10000 1 50 100

       pcacheAttrset <index> <attrs...>
	      Used to associate	a set of attributes <attrs..> with an <index>.
	      Each attribute set is associated with an integer from 0 to  <nu-
	      mattrsets>-1.  These  indices are	used by	the pcacheTemplate di-
	      rective to define	cacheable templates.  A	set of attributes can-
	      not  be  empty.  A set of	attributes can contain the special at-
	      tributes "*" (all	user attributes),  "+"	(all  operational  at-
	      tributes)	 or  both;  in the latter case,	any other attribute is
	      redundant	and should be avoided  for  clarity.   A  set  of  at-
	      tributes	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.  The "undef" key-
	      word cannot be used with the slapd-mdb(5)	backend	as it requires
	      all schema elements be fully defined.

       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  al-
	      lows  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 per-
	      formed.

       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 re-
	      turned 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  en-
	      tries  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 pcacheTemplate. The <filter_template> is
	      similar to a <template_string> except that it may	have some val-
	      ues  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=posixAccount)(uid=<username>))"  then the	corre-
	      sponding template	 "(&(objectClass=posixAccount)(uid=))"	should
	      be  used here. When converted to a regular template e.g. "(&(ob-
	      jectClass=)(uid=))" this template	and the	 <attrset_index>  must
	      match an already defined pcacheTemplate clause. The "time	to re-
	      fresh" <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  pcacheTemplate  ttl. The <scope> and
	      <base> should match the search scope and base used  by  the  au-
	      thentication  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	stack-
	      ing  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	 data-
	      bases  and thus returned after massaging the first time, and be-
	      fore 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  di-
	      rective pcacheAttrset;

	      all  attribute  sets SHOULD be referenced	by (at least) one pca-
	      cheTemplate directive;

       The following adds a template with filter  string  (&(sn=)(givenName=))
       and  attributes	mail,  postaladdress,  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	 addi-
       tion,  an  equality index on the	pcacheQueryid attribute	should be con-
       figured,	to assist in the removal of expired query data.

BACKWARD COMPATIBILITY
       The configuration keywords have been renamed and	the older form is dep-
       recated.	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  inconsis-
       tencies can be minimized	by careful use of the TTR.

       The  proxy cache	overlay	requires a full	result set of data to properly
       function. Therefore it will strip out the paged results control	if  it
       is requested by the client.

       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 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 tem-
       plate, it needs the definition of the objectClasses of the  entries  it
       is  supposed  to	cache.	It is the responsibility of the	proxy adminis-
       trator to keep the proxy	schema lined  up  with	that  of  the  proxied
       server.

       Another potential (and subtle) inconsistency may	occur when data	is re-
       trieved with different identities and specific per-identity access con-
       trol  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	different results from the re-
       mote  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 suggested  that,  when	 using
       back-ldap,  proxy  caching be used in conjunction with the identity as-
       sertion	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
       /usr/local/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.6.2			  2022/05/04		       SLAPO-PCACHE(5)

NAME | SYNOPSIS | DESCRIPTION | BACKWARD COMPATIBILITY | CAVEATS | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=slapo-pcache&sektion=5&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help