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:
Section 7.2, "Configuring the Default JVM and Java Arguments"
Section 7.3, "Configuring the Java Run-Time Settings During the Server Setup"
Note:
Beginning with 11g Release 2 (11.1.2.3), Oracle Unified Directory requires JDK 7 or JRE 7.dstune UtilityThe 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.
Note:
Thedstune 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.
This section describes how to configure the JVM and the Java options for Oracle Unified Directory server and each command-line utility, including:
Section 7.2.3, "Specifying the Java Virtual Machine for a Specific Utility"
Section 7.2.4, "Specifying the Java Arguments for a Specific Utility"
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:
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 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 If |
|
|
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. |
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. |
|
|
|
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 ( 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 JVM heaps greater than 4 Gbytes require a 64-bit JVM. |
|
|
|
Prevents external applications from forcing expensive garbage collections. If you are using |
|
|
|
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 |
|
|
Prints the garbage collection details. |
|
|
|
Prints the garbage collection time stamps to help with debugging. |
|
|
Other Applications (for example, |
|
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. |
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.7 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.7.0
Run the dsjavaproperties utility to apply the property value.
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 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
Run the dsjavaproperties utility to apply the property value.
You can provide run-time options when you run the directory server setup script (oud-setup or oud-setup.bat), as follows:
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 Section 3.1, "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 Section 3.2, "Setting Up the Directory Server Using the Command-Line Interface (CLI)."
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.
Note:
Thedb-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:
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 Gbyte memory allocation, 1 Gbyte of memory will be allocated to the database cache and the rest to the JVM.
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.