For the upgrade process, you must download and extract a new version of the Directory Server .zip file on the server that will be updated. In addition, you must run the update utility with the --serverRoot or -R option value from the new root server pointing to the installation that will be upgraded.


Consider the following when planning for and upgrading replicating servers:

  • The upgrading process affects only the server being upgraded. The process does not alter the configuration of other servers.
  • The update tool verifies that the Java version installed meets the new server requirements. Before running the tool, install the Java version that is supported by the new server.
  • For precautionary measures, backup the user data userRoot before an upgrade. Restoring from a backup might be necessary if all other servers in the replication topology have been upgraded and a database or encoding change in the new server version prevents the database from being used with the older server version. The update and revert-update utilities issue a warning when this is the case.
  • Temporarily raise the replication purge delay for all servers in the topology to cover the expected downtime for maintenance. This results in a temporary increase in disk usage for the replicationChanges database stored in <server-root>/changelogDb.
  • Replication does not need to be disabled on a server before an upgrade.
  • Make sure upgraded servers are working as expected before upgrading the last server in the topology.
  • After all replicating servers are upgraded, enable new features.

For additional considerations, see the Planning your upgrade guide.

Considerations when upgrading to


If you plan to upgrade servers using a mixed-version environment where one version is earlier than 7.0 and some of the servers are still using the admin backend while others have been updated to the topology registry, do not attempt to make size changes to the topology. You cannot remove any existing servers (using dsreplication disable) or add new servers (using dsreplication enable) when in this transitional state of partially-updated servers. When a topology has been completely migrated to a 7.0 or later version with the topology registry, changes to the topology size are allowed, even in mixed-version environments (for example, mixed 7.3 and 8.3).

RFC 8996 has just been released, which officially deprecates the TLSv1 and TLSv.1.1 protocols and explicitly states that these MUST NOT be used. Per this specification, only TLSv1.2 and TLSv1.3 are considered acceptable for use. Therefore, for this release, TLSv1 and TLSv.1.1 are disabled by default. Disabling support for TLSv1 and TLSv1.1 does not prevent these protocols from being used, it only disables them by default. Support for these legacy protocols can be re-enabled in the configuration if necessary. Also, support for TLS cipher suites that use the SHA-1 message digest is being deprecated, as SHA-1 is no longer considered secure. We are also deprecating support for TLS cipher suites that use RSA key exchange because these do not provide forward secrecy.

Changes to entries made by the clients using the SCIMv2 API will now have the actual user ID, making the request stored in the access and audit logs. By default, the server will continue to use the "SCIM2 Servlet" user as the authorization identity for all SCIM2 requests, and the DN of thist user will be recorded in the access log and in the creatorsName and modifiersName attributes. If you want to change this behavior, change the value of the map-access-tokens-to-local-users property from disabled to either optional or required. This will cause the server to map the token to a local user, and if the mapping is successful, the mapped user's DN will be used as the authorization identity for the operations.