PingDirectory

Upgrading the PingDirectory and PingDirectoryProxy servers

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.

  • Upgrade servers in a topology

  • Upgrade the server

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 begin

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-privileges set to true, such as the cn=Directory Manager user, 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.

    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

Steps

  1. To make clustered configuration changes in a mixed-version cluster:

    Choose from:

    • Update each server to the same version.

    • Temporarily split up the cluster by changing the cluster-name property on the server instance configuration objects.

      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.

  2. Make clustered configuration changes again to mirror these changes across the topology.

    Result:

    When all of these conditions are met, the cluster-wide configuration is synchronized on all servers in the topology.

    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.

  3. 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 config-diff output.

    Example:

    $ bin/config-diff --sourceHost hostName \
  --sourcePort port \
  --sourceBindDN bindDN \
  --sourceBindPassword password \
  --targetHost hostName \
  --targetPort port \
  --targetBindDN bindDN \
  --targetBindPassword password

Upgrading the server

Use the following steps to upgrade the PingDirectory and PingDirectoryProxy servers.

Before you begin

This task shows the upgrade process for the PingDirectory server as an example.

Steps

  1. Download and extract the new version of the PingDirectory server in a location outside the existing server’s installation.

    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.

  2. 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 displays 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.

About this task

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.

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:

Steps

  • Run the revert-update command in the server root directory to revert back to the most recent version of the server.

    Example:

    $ PingDirectory-old/revert-update

Next steps

Depending on your installation and configuration, you might need to perform one or more of the following tasks:

  • 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.

  • 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 command successfully.

    $ bin/dsconfig set-global-configuration-prop \
    --set force-as-master-for-mirrored-data:true