--- title: Prepare the Java environment description: AM software depends on a Java runtime environment. Check the output of the java -version command to make sure your version is supported according to the Java requirements. component: pingam version: 8.1 page_id: pingam:installation:prepare-java canonical_url: https://docs.pingidentity.com/pingam/8.1/installation/prepare-java.html keywords: ["Install"] page_aliases: ["install-guide:prepare-java.adoc"] section_ids: prepare-java-oracle: Settings for Oracle Java environments prepare-java-openjdk: Settings for OpenJDK Java environments tuning-jvm-for-openam: Tune JVM settings --- # Prepare the Java environment AM software depends on a Java runtime environment. Check the output of the `java -version` command to make sure your version is supported according to the [Java requirements](https://docs.pingidentity.com/pingam/release-notes/requirements.html#prerequisites-java). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Keep your Java software up-to-date with the latest supported version. Make sure your `JAVA_HOME` environment variable always points to the latest supported Java version. | The following table summarizes the high-level tasks required to configure your Java environment: | Task | Resources | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Prepare your JDKThe suggestions in these sections apply to AM deployments with the following characteristics:- The deployment has a dedicated DS server for the Core Token Service (CTS). The host running this directory server is a high-end server with a large amount of memory and multiple CPUs. - The AM server is configured to use server-side sessions. | * [Settings for Oracle Java environments](#prepare-java-oracle) * [Settings for OpenJDK Java environments](#prepare-java-openjdk) | | Tune the JVM for AMThis document provides guidance on tuning the JVM for production, but you must also tune it for garbage collection based on your environment. | - [Tune JVM settings](#tuning-jvm-for-openam) | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can find information on configuring JVM properties for proxy support in [Configuring AM for Outbound Communication](../security/reverse-proxy.html#outbound-communication). | ## Settings for Oracle Java environments When using an Oracle Java environment, set at least the following options: * `-Xmx1g` (minimum) AM requires at least a 1 GB heap. Higher volume and higher performance deployments require additional heap space. * `-XX:MetaspaceSize=256m` Set the metaspace memory size to 256 MB. * `-XX:MaxMetaspaceSize=256m` Set the maximum metaspace memory size to 256 MB. You can find additional JVM tuning and security recommendations in [Tune JVM settings](#tuning-jvm-for-openam). ## Settings for OpenJDK Java environments When using an OpenJDK Java environment, set at least the following options. * `-Xmx1024m` (minimum) AM requires at least a 1 GB heap. Higher volume and higher performance deployments require additional heap space. Recommended: `-Xmx2048m`. * `-XX:MetaspaceSize=256m` Set the initial metadata space size to 256 MB. ## Tune JVM settings This section gives some initial guidance on configuring the JVM for running AM when the deployment has a dedicated CTS token store, and AM is configured to use server-side sessions. These settings provide a strong foundation to the JVM before a more detailed garbage collection tuning exercise, or as best practice configuration for production: **Heap size settings** | JVM parameters | Suggested value | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-Xms` & `-Xmx` | At least 1 GB. In production environments, at least 2 to 3 GB. This setting depends on the available physical memory and whether a 32- or 64-bit JVM is used. | | | `-XX:MetaspaceSize` & `-XX:MaxMetaspaceSize` | Set both to 256 MB Metadata space (Metaspace) is a dedicated region within Native Memory. It can grow automatically if you don't set a maximum size. The ideal Metaspace size depends on your deployment and the number of scripts you're running. 256 MB is considered a safe value for production deployments, but you might need to tweak this for your specific deployment. | Controls the size of the metaspace in the JVM. | | `-Dsun.net.client.defaultReadTimeout` | 60000 | Controls the read timeout in the Java HTTP client implementation.This applies only to the Sun/Oracle HotSpot JVM. | | `-Dsun.net.client.defaultConnectTimeout` | High setting: 30000 (30 seconds) | Controls the connect timeout in the Java HTTP client implementation.When you have hundreds of incoming requests per second, reduce this value to avoid a huge connection queue.This applies only to the Sun/Oracle HotSpot JVM. | **Security settings** | JVM parameters | Suggested value | Description | | ----------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `-Dhttps.protocols` | `TLSv1.2` | Controls the protocols used for outbound HTTPS connections from AM.Specify one or more of the following values, separated by commas:- TLSv1.2 - TLSv1.3This setting applies only to Sun/Oracle Java environments. | | `-Dorg.forgerock.openam.ldap.secure.protocol.version` | `TLSv1.2` | Controls the protocol AM uses to connect to affected external resources.Specify one or more of the following values, separated by commas:- TLSv1.2 - TLSv1.3This setting overrides the default server value. Learn more in [advanced properties](../setup/deployment-configuration-reference.html#org.forgerock.openam.ldap.secure.protocol.version). | **Garbage collection settings** | JVM parameters | Suggested value | Description | | --------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `-verbose:gc` | | Verbose garbage collection reporting. | | `-Xlog:gc*` | `-Xlog:gc=info:file=$CATALINA_HOME/logs/gc-info.log` | Logs detailed information about garbage collection. When using the `-Xlog:gc` option, you can also specify the level, and output file. | | `-XX:+HeapDumpOnOutOfMemoryError` | | Out of Memory errors generate a heap dump automatically. | | `-XX:HeapDumpPath` | `$CATALINA_HOME/logs/heapdump.hprof` | Location of the heap dump. | | `-XX:+PrintClassHistogram` | | Prints a heap histogram when the JVM receives a SIGTERM signal. | **Other settings** | JVM parameters | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--add-opens java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED` | When running AM, SAML Artifact flows, WS-Federation flows and any flows that use Xerces SOAP libraries can fail with the following error:`Caused by: java.lang.IllegalAccessError: superclass access check failed: class com.sun.xml.messaging.saaj.soap.SOAPDocumentImpl (in unnamed module @0x774ca796) cannot access class com.sun.org.apache.xerces.internal.dom.DocumentImpl (in module java.xml) because module java.xml does not export com.sun.org.apache.xerces.internal.dom to unnamed module @0x774ca796`Set these JVM parameters to avoid this error. | | `--add-exports java.xml/com.sun.org.apache.xerces.internal.jaxp=ALL-UNNAMED` | | | `--add-exports java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED` | |