How do I configure idle timeouts properly in OpenAM 11.x and 12.x for persistent search connections made through a load balancer or firewall?

Last updated Jan 5, 2021

The purpose of this article is to provide information on configuring idle timeouts properly in OpenAM 11.x and 12.x for persistent search connections made through a load balancer or firewall for connections to the configuration store. By default, persistent search idle timeouts are set to 0, which means persistent searches are not restarted. This setting can cause the load balancer or firewall to inadvertently close persistent search connections.

1 reader recommends this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Overview

Active persistent searches require an open TCP connection between OpenAM and the directory server (configuration store). When connecting through a Load Balancer (LB) or firewall, the LB or firewall may terminate this connection if there is no traffic passing through (idle timeout).

The solution to this problem is different depending on the type of connection the persistent search is used on:

For user store (identity repository) connections, the OpenDJ LDAP SDK has a heartbeat mechanism, which runs in the background causing traffic on the connection. Even if there are no persistent search results returned for a long time, the heartbeat will keep the connection alive. Heartbeats are enabled by default.
Persistent search connections used for connections to the configuration store use the legacy Netscape® LDAP SDK in pre-OpenAM 13 versions; this SDK has been replaced with the newer OpenDJ LDAP SDK in OpenAM 13. The Netscape LDAP SDK does not have heartbeats on the connection, instead the solution is to configure an idle timeout for the connection in OpenAM (as described in the following section).

Configuring idle timeouts

To prevent the LB or firewall from terminating the persistent search connection, you should set the persistent search idle timeout to a value lower than the LB or firewall TCP connection idle timeout to ensure the persistent searches are restarted before the TCP connections are terminated. It is recommended that the difference is 5 minutes. For example, if your LB idle timeout is 45 minutes, your persistent search idle timeout should be 40 minutes.

Additionally, if you have both a LB and firewall, you may need to stagger all the idle timeouts by 5 minutes, with the firewall idle timeout being the highest and the persistent search idle timeout the lowest. For example, if your firewall idle timeout is 30 minutes, your LB idle timeout should be 25 minutes and your persistent search idle timeout should be 20 minutes.

You can set the persistent search idle timeout using either the OpenAM console or ssoadm:

OpenAM console: navigate to: Configuration > Servers and Sites > Default Server Settings > SDK > Event Service > Idle Time Out and enter the required number of minutes.
ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.am.event.connection.idle.timeout=[minutes] replacing [adminID], [passwordfile] and [minutes] with appropriate values.

Note

You must restart all OpenAM servers that share the same configuration store to apply these configuration changes.

Related Training

N/A

Related Issue Tracker IDs

N/A