7 Configuring the JVM, Java, and Database Cache Options for Oracle Unified Directory

This chapter describes the configuration and manual tuning options for the Java Virtual Machine (JVM), Java, and database cache for the Oracle Unified Directory server and command-line utilities.

This chapter includes the following sections:


Beginning with 11g Release 2 (, Oracle Unified Directory requires JDK 7 or JRE 7.

7.1 Configuring the JVM Using the dstune Utility

The dstune command-line utility allows you to tune the Oracle Unified Directory server and tools (import-ldif, export-ldif, rebuild-index, and verify-index) using criteria such as the data that the directory contains or the amount of system memory to use. The dstune utility provides these options:

  • The data-based subcommand tunes the server based on the data that the database either already contains or will contain.

  • The mem-based subcommand tunes the server and tools based on the heap size they will use.

  • The set-runtime-options subcommand allows you either to use the JVM default values on the system or to directly provide JVM arguments to tune the server and tools.


The dstune memory-based and data-based options are available only if you are running a JVM that uses Java HotSpot, such as Java Platform, Standard Edition (Java SE).

For more information, including the dstune syntax and tuning examples, see Oracle Fusion Middleware Administering Oracle Unified Directory.

7.2 Configuring the Default JVM and Java Arguments

This section describes how to configure the JVM and the Java options for Oracle Unified Directory server and each command-line utility, including:

7.2.1 Using the Java Properties File

The java.properties file contains the Java configuration properties that are used by Oracle Unified Directory scripts and server commands. This file is located in instance-dir/OUD/config/ on UNIX and Linux systems or instance-dir\OUD\config\ on Windows systems.

The properties in the java.properties file have these formats:

  • command-name.java-home=JVM-path

  • command-name.java-args=JVM-arguments

To use the configuration properties in the java.properties file:

  1. Edit the properties in the file you want to set.

    For example, you can set the Java properties to specify whether a command runs using the JVM in -server mode or -client mode.

    Or, for certain commands, including import-ldif, export-ldif, backup, and restore, you can specify the Java arguments and a different JVM, if you prefer, depending on whether the command is run in online or offline mode.

  2. Run the dsjavaproperties (or dsjavaproperties.bat) command, which uses the properties in the java.properties to update the Oracle Unified Directory scripts and commands, so that they use the specific JVM and JVM arguments specified in java.properties.

For examples, see Section 7.2.3, "Specifying the Java Virtual Machine for a Specific Utility" and Section 7.2.4, "Specifying the Java Arguments for a Specific Utility."

For more information, about dsjavaproperties, see Oracle Fusion Middleware Administering Oracle Unified Directory.

Table 7-1 shows the properties in the java.properties file that are relevant to Oracle Unified Directory.

Table 7-1 Properties in the java.properties File Relevant to Oracle Unified Directory

Property Description


If true, the system checks the default.java-args property in this properties file before checking the OPENDS_JAVA_ARGS environment variable.

If false, the system checks the OPENDS_JAVA_ARGS environment variable first.


Sets the JVM that will be used for the directory server and all of its command-line utilities, unless a different JVM is specified for a particular utility.

7.2.2 Configuring JVM Options

Table 7-2 summarizes the Java options that can impact the server's performance. Some of these options apply only to the Oracle JVM.

Table 7-2 Java Options That Can Affect Oracle Unified Directory Server Performance

Condition Option Description


Selects the server application run-time optimizations. The directory server will take longer to start, but it will be better optimized to produce higher throughput.



For 64-bit machines only. By default, the directory server selects a 32-bit JVM regardless of the architecture. Specify this option when a JVM greater than 4 Gbytes heap is required and the architecture is 64-bit.


-Xms2G -Xmx2G

Selects the initial and maximum memory sizes available to the JVM, respectively. These values are used for the JVM heap, which reserves memory for the directory server and its database (DB) cache (or caches if more than one).

Increasing the amount of memory available can improve performance, but increasing it to too high a value can have a detrimental effect in the form of longer pauses for full garbage collection runs. Therefore, the initial and maximum sizes should be set to the same value.

As a general guideline, examine the size of the Oracle Berkeley Java Edition (JE) database folders (instance-dir/OUD/db/userRoot). Based on the folders' combined size, determine how much memory you want to reserve for the database cache. After determining this value, tune the local DB back-end properties, db-cache-percent or db-cache-size and other JVM options appropriately.

Be careful to allow additional memory for the server run time. For example, if you have a single database of 1 Gbyte, which you want to store entirely in memory, then a 2 Gbyte heap with 60% reserved for the database cache should be sufficient for efficient directory server performance.

You can test this setup by preloading the database with the local database back end by using the preload-time-limit property.

JVM heaps greater than 4 Gbytes require a 64-bit JVM.



Prevents external applications from forcing expensive garbage collections. If you are using jstatd or other RMI-based applications to monitor Oracle Unified Directory, consider using this option to avoid unexpected pauses.



In heavy throughput environments, you should consider using this option to increase the size of the JVM young generation.

By default, the young generation is quite small, and high throughput scenarios can result in a large amount of generated garbage. This garbage collection, in turn, causes the JVM to inadvertently promote short-lived objects into the old generation.

Server Only


Selects the CMS garbage collector. This garbage collector is set for low pause time. It will result in a Java application that has a lower average throughput, but much shorter CPU-intensive garbage collections. This option is required in environments that have response time constraints.



Selects the level at which the collection is started. The default value is 68%.

Offline Import Only


Selects the parallel old generational garbage collector. This garbage collector is set for high throughput. It will maximize the average throughput of the import-ldif utility at the cost of an occasional stop-the-world garbage collection, which is not as critical to imports.



Prints the garbage collection details.



Prints the garbage collection time stamps to help with debugging.

Other Applications (for example, dsconfig)


Selects client application run-time optimizations. The application will be faster to start and more responsive due to lower compilation overheads.



Selects a low initial JVM heap size for an application.

7.2.3 Specifying the Java Virtual Machine for a Specific Utility

To set the JVM for a specific utility:

  1. Edit the following property in the java.properties file.


    For example, to configure a specific JDK 1.7 for the offline import-ldif command, set the property that starts with import-ldif.offline. For example:

  2. Run the dsjavaproperties utility to apply the property value.

7.2.4 Specifying the Java Arguments for a Specific Utility

To set the Java arguments for a specific utility:

  1. Edit the following property in the java.properties file.


    For example, to specify that a maximum heap size of 256 Mbytes be used for the online export, set the property that starts with export-ldif.online. For example:

    export-ldif.online.java-args=-Xms256m -Xmx256m
  2. Run the dsjavaproperties utility to apply the property value.

7.3 Configuring the Java Run-Time Settings During the Server Setup

You can provide run-time options when you run the directory server setup script (oud-setup or oud-setup.bat), as follows:

7.4 Setting the Database Cache Size

The size of the database cache can affect the overall performance of Oracle Unified Directory server. You must determine your specific memory settings for the database cache depending on your hardware, the number and size of entries in your directory, and the performance requirements for your deployment.

For example, when importing data using the import-ldif utility, you can configure the directory server to avoid (or minimize) potential database cache eviction problems. Ideally, you should set the database cache to a value that allows the entire database to fit into the cache.

The size of the required heap depends on the number of entries and their size. For example, if you are importing 200,000 entries of 10 Kbytes each, you might specify two Gbytes for the JVM heap size, and then allocate at least one Gbyte for the directory server run-time environment and the rest for the database cache.

You can set the database cache by configuring the db-cache-percent or the db-cache-size properties using either the dsconfig command-line utility or Oracle Directory Sever Manager (ODSM).

The db-cache-percent and the db-cache-size properties represent the maximum size that the server can use for the database cache. If the database is smaller than the size set by either of these properties, only the size of the database is allocated to the JVM heap.


The db-cache-size property has precedence over the db-cache-percent property, if both properties have values. Therefore, to set the db-cache-percent property, the db-cache-size property must be set to 0 Mbytes (the default).

To set the database cache using dsconfig:

  1. Change to the directory where dsconfig is located.

    On UNIX and Linux systems:

    $ cd instance-dir/OUD/bin

    On Windows systems:

    C:\> cd instance-dir\OUD\bat
  2. Run the dsconfig command to set the db-cache-percent property. For example:

    $ dsconfig set-workflow-element-prop \
    --element-name userRoot --set db-cache-percent:50 \
    --hostname hostname --port port-number \
    -X -D "cn=Directory Manager" -j /tmp/password -n

    This example sets the db-cache-percent to 50 percent. Thus, for a 2 Gbyte memory allocation, 1 Gbyte of memory will be allocated to the database cache and the rest to the JVM.

7.5 Setting the Database Cache Mode

The database cache mode (db-cache-mode property) controls the caching of records in the database cache. The database cache is used to store Java Edition (JE) nodes (upper, inner and leaf nodes). When a record is stored or retrieved, the database cache mode determines how long the record is subsequently retained in the cache, relative to other records in the cache.

The default database cache mode retains all types of nodes in the cache. The default mode is recommended for most deployments. However, you might consider changing the mode if your performance expectations are not being met or if the memory available to run Oracle Unified Directory cannot hold all entries in the database cache.

Other database cache modes to consider are:

  • evict-ln mode evicts leaf nodes from the database cache once they are used. Use this mode only if the default mode does not meet your performance expectations and the memory allocated to Oracle Unified Directory is lower than your database size. Using this mode reduces the memory pressure for Java garbage collection and the elapsed processing time (etime) for outliers.

  • evict-bin mode evicts bottom inner nodes from the database cache once they are used. Before using this mode, Oracle recommends trying the evict-ln mode. Use this mode in staging deployments only if the memory allocated to Oracle Unified Directory is significantly smaller than the database size and you cannot otherwise meet your performance expectations.

For other values that you can specify for the database cache mode, see the "DB Local Backend Workflow Element" in the Oracle Fusion Middleware Configuration Reference for Oracle Unified Directory.

To set the database cache mode, use the dsconfig command-line utility. For example to set the mode to evict-ln:

$ dsconfig set-workflow-element-prop \
  --element-name userRoot \
  --set db-cache-mode:evict-ln \
  --hostname localhost --port 4444 \
  -X -D "cn=Directory Manager" -j password-file -n

See also Oracle Fusion Middleware Administering Oracle Unified Directory.