Upgrading the replica administrative node
Upgrade the PingAccess replica administrative node using the PingAccess Upgrade Utility, then resume configuration replication.
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.
During the upgrade, it is important to not make any changes to the running PingAccess environment. |
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 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 thedeploy
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 newPA_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 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
org
to specify the unit.Memory option Description -Xmsamount
Minimum heap size.
-Xmxamount
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.
For 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 replica admin instance.
-
Start the new PingAccess replica admin instance.
You’re now ready to resume configuration replication for the replica administrative node.
-
In a browser, go to https://host:admin-port/pa-admin-api/v3/api-docs/.
Example:
-
Expand the /adminConfig/replicaAdmins endpoint.
-
Click the GET /adminConfig/replicaAdmins operation.
-
Click Try it out! and note the
id
for the replica admin. -
Click the GET /adminConfig/replicaAdmins/{id} operation.
-
Enter the id of the replica admin you want to update and click Try it out!
-
Copy the Response Body.
-
Click the PUT /adminConfig/replicaAdmins/{id} operation and enter the id of the replica admin you want to update.
-
Paste the Response Body you copied and change
"configReplicationEnabled"
totrue
. -
Click Try it out!
Result:
If the operation is successful, you will receive a response code of
200
.Click Settings and then go to Clustering → Administrative Nodes.
-
Ensure the Replica Administrative Node displayed and reporting on the Administrative Nodes tab. A healthy node shows a green status indicator.
Next steps
After you have upgraded the administrative and replica administrative nodes, you can begin upgrading the engines.