23 Oracle Virtual Directory Performance Tuning

This chapter provides tuning tips for Oracle Virtual Directory. It contains the following sections:

Section 23.1, "About Oracle Virtual Directory"
Section 23.2, "Basic Tuning Considerations"
Section 23.3, "Advanced Tuning Configurations"

23.1 About Oracle Virtual Directory

Oracle Virtual Directory is an LDAP Version 3-enabled service that provides an abstracted view of one or more enterprise data sources. Oracle Virtual Directory consolidates multiple data sources into a single directory view, enabling you to integrate LDAP-aware applications with diverse directory server data stores.

The information in this chapter assumes that you have reviewed the concepts and administration information in the Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.

Note:

Oracle Virtual Directory's out of box configuration may not be optimal for many production and test deployments. You are encouraged to incorporate the recommendations listed in "Basic Tuning Configurations" to achieve optimal performance and availability.

23.2 Basic Tuning Considerations

The tuning considerations in this section apply to most deployments and usage scenarios. It is highly recommended that you review these configurations and implement those that are appropriate for your use case scenarios. The tuning information is summarized in Table 23-1.

Increase the ping interval to 60 seconds (or more as needed) in the opmn.xml file.

When the system is busy, a ping from the Oracle Process Manager and Notification Server (OPMN) to Oracle Virtual Directory may fail. As a result, OPMN will restart Oracle Virtual Directory after 20 seconds (the default ping interval). To avoid this, consider increasing the ping interval to 60 seconds or more.

The ping interval can be modified in the $ORACLE_INSTANCE/config/OPMN/opmn/opmn.xml as shown below:

<process-type id="OVD" module-id="OVD">
               <module-data>
                  <category id="start-options">
                     <data id="java-bin" value="$ORACLE_HOME/jdk/bin/java"/>
                     <data id="java-options" value="-server -Xms2056m -Xmx2056m                               -Dvde.soTimeoutBackend=0  -DdisableECID=1  -Didm.oracle.home=$ORACLE_HOME                               -Dcommon.components.home=$ORACLE_HOME/../oracle_common                               -Doracle.security.jps.config=$ORACLE_INSTANCE/config/JPS/jps-config-jse.xml"/>
                     <data id="java-classpath" value="$ORACLE_HOME/ovd/jlib/vde.jar$:$ORACLE_HOME/jdbc/lib/ojdbc6.jar"/>
                  </category>
               </module-data>
               <stop timeout="120"/>
              <ping interval="60"/>
            </process-type>

Tune the number of worker threads based on the number of central processing units (CPU) available for Oracle Virtual Directory Server on the system.

The 'Threads' configuration parameter in the Oracle Virtual Directory Listener settings should be set to an appropriate value. The default out of box value for Threads in the Admin Gateway listener and DSML Gateway listener should be generally optimal and need not be changed. The number of Threads for the LDAP Listeners are typically the threads that need to be tuned since typically it is the LDAP Listeners that take on concurrent traffic from applications. A common configuration is to have 10 threads per CPU. For example, if there are 4 central processing units on the system, then there would be 40 threads.

For more information, see "Managing Listeners" in Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.
Tune the Work Queue Capacity based on the expected maximum number of concurrent clients to a given LDAP Listener.

The 'WorkQueueCapacity' configuration parameter in the Oracle Virtual Directory Listener settings should be set to an appropriate value. This ensures that the connection requests from LDAP clients are not rejected due to a lack of work queue capacity. Work elements are allocated on demand only, therefore a value higher than the actual estimate can be used.

The Fusion Middleware Control Performance Monitor provides a historical report which contains the maximum number of connections. Use this report to determine how to adjust the connection value based on production data.

If Oracle Virtual Directory needs to support high number of concurrent clients, then set the ulimit 'nofiles' (descriptor) parameter to the number of LDAP Clients expected. For example, in the command window where OPMN is started, set the following ulimit when 8000 concurrent clients are expected:
```
ulimit -n 8192
```
This change requires restart of OPMN and Oracle Virtual Directory to take effect.

