PingFederate Server

Copying customized files or settings

After you upgrade PingFederate, you must copy files that were customized in the previous release to the current installation.

User-facing windows

If you modified any Velocity templates for user-facing windows, to preserve the customized user experience, some of your custom changes must be migrated manually to the new installation manually for each server node.

The templates are located in the <pf_install>/pingfederate/server/default/conf/template directory.

As of PingFederate 11.0, the Upgrade Utility migrates your modified Velocity HTML templates to the new installation. The default templates in the new installation that correspond to the modified templates are renamed with the following format: <template_name>-default-<PF-version>.<ext>.

Supporting CSS and image file names 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 before PingFederate 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.

As of PingFederate 11.0, the Upgrade Utility migrates your modified Velocity HTML templates to the new installation. The default templates in the new installation that correspond to the modified templates are renamed with the following format: <template_name>-default-<PF-version>.<ext>.

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 PingFederate 6.9 or later, merge any changes in <pf_install>/etc/jetty-runtime.xml and <pf_install>/etc/jetty-admin.xml files into the corresponding files of the new deployment.

If only the values of the minThreads, maxThreads, and acceptQueueSize parameters were modified in those Jetty files, you should set those values in the new deployment’s <pf_install>/bin/run.properties file instead of merging them into the Jetty files.

The advantage of setting those values in run.properties is that PingFederate can automatically merge run.propertiescustomizations into new deployments, saving you time and preventing errors in future upgrades. For more information, see Configuring PingFederate properties.

If you are upgrading from PingFederate 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 before 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.

The size-limits.conf file

Before PingFederate 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 Adapter session-state data and Inter-request state information data sets.

Adapter session-state data

The state information, along with the associated attributes and any of their values, maintained or used by the adapters.

Inter-request state information

The state information between the redirects to complete a request.

PingFederate 8.4.2 and later 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 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 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 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.

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

If you 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 archive 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

  • The csd_configuration.yaml file

  • Non-default files located in the template directory

If you 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 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 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 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.