Chapter 16 Managing LDAP Persistent Searches

OpenSSO Enterprise can use LDAP persistent searches (psearches) to obtain asynchronous notifications of changes that occur in Sun Java System Directory Server. By default, however, persistent searches are not enabled for OpenSSO Enterprise.

Contents

• Enabling Persistent Searches

• Disabling Persistent Searches

• Disabling Persistent Searches on a Data Store

• Configuration Properties That Affect Persistent Searches

Enabling Persistent Searches

The OpenSSO Enterprise Event Service (amEventService) creates and manages the persistent search connections. Since persistent searches are disabled by default, use the following methods to enable them

• aci - To receive changes to the aci attribute, with the persistent search using the LDAP filter (aci=*).

• sm - To receive changes in the OpenSSO Enterprise configuration data store (service management node), which includes objects with the sunService or sunServiceComponent marker object class. For example, creation of a new policy to define access privileges for a protected resource or changes to the rules, subjects, conditions, or response providers for an existing policy.

• um - To receive changes in the user data store (user management node). For example, changes to a user's name or address.

The Directory Server nsslapd-maxpsearch attribute defines the maximum number of persistent searches that can be performed on Directory Server. For example:

Property Value  Entry DN: cn=config
Valid Range: 1 to maximum threadnumber
Default Value: 30
Syntax: Integer
Example: nsslapd-maxpsearch: 30

The Directory Server nsIdletimeout attribute does not apply to these connections. A connection is closed when the Directory Server or OpenSSO Enterprise server goes down or after a load balancer or firewall TCP timeout.

To Enable Persistent Searches Using the Console

1. Log in to the Admin Console as amadmin.

2. Click Configuration, Servers and Sites, server-name, SDK, and then Event Service.

3. In the Disable Event Service Connection field, specify only the searches you want to disable, including aci, sm, or um (or a combination, with each item separated by a comma).

   That is, to enable a persistent search, make sure that aci, sm, or um is not present in this files.

4. Click Save and log out of the Console.

5. Restart the OpenSSO Enterprise web container.

Enabling Persistent Searches by Setting the com.sun.am.event.connection.disable.list Property

You can also enable persistent searches by setting the com.sun.am.event.connection.disable.list property, using the ssoadm command.

To enable a specific persistent searches, make sure the respective persistent search value (aci, sm, or um) is not is not included in the property.

Values are case insensitive. To specify multiple values, separate each value with a comma.

For example, to enable persistent searches for ACI changes only:

com.sun.am.event.connection.disable.list=sm,um

After you set the property, restart the OpenSSO Enterprise web container for the new values to take effect.

Disabling Persistent Searches

Each active persistent search requires an open TCP connection between OpenSSO Enterprise server and Directory Server, which can cause a performance overhead on Directory Server. Therefore, use persistent searches only for essential tasks and close any idle LDAP connections when they are no longer required.

If you determine that improving performance is critical for your deployment, the com.sun.am.event.connection.disable.list property allows you to disable persistent searches.

---

Caution –

Before disabling a persistent search, however, you should understand the consequences. The com.sun.am.event.connection.disable.list property was introduced primarily to avoid overhead on Directory Server when multiple version 2.1 J2EE policy agents were used, because each agent established persistent searches. OpenSSO Enterprise does not support version 2.1 policy agents, and version 2.2 and version 3.0 J2EE policy agents do not establish persistent searches.

A component with a disabled persistent search does not receive notifications from Directory Server. Consequently, changes made in Directory Server are not be notified to the component cache, and the component cache can go stale. For example, if you disable persistent searches for changes in the user data store (um), OpenSSO Enterprise server does not receive notifications from Directory Server for any changes to the user data store. Therefore, an agent does not get notifications from OpenSSO Enterprise to update its local user cache with any new values for user attributes. Then, if an application queries the agent for user attributes, the application might receive old values for the attributes.

Disabling persistent searches for a component is recommended only if absolutely required for a deployment. For example, if you know that changes to the configuration data store (service management (sm) node) will not happen in an environment, you can disable the persistent search for this component. However, if any changes do occur for any of the services, a server restart is required to get the changes. This situation also applies to persistent searches for changes to the aci attribute and user data store (sm).

---

To Disable Persistent Searches Using the Console

1. Log in to the Admin Console as amadmin.

2. Click Configuration, Servers and Sites, server-name, SDK, and then Event Service.

3. In the Disable Event Service Connection field, specify aci, sm, or um (or a combination, with each item separated by a comma).