For more information, see "Managing Listeners" in Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.
Tune the size of the LDAP connection pool in Oracle Virtual Directory LDAP Adapter to be at least as high as the total number of Threads configured in the Oracle Virtual Directory Listeners that actively use the LDAP Adapter.

This ensures that in the worker threads have enough LDAP connections to process requests. The actual number of active adapters, active listeners and traffic pattern control the usage of connections. However, since connections that are idle in the LDAP Adapter connection pool are periodically closed, a higher value should not impact performance. Ensure that the back-end Directory Server is configured to handle the number of concurrent connections from Oracle Virtual Directory LDAP Adapter connection pool.

For more information, see "Configuring LDAP Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.
Tune the maximum Java heap size of the JVM running Oracle Virtual Directory. This is to ensure that Oracle Virtual Directory has sufficient heap to handle the concurrent load.

For more information, see "Controlling the Maximum Heap Size Allocated to the Oracle Virtual Directory Server" in Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory.

Table 23-1 Basic Tuning Configurations

Configuration Attribute	Category	Default Value	Recommended Value	Notes
Threads	Listener Properties	10	10 * Number Of central processing units (CPUs) available for Oracle Virtual Directory Server	Recommendation applies only to the active LDAP Listeners.
Work Queue Capacity	Listener Properties	2048	Expected Number of Max Concurrent Clients * 2	2048 operations are executed concurrently. Some clients may send asynchronous operations as well.
Max, Initial Pool Connections	LDAP Adapter Properties	10	Total Number of 'Threads parameter values for all active Listeners that use this Adapter	Ensure that the back-end Directory Servers can handle these connections.
Max Heap Size	System Properties	256 MB	Up to 2 GB on 32-bit systems and higher values on 64-bit systems.	Higher values protect against Out Of Memory errors. Ensure that there is sufficient RAM on the system to handle the configured value.

23.3 Advanced Tuning Configurations

Depending on your Oracle Virtual Directory deployment's use case scenarios, the following tuning configurations may improve performance.

23.3.1 Database Adapters

The Database Adapter is a fully featured LDAP-to-JDBC gateway supporting translation of all LDAP operations (add, bind, delete, baseSearch, modify, wildCardSearch) into equivalent SQL prepared statement code. The Database Adapter uses JDBC class libraries to form connections to databases for the purpose of performing LDAP searches. The database libraries are generally provided by the database vendor.

Note:

For improved performance, tune the database before using the Database adapter. Consult your database documentation for more information. If the database being used is an Oracle database, see Oracle Database Performance Tuning Guide.

For optimal performance, consider the following configuration options for the database schema against which the Oracle Virtual Directory database adapter is configured:

In general, the mapped columns in the underlying database schema should have an index defined if the mapped LDAP attribute is used in LDAP search filters.
In scenarios where an LDAP attribute that is used in an LDAP search filter has a matching rule of 'caseIgnoreMatch', the mapped database table column for this attribute needs a function index to be defined for optimal look-up performance.

For example, if LDAP attribute 'CN' is mapped to database schema column EMP.NAME, then a function index on UPPER(EMP.NAME) is required for optimal performance of LDAP search filters involving CN attribute.

For more information on function-based indexes, see "Using Function-based Indexes for Performance" in Oracle Database Performance Tuning Guide.

Table 23-2 describes some additional Database Adapter settings:

Table 23-2 Database Adapter Settings

Parameter	Value	Notes
Adapter	Default: Active	An adapter can be configured as Active or Inactive. An inactive adapter can not start during a server restart or when you try to start it. The purpose of the Inactive setting is to keep old configurations available or on stand-by without having to delete them from the configuration.
Maximum Connections	Default: 10 connections	This defines the maximum connections the Database Adapter may make with the database.
Database Connection Timeout	Default: 10 seconds	The database connection timeout adapter property controls the LDAP request to wait for a connection to become available in the cache after reaching the maximum number of connections limit. If a connection does not become available within the number of seconds defined, the LDAP request fails. If database connection timeout system property is not used, the LDAP request waits 10 seconds for a connection to become available.

