1.lf 1 stdin 2.TH SLAPO-PCACHE 5 "2020/04/28" "OpenLDAP 2.4.50" 3.\" Copyright 1998-2020 The OpenLDAP Foundation, All Rights Reserved. 4.\" Copying restrictions apply. See the COPYRIGHT file. 5.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> 6.\" $OpenLDAP$ 7.SH NAME 8slapo\-pcache \- proxy cache overlay to slapd 9.SH SYNOPSIS 10/etc/openldap/slapd.conf 11.SH DESCRIPTION 12The 13.B pcache 14overlay to 15.BR slapd (8) 16allows caching of LDAP search requests (queries) in a local database. 17For an incoming query, the 18proxy cache determines its corresponding \fBtemplate\fP. If the template 19was specified as cacheable using the \fBpcacheTemplate\fP directive 20and the request is contained in a cached request, it is answered from 21the proxy cache. 22Otherwise, the search is performed as usual and cacheable search results 23are saved in the cache for use in future queries. 24.LP 25 26A template is defined by a filter string and an index identifying a set of 27attributes. The \fBtemplate string\fP for a query can be obtained by 28removing assertion values from the RFC 4515 representation of its search 29filter. A query belongs to a template if its template string and set of 30projected attributes correspond to a cacheable template. 31Examples of template strings are \fB(mail=)\fP, \fB(|(sn=)(cn=))\fP, 32\fB(&(sn=)(givenName=))\fP. 33 34.LP 35The config directives that are specific to the 36.B pcache 37overlay can be prefixed by 38.BR pcache\- , 39to avoid conflicts with directives specific to the underlying database 40or to other stacked overlays. This may be particularly useful for those 41directives that refer to the backend used for local storage. 42The following cache specific directives can be used to configure the proxy 43cache: 44.TP 45.B overlay pcache 46This directive adds the proxy cache overlay to the current backend. The 47proxy cache overlay may be used with any backend but is intended for use 48with the 49.BR ldap , 50.BR meta , 51and 52.BR sql 53backends. Please note that the underlying backend must have a configured 54.BR rootdn. 55.TP 56.B pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period> 57The directive enables proxy caching in the current backend and sets general 58cache parameters. A <database> backend will be used internally to maintain 59the cached entries. The chosen database will need to be configured as well, 60as shown below. Cache replacement is invoked when the cache size grows to 61<max_entries> entries and continues till the cache size drops below this size. 62<numattrsets> should be equal to the number of following \fBpcacheAttrset\fP 63directives. Queries are cached only if they correspond to a cacheable template 64(specified by the \fBpcacheTemplate\fP directive) and the number of entries 65returned is less than <entry_limit>. Consistency check is performed every 66<cc_period> duration (specified in secs). In each cycle queries with expired 67"time to live(\fBTTL\fP)" are removed. A sample cache configuration is: 68.LP 69.RS 70pcache \fBmdb 10000 1 50 100\fP 71.RE 72 73.TP 74.B pcacheAttrset <index> <attrs...> 75Used to associate a set of attributes <attrs..> with an <index>. Each attribute 76set is associated with an integer from 0 to <numattrsets>\-1. These indices are 77used by the \fBpcacheTemplate\fP directive to define cacheable templates. 78A set of attributes cannot be empty. A set of attributes can contain the 79special attributes "*" (all user attributes), "+" (all operational attributes) 80or both; in the latter case, any other attribute is redundant and should 81be avoided for clarity. A set of attributes can contain "1.1" as the only 82attribute; in this case, only the presence of the entries is cached. 83Attributes prefixed by "undef:" need not be present in the schema. 84 85.TP 86.B pcacheMaxQueries <queries> 87Specify the maximum number of queries to cache. The default is 10000. 88 89.TP 90.B pcacheValidate { TRUE | FALSE } 91Check whether the results of a query being cached can actually be returned 92from the cache by the proxy DSA. When enabled, the entries being returned 93while caching the results of a query are checked to ensure consistency 94with the schema known to the proxy DSA. In case of failure, the query 95is not cached. By default, the check is off. 96 97.TP 98.B pcacheOffline { TRUE | FALSE } 99Set the cache to offline mode. While offline, the consistency checker 100will be stopped and no expirations will occur. This allows the cache 101contents to be used indefinitely while the proxy is cut off from network 102access to the remote DSA. The default is FALSE, i.e. consistency 103checks and expirations will be performed. 104 105.TP 106.B pcachePersist { TRUE | FALSE } 107Specify whether the cached queries should be saved across restarts 108of the caching proxy, to provide hot startup of the cache. Only non-expired 109queries are reloaded. The default is FALSE. 110 111.BR CAVEAT : 112of course, the configuration of the proxy cache must not change 113across restarts; the pcache overlay does not perform any consistency 114checks in this sense. 115In detail, this option should be disabled unless the existing 116.B pcacheAttrset 117and 118.B pcacheTemplate 119directives are not changed neither in order nor in contents. 120If new sets and templates are added, or if other details of the pcache 121overlay configuration changed, this feature should not be affected. 122 123.TP 124.B pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]] 125Specifies a cacheable template and "time to live" <ttl> of queries 126belonging to the template. An optional <negttl> can be used to specify 127that negative results (i.e., queries that returned zero entries) 128should also be cached for the specified amount of time. Negative 129results are not cached by default (<negttl> set to 0). 130An optional <limitttl> can be used to specify that results 131hitting a sizelimit should also be cached for the specified amount of time. 132Results hitting a sizelimit are not cached by default (<limitttl> set to 0). 133An optional <ttr> "time to refresh" can be used to specify that cached 134entries should be automatically refreshed after a certain time. Entries 135will only be refreshed while they have not expired, so the <ttl> should 136be larger than the <ttr> for this option to be useful. Entries are not 137refreshed by default (<ttr> set to 0). 138 139.TP 140.B pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base> 141Specifies a template for caching Simple Bind credentials based on an 142already defined \fBpcacheTemplate\fP. The <filter_template> is similar 143to a <template_string> except that it may have some values present. Its 144purpose is to allow the overlay to generate filters similar to what other 145applications do when they do a Search immediately before a Bind. E.g., 146if a client like nss_ldap is configured to search for a user with the 147filter "(&(objectClass=posixAccount)(uid=<username>))" then the corresponding 148template "(&(objectClass=posixAccount)(uid=))" should be used here. When 149converted to a regular template e.g. "(&(objectClass=)(uid=))" this 150template and the <attrset_index> must match an already defined 151\fBpcacheTemplate\fP clause. The "time to refresh" <ttr> determines the 152time interval after which the cached credentials may be refreshed. The 153first Bind request that occurs after that time will trigger the refresh 154attempt. Refreshes are not performed when the overlay is Offline. There 155is no "time to live" parameter for the Bind credentials; the credentials 156will expire according to the \fBpcacheTemplate\fP ttl. The <scope> and 157<base> should match the search scope and base used by the authentication 158clients. The cached credentials are not stored in cleartext, they are 159hashed using the default password hash. 160By default Bind caching is not enabled. 161 162.TP 163.B pcachePosition { head | tail } 164Specifies whether the response callback should be placed at the 165.B tail 166(the default) or at the 167.B head 168(actually, wherever the stacking sequence would make it appear) 169of the callback list. This affects how the overlay interacts with other 170overlays, since the proxycache overlay should be executed as early 171as possible (and thus configured as late as possible), to get 172a chance to return the cached results; however, if executed early 173at response, it would cache entries that may be later "massaged" 174by other databases and thus returned \fIafter\fP massaging the first 175time, and \fIbefore\fP massaging when cached. 176 177.TP 178There are some constraints: 179 180all values must be positive; 181 182.B <entry_limit> 183must be less than or equal to 184.BR <max_entries> ; 185 186.B <numattrsets> 187attribute sets SHOULD be defined by using the directive 188.BR pcacheAttrset ; 189 190all attribute sets SHOULD be referenced by (at least) one 191.B pcacheTemplate 192directive; 193 194.LP 195The following adds a template with filter string \fB(&(sn=)(givenName=))\fP 196and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour. 197.LP 198.RS 199.nf 200pcacheAttrset \fB0 mail postaladdress telephonenumber\fP 201pcacheTemplate \fB(&(sn=)(givenName=)) 0 3600\fP 202.fi 203.RE 204 205.LP 206Directives for configuring the underlying database must also be given, as 207shown here: 208.LP 209.RS 210.nf 211directory /var/tmp/cache 212cachesize 100 213.fi 214.RE 215.LP 216Any valid directives for the chosen database type may be used. Indexing 217should be used as appropriate for the queries being handled. In addition, 218an equality index on the \fBpcacheQueryid\fP attribute should be configured, to 219assist in the removal of expired query data. 220.SH BACKWARD COMPATIBILITY 221The configuration keywords have been renamed and the older form is 222deprecated. These older keywords are still recognized but may disappear 223in future releases. 224 225.TP 226.B proxycache 227use pcache 228 229.TP 230.B proxyattrset 231use pcacheAttrset 232 233.TP 234.B proxycachequeries 235use pcacheMaxQueries 236 237.TP 238.B proxycheckcacheability 239use pcacheValidate 240 241.TP 242.B proxysavequeries 243use pcachePersist 244 245.TP 246.B proxytemplate 247use pcacheTemplate 248 249.TP 250.B response-callback 251use pcachePosition 252 253.SH CAVEATS 254Caching data is prone to inconsistencies because updates on the remote server 255will not be reflected in the response of the cache at least (and at most) 256for the duration of the 257.B pcacheTemplate 258.BR TTL . 259These inconsistencies can be minimized by careful use of the TTR. 260 261The remote server should expose the 262.B objectClass 263attribute because the underlying database that actually caches the entries 264may need it for optimal local processing of the queries. 265 266The proxy server should contain all the schema information required for caching. 267Significantly, it needs the schema of attributes used in the query templates. 268If the objectClass attribute is used in a query template, it needs the definition 269of the objectClasses of the entries it is supposed to cache. 270It is the responsibility of the proxy administrator to keep the proxy schema 271lined up with that of the proxied server. 272 273Another potential (and subtle) inconsistency may occur when data is retrieved 274with different identities and specific per-identity access control 275is enforced by the remote server. 276If data was retrieved with an identity that collected only partial results 277because of access rules enforcement on the remote server, other users 278with different access privileges on the remote server will get different 279results from the remote server and from the cache. 280If those users have higher access privileges on the remote server, they will 281get from the cache only a subset of the results they would get directly 282from the remote server; but if they have lower access privileges, they will 283get from the cache a superset of the results they would get directly 284from the remote server. 285Either occurrence may or may not be acceptable, based on the security policy 286of the cache and of the remote server. 287It is important to note that in this case the proxy is violating the security 288of the remote server by disclosing to an identity data that was collected 289by another identity. 290For this reason, it is suggested that, when using 291.BR back-ldap , 292proxy caching be used in conjunction with the 293.I identity assertion 294feature of 295.BR slapd\-ldap (5) 296(see the 297.B idassert\-bind 298and the 299.B idassert\-authz 300statements), so that remote server interrogation occurs with a vanilla identity 301that has some relatively high 302.B search 303and 304.B read 305access privileges, and the "real" access control is delegated to the proxy's ACLs. 306Beware that since only the cached fraction of the real datum is available 307to the cache, it may not be possible to enforce the same access rules that 308are defined on the remote server. 309When security is a concern, cached proxy access must be carefully tailored. 310.SH FILES 311 312.TP 313/etc/openldap/slapd.conf 314default slapd configuration file 315.SH SEE ALSO 316.BR slapd.conf (5), 317.BR slapd\-config (5), 318.BR slapd\-ldap (5), 319.BR slapd\-meta (5), 320.BR slapd\-sql (5), 321.BR slapd (8). 322.SH AUTHOR 323Originally implemented by Apurva Kumar as an extension to back-meta; 324turned into an overlay by Howard Chu. 325