Upgrading the engine

Use the PingAccess Upgrade Utility to upgrade the engine.

Before you begin

For more information on upgrading PingAccess, see Upgrade PingAccess. The following flowchart displays an example engine upgrade.

Flowchart showing a deployment as the engine is upgraded.

In this flowchart:

A user with a WebSession Cookie sends a request to the load balancer.
The load balancer directs the request to one of the un-upgraded engine nodes. The first engine node is using the target version of PingAccess, while the other engine nodes are still using the source version of PingAccess.
The administrative node is using the target version of PingAccess.

Before beginning the upgrade process, make sure you have:

Ensured the PingAccess engine is running
Downloaded the PingAccess distribution .zip file or the incremental update bundle and extracted it.
The PingAccess license

About this task

Any warnings or errors encountered are recorded in log/upgrade.log, as well as on the screen while the utility is running. The upgrade uses an exit code of 0 to indicate a successful upgrade and an exit code of 1 to indicate failure.

Steps

If you are using the upgrade utility, change to the new version’s /upgrade/bin directory on the command line.

Example:
```
cd /pingaccess-6.1.0/upgrade/bin
```

Upgrade the system:

Choose from:

If you are using the upgrade utility on a Windows system, use this command: upgrade.bat <admin_port>] <directory>] <jvm_memory_options_file>] <newPingAccessLicense>] [-s \| --silent] <sourcePingAccessRootDir>.

For example:
```
upgrade.bat ../pingaccess-5.3.0
```
If you are using the upgrade utility on a Linux system, use this command: ./upgrade.sh <admin_port>] <directory>] <jvm_memory_options_file>] <newPingAccessLicense>] [-s \| --silent] <sourcePingAccessRootDir>.

For example:
```
./upgrade.sh ../pingaccess-5.3.0
```

If you are using the incremental update package, open the ReadMeFirst.txt file and make the file changes specified in the readme.

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

Parameter definitions

Parameter Value description

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 (for example, plugins, JDBC drivers) to be copied into the target installation. Beginning in version 6.0, JAR files are stored in the `<PA_HOME>/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 `<PA_HOME>/deploy` folder if no directory is specified.
<sourcePingAccessRootDir>	The PA_HOME for the source PingAccess version.
-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) 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.

-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 (for example, plugins, JDBC drivers) to be copied into the target installation.

Beginning in version 6.0, JAR files are stored in the <PA_HOME>/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 <PA_HOME>/deploy folder if no directory is specified.

<sourcePingAccessRootDir>

The PA_HOME for the source PingAccess version.

-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) 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:

Environment variable Description

Environment variable	Description
`PA_SOURCE_API_USERNAME`	The username for the source version’s Admin application programming interface (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.

PA_SOURCE_API_USERNAME

The username for the source version’s Admin application programming interface (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.

JVM Memory options

These options can be included in the JVM memory options file. Memory amounts use m or g to specify the unit.

Memory option Description

Memory option	Description
`-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.

-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.

Example:

#Sample JVM Memory options file
-Xms512m
-Xmx1g
-XX:NewSize=256m
-XX:MaxNewSize=512m
-XX:+UseParallelGC

You can copy the existing PA_HOME/conf/jvm-memory.options file to create a JVM memory options file for the upgrade.

Stop the existing PingAccess instance. Do not start the new instance.

Next steps

If PingAccess is running as a service and you upgraded using the upgrade utility:

In Linux, update PA_HOME in /etc/systemd/system/pingaccess.service to point to the new installation.
In Windows, remove the existing PingAccess service (<OLD_PA_HOME>\sbin\Windows\uninstall-service.bat) and add the new service (<NEW_PA_HOME>\sbin\Windows\install-service.bat).