PingDirectory and PingDirectoryProxy
The following content provides a brief description of the upgrade process and considerations that might affect your upgrade decisions.
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 |
Overview
For the upgrade process, you must download and extract a new version of the PingDirectory server .zip
file on the server that will be updated. In addition, you must run the update
command with the --serverRoot
or -R
option value from the new root server pointing to the installation that will be upgraded.
Considerations
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
command verifies that the Java version installed meets the new server requirements. Before running the command, install the Java version that is supported by the new server. -
For precautionary measures, back up 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. Theupdate
andrevert-update
commands 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 Planning your upgrade. |
Upgrade considerations introduced in PingDirectory 10.1.0.0
Keep in mind the following upgrade considerations introduced in PingDirectory 10.1.0.0.
Schema backends now have calculated generation ID values, represented by the ds-sync-generation-id
operational attribute, rather than the fixed legacy value of 16848715
. This change prevents incompatible schema backends from replicating with each other.
This change also creates a known replication issue for the following scenario: Given a topology of newly created 10.1.0.0 or later servers (that were not upgraded from an earlier version) with schema replication active, you add a pre-10.1.0.0 server to the topology. The schema then gets initialized from a 10.1.0.0 or later server to the pre-10.1.0.0 server. In this scenario, the schema gets copied as intended, but the 10.1.0.0 or later servers and the pre-10.1.0.0 server won’t replicate schema changes after initialization, due to the non-matching schema generation IDs. In general, you should not initialize from a newer server to an older server. |
Upgrade considerations introduced in PingDirectory 9.x
Keep in mind the following upgrade considerations introduced in PingDirectory 9.x versions.
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 |
Permissive Modify no longer enabled by default in Directory REST API
In previous versions, Permissive Modify behavior was enabled by default for all API modify (PATCH) requests. In version 9.3, this behavior is controlled by an |
Enabling Permissive Modify behavior affects operations like removing an attribute that does not exist, or adding a duplicate value to a single-value attribute, by returning a "success" response without actually modifying the underlying data. Having the always-use-permissive-modify
configuration parameter set to false
by default will return "failure" responses for such permissive operations.
Enabling replication-purge-obsolete-replicas
The following requirement applies when upgrading from a version earlier than 9.2 to version 9.2 or higher: You must set the Learn more about Discovering obsolete replicas or Purging obsolete replicas. |
Cleaning replication history
When cleaning replication history from a PingDirectory server, you must now use the new remove-defunct-server
argument --performLocalCleanup
. If you have existing automation around disaster recovery, the previous method of running remove-defunct-server
without bind credentials no longer performs this replication cleanup step. For PingDirectory versions 9.0.0.0 and later, update any existing automation to use the --performLocalCleanup
flag.
Upgrade considerations introduced in PingDirectory 8.x
Keep in mind the following upgrade considerations introduced in PingDirectory 8.x versions.
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 |
Upgrade considerations introduced in 8.3.0.0
-
RFC 8996 was released, officially deprecating the TLSv1 and TLSv.1.1 protocols and explicitly stating 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 this user will be recorded in the access log and in the
creatorsName
andmodifiersName
attributes. If you want to change this behavior, change the value of themap-access-tokens-to-local-users
property fromdisabled
to eitheroptional
orrequired
. 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.
Upgrade considerations introduced in 8.1.0.0
-
If you have upgraded a server that is in a cluster (that has a cluster name set in the server Instance configuration object) to version 8.1, you will not be able to make cluster configuration changes until all servers with the same cluster name have been upgraded to version 8.1. If needed, you can create temporary clusters based on server versions and modify the cluster name appropriately on each of the servers to minimize the impact while you are upgrading.
-
The
bypass-pw-policy privilege
was intended to provide a way for administrators to bypass certain password restrictions that would normally be imposed when managing passwords for other users. A user with this privilege could use it to bypass password validation for their own entry. Thebypass-pw-policy
privilege now only applies when changing another user’s password (that is, an administrative password reset), and only in the following scenarios:-
A user with this privilege will be permitted to set pre-encoded passwords.
-
A user with this privilege will be permitted to set passwords that would otherwise be rejected by one or more password validators.
-
A user with this privilege will be permitted to set passwords that match the current password or that are in the password history.
-
The privilege will only apply when changing the password for another user, and it will have no effect for a self-password change. Further, a user with this privilege will no longer be exempted from any other restrictions in their own password policy. Before upgrading, you should search for users that have the bypass-pw-policy
-
Missing changes will now be detected when the backend is reverted and there are insufficient changes in the changelog database. When in this particular missing-changes state the local replica will not accept changes from the local replication server. You can use the existing password validators and a custom password policy to enforce passwords for administrative users.
-
Fixed an issue in which the server could incorrectly evaluate a matched values request control containing an extensible match filter that specified both an attribute type and a matching rule. The server incorrectly used the attribute type’s equality matching rule instead of the matching rule specified in the filter.
-
Updated the "delay bind response" failure lockout action to provide an option to delay the response to bind requests initiated by non-LDAP clients (for example, when using HTTP basic authentication). This option is disabled by default because delaying the bind response for non-LDAP clients might require temporarily blocking the thread used to process the request, which could increase the risk of a denial-of-service attack. To help mitigate this risk, if you enable delayed bind responses for non LDAP clients, we recommend that you also increase the number of request handler threads for all enabled HTTP connection handlers.
-
Updated setup to create a second encryption settings definition if data encryption is enabled. It will continue to create a definition for 128-bit AES encryption for use as the preferred definition to preserve backward compatibility with existing servers in the topology, but it will now also generate a definition for 256-bit AES encryption. The 256-bit AES definition might become the preferred definition in a future release, but you can use it now by first ensuring that any existing instances are updated to contain the new definition (with the
encryption-settings export
andencryption-settings import
commands) and then making it the preferred definition (withencryption-settings set-preferred
) in all instances. -
Fixed an issue that could prevent the uninstaller from removing information about the instance from the topology registry.