--- title: Upgrading a PingAccess cluster using the upgrade utility description: Upgrade a PingAccess cluster to a newer version using the upgrade utility. component: pingaccess version: 8.3 page_id: pingaccess:upgrading_pingaccess:pa_upgrading_a_pa_cluster_using_the_upgrade_utility canonical_url: https://docs.pingidentity.com/pingaccess/9.1/upgrading_pingaccess/pa_upgrading_a_pa_cluster_using_the_upgrade_utility.html llms_txt: https://docs.pingidentity.com/pingaccess/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: August 20, 2026 superseded_by: https://docs.pingidentity.com/pingaccess/9.1/upgrading_pingaccess/pa_upgrading_a_pa_cluster_using_the_upgrade_utility.html section_ids: before-you-begin: Before you begin pingaccess-cluster-upgrade-parameters: PingAccess cluster upgrade parameters parameter-definitions: Parameter definitions environment-variables: Environment variables java-virtual-machine-jvm-memory-options: Java virtual machine (JVM) memory options example: Example steps: Steps choose-from: Choose from: choose-from-2: Choose from: choose-from-3: Choose from: next-steps: Next steps --- # Upgrading a PingAccess cluster using the upgrade utility Upgrade a PingAccess cluster to a newer version. Use the PingAccess upgrade utility to upgrade from your current environment version (the *source version*) to the most recent version (the *target version*). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The upgrade procedure causes some downtime. To upgrade a cluster with no downtime, use the [Zero Downtime Upgrade](../pingaccess_zero_downtime_upgrade/pa_zero_downtime_upgrade.html) guide. | The upgrade utility starts an instance of PingAccess with an administrative listener on port 9001. You can change this port number using the `upgrade.bat` or `upgrade.sh` `-p` parameter, but this port configuration is only used for the upgrade. The upgraded server uses the port configured in the `run.properties` file after the upgrade is complete. | | | | - | --------------------------------------------------------------------------------- | | | During the upgrade, don't make any changes to the running PingAccess environment. | Any warnings or errors are recorded in `log/upgrade.log`, as well as on screen while the utility is running. The upgrade uses the following exit codes: * 0 Indicates a successful upgrade. * 1 Indicates the upgrade failed. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're upgrading from PingAccess 4.3 or earlier and your installation uses custom plugins, you must:* Rebuild them using the SDK version included in PingAccess 5.0 or later. * Run the upgrade utility manually with the new `-i` command-line option to specify a directory containing only the custom plugin JAR files.Learn more about migrating your custom plugins in the [PingAccess Add-On SDK for Java migration guide](../agents_and_integrations/pa_add_on_sdk_for_java_migration_guide.html). | ## Before you begin * Create a backup of your existing PingAccess configuration. If the upgrade fails, restore your environment from this backup. * If you're using PingAccess 6.2 or earlier, upgrade to PingAccess 6.3 before upgrading to a more recent version. * Review the release notes for every version between the source and target version. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | PingAccess 5.0 contains potentially breaking changes to the Software Development Kit (SDK) *(tooltip: \
\

A set of tools that allows a developer to build a custom application that integrates with or connects to a platform or service.\

