--- title: memoryoptions and upgrade description: Upgrade paths behave differently when changes are executed based on the recommendations and execution of the memoryoptions utility tool. component: pingfederate version: 13.1 page_id: pingfederate:performance_tuning_guide:pf_memoryoptions_upgrade canonical_url: https://docs.pingidentity.com/pingfederate/13.1/performance_tuning_guide/pf_memoryoptions_upgrade.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: June 13, 2023 --- # 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 `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 `.zip`file.* 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 `/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 `/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 \/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 `/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 `/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. |