If you have modified any Velocity templates for user-facing screens and you wish 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.
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.
<link rel="..." href="assets/css/screen.1.css"/>
.1 to any references in the copied templates to the
installed image files contained in the assets/images directory.
Similarly, if you have modified the email notification templates prior to version 8.2 and you wish to preserve the customized user experience, you must migrate your custom changes to the new HTML-based templates manually for each server node. The plain text templates (message-template-*.txt) can be found in the <pf_install>/pingfederate/server/default/conf directory in the source installation. The new HTML-based templates are located in the <pf_install>/pingfederate/server/default/conf/template/mail-notifications directory 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 a more recent), you can simply 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, a commonly modified file prior to version 6.9 might be the jboss-service.xml file located in the <pf_install>/pingfederate/server/default/deploy/jetty.sar/META-INF directory. When changes are identified, 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.
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 help 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 AS 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 such setting values to the new installation.
The upgrade tools do not copy comments from the existing installation to the new installation.
On rare occasions that you have removed a setting or a block of settings from a configuration file in the config-store directory, the upgrade tools preserves your changes by removing such setting or block of settings from the new installation and records the removals in its log file. If you wish to re-add such 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.
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 because of 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 Machines (JVM) options in the run.bat or run.sh files, instead of updating these files, manually merge your JVM options to the jvm-memory.options file located in the <pf_install>/pingfederate/bin directory. For more information, see Fine-tuning JVM options and memoryoptions and upgrade.