\
)* for Java, Groovy scripts, and the admin API. Learn more about these changes and actions administrators might need to take in [Upgrade considerations](pa_upgrade_considerations.html) and the [PingAccess 5.0](https://cdn-docs.pingidentity.com/archive/pdf/pingaccess/pingaccess-50.pdf#page=263) release notes. | * Verify the following: * Basic authentication is configured and enabled for the admin API of the source PingAccess instance. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You might need to enable basic authentication if you have limited access permissions to OAuth because of your configured role. Learn more in [Configuring API authentication](../pingaccess_user_interface_reference_guide/pa_configuring_api_authn.html). | * You're using the same account normally used to run PingAccess. * Each node is using the same PingAccess version. You can check the version by viewing the `/lib/pingaccess-admin-ui-.jar` file. * The PingAccess administrative node is running. * You have the `.zip` archive for the target version of PingAccess. ## PingAccess cluster upgrade parameters The command-line parameters are the same regardless of the platform, and are defined as follows. ### Parameter definitions | Parameter | Value description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -r \| --disable-config-replication | Disables configuration replication on the admin node. For more information about using this parameter in an upgrade, see the [Zero Downtime Upgrade](../pingaccess_zero_downtime_upgrade/pa_zero_downtime_upgrade.html). | | -p *\* | Optional port to be used by the temporary PingAccess instance run during the upgrade. The default is 9001. | | -i *\* | An optional directory containing additional library JAR files, such as plugins, Java Database Connectivity (JDBC) drivers to be copied into the target installation.Beginning in version 6.0, `JAR` files are stored in the `/deploy` folder.During an upgrade from versions earlier than 6.0, third-party `JAR` files are migrated from the `lib` folder to the `deploy` folder if no directory is specified.During an upgrade from version 6.0 or later, the contents of the `deploy` folder are migrated to the new `/deploy` folder if no directory is specified. | | *\* | The PA_HOME for the source PingAccess version. | | -l *\* | An optional path to the PingAccess license file to use for the target version. If not specified, the existing license is reused. | | -j *\* | An optional path to a file with Java Virtual Machine (JVM) *(tooltip: \
\

A virtual machine that allows a computer to run Java programs and programs that are compiled to Java bytecode.\

\
)* memory options to use for the new PingAccess instance during the upgrade. | | -s \| --silent | Run the upgrade with no user input required. To use this option, specify the source version's credentials using environment variables. | ### Environment variables You can specify the username and password for the source version using these environment variables: * `PA_SOURCE_API_USERNAME` – The username for the source version's Admin API. This should be set to Administrator. * `PA_SOURCE_API_PASSWORD` – The basic authorization password for the Administrator in the source version's Admin API. ### Java virtual machine (JVM) memory options These options can be included in the JVM memory options file. Memory amounts use `m` or `g` to specify the unit. * `-Xms` – Minimum heap size. * `-Xmx` – Maximum heap size. * `-XX:NewSize=` – Minimum size for the Young Gen space. * `-XX:MaxNewSize=` – Maximum size for the Young Gen space. * `-XX:+UseParallelGC` – Specifies that the parallel garbage collector should be used. You can copy the existing `/conf/jvm-memory.options` file to create a JVM memory options file for the upgrade. ### Example ``` #Sample JVM Memory options file -Xms512m -Xmx1g -XX:NewSize=256m -XX:MaxNewSize=512m -XX:+UseParallelGC ``` ## Steps 1. On the administrative node, extract the `.zip` archive for the target version of PingAccess. 2. Go to the new version's `/upgrade/bin` directory. 3. Run the PingAccess upgrade utility: ### Choose from: * On Windows: `upgrade.bat [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` * On Linux: `./upgrade.sh [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` 4. Review the upgrade log. If it records any manual post-upgrade tasks: 1. Stop the source administrative console. 2. Start the target administrative console using the `/bin/run.sh` command on Linux systems or the `\bin\run.bat` command on Windows systems. 3. Perform any manual post-upgrade tasks recorded in the upgrade log. 4. Shut down the upgraded administrative console. 5. Run the upgrade utility on the replica administrative node. ### Choose from: * On Windows: `upgrade.bat [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` * On Linux: `./upgrade.sh [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` 6. Run the upgrade utility on each engine node. ### Choose from: * On Windows: `upgrade.bat [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` * On Linux: `./upgrade.sh [-p ] [-i ] [-j ] [-l ] [-s | --silent] ` 7. Shut down the entire cluster. 8. Start the upgraded administrative node. 9. Start the upgraded replica administrative node. 10. Start each upgraded engine node. ## Next steps Review [Performing post-upgrade tasks](pa_performing_post_upgrade_tasks.html).