Hosting Environment
Operating System
Task Type
Draft Beta

Upgrade PingAccess

Updated 94

Add to MyDocs | Hide Show Table of Contents

Upgrade a PingAccess standalone version

Important: In release 5.0, there are potentially breaking changes to the SDK for Java, Groovy scripts, and the Administrative API. For information on these changes and the actions administrators may need to take, review the PingAccess Release Notes for release 5.0, in addition to any release notes for releases between your current version and the target version.

This document provides instructions for upgrading a standalone instance of PingAccess.

To run the upgrade utility, you will need the following:

  • The PingAccess Upgrade Utility archive
  • The PingAccess distribution zip file
  • Your PingAccess license file
  • Login access to the PingAccess host, as the utility is run on the host
  • Basic Authentication needs to be configured and enabled for the running PingAccess instance. Administrator Single Sign-On must be disabled for the upgrade.
  • The version of PingAccess you are upgrading from must be running
  • Administrator credentials for the running PingAccess instance

If your installation uses custom plugins, they will need to be rebuilt against the new (5.0) SDK. You will then run the Upgrade Utility manually with the new "-i" command-line option to include their plugin directory. To migrate your custom plugins, see the PingAccess Addon SDK for Java Migration Guide.

Copy these files to the system being upgraded, and unpack the PingAccess Upgrade Utility archive.
Important: If you have set security.overridePropertiesFile=false in $JAVA_HOME/jre/lib/, the upgrade utility may fail, as the PingAccess Upgrade Utility uses an override to enable deprecated ciphers and protocols during the upgrade process.

The upgrade utility starts an instance of PingAccess with an administrative listener on port 9001. This port number can be changed using the run.bat/ -p parameter. This port configuration is only used for the upgrade - the default 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 the screen while the utility is being run.

Info: During the upgrade, it is important to not make any changes to the running PingAccess environment.

Use the PingAccess Upgrade Utility to upgrade from PingAccess 2.1 or later to the most recent version.

Important: Before you upgrade, create a backup of your existing PingAccess configuration. In the event of an upgrade failure, you can restore the backup configuration.
  1. Unpack the upgrade utility zip file.
  2. Change to the upgrade utility's bin directory.
  3. Run the PingAccess Upgrade Utility:
    • On Windows: run.bat [-p <admin_port>] [-i <directory>] <sourcePingAccessRootDir> <outputDir> <pingaccessZip> <newPingAccessLicense>
    • On Linux: ./ [-p <admin_port>] [-i <directory>] <sourcePingAccessRootDir> <outputDir> <pingaccessZip> <newPingAccessLicense>
    For example: ./ -p 9002 -i MyJARDir pingaccess-4.3 pingaccess-5.0 pingaccess50.lic

    Parameter Definitions

    The command-line parameters are the same regardless of the platform, and are defined as follows:

    Parameter Value description
    <admin_port> Optional port to be used by the temporary PingAccess instance run during the upgrade. The default is 9001.
    <directory> A directory containing additional library JAR files (e.g. plugins, JDBC drivers) to be copied into the target installation
    <sourcePingAccessRootDir> The PA_HOME for the source PingAccess version
    <outputDir> The target directory which will contain the unpacked PingAccess distribution
    <pingaccessZip> The PingAccess distribution for the target version
    <newPingAccessLicense> The path to the PingAccess license file to use for the target version
    Note: In the context of an upgrade, "source" refers to the old version of PingAccess, and "target" refers to the new version.

Tags Product > PingAccess > PingAccess 5.2; Product > PingAccess