--- title: Tune caching description: AM caches data to avoid having to query user and configuration datastores 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. component: pingam version: 8.1 page_id: pingam:maintenance:caching canonical_url: https://docs.pingidentity.com/pingam/8.1/maintenance/caching.html keywords: ["Tuning"] page_aliases: ["maintenance-guide:caching.adoc"] section_ids: caching-server-settings: Overall server cache settings turn-off-global-user-data-caching: Turn off global user data caching change-max-cache-size: Change the maximum size of the global user data cache clear-config-cache: Clear the configuration cache caching-properties: Cache settings --- # Tune caching AM caches data to avoid having to query user and configuration datastores 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 datastores. The user datastore 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: ![Servers cache user data and configuration data separately.](_images/openam-caches.png)Figure 1. Caches The rest of this page covers settings for global user data cache and for SDK clients. You can find information on datastore cache settings in [Tune LDAP connectivity](tuning-ldap-settings.html). ## 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. ### 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 datastore 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: 1. In the AM admin UI, go to Deployment > Servers > *server name* > Advanced. 2. Set the value of the `com.iplanet.am.sdk.caching.enabled` property to `false` to disable caching overall. 3. Set the value of the `com.sun.identity.sm.cache.enabled` property to `true` to enable configuration data caching. All supported configuration datastores 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. | 4. Save your work. 5. AM starts persistent searches on user datastores when possible(1) in order to monitor changes. With user datastore caching disabled, AM still starts the persistent searches, even though it no longer uses the results. Therefore, if you disable user datastore 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). (1) AM starts persistent searches on user datastores on directory servers that support the `psearch` control. ### Change the maximum size of the global user data cache With a large user datastore and active user base, the number of user entries in cache can grow large. 1. In the AM admin UI, go to Configure > Server Defaults > SDK. 2. Change the value of SDK Caching Maximum Size. There is no corresponding setting for configuration data, because the number of configuration entries in a large deployment is not likely to grow nearly as large as the number of user entries. ## Clear the configuration cache When you change configuration property values, the old value remains in effect until the affected service is restarted. To avoid having to restart AM when you change a property value, you can clear the configuration cache and force the new property value to take effect. To clear the configuration cache, send an empty POST request to the `/json/cache` endpoint with the `clear` action, for example: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "iPlanetDirectoryPro: kYQVVJ2YFCuAe-b1xjm7evGBDkw.AAJTSQACMDEAAlNLABxQS0ZIYzBPeFVWUzBQOTNLaHV0elVQemdqVU09AAR0eXBlAANDVFMAAlMxAAA. " \ --header "Accept-API-Version: resource=1.0" \ --data '{}' \ https://am.example.com:8443/am/json/cache?_action=clear {} ``` Only members of a group with the `Realm Admin` or `Cache Admin` privilege can run this operation to clear the cache. All attempts to access the endpoint are audited, including information about the user that attempted to clear the cache. ## 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 and 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 and 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 and 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 and 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 and SDK | | `sun-idrepo-ldapv3-dncache-enabled` | Set this to `true` to enable DN caching of user data. | `false` | Server and SDK | | `sun-idrepo-ldapv3-dncache-size` | Sets the cache size. | `1500` | Server and SDK |