.TH SLAPO-PCACHE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2004 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2007 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
+slapo-pcache \- proxycache overlay to slapd
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
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
+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=)).
+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 proxycache
-This directive adds the proxycache overlay to the current backend. The
-proxycache overlay may be used with any backend but is intended for use
+.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 ,
.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 proxysavequeries { 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.
+
+.BR CAVEAT :
+of course, the configuration of the proxycache 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
+.B proxyattrset
+and
+.B proxytemplate
+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.
+
.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.
+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.
.TP
-.B proxytemplate <template_string> <attrset_index> <ttl>
+.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.
+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 (&sn=)(givenName=)) and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour.
+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
proxytemplate \fB(&(sn=)(givenName=)) 0 3600\fP
.fi
.RE
+
.LP
Directives for configuring the underlying database must also be given, as
shown here:
.fi
.RE
.LP
-Any valid directives for the chosen database type may be used.
+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
.BR slapd\-ldap (5),
.BR slapd\-meta (5),
.BR slapd\-sql (5),
-.BR slapd (8),
-.BR regex (7).
+.BR slapd (8).
.SH AUTHOR
Originally implemented by Apurva Kumar as an extension to back-meta;
turned into an overlay by Howard Chu.
projects / openldap / blobdiff