Copying customized files or settings

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

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

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

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.

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

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.

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.

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.

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.

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:

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.

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.