PingFederate Server

memoryoptions and upgrade

Upgrade paths behave differently when changes are executed based on the recommendations and execution of the memoryoptions utility tool.

Depending upon the selected tool and whether the jvm-memory.options file exists in the source installation, the expected behavior of the memoryoptions utility differs. In general, the jvm-memory.options file from the source installation is preserved without new recommended values.

You should not use the memoryoptions script when you deploy PingFederate inside of a container. Instead, you should edit the jvm-memory.options file directly. In containers, you should use the InitialRAMPercentage and MaxRAMPercentage JVM options to control the size of the heap.

See the following table for information regarding expected behaviors.

PingFederate upgrade paths and their expected behaviors from the execution of the memoryoptions utility tool
Upgrade path Expected behavior when thejvm-memory.optionsfile does not exist in the source installation

PingFederate installer for Windows

  • The installer creates a new PingFederate installation.

  • The installer runs the [.ph]## memoryoptions utility. Regardless of available memory, PingFederate uses the Garbage-First (G1) garbage collector (GC). The script assumes that PingFederate will be the only service on the server and consume a majority of the memory. The script records the defaults in the jvm-memory.options file.

  • The installer configures PingFederate to run as a service.

  • The recommended options are activated as the PingFederate service starts.

PingFederate Upgrade Utility (upgrade.bat)

The upgrade utility creates a new PingFederate installation based on the source installation and the PingFederate product distribution .zip file.

The default jvm-memory.options file becomes part of the new installation as the upgrade utility extracts files from the PingFederate product distribution .zipfile.

PingFederate as a console application on Windows

  • The G1GC JVM options set in the default jvm-memory.options file are activated as PingFederate starts.

  • The default JVM options are conservative. For most deployment scenarios using various physical or virtual resources, run the memoryoptions utility. Regardless of available memory, PingFederate uses the G1GC. The script assumes that PingFederate will be the only service on the server and consume a majority of the memory.

  • As a result of the execution of the memoryoptions utility or a manual edit of the jvm-memory.options file, the JVM options are activated as PingFederate restarts.

PingFederate as a service on Windows

  • When administrators run the PingFederate service-installation program install-service.bat, located in the <pf_install>/pingfederate/sbin/win-x86-64 directory, to install the PingFederate Windows service manually, the program runs the memoryoptions utility. Regardless of available memory, PingFederate uses the G1GC. The script assumes that PingFederate will be the only service on the server and consume a majority of the memory. The service-installation program then runs a helper utility, generate-wrapper-jvm-options.bat, located in the <pf_install>/pingfederate/sbin/wrapper directory, to read the JVM options from the jvm-memory.options file and create a resource file that the PingFederate Windows service requires to configure its JVM options

  • The default options are activated as the PingFederate service starts.

PingFederate Upgrade Utility (upgrade.sh)

  • The upgrade utility creates a new PingFederate installation based on the source installation and the PingFederate product distribution zip file. The default jvm-memory.options file becomes part of the new installation as the upgrade utility extracts files from the PingFederate product distribution zip file.

  • The JVM options set in the default jvm-memory.options file are activated as PingFederate starts.

  • The default JVM options are conservative. For most deployment scenarios using various physical or virtual resources, run the memoryoptions utility. Regardless of available memory, PingFederate uses the G1GC. The script assumes that PingFederate will be the only service on the server and consume a majority of the memory. The default options are recorded in the jvm-memory.options file.

  • As a result of the execution of the memoryoptions utility or a manual edit of the jvm-memory.options file, the JVM options are activated as PingFederate restarts.
Upgrade path Expected behavior when the jvm-memory.optionsfile exists in the source installation

PingFederate installer for Windows

  • The installer creates a new PingFederate installation based on the source installation and copies the jvm-memory.options file from the source installation to the new installation.

  • At the end of the installation, the installer runs the PingFederate service-installation program, which runs a helper utility generate-wrapper-jvm-options.bat, located in the <pf_install>/pingfederate/sbin/wrapper directory, to read the JVM options from the jvm-memory.options file and create a resource file that the PingFederate Windows service requires to configure its JVM options.

  • The preserved Java virtual machine (JVM) options are activated as the PingFederate service starts.

PingFederate Upgrade Utility (upgrade.sh)

  • The installer creates a new PingFederate installation based on the source installation and copies the jvm-memory.options file from the source installation to the new installation.

  • The preserved JVM options are activated as the PingFederate service starts.

PingFederate Upgrade Utility (upgrade.bat)

The installer creates a new PingFederate installation based on the source installation and copies the jvm-memory.options file from the source installation to the new installation.

PingFederate as a console application on Windows

The preserved JVM options are activated as the PingFederate service starts.

PingFederate as a service on Windows

  • When administrators run the PingFederate service-installation program install-service.bat, located in the <pf_install>/pingfederate/sbin/win-x86-64 directory, to install the PingFederate Windows service manually, the program runs the memoryoptions utility. Regardless of available memory, PingFederate uses the G1GC. The script assumes that PingFederate will be the only service on the server and consume a majority of the memory. The default options are recorded in the jvm-memory.options file. The service-installation program then runs a helper utility, generate-wrapper-jvm-options.bat, located in the <pf_install>/pingfederate/sbin/wrapper directory, to read the JVM options from the jvm-memory.options file and create a resource file that the PingFederate Windows service requires to configure its JVM options

  • The new recommended options are activated as the PingFederate service starts.

To restore the preserved JVM options from the source installation, see Restoring the preserved JVM.