When executed by the upgrade tools, depending the selected tool and whether the jvm-memory.options exists in the source installation, the expected behavior differs. Generally speaking, the jvm-memory.options file from the source installation is preserved without new recommended values. Refer to the following table for information regarding expected behaviors.

Upgrade path Expected behavior when the jvm-memory.options file does not exist in the source installation
PingFederate installer for Windows
  • The installer creates a new PingFederate installation.
  • The installer runs the memoryoptions utility, which is designed to determine the recommended Java heap and garbage collector options based on the available resources and to record them 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 ZIP file.
PingFederate as a console application on Windows
  • The JVM options set in the default jvm-memory.options file are activated as PingFederate starts.
  • Note that the default JVM options are conservative. For most deployment scenarios using various physical or virtual resources, administrators should run the memoryoptions utility, which is designed to determine the recommended Java heap and garbage collector options based on the available resources and to record them in the jvm-memory.options file.
  • The JVM options as a result of the execution of the memoryoptions utility (or a manual edit of the jvm-memory.options file) 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, which is designed to determine the recommended Java heap and garbage collector options based on the available resources and to record them 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 recommended 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.
  • Note that the default JVM options are conservative. For most deployment scenarios using various physical or virtual resources, administrators should run the memoryoptions utility, which is designed to determine the recommended Java heap and garbage collector options based on the available resources and to record them in the jvm-memory.options file.
  • The JVM options as a result of the execution of the memoryoptions utility (or a manual edit of the jvm-memory.options file) are activated as PingFederate restarts.
Upgrade path Expected behavior when the jvm-memory.options file 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 in turn 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 JVM 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 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 upgrade utility 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, which is designed to determine the recommended Java heap and garbage collector options based on the available resources and to record them 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, follow these steps:

  1. Rename the current jvm-memory.options file.

    For example: jvm-memory.options.backup

  2. Look for the preserved jvm-memory.options file.

    The preserved file was renamed with a time stamp.

  3. Remove the time stamp from the file name.

    At this point, the jvm-memory.options is the file preserved from the source installation.

  4. Open a command prompt and go to the <pf_install>/pingfederate/sbin/wrapper directory.
  5. Run generate-wrapper-jvm-options.bat.

    This helper utility reads the JVM options from the jvm-memory.options file and creates a resource file that the PingFederate Windows service requires to configure its JVM options.

  6. Close the command prompt.
  7. Restart the PingFederate Windows service.

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