Upgrading PingDataMetrics - PingDirectory

Upgrading PingDataMetrics - PingDirectory - 9.3

PingDirectory 9.3

bundle

pingdirectory-93

ft:publication_title

PingDirectory 9.3

Product_Version_ce

PingDirectory 9.3

Upgrading servers in a topology

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

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, the following command can be used 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

Make sure of the following:

An existing version of the server is stored at PingData-server-old.
A complete, readable backup of the existing system is available before upgrading the server.
There is a clear back-out plan and schedule.

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.
Specify the server instance that is being upgraded with the --serverRoot option.
Stop the server to apply the update.

Reverting an update

You can revert a server to the previous version using the revert-update command.

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

Note:

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

Go to the server root directory.
To revert back to the most recent version of the server, use the revert-update command.
```
$ PingData-server-old/revert-update
```

Reverting from version 7.x to a version earlier than 7.0

Reverting from version 7.0 or later to a pre-7.0 version can be done using the revert-update command with some extra steps.

This is also the case when updating or reverting from a pre-6.2.0.2 version to 6.2.0.2 or later. These steps are listed when the update and revert-update commands are run as well. You might need to perform one or more of the following tasks, depending on your installation and configuration:

Processes for reverting from version 7.x to versions earlier than 7.0

When updating or reverting from 6.2.0.2 or later to a pre-6.2.0.2 version, 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 use the rebuild-index command to rebuild the indexes. The command for recreating an index will be in the "Undo" portion of the logs/config-audit.log file. If you want to later revert to an older version, delete and recreate those composite indexes again after the revert has completed.
When updating to 7.x for the first time, instance names will need to be set for each server in the topology if they were not previously set. This is done with the following dsconfig command:
```
$ 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, the revert-update command can be used to return to the previous version. However, if new servers are added, then the restored admin backend of this server will not contain information about the new servers, and the local server will not be able to 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 pre-7.x version, any servers in the topology using the topology portion of the configuration (rather than the admin backend) will need to know that the reverted server was downgraded to the admin backend. This is done by running the following dsconfig command on one of the servers that has not been reverted:
```
$ 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, it will not succeed. In this case, one of the remaining updated servers in the topology must be made primary with the following command. This will enable the chosen instance to run the first command successfully.
```
$ 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 (6.x or older). If you want to later revert to an older version, the data must be exported to LDIF before performing the reversion. Re-import the data after the revert process has completed. In addition, the changelogDb/ and db/changelog/ directories in the reverted server root must be deleted after the revert has completed.

Note:

When you start a server after a revert has been run, and the necessary extra steps have been completed, the server will display warnings about "offline configuration changes," but they are not critical and will not appear on subsequent startups.

Reverting to the latest server version

You can revert your server to the previous, most recent version.

Go to the server root directory.
Run the revert-update command to revert to the most recent version.
```
$ <PingServer>-old/revert-update
```