--- title: Upgrading a PingAccess cluster using the upgrade utility description: Upgrade a PingAccess cluster to a newer version. component: pingaccess version: 9.0 page_id: pingaccess:upgrading_pingaccess:pa_upgrading_a_pa_cluster_using_the_upgrade_utility canonical_url: https://docs.pingidentity.com/pingaccess/9.0/upgrading_pingaccess/pa_upgrading_a_pa_cluster_using_the_upgrade_utility.html revdate: February 6, 2023 section_ids: before-you-begin: Before you begin about-this-task: About this task steps: Steps choose-from: Choose from: choose-from-2: Choose from: choose-from-3: Choose from: next-steps: Next steps 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 --- # Upgrading a PingAccess cluster using the upgrade utility Upgrade a PingAccess cluster to a newer version. ## Before you begin * If you are using PingAccess 3.2 or earlier, upgrade to PingAccess 4.3 or 5.3 before upgrading to the latest version. * Create a backup of your existing PingAccess configuration. If the upgrade fails, you can restore your environment from this backup. * Review the release notes for every version between your current version and the target version. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In PingAccess 5.0 or later, there are 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 administrative SDK. For information on these changes and the actions administrators might need to take, see the [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: * 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. * Basic authentication is configured and enabled for the running PingAccess administrative node. * You have the `.zip` bundle for the target version of PingAccess. * Verify that you are using the same account normally used to run PingAccess. ## About this task Use the PingAccess upgrade utility to upgrade a cluster from PingAccess 4.0 or later, the source version, to the most recent version, the target version. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The upgrade procedure causes some downtime. To upgrade a cluster with no downtime, see 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. This port configuration is only used for the upgrade. The configured port is used by the upgraded server when the upgrade is complete. Any warnings or errors encountered are recorded in `log/upgrade.log`, as well as on-screen while the utility is being run. The upgrade uses an exit code of 0 to indicate a successful upgrade and an exit code of 1 to indicate failure. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you are upgrading from version 4.3 or earlier, and your installation uses custom plugins, they must be rebuilt 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 the custom plugin JAR files and only the custom plugin JAR files. To migrate your custom plugins, see the [PingAccess Addon SDK for Java Migration Guide](../agents_and_integrations/pa_add_on_sdk_for_java_migration_guide.html). | | | | | - | ---------------------------------------------------------------------------------- | | | During the upgrade, do not make any changes to the running PingAccess environment. | ## Steps 1. On the administrative node, extract the `.zip` file 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 After you complete the upgrade, see [Performing post-upgrade tasks](pa_performing_post_upgrade_tasks.html). ## 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 ```