1SLAPO-PCACHE(5) File Formats Manual SLAPO-PCACHE(5)
2
6 slapo-pcache - proxycache overlay
7
9 /etc/openldap/slapd.conf
10
12 The pcache overlay to slapd(8) allows caching of LDAP search requests
13 (queries) in a local database. For an incoming query, the proxy cache
14 determines its corresponding template. If the template was specified as
15 cacheable using the proxytemplate directive and the request is con‐
16 tained in a cached request, it is answered from the proxy cache. Oth‐
17 erwise, the search is performed as usual and cacheable search results
18 are saved in the cache for use in future queries.
19 A template is defined by a filter string and an index identifying a set
21 of attributes. The template string for a query can be obtained by
22 removing assertion values from the RFC 2254 representation of its
23 search filter. A query belongs to a template if its template string and
24 set of projected attributes correspond to a cacheable template. Exam‐
25 ples of template strings are (mail=), (|(sn=)(cn=)), (&(sn=)(given‐
26 Name=)).
27 The config directives that are specific to the proxycache overlay can
30 be prefixed by proxycache-, to avoid conflicts with directives specific
31 to the underlying database or to other stacked overlays. This may be
32 particularly useful for those directives that refer to the backend used
33 for local storage. The following cache specific directives can be used
34 to configure the proxy cache:
35 overlay pcache
37 This directive adds the proxy cache overlay to the current back‐
38 end. The proxy cache overlay may be used with any backend but is
39 intended for use with the ldap, meta, and sql backends.
40 proxycache <database> <max_entries> <numattrsets> <entry_limit>
42 <cc_period>
43 The directive enables proxy caching in the current backend and
44 sets general cache parameters. A <database> backend will be used
45 internally to maintain the cached entries. The chosen database
46 will need to be configured as well, as shown below. Cache
47 replacement is invoked when the cache size grows to
48 <max_entries> entries and continues till the cache size drops
49 below this size. <numattrsets> should be equal to the number of
50 following proxyattrset directives. Queries are cached only if
51 they correspond to a cacheable template (specified by the prox‐
52 ytemplate directive) and the number of entries returned is less
53 than <entry_limit>. Consistency check is performed every
54 <cc_period> duration (specified in secs). In each cycle queries
55 with expired "time to live(TTL)" are removed. A sample cache
56 configuration is:
57 proxycache bdb 10000 1 50 100
59 proxycachequeries <queries>
61 Specify the maximum number of queries to cache. The default is
62 10000.
63 proxyattrset <index> <attrs...>
66 Used to associate a set of attributes <attrs..> with an <index>.
67 Each attribute set is associated with an integer from 0 to
68 <numattrsets>-1. These indices are used by the proxytemplate
69 directive to define cacheable templates.
70 proxytemplate <template_string> <attrset_index> <ttl> [<negttl>]
73 Specifies a cacheable template and "time to live" (in sec) <ttl>
74 of queries belonging to the template. An optional <negttl> can
75 be used to specify that negative results (i.e., queries that
76 returned zero entries) should also be cached for the specified
77 number of seconds. Negative results are not cached by default.
78 response-callback { head | tail }
81 Specifies whether the response callback should be placed at the
82 tail (the default) or at the head (actually, wherever the stack‐
83 ing sequence would make it appear) of the callback list. This
84 affects how the overlay interacts with other overlays, since the
85 proxycache overlay should be executed as early as possible (and
86 thus configured as late as possible), to get a chance to return
87 the cached results; however, if executed early at response, it
88 would cache entries that may be later "massaged" by other data‐
89 bases and thus returned after massaging the first time, and
90 before massaging when cached.
91 There are some constraints:
94 all values must be positive;
96 <entry_limit> must be less than or equal to <max_entries>;
98 <numattrsets> attribute sets SHOULD be defined by using the
100 directive proxyattrset;
101 all attribute sets SHOULD be referenced by (at least) one prox‐
103 ytemplate directive;
104 The following adds a template with filter string (&(sn=)(givenName=))
107 and attributes mail, postaladdress, telephonenumber and a TTL of 1
108 hour.
109 proxyattrset 0 mail postaladdress telephonenumber
111 proxytemplate (&(sn=)(givenName=)) 0 3600
112 Directives for configuring the underlying database must also be given,
115 as shown here:
116 directory /var/tmp/cache
118 cachesize 100
119 Any valid directives for the chosen database type may be used. Indexing
121 should be used as appropriate for the queries being handled. In addi‐
122 tion, an equality index on the queryid attribute should be configured,
123 to assist in the removal of expired query data.
124
126 Caching data is prone to inconsistencies because updates on the remote
127 server will not be reflected in the response of the cache at least (and
128 at most) for the duration of the proxytemplate TTL.
129 The remote server should expose the objectClass attribute because the
131 underlying database that actually caches the entries may need it for
132 optimal local processing of the queries.
133 Another potential (and subtle) inconsistency may occur when data is
135 retrieved with different identities and specific per-identity access
136 control is enforced by the remote server. If data was retrieved with
137 an identity that collected only partial results because of access rules
138 enforcement on the remote server, other users with different access
139 privileges on the remote server will get different results from the
140 remote server and from the cache. If those users have higher access
141 privileges on the remote server, they will get from the cache only a
142 subset of the results they would get directly from the remote server;
143 but if they have lower access privileges, they will get from the cache
144 a superset of the results they would get directly from the remote
145 server. Either occurrence may or may not be acceptable, based on the
146 security policy of the cache and of the remote server. It is important
147 to note that in this case the proxy is violating the security of the
148 remote server by disclosing to an identity data that was collected by
149 another identity. For this reason, it is suggested that, when using
150 back-ldap, proxy caching be used in conjunction with the identity
151 assertion feature of slapd-ldap(5) (see the idassert-bind and the
152 idassert-authz statements), so that remote server interrogation occurs
153 with a vanilla identity that has some relatively high search and read
154 access privileges, and the "real" access control is delegated to the
155 proxy's ACLs. Beware that since only the cached fraction of the real
156 datum is available to the cache, it may not be possible to enforce the
157 same access rules that are defined on the remote server. When security
158 is a concern, cached proxy access must be carefully tailored.
159
161 /etc/openldap/slapd.conf
162 default slapd configuration file
163
165 slapd.conf(5), slapd-ldap(5), slapd-meta(5), slapd-sql(5), slapd(8).
166
168 Originally implemented by Apurva Kumar as an extension to back-meta;
169 turned into an overlay by Howard Chu.
170OpenLDAP 2.3.34 2007/2/16 SLAPO-PCACHE(5)