An update to the current PingDirectory 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 tool and provide LDAP authentication options to the peer servers of the server being updated. The update tool 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 prior to 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.
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-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 topology.
Run the dsframework command on the server being
$ bin/dsframework set-server-properties \ --serverID serverID \ --set ldapport:port \ --set ldapsport:port \ --set startTLSEnabled:trueImportant:
To run this command, you must have enabled or fixed the configuration of the LDAP Connection Handlers to support the desired connection security protocol on each server, so that its admin backend has the most up-to-date information.
Before allowing the update, the update tool verifies that the following conditions are satisfied on every server in the topology:
- 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.
If any of these conditions or those listed in the preceding Before you begin section are not satisfied, the update tool lists all of the errors encountered for each server and provides instructions on how to fix them.
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 master. If additional configuration steps are needed, see step 4.
To synchronize the cluster-wide configuration data across
all servers in the topology, run the config-diff tool 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