Tuning Caching

AM caches data to avoid having to query user and configuration data stores each time it needs the information. By default, AM makes use of LDAP persistent search to receive notification of changes to cached data. For this reason, caching works best when data are stored in a directory server that supports LDAP persistent search.

AM has two kinds of cache on the server side that you can configure, one for configuration data and the other for user data. Generally use the default settings for configuration data cache. This section mainly covers the configuration choices you have for caching user data.

AM implements the global user data cache for its user data stores.

The user data store also supports a DN Cache, used to cache DN lookups that tend to occur in bursts during authentication. The DN Cache can become out of date when a user is moved or renamed in the underlying LDAP store, events that are not always reflected in a persistent search result. You can enable the DN cache when the underlying LDAP store supports persistent search and mod DN operations (that is, move or rename DN).

The following diagram depicts the two kinds of cache, and also the two types of caching available for user data:

Caches

The rest of this section concerns mainly settings for global user data cache and for SDK clients. For a look at data store cache settings, see "LDAP Identity Store Settings".

Overall Server Cache Settings

By default AM has caching enabled both for configuration data and also for user data. This setting is governed by the server property com.iplanet.am.sdk.caching.enabled, which by default is true. When you set this advanced property to false, then you can enable caching independently for configuration data and for user data.

To Turn Off Global User Data Caching

Disabling caching can have a severe negative impact on performance. This is because when caching is disabled, AM must query a data store each time it needs data.

If, however, you have at least one identity store that does not support LDAP persistent search, then you must disable the global cache for user data. Otherwise user data caches cannot stay in sync with changes to user data entries:

In the AM console, navigate to Deployment > Servers > Server Name > Advanced.
Set the value of the com.iplanet.am.sdk.caching.enabled property to false to disable caching overall.
Set the value of the com.sun.identity.sm.cache.enabled property to true to enable configuration data caching.
All supported configuration data stores support LDAP persistent search, so it is safe to enable configuration data caching.
You must explicitly set this property to true, because setting the value of the property com.iplanet.am.sdk.caching.enabled to false in the previous step disables both user and configuration data caching.
Save your work.
AM starts persistent searches on user data stores when possible ^[1] in order to monitor changes. With user data store caching disabled, AM still starts the persistent searches, even though it no longer uses the results.
Therefore, if you disable user data store caching, you should also disable persistent searches on identity stores in your deployment to improve performance. To disable persistent search on an identity store, remove the value of the Persistent Search Base DN configuration property and leave it blank. Locate this property under Realms > Realm Name > Identity Stores > Identity Store Name > Persistent Search Controls.

To Change the Maximum Size of Global User Data Cache

With a large user data store and active user base, the number of user entries in cache can grow large.

In the AM console, navigate to Configure > Server Defaults > SDK.
Change the value of SDK Caching Maximum Size.
There is no corresponding setting for configuration data, as the number of configuration entries in a large deployment is not likely to grow nearly as large as the number of user entries.

^[1] AM starts persistent searches on user data stores on directory servers that support the psearch control.

Cache Settings

The table below provides a quick reference, primarily for user data cache settings.

Notice that many properties for configuration data cache have sm (for Service Management) in their names, whereas those for user data have idm (for Identity Management) in their names:

Cache Properties

Property	Description	Default	Applies To
`com.iplanet.am.sdk.cache.maxSize`	Maximum number of user entries cached.	10000	Server and SDK
`com.iplanet.am.sdk.caching.enabled`	Whether to enable caching for both configuration data and also for user data. If `true`, this setting overrides `com.sun.identity.idm.cache.enabled` and `com.sun.identity.sm.cache.enabled`. If `false`, you can enable caching independently for configuration data and for user data using the aforementioned properties.	`true`	Server & SDK
`com.iplanet.am.sdk.remote.pollingTime`	How often in minutes the SDK client, such as a web or a Java agent should poll AM for modified user data entries. The SDK also uses this value to determine the age of the oldest changes requested. The oldest changes requested are 2 minutes older than this setting. In other words, by default the SDK polls for entries changed in the last 3 minutes. Set this to 0 or a negative integer to disable polling.	1 (minute)	SDK
`com.sun.am.event.notification.expire.time`	How long AM stores a given change to a cached entry, so that clients polling for changes do not miss the change.	30 (minutes)	Server only
`com.sun.identity.idm.cache.enabled`	If `com.iplanet.am.sdk.caching.enabled` is `true`, this property is ignored. Otherwise, set this to `true` to enable caching of user data.	`false`	Server & SDK
`com.sun.identity.idm.cache.entry.default.expire.time`	How many minutes to store a user data entry in the global user data cache.	30 (minutes)	Server & SDK
`com.sun.identity.idm.cache.entry.expire.enabled`	Whether user data entries in the global user data cache should expire over time.	`false`	Server & SDK
`com.sun.identity.idm.remote.notification.enabled`	Whether the SDK client, such as a web or a Java agent should register a notification listener for user data changes with the AM server. The SDK client uses the URL specified by `com.sun.identity.client.notification.url` to register the listener so that AM knows where to send notifications. If notifications cannot be enabled for some reason, then the SDK client falls back to polling for changes.	`true`	SDK
`com.sun.identity.sm.cache.enabled`	If `com.iplanet.am.sdk.caching.enabled` is `true`, this property is ignored. Otherwise, set this to `true` to enable caching of configuration data. It is recommended that you always set this to `true`.	`false`	Server & SDK
`sun-idrepo-ldapv3-dncache-enabled`	Set this to `true` to enable DN caching of user data.	`false`	Server & SDK
`sun-idrepo-ldapv3-dncache-size`	Sets the cache size.	`1500`	Server & SDK

Policy Evaluation Settings

The AM policy engine places policies for evaluation on a queue in batches. Use ssoadm to optimize performance evaluation throughput by configuring the number of threads available for this queue.

This example increases the number of threads from the default value of 10 to 20:

./ssoadm set-entitlement-conf -u amadmin  -f pwd.txt -a evalThreadSize=20

^[1] AM starts persistent searches on user data stores on directory servers that support the psearch control.