The daily edition.

Scope: Rocket Enterprise Developer 12.0 for Eclipse (UNIX) documentation, Enterprise Server security, the MLDAP ESM Module. The same pages also appear in the 12.0 Windows bundles, but every citation below is from the UNIX bundle enterprisedevelopereclux_ug_120.

What the cache does

An Enterprise Server region that authenticates users and authorizes resource access through LDAP pays a network round trip for each LDAP search. The MLDAP ESM Module can avoid many of them. As described in MLDAP ESM Module Caching, the results of most successful LDAP searches (including a search that returns an empty result, but not one that ends in an error) are stored for a period of time and returned from the cache when a later request needs them. The same page says caching can significantly improve performance, "at the cost of some additional overhead and some delay in recalling changes to the external security information in the LDAP repository." The trade-off is staleness against latency, and the configuration choices below are how you set it.

Two parameters, and they may already be on

Caching is controlled by two parameters on each Security Manager definition, described in Enabling and Configuring MLDAP ESM Module Caching:

• Cache TTL: how long, in seconds, an entry is kept. An entry stored longer than this is ignored and removed when space is needed for a new entry.
• Cache limit: the approximate size, in kB, of the cache for each process.

Search-result caching is enabled by setting positive values for both parameters. Understanding LDAP Caching adds an easily missed note: the sample security manager definitions, and those created through the administration user interfaces, typically already have positive settings. Caching is therefore on in many existing configurations and on by default in new ones. Setting the cache limit and/or the TTL to 0 disables it.

The documented starting point is a 16 KB cache limit and a 300-second TTL. The TTL page guidance is about processes that do not run constantly: set it relatively high if you want caching to be effective for relatively infrequently used processes such as less-active SEPs, balanced against how long you can tolerate the region using out-of-date security information. Cache limit is approximate because LDAP search results vary widely in size, so the number of entries that fit cannot be predicted. Bigger caches are more useful with many MSS resources, users, groups or access rules, but they also take longer to search.

What is and is not cached

The cache is used for two ESF request types: Verify (authenticate a user) and Auth (authorize access to a resource). Other requests, such as ESF Admin, bypass the cache, as do special searches that query the LDAP schema, check whether an optional resource class is defined, or check whether an LDAP session is still valid. Cacheable results include information about user, group and resource access control rule objects. Each entry's key contains all the relevant data of the LDAP search, so a cached result is returned only for an identical search request (Understanding LDAP Caching).

Each cache is private to that Security Manager and process, and caches are shared only between threads inside a single process. Practically, each process in a region warms its own cache; a second process does not benefit from what the first has already looked up.

Four ways an entry leaves the cache

The same page lists four causes of eviction, which are worth knowing when a security change does not seem to "take":

• Expiration: the entry reaches the end of its Cache TTL lifetime.
• Early eviction: when a new result needs room, after expired entries are evicted the module may remove the least-recently-used entry.
• Staleness: when the module itself modifies an LDAP object (for example, a successful password change in a Verify request), the cache entry for that user is marked stale. Stale entries are not returned and are evicted when no longer in use.
• Flushing: the ESF Update feature notifies ESF that security data has been updated; when the MLDAP ESM Module processes an Update request, it flushes the cache and evicts every entry.

So a change made directly in the LDAP directory by some other means is not announced to the cache. Without an ESF Update, the region keeps using the cached answer until the entry expires or is evicted, which is the "delay in recalling changes" mentioned above.

Rule-set caching: new in 12.0 and off by default

Beginning with Enterprise Server 12.0, the module can also cache rule sets, the internal representation of data derived from microfocus-MFDS-Resource objects, which are the access control rules for Enterprise Server resources. The MLDAP ESM Module Caching page says this is disabled by default and must be explicitly enabled. It can avoid repeated LDAP searches that return large result sets, plus the overhead of parsing the responses and building the rule set objects. The page singles out JCL workloads with many job and spool queries as a likely beneficiary, because those security requests get little benefit from the ordinary ESF result cache: the job number is part of the resource name, so each request is often unique.

To enable it, add this to the Configuration Information field of every Security Manager definition that specifies the MLDAP ESM Module:

[Cache]
rule sets=yes

Two nuances from Enabling and Configuring MLDAP ESM Module Caching:

1. Rocket Software recommends a Cache limit of at least 1024 (1 MB) once rule set caching is on. The size of a rule set depends largely on the lengths of the rule names and access control lists, so no simple formula exists; the cache performance information reported at region shutdown can guide sizing. A longer TTL may also be needed to see the full benefit.
2. Rule-set caching rides on top of the normal cache. The option reference states that rule sets can be cached only when caching for the Security Manager is also enabled; with it disabled, only LDAP search results are eligible.

Limiting which rule sets are cached

The MLDAP ESM Module Custom Configuration Information page documents two further [Cache] section options for filtering:

• minimum number of rules=integer sets the smallest rule set eligible for caching, to avoid caching very small rule sets that are cheap to recreate. A rule set can have zero rules, for example when a resource class contains only wildcard rules and a search for the specific name returns nothing. The default is 1.
• maximum number of rules=integer sets the largest rule set eligible, which can keep extremely large and infrequently encountered rule sets out of the cache. The default is 0, unless rule sets is yes, in which case it is the maximum allowed value, 2147483646.

The rule sets option itself defaults to no, unless the minimum and maximum are set to a valid range, in which case it defaults to yes. A minimum greater than the maximum disables rule-set caching. The largest cacheable rule set can also be limited by the cache size rather than the rule count, which is another reason to raise Cache limit alongside it.

Verifying it works

When a process terminates ESF (usually during shutdown), the module logs message 1095 with information about cache performance. There is also an optional cache tracing setting, but the documentation warns it produces extensive information about cache activity and should be used with care (Understanding LDAP Caching). Use the shutdown message to judge whether your limit and TTL are sized sensibly before reaching for tracing.

Takeaway

MLDAP ESM caching is controlled by Cache Limit and Cache TTL (both must be positive), is per process, and may already be active from your sample definitions. Rule-set caching is a separate 12.0 opt-in ([Cache] / rule sets=yes) that needs a larger limit, and any LDAP change made outside the module stays invisible until the entry expires, is evicted, or an ESF Update flushes the cache.