mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
209 lines
7.6 KiB
Groff
209 lines
7.6 KiB
Groff
.TH SLAPO-PCACHE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" Copyright 1998-2006 The OpenLDAP Foundation, All Rights Reserved.
|
|
.\" Copying restrictions apply. See the COPYRIGHT file.
|
|
.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
|
|
.\" $OpenLDAP$
|
|
.SH NAME
|
|
slapo-pcache \- proxycache overlay
|
|
.SH SYNOPSIS
|
|
ETCDIR/slapd.conf
|
|
.SH DESCRIPTION
|
|
The
|
|
.B pcache
|
|
overlay to
|
|
.BR slapd (8)
|
|
allows caching of LDAP search requests (queries) in a local database.
|
|
For an incoming query, the
|
|
proxy cache determines its corresponding \fBtemplate\fP. If the template
|
|
was specified as cacheable using the \fBproxytemplate\fP 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.
|
|
.LP
|
|
|
|
A template is defined by a filter string and an index identifying a set of
|
|
attributes. The \fBtemplate string\fP 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 \fB(mail=)\fP, \fB(|(sn=)(cn=))\fP,
|
|
\fB(&(sn=)(givenName=))\fP.
|
|
|
|
.LP
|
|
The config directives that are specific to the
|
|
.B proxycache
|
|
overlay can be prefixed by
|
|
.BR 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:
|
|
.TP
|
|
.B 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
|
|
.BR ldap ,
|
|
.BR meta ,
|
|
and
|
|
.BR sql
|
|
backends.
|
|
.TP
|
|
.B proxycache <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 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 \fBproxyattrset\fP
|
|
directives. Queries are cached only if they correspond to a cacheable template
|
|
(specified by the \fBproxytemplate\fP 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(\fBTTL\fP)" are removed. A sample cache configuration is:
|
|
.LP
|
|
.RS
|
|
proxycache \fBbdb 10000 1 50 100\fP
|
|
.RE
|
|
.TP
|
|
.B proxycachequeries <queries>
|
|
Specify the maximum number of queries to cache. The default is 10000.
|
|
|
|
.TP
|
|
.B 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 \fBproxytemplate\fP directive to define cacheable templates.
|
|
|
|
.TP
|
|
.B 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.
|
|
|
|
.TP
|
|
.B response-callback { head | tail }
|
|
Specifies whether the response callback should be placed at the
|
|
.B tail
|
|
(the default) or at the
|
|
.B 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 \fIafter\fP massaging the first
|
|
time, and \fIbefore\fP massaging when cached.
|
|
|
|
.TP
|
|
There are some constraints:
|
|
|
|
all values must be positive;
|
|
|
|
.B <entry_limit>
|
|
must be less than or equal to
|
|
.BR <max_entries> ;
|
|
|
|
.B <numattrsets>
|
|
attribute sets SHOULD be defined by using the directive
|
|
.BR proxyattrset ;
|
|
|
|
all attribute sets SHOULD be referenced by (at least) one
|
|
.B proxytemplate
|
|
directive;
|
|
|
|
.LP
|
|
The following adds a template with filter string \fB(&(sn=)(givenName=))\fP
|
|
and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour.
|
|
.LP
|
|
.RS
|
|
.nf
|
|
proxyattrset \fB0 mail postaladdress telephonenumber\fP
|
|
proxytemplate \fB(&(sn=)(givenName=)) 0 3600\fP
|
|
.fi
|
|
.RE
|
|
|
|
.LP
|
|
Directives for configuring the underlying database must also be given, as
|
|
shown here:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
directory /var/tmp/cache
|
|
cachesize 100
|
|
.fi
|
|
.RE
|
|
.LP
|
|
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 \fBqueryid\fP attribute should be configured, to
|
|
assist in the removal of expired query data.
|
|
.SH 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
|
|
.B proxytemplate
|
|
.BR TTL .
|
|
|
|
The remote server should expose the
|
|
.B 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 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 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 suggested that, when using
|
|
.BR back-ldap ,
|
|
proxy caching be used in conjunction with the
|
|
.I identity assertion
|
|
feature of
|
|
.BR slapd-ldap (5)
|
|
(see the
|
|
.B idassert-bind
|
|
and the
|
|
.B idassert-authz
|
|
statements), so that remote server interrogation occurs with a vanilla identity
|
|
that has some relatively high
|
|
.B search
|
|
and
|
|
.B 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.
|
|
.SH FILES
|
|
|
|
.TP
|
|
ETCDIR/slapd.conf
|
|
default slapd configuration file
|
|
.SH SEE ALSO
|
|
.BR slapd.conf (5),
|
|
.BR slapd\-ldap (5),
|
|
.BR slapd\-meta (5),
|
|
.BR slapd\-sql (5),
|
|
.BR slapd (8).
|
|
.SH AUTHOR
|
|
Originally implemented by Apurva Kumar as an extension to back-meta;
|
|
turned into an overlay by Howard Chu.
|