4. Click Save and log out of the Console.

5. Restart the OpenSSO Enterprise web container.

Disabling Persistent Searches by Setting the com.sun.am.event.connection.disable.list Property

You can also disable persistent searches by setting the com.sun.am.event.connection.disable.list property, using the ssoadm command, to one or more of the following values: aci, sm, or um.

Values are case insensitive. To specify multiple values, separate each value with a comma. For example:

To disable all persistent search connections: com.sun.am.event.connection.disable.list=aci,sm,um

To disable persistent searches for ACI changes only: com.sun.am.event.connection.disable.list=aci

To disable persistent searches for configuration data store changes only: com.sun.am.event.connection.disable.list=sm

To disable persistent searches for user data store changes only: com.sun.am.event.connection.disable.list=um

To disable persistent searches for configuration data store and user data store changes: com.sun.am.event.connection.disable.list=sm,um

Re-Enabling Persistent Searches

If you need to re-enable a persistent search that you have disabled, follow the instructions in the previous section using the Admin Console, however, leave a blank for the search (or searches) you want to re-enable.

You can also re-enable one or more persistent searches by setting set the com.sun.am.event.connection.disable.list property to a blank value for each specific search you want to re-enable. For example, to re-enable the search for configuration data store and aci changes, but leave the search disabled for user data store changes, set the property as follows:

com.sun.am.event.connection.disable.list=um

When you are finished, restart the OpenSSO Enterprise web container

To Disable Persistent Searches for a Data Store

1. Log in to the Admin Console as amadmin.

2. Click Access Control, realm-name, Data Stores, data-store-name.

3. Set the Persistent Search Base DN field to blank.

4. Click Save and log out of the Console.

5. Restart the OpenSSO Enterprise web container.

Disabling Persistent Searches on a Data Store

To Disable Persistent Searches on a Data Store

1. Log in to the Console as amadmin.

2. Click Access Control, realm-name, Data Stores, data-store-name and then LDAPv3 Configuration

3. The “Persistent Search BaseDN” field must be empty (spaces).

4. If you made configuration changes, click Save.

Configuration Properties That Affect Persistent Searches

Set these properties either in the OpenSSO Enterprise Admin Console or using the ssoadm command.

Connection Idle Timeout

• com.sun.am.event.connection.idle.timeout specifies the number of minutes after which persistent searches will be restarted. The default is 0, which indicates that persistent searches will not be restarted.

  If persistent search connections are made through a load balancer or firewall, these connections are subject to the TCP time out value of the load balancer or firewall. If the load balancer or firewall closes the persistent search connection due to an idle TCP time out, change notifications are not sent to OpenSSO Enterprise unless the persistent search connection is re-established.

  Therefore, set com.sun.am.event.connection.idle.timeout to a value lower than the load balancer or firewall TCP timeout, to make sure that persistent searches are restarted before the connections are dropped. The difference between the load balancer or firewall timeout value should not be more than 5 minutes. For example, if your load balancer idle connection time out is 50 minutes, set com.sun.am.event.connection.idle.timeout to 45 minutes.

Persistent Search Connection Restart

• com.iplanet.am.event.connection.num.retries specifies the number of attempts to successfully re-establish the persistent search connections. The default is 3.

• com.iplanet.am.event.connection.delay.between.retries specifies the delay in milliseconds between retries to re-establish the persistent search connections. The default is 3000.

• com.iplanet.am.event.connection.ldap.error.codes.retries specifies the LDAP exception error codes for which retries to re-establish persistent search connections will trigger. The default error codes are 80,81,91; however, you can specify any valid LDAP error code.

These four properties apply only to the persistent search (Event Service) connections and are not shared by other modules. For example, these properties do not affect the SDK LDAP connection pool or the authentication LDAP or policy LDAP connections.

LDAPv3 Plug-in Idle Timeout

Each instance of an LDAPv3 plug-in data store creates a persistent search connection using the filter (objectclass=*). Therefore, exercise caution in creating LDAPv3 data stores to prevent the OpenSSO Enterprise server from being flooded with too many notifications. Also, Directory Server does not return an error if the base DN of the persistent search does not exist, so make sure you supply the correct base DN.

• sun-idrepo-ldapv3-config-idletimeout specifies the maximum idle time before an LDAPv3 data store restarts a persistent search connection. If you are using a load balancer or firewall, set this value lower than the load balancer or firewall TCP connection idle timeout value.

For information about using persistent searches in custom applications, see the Sun OpenSSO Enterprise 8.0 Developers Guide.