PingFederate Server

Cluster management

When multiple PingFederate servers are running as a cluster, the administrative console provides a Cluster Management window that you can use to ensure the all the nodes have the same configuration and license.

When you change the configuration of PingFederate on the administrative console, a notification banner appears at the top of the console, reminding you to go to the Cluster Management window and replicate the configuration of the administrative console node to all engine nodes in the cluster. The replication procedure generates new replication data that the engine nodes use to replicate from the administrative node’s configuration. Another notification banner appears when a cluster node is out-of-date or has failed.

Screenshot of the cluster management banners

Each node periodically reaches out to a random node in the cluster to see if newer replication data is available. If a node finds newer data, it attempts to retrieve and apply it. By default, the nodes poll another node every 60 seconds. You can change the replication poll interval by editing the value of the replication.poll.interval property in the <pf_install>/pingfederate/server/default/conf/cluster-config-replication.conf file.

The Cluster Management window also shows the version of each node.

Cluster settings

To view the cluster management settings, from System → Server → Cluster Management, click Settings. There are two checkboxes:

Replicate Connections when saved

When checked, changes to SP and IdP Connections are replicated to the cluster when a connection is saved. This setting is enabled by default. If unchecked, any changes must be replicated manually.

Replicate OAuth Clients when saved

When checked, changes to OAuth clients are replicated to the cluster when an OAuth client is saved. This setting is enabled by default. If unchecked, any changes must be replicated manually.

Connections and clients are only replicated if their dependencies have already been replicated. For example, when switching a connection’s signing certificate, if the new certificate already exists and has been pushed to the cluster, the connection will automatically be replicated. Otherwise, a full configuration replication is required.

You can see the replication status of connections and clients in the Replication Status column on the IdP Connections and SP Connections pages.

Cluster replication configuration file properties

The following table describes the properties in the <pf_install>/pingfederate/server/default/conf/cluster-config-replication.conf file.

Property description
Property Description

rpc.replication.status.timeout

The timeout period for replication status requests, in milliseconds.

The default value is 2000.

rpc.replication.data.timeout

The timeout period for requests to retrieve configuration data, in milliseconds.

The default value is 20000.

replication.data.retries

The number of retry attempts, if an error occurs while retrieving configuration data.

The default value is 1.

replication.poll.interval

The interval in seconds to check if more recent configuration data is available

The default value is 60.

require.replication.data.on.startup

Indicates if engines require replication data for startup and serving traffic. When set to true, engines that fail to retrieve replication data from the cluster during startup will exit, preventing them from serving traffic. NOTE: If an engine has previously retrieved replication data from a console or engine and is restarted, this flag will not be enforced. Instead, the engine will start up with the previously downloaded data.

The default value is false.

publish.replication.data.on.startup

Enables availability of previously published replication data (in the case of consoles) or retrieved data (in the case of engines) to the cluster during startup, eliminating the need for manual or automated replication triggers upon console restart.

This feature relies on the saved replication data being accessible after node restarts. If the data directory does not persist across restarts, a restarted node will have no replication data to publish. To benefit from this flag, the console’s data directory must persist across restarts at a minimum.

The default value is true for fresh installations and false for upgrades.