Use new keywords, deprecate old keywords, add ttr and pcacheOffline

doc/man/man5/slapo-pcache.5

@@ -4,7 +4,7 @@
 .\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
 .\" $OpenLDAP$
 .SH NAME
-slapo\-pcache \- proxycache overlay to slapd
+slapo\-pcache \- proxy cache overlay to slapd
 .SH SYNOPSIS
 ETCDIR/slapd.conf
 .SH DESCRIPTION
@@ -32,9 +32,9 @@ Examples of template strings are \fB(mail=)\fP, \fB(|(sn=)(cn=))\fP,
 
 .LP 
 The config directives that are specific to the
-.B proxycache
+.B pcache
 overlay can be prefixed by
-.BR proxycache\- ,
+.BR pcache\- ,
 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.
@@ -51,28 +51,28 @@ and
 .BR sql
 backends.
 .TP
-.B proxycache <database> <max_entries> <numattrsets> <entry_limit> <cc_period> 
+.B 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 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
+<numattrsets> should be equal to the number of following \fBpcacheAttrset\fP
 directives. Queries are cached only if they correspond to a cacheable template
-(specified by the \fBproxytemplate\fP directive) and the number of entries
+(specified by the \fBpcacheTemplate\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
+pcache \fBbdb 10000 1 50 100\fP
 .RE
 
 .TP
-.B proxyattrset <index> <attrs...>
+.B 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 <numattrsets>\-1. These indices are
-used by the \fBproxytemplate\fP directive to define cacheable templates. 
+used by the \fBpcacheTemplate\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
@@ -80,11 +80,11 @@ 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 proxycachequeries <queries>
+.B pcacheMaxQueries <queries>
 Specify the maximum number of queries to cache. The default is 10000.
 
 .TP
-.B proxycheckcacheability { TRUE | FALSE }
+.B 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
@@ -92,25 +92,33 @@ with the schema known to the proxy DSA.  In case of failure, the query
 is not cached.  By default, the check is off.
 
 .TP
-.B proxysavequeries { TRUE | FALSE }
+.B pcacheOffline { TRUE | FALSE }
+Set the cache to offline mode. While offline, the consistency checker
+will be stopped and no expirations will occur. This allows 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 performed.
+
+.TP
+.B 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.
 
 .BR CAVEAT :
-of course, the configuration of the proxycache must not change
+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
-.B proxyattrset
+.B pcacheAttrset
 and
-.B proxytemplate
+.B 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.
 
 .TP
-.B proxytemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl>]]
+.B 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 returned zero entries)
@@ -119,9 +127,14 @@ 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
+entries 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).
 
 .TP
-.B response\-callback { head | tail }
+.B pcachePosition { head | tail }
 Specifies whether the response callback should be placed at the
 .B tail
 (the default) or at the 
@@ -158,8 +171,8 @@ 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
+pcacheAttrset \fB0 mail postaladdress telephonenumber\fP
+pcacheTemplate \fB(&(sn=)(givenName=)) 0 3600\fP
 .fi
 .RE
 
@@ -178,12 +191,46 @@ 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 BACKWARD COMPATIBILITY
+The configuration keywords have been renamed and the older form is
+deprecated. These older keywords are still recognized but may disappear
+in future releases.
+
+.TP
+.B proxycache
+use pcache
+
+.TP
+.B proxyattrset
+use pcacheAttrset
+
+.TP
+.B proxycachequeries
+use pcacheMaxQueries
+
+.TP
+.B proxycheckcacheability
+use pcacheValidate
+
+.TP
+.B proxysavequeries
+use pcachePersist
+
+.TP
+.B proxytemplate
+use pcacheTemplate
+
+.TP
+.B response-callback
+use pcachePosition
+
 .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
+.B pcacheTemplate
 .BR TTL .
+These inconsistencies can be minimized by by careful use of the TTR.
 
 The remote server should expose the
 .B objectClass