PingFederate Server

Upgrading PingFederate installations

When upgrading your PingFederate installation on Linux, you must use the Upgrade Utility. On Windows, you can use either the Upgrade Utility or the installer.

Before you begin

  • Read Upgrading PingFederate for an overview of the upgrade process.

  • Ensure that you are signed on to your server with appropriate privileges to install and run an application.

About this task

Choose the relevant procedure for your system to upgrade PingFederate.

If you are upgrading a clustered PingFederate environment, start with the console node, and then upgrade the engine nodes.

All nodes must use the same version of PingFederate.

  • Upgrading on Linux

  • Upgrading on Windows with the Upgrade Utility

  • Upgrading on Windows with the installer

Upgrading PingFederate on Linux systems

You can use the Upgrade Utility on Linux servers to upgrade to the current version of PingFederate.

About this task

The Upgrade Utility copies all relevant sources of your current installation into the new target directory of your choice. It doesn’t change the current installation.

The Upgrade Utility migrates the existing versions of all PingFederate plugins by default. You can use the -c command line parameter to override the default behavior and install the latest versions of each plugin.

Upgrade results are contained in the <pf_install_target>/pingfederate/upgrade/log/upgrade.log file.

To use the Upgrade Utility on Linux servers to upgrade to the current version of PingFederate:

Steps

  1. Download the latest version of the PingFederate Server distribution.zip archive from the Ping Identity website.

  2. Extract the .zip to the new target directory of your choice, <pf_install_target>.

  3. Stop PingFederate.

  4. On the command line, change directory to <pf_install_target>/upgrade/bin and execute the following command:

    ./upgrade.sh  <pf_install_source>  <newLicense>] [-c] [--release-notes-reviewed]

    where: <pf_install_source>::

    The full or relative path of the base pingfederate directory where the existing PingFederate software is installed.

The pingfederate directory must have the name "pingfederate" for the Upgrade Utility to function correctly.
<newLicense>

The optional path and file name of the license to use for the upgraded PingFederate version.

If your current license is valid, the Upgrade Utility automatically copies it from the source installation to the target installation, and you don’t need to specify the <newLicense> parameter.

If your license isn’t 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’ve already reviewed the release notes. This parameter prevents prompts during the upgrade that ask if you’ve 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.

  1. If you’re using an older version of the Amazon Web Services (AWS) CloudHSM client:

    1. Update the CloudHSM client and the CloudHSM Software Library for Java to a supported version and restart the client.

      For more information, see System requirements.

    2. Copy <pf_install_target>/pingfederate/lib-ext/pf-aws-cloud-hsm-wrapper.jar to the JAVA_HOME/jre/lib/ext directory.

    3. Copy all of the files in the /opt/cloudhsm/java and /opt/cloudhsm/lib directories to the JAVA_HOME/jre/lib/ext directory.

    If you’re upgrading a clustered PingFederate environment, repeat from step 1 to upgrade PingFederate on each engine node.

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

  1. If PingFederate is running as a service, reconfigure the PingFederate service:

    1. Edit the <pf_install_target>/pingfederate/sbin/linux/pingfederate.service systemd unit file (see step installing_and_uninstalling_pingfederate:pf_install_pf_service_on_linux_manually.adoc#pf_step_installPingfederateSystemdService in Installing PingFederate > Installing on Linux manually).

    2. Edit the <pf_install_target>/pingfederate/sbin/linux/pingfederate SysV initialization script (see step installing_and_uninstalling_pingfederate:pf_install_pf_service_on_linux_manually.adoc#pf_step_installPingfederateSysvInitializationScript in Installing PingFederate > Installing on Linux manually).

    Start the new PingFederate installation.

If you’re upgrading a clustered PingFederate environment, start the new PingFederate instance on the console node.

If you’ve configured single sign-on using OpenID Connect (OIDC) 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.

  1. Verify the new installation’s version:

    1. Open the new installation’s administrative console.

    2. On the toolbar, click the Question Mark icon. On the Help menu, click About.

    3. Verify that the pop-up shows the new version.

  2. If you’re 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 page.

    2. On the Cluster Management page, click Replicate Configuration.

  1. Although 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_target>/pingfederate/server/default/conf/language-packs directory.

    • Standard .properties files include pingfederate-email-messages.properties, pingfederate-messages.properties, and pingfederate-sms-messages.properties. During the 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_target>/pingfederate/server/default/conf/language-packs that don’t fit the previous criteria are copied (not merged) into the upgraded PingFederate installation.

Next steps

After upgrading PingFederate, perform the Post-upgrade tasks.

Upgrading PingFederate on Windows using the Upgrade Utility

You can use the Upgrade Utility on Windows servers to upgrade to the current version of PingFederate.

About this task

The Upgrade Utility copies all relevant sources of your current installation into the new target directory of your choice. It doesn’t change the current installation.

Upgrade results are contained in the <pf_install_target>\pingfederate\upgrade\log\upgrade.log file.

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

Steps

  1. Download the latest version of the PingFederate Server distribution .zip archive from the Ping Identity website.

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

  2. Extract the .zip to the new target directory of your choice, <pf_install_target>.

  3. Stop PingFederate.

  4. At the command prompt, change the directory to <pf_install_target>\pingfederate\upgrade\bin and enter the following command:

    upgrade  <pf_install_source>  <newLicense>] [-c] [--release-notes-reviewed]

    where: <pf_install_source>::

    The full or relative path of the base pingfederate directory where the existing PingFederate software is installed.

The pingfederate directory must have the name "pingfederate" for the Upgrade Utility to function correctly.
<newLicense>

The optional path and file name of the license to use for the upgraded PingFederate version.

If your current license is valid, the Upgrade Utility automatically copies it from the source installation to the target installation, and you don’t need to specify the <newLicense> parameter.

If your license isn’t 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’ve already reviewed the release notes. This parameter prevents prompts during the upgrade that ask if you’ve 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.

+ If you’re upgrading a clustered PingFederate environment, repeat from step 1 to upgrade PingFederate on each engine node.

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

  1. If PingFederate is running as a service, reinstall the service:

    1. Remove the existing PingFederate service.

      For more information, see Uninstalling PingFederate from a Windows server.

    2. Install the new PingFederate service.

      For more information, see Installing the PingFederate service on Windows manually.

    3. For a clustered PingFederate environment, reinstall the PingFederate service on all nodes.

    Start the new PingFederate installation.

If you’re upgrading a clustered PingFederate environment, start the new PingFederate instance on the console node.

If you’ve configured single sign-on using OpenID Connect (OIDC) 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.

  1. Verify the new installation’s version:

    1. Open the new installation’s administrative console.

    2. On the toolbar, click the Question Mark icon. On the Help menu, click About.

    3. Verify that the pop-up shows the new version.

  2. If you’re upgrading a clustered PingFederate environment:

    1. Start the new installation on each engine node, and then go to System → Server → Cluster Management and ensure all nodes are shown.

    2. On the Cluster Management page, click Replicate Configuration.

  1. Although 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_target>\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_target>\pingfederate\server\default\conf\language-packs that don’t fit the previous criteria are copied (not merged) into the upgraded PingFederate installation.

Next steps

After upgrading PingFederate, perform the Post-upgrade tasks.

Upgrading PingFederate on Windows using the installer

If you used the PingFederate installer for Windows to install the previous version of PingFederate, you can use it to upgrade to the current version of PingFederate.

About this task

Upgrade results are contained in the upgrade.log file. If the upgrade succeeds, upgrade.log is located in <pf_install_target>\pingfederate\upgrade\log. If the upgrade fails, upgrade.log is located in <pf_install_target>.

The default location for <pf_install_target> is C:\Program Files\Ping Identity. You can change the location during the upgrade process.

The PingFederate installer for Windows doesn’t support custom mode. If you want to override the newer default security settings or upgrade the OpenToken Adapter, use the PingFederate Upgrade Utility.

Steps

  1. Download the PingFederate installer for Windows from the Ping Identity website.

  2. Double-click the pingfederate-<version>.msi file to begin the upgrade.

  3. Follow the instructions in the PingFederate Setup Wizard to upgrade PingFederate.

    Screen capture of the Welcome page for the installer for Windows

    Errors are rare but might include problems, such as missing or malformed configuration files in the source installation. If the upgrade tool reports an error, review the error messages in the upgrade.log file.

You can rerun the tool as many times as needed to correct any problems.

When the tool completes the upgrade, it automatically starts the new PingFederate installation.

+ If you’re upgrading a clustered PingFederate environment, repeat from step 1 to upgrade PingFederate on each engine node.

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

  1. Verify the new installation’s version:

    1. Open the new installation’s administrative console.

    2. On the toolbar, click the Question Mark icon. On the Help menu, click About.

    3. Verify that the pop-up shows the new version.

  2. If you are upgrading a clustered PingFederate environment:

    1. Go to System → Server → Cluster Management and ensure all nodes are shown.

    2. On the Cluster Management page, click Replicate Configuration.

Next steps

After upgrading PingFederate, perform the Post-upgrade tasks.