Upgrading PingFederate on Windows using the Upgrade Utility - PingFederate - 10.3

PingFederate Server

bundle
pingfederate-103
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 10.3
category
Product
pf-103
pingfederate
ContentType_ce

If you used the server distribution .zip file to install the previous version of PingFederate on Windows, you must use the Upgrade Utility to upgrade to the current version of PingFederate.

Read the Upgrading PingFederate 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.

Important:

If you are upgrading a clustered PingFederate environment, start with the console node, and then follow the additional steps to upgrade the engine nodes. All servers in a cluster must use the same version of PingFederate.

  1. Download the latest version of the PingFederate Server distribution .zip file from the Ping Identity website.
    Note:

    The distribution .zip file is identical for both Windows and Linux.

  2. Extract the distribution.zip file into the target installation directory.
  3. Stop PingFederate.
  4. At the command prompt, change the current directory to <pf_install>\pingfederate\upgrade\bin within the target installation and enter the following command.
    upgrade <pf_install_source> [-l <newLicense>] [-c] [--release-notes-reviewed]

    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.

    <newLicense>
    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 <newLicense> 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 to the newest version of each installed plugin.
    --release-notes-reviewed
    An optional parameter that indicates that you have already reviewed the release notes. This parameter prevents prompts during the upgrade that ask if you have read the release notes and the upgrade considerations.
    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 then correct the indicated problems. Errors during the upgrade should be rare but might include problems such as missing or malformed configuration files in the source installation. The messages are also logged to the upgrade.log file in the Upgrade Utility base directory.

  5. If you are upgrading a clustered PingFederate environment, repeat from step 1 to upgrade PingFederate on each engine node.
    Note:

    End users might experience disruptions while you upgrade your PingFederate environment.

  6. Start the new PingFederate installation.
    If you are upgrading a clustered PingFederate environment, start the new PingFederate instance on the console node.

    If you have configured single sign-on using OpenID Connect as the console authentication scheme and set the endpoint settings back to your PingFederate environment, start the new PingFederate instance on the console node and one of the engine nodes.

  7. Open the administrative console and verify the new installation.
  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 > Server > Cluster Management window.
    2. Click Replicate Configuration on the Cluster Management window.
  9. If PingFederate is running as a service, re-install the service.
    1. Remove the existing PingFederate service (see Uninstalling PingFederate from a Windows server).
    2. Install the new PingFederate service (see Installing PingFederate service on Windows manually).
    For a clustered PingFederate environment, re-install the PingFederate service on all nodes.
  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.
    • If the PingOne MFA or PingOne Protect integration kit was installed on PingFederate, you must manually migrate its .properties file after the upgrade.
    • All other .properties files in <pf_install>\pingfederate\server\default\conf\language-packs that do not fit the previous criteria are copied (not merged) into the upgraded PingFederate installation.