PingCentral

Upgrading PingCentral

You can upgrade from PingCentral 1.2 through 1.7 directly to 1.12. To begin the upgrade, download and extract the contents of the 1.12 distribution file and run the upgrade utility for Windows or Linux, as appropriate.

To learn how the upgrade works and which files are added and replaced during the process, see How the upgrade works.

For instructions on running the upgrade itself, see Upgrading to PingCentral 1.12.

Starting with PingCentral 1.8, signing certificates are stored in the PingCentral database instead of a PingCentral-specific trust store. Certificates that exist in this trust store are imported to the PingCentral database during the upgrade process.

How the upgrade works

The upgrade utility uses the extracted contents of the ping-central-1.12.0.zip file to copy and replace the appropriate information in the existing version installation location.

Files that were not modified since they were initially installed are overwritten with new versions during the upgrade process.

Note the following:

  • The database files (h2-data directory), the log files (log directory), the external library files (ext-lib directory), and the host key file (conf/pingcentral.jwk) remain intact during the upgrade process to preserve user data.

    If you are using the H2 database, when upgrading from any version prior to PingCentral to 1.11, the upgrade script will generate a directory that contains the old H2 v1 database (h2v1-data). This file may be deleted after checking that the upgrade was successful in PingCentral.

    Use the H2 database only for trial or training environments. It is not recommended to use the default H2 database in production. For testing and production environments, always use a secured external storage solution for proper functioning in a clustered environment. For more information on setting up an external database, see Setting up MySQL.

    Testing involving H2 is not a valid test. In both testing and production, it might cause various problems due to its limitations, and PingCentral does not support H2-involved cases.

  • If the application.properties file was modified, the current version of the file is merged with the latest version, preserving customizations.

    If you upgrade from any version prior to 1.10, use an H2 database, and still use the default password from your last installation, a new password will override it during this upgrade. However, if you updated the password from the original default, it is preserved in the application.properties file.

  • If the conf/log4j2.xml, bin/run.sh, and bin.run.bat files were modified, the new versions are installed and the old versions are renamed. Manually update the new files with customizations as necessary.

The following list indicates which directories and files are replaced with new files during the upgrade process of PingCentral 1.12, provided that they were not modified since the initial installation.

  • ReadMeFirst.txt

  • bin/obfuscate.bat

  • bin/obfuscate.sh

  • bin/run.bat

  • bin/run.sh

  • conf/application.properties

  • conf/log4j2.xml

  • bin/obfuscate.bat

  • legal

  • ping-central.jar

  • sbin

  • tools

Upgrading to PingCentral 1.12

To upgrade PingCentral to 1.12, on either Windows or Linux, download the 1.12 installation file, run the PingCentral upgrade utility, and plan for a short period of downtime.

Before you begin

Ensure that:

  • You are signed on to your system and have privileges that allow you to install applications.

  • All System requirements and supported configurations are met, and the Oracle Java 11 LTS runtime environment is installed.

  • The <JAVA_HOME> path points to the Java Development Kit software on your system. For example, /usr/lib/jvm/java-11-openjdk-11.0.5.10-0.e17_7.x86_64. To verify this information, run the echo $JAVA_HOME command.

  • The JAVA /bin directory path is added to the <PATH> variable. To verify this information, run the echo $PATH command.

Steps

  1. Download the ping-central-1.12.0.zip file and extract its contents.

    You can delete this file after the upgrade is complete.

  2. If PingCentral is running, shut it down.

    This maintains the integrity of the H2 database file and ensures that you are running 1.12 as you complete the installation.

  3. Make a copy of the existing PingCentral version product directory so that the older version can be restored if the upgrade process fails.

    If PingCentral has been configured to use an external database, such as MySQL, or PostgreSQL, make a copy of that database so that it can be restored if the upgrade process fails.

  4. Go to the <pingcentral_1.12.0_install>/upgrade directory and run the appropriate file:

    Option Description

    Windows

    Run bin\upgrade.bat "--existing=<PINGCENTRAL_HOME>"

    Linux

    Run bin/upgrade.sh --existing=<PINGCENTRAL_HOME>

    Result:

    The upgrade process begins. The upgrade utility uses the extracted contents of the ping-central-1.12.0.zip file to copy and replace the appropriate information in the existing version location.

    When the upgrade is complete for this release, PingCentral 1.12 will run from the directory in which PingCentral was initially installed. For example, if PingCentral 1.4 was initially installed and you upgraded to 1.6, and now to 1.2, PingCentral 1.12 will run from the original 1.4 directory. The same is true if you upgraded directly from 1.4 to 1.12.

  5. Optional: To update the license file (conf/pingcentral.lic), add --license=<file> at the end of the upgrade command and specify the path to the new license.

    Result:

    As the upgrade continues, a message displays that reminds you to shut down PingCentral if you have not already done so.

  6. To continue, type yes.

    Result:

    A message displays that reminds you to back up your PingCentral program files.

  7. To continue, type yes.

    Result:

    The upgrade continues and the system displays a message when the upgrade is complete.

    If PingCentral was installed as a service by one user, and the upgrade is performed by another user, the service will no longer start. To resolve this issue, run the following command to update the installation files to match the existing ownership:

    chown -R [user]:[group] [INSTALL_DIR]

    Where the user and group match the existing installation:

    chown -R pingcentral:pingcentral /usr/local/pingcentral-1-1.12.0/

  8. Inspect the upgrade utility output for warnings regarding required manual merges.

    Other than the application.properties file, which is merged automatically, you must manually merge customizations you consider important. These customizations might include changes you made to the conf/log4j2.xml file, or changes you made to a file in the /bin directory.

    If you are upgrading from any version prior to 1.10, using an H2 database and were still using the default password from your last upgrade, you need to update the password in the application.properties file.

  9. Start PingCentral 1.12.

    Option Description

    Windows

    Run /<PINGCENTRAL_HOME>/bin/run.bat.

    Linux

    Run /<PINGCENTRAL_HOME>/bin/run.sh, or by running the systemd service command, systemctl pingcentral-# start.

  10. Sign on to PingCentral using the credentials you used to sign on to the previous version.

    There is no need to reconfigure PingCentral to run as a Windows or Linux systemv or systemd service after the upgrade.

  11. Upon successful upgrade, delete the 1.12 distribution .zip file and the directory into which it was extracted.

    After the upgrade, advise your users to refresh their browsers if they experience issues.