• 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.
    Important:

    In PingAccess 5.0 or later, there are potentially breaking changes to the SDK 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 and the PingAccess Release Notes for release 5.0.

  • Verify the following:
    • Each node is using the same PingAccess version. You can check the version by viewing the <PA_HOME>/lib/pingaccess-admin-ui-<version number>.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.

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.

Note:

The upgrade procedure causes some downtime. To upgrade a cluster with no downtime, see the Zero Downtime Upgrade 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.

Important:

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.

Note:

During the upgrade, do not make any changes to the running PingAccess environment.

  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:
    • On Windows: upgrade.bat [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
    • On Linux: ./upgrade.sh [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
  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 <PA_HOME>/bin/run.sh command on Linux systems or the <PA_HOME>\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.
    • On Windows: upgrade.bat [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
    • On Linux: ./upgrade.sh [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
  6. Run the upgrade utility on each engine node.
    • On Windows: upgrade.bat [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
    • On Linux: ./upgrade.sh [-p <admin_port>] [-i <directory>] [-j <jvm_memory_options_file>] [-l <newPingAccessLicense>] [-s | --silent] <sourcePingAccessRootDir>
  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.

After you complete the upgrade, see Performing post-upgrade tasks.