--- 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: 7.3 page_id: pingam:install-guide:prepare-java canonical_url: https://docs.pingidentity.com/pingam/8.1/installation/prepare-java.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Install"] 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 that 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 JDK.The suggestions in these sections pertain to AM deployments with the following characteristics:- The deployment has a dedicated DS server for the Core Token Service. 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 AMForgeRock provides guidance on how to tune the JVM for production, but you must also tune it for garbage collection based on your environment. | - [Tune JVM settings](#tuning-jvm-for-openam) | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | To configure JVM properties for proxy support, see [Configuring AM for Outbound Communication](../security-guide/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. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. 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. For additional JVM tuning and security recommendations, see [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. If you are including the embedded DS, AM requires at least a 2 GB heap, as 50% of that space is allocated to DS. 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 (2 GB with embedded DS), in production environments at least 2 GB to 3 GB. This setting depends on the available physical memory, and on whether a 32- or 64-bit JVM is used. | | | `-XX:MetaspaceSize` & `-XX:MaxMetaspaceSize` | Set both to 256 MB | 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 implementationWhen 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. For details, refer to [advanced properties](../reference/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. | **Java 17-specific settings** | Module flag | Suggested value | Description | | ------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--add-opens` | `java.xml/com.sun.org.apache.xerces.internal.dom=ALL-UNNAMED` | When running AM with JRE 17, SAML Artifact flows (or 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 this module flag to avoid this error. |