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

7.1 Configuring the JVM Using the `dstune` Utility

The dstune command-line utility enables 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.

Note:

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

For more information on the dstune syntax and tuning examples, see Tuning Java Virtual Machine Settings Using the dstune Utility in Administering Oracle Unified Directory.

7.2 Configuring the Default JVM and Java Arguments

Use the Java properties file to configure the Java Virtual Machine, Java options and Java arguments for Oracle Unified Directory server.

7.2.1 Using the Java Properties File

The java.properties file contains the Java configuration properties. Oracle Unified Directory scripts and server commands use these Java configuration properties. 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:

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.
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 Specifying the Java Virtual Machine for a Specific Utility and Specifying the Java Arguments for a Specific Utility.

See also dsjavaproperties in 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

Property	Description
`overwrite-env-java-args`	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.
`default.java-home`	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.

overwrite-env-java-args

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.

default.java-home

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

Oracle Unified Directory provides several Java options that can impact the server's performance. Each option is applied for a specific condition and some of these options apply only to the Oracle JVM.

Table 7-2 summarizes the Java options that can impact the server's performance.

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

Condition	Option	Description
For Server and Offline Import to use server grade JVM runtime optimizations	`-server`	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	`-d64`	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 GB heap is required and the architecture is 64-bit.
For JVM Heap	`-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 GB, which you want to store entirely in memory, then a 2 GB 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 GB require a 64-bit JVM.
For `jstatd` or other RMI-based applications	`DisableExplicitGC`	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.
For heavy throughput environments	`-XX:NewSize=512M`	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	`-XX:+UseConcMarkSweepGC`	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.
For GC Analysis and Tuning	`-XX:CMSInitiatingOccupancyFraction=70`	Selects the level at which the collection is started. The default value is 68%.
Offline Import Only	`-XX:+UseParallelOldGC`	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.
For GC Analysis and Tuning	`-XX:+PrintGCDetails`	Prints the garbage collection details.
For GC Analysis and Tuning	`-XX:+PrintGCTimeStamps`	Prints the garbage collection time stamps to help with debugging.
Other Applications (for example, `dsconfig`)	`-client`	Selects client application run-time optimizations. The application will be faster to start and more responsive due to lower compilation overheads.
For very low initial JVM Heap size	`-Xms8m`	Selects a low initial JVM heap size for an application.

7.2.3 Specifying the Java Virtual Machine for a Specific Utility

Edit the Java home property in the java.properties file to set the Java Virtual Machine for a specific utility.

To set the JVM for a specific utility:

Edit the following property in the java.properties file.
```
command-name.java-home=jvm-location
```
For example, to configure a specific JDK 1.8 for the offline import-ldif command, set the property that starts with import-ldif.offline. For example:
```
import-ldif.offline.java-home=/usr/java/jdk1.8.0
```
Run the dsjavaproperties utility to apply the property value.

7.2.4 Specifying the Java Arguments for a Specific Utility

Edit the Java arguments property in the java.properties file to specify the Java Arguments for a specific utility.

To set the Java arguments for a specific utility:

Edit the following property in the java.properties file.
```
command-name.java-args=arguments
```
For example, to specify that a maximum heap size of 256 MB be used for the online export, set the property that starts with export-ldif.online. For example:
```
export-ldif.online.java-args=-Xms256m -Xmx256m
```
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).

In GUI mode, on the Providing Runtime Options screen, click Change to change any of the displayed values for the Server Runtime Settings or the Offline Tools Runtime Settings.

See Setting Up the Directory Server Using the Graphical User Interface (GUI).
In CLI mode, you can specify JVM arguments when you tune Oracle Unified Directory server and the off-line tools.

See Setting Up the Directory Server Using the Command-Line Interface (CLI).

7.4 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 KB each, you might specify two GB for the JVM heap size, and then allocate at least one GB 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 Unified Directory Services Manager.

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.

Note:

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 MB (the default).

See Setting Database Cache Using dsconfig.

7.4.1 Setting Database Cache Using dsconfig

Use the database cache percentage property of the dsconfig command to allocate memory to the database cache.

To set the database cache using dsconfig:

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
```
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 GB memory allocation, 1 GB 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. You can use the database cache 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 DB Local Backend Workflow Element in 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 Managing the Database Cache in Administering Oracle Unified Directory.

7.1 Configuring the JVM Using the dstune Utility