H2: Overview
-The proxy cache extension of slapd handles a search request (query)
+The proxy cache extension of slapd is designed to improve the
+responseiveness of the ldap and meta backends. It handles a search
+request (query)
by first determining whether it is contained in any cached search
filter. Contained requests are answered from the proxy cache's local
-database.
+database. Other requests are passed on to the underlying ldap or
+meta backend and processed as usual.
E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
{{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
belongs to one of these templates. The entries corresponding to
cached queries are stored in the proxy cache local database while
its associated meta information (filter, scope, base, attributes)
-is stored in main memory. Instead of sending a referral for requests
-which are not contained, it acts as a proxy and obtains the result
-by querying one or more target servers. The proxy cache extends the
-meta backend and uses it to connect to target servers.
+is stored in main memory.
A template is a prototype for generating LDAP search requests.
Templates are described by a prototype search filter and a list of
The cache replacement policy removes the least recently used (LRU)
query and entries belonging to only that query. Queries are allowed
a maximum time to live (TTL) in the cache thus providing weak
-consistency. A background thread periodically checks the cache for
+consistency. A background task periodically checks the cache for
expired queries and removes them.
The Proxy Cache paper
({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
-design/implementation details.
+design and implementation details.
H2: Proxy Cache Configuration
The cache configuration specific directives described below must
-appear after the {{EX:"database meta"}} directive and before any other
-{{EX:"database"}} declaration in {{slapd.conf}}(5).
+appear after a {{EX:overlay proxycache}} directive within a
+{{EX:"database meta"}} or {{EX:database ldap}} section of
+the server's {{slapd.conf}}(5) file.
H3: Setting cache parameters
-> cacheparams <lo_thresh> <hi_thresh> <numattrsets> <max_entries> <cc_period>
+> proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
-The directive enables proxy caching and sets general cache parameters.
-Cache replacement is invoked when the cache size crosses the
-<hi_thresh> bytes and continues till the cache size is greater than
-<lo_thresh> bytes. Total number of attributes sets (as specified
-by the attrset directive) is given by <numattrsets>. The entry
-restriction for cacheable queries is specified by <max_entries>.
-Consistency check is performed every <cc_period> duration (specified
-in secs). In each cycle queries with expired TTLs are removed.
+This directive enables proxy caching and sets general cache parameters.
+The <DB> parameter specifies which underlying database is to be
+used to hold cached entries. It should be set to {{EX:bdb}},
+{{EX:hdb}}, or {{EX:ldbm}}. The <maxentries> parameter specifies
+the total number of entries which may be held in the cache. The
+<nattrsets> parameter specifies the total number of attribute sets
+(as specified by the {{EX:proxyAttrSet}} directive) that may be defined.
+The <entrylimit> parameter specifies the maximum number of entries
+in a cachable query. The <period> specifies the consistency
+check period (in seconds). In each period, queries with expired
+TTLs are removed.
H3: Defining attribute sets
->
attrset <index> <attrs...>
+>
proxyAttrset <index> <attrs...>
Used to associate a set of attributes to an index. Each attribute
set is associated with an index number from 0 to <numattrsets>-1.
-These indices are used by the addtemplate directive to define
+These indices are used by the proxyTemplate directive to define
cacheable templates.
H3: Specifying cacheable templates
->
addtemplate <prototype_string> <attrset_index> <TTL>
+>
proxyTemplate <prototype_string> <attrset_index> <TTL>
Specifies a cacheable template and the "time to live" (in sec) <TTL>
for queries belonging to the template. A template is described by
its prototype filter string and set of required attributes identified
by <attrset_index>.
+
H3: Example
-An example {{slapd.conf}}(5) for a caching server which proxies for
-the backend server {{EX:ldap://server.mydomain.com}} and caches
-queries with base object in the {{EX:"dc=example,dc=com"}} subtree
-is described below,
+An example {{slapd.conf}}(5) database section for a caching server
+which proxies for the {{EX:"dc=example,dc=com"}} subtree held
+at server {{EX:ldap.example.com}}.
-> database meta
+> database ldap
> suffix "dc=example,dc=com"
-> uri ldap://server.mydomain.com/dc=example,dc=com
-> cacheparams 100000 150000 1 50 100
-> attrset 0 mail postaladdress telephonenumber
-> addtemplate (sn=) 0 3600
-> addtemplate (&(sn=)(givenName=)) 0 3600
-> addtemplate (&(departmentNumber=)(secretary=*)) 0 3600
-
-A different name space is associated with the local cache database.
-E.g if the local database suffix is {{EX:"dc=example,dc=com,cn=cache"}},
-then following rewriting rules need to be defined to translate
-between master and cache database naming contexts.
-
-> rewriteEngine on
-> rewriteContext cacheResult
-> rewriteRule "(.*)dc=example,dc=com" "%1dc=example,dc=com,cn=cache" ":"
-> rewriteContext cacheBase
-> rewriteRule "(.*)dc=example,dc=com" "%1dc=example,dc=com,cn=cache" ":"
-> rewriteContext cacheReturn
-> rewriteRule "(.*)dc=example,dc=com,cn=cache" "%1dc=example,dc=com" ":"
-
-Finally, the local database for storing cached entries can be declared
-as follows:
-
-> database ldbm
-> suffix "dc=example,dc=com,cn=cache"
-> #other database specific directives
+> rootdn "dc=example,dc=com"
+> uri ldap://ldap.example.com/dc=example%2cdc=com
+> overlay proxycache
+> proxycache bdb 100000 1 1000 100
+> proxyAttrset 0 mail postaladdress telephonenumber
+> proxyTemplate (sn=) 0 3600
+> proxyTemplate (&(sn=)(givenName=)) 0 3600
+> proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
+>
+> cachesize 20
+> directory ./testrun/db.2.a
+> index objectClass eq
+> index cn,sn,uid,mail pres,eq,sub
+
+
+H4: Cacheable Queries
+
+A LDAP search query is cacheable when its filter matches one of the
+templates as defined in the "proxyTemplate" statements and when it references
+only the attributes specified in the corresponding attribute set.
+In the example above the attribute set number 0 defines that only the
+attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
+proxyTemplates.
+
+H4: Examples:
+
+> Filter: (&(sn=Richard*)(givenName=jack))
+> Attrs: mail telephoneNumber
+
+ is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
+ attributes are contained in proxyAttrset 0.
+
+> Filter: (&(sn=Richard*)(telephoneNumber))
+> Attrs: givenName
+
+ is not cacheable, because the filter does not match the template,
+ nor is the attribute givenName stored in the cache
-The proxy cache database instance could be either {{TERM:BDB}} or
-{{TERM:LDBM}}. A script for demonstrating the proxy cache
-({{FILE:test019-proxycaching}}) functionality is provided in the
-tests/scripts directory of the distribution.
+> Filter: (|(sn=Richard*)(givenName=jack))
+> Attrs: mail telephoneNumber
+ is not cacheable, because the filter does not match the template ( logical
+ OR "|" condition instead of logical AND "&" )
projects / openldap / blobdiff