Parameter

Value

Notes

Adapter

Default: Active

An adapter can be configured as Active or Inactive. An inactive adapter can not start during a server restart or when you try to start it. The purpose of the Inactive setting is to keep old configurations available or on stand-by without having to delete them from the configuration.

Maximum Connections

Default: 10 connections

This defines the maximum connections the Database Adapter may make with the database.

Database Connection Timeout

Default: 10 seconds

The database connection timeout adapter property controls the LDAP request to wait for a connection to become available in the cache after reaching the maximum number of connections limit.

If a connection does not become available within the number of seconds defined, the LDAP request fails. If database connection timeout system property is not used, the LDAP request waits 10 seconds for a connection to become available.

23.3.2 Join Adapters

If you are using Join Adapters, join only appropriate sources. For example if a deployment requires only to link attributes in the primary source under "cn=users" branch, create a primary adapter that only exposes this branch. And then create the join rule with that adapter. This can reduce the need for Oracle Virtual Directory to try to join entries that may never have corresponding linked entries.

Tip:

Always make sure that the attributes used by join rules are properly indexed.

23.3.3 General Filter Tuning

If a known client search filter does not apply to certain adapters, apply the filter to all applicable "Exclude Filters" to improve performance and reduce network traffic.

23.3.4 Load Balancer Local Store Adapter Tuning

Some load balancers query an LDAP server to determine if it is up or down. If your load balancer uses this feature - consider creating a local store adapter with a separate namespace (for example dc=loadbalancer) that is used only for the load balancer. While the performance impact of the load-balancer is probably not noticeable, by keeping it in a separate namespace. it makes it easier to exclude the load-balancer KeepAlive requests from creating large log files during troubleshooting.

23.3.5 Cache Plug-In Tuning

The CachePlug-in provides an in-memory cache for Oracle Virtual Directory. It has the ability to cache query results from any source for re-use by LDAP clients. This plug-in can improve performance for those applications where queries are highly repetitive.

To review cache operation and configuration, set VE logging level to 'Dump' to see more details. Because the cache is a normal plug-in, the cache can be configured to run anywhere within Oracle Virtual Directory. It can be executed globally, or within the context of a single adapter. It can also be restricted to specific namespaces by using the namespace filtering available in standard plug-in configuration.

23.3.5.1 Cache Hit Logic

The cache works by storing query results and making them available for later use. If a query is repeated by the same user and the same attributes or a subset of attributes are requested, the cache can return its results instead of having Oracle Virtual Directory pull the information from the source. The plug-in can also be configured to allow cache hits to be shared between users.

Sharing cache entries between users should not be used unless the pass credentials are not being passed to back-end sources and Oracle Virtual Directory is solely responsible for security enforcement. Careful consideration should be given when sharing cache hits between users as it would then be possible for one user to see something they should not, since they may have access to a cache result from a more privileged user.

23.3.5.2 Cache Plug-in Memory Management

This plug-in periodically reviews the cache and checks for expired results, or entries that have been invalidated by a previous modify transaction. In the event that the cache quota is exceeded, the plug-in attempts to trim memory by purging the queries that were least recently used (LRU).

Table 23-3 describes some parameters used to tune the Memory Management Plug-in:

Table 23-3 Memory Management Plug-in Settings

