Upgrading PingDataSync

Use the PingDirectory server’s update command to upgrade the current code version.

Click the following tabs to see instructions for the tasks you want to perform.

Upgrade servers in a topology
Upgrade the server

Upgrading servers in a topology

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.

For additional considerations, see Planning your upgrade.

An update to the current release includes significant changes, and the introduction of a topology registry, which will store information previously stored in the admin backend (server instances, instance and secret keys, server groups, and administrator user accounts). For the admin backend to be migrated, the update command must be provided LDAP authentication options to the peer servers of the server being updated.

The LDAP connection security options requested (either plain, TLS, StartTLS, or SASL) must be configured on every server in the topology. The LDAP credentials must be present on every server in the topology, and must have permissions to read from the admin backend and the config backend of every server in the topology. For example, a root DN user with the inherit-default-privileges set to true (such as the cn=Directory Manager user) that exists on every server can be used.

Changes to clustered configurations are not allowed in mixed-version clusters. This applies to configuration in the cn=Cluster,cn=config subtree and only applies to servers with matching cluster names. Consider this when updating multiple servers in a cluster.
To make clustered configuration changes in a mixed-version cluster, choose one of the following options:
- Update each server to the same version.
- Temporarily split up the cluster by changing the cluster-name property on the server instance configuration objects.
After you have updated all the servers to the same version, you can again make clustered configuration changes and those changes will mirror across the topology.

The update command will verify that the following conditions are satisfied on every server in the topology before allowing the update:

When the first server is being updated, all other servers in the topology must be online. When updating additional servers, all topology information will be obtained from one of the servers that has already been updated. The update command will connect to the peer servers of the server being updated to obtain the necessary information to populate the topology registry. The provided LDAP credentials must have read permissions to the configuration and admin backends of the peer servers.
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 will be uniquely identified by its instance name. After it has been set, the name cannot be changed. If needed, you can 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
```
The cluster-wide configuration is synchronized on all servers in the topology. Older versions have some topology configuration under cn=cluster,cn=config (JSON attribute and field constraints). These items did not support mirrored cluster-wide configuration data. An update should 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 the dsconfig command to update each instance using the config-diff command’s output. For example:
```
$ bin/config-diff --sourceHost hostName \
  --sourcePort port \
  --sourceBindDN bindDN \
  --sourceBindPassword password \
  --targetHost hostName \
  --targetPort port \
  --targetBindDN bindDN \
  --targetBindPassword password
```

If any of these conditions are not satisfied, the update command will list all of the errors encountered for each server, and provide instructions on how to fix them.

Upgrading the server

About this task

This procedure assumes that an existing version of the server is stored at PingData-server-old. Make sure a complete, readable backup of the existing system is available before upgrading the server. Also, make sure there is a clear back-out plan and schedule.

Steps

Download the latest version of the server software and unzip the file.
Use the update command of the newly unzipped build to update the server. Make sure to specify the server instance that is being upgraded with the --serverRoot option. The server must be stopped for the update to be applied.

Reverting an update

If necessary, a server can be reverted to the previous version using the revert-update command. The command accesses a log of file actions taken by the update command to put the file system back to its prior state. If multiple updates have been run, you can run the revert-update command multiple times to revert to each prior update sequentially. For example, you can run the revert-update command to revert the server to its previous state, then run the command again to return it to its original state. The server is stopped during the revert-update process.

Reverting an update is not supported for upgrades to version 7.0, because of the topology backend changes.

Use the revert-update command in the server root directory to revert back to the most recent version of the server:

$ PingData-server-old/revert-update