Upgrading configuration data
PingFederate can automatically upgrade your configuration data when you load the data as a configuration archive file. This simplifies upgrading to a new version of PingFederate without using the upgrade utility. After your configuration data is updated to the new version, you can replicate the upgraded data to your clustered server nodes.
Configuration data is stored in the <pf-install>pingfederate/server/default/data directory. Learn more about creating a configuration data archive in Exporting an archive.
Automatic configuration data upgrade
The following actions trigger an automatic configuration data upgrade:
-
After starting a new install of PingFederate 12.2 or later, performing an archive import.
-
After starting a new install of PingFederate 12.2 or later, loading a configuration archive into the drop-in deployer.
-
PingFederate 12.2 or later starting up with an existing
<pf-install>/pingfederate/server/default/datafolder containing data from an older version.PingFederate won’t upgrade a configuration archive from version 11.0 or earlier.
In a clustered environment, configuration data upgrades are automatically replicated to your server nodes.
-
After a current configuration archive is successfully loaded using the drop-in deployer, PingFederate automatically replicates the configuration to the server nodes.
-
After a configuration archive from an older version is loaded using the drop-in deployer, and the data upgrade completes, PingFederate automatically replicates the upgraded configuration to the server nodes.
|
You can disable the automatic upgrade by setting the |
Configuration archive import
PingFederate can export and import a zipped archive of your configuration files.
You can export your configuration data manually. You can also have PingFederate automatically export archives on a schedule.
When you import a configuration archive from an older version, PingFederate automatically upgrades the data to be compatible with the upgraded version.
Learn more in Configuration archive.
Drop-in deployer
PingFederate’s drop-in deployer automatically replicates configuration archives to clustered servers.
When you drop a configuration archive into the <pf-install>/pingfederate/server/default/data/drop-in-deployer directory on each cluster node or provisioning-failover node, PingFederate automatically upgrades the configuration data to be compatible with the upgraded version.
Learn more in Configuration-archive deployment.
replicate.after.drop.in.deploy
The replicate.after.drop.in.deploy attribute enables PingFederate to automatically replicate configuration data archives from the drop-in deployer to clustered node servers. If PingFederate encounters any errors during the drop-in deployment or automatic configuration data upgrade, it won’t automatically replicate the data to avoid pushing potentially problematic configuration data to the engine nodes.
The replicate.after.drop.in.deploy attribute is located in the <pf-install>/pingfederate/server/default/conf/cluster-config-replication.conf file. replicate.after.drop.in.deploy is set to false by default.
The automatic replication process can also be affected by the ForceImport attribute in the org.sourceid.saml20.domain.mgmt.impl.DataDeployer.xml file. During startup, if PingFederate encounters any errors with data upgrade or drop-in deployer processes, enabling this attribute forces PingFederate to log the error and proceed with startup. This attribute is enabled by default.
If replicate.after.drop.in.deploy and ForceImport are both true, PingFederate continues with startup when it encounters errors with the data upgrade or drop-in deployer processes.
If replicate.after.drop.in.deploy is true and ForceImport is false, PingFederate halts startup when it encounters errors with the data upgrade or drop-in deployer processes.
Configuration data upgrade failure
If the configuration data upgrade fails, the archive import will also fail. If the archive import fails, check the server.log file for errors.
If the drop-in deployer data fails to load, PingFederate starts with the default new installation configuration instead of the configuration from the archive.
If the drop-in deployer fails to replicate the configuration data to server nodes, PingFederate logs the error.