PingFederate Server

Migrating cluster discovery settings

To simplify future upgrades, you should migrate the cluster discovery settings in the tcp.xml file to the jgroups.properties file.

About this task

When you upgrade, PingFederate can set the default configuration of any new features in the supported discovery protocols. Because of this, you should use the <pf_install>/pingfederate/bin/jgroups.properties file to enable and configure cluster discovery settings. For example, if NATIVE_S3_PING gets a new discovery protocol configuration, a PingFederate upgrade could automatically add the following line to jgroups.properties as a reasonable default, letting you take advantage of the new configuration:

pf.cluster.NATIVE_S3_PING.new_configuration=reasonable-default-configuration-value

For more information, see Dynamic cluster discovery.

The tcp.xml file has a ${DISCOVERY_TAG} that replaces all content related to cluster discovery protocol configuration. The jgroups.properties file is where the discovery protocol configuration exists and lets you do what you previously did in tcp.xml, such as:

  • Add custom configuration to discovery protocols that PingFederate officially supports, using the following syntax:

    pf.cluster.{discovery protocol}.{attribute name}={attribute value}

    For example, the following line adds a custom attribute called bucket_prefix with the value jgroups to the NATIVE_S3_PING protocol configuration:

    pf.cluster.NATIVE_S3_PING.bucket_prefix=jgroups

  • Add and configure a discovery protocol that PingFederate does not officially support, using the following syntax:

    pf.cluster.discovery.protocol={discovery protocol}
pf.cluster.discovery.class={fully qualified class name}

    For example, the following lines add a discovery protocol called CUSTOM and then add an attribute called attr1 with the value value1 to it:

    pf.cluster.discovery.protocol=CUSTOM
pf.cluster.discovery.class=org.jgroups.custom.discovery
pf.cluster.CUSTOM.attr1=value1

The examples in the following table compare the syntax of cluster discovery settings in the tcp.xml file and the jgroups.properties file.

Examples intcp.xml Examples injgroups.properties 
<TCPPING
  initial_hosts="${pf.cluster.tcp.discovery.initial.hosts}"
  return_entire_cache="true"
  port_range="0"/>
 
pf.cluster.TCPPING.initial_hosts=${pf.cluster.tcp.discovery.initial.hosts}
pf.cluster.TCPPING.return_entire_cache=true
pf.cluster.TCPPING.port_range=0
 
<org.jgroups.aws.s3.NATIVE_S3_PING
  region_name="us-east-1"
  bucket_name="[...]"
  endpoint="[...]"
  remove_all_data_on_view_change="true"
  write_data_on_find="true"/>
 
pf.cluster.NATIVE_S3_PING.region_name=us-east-1
pf.cluster.NATIVE_S3_PING.bucket_name=
pf.cluster.NATIVE_S3_PING.endpoint=
pf.cluster.NATIVE_S3_PING.remove_all_data_on_view_change=true
pf.cluster.NATIVE_S3_PING.write_data_on_find=true
 
<dns.DNS_PING
  dns_query="[service name].default.svc.cluster.local" />
 
pf.cluster.DNS_PING.dns_query=[service name].default.svc.cluster.local

To migrate the cluster discovery settings from the tcp.xml file to the jgroups.properties file:

Steps

  1. Open the <pf_install>/pingfederate/bin/jgroups.properties file and the <pf_install>/pingfederate/server/default/conf/tcp.xml file in a text editor.

  2. In the jgroups.properties file:

    1. Specify the cluster discovery protocol.

      For example:

      pf.cluster.discovery.protocol=NATIVE_S3_PING

    2. Specify the values for the cluster discovery protocol parameters that correspond with the values in the tcp.xml file.

      For example:

      pf.cluster.NATIVE_S3_PING.region_name=us-east-1
pf.cluster.NATIVE_S3_PING.bucket_name=
pf.cluster.NATIVE_S3_PING.endpoint=
pf.cluster.NATIVE_S3_PING.remove_all_data_on_view_change=true
pf.cluster.NATIVE_S3_PING.write_data_on_find=true

  3. In the tcp.xml file, insert the ${DISCOVERY_TAG} and remove the cluster discovery protocol settings.

    Do not remove other settings from the tcp.xml file.

  4. Repeat these steps for the other PingFederate nodes in the cluster.