SLAPO-PCACHE(5)

💖 NAME 💖

slapo-pcache — the proxy cache overlay for slapd, bestie 💅

---

✨ SYNOPSIS ✨

/etc/openldap/slapd.conf

---

🦋 DESCRIPTION 🦋

Okay so, the pcache overlay for slapd(8)? It lets you cache LDAP search requests (aka queries, the lil asks you send out into the world 🌸) inside a local database. Obsessed, honestly.

Here's the vibe: when a query comes in, the proxy cache figures out which template it belongs to. If that template was marked cacheable with the pcacheTemplate directive, and the request is sitting inside a cached request already, boom 💥 — it gets answered straight from the proxy cache. If not? The search just happens like normal, and the cacheable results get saved for next time. Main character energy ✨

A template is defined by a filter string plus an index that identifies a set of attributes. Wanna know the template string for a query? Just take the <span>RFC 4515</span> representation of its search filter and remove the assertion values. A query belongs to a template when its template string and its set of projected attributes match up with a cacheable template. Some examples of template strings, for the girls:

• (mail=)
• (|(sn=)(cn=))
• (&(sn=)(givenName=))

The config directives that are specific to the pcache overlay can be prefixed with pcache-, so you don't start drama with directives belonging to the underlying database or to other stacked overlays. This is<em> especially</em> handy for directives that point at the backend used for local storage. The following cache-specific directives are what you use to set up the proxy cache:

• overlay pcache — drops the proxy cache overlay onto the current backend. You can technically use it with any backend, but it's meant for the ldap and meta backends, lowkey. Heads up bestie: the underlying backend must have a configured rootdn. Periodt.
• pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period> — turns on proxy caching in the current backend and sets the general cache params 🎀. A <database> backend gets used internally to hold onto the cached entries, and you'll need to configure that chosen database too (see below, iykyk). Cache replacement kicks in when the cache grows to <max_entries> entries and keeps going until it drops back below that size. <numattrsets> should equal the number of pcacheAttrset directives that follow it. Queries only get cached if they match a cacheable template (specified by the pcacheTemplate directive) and the number of entries returned is less than <entry_limit>. A consistency check runs every <cc_period> duration (specified in secs). In each cycle, queries with expired "time to live (TTL)" get removed 💀. A sample cache config looks like:

pcache mdb 10000 1 50 100

• pcacheAttrset <index> <attrs...> — links a set of attributes <attrs..> with an <index>. Each attribute set gets an integer from 0 to <numattrsets>-1, and those indices are what the pcacheTemplate directive uses to define cacheable templates. A set of attributes cannot be empty. A set can also hold the special attributes "*" (all user attributes), "+" (all operational attributes), or both — and if you do both, any other attribute is redundant and you should avoid it for clarity, ngl. A set can contain "1.1" as its only attribute, and in that case only the presence of the entries gets cached. Attributes prefixed by "undef:" don't need to be present in the schema. But watch out: the "undef" keyword cannot be used with the slapd-mdb(5) backend, because that one requires all schema elements to be fully defined.
• pcacheMaxQueries <queries> — sets the max number of queries to cache. Default is 10000.
• pcacheValidate { TRUE | FALSE } — checks whether the results of a query being cached can actually be returned from the cache by the proxy DSA 👑. When it's on, the entries being returned while caching a query's results get checked to make sure they're consistent with the schema known to the proxy DSA. If it fails, the query doesn't get cached. By default this check is off.
• pcacheOffline { TRUE | FALSE } — puts the cache in offline mode. While offline, the consistency checker stops and no expirations happen — which lets the cache contents be used indefinitely while the proxy is cut off from network access to the remote DSA 🌈. Default is FALSE, meaning consistency checks and expirations will be performed.
• pcachePersist { TRUE | FALSE } — says whether the cached queries should be saved across restarts of the caching proxy, so you get a hot startup of the cache 🔥. Only non-expired queries get reloaded. Default is FALSE.

CAVEAT: obviously, the proxy cache config must not change across restarts — the pcache overlay does zero consistency checks in that regard, no cap. In detail: this option should be disabled unless the existing pcacheAttrset and 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.

• pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]] — sets a cacheable template and the "time to live" <ttl> of the queries belonging to it. An optional <negttl> can specify that negative results (i.e., queries that returned zero entries 🫥) should also be cached for that amount of time. Negative results are not cached by default (<negttl> set to 0). An optional <limitttl> can specify that results hitting a sizelimit should also be cached for the specified amount of time — those are not cached by default either (<limitttl> set to 0). An optional <ttr> "time to refresh" can specify that cached entries should automatically refresh after a certain time ⭐. Entries only refresh while they haven't expired, so the <ttl> should be larger than the <ttr> for this option to actually be useful. Entries are not refreshed by default (<ttr> set to 0).
• pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base> — sets a template for caching Simple Bind credentials, based on an already-defined pcacheTemplate 🎀. The <filter_template> is like a <template_string>, except it may have some values present. Its whole job is to let the overlay generate filters similar to what other applications do when they run a Search right before a Bind. E.g., if a client like nss_ldap is configured to search for a user with the filter "(&(objectClass=posixAccount)(uid=<username>))", then the corresponding template "(&(objectClass=posixAccount)(uid=))" is what you'd use here. When converted to a regular template, e.g. "(&(objectClass=)(uid=))", this template and the <attrset_index> must match an already-defined pcacheTemplate clause. The "time to refresh" <ttr> determines the time interval after which the cached credentials may be refreshed — the first Bind request that happens after that time will trigger the refresh attempt. Refreshes are not performed when the overlay is Offline. There is no "time to live" parameter for the Bind credentials; the credentials expire according to the pcacheTemplate ttl. The <scope> and <base> should match the search scope and base used by the authentication clients. And good news for the security girlies: the cached credentials are not stored in cleartext — they're hashed using the default password hash 🔐. By default Bind caching is not enabled.
• pcachePosition { head | tail } — picks whether the response callback goes at the tail (the default) or at the head (well, actually wherever the stacking sequence would make it appear) of the callback list. This changes how the overlay vibes with other overlays, since the proxycache overlay should be executed as early as possible (and therefore configured as late as possible) to get a chance to return the cached results. But — plot twist — if it executes early at response, it'd cache entries that might later get "massaged" by other databases, and thus returned after massaging the first time, and before massaging when cached. Messy, ik 😭.

