From: Howard Chu Date: Mon, 17 Aug 2009 00:39:30 +0000 (+0000) Subject: Use new keywords, deprecate old keywords, add ttr and pcacheOffline X-Git-Tag: ACLCHECK_0~324 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=0163567fab18e30fb4871e9551f4bb71b25090a7;p=openldap Use new keywords, deprecate old keywords, add ttr and pcacheOffline --- diff --git a/doc/man/man5/slapo-pcache.5 b/doc/man/man5/slapo-pcache.5 index e7f8e706ef..bb89334b8c 100644 --- a/doc/man/man5/slapo-pcache.5 +++ b/doc/man/man5/slapo-pcache.5 @@ -4,7 +4,7 @@ .\" Copyright 2001, Pierangelo Masarati, All rights reserved. .\" $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 +.B pcache The directive enables proxy caching in the current backend and sets general cache parameters. A 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 entries and continues till the cache size drops below this size. - should be equal to the number of following \fBproxyattrset\fP + 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 . Consistency check is performed every 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 +.B pcacheAttrset Used to associate a set of attributes with an . Each attribute set is associated with an integer from 0 to \-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 +.B pcacheMaxQueries 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 [ []] +.B pcacheTemplate [ [ []]] Specifies a cacheable template and "time to live" of queries belonging to the template. An optional 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 ( set to 0). An optional 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 ( set to 0). +An optional "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 should +be larger than the for this option to be useful. Entries are not +refreshed by default ( 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