PingDirectory and PingDirectoryProxy

The following content provides a brief description of the upgrade process and considerations that might affect your upgrade decisions.

Overview

For the upgrade process, you must download and extract a new version of the PingDirectory server .zip file on the server that will be updated. In addition, you must run the update command with the --serverRoot or -R option value from the new root server pointing to the installation that will be upgraded.

Considerations

Consider the following when planning for and upgrading replicating servers:

The upgrading process affects only the server being upgraded. The process does not alter the configuration of other servers.
The update command verifies that the Java version installed meets the new server requirements. Before running the command, install the Java version that is supported by the new server.
For precautionary measures, back up the user data userRoot before an upgrade. Restoring from a backup might be necessary if all other servers in the replication topology have been upgraded, and a database or encoding change in the new server version prevents the database from being used with the older server version. The update and revert-update commands issue a warning when this is the case.
Temporarily raise the replication purge delay for all servers in the topology to cover the expected downtime for maintenance. This results in a temporary increase in disk usage for the replicationChanges database stored in <server-root>/changelogDb.
Replication does not need to be disabled on a server before an upgrade.
Make sure upgraded servers are working as expected before upgrading the last server in the topology.
After all replicating servers are upgraded, enable new features.

Learn more in Planning your upgrade in the Best Practice Guides.

Upgrade considerations introduced in PingDirectory 10.1.0.0

Keep in mind the following upgrade considerations introduced in PingDirectory 10.1.0.0.

Schema backends now have calculated generation ID values, represented by the ds-sync-generation-id operational attribute, rather than the fixed legacy value of 16848715. This change prevents incompatible schema backends from replicating with each other.

This change also creates a known replication issue for the following scenario:

Given a topology of newly created 10.1.0.0 or later servers (that were not upgraded from an earlier version) with schema replication active, you add a pre-10.1.0.0 server to the topology. The schema then gets initialized from a 10.1.0.0 or later server to the pre-10.1.0.0 server.

In this scenario, the schema gets copied as intended, but the 10.1.0.0 or later servers and the pre-10.1.0.0 server won’t replicate schema changes after initialization, due to the non-matching schema generation IDs.

In general, you should not initialize from a newer server to an older server.

Upgrade considerations introduced in PingDirectory 9.x

Keep in mind the following upgrade considerations introduced in PingDirectory 9.x versions.

Permissive Modify no longer enabled by default in Directory REST API

In previous versions, Permissive Modify behavior was enabled by default for all API modify (PATCH) requests. In version 9.3, this behavior is controlled by an always-use-permissive-modify configuration parameter, which now has a default value of false. If you see a change in your application’s behavior as a result of this default configuration, you can re-enable Permissive Modify by changing the value of the configuration parameter to true with bin/dsconfig.

Enabling Permissive Modify behavior affects operations like removing an attribute that does not exist, or adding a duplicate value to a single-value attribute, by returning a "success" response without actually modifying the underlying data. Having the always-use-permissive-modify configuration parameter set to false by default will return "failure" responses for such permissive operations.

Enabling replication-purge-obsolete-replicas

The following requirement applies when upgrading from a version earlier than 9.2 to version 9.2 or higher:

You must set the replication-purge-obsolete-replicas global configuration property to true on each server in the topology before beginning the upgrade process. Failure to do so could result in a server entering lockdown mode over missing changes from an obsolete replica.

Learn more about Discovering obsolete replicas or Purging obsolete replicas.

Cleaning replication history

When cleaning replication history from a PingDirectory server, you must use the new remove-defunct-server argument --performLocalCleanup. If you have existing automation around disaster recovery, the previous method of running remove-defunct-server without bind credentials no longer performs this replication cleanup step. For PingDirectory versions 9.0.0.0 and later, update any existing automation to use the --performLocalCleanup flag.