Upgrading a PingAccess standalone version using the upgrade utility
Upgrade a standalone PingAccess deployment 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 current version of PingAccess.
-
Create a backup of your existing PingAccess configuration. If the upgrade fails, restore your environment from this backup.
-
Review the release notes for every version between your current version and the target version.
In release 5.0, there are potentially breaking changes to the Software Development Kit (SDK) for Java, Groovy scripts, and the administrative application programming interface (API). For information on these changes and the actions administrators might need to take, review the Upgrade considerations and the PingAccess Release Notes for release 5.0.
-
Verify that you have the following:
-
The PingAccess distribution
.zip
file -
Your new PingAccess license file, if you plan to switch to a new license file
-
Sign on access to the PingAccess host, as the utility is run on the host
-
Administrator credentials for the running PingAccess instance
-
-
Verify that basic authentication is configured and enabled for the running PingAccess instance.
-
Verify that the PingAccess host is running.
-
Verify that you are using the same account normally used to run PingAccess.
If you have set |
About this task
Use the PingAccess upgrade utility to upgrade from PingAccess 4.0 or later, the source version, to the most recent version, the target version.
The upgrade utility starts an instance of PingAccess with an administrative listener on port 9001. This port number can be changed 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 |
During the upgrade, do not make any changes to the running PingAccess environment. |
Steps
-
Copy the
.zip
file for the new PingAccess version to the PingAccess host and extract it. -
Change to the new version’s
/upgrade/bin
directory. -
Run the PingAccess upgrade utility:
Choose from:
-
On Windows:
upgrade.bat <admin_port>] <directory>] <jvm_memory_options_file>] <newPingAccessLicense>] [-s \| --silent] <sourcePingAccessRootDir>
-
On Linux:
./upgrade.sh <admin_port>] <directory>] <jvm_memory_options_file>] <newPingAccessLicense>] [-s \| --silent] <sourcePingAccessRootDir>
Example:
For example:
./upgrade.sh -p 9002 -i MyJARDir pingaccess-5.3
-
Next steps
After you complete the upgrade, see Performing post-upgrade tasks.
PingAccess standalone upgrade parameters
The command-line parameters are the same regardless of the platform and are defined in the following table.
Parameter | Value description |
---|---|
-p <admin_port> |
Optional port to be used by the temporary PingAccess instance run during the upgrade. The default is 9001. |
-i <directory> |
An optional directory containing additional library JAR files, such as plugins and Java Database Connectivity (JDBC) drivers, to be copied into the target installation. Beginning in version 6.0, JAR files are stored in the During an upgrade from versions earlier than 6.0, third-party JAR files are migrated from the During an upgrade from version 6.0 or later, the contents of the |
<sourcePingAccessRootDir> |
The |
-l <newPingAccessLicense> |
An optional path to the PingAccess license file to use for the target version. If not specified, the existing license is reused. |
-j <jvm_memory_options_file> |
An optional path to a file with Java Virtual Machine (JVM) 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
You can include these options in the JVM memory options file. Memory amounts use m
or g
to specify the unit.
-
-Xms<amount>
– Minimum heap size -
-Xmx<amount>
– Maximum heap size -
-XX:NewSize=<amount>
– Minimum size for the Young Gen space -
-XX:MaxNewSize=<amount>
– Maximum size for the Young Gen space -
-XX:+UseParallelGC
– Specifies that the parallel garbage collector should be used
You can copy the existing <PA_HOME>/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