PingDirectory

Upgrade overview and considerations

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

If you plan to upgrade servers using a mixed-version environment where one version is earlier than 7.0 and some of the servers are still using the admin backend while others have been updated to the topology registry, do not attempt to make size changes to the topology. You cannot remove any existing servers (using dsreplication disable) or add new servers (using dsreplication enable) when in this transitional state of partially-updated servers. When a topology has been completely migrated to a 7.0 or later version with the topology registry, changes to the topology size are allowed, even in mixed-version environments (for example, mixed 7.3 and 8.3).

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 utility 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 tool verifies that the Java version installed meets the new server requirements. Before running the tool, install the Java version that is supported by the new server.

  • For precautionary measures, backup 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 utilities 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.

For additional considerations, see the Planning your upgrade guide.