Tuning the HTTP user cache

All mobile devices connecting to an HCL Traveler server connect through the HCL Domino HTTP server component. It is important to tune this component for mobile traffic, as data traffic from mobile devices while syncing is much different than normal web site data traffic.

When a mobile device connects to the HCL Traveler server, the request must first be authenticated. This action is performed by the HCL Domino HTTP server. The HTTP server attempts to validate these credentials, or any session token information, as well as read user information, such as group membership from the Domino Directory or LDAP servers that have been configured for this purpose. Often, this validation uses Domino Directory Assistance configuration information. Before the HTTP server makes the request to the LDAP or Domino directory, it will check to see if the user cache already contains the results from a previous authentication attempt. If so, then the request retrieves the user information from the cache instead of asking the directory.

It is common to use remote LDAP servers or remote Domino Directories with HCL Traveler. Instead of having to replicate all this information locally on every HCL Traveler server, it is more convenient to have this service performed by a central hub. However, mobile devices can make a large number of requests against an HCL Traveler server during push or sync operations. If your HCL Domino HTTP server user cache is not sufficient, this can result in increased load against your LDAP or directory servers. Also, if this request fails for any reason (network request time-out, temporary network loss, directory server is temporarily unavailable), then the failure is returned to the mobile device. Most often this results in the device believing that the user credentials are incorrect. Depending on the device client in use, the end user may see a pop-up asking for a new password or syncing will stop until a new password is provided by the mobile user.

The solution here is to make sure that your HCL Domino HTTP server user cache is sufficient for your mobile population, and that the expiration interval on the cache objects is long enough to be effective.

Configuring the HTTP user cache

To configure the HCL Domino HTTP server user cache, use the Domino Administrator client and open the server document used by your HCL Traveler server. Find the Internet Protocols tab and then the Domino Web Engine tab. Locate a section called Memory Caches, which contains the following fields:

Maximum Cached Designs: This field is not significant to HCL Traveler. It is recommended that you leave this setting as whatever value was previously set.
Maximum Cached Users: The default setting is 64, which is typically too small for an HCL Traveler installation. Set this to the number of users that are expected to use this HCL Traveler server.
Cached User Expiration Interval: The default setting is 120 seconds, which is generally too short for an HCL Traveler installation. It is recommended that you increase this value to 28800 seconds (8 hours). Note that group memberships for a user are also saved in the user cache. The disadvantage of setting this interval too long is that if a user is moved out of a group that can access the HCL Traveler server, then this membership change will not be recognized until the user cache record expires. Depending on your security requirements, you may want to adjust this value lower.; In some circumstances, you may not want to wait. In order to force a refresh of the entire HTTP User Cache, it is necessary to restart the HTTP task.

Monitoring the user cache using Domino statistics

The HTTP user cache can be monitored using HCL Domino server statistics. To display the user cache statistics, run the following command on the Domino server console:

show stat domino.cache.user*

This command will return data similar to the following:

Domino.Cache.User Cache.Count = 687
Domino.Cache.User Cache.DisplaceRate = 0
Domino.Cache.User Cache.HitRate = 99.3575742001799
Domino.Cache.User Cache.MaxSize = 1000

It is possible that the Domino.Cache.User Cache.Count could temporarily grow larger than the Domino.Cache.User Cache.MaxSize. This is a sign that the cache size is too small. In general, you should tune the user cache so that Domino.Cache.User Cache.HitRate is 90% or higher.