Parameter	Value	Notes
Size	Default: 1000 entries	The maximum number of entries that may be cached at any one time.
MaxResultSize	Default: 1000 entries	The maximum number of entries that may be cached for any particular query.
Trimsize	Default: 1000 entries	When the maximum cache size is exceeded, the amount by which the cache manager must reduce the balance. Note: when necessary, trimming is done by purging expired queries first followed by queries in order of least recent use.
MaximumAge	Default: 600 seconds	The maximum age in seconds for any query/entry stored in the cache.
MaintenanceInterval	Default: 60 seconds	The interval in seconds between when the cache manager checks for expired queries.
BySubject	Default: 1 (not shared)	A flag (1 or 0) indicating whether cache results are shared between subjects. A value of 1 indicates that results are not be shared between subjects.

23.3.6 LDAP Listener Tuning

Table 23-4 describes some parameters used to tune the LDAP Listener:

Table 23-4 Listener Parameters

Parameter	Value	Notes
Backlog	Default: 128 requests	Specifies the maximum number of pending connection requests that are allowed to queue up before the server starts rejecting new connection attempts. The default value is sufficient in most cases and the need to change this value is very rare.
Reuse address	Default: False	This option determines whether LDAP listener should reuse socket descriptors. If enabled, the SO_REUSEADDR socket option is used on the Oracle Virtual Directory server listen socket to potentially allow the reuse of socket descriptors for clients in TIME_WAIT state.
Keep Alive	Default: False	This option determines whether the LDAP connection should use TCP keep-alive. If enabled, the SO_KEEPALIVE socket option is used to indicate that TCP keepalive messages should periodically be sent to the client to verify that the associated connection is still valid.
TCP No delay	Default: True	This option determines whether the LDAP connection should use TCP no-delay. If enabled, TCP_NODELAY socket option is used to ensure that response messages to the client are sent immediately rather than potentially waiting to determine whether additional response messages can be sent in the same packet.
Read Timeout	Default: 0	This option enables/disables SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a nonzero timeout, client connection to the Oracle Virtual Directory server can remain idle only for this amount of time. If the connection is idle for a period longer than the specified timeout, the client connection is terminated. A timeout of zero is interpreted as an infinite timeout. Warning: This option is equivalent to vde.soTimeoutFrontend system property in Oracle Virtual Directory version 10g. The vde.soTimeoutFrontend system property is not supported for 11g. Users must modify the value specified in system property The mapping of values from 10g to 11g are:.Enabled to 0 Disabled to nonzero amount of time in milliseconds

23.3.7 Server Tuning

Table 23-5 describes some basic parameters used to tune the server:

Table 23-5 Server Parameters

Parameter	Value	Notes
Anonymous Search Limit	Default: 1000	The maximum number of entries returned for an anonymous client.
Connection Timeout	Default: 120 (minutes)	The Connection Timeout system property is used to prevent service outages caused by clients that do not properly close connections. The value can be set in Oracle Enterprise Manager's Server Properties page. Warning: Setting to 0 disables the enforcement and client connections can not be closed regardless of how long they are inactive. The system property is not enforced on IP addresses and subjects that are exempt from the quota limit or that have disabled quota enforcement.
Logging Levels	Default: Error:1 (Severe)	By default, log messages are written to the access.log file only when logging is set to NOTIFICATION:1. To maintain performance, consider keeping the default log level or use WARNING:1 (WARNING) to limit the amount of information written to the access.log file.

Parameter

Value

Notes

Anonymous Search Limit

Default: 1000

The maximum number of entries returned for an anonymous client.

Connection Timeout

Default: 120 (minutes)

The Connection Timeout system property is used to prevent service outages caused by clients that do not properly close connections. The value can be set in Oracle Enterprise Manager's Server Properties page.

Warning: Setting to 0 disables the enforcement and client connections can not be closed regardless of how long they are inactive. The system property is not enforced on IP addresses and subjects that are exempt from the quota limit or that have disabled quota enforcement.

Logging Levels

Default: Error:1 (Severe)

By default, log messages are written to the access.log file only when logging is set to NOTIFICATION:1. To maintain performance, consider keeping the default log level or use WARNING:1 (WARNING) to limit the amount of information written to the access.log file.