When upgrading your server, there are multiple upgrade scenarios with different implications that you need to consider. Use the server’s update utility to upgrade the current server code version.
Click the following tabs to see instructions for the tasks you want to perform.
Upgrading servers in a topology
An update to the current server release includes the introduction of a topology registry, which stores information that was stored previously in the admin backend, such as server instances, instance and secret keys, server groups, and administrator user accounts.
Before you can update and migrate the admin backend, the following conditions must be satisfied:
- Run the update command and provide LDAP authentication options to the peer servers of the server being updated. The update command connects to the peer servers of the server being updated to obtain the necessary information to populate the topology registry.
- On every server in the topology, configure the encryption protocol requested, either plain, TLS, StartTLS, or SASL, for an LDAP connection.
- Ensure the LDAP credentials are present on every server in the topology.
- Ensure the users related to the LDAP credentials have permissions to read from
the admin backend and the config backend of every server in the topology. For
example, you can use a root DN user that has
inherit-default-privilegesset to true, such as the
cn=Directory Manageruser, that exists on every server.
- The instance name is set on every server and is unique across all servers in the
topology. The instance name is a server’s identifier in the topology. After all
servers in the topology have been updated, each server is uniquely identified by
its instance name. After the name is set, it cannot be changed. Tip:
If needed, use the following command to set the instance name of a server before the update.
$ bin/dsconfig set-global-configuration-prop \ --set instance-name:uniqueName
This information is only applicable when updating from a server version that uses the admin backend to a server version that uses the topology registry. This is only the case when updating from a server version earlier than a 7.x to a 7.x version and is not applicable to any updates to a server version of 8.x or later.
- When the first server is being updated, all other servers in the topology are online.
- When updating additional servers, all topology information was obtained from one of the servers that has already been updated.
- The users related to the provided LDAP credentials have read permissions to the config and admin backends of the peer servers.
- The instance name is set on every server and is unique across all servers in the topology.
To make clustered configuration changes in a mixed-version cluster:
- Update each server to the same version.
- Temporarily split up the cluster by changing the
cluster-nameproperty on the server instance configuration objects.Note:
Changes to clustered configurations are not allowed in mixed-version clusters. This applies to configuration in the
cn=Cluster,cn=configsubtree and only applies to servers with matching cluster names.
Make clustered configuration changes again to mirror these changes across the
When all of these conditions are met, the cluster-wide configuration is synchronized on all servers in the topology.Note:
Older versions have some topology configuration under the cn=cluster,cn=config JSON attribute and field constraints. These items do not support mirrored cluster-wide configuration data. In an update, avoid custom configuration changes on a server being overwritten with the configuration on the mirrored subtree primary.
To synchronize the cluster-wide configuration data across
all servers in the topology, run the config-diff command on
each pair of servers to determine the differences, and use
dsconfig to update each instance using the
$ bin/config-diff --sourceHost hostName \ --sourcePort port \ --sourceBindDN bindDN \ --sourceBindPassword password \ --targetHost hostName \ --targetPort port \ --targetBindDN bindDN \ --targetBindPassword password
Restoring a mixed topology to a clean state
Perform the following steps to restore a mixed-version 6.2 - 7.x topology with replication problems to a clean state with all servers at the same level and with replication functioning normally.
This information is only applicable when updating from a server version that uses the admin backend to a server version that uses the topology registry. This is only the case when updating from a server version earlier than 7.x to a 7.x version and is not applicable to any updates to server version 8.x or later.
If you are upgrading a PingDirectory server version earlier than 7.3 to 7.3 or later and at least one server was previously removed from the topology, you might receive an error message similar to one of the following:
[09/Dec/2019:18:37:56.927 -0700] instanceName="[INSTANCE_NAME]" \
threadID=438 category=REPLICATION severity=NOTICE msgID=118947975 msg="The \
replication total backlog count is 163364"
[09/Dec/2019:17:15:10.108 -0700] category=REPLICATION \
severity=SEVERE_ERROR msgID=14942295 msg="While clearing the database 997 \
o=mycompany, the following error happened: (JE 7.5.12) Attempted to remove \
non-existent database 997 o=mycompany DatabaseNotFoundException: (JE 7.5.12) \
Attempted to remove non-existent database 997 o=pingone (DbTree.java:922 \
DbTree.java:1183 DbTree.java:1235 Environment.java:1001 Environment.java:1221 \
Environment.java:1204 Environment.java:1009 ReplicationDbEnv.java:1186 \
DomainDbEnv.java:995 ReplicationDB.java:1002 DbHandler.java:1324 DbHandler.java:1064 \
DbHandler.java:1042 DbHandler.java:798 DbHandler.java:723 DirectoryThread.java:352 \
- To export a safe copy of the data, run bin/export-ldif on the primary server.
- Start the down-level primary server and stop the upgraded replica server.
Run bin/remove-defunct-server on the upgraded replica server
and do the following when prompted:
- Select the replica server itself.
- Supply the credentials for the primary server when prompted.
- Select [c] to continue.
- Enter the path to the local changelogDB when prompted.
- Leave the upgraded replica server stopped and stop the down-level primary server.
Run bin/dsreplication on the primary server and do the
- Select 2) Manage the topology (add and remove servers).
- Select 4) Cleanup Server.
- Select [c] to continue.
- Enter the path to the local changelogDB when prompted.
- Start the down-level primary server and the upgraded replica server.
- Run bin/status on both servers and verify that status of Replication: disabled in Data Sources.
- Upgrade the replica server to version 22.214.171.124 or later, which contains fixes for issues 00668265 and DS-40955.
- Upgrade the primary server to the same level as the replica server.
- To re-enable replication between the primary and replica server, run the bin/dsreplication tool.
- Re-initialize the replica server data from the primary server.
- Run bin/status on both servers to verify that replication is enabled in Data Sources and that both servers show the same number of entries.
Upgrading the server
Use the following steps to upgrade the PingDirectory and PingDirectoryProxy servers.
Download and extract the new version of the PingDirectory server in a location outside the existing
For these steps, assume the existing server installation is located in /prod/PingDirectory and the new server version is extracted in the /home/stage/PingDirectory location.
Run the update command provided with the new server package to
update the existing PingDirectory server.
The update tool might prompt for confirmation of the server configuration changes if it detects customization and display the following code.
$ /home/staging/PingDirectory/update --serverRoot /prod/PingDirectory
Reverting an update
After the server has been updated, you can revert to the last version or one level back using the revert-update command.
The revert-update command accesses a log of file actions taken by the updater to put the file system back to its prior state. If you have run multiple updates, you can run the revert-update command multiple times to revert to each prior update sequentially. You can only revert back one level. For example, if you have run the update twice since first installing the server, you can run the revert-update command to revert to its previous state, then run the revert-update command again to return to its original state. The following steps detail reverting from 7.x to a version earler than 7.0.
When starting up the server for the first time after a revert has been run, and the necessary extra steps have been completed, the server displays warnings about "offline configuration changes," but they are not critical and do not appear on subsequent start ups.
To revert to the most recent server version:
Run the revert-update command in the server root directory to
revert back to the most recent version of the server.
Reverting from the 7.0 version or later to a version earlier than 7.0 using the revert-update command might require extra steps. This is also the case when updating or reverting from a version earlier than 126.96.36.199 to a 188.8.131.52 version or later. These steps are listed when the update and revert-update command are run as well. Depending on your installation and configuration, you might need to perform one or more of the following tasks:
- When updating or reverting from 184.108.40.206 or later to a version earlier than 220.127.116.11,
indexes might need to be rebuilt. Older versions of the server use an incompatible
format for Local DB Composite Indexes. To update a server with composite indexes in
the previous format, delete these indexes and re-run the update. After the update is
complete, recreate the indexes and rebuild the indexes using the
rebuild-index command. The command for recreating an index is
Undoportion of the logs/config-audit.log file. To later revert to an older version, delete and recreate those composite indexes again after the revert process completes.
- When updating to 7.x for the first time, instance names must be set for each server
in the topology if they were not previously set. This is done with the following
$ bin/dsconfig --bindDN "cn=Directory Manager" \ --bindPassword secret \ --no-prompt set-global-configuration-prop \ --set instance-name:<name>
- Topology information such as server instances, instance and secret keys, server groups, and administrator users have moved to the topology portion of the configuration from the admin backend. As long as new servers are not added to the topology after this update, you can use the revert-update command to return to the previous version. However, if new servers are added, then the restored admin backend of this server does not contain information about the new servers, and the local server cannot communicate with any other servers in the topology. New servers should not be added to the topology if reverting this update is a possibility.
- If new servers were added to the topology after the update, the new servers must be temporarily removed from the topology until all servers have been reverted to the previous version.
- When a server is reverted to a version earlier than 7.x, any servers in the topology
using the topology portion of the configuration rather than the
admin backend must know that the reverted server was downgraded
to the admin backend. To do this, run the following
dsconfig command on one of the servers that has not been
$ bin/dsconfig set-server-instance-prop \ --instance-name <Reverted server instance name> \ --set server-version:<Version to which server is reverted>
- If the topology does not have a primary server when this command is run, the
revert-update will not succeed. In this case, you must make one
of the remaining updated servers in the topology the primary with the following
command. This enables the chosen instance to run the revert-update
$ bin/dsconfig set-global-configuration-prop \ --set force-as-master-for-mirrored-data:true
- The 7.x server version includes database changes that are not compatible with previous server versions, such as 6.x or earlier. To later revert to an older version, you must export the data to LDIF before performing the reversion. Then, re-import the data after the revert process completes. In addition, you must delete the changelogDb/ and db/changelog/ directories in the reverted server root after the revert process completes.