7 Configuring the JVM, Java Options, and Database Cache

Oracle Unified Directory and its command-line utilities run with a default Java Virtual Machine and with default Java arguments. To improve performance for your specific directory deployment, it might be useful to configure the JVM, Java options, and database (DB) cache (or caches).

This section covers the following topics:

7.1 Configuring the Default JVM and Java Arguments

The directory server provides a means of configuring the Java Virtual Machine (JVM) and Java options for each command-line utility and for the directory server itself. The Java configuration is provided in a properties file, located at instance-dir/OUD/config/java.properties (Unix) or instance-dir\OUD\config (Windows). The configuration specified in this file is taken into account each time the dsjavaproperties command is run. If you do not run the dsjavaproperties command, the properties file is ignored.

The properties file can be used to specify (among other arguments) whether a command runs using the JVM in -server mode or -client mode. By default, all client applications run in -client mode, while the directory server and certain server utilities run in -server mode. Generally, -server mode provides higher throughput than -client mode, at the expense of slightly longer startup times.

For certain commands (import-ldif, export-ldif, backup, and restore) you can also specify different Java arguments (and a different JVM) depending on whether the command is run in online or offline mode.

7.1.1 The Java Properties File Format

The Java properties file has the following format.

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

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

The following table shows three properties present in the java.properties file that are of particular importance.

Property Description


If True, the system checks the default.java-args property in this properties file before the 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 for all of its command-line utilities, unless a different JVM is specified for a particular utility.

7.1.2 Configuring JVM Options

The following table summarizes the Java options that can have an impact on server performance. Note that some of these options apply only to the Sun JVM.

Condition Option Description


Selects server application runtime optimizations. The directory server will take longer to start and "warm up" but will be more aggressively optimized to produce higher throughput.



For 64-bit machines only. By default, the directory server selects a 32-bit JVM regardless of the architecture. This options should be specified when a large JVM heap is required (greater than 4 Gbytes) 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, take a look at 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 DB 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 runtime. 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 DB 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, you should consider using this option in order 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.1.3 To Specify the JAVA_HOME Environment Variable for a Specific Utility

  1. Edit the Java properties file as follows: command-name.java-home=jvm.

    For example, to specify a particular JDK 1.6 for the offline import, edit the line that starts with import-ldif.offline in the java.properties file, as follows: import-ldif.offline.java-home=/usr/jdk1.6.

  2. Run the dsjavaproperties command to apply the property.

7.1.4 To Specify the Java Arguments for a Specific Utility

  1. Edit the Java properties file as follows: command-name.java-args=arguments.

    For example, to specify that a maximum heap size of 256 Mbytes be used for the online export, edit the line that starts with export-ldif.online in the java.properties file, as follows: export-ldif.online.java-args=-Xms256m -Xmx256m.

  2. Run the dsjavaproperties command to apply the property.

7.2 Configuring the Java Runtime Settings During Installation

If you use the GUI installer, you can configure Java runtime settings as part of the install process. To configure Java runtime settings, click Change on the Runtime Options panel. The following settings can be configured:

  • Initial Memory. Specifies the amount of memory, in Megabytes, that will be used to start the server.

  • Maximum Memory. Specifies the maximum amount of memory, in Megabytes, that will be dedicated to running the server.

  • Other Java Arguments. Any other Java options that might have an impact on server performance. For a detailed list of these options, see Configuring JVM Options.


You can also specify the Java settings for the import task when you install a directory server by using the oud-setup command. This option is not available when you install a proxy server.

7.3 Setting the Database Cache

A critical component of your directory server's overall performance is the size of the database (DB) cache. You need to determine your particular memory settings depending on your hardware, the number of entries in your directory, and your performance requirements. For example, when importing data by using the import-ldif utility, you must configure the directory server in such a way to minimize and avoid potential data cache eviction problems. Ideally, you should set the DB cache to a value that ensures that the whole database can fit into the cache. The size of the required heap depends on the number of entries and their size. For example, if you were importing 200K entries of 10Kbytes each, you might specify 2 Gbytes for the JVM heap size, then allocate at least 1 Gbyte for the directory server runtime environment and the rest for the DB cache.

7.3.1 To Set the Database Cache

You can set the DB cache by configuring the db-cache-percent or the db-cache-size properties with the dsconfig command-line utility. The db-cache-percent and the db-cache-size properties represent the maximum size that the server can use for the DB 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.


If you want to set the db-cache-percent property, then the db-cache-size property must be kept at the default value of 0 Mbytes. The db-cache-size property has precedence over the db-cache-percent property if both are given values.

  1. Change to the appropriate directory.

    (UNIX, Linux)  $ cd instance-dir/OUD/bin
    (Windows)      C:\> cd instance-dir\OUD\bat
  2. Run the dsconfig command to set the db-cache-percent, as follows:.

    dsconfig set-workflow-element-prop --element-name userRoot --set 
    db-cache-percent:50 --hostname <hostname> --port <portnumber> -X -D 
    @ "cn=directory manager"-j /tmp/password -n

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