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 the Planning your upgrade guide.
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 tool must
be provided LDAP authentication options to the peer servers of the server being
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
- 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. 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-nameproperty 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.
After enabling or fixing the configuration of the LDAP connection handler(s) to support
the desired connection security mechanism on each server, run the following
dsframework command on the server being updated so that its admin
backend has the most up-to-date information:
$ bin/dsframework set-server-properties \ --serverID serverID \ --set ldapport:port \ --set ldapsport:port \ --set startTLSEnabled:true
update tool 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
updatetool 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 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. 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. Once set, the name cannot be changed. If needed, the following
command can be used to set the instance name of a server prior to the
$ 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 master. To synchronize the cluster-wide configuration data across all servers in the topology, run the
config- difftool on each pair of servers to determine the differences, and use
dsconfigto update each instance using the
config-diffoutput. 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 tool will list
all of the errors encountered for each server, and provide instructions on how to fix