slapo-pcache(5)
SLAPO-PCACHE(5) FILE FORMATS SLAPO-PCACHE(5)
NAME
slapo-pcache - proxycache overlay
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 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=)),
(&(sn=)(givenName=)).
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
SLAPO-PCACHE(5) FILE FORMATS SLAPO-PCACHE(5)
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
is:
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
templates.
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
<max_entries>;
OpenLDAP 2.3.27 Last change: 2006/08/19 2
SLAPO-PCACHE(5) FILE FORMATS SLAPO-PCACHE(5)
<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.
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
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
queries.
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
SLAPO-PCACHE(5) FILE FORMATS SLAPO-PCACHE(5)
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.
FILES
/etc/openldap/slapd.conf
default slapd configuration file
SEE ALSO
slapd.conf(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.3.27 Last change: 2006/08/19 4
Man(1) output converted with
man2html