document "cancel" feature

[openldap] / doc / man / man5 / slapo-pcache.5

diff --git a/doc/man/man5/slapo-pcache.5 b/doc/man/man5/slapo-pcache.5
index ff977f7a7d3557b75b74e7540bdd2e20a9104ff9..66891d3de28ebea150c677dd749cb9fb2ba67c15 100644 (file)
--- a/doc/man/man5/slapo-pcache.5
+++ b/doc/man/man5/slapo-pcache.5
@@ -1,5 +1,5 @@
 .TH SLAPO-PCACHE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2005 The OpenLDAP Foundation, All Rights Reserved.
+.\" 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$
@@ -67,6 +67,10 @@ returned is less than <entry_limit>. Consistency check is performed every
 .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
@@ -74,9 +78,12 @@ 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> 
+.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 }
@@ -111,7 +118,7 @@ all attribute sets SHOULD be referenced by (at least) one
 directive; 
 
 .LP
-The following adds a template with filter string \fB((&sn=)(givenName=))\fP 
+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
@@ -132,8 +139,61 @@ cachesize 100
 .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