Chapter 15 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
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
-
Log in to the Admin Console as amadmin.
-
Click Configuration, Servers and Sites, server-name, SDK, and then Event
Service.
-
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.
-
Click Save and log out of the Console.
-
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
-
Log in to the Admin Console as amadmin.
-
Click Configuration, Servers and Sites, server-name, SDK, and then Event
Service.
-
In the Disable Event Service Connection field,
specify aci, sm, or um (or
a combination, with each item separated by a comma).
-
Click Save and log out of the Console.
-
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
-
Log in to the Admin Console as amadmin.
-
Click Access Control, realm-name, Data Stores, data-store-name.
-
Set the Persistent Search Base DN field to
blank.
-
Click Save and log out of the Console.
-
Restart the OpenSSO Enterprise web container.
Disabling Persistent Searches on a Data Store
To Disable Persistent Searches on a Data
Store
-
Log in to the Console as amadmin.
-
Click Access Control, realm-name,
Data Stores, data-store-name and
then LDAPv3 Configuration
-
The “Persistent Search BaseDN” field must be empty
(spaces).
-
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.
For information about using persistent searches in custom applications,
see the Sun OpenSSO Enterprise 8.0 Developers Guide.
Загрузить это руководство в формате PDF (1816 КБ)