Read the PingFederate Upgrade Guide topic for an overview of the upgrade process.

Upgrade results are contained in the upgrade.log file, which is located in <pf_install_target>/pingfederate/upgrade/log.

CAUTION:

If you are upgrading to PingFederate 10.0.1 and you are using AWS CloudHSM, you must update your CloudHSM client and CloudHSM Software Library for Java to version 3.0. See the instructions in step 5 for more information.

Important:

End users might experience service disruptions as you upgrade your PingFederate environment. All nodes in a clustered environment must have the same major.minor version of PingFederate. So when you upgrade nodes in a cluster to another major.minor version, you must stop all the nodes before you upgrade any of them.

  1. Download the latest version of the PingFederate Server distribution .zip file from the Ping Identity website.
  2. Unzip the distribution .zip file into the target installation directory.
  3. Stop PingFederate.
  4. On the command line, change the current directory to <pf_install>/upgrade/bin within the target installation and execute the following command: 
    ./upgrade.sh <pf_install_source> [-l <newPingFederateLicense>] [-c]

    where:

    <pf_install_source>
    The full or relative path of the base directory where the existing PingFederate software (pingfederate) is installed.
    Note:

    The pingfederate subdirectory must exist by that name for the Upgrade Utility to function correctly.

    <newPingFederateLicense>
    The optional path and file name of the license to use for the upgraded PingFederate version.
    Note:

    If your current license is valid, the Upgrade Utility automatically copies it from the source installation to the target installation, and you do not need to specify the <newPingFederateLicense> parameter.

    If your license is not valid, obtain a valid license file and specify its path and file name for this parameter.

    -c
    The optional parameter to run the tool in custom mode, which allows you to override newer default security settings (if any) and to upgrade the program files for the OpenToken Adapter.
    The command prompt displays messages indicating upgrade progress. The process is complete when the following message appears.
    Upgrade completed with [N] errors and [N] warnings

    If there are errors, scroll up the command window to see them and correct indicated problems. Errors during the upgrade should be rare but may include problems such as missing or malformed configuration files in the source installation. The messages, including any errors, are also logged to the upgrade.log file in the Upgrade Utility base directory.

  5. If you are using AWS CloudHSM:
    1. Make sure that you have updated the CloudHSM client and the CloudHSM Software Library for Java to 3.0 and that you have restarted the client.
    2. Copy <pf_install>/pingfederate/lib-ext/pf-aws-cloud-hsm-wrapper.jar to the JAVA_HOME/jre/lib/ext directory.
    3. Copy all of the files under /opt/cloudhsm/java and /opt/cloudhsm/lib to the JAVA_HOME/jre/lib/ext directory.
  6. If you are upgrading a clustered PingFederate environment, repeat from step 1 to upgrade PingFederate on each engine node.
  7. Start the new PingFederate installation and open the administrative console.
    If you are upgrading a clustered PingFederate environment, start the new PingFederate installation on the console node.
  8. If you are upgrading a clustered PingFederate environment:
    1. Start the new installation on each engine node, and then ensure all nodes are shown on the System > Cluster Management window.
    2. Click Replicate Configuration on the System > Cluster Managementwindow.
  9. If PingFederate is running as a service, re-configure the service.
    PingFederate systemd service
    Edit the PingFederate systemd unit file and reconfigure the PingFederate service (see step 7 in Installing the PingFederate service on Linux manually).
    PingFederate SysV initialization script
    Edit the PingFederate SysV initialization script and reconfigure the PingFederate service (see step 8 in Installing the PingFederate service on Linux manually).
  10. The upgrade utility automatically merges, migrates, and copies the language packs' .properties files into the upgraded PingFederate installation. Verify the language packs in the upgrade installation by looking at the .properties files located in the upgraded <pf_install>/pingfederate/server/default/conf/language-packs directory.
    • Standard .properties files include pingfederate-email-messages.properties, pingfederate-messages.properties, and pingfederate-sms-messages.properties. During upgrade, these files are migrated and merged into the upgraded PingFederate installation.
    • Localized .properties files (for example, pingfederate-messages_fr_CA.properties) are also migrated and merged into the upgraded PingFederate installation.
    • All other .properties files in <pf_install>/pingfederate/server/default/conf/language-packs that do not fit the previous two criteria are copied (not merged) into the upgraded PingFederate installation.