There are some constraints, bestie. Write these down 📝:

• all values must be positive;
• <entry_limit> must be less than or equal to <max_entries>;
• <numattrsets> attribute sets SHOULD be defined by using the directive pcacheAttrset;
• all attribute sets SHOULD be referenced by (at least) one pcacheTemplate directive;

This next bit adds a template with filter string (&(sn=)(givenName=)) and attributes mail, postaladdress, telephonenumber, plus a TTL of 1 hour:

pcacheAttrset 0 mail postaladdress telephonenumber
pcacheTemplate (&(sn=)(givenName=)) 0 3600

Directives for configuring the underlying database must also be given, like so:

directory /var/tmp/cache
maxsize   1073741824

Any valid directives for the database type you chose may be used ✨. Indexing should be used as appropriate for the queries being handled. And on top of that, an equality index on the pcacheQueryid attribute should be configured, to help out with removing expired query data. Slay.

---

🌸 BACKWARD COMPATIBILITY 🌸

The configuration keywords got renamed, and the older form is deprecated 💀. These older keywords are still recognized, but they may disappear in future releases, so don't get too attached:

• proxycache — use pcache
• proxyattrset — use pcacheAttrset
• proxycachequeries — use pcacheMaxQueries
• proxycheckcacheability — use pcacheValidate
• proxysavequeries — use pcachePersist
• proxytemplate — use pcacheTemplate
• response-callback — use pcachePosition

---

🎀 CAVEATS 🎀

okay bestie, deep breath, this is the part where I have to be real with you 💖 caching data is literally prone to inconsistencies, because updates that happen on the remote server will not show up in the cache's response for at least (and at most, no cap) the whole duration of the pcacheTemplate TTL. like, that's just how it is. you can minimize these inconsistencies by being careful with the TTR tho. ✨

the proxy cache overlay needs a full result set of data to even function properly. so yeah — it will strip out the paged results control if the client asks for it. bye 👋

the remote server should expose the objectClass attribute, because the underlying database that actually does the caching may need it for optimal local processing of the queries. 🔥

the proxy server should contain all the schema information required for caching. and like, significantly: it needs the schema of attributes used in the query templates. if the objectClass attribute shows up in a query template, it needs the definition of the objectClasses of the entries it's supposed to cache. it is the responsibility of the proxy administrator to keep the proxy schema lined up with that of the proxied server. that's on you, admin. 🫡

---

okay now the subtle one, and it's giving main character energy 😭 another potential (and subtle, which is always the scary kind) inconsistency can happen when data is retrieved with different identities and specific per-identity access control is enforced by the remote server. so here's the tea:

if data was retrieved with an identity that only got a partial result because the remote server's access rules kicked in, then other users with different access privileges on the remote server will get different results from the remote server vs. from the cache. like:

• if those users have higher access privileges on the remote server, they'll get from the cache only a subset of the results they'd get directly from the remote server 😬
• if they have lower access privileges, they'll get from the cache a superset of the results they'd get directly from the remote server 💀

either one may or may not be acceptable, depending on the security policy of the cache and of the remote server. that's a you decision, bestie.

it is important to note that in this case the proxy is violating the security of the remote server by disclosing to an identity data that was collected by another identity. 🚨

for this reason, it's suggested that, when using back-ldap, proxy caching be used together with the identity assertion feature of slapd-ldap(5) — peep the idassert-bind and the idassert-authz statements, iykyk — so that remote server interrogation happens with a vanilla identity that has some relatively high search and read access privileges, and the "real" access control gets delegated to the proxy's ACLs. slay 💅

but beware 🫣 since only the cached fraction of the real datum is available to the cache, it may not be possible to enforce the same access rules that are defined on the remote server. when security is a concern, cached proxy access must be carefully tailored. also, referral chasing may cause inconsistencies in the remote and cached data. it is unsafe to cache results from a remote server if arbitrary users can create referrals on the remote server. sites must carefully consider whether to enable or disable automatic referral chasing in the proxy backend. fr fr, don't skip this one. 🌸

---

📁 FILES 📁

• /etc/openldap/slapd.conf — default slapd configuration file

---

👀 SEE ALSO 👀

slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5), slapd(8).

---

💖 AUTHOR 💖

originally implemented by Apurva Kumar as an extension to back-meta; turned into an overlay by Howard Chu. iconic behavior, truly. 👑

---

and that's the whole page, bestie!! 🦋 mwah 💋 this was OpenLDAP 2.7.2, dated 2026/10/21, and yes it's literally called SLAPO-PCACHE(5). go forth and cache responsibly, no cap ✨💜