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 configurable cache on the server side; one for configuration data and one for user data. You can generally use the default settings for configuration data cache. This section covers the configuration choices available 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 modDN 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:
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 for both configuration data and user data. This setting is governed by the server property com.iplanet.am.sdk.caching.enabled, which is true by default. If you set this advanced property to false, you can enable caching independently for configuration data and for user data.
Important
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, go to Deployment > Servers > Server Name > Advanced.
Set the value of the
com.iplanet.am.sdk.caching.enabledproperty tofalseto disable caching overall.Set the value of the
com.sun.identity.sm.cache.enabledproperty totrueto 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 propertycom.iplanet.am.sdk.caching.enabledtofalsein 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, go to Realms > Realm Name > Identity Stores > Identity Store Name > Persistent Search Controls and remove the value of the Persistent Search Base DN configuration property (leave it blank).
With a large user data store and active user base, the number of user entries in cache can grow large.
In the AM console, go 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:
| Property | Description | Default | Applies To |
|---|---|---|---|
| Maximum number of user entries cached. | 10000 | Server and SDK |
| Whether to enable caching for both configuration data and also for user data. If If |
| Server & SDK |
| 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 |
| 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 |
| If Otherwise, set this to |
| Server & SDK |
| How many minutes to store a user data entry in the global user data cache. | 30 (minutes) | Server & SDK |
| Whether user data entries in the global user data cache should expire over time. |
| Server & SDK |
| 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 If notifications cannot be enabled for some reason, then the SDK client falls back to polling for changes. |
| SDK |
| If Otherwise, set this to |
| Server & SDK |
| Set this to |
| Server & SDK |
| Sets the cache size. |
| Server & SDK |
[1] AM starts persistent searches on user data stores on directory servers that support the psearch control.