User-facing windows

If you have modified any Velocity templates for user-facing windows, to preserve the customized user experience, you must migrate your custom changes to the new installation manually for each server node. The templates are located in the <pf_install>/pingfederate/server/default/conf/template directory.

CAUTION:

Supporting CSS and image file names were changed as of PingFederate 7.0. For each modified HTML template copied, add .1 to the base name for each CSS file referenced in the header (for example <link rel="..." href="assets/css/window.1.css"/>).

Add .1 to any references in the copied templates to the installed image files contained in the assets/images directory (for example, <img src="assets/images/green_check.1.png"/>)

Email notifications

If you modified the email notification templates prior to version 9.2, manually migrate your custom changes to the new HTML-based templates for each server node.

The plain text templates (message-template-*.txt) are located in <pf_install>/pingfederate/server/default/conf in the source installation. The new HTML-based templates are located in <pf_install>/pingfederate/server/default/conf/template/mail-notifications with the same file naming convention but an .html file extension.

Jetty or JBoss configuration

If you have modified any Jetty or JBoss settings that need to be carried forward, you must make the corresponding changes manually in the new PingFederate deployment.

If you are upgrading from version 6.9 or later, you can copy over the relevant files from the Jetty configuration directory, <pf_install>/pingfederate/etc.

If you are upgrading from version 6.0 through 6.8, first identify any changes made to the JBoss configuration, then make corresponding changes for the newer Jetty configuration.

For example, if you modified the <pf_install>/pingfederate/server/default/deploy/jetty.sar/META-INF/jboss-service.xml file prior to version 6.9, identify the changes and make the same modifications at corresponding points in either the jetty-admin.xml or jetty-runtime.xml files located in the new Jetty configuration directory, <pf_install>/pingfederate/etc.

size-limits.conf

Prior to version 8.4.2, the InterReqStateMgmtMapImpl.expiry.mins setting in the <pf_install>/pingfederate/server/default/conf/size-limits.conf file defines the lifetime of the following data sets:

Inter-request state information
The state information between the redirects to complete a request.
Adapter session-state data
The state information (along with the associated attributes and their values, if any) maintained (or used) by the adapters.

PingFederate 8.4.2 splits the InterReqStateMgmtMapImpl.expiry.mins settings into two settings, one setting for each data type.

New settings Data type Default value in minutes
InterReqStateMgmtMapImpl.expiry.mins.state.map Inter-request state information 30
InterReqStateMgmtMapImpl.expiry.mins.attr.map Adapter session-state data 1440 (24 hours)

The new settings reduce the memory footprint of PingFederate by purging the inter-request state information after 30 minutes and retaining adapter session-state data during the day.

If you have previously modified the value of the InterReqStateMgmtMapImpl.expiry.mins setting, when migrating your change to the latest version, adjust the value of the new settings based on your requirements.

Cross-origin resource sharing (CORS) support for OAuth endpoints

If you have previously edited the <pf_install>/pingfederate/etc/webdefault.xml file to enable CORS support for OAuth endpoints, instead of updating the webdefault.xml file, define the allowed origins manually using the PingFederate administrative console after the upgrade. For more information, see Configuring authorization server settings.

Configuration files in the config-store directory

If you have added or replaced setting values in configuration files stored in the <pf_install>/pingfederate/server/default/data/config-store directory, the PingFederate upgrade tools copy these setting values to the new installation.

Note:

The upgrade tools do not copy comments from the existing installation to the new installation.

If you have removed a setting or a block of settings from a configuration file in the config-store directory, the upgrade tool preserves your changes by removing the setting or block of settings from the new installation and records the removals in its log file. To re-add a setting or block of settings to the new installation, compare the configuration file found in the new installation to the file found in the product distribution .zip file and make your changes.

Other configuration files

As of PingFederate 10.0, the upgrade process copies many files automatically. However, there are still some files that you must copy manually, which you can find in <pf_install>/pingfederate/server/default/conf.

The following files are copied automatically:

  • Properties files with the .conf extension
  • The log4j2.db.properties file
  • The jmx-remote-config.xml file
  • Non-default files located in the template directory

If you have modified the default templates, located in <pf_install>/pingfederate/server/default/conf/template, you must customize these templates in the new PingFederate installation.

If you have modified versions of tcp.xml, udp.xml, and log4j2.xml, they are copied over intact. The default files are saved in the target directory with a different extension. To take advantage of the improvements in the default versions of these files, merge your changes into the current default files and then rename them appropriately.

Note:

If you are upgrading from version 8.0 or earlier, PingFederate might not start until you have merged your changes into the current default files due to JGroups errors.

Other files, such as jmx.remote.access, are not copied to the new installation automatically. To preserve any custom settings, create a backup of the current configuration files and merge your changes to the current files.

If you have previously customized Java Virtual Machine (JVM) options in the run.bat or run.sh files, instead of updating these files, manually merge your JVM options to the <pf_install>/pingfederate/bin/jvm-memory.options file. For more information, see Fine-tuning JVM options and memoryoptions and